The caller uses the TRCMD macro to transfer a command to SDF as a character string. SDF analyzes this command and generates a log, INVARIANT-INPUT form or ACCEPTED-INPUT form and the internal form.
The internal form (also called the converted form) is precisely the information which is necessary for calling the command server and therefore for executing the command. The internal form is either a character string or a standardized transfer area, depending on how the command is defined in the syntax file.
SDF also transfers the result of the syntax analysis to the program.
In interactive jobs, the command can be corrected in the course of an error dialog.
The INVARIANT-INPUT form of the statement contains all the specified operands, all the operands which have default values and all the operands which are currently permitted for the task (see also "CMDRST Read and analyze statement").
The ACCEPTED-INPUT form contains all the names in their long form, all the specified operands with their name and value and any corrections. As there are no abbreviations in the ACCEPTED-INPUT form, their uniqueness is guaranteed for later BS2000 versions. Passwords and secret operands are not masked out.
Operation | Operands | |||||||
TRCMD | INPUT = *NO / addr / (r) ,OUTPUT = *NO / addr / (r) ,CMD = *ALL / (name,...) ,DIALOG = NO / YES / ERROR ,MESSAGE = *NO / addr / (r) ,ERROR = NO / YES ,PROT = *YES / *NO / addr / (r) ,MEMORY = ACTUAL / BASIC ,CALLINF = *NO / addr / (r) ,EXIT = YES / NO ,CALLID = *NO / addr / (r) ,EXECUTE = NO / YES ,PROCMOD = ANY / YES / NO / ALL ,CHKPRV = *YES / *NO / addr ,DUMESC = NO / YES ,OVERLNG = NO / YES ,SETVAR = NO / YES ,INVAR = *NO / addr / (r) ,ACCEPT = *NO / addr / (r) ,DEFDEF = NO / YES
|
INPUT =
Determines which command SDF should analyze.
Specification of this parameter is mandatory.
*NO
SDF is not to analyze any commands stored in the program, but rather the first command generated by a system exit. All other commands generated by a system exit can be requested by the repeated call of TRCMD with INPUT=*NO.
addr / (r)
SDF is to analyze the command whose address is specified or is in the specified register. SDF expects the command character string as a variable-length record in the standard BS2000 format. The record area must be aligned on a halfword boundary.
OUTPUT =
determines whether the internal form of the command is generated.
Specification of this parameter is mandatory.
*NO
The internal form of the command is not generated. The syntax of the command specified at INPUT is checked.
addr / (r)
Address of an area in which SDF saves the internal form, or a register which contains this address. The internal form can be processed by the command server. Depending on the command definition in the syntax file, the internal form is either:
a character string (see the statement ADD-CMD ... IMPLE-
MENTOR=*STRING/*PROCEDURE...)a standardized transfer area (see the statement ADD-CMD ... IMPLE-MENTOR=*NEW/*TRANSFER-AREA...).
The area must begin on a word boundary. Before TRCMD is called, the program must ensure that the maximum possible area length is in the first halfword of the area.
CMD =
Determines which commands are permitted as input.
*ALL
All commands of the current syntax hierarchy are permitted.
(name,...)
Only commands whose RESULT-INTERNAL-NAME is specified are permitted. The RESULT-INTERNAL-NAME is in stored in the command definition of the syntax file (see the ADD-CMD statement). The names specified here must be of the data type <alphanum-name 1..8>
DIALOG =
Determines whether SDF is to conduct a dialog during the command analysis. This operand is only relevant when the program is executing in an interactive task.
NO
SDF is not to conduct a dialog.
YES
SDF is to offer the command transferred by the program to the user in the dialog for any changes, as far as this is compatible with the valid SDF specifications for the dialog (see MODIFY-SDF-OPTIONS and SET-GLOBALS).
ERROR
SDF is only to conduct a dialog when syntax errors are detected.
MESSAGE =
Determines whether SDF is to output a message on SYSOUT if the user is offered the command for checking and any changes (only relevant for DIALOG î NO). SDF integrates this message into the form.
*NO
SDF is not to issue a message.
addr / (r)
Address of the message text to be output (aligned on a halfword boundary) or register which contains this address. The text is expected as a variable-length record with a maximum length of 400 characters. In guided dialog only the first 280 characters are represented. SDF interprets the first byte of the message text as a printer control character. If the text contains screen control characters, the menu mask can be destroyed.
ERROR =
Determines how the message text specified for the MESSAGE operand is output.
NO
SDF is to output the message text as a message.
YES
SDF is to output the message text as an error message.
PROT =
Controls the log output for the input command.
*YES
SDF is to write the log form to SYSOUT.
*NO
SDF is to not output a log form.
addr / (r)
Address of a log buffer (aligned on a halfword boundary) or register which contains this address. SDF is only to write the log form of the command and messages in the buffer, not to SYSOUT. The length of the buffer is given in the first halfword of the buffer. The length of the buffer actually used is given in the second halfword. Then come the log records with variable record length.
If the buffer is not empty, the first record is normally the log of the input command. The other records contain messages of all types. If no input log is available or can be output, a slash (/) is written in the output area.
MEMORY =
Specifies whether the definition of the command is to be read from the current syntax file hierarchy or only from the basic system syntax file.
ACTUAL
The command is analyzed in the current syntax file hierarchy.
BASIC
Only the command definition in the basic system syntax file is analyzed. Definitions from a group or user syntax file are ignored.
CALLINF =
Determines whether call information is generated for the command server. If SDF is to execute the commands MODIFY-SDF-OPTIONS and SHOW-SDF-OPTIONS, this call information must be transferred by the program.
CALLINF = *NO
The call information is not generated. No SDF command is executed.
CALLINF = addr / (r)
Address of an area which is 102 bytes long and aligned on a halfword boundary, or a register which contains this address. SDF stores the call information for the input command here.
EXIT = YES / NO
Determines whether system exits (80/81) are called for analyzing the input command.
CALLID =
Determines in which context SDF analyzes the command.
*NO
The currently activated syntax file hierarchy is used (the system context).
addr / (r)
Address of a 4-byte field (aligned on a word boundary), or a register which contains this address. In this, the caller transfers the CALLID of the program context that it wishes to use.
The CALLID of the program context is provided from a previous OPNCALL call. With OPNCALL the input mode for the task can also be specified (parameter TASKTYP).
EXECUTE = NO / YES
Determines whether the SHOW-SDF-OPTIONS and MODIFY-SDF-OPTIONS commands are executed. A precondition for this is that in the case of CALLINF the call information is transmitted for the command. EXECUTE has no meaning if TRCMD refers to the system context rather than the program context (i.e. CALLID=*NO). The commands are always executed by TRCMD.
PROCMOD =
Determines which environment the user works in. SDF carries out a check: commands which are not permitted in the specified environment are not accepted by SDF. This operand refers to the possibility of opening several syntax file hierarchies. It is only important when the macro call refers to one of the new syntax hierarchies which are opened in addition to the current one. In the case of CALLID=*NO, PROCMOD is irrelevant, i.e. the value ANY is set automatically and the current procedure mode is valid.
For further information on the PROCMOD parameter see the OPNCALL macro, parameter TASKTYP=ALL ("OPNCALL Create program context").
ANY
No check is carried out
YES
Commands are handled as though they are being read from a procedure file, i.e. they are analyzed if they are defined in the syntax file with DIALOG-PROC-ALLOWED=*YES and if the program is running in interactive mode, or in the case of BATCH-PROC-ALLOWED=*YES in batch jobs.
NO
Commands are handled as though they are being read from one of the primary levels, e.g. from the screen input or from a batch job. They are analyzed if they were defined in the syntax file with DIALOG-ALLOWED=*YES and if the program is running in interactive mode or in the case of BATCH-ALLOWED=*YES in batch jobs.
ALL
Commands are checked for all procedure modes. Depending on the TASKTYP parameter for the OPNCALL macro, the following behavior is observed:
for TASKTYP=ANY:
Every command is considered to be illegal and is rejected (illegal parameter combination)for TASKTYP=BATCH:
The command is analyzed if it is defined in the syntax file with BATCH-ALLOWED=*YES or BATCH-PROC-ALLOWED=*YESfor TASKTYP=TERMINAL:
The command is analyzed if it is defined in the syntax file with DIALOG-ALLOWED=*YES or DIALOG-PROC-ALLOWED=*YES
CHKPRV =
Determines whether SDF checks the privileges of the commands.
The parameter is only meaningful in the program context (i.e. for CALLID î *NO).
*YES
The privileges are checked as a function of the permitted input mode (TRCMD PROC-MOD=... , OPNCALL TASKTYP=...).
*NO
The privileges of the commands are not checked. The command is not executed, i.e. EXECUTE=NO is always valid.
addr
Address of an 8-byte area in which a 64-bit privilege mask is stored. The command is checked against this privilege mask to determine whether it is permitted in a particular input mode. The order of the privileges in the bit mask is the same as the order in which the privileges are currently defined in the system. These privilege masks can be output with the SDF-I statement SHOW-SYNTAX-FILE for example (see “SDF Dialog Interface” [1]).
DUMESC =
Specifies whether expression substitutions which begin with an escape sign can be considered to be part of the command or ignored. Expression substitutions are normally specified in the form '&proc-parameter' or '&(expression)'.
NO
Specifies whether expression substitutions are considered to be part of the command by SDF and syntactically analyzed as such. In most cases (with the exceptions of <text> and <cmd-rest>) SDF returns a syntax error.
YES
Expression substitutions which begin with the escape character are not subjected to a syntax analysis by SDF. The keyword BY-AND is also ignored.
OVERLNG =
Determines whether SDF is to overwrite the length field of the area specified in OUTPUT (first halfword) with the actual length of the internal form (ISP character string or standardized transfer area). However, this only occurs in the case of a successful function call and if the OUTPUT area is not too short.
NO
The length field of the OUTPUT area is not overwritten.
YES
In the case of a successful function call, the length field is overwritten with the actual length (including the length field) of the internal command form.
SETVAR =
Specifies whether the command can be an assignment of the form '<variable-name>=value' if it is entered in an S procedure. In non-S procedures, there may be conflicts with the permissible ISP inputs for /REMARK, /TYPE, /PAUSE etc.
NO
Equals signs are considered to be part of the operand list of the command. For reasons of compatibility NO is the default value.
YES
Equals signs are interpreted as variable assignments. By default, /SET-VARIABLE is used as the command name. If this command is not defined in the syntax hierarchy, the input command is rejected with a corresponding error message. If SDF could successfully identify the variable assignment, the requested outputs are produced by SET-VARI-ABLE on the basis of the command definition.
INVAR =
Specifies whether the INVARIANT-INPUT form of the command is saved, i.e. that the statement is stored with all the input operands, all the operands with default values and all the operand values which are permitted for the task dependent on the input mode and on the privileges:
The input mode (PROCMOD parameter) is only checked if CALLID is also specified. The dependencies between CALLID and PROCMOD are included in the description of the PROCMOD parameter
The privileges in the case of CHKPRV are only taken into account if CALLID is also specified. If CALLID is not specified, TRCMD uses the current task privileges.
Keywords and secret operands are not masked out.
INVAR must not be specified together with ACCEPT.
*NO
The INVARIANT-INPUT form of the statement is not saved.
addr / (r)
Specifies the address of a buffer aligned on a word boundary in which SDF writes the INVARIANT-INPUT form of the command. The first halfword must contain the length of the buffer. If the buffer is too short, the corresponding macro return code is returned. SDF stores the INVARIANT-INPUT form as of the second halfword as a variable-length record.
The buffer contains the following:
2 bytes 2 bytes 2 bytes
buflen | reclen | filler | invariant-input |
| buflen: reclen: filler: invariant-input: | Length of the buffer Length of the record which SDF writes Filler INVARIANT-INPUT form of the command, beginning at the seventh byte |
ACCEPT =
Specifies whether the ACCEPTED-INPUT form of the command is saved. The ACCEPTED-INPUT form contains all the names in their long form and all the input operands with their names and values (as permitted for the task dependent on the input mode and the privileges):
The input mode (PROCMOD parameter) is only checked if CALLID was also specified. The dependencies between CALLID and PROCMOD are outlined in the description of the PROCMOD parameter.
The privileges for CHKPRV are only taken into account if CALLID is also specified. If CALLID is not specified, TRCMD uses the current task privileges.
Keywords and secret operands are not masked out.
INVAR must not be specified together with ACCEPT.
ACCEPT = *NO
The ACCEPTED-INPUT form of the statement is not saved.
ACCEPT= addr / (r)
Specifies the address of a buffer aligned on a word boundary in which SDF writes the ACCEPTED-INPUT form of the command. The first halfword must contain the length of the buffer. If the buffer is too short, the corresponding macro return code is returned. SDF stores the ACCEPTED-INPUT form as of the second halfword as a variable-length record.
The buffer contains the following:
2 bytes 2 bytes 2 bytes
buflen | reclen | filler | invariant-input |
| buflen: | Length of the buffer |
| reclen: | Length of the record which SDF writes |
| filler: | Filler |
| accepted-input: | ACCEPTED-INPUT form of the command, beginning at the seventh byte |
Specifies whether commands for setting task-specific default values may be input (see the “Introductory Guide to the SDF DIalog Interface“ [1 (Related publications)]).
NO
Commands for setting task-specific default values are not accepted.
YES
Commands for setting task-specific default values are accepted. The set default values remain valid until they are explicitly changed. SDF transfers a special return code if it recognizes a default value definition, and in this case it ignores the output parameters. For syntax errors the normal return code is returned.
MF =
Defines special requirements for the macro expansion (see the “Executive Macros“ manual [8 (Related publications)]).
L
Only the data part of the macro expansion (operand list) is generated. This requires that no operand types with executable code occur in the macro call. The generated data part has the address given in the name field of the macro call.
(E,(1)) / (E,opaddr)
Only the command part of the macro expansion is generated. The corresponding data part (operand list) is indicated by the address “opaddr“. This is either in register 1 or is specified directly.
Return information and error flags
The format of the transfer area is described on "Format of the standardized transfer area".
Register 15 contains a return code in the right-most byte:
X’00’ X’04’ X’08’ X’0C’ X’10’ X’1C’ X’20’ X’24’ X’28’ | Normal termination; command is syntactically correct Unrecoverable system error Operand error in the macro Transfer area too small EOF detected Error in command or command unknown Error dialog not possible Error dialog rejected Error or log area too small |
X’30’ X’38’ X’44’ X’48’ X’5C’ X’6C’ X’70’ | Time out SDF not available Syntax file not found SDF command carried out Not enough space in INVAR buffer, INVARIANT-INPUT truncated Command for setting task-specific fault values recognized String passed is empty |
Indicator for additional command (via a system exit):
If a 1:n conversion of the input command has been carried out via a system exit, the flag shows FURTH in the call information (CALLINF), indicating that further commands can be requested with TRCMD INPUT=*NO.