Statement syntax

The CHQI input syntax consists of the following elements:

Comments: Any record beginning with an asterisk in column 1 is a comment. The text in columns 2–80 is not parsed. You can code a comment line anywhere in the file.
Verbs: Each statement begins with a verb, and each type of statement requires a different set of parameters following the verb. There are no abbreviations for the verbs; you must code each 1 in full. CHQI recognizes 4 verb statements: LOAD, DESCR, ADD, and REMOVE.
Parameters: The DESCR verb takes a positional parameter (the text that follows it); the other verbs all take keyword parameters. Keyword parameters consist of the keyword, followed immediately by either a single dash or by a single equal sign, followed by the value. There can be 1 or more spaces between the dash or equal sign and the value, as long as the value is in the same record as the keyword. There must not be any spaces between the keyword and the dash or equal sign.

The input file is free format in that you do not have to code verbs and parameters on a particular line or in a particular column. Blank lines can be inserted at any point to improve readability. Exceptions to this free format include the following:

Comments must begin in column 1.
Each parameter must be completed in the same record that it begins; that is, a keyword and its associated value must be on the same line.
The DESCR verb takes 1 parameter that includes all of the text from the DESCR verb to the end of the record.
The input file must be in uppercase, except for:
- Text in comments
- Text in DESCR parameters
- TP parameter values; these must match the transaction program names defined in your network.

CHQI's parser scans the input file, strips out comments, and parses the remaining text into tokens. A token is any string of characters that is delimited by a space, null character, comma^¹, dash, equal sign, or logical end of record and that does not contain a space, null character, dash, equal sign or logical end of record^².

Tokens are classified as verbs, parameter keywords, and parameter values. Each verb begins a new statement, and each statement consists of the verb that initiates it and any following parameters up to the next verb or the end of file. The statements are checked for errors. Any statement containing no error messages or only attention messages is written to the side information data set in the proper format to be read by the z/TPF side information data loader. Statements containing 1 or more errors are not written to the side information data set.

The following shows the format of the statements and describes the verbs and parameters.

LOAD SS-subsystem

LOAD: Must be the first statement in the file, if used. If the LOAD statement occurs following any other statement, the LOAD statement is flagged with an error. The LOAD statement requires the SS parameter; if SS is omitted, the LOAD statement is flagged with an error.
SS-subsystem: Specifies the subsystem on which the generated side information data must be loaded. SS can be abbreviated to S.
The SS parameter value is any string from 1 to 4 characters long. The subsystem name is copied to the header of the first record in the side information data set.

DESCR text

DESCR: Can be coded anywhere except before a LOAD statement.
text: Represents a positional parameter that consists of the text between the DESCR verb and the next logical end of record, stripped of any leading or trailing blanks. There are no restrictions on the characters or strings that you can use, assuming the characters you use can be handled by your console.

ADD NAME-sdn TP-tpn LU-lun MODE-mode

ADD

Can be coded anywhere except before a LOAD statement. Each ADD statement takes 4 keyword parameters: NAME, TP, LU, and MODE. You can code these parameters in any order. If the NAME parameter is omitted, the statement is flagged with an error. If the TP, LU, or MODE parameter is omitted, the statement is flagged as requiring attention and the corresponding field in the side information entry is set to a null value.

Note: Transaction programs referring to an entry containing a null field must set valid values for the mode_name, mode_name_length, partner_LU_name, partner_LU_name_length, TP_name, and TP_name_length conversation characteristics before successfully allocating a conversation. See the cmsmn, cmspln, and cmstpn functions in the z/TPF C/C++ Language Support User's Guide for additional information.

If any of these parameters is repeated in a single ADD statement, it is flagged as an error. (Successive TP parameters, which are concatenated, are treated as a single instance of the TP parameter.)

NAME-sdn

Specifies the symbolic destination name of the new side information table entry. NAME can be abbreviated to NAM, NA, or N.

The NAME parameter value is any string from 1- to 8-characters long, consisting of any characters except token delimiters (dash, equal sign, comma, or blank) and lowercase letters. The symbolic name written to the side information data set is an 8-byte field consisting of the NAME parameter value padded to the right with space characters.

TP-tpn

Specifies the remote transaction program name associated with the symbolic destination name. TP can be abbreviated to T.

SNA allows transaction program names to include unprintable characters. To allow entry of such names, the TP parameter value can include substrings that are translated to unprintable characters in the output side information entry. The generated transaction program name is a variable-length field from 1 to 64 bytes long with no padding.

