The CMDTST macro causes SDF to
analyze a program statement stored in the program itself, and
pass the results of the analysis to the program.
Additional statements may result from the analysis of the transferred statement, due to the fact that a system exit may replace the transferred statement by several statements. Dealing with these additional statements is the responsibility of the program.
An activated syntax file must contain the definition of the program and its statements.
Figure 14: Effects of the CMDTST macro
Operation | Operands |
CMDTST | PROGRAM = *NONE / <c-string 1..8> / <var: char:8> ,EXTNAME = *NONE / <c-string 1..8> / <var: char:8> ,INPUT = <var: pointer> / *NO ,OUTPUT = <var: pointer> ,STMT = *ALL / <var: pointer> ,DIALOG = *NO / *YES / *ERROR / <var: enum-of DIALOG_S:1> ,MESSAGE = *NO / <var: pointer> ,PROT = *YES / *NO / <var: bit:1> ,BUFFER = *NO / <var: pointer> ,INVAR = *NO ,DEFAULT = *NO / <var: pointer> ,ERROR = *NO / *YES / <var: bit:1> ,CALLID = *NO / <var: pointer> ,EXECUTE = *NO / *YES / <var: bit:1> ,PROCMOD = *ANY / *NO / *YES / <var: enum-of PROCEDURE_S:1> ,CCSNAME = *NO / *EXTEND / <c-string 1..8> / <var: char:8> ,INPUTSV = *NO / *YES / <var: bit:1> ,OUTFORM = *NEW / *OLD / <var: bit:1> ,DEFDEF = *NO / *YES / <var: bit:1> ,MF = C / D / L / M / E |
PROGRAM = <c-string 1..8> / <var: char:8>
Internal name of the program that is executed by the macro. This name is stored in the pro-gram definition1 in the syntax file (see ADD-PROGRAM).
*NONE
The internal name of the program is not specified. In this case the external name of the program must be specified in the EXTNAME operand.
<c-string 1..8> / <var: char:8>
The internal name of the program can be passed as a c-string constant or a string variable. It is at least one byte and at most eight bytes long.
1 If the program-specific syntax file is even assigned with CMDTST, then CMDEDIT is to be specified as the program name.
EXTNAME =
External name of the program that issued the macro call. This name is stored in the program definition in the syntax file (see the ADD-PROGRAM statement, NAME operand, "ADD-CMD Define command").
*NONE
The external name of the program is not specified. In this case the internal name of the program must be specified in the EXTNAME operand.
<c-string 1..8> / <var: char:8>
The internal name of the program can be passed as a c-string constant or a string variable. It is at least one byte and at most eight bytes long.
INPUT =
specifies which statement SDF is to analyze.
*NO
SDF is not to analyze any statement stored in the program, but is instead to analyze an additional statement provided by a system exit.
<var:pointer>
SDF is to analyze the statement whose address is specified. The area with the specified address must be aligned on a halfword boundary. SDF expects the statement in the following format.
2 bytes: absolute length of the record (n+4)
2 bytes: (Reserved)
n bytes: Message text
OUTPUT = <var:pointer>
Address of the standardized transfer area. The area must begin on a word boundary. The transfer area is generated by means of the CMDTA macro (or in OUTFORM=*OLD by means of CMDSTRUC, see chapter “Appendix”).
STMT =
Specifies which statements are permitted as input. Only statements with specified internal statement names are permitted. The internal statement name is stored in the syntax file in the statement definition (see ADD-STMT). It is at least one and not more that 8 bytes in length. The SDF standard statements are always permitted, regardless of the specification made here.
*ALL
All statements are permitted.
<var:pointer>
Address of the list of permitted statements. This list can have been generated with the CMDALLW macro. The list must be aligned on a halfword boundary and structured as follows:
2 bytes: Number of internal names in the list (n)
8 bytes: First internal statement name
...
n bytes: nth internal statement name
DIALOG =
Specifies whether SDF is to conduct a dialog when analyzing statements. This operand is relevant only when the program is executing in an interactive task.
*NO
SDF is not to conduct a dialog.
*YES
SDF is to present the statement given to it by the program to the user in dialog for possible modification, provided this is compatible with the current SDF specifications for the dialog (see MODIFY-SDF-OPTIONS and SET-GLOBALS).
*ERROR
SDF is to conduct a dialog only when it has detected a syntax error. If the statement contains a semantic error, the program can initiate a semantic error dialog by means of CMDCST.
<var:enum-of DIALOG_S:1>
Enumeration variable which can assume the following values:
0 : same as *NO
1 : same as *YES
2 : same as *ERROR
MESSAGE =
Specifies whether SDF is to issue a message when presenting the statement to the user for checking and possible modification (relevant only for DIALOG î NO). SDF integrates this message into the form.
*NO
SDF is not to issue a message.
<var:pointer>
Address of the message text to be issued, aligned to a halfword boundary. The text is expected in the form of a variable-length record.
2 bytes: absolute length of the record (n+4)
2 bytes: (Reserved)
n bytes: Message text
The message text has a maximum length of 400 characters. However, only the first 280 characters are displayed on SDF-formatted screens. If the text contains screen control characters, the menu mask may be destroyed.
PROT =
specifies whether SDF is to log input and messages to SYSOUT. If they are not written to SYSOUT, the user of the program should be informed of this in the program documentation. A logging buffer is available (see BUFFER).
*NO
SDF is not to perform any logging.
*YES
SDF is to log input and messages to SYSOUT.
<var: bit: 1>
Bit variable: | bit = 0: same as *NO |
The log of the statement and error messages can be written to an area defined by the user.
*NO
No buffer is defined.
<var:pointer>
Address of an area in which the log of the specified statement and the messages are stored, irrespective of the values specified for PROT. The area must be aligned to a halfword boundary, and has the following format.
2 bytes: Absolute length of the logging area (n+4)
2 bytes: Actual used length of the logging area
n bytes: Log records
Each individual log record has the following format:
2 bytes: Absolute length of the log record (n+4)
2 bytes: (Reserved)
m bytes: Contents of the log record
If the buffer is not empty, the first record is generally the log of the input command. Subsequent records contain messages. If no input log is available, or if the input log cannot be output, two slashes (“//”) are written to the output area. The alignment of the log records is not guaranteed.
INVAR =
Specifies whether the INVARIANT-INPUT form of the statement is stored. This means that the statement is stored with all the defined operands, all operands having default values and all operands currently allowed for this task. INVARIANT-INPUT is thus the largest input form for a statement available to a user who has certain privileges and who is working in the selected dialog mode. In contrast to LOGGING=*INVARIANT-FORM (see MODIFY-SDF-OPTIONS), this form does not mask out keywords and secret operands.
*NO
The INVARIANT-INPUT form of the statement is not stored.
<var:pointer>
Specifies the address of a buffer into which SDF writes the INVARIANT-INPUT form of the statement. The buffer must be aligned on a word boundary and the first halfword must contain the length of the buffer. SDF stores the INVARIANT-INPUT form as a record of variable length beginning with the second halfword.
The contents of the buffer are then as follows:
2 bytes: Maximum length of the buffer
2 bytes: Output length written by SDF (n+4)
2 bytes: Reserved
n bytes: INVARIANT-INPUT form of the statement, as of the 7th byte
DEFAULT =
specifies whether the following values are to be replaced by SDF with values dynamically generated by the program:
operand values entered or
operand default values
The operands, or operand values, must have been defined accordingly in the syntax file (see ADD OPERAND..., OVERWRITE-POSSIBLE=YES,... and ADD-VALUE...,VALUE=<c-string> (OVERWRITE-POSSIBLE=*YES),...). The program-generated value must be a valid operand value.
In guided dialog, the values generated by the program are displayed by SDF in the form.
Example:
In the MODIFY statements issued to SDF-A, the value *UNCHANGED is replaced by the current value.
*NO
SDF is not to replace the operand values entered by values generated dynamically by the program.
<var:pointer>
Address of a list aligned on a word boundary that contains addresses of conversion descriptions for statements. A formatted transfer area of the type “structure” is used as a conversion description (see section “Format of the standardized transfer area”). Only one conversion description can be specified per statement. A conversion description contains, among other things, the internal statement name and information regarding which of the operand values entered are to be changed and what values they are to be changed to. The list of addresses of conversion description is structured as follows:
2 bytes: Number of conversion descriptions in the list (n)
2 bytes: (Reserved)
4 bytes: Address of the first conversion description
...
4 bytes: Address of the nth conversion description
The areas for the conversion descriptions which are passed for the default values of the program must be aligned on a word boundary. The same is true of the output area of the macros (OUTPUT operand).
If the operands to be given default values are in a structure introduced by a value defined with LIST-ALLOWED=*YES (see ADD-VALUE), the following situation may arise: the conversion description contains several list elements to which structures with operands to be defaulted are attached. On the other hand, the user likewise enters several list elements to which structures with operands to be defaulted are attached. SDF first tries to match the structures entered by the user to those specified in the conversion description by means of the values introducing the structures. If an unambiguous allocation cannot be made on the basis of the values introducing the structures because none of the values entered matches any of the ones in the conversion description or because the user has entered the matching value more than once, the allocation is then made on the basis of the list position of the introductory value.
ERROR =
Specifies how the message text specified with the MESSAGE operand is to be issued.
*NO
SDF is to issue the message text as a message.
*YES
SDF is to issue the message text as an error message.
<var: bit:1>
Bit variable: | bit = 0: same as *NO |
Defines the context to be used by SDF for analyzing the command. CALLID defines the program context (=syntax file hierarchy opened by an OPNCALL macro) in which the statement must be analyzed.
*NO
The currently active syntax file hierarchy is used.
<var. pointer>
Address of a 4-byte field which is aligned on a word boundary. The caller transfers the CALLID of the context to be used.
EXECUTE =*NO / *YES / <var: bit:1>
Specifies whether standard SDF statements are to be executed. EXECUTE is irrelevant if the CMDTST macro does not refer to a new syntax file hierarchy (CALLID=*NO), e.g. if the current syntax file hierarchy is used. In this case, the standard SDF statements are always executed by CMDTST, provided they exist in the current hierarchy. The operand belongs to the multihierarchical attribute introduced with the preceding CALLID operand. If CMDTST refers to a hierarchy opened in parallel (CALLID=<var: pointer>), the standard SDF statements are executed if EXECUTE = *YES.
<var: bit:1>
Bit variable: | bit = 0: same as *NO |
Defines the environment in which the user works. SDF performs a check, as a result of which it rejects commands which are illegal in the specified environment. The operand belongs to the multihierarchical attribute referred to by means of the CALLID operand and is only of relevance if the macro call refers to a new hierarchy opened in addition to the current one.
If no CALLID has been defined (CALLID=*NO), PROCMOD is irrelevant. In other words, the value *ANY is set automatically and reference is made to the current procedure mode.
*ANY
No check is made. Statements are always analyzed.
*YES
Statements are handled as if they were read from a procedure file. They are analyzed if they have been defined in the syntax file with DIALOG-PROC-ALLOWED=*YES and if the program runs in interactive mode, or if BATCH-PROC-ALLOWED=*YES applies in batch jobs.
*NO
Statements are handled as if they were read from a primary level, e.g. from terminal input or from a batch job. They are analyzed if they have been defined in the syntax file with DIALOG-ALLOWED=*YES and if the program runs in interactive mode, or if BATCH-ALLOWED=*YES applies in batch jobs.
<var: enum-of PROCEDURE_S:1>
Enumeration variable which can assume the following values:
0 : same as *ANY
1 : same as *YES
2 : same as *NO
CCSNAME =
Specifies the name of the character set used for the correction dialog on 8-bit terminals and for conversion from lowercase to uppercase letters. Each terminal uses a certain character set. A coded character set (CCS) is the unique representation of the characters in a character set in binary form. Each coded character set is defined by its coded character set name, or CCSN (see the “XHCS” manual [11]). This parameter has no effect on message output.
*NO
Standard 7-bit code is used for I/O operations.
*EXTEND
Standard 8-bit code is used for I/O operations.
<c-string 1..8> / <var:char:8>
Specifies the name of a special 8-bit code for I/O operations. The name must be 8 bytes long and can be passed as a c-string constant or as a string variable.
INPUTSV =
Specifies whether a history of past inputs is to be saved in the form of a list that can be subsequently accessed again via the built-in RESTORE mechanism (see the MODIFY-SDF-OPTIONS and RESTORE-SDF-INPUT statements).
*NO
The inputs are not saved.
*YES
The inputs are saved in a buffer.
<var: bit:1>
Bit variable: | bit = 0: same as *NO |
OUTFORM =
Specifies which format of the standardized transfer area is output by SDF. When default values are input, (see the DEFAULT parameter), SDF identifies the format of the transfer area itself.
*NEW
The standardized transfer area has the new format (see "Format of the standardized transfer area").
*OLD
The standardized transfer area has the format used up to SDF V4.0 (see chapter (Appendix) “Appendix”).
<var: bit:1>
Bit variable: | bit = 0: same as *NEW |
DEFDEF =
Specifies whether statements for setting task-specific default values may be entered (see the “Introductory Guide to the SDF Dialog Interface SDF” [1 (Related publications)]).
*NO
Statements for setting task-specific values are not accepted.
*YES
Statements for setting task-specific values are accepted.
<var: bit:1>
Bit variable: | bit = 0: same as *NO |
Description of the parameters MF, PARAM, MACID and PREFIX: see the “Executive
Macros” manual [8 (Related publications)].
Return information and error flags
The format of the transfer area is described on "Format of the standardized transfer area". The format used for the transfer area up to SDF V4.0 can be found in chapter “Appendix”.
Information on the INVARIANT-INPUT form of a statement can be found under the description of the CMDRST macro on "CMDRST Read and analyze statement".
The return code is passed in the standard header of the parameter list.
| Standard header |
| cc: Subcode 2 (SC2) bb: Subcode 1 (SC1) aaaa: Maincode |
| (SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
| 00 | 0000 | Normal termination | |
| 00 | no special occurrences | ||
| 01 | program supplies default values | ||
| 00 | 20 | 0004 | Unrecoverable system error |
| 01 | 0008 | Parameter error: | |
| 00 | wrong parameter list | ||
| 01 | OUTPUT | ||
| 02 | STMT list | ||
| 03 | DEFAULT | ||
| 04 | MESSAGE | ||
| 05 | PROT | ||
| 06 | INVAR | ||
| 07 | CALLID | ||
| 09 | INPUT | ||
| 00 | 40 | 000C | Transfer area too small |
| 00 | 40 | 0018 | Statement is correct but the default values provided by the system are errored |
| 00 | 40 | 001C | Error in statement |
| 00 | 40 | 0020 | Error dialog not possible |
| 00 | 40 | 0024 | Error dialog rejected by user |
| 00 | 40 | 0028 | Not enough space in buffer, log truncated |
| 00 | 40 | 002C | END statements read |
| 00 | 40 | 003C | Program not known in syntax file |
| 00 | 40 | 0040 | Specified CALLID not found |
| 00 | 40 | 0044 | Syntax file entered in DSSM catalog not found |
| 00 | 40 | 005C | Not enough space in INVAR buffer, INVARIANT-INPUT truncated |
| 00 | 40 | 0064 | XHCS error during statement entry |
| 00 | 40 | 006C | Statement for setting task-specific defaults was entered instead of normal statement |
Indicators of additional statements (created by a system exit):
In the case of an error-free parameter list, an indicator for additionally generated statements is stored in the parameter list in the field <prefix><macid>EXIT_ACTIVE.
The following values can occur:
Value | Meaning |
X’00’ X’01’ | There are no further statements There are further statements |
Migration from TRSTMT to CMDTST
| TRSTMT | CMDTST |
INPUTSAV = NO/YES |
|
The macro return code is transferred in the standard header of the parameter list. The maincode of CMDTST is equivalent to the values which were transferred in TRSTMT in the right-most byte in register 15. The generation of equates for return codes by means of the CMDANALY macro is no longer necessary, as these are automatically generated with CMDTST MF=D. The following table shows a comparison of the old (TRSTMT) and new (CMDTST) field names:
TRSTMT | CMDTST |
&P.NOERR | &PREFIX.MDTSUCCESSFUL |