# Creating a text parameter file

To declare application-specific parameters, use any ASCII text editor to create a text parameter file with a .pf file extension. Ensure that your text editor or word processor does not embed formatting information into the text parameter file.

This topic presents:

- Text parameter file syntax

- Sample .pf file

## Text parameter file syntax

Specify the following information in a .pf file:

Keyword | Description
--- | ---
SvcName | Name of the service to contain the application parameters. Always set to PRM for application-specific parameters.
SvcID | Service ID of the service to contain the application parameters. Always set to 0xE for application-specific parameters.
Category | Named list that can contain substructure blocks, field names, or both. From a hierarchical perspective, a category provides the first level of name scoping under the service name. For example, RECORD is a category under the ADI Service, and the hierarchical name is ADI.RECORD. Terminate a category block with the keyword End. For example: Category category name field descriptor or substructure End
SubStructure | Named list that can contain field names and other substructure blocks. From a hierarchical perspective, a substructure provides a second level of name scoping (under a category). For example, callctl is a substructure under the START category of the ADI service and its hierarchical name is ADI.START.callctl. Substructure blocks are optional. Terminate a substructure block with the keyword End. For example: SubStructure substructure name field descriptor End
field descriptor | The actual specification of a parameter. A field descriptor can be declared only within a Category or SubStructure block. A field descriptor specification begins with the name of the field itself and has the following form: name, type, unit, [size,] default value For example: qualamp, INT32, dBm, -28
Parameter | Valid values
name | A field name must be unique within its scope. (There can be only one busycount field within the CALLPROG category. However, there could also be a busycount field in the COLLECT category.)
type | Supported data types are: WORD (16-bit unsigned integer) DWORD (32-bit unsigned integer) INT16 (16-bit signed integer) INT32 (32-bit signed integer) BYTE_ARRAY STRING When the field data type is a string or byte-array, declare a maximum string size (in bytes) that is sufficient to store the default string. Refer to the sample .pf file.
unit | Supported units are: INTEGER COUNT MASK HZ MS DB DBM IDU (internal data unit) PERCENT STRING The STRING units specification must be used when the field data type is a string.
size | When declaring a STRING, you must also declare a maximum string size (in bytes) sufficient to store the largest expected string and the null terminator.
default | Value with which to initialize the parameter. String values must be surrounded by double quotes. Integer values can be entered in either hexadecimal or decimal format.

Use the following syntax for a text parameter file:

Item | Description
--- | ---
Comments | A number sign (#) is a comment character and can be used anywhere within a text parameter file. All characters following the # are ignored on the current line. Functionality is similar to # in UNIX shell scripts or the rem command in DOS batch files. A blank line in the text parameter file is also ignored.
Special characters | Use a backslash (\) to escape reserved characters. For example, use \# to enter a literal # character. Use \\ to enter a literal \ character.
Case | The PRM service and utilities are not case sensitive. For example, keywords and service names can be in uppercase, lowercase, or any combination.
Naming rules | Categories, subcategories, and fields are named entities. In order to name them, the following rules apply: The legal alphabet includes all alphanumeric characters (a-z, 0-9) and underscore (_). The first character of a name cannot be an underscore or a numeric character. White space is not allowed in a name. Name length is not restricted (however, typical names do not exceed 20 characters in length).
Delimiters | Separate keywords and declarations with a space or a comma. Separate declarations containing multiple pieces of information with a space or commas.

## Sample .pf file

The following example declares a subset of the ADI service parameters as separate, autonomous application parameters.

The parameter list is:

- PRM.TONEDETECT.qualampl

- PRM.TONEDETECT.qualtime

- PRM.START.CALLCTL.blockmode

- PRM.START.CALLCTL.eventmask

- PRM.START.DIAL.interpulse

- PRM.START.DIAL.method

- PRM.START.t_str1

- PRM.START.testbytearray

Sample file:

###########################################################################
# Start of text parameter file
###########################################################################
###########################################################################
# PRM Service Name and ID
###########################################################################
SvcName PRM # do not modify this line for PRM Service
SvcID 0xE # do not modify this line for PRM Service
###########################################################################
# Category TONEDETECT
###########################################################################
Category TONEDETECT
qualamp1, INT32, dBm, -28 # min. detectable signal level
qualtime, DWORD, ms, 500 # min. duration of detected tone
End
###########################################################################
# Category START
###########################################################################
Category START
Substructure callcontrol
blockmode, DWORD, Integer, 0 # blocking method
eventmask, DWORD, Mask, 0x00000000 # event reporting
End
Substructure dial
interpulse, DWORD, Ms, 700 # interdigit pulse time
method, DWORD, Mask, 0X00000000 # signaling type
End
t_str1, STRING, STRING, 50, "sample string" # Just an example
# of a string
testbytearray, BYTE_ARRAY, IDU, 5, 0x1, 0x2, 0x3, 0x4, 0x5
End
###########################################################################
# End of text parameter file
###########################################################################