Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly
Loading...

{{viewport.spaceProperty.prod}}

CMDRST Read and analyze statement

&pagelevel(5)&pagelevel

The CMDRST macro causes SDF to

  • read in a program statement from SYSSTMT. (For the system file SYSSTMT the same assignment applies as was made for the system file SYSDTA. With regard to continuation lines, continuation characters and notes, the same rules apply to statement input from SYSSTMT as to command input from SYSCMD.)

  • analyze the statement read in, and

  • pass the results of the analysis to the program.

This presupposes that an activated syntax file contains the definition of the program and its statements.
The input length for a statement read via CMDRST is 16348 bytes.

In addition to normal reading and analysis of statements, CMDRST can also read records. However, this function is intended solely for purposes of migration. SDF merely passes the records on, i.e. no formatting takes place.

Figure 12: Effects of the CMDRST macro

Operation

Operands

CMDRST

PROGRAM = <c-string 1..8> / <var: char:8>

,OUTPUT = <var: pointer>

,STMT = *ALL / <var: pointer>

,PREFER = *ALL / <c-string 1..8> / <var: char:8>

,DEFAULT = *NO / <var: pointer>

,MESSAGE = *NO / <var: pointer>

,PROT = *YES / *NO / <var: bit:1>

,BUFFER = *NO / <var: pointer>

,INVAR = *NO / <var: pointer>

,SPIN = *NO / *YES / <var: bit:1>

,ERRSTMT = *STEP / *NEXT / <var: bit:1>

,CALLID = *NO / <var: pointer>

,CCSNAME = *NO / *EXTEND / <c-string 1..8> / <var: char:8>

,DATA_RECORD = *NO / <var: pointer>

,STMTRC = *NO / <var: pointer>

,OUTFORM = *NEW / *OLD / <var: bit:1>

,MF = C / D / L / M / E

PROGRAM=<c-string 1..8> / <var: char:8>
Internal name of the program that generates the macro. This name is stored in the program definition in the syntax file (see ADD-PROGRAM). It is at least one byte and at most eight bytes long and can be transferred as a c-string constant or a string variable.

OUTPUT=<var:pointer>
Address of the standardized transfer area, which must begin on a word boundary. The transfer area must be generated with the CMDTA macro (or for OUTFORM=*OLD with CMDSTRUC, see chapter “Appendix”).

STMT =
specifies which statements are permitted as input.
Only statements with specified internal application 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 than eight bytes long. The SDF default statements are always permitted, regardless of the specification made here.

*ALL
All statements are permitted.

<var:pointer>
Address of the list of the permitted statements. This list can have been generated with the CMDALLW macro.

The list must be aligned on a halfword boundary and have the following format:

2 bytes: Number of internal names in the list (n)
8 bytes: First internal statement name

. . .

8 bytes: nth internal statement name

PREFER =
Relevant only for guided dialog; specifies whether a particular statement is expected as the next input.

*NO
No particular statement is expected. SDF asks the user via the statement menu which statement is to be entered.

<c-string 1..8>
Internal name of the statement most likely to be entered. SDF does not display a statement menu in which the user selects the statement to be entered, but instead immediately displays the form listing the operand values for the expected statement. The user may of course enter another statement instead of the one expected.

Example:

Following MODIFY-OPERAND, SDF-A expects MODIFY-VALUE as the next statement. The internal statement name is stored in the statement definition in the syntax file (see ADD-STMT). It is at least one byte and at most eight bytes long.

<var: char:8>
Address of an area, 8 bytes long, containing the internal name of the expected statement. The name must be left-justified and padded with blanks as necessary (X’40’).

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 entered MODIFY statements SDF replaces the value *UNCHANGED by the current value.

*NO
SDF is not to replace the entered operand values by values generated dynamically by the program.

<var: pointer>
Address of a list aligned on a word boundary which contains the addresses of conversion descriptions for statements. The conversion descriptions for these statements are a formatted transfer area of the type “structure” (see section “Format of the standardized transfer area”ff). Only one conversion description can be specified per statement. A conversion description contains, among other things, the internal statement name and information as to 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 descriptions has the following format:

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.

MESSAGE =
specifies whether SDF is to issue a message when requesting statement input. In guided dialog this message is integrated into the statement menu.

*NO
SDF is not to issue a message.

<var: pointer>
Address of the message text to be issued, or a register that contains this address. 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 text may be 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 log buffer can be provided.

*YES
SDF is to log input and messages to SYSOUT.

*NO
SDF is not to perform any logging.
The following behavior may be expected:


Result of analysis

PROT parameter

*YES

*NO

No error

Input statement

– / –

Syntax error

