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

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:

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
###########################################################################