The dollar sign ($, X'5B') is used to delimit substrings of TP parameter values that are to be interpreted as hexadecimal values, according to the following rules:

Pairs of hexadecimal digits entered between 2 single dollar signs ($) are converted to the corresponding binary values; for example, T-$07F0$ sets the transaction program name to X'07F0'.
Hexadecimal substrings can be freely intermixed with literal substrings in the same TP specification, as in T-A$01$BCD$020304$E$05$, which sets the transaction program name to X'C101C2C3C4020304C505'.
If a dollar sign is actually desired in the transaction program name, 2 consecutive dollar signs ($$) must be used for each dollar sign needed. For example, T-X$$Y$$Z sets the transaction program name to "X$Y$Z", and T-$$$$$$32$F1$$F0$$$ sets the transaction program name to "$$$3210$".
The transaction program name cannot include blank characters (X'40'); therefore, a parameter of T-123$40$ABC is flagged as an error.
The length of the converted TP parameter value must be between 1 and 64 bytes.

To accommodate the possibility of a TP parameter value being too long to fit into 1 80-byte record, the values of adjacent TP parameters are concatenated. Each of the parameter values must conform to the rules stated previously, and the total length of all the concatenated converted strings must be less than or equal to 64. No other parameters can be coded between 2 concatenated TP parameters.

Note: N1 of the other keyword parameters are concatenated in this way.

The following example shows adjacent TP parameters that are concatenated to produce 1 transaction program name value for the generated entry:

   **************************************************
   * ADD STATEMENT WITH CONCATENATED TP PARAMETERS. *
   * THE GENERATED TRANSACTION PROGRAM NAME IS:     *
   *     HEX    : C2C5C7C9 D5010203 5BC5D5C4        *
   *     EBCDIC : B E G I  N . . .  $ E N D         *
   **************************************************
   ADD    N-CONCAT
          T-BEGIN
          T-$010203$
          T-$$
          T-END
          …

LU-lun

Specifies the partner LU name associated with a symbolic destination name. LU can be abbreviated to L.

The LU parameter value is a string from 1 to 17 characters long, consisting of an LU name and an optional network ID. If the network ID is included, it must precede the LU name and be separated from it with a period. If you only include the LU name, a period is not required.^³ Both the network ID and the LU name must be from 1 to 8 characters long, must contain only capital letters (A–Z) and numeric digits (0–9), and must begin with a capital letter. Any LU parameter that does not satisfy these requirements is flagged as an error. The following are examples of valid LU parameter values:

    NETID.LUNAME
    LUNMONLY
    N112358D.L1234567
    N.L
    LU62MAPD

The partner LU name field written to the side information data set is a variable-length field from 1 to 17 bytes long. The LU parameter value is copied to it without conversion or padding.

MODE-mode

Specifies the mode associated with a symbolic destination name. MODE can be abbreviated to MOD, MO, or M.

The MODE parameter value is a string from 1 to 8 characters long. It must contain only capital letters (A–Z) and numeric digits (0–9), and must begin with a capital letter. Any MODE parameter value that does not satisfy these requirements is flagged as an error. The mode field written to the side information data set is a variable-length field from 1 to 8 bytes long. The MODE parameter value is copied to it without conversion or padding.

REMOVE NAME-sdn

REMOVE: Can be coded anywhere except before a LOAD statement. Each REMOVE statement requires the NAME parameter. If the NAME parameter is omitted or repeated in the REMOVE statement, the statement is flagged with an error. The TP, LU, and MODE parameters are not required for this statement. Each occurrence of 1 of these parameters is flagged as requiring attention, and the parameter value is ignored.
NAME-sdn: Specifies the symbolic destination name of the side information table entry to be removed. Refer to the ADD statement parameter description for additional information about this parameter.

¹ Commas have no meaning other than to separate tokens and are exactly equivalent to blank characters.

² The parameter for the DESCR verb is an exception to this. DESCR's parameter begins with the first nonblank character following the verb and continues to the last nonblank character before the next logical end of record. If there is no nonblank character between the DESCR verb and the next end of record, the parameter is a null string.

³ For consistency with z/TPF commands, LU parameters specified as .luname; that is, no network ID but a leading period before the LU name are accepted. The leading period is not included in the side information data set or in the online side information table.