1. Input statement
2. Syntax error message
3. Spin-off message

Spin-off message


BUFFER =
The statement log and the error messages can be written into an area provided by the user.

*NO
No buffer area is provided.

<var: pointer>
Address of an area in which the log of the entered statements and the messages are written, regardless of what was specified for PROT. The area must be aligned on a word boundary and has the following format:

2 bytes:   Maximum length of logging area
2 bytes:   Length of logging area actually used
n bytes:   Log records

Each individual log set has the following format:
2 bytes:   Absolute length of the log record (m+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 into the output area.

INVAR =
Specifies whether the INVARIANT-INPUT form of the statement is stored. This means that the statement is stored with all the specified operands, all operands having default values and all operands currently allowed for this task. In contrast to LOGGING=*INVARIANT-FORM (see MODIFY-SDF-OPTIONS), this form does not mask out keywords and secret operands. More details on this topic can be found on "CMDRST Read and analyze statement".

*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:   Length of the record written by SDF (n+4)
2 bytes:   (Reserved)
n bytes:   INVARIANT-INPUT form of the statement, starting at the seventh byte

SPIN =

Specifies which statement, in batch mode, SDF is to read and analyze next.

*NO
SDF is to read and process the next statement in the statement sequence.

*YES
SDF is to skip all statements until the next STEP statement (or, as the case may be, until the END statement) and, if there is a STEP statement, continue processing with the statement following it.

<var: bit1>

Bit variables:

bit = 0: as *NO
bit = 1: as *YES

ERRSTMT =

defines which statement terminates the spin-off mechanism if SDF senses a syntax error for the read statement.

*STEP
SDF initiates spin-off until STEP or END is recognized. The return code is X’1C’, X’34’,...

*NEXT
SDF does not initiate spin-off. The next statement is read on the next CMDRST call. The return code is then X’50’.

<var: bit1>

Bit variables:

bit = 0: as *STEP
bit = 1: as *NEXT

CALLID =

This function applies to the OPNCALL and CLSCALL macros.
CALLID specifies the program context (=syntax file hierarchy opened by an OPNCALL macro) in which the statement must be read and analyzed. The name of the syntax file hierarchy (CALLID) must have the 4-byte value returned by SDF to the field which was designated by the CALLID operand in the OPNCALL macro.

*NO
The current syntax file hierarchy (context) of the task is used for analyzing the statement. This can, for example, be the syntax file hierarchy opened for the task at LOGON.

<var: pointer>
Address of the call check field or register containing this address. The area must be aligned on a word boundary.

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 (Related publications)]). 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.

DATA_RECORD=
determines whether SDF stores data which was entered instead of statements. If this is the case, SDF returns a special return code (see “Return information and error flags (CMDSEL Create selection mask for guided dialog)“ below). This parameter may only be used for migration from RDATA to CMDRST (not for programs which already contain RDSTMT or CMDRST calls). In this way a program which only offers the SDF interface in the dialog can be called compatibly in procedures and batch jobs. The SDF statements of the program must be preceded by “//” in the procedures and batch jobs.

*NO
No data storage. The result of the CMDRST call is dependent on the input:

Input from:

Type of input

Output by CMDRST

Terminal

//<stmt>

in OUTPUT parameter

Terminal

<data>

not possible

Procedure/Batch

//<stmt>

in OUTPUT parameter

Procedure/Batch

<data>

in OUTPUT parameter 1)

S procedure

//<stmt>

in OUTPUT parameter

S procedure

<data>

Error 2)

1Data treated as statement 

2'//' is mandatory before statements in S procedures

<var: pointer>
Address of an area aligned on a word boundary in which SDF stores the data which was read instead of statements. The area has the following layout:

2 bytes: maximum length of the area
2 bytes: Output length actually used (n+4)
2 bytes: (Reserved)
n bytes: Data records

The result of the CMDRST call is independent of the input:

Input from:

Type of input

Output by CMDRST

Terminal

//<stmt>

in OUTPUT parameter

Terminal

<data>

not possible

Procedure/Batch

//<stmt>

in OUTPUT parameter

Procedure/Batch

<data>

in DATA_RECORD parameter

S procedure

//<stmt>

in OUTPUT parameter

S procedure

<data>

in DATA_RECORD parameter

STMTRC =

Specifies whether the statement supplies a return code. This return code can be evaluated with SDF-P functions in S procedure like a command return code.

*NO
The statement does not generate a return code. SDF transfers some default return codes according to the specifications made for ERRSTMT and SPIN:

(SC2)      SC1

Maincode

Meaning

0           0

CMD0001

No errors

0           1CMD0230SDF is in spin-off
1           0CMD0232//STEP was recognized during spin-off, control returned to program
<var: pointer>

