gtpp2m0aProgramming Standards

Commands

Commands (previously known as functional messages), which are sent from the operator to the TPF system, have Z as the primary action code (that is, the first character) and have a 1- to 4-character secondary action code immediately following the Z.

Reserved Secondary Action Codes

The following secondary action codes are reserved:

Secondary Action Code Format Examples

The secondary action code either ends the message or is followed by a blank.

Examples:
 
ZDTIM             The secondary action code DTIM ends the
                  message.
 
ZDCOR 000100      DCOR does not end the message, so it is
                  followed by a blank.
 
ZZDW/0125////     This message format is non-standard.

Character Set

For interfaces that receive commands on data level 0 (D0), the character set is restricted to alphanumeric characters A-Z, 0-9, and special characters hyphen (-), period (.), asterisk (*), dollar sign ($), and slash (/).

Example:
 
ZRTCU CTON #KEYPT     This message is nonstandard because it
                      contains a pound sign, #, which is not
                      available on all terminals.
Note:
Message help functions can use nonstandard characters only if there is also support for an alternative standard form of the message.
Example:
 
ZASER ?              The question mark is a non-standard character;
ZASER HELP           however, the alternative HELP parameter will
                     provide the same function.

There is also another interface provided where a copy of the command, as it was entered, is pointed to by field CE2CRSMSG of the entry control block (ECB). This copy of the command message can contain uppercase characters, lowercase characters, other special characters, and is ended by the null character (X'00').

Field Delimiters

Fields in the message should be delimited by blanks. Occasionally, you can use a special character, (hyphen, period, asterisk, dollar sign and virgule) to delimit subfields of a field. All new commands should be free format, that is, all unnecessary blanks in the command should be ignored.

Examples:

 ZTINT 280 123456 D1600 
Each field is delimited by a blank.

 ZDREC 05C.000006 080 006 
The record ID field (05C.000006) uses the period (.) to separate the record type from the ordinal number.

Parameters

Commands can contain positional or keyword parameters, or combinations of the two. Positional parameters must be entered in the sequence shown in TPF Operations, separated by one or more blanks. Keyword parameters can be entered in any position. The absence of a parameter implies a default specification. The default should be indicated in the command documentation in the individual command specifications.

Commands should support variable length keywords and parameters. The shortest unique character string should be allowed for keywords (that is, the keyword parameters may be truncated to the minimum unique abbreviation). This can be identified in the individual command documentation by uppercase letters. No extraneous data should be entered after the keywords or parameters. If any extraneous data is entered with a message, the message will be flagged as not valid by the message processor.

Examples:
 
ZAUTH D(isplay) LIT-030205   The minimum character representation
                             for display is D.  The second
                             parameter is a keyword.
 
ZVFAC DIS(play) STA(tus)     The minimum character representation
                             for display is DIS and for status is STA.
 
ZMPIF DEF(ine) D(evice) N(ame)-$3088G00   The minimum character representation
                                          for define is DEF, for device is D,
                                          and for name is N.

Message Parsing Techniques

Use the Input Message Tokenization support (either through the BPKDC macro or the IPRSE C language utility) to edit command parameters. Using these tools saves you the tedium of editing out multiple blanks, checking for an end-of-message, and so on. When coding new commands, look into the function provided by these macros in TPF General Macros and the TPF C/C++ Language Support User's Guide.