gtpp2m0a | Programming Standards |
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.
The following secondary action codes are reserved:
Within the IBM reserved action codes, the following applies:
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.
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.
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').
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:
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.
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.