Address of a structure which contains the return code of the statement. SDF checks the following return code requirements to ensure that the ones returned to the user are meaningful. If these are not adhered to, SDF generates its own return codes.

  1. In the case of an error in the read statement, SDF should first be called as CMDRST with SPIN=*YES and a statement return code with SC1 not equal to zero.

  2. In the case of no errors, SDF should first be called with SPIN=*NO and a return code with SC1 equal to zero.

  3. In the case of semantic errors, CMDRST should first be called with SPIN=*YES and a return code with SC1 not equal to null. If no return codes are generated or if the return code is positive, SDF uses the return code CMD0230.

  4. If CMDRST is called with ERRSTMT=*NEXT and the macro return code X'50' is returned, the next CMDRST can be called without spin-off and a return code with SC1 equal to null. The program should not start a spin-off since it has already suppressed a spin-off initiated by SDF.

OUTFORM =
Specifies which format of the standardized transfer area is output by SDF. If 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 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
bit = 1: same as *OLD

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 transfer area format used up to SDF V4.0 can be found in chapter “Appendix”.

In the INVARIANT-INPUT form, the statement is stored with all specified operands, all operands having default values, and all the operand values currently allowed for this task. INVARIANT-INPUT is thus the largest input form for a statement that is available to a user who has certain privileges and who is working in the selected dialog mode. Keywords and secret operands are not masked out. The INVARIANT-INPUT form is not the same as the logging format LOGGING=*INVARIANT-FORM (see MODIFY-SDF-OPTIONS).

The INVARIANT-INPUT form provides a portable format for SDF inputs. Since only standard names are used, this form can be transmitted without problems to a remote partner even if other external names or other default values are used at that location.

The INVARIANT-INPUT form can, however, be rejected by the remote partner if certain commands, operands, etc. have been removed from there (see the REMOVE statement) or are not allowed because of inappropriate privileges. Default values which are not allowed in the local environment are not transmitted to the remote partner, since the default values that apply in the environment of the remote system are inserted on executing the command or 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)SC1MaincodeMeaning
00000000Normal termination
00200004Unrecoverable system error

010008Parameter error:
00


















Wrong parameter list
01OUTPUT
02STMT list
03DEFAULT
04MESSAGE
05PROT
06INVAR
07CALLID
08DATA_RECORD
10STMTRC
0040000CTransfer area too small
00400010End of input recognized
00400014Error in statement, command was recognized
00400018Statement is correct but the default values provided by the system are errored
0040001CError in statement, //STEP was recognized
00400028Not enough space in buffer, log truncated
0040002CEND statements read
00400034Error in statement, the next statement to be processed is END
0040003CProgram not known in syntax file
00400040Specified CALLID not found
00400044Syntax file entered in DSSM catalog not found
00400050Error in statement, spin-off was not initiated
0040005CNot enough space in INVAR buffer, INVARIANT-INPUT truncated
00400064XHCS error during statement entry
00400068Data record was read instead of a statement and stored in the DATA_RECORD buffer


CMDRST also provides the origin of the statement. In the case of a error-free parameter list, the SYSSTMT assignment is stored in the parameter list in field <prefix><macid>SYSSTMT_STATE.

The following values can occur:

Value

SYSSTMT =

X’01’

X’02’

X’03’

X’04’

X’05’

X’06’

Data display terminal

SYSCMD in non-S procedure or file

Card reader

Floppy disk

SYSCMD in S procedure

S variable


Migration from RDSTMT to CMDRST

