gtpg2m0mGeneral Macros

BPKDC-TPF Input Message Tokenization Support

This general macro is a standardized TPF function for tokenizing input commands. It allows the command support routine to define to the tokenizer the expected format and values of an input message in a standardized way. This allows all input messages to be processed in a standard way and simplifies the operator interface and user factors.

A standard input command has 'Z' as the first character followed immediately by a blank or a 1- to 4-character secondary action code. The secondary action code either ends the message or is followed by a blank. For more information about the standard format of an input command see TPF Programming Standards.

The BPKDC macro is used in conjunction with the BPPSC macro to define the input message format. (See BPPSC-Static Positional List Build for additional information.)

To define the input message format, the message processor program issues two macros that build the tables required by the tokenizer program. The definition form of BPKDC is used to define the actual message input format. The macro BPPSC is used to define allowable values for a specific positional parameter.

When the input message processor is given control, it invokes the tokenizer program by issuing the execute form of the BPKDC macro. The tokenizer builds an output parameter list that contains pointers to each of the tokens found in the input message. The sequence of output pointers is determined by the sequence of definitions in the input BPKDC. Also, if requested, the tokenizer performs some simple conversion of input parameters to usable binary output values.

When an error is encountered, the action taken by the tokenizer will depend upon the options specified on the BPKDC macro. One of the following actions will occur:

Format




label
A symbolic name can be assigned to the macro statement.

EXECUTE=YES
This parameter is used to define the form of the BPKDC macro being specified. If EXECUTE=YES, then the macro expands into a invocation of the BPKDC tokenizer program. If this is not an execute form, then the execute keyword should not be specified.

BPKD=label|Rx
The label of the definition BPKDC to be used to tokenize the input message on level 0. It may be specified as either a label or a register parameter.

ERROR=label
An optional parameter to indicate where to branch to if an error occurs in parsing the input. If it is not entered, then the tokenizer program will exit the ECB with an appropriate error message to the inputting terminal.

EMSG=Y|N
An optional parameter, which can be coded only with the ERROR parameter, to indicate whether an error will cause an error message to be issued to the inputting terminal before returning to the calling segment. The default is EMSG=N.

HELP=label
An optional parameter to indicate where to branch if the word 'HELP' or the character '?' appears as the first parameter.

type
A set of letters which define the parameter type and conversion to be performed. The following type codes are valid:

The following rules about usage of the type codes apply:

Either P or K must be specified.

P and K are mutually exclusive.

L is valid only when H is specified.

X, H, D, S, and C are mutually exclusive.

Note:
The parameter definition fields are determine by the type code assigned to the parameter. The following are the legal field definitions by type codes:

P - (type,name,,mxplgh)

PS - (type,name,pslabel)

K - (type,keyword,mklgh,mxplgh)

KS - (type,keyword,mklgh)

name
This is the name of the parameter as represented in the operator's guide. This name is used as a parameter for any error messages issued for this parameter. It must consist of 14 or fewer alphanumeric characters.

keyword
This is the keyword name as represented in the operator's guide. The value specified is the value that will be accepted as the keyword by the tokenizer. It must consist of 14 or fewer alphanumeric characters. This name is also used as a parameter for any error messages issued for this parameter.

mklgh
This is the minimum length acceptable for the name of a keyword parameter. This value must be less than the length of the keyword name.

pslabel
This is the name of a BPPSC macro which defines the accepted terms for a PS (self-defining positional) type of parameter.

mxplgh
This is the maximum input length for a legal parameter value.

MNOTE
This specifies whether BPKDC is to generate MNOTE messages describing the output DSECT label to be used to access each specified input parameter. The default is N.

Y
Generate MNOTE messages.

N
Do not generate MNOTE messages.

Entry Requirements

The tokenizer program expects data level 0 to contain the input command block in a MI0MI format. It also expects data level 1 and the extended switch EBXSW0 to be available for use.

Return Conditions

Programming Considerations

Examples

The BPKDC 'MCPYBPKD' is used to start the input message processing. The first parameter expected is a self-defining positional, and the legal values are defined by the TYPEBPK2 BPPSC macro. If either 'ABORT' or 'ALL' is entered then a switch to another BPKDC takes place. 'ABORT' causes a switch to the BPKDC with label 'BPKD2' and 'ALL' causes a switch to the BPKDC 'BPKD3'. If 'RESTART' is entered then processing continues with this BPKDC. If the entered value is not one of these, the request is cancelled and either the ECB is exited or control is passed back to the calling segment depending on if the ERROR parameter was coded on the execution form.

By providing a switch capability, it is possible to restrict input parameters to those commands on which the input parameters are valid. In this example, ZMCPY ABORT BP, the BP keyword is only allowed when 'ABORT' has been specified. Therefore if it is entered on one of the other types of ZMCPY, it will not be accepted as valid because the BPKDCs for those messages do not have the 'BP' defined for them.

The 'ALL' case shows another reason for the BPKDC switch. It allows the input parameters to be defined as to the conversion to be performed on them. The 'FROMSDA' and the 'TOSDA' are entered as hexadecimal input, and this BPKDC specifies that they are to be converted to binary hexadecimal numbers. Also the 'TO' PS parameter allows the command to be tested for correct syntax. The 'TO' value can only be 'TO' (as defined in the BPPSC) and must be specified. If it is not entered, or not entered as 'TO' then an error message is written and the request is cancelled. This fulfills the syntax checking required by the operator's guide.

Note:
When doing BPKDC switching as in the above paragraph, the BPKDC parameter definitions before the switch point must be the same in all the possible branch to BPKDCs. In other words, if the switch parameter is the third parameter, the first two parameter definitions must be the same in the BPKDC statements. In the above example the first parameter definition is repeated in each of the three BPKDCs. This is required because the tokenizer does not change input or output parameter displacements when it performs a BPKDC switch. It assumes that it will start processing the new BPKDC at the same displacement it would have continued with in the old BPKDC if no switch had occurred.