Declaring parameters

The following files contain the service parameters:

File	Description
xxxparm.pf	ASCII definition of each parameter and hierarchical structure.
xxxparm.c	Parameter source file automatically generated from xxxparm.pf during the make process.
xxxparm.h	Parameter header file automatically generated from xxxparm.pf during the make process.

This topic presents:

Creating the parameter definition file
Generating the parameter files

Creating the parameter definition file

The parameter definition file (.pf file) specifies the service name, service ID, the parameter category, and the parameter name. The following table provides an overview of the .pf file. Refer to the Natural Access Developer's Reference Manual for more details on constructing and using a .pf file.

Field	Description
SvcName	Specifies the service name.
SvcID	Specifies the service ID.
Category	Specifies the name of the category being declared. Terminate a category block with the keyword End. Category category_name field_descriptor or substructure . . . End
SubStructure	Specifies the name of the substructure being declared. Terminate a substructure block with the keyword End. SubStructure substructure_name field_descriptor . . . End
FieldDescriptor	Declare a field descriptor within a Category or SubStructure block. A FieldDescriptor specification does not begin with a keyword. It begins with the name of the field itself, as follows: name, type, unit, default_value name: A field name must be unique within its scope (for example, there can only be one busycount field within the CALLPROG category. However, there could also be a busycount field in the COLLECT category. A field name is not case sensitive (for example, CALLPROG.busycount and CALLPROG.busyCount are duplicates). type: A field descriptor must contain a data type. The supported data types are: WORD, DWORD, INT16, INT32, STRING, BYTE_ARRAY unit: A field descriptor must also contain a units specification. Supported units are: INTEGER, COUNT, MASK, HZ, MS, DB, DBM, IDU, PERCENT The STRING units specification must be used when the field data type is a string. When declaring a STRING, you must also declare a maximum string size (in bytes). The declared maximum size must be sufficient to store the default string. default_value: A field descriptor must contain a default value. String values must be surrounded by double quotes. Integer values may either be entered in hexadecimal or decimal format. For example: NumTicks, DWORD, COUNT, 2

tik service

<<<< excerpt from tikparm.pf >>>>

#-------------------------------------------------------------
# NAME: tikparm.pf
# This file defines (ASCII format) the TIK Service parameters
# that are accessible through the Natural Access API parameter functions.
# This file is used by the pf_tosrc conversion program to
$ generate the following 'C' files: tikparm.h and tikparm.c
#-------------------------------------------------------------
SvcName TIK # TIK Service Name
SvcId    0x40 # TIK Service ID

# Only one category (two fields) is required by the tik service;
# The TIK parameters (usable through Natural Access) are:
# tik.start.NumTicks
# tik.start.Frequency

Category              Start
    NumTicks, DWORD, COUNT, 2 # number of tick strings rcvd
    Frequency, DWORD, COUNT, 2 # frequency of tick strings rcvd
End

Generating the parameter files

Use the utility pf2src to automatically generate the parameter files xxxparm.c and xxxparm.h from the parameter file (.pf).

To generate the source file for the .pf file, enter:

pf2src pf_file

pf_file is the .pf input file.

The generated header file xxxparm.h defines the service ID assigned to the service and the API level parameter data structure on a per category basis. Each parameter structure uses the naming convention _PARMS as described in Parameter structures.

tik service

<<<< excerpt from tikparm.h >>>>

/***************************************************
* Auto Generated Source Module.
* Manual edits will be lost when file is regenerated!!
* UDP Compiler ( Version 1.1 )
****************************************************/
#ifndef TIKPARMPARM_DEFINED
#define TIKPARMPARM_DEFINED

#include "ctadef.h"

#ifdef __cplusplus
extern "C"
{
#endif

#define TIK_SVCID 0x40

#define TIK_START_PARMID 0x400001

typedef struct
{
    DWORD size;
    DWORD NumTicks;
    DWORD Frequency;
} TIK_START_PARMS;

extern const CTAPARM_DESC * const _tikParmDescTable[];

#ifdef __cplusplus
}
#endif

#endif

In the generated xxxparm.c file, the parameter description tables are declared and a pointer to the tables is created. You must include the pointer to the parameter descriptor table in the call to dispRegisterService during service initialization (see xxxDefineService).

tik service

<<<< excerpt from tikparm.c >>>>

/****************************************************
* Auto Generated Source Module.
* Manual edits will be lost when file is regenerated!!
* UDP Compiler ( Version 1.1 )
*****************************************************/
#include <nmstypes.h>
#include <ctadisp.h>
#include <tikparm.h>
TIK_START_PARMS _tikStartDefaults =
{
    12,
    2,
    2,
};
#define _F_(f,s,u) CTAFIELDDESC(TIK_START_PARMS,f,s,u)
const CTAPARM_FIELD _tikStartStructDef[] =
{
    "START", 0, 12 , 0, 0,
    _F_( NumTicks, DWORD, COUNT ),
    _F_( Frequency, DWORD, MS ),
};
#undef _F_
CTAPARM_DESC _tikStartParmDescr =
{
    TIK_START_PARMID,
    &_tikStartDefaults,
    _tikStartStructDef,
    CTAPARM_FIELDCNT(_tikStartStructDef)
};
const CTAPARM_DESC * const _tikParmDescTable[] =
{
&_tikStartParmDescr,
NULL
};