Migration from RDSTMT to CMDRST is only necessary if the user wants to use the new functions of CMDRST. In doing so, the following points should be noted:

  • In the case of a CMDRST call, the MF parameter must always be specified. The CMDDRST parameter list must be declared and initialized with MF=L, separate from the executing code.The DSECT for the parameter list must be generated with MF=D. Direct modifications (via an offset from the beginning of the parameter list) are not permitted. More information about the parameters MF and PARAM can be found in the “Executive Macros” manual [8 (Related publications)].

    Comparison of RDSTMT and CMDRST

    RDSTMT

    CMDRST

    <Program code> . . .

    <Program code> . . .

    LA 1,LABEL
    USING D,1

    <Code for manipulating the
    parameter list using
    LABEL+Offset>    		<Code for manipulating the parameter
    list with the name from DSECT D>
    CMDRST MF=M,PARAM=(1),<params>

    RDSTMT MF=(E,(LABEL))

    <Program code> . . .

    <Data>

    LABEL RDSTMT MF=L,<params>

    CMDRST MF=E,PARAM=LABEL

    <Program code> . . .

    <Data>

    LABEL CMDRST MF=L,<params>
    <dsect>
    D CMDRST MF=D

  • The macro return code is transferred in the standard header of the parameter list. The maincode of CMDRST is equivalent to the values which were transferred in RDSTMT in the right-most byte in register 15. The generation of equates for return codes with the CMDANALY macro is no longer necessary since these are automatically generated with CMDRST MF=D. The following table shows a comparison of the old (RDSTMT) and new (CMDRST) field names:

    RDSTMT

    CMDRST

    &P.NOERR
    &P.SYERR
    &P.PAERR
    &P.TRUNC
    &P.EOF
    &P.SCMD
    &P.DFLT
    &P.STEP
    &P.PTRC
    &P.END
    &P.EERR
    &P.NOPRG
    &P.INCID
    &P.NOFND
    &P.NEXT
    &P.ITRC
    &P.XHCS

    &PREFIX.MDRSUCCESSFUL
    &PREFIX.MDRSYSTEM_ERROR
    &PREFIX.MDRPARAMETER_ERROR
    &PREFIX.MDRAREA_TOO_SMALL
    &PREFIX.MDREOF
    &PREFIX.MDRSTMTERROR_CMD
    &PREFIX.MDRWRONG_DEFAULTS
    &PREFIX.MDRSTMTERROR_STEP
    &PREFIX.MDRPROTOCOL_TRUNCATION
    &PREFIX.MDREND_STMT
    &PREFIX.MDRSTMTERROR_END
    &PREFIX.MDRPROGRAM_NOT_IN_SYNTAX_FILE
    &PREFIX.MDRINVALID_CALLID
    &PREFIX.MDRSYNTAX_FILE_NOT_FOUND
    &PREFIX.MDRSTMTERROR_NEXT
    &PREFIX.MDRINVARIANT_INPUT_TRUNCATED
    &PREFIX.MDRXHCS_ERROR

  • The syntax for the parameters of CMDRST only differs from RDSTMT in the following points:

    • keywords must be preceded by an asterisk (e.g. *YES)

    • character strings must be enclosed in single quotes (e.g. 'test')

    • the parameter value *ADDR is no longer permitted; only identifiers can be specified.

    Examples of different entries

    RDSTMT

    CMDRST

    PROGRAM = namePROGRAM = 'name'
    OUTPUT= addr/(r)OUTPUT = identifier  2
    STMT = *ALL/(name,...)/  1
    *ADDR(addr/(r))    		STMT = *ALL/identifier
    PREFER = *NO/name/*ADDR(addr/(r))PREFER = *NO/'name'/identifier
    DEFAULT = *NO/(addr,...)DEFAULT = *NO/identifier
    MESSAGE = *NO/addr/(r)MESSAGE = *NO/identifier
    PROT = YES/NOPROT = *YES/*NO
    BUFFER = *NO/addr|(r)BUFFER = *NO/identifier
    INVAR = *NO/addr|(r)INVAR = *NO/identifier
    SPIN = NO/YESSPIN = *YES/*NO
    ERRSTMT = STEP/NEXTERRSTMT = *STEP/*NEXT
    CALLID = *NO/addr/(r)CALLID = *NO/id
    CCSNAME = *NO/*EXTEND/nameCCSNAME = *NO/*EXTEND/'name'/identifier
    MF = LMF = L
    MF = (E,(1))/(E,param)MF = E,PARAM=identifier

    MF not specified (standard form)

    (not supported)

1 List entries are no longer possible for STMT and DEFAULT
2 identifier can be a label in the program (address) or, with MF=M, a register

  • The format of the standardized transfer area was modified at the same time as CMDRST was introduced. Considerably more information can be stored in the new transfer area and the alignment of the data is guaranteed. It is therefore recommended that only transfer areas in the new format are specified for OUPUT and DEFAULT. For reasons of compatibility, SDF continues to support the old format of the transfer area (see the OUTFORM parameter). If the program passes its own default values to SDF, SDF identifies the format of the transfer area itself.

    • In the case of OUTFORM=*OLD, the program section for analyzing the transfer area must not be modified. However, the transfer area must still be generated with CMDSTRUC (see chapter “Appendix”).

    • In the case of OUTFORM=*NEW, it is sometimes sufficient to substitute CMDTA for CMDSTRUC and to recompile the program. The fields in the DSECTs which are generated by CMDSTRUC are to some extent also contained in the DSECTs generated by CMDTA. A list showing the old and new DSECTs can be found in the description of the CMDTA macro (“Migration from CMDSTRUC to CMDTA” (CMDTA Generate transfer area for analyzed statement)).

Powered by Atlassian Confluence and Scroll Viewport.