The READCMDS command lets you read and process commands from an external data set or path. The commands are Common Address Space Shell (CASRV) commands or CA product or component command statements. See Statement Syntax for a description of how to specify commands in an external data set.
READCMDS [,DDNAME=ddname][,MEMBER=member][,SYNC={YES|NO|WAIT}]
Note: Do not use the leading comma for the first operand after the command verb.
Parameters
(Optional) DDNAME of data set or path to be used to retrieve command statements for the CA product or component being started.
If omitted, the DDNAME of CASVPARM is used.
If the DDNAME of CASVPARM is not allocated, parameters are retrieved from the system logical PARMLIB data sets.
Optional PDS(E) member name containing command statements. There is no default member name.
Indicates whether commands read in by READCMDS should be queued for synchronous execution.
By default, commands are read in synchronously, and you are prompted to respond to commands that contain errors. You are not prompted to respond to commands that contain errors when SYNC=NO is specified.
YES: Commands should be queued synchronously for execution by READCMDS.
NO: Commands should not be queued synchronously for execution by READCMDS.
The READCMDS command waits for each command to complete processing before the next command is read and executed. The READCMDS command will not terminate until all commands are processed. The completion code from the READCMDS is the highest return code set by any processed command.
This section includes a description of how to specify statements in an external data set. All of the statements in the parameter file (including any line continuation) must be contained within columns 1-71 of the external file. Some of the features that are supported for use in the parameter file are:
Comments
Comments within a parameter file that are removed as part of the "sanitization" process. Two ways to define comments in a parameter file. First, if an asterisk, ‘*’, is placed in the starting column. Second, if text is placed between a spanning comment starting with "/*" and terminating with "*/".
The terminating spanning comment is scanned for unless a starting spanning comment is already found. If a spanning comment begins and does not terminate before end of file is reached, a syntax error occurs and the statement where the error was found is returned.
All data found to be between spanning comments is removed from the parameter statement before the statement is returned to the caller.
For example, the following input parameter file using comments:
/**
** This is a comment that extends over multiple lines
**/
* This is a comment that is over a single line
VERB KEYWORD=( OPERAND0, /* Optional comment */
OPERAND1) /* Optional comment */
Would be returned as:
VERB KEYWORD=(OPERAND0,OPERAND1)
Concatenation
The concatenation operator (||) is used to concatenate quoted strings. The operator only affects it when preceded by a quoted string. When a quoted string precedes the concatenate operator, a quoted string (after comments are removed) must follow it or a syntax error occurs, and the statement on which the error was found is returned.
All quoted strings that are concatenated using the concatenation operator must consistently use the same type of quote to start and terminate each quoted string. If not, a syntax error occurs, and the statement on which the error was found is returned.
For example, the following statement would result in a syntax error:
TEXT="Sample text string " || ‘using concatenation.’ /*SYNTAX ERROR*/
The concatenation operator can be used to concatenate quoted strings on the same line or over multiple lines. If concatenating a quoted string with a string on a proceeding line, the continuation operator (,) is implicit and can be omitted or explicitly supplied.
For example, all three of the following input statements using concatenation:
TEXT="Sample text string " || "using concatenation."
TEXT="Sample text string " ||,
"using concatenation."
TEXT="Sample text string "||
"using concatenation."
Returned as:
TEXT="Sample text string using concatenation."
Continuation
Continuation is only implied following the concatenation operator. In all other cases, to continue a statement, explicitly code continuation at the end of the statement.
If continuation is expected because it was indicated on the end of an input line and the end of file is reached, a syntax error occurs and the statement on which the error was found is returned.
A "dangling" comma (,) on the end of a parameter statement does continuation by default. In this case, the comma remains in the statement that the Common Parameter File Reader Service retruned.
For example, the following input statement using default continuation:
VERB KEYWORD=( OPERAND0, OPERAND1, OPERAND2, OPERAND3)
Would be returned as:
VERB KEYWORD=(OPERAND0,OPERAND1,OPERAND2,OPERAND3)
ENDIF Keyword
ENDIF is used to terminate a corresponding IF keyword statement. The ENDIF keywords must equally match the number of IF keyword statements that are specified in a parameter file. If there are more ENDIF keyword statements than there are corresponding IF keyword statements, a syntax error occurs and the statement on which the error was found are returned.
ENDIF is only recognized as a keyword if it is the first verb that is read in on a given input statement. You can use comments on an ENDIF keyword statement, but not other extraneous data can be found. If extraneous data is found on a keyword statement, a syntax error occurs and the statement on which the error was found is returned.
If an ENDIF keyword statement is successfully processed, the statement is not returned to the caller; rather, the service will begin reading the next statement.
For example: usage of the ENDIF keyword statement, see the IF keyword statement.
IF Keyword
The IF keyword statement is used to support "if" logic in a parameter file. Several cases for which a syntax error can be found on an IF keyword statement. For all of the syntax errors, the statement on which the error was found is returned.
The IF keyword takes on the form:
IF &symbol. [!]= (value0 [,value1] …)
The IF keyword statement is only recognized as a keyword if it is the first verb that is read in on a given input statement. Follow it by one or more spaces. If a space does not follow "IF", it is not treated as a keyword. IF keyword statements can be nested up to 12,287 levels.
If the service determines that the IF keyword statement is present, and the caller of the service specified SYMSUB=NO on the OPEN call, symbol substitution will be done on the next data item found, &symbol., unconditionally. (See MVS Initialization and Tuning Reference for more information about the system symbols.)
&symbol. is a data item compared against the values on the right side of the compare operator. It is passed to the #SYMSUB service and if it was found to be a defined symbol, it is substituted to its appropriate value. If &symbol. was &SYSNAME., after substitution, &SYSNAME. is the name of the current system after substitution. Follow &symbol. by one or more spaces, if a space does not follow it, a syntax error occurs.
[!]= is the compare operator. The valid operators are ‘=’ and "!=" which are interpreted as "equal" and "not equal" respectively. If the operator is ‘=’, the &symbol. is compared against the values on the right side of the compare operator and the IF keyword statement is evaluated as true if the &symbol. is equal to any compare values. If the compare operator is "!=", the &symbol. is compared against the values on the right side of the compare operator and the IF keyword statement is evaluated as true if the &symbol. is not equal to any compare values. One or more spaces must follow [!]=. If a space does not follow it, a syntax error occurs.
(value0 [,value1] …) is compared against the &symbol. regarding the specified compare operator. This part of the IF keyword statement is parsed with the Parse and Scan Facility (PSF) Common Service. Up to 32 different compare values can be specified here. If more than one value is compared, enclose the values inside of parentheses and separate each value by a comma. If PSF finds a syntax error and an error message buffer was supplied by the caller on the READ request, an error message is returned in the error message buffer. See the MSGBUF description and the PSF message descriptions for the format of this message and information about how to determine why the syntax error occurred.
If any part of the IF keyword statement as described in its form is omitted, a syntax error occurs.
If an IF keyword statement is successfully processed, the statement is not returned to the caller. The service begins reading the next statement.
For the remainder of the IF keyword description section, the following statements are all read while executing on a system name "SYS1" with the "z/OS" operating system.
For this example, the following input statements use an "equal" compare:
IF &SYSNAME.=SYS1
INCLUDE SYS1PARM
ENDIF
This causes INCLUDE member "SYS1PARM" to be opened as an INCLUDE member because &SYSNAME. is substituted as "SYS1", and the IF keyword statement would evaluate as true. Notice that ENDIF is always required to be paired with an equal number of IF keyword statements. See the ENDIF keyword for more information about this.
For this example, the following statements use a "not equal" compare:
IF &SYSNAME.!=SYS1
INCLUDE SYS1PARM
VERB KEYWORD=OPERAND
ENDIF
This causes the INCLUDE member keyword statement to be skipped and the "VERB KEYWORD=OPERAND" statement because &SYSNAME. is substituted as "SYS1", and the "if not" statement would evaluate as false. The skipped statements are processed but not returned to the caller on a READ request.
For this example, the following statements use nested IF keyword statements:
IF &OSNAME.=z/OS
IF &SYSNAME=(SYS1, SYS2)
INCLUDE SYS1PARM
ENDIF
IF &SYSNAME != (SYS1, SYS2)
INCLUDE PARMFILE
ENDIF
ENDIF
This causes INCLUDE member "SYS1PARM" to be opened as an INCLUDE member because &SYSNAME. is substituted as "SYS1", and the IF keyword statement would evaluate as true as before, simultaneously this statement is inside of an IF keyword statement comparing the &OSNAME. symbol that has also been evaluated to be true. The IF keyword statement doing a "not equal" compare is evaluated as false, and therefore, "PARMFILE" is not opened as an INCLUDE member.
INCLUDE Keyword
INCLUDE is a parameter file keyword, and if found, is used to allow multiple members to be included and read as one large parameter file.
INCLUDE is only recognized as a keyword if it is the first verb that is read in on a given statement. Follow the INCLUDE keyword by at least one space and then an eight character maximum member name. If a space does not follow INCLUDE, it is not treated as a keyword. If a member name does not follow INCLUDE, a syntax error occurs and the statement on which the error was found is returned. If the member name is longer than eight characters or if there is extraneous data is found on the statement after the member name a syntax error occurs.
The INCLUDE members can INCLUDE other members themselves. No defined restriction exists to the number of nested INCLUDE statements. All INCLUDE members must unique between one another and between the originally opened parameter file. Do not recursively INCLUDE parameter files.
When the end of file is reached for an INCLUDE member, reading resumes with the member that opened the file using the INCLUDE keyword statement. All syntax rules apply within a given parameter file only. Do not begin a spanning comment beginning at the end of an INCLUDE member and attempt to terminate the spanning comment in the original member. This action yields a syntax error.
For example, to INCLUDE a parameter file "PARMFILE", code:
INCLUDE PARMFILE
LOG/NOLOG Keywords
LOG and NOLOG are used to control logging attributes of a parameter file.
When the LOG keyword is in use, each statement image in the parameter file is written to the system log. The message identifier CAMS504I prefixes each statement image in this case. If the statement image contains a symbolic value that has been successfully substituted, the statement image containing the substituted value is also written to the system log. The message identifier CAMS505I prefixes each statement image in this case.
Note: When reading from the Logical Parmlib Concatenation, statement images that contain symbolic values are only logged with the substituted values.
When the NOLOG keyword is in use, no records in the parameter file are written to the system log.
The LOG and NOLOG keywords can be used any number of times in a parameter file. The current log specification remains in effect until a different log specification is requested. The current log specification also remains in effect for parameter files that are opened with the INCLUDE keyword. Changes in the log specification in a parameter file that was opened with the INCLUDE keyword only remain in effect until the INCLUDE file is closed. After an INCLUDE file is closed, the logging attributes for the previous member carry on.
LOG and NOLOG are only recognized as keywords if they are the first verbs read on a given input statement. You can use comments on the LOG and NOLOG keywords statements, but no other extraneous data can be found. If extraneous data is found on a keyword statement, a syntax error occurs and the statement on which the error was found is returned.
If a LOG keyword statement is successfully processed, the effect of the keyword takes effect immediately.
If a NOLOG keyword statement is successfully processed, the effect of the keyword takes effect beginning with the next statement image read in.
Example
For the following example, assume that NOLOG is in effect at the time the first statement is read and that the statements are all read while executing on a system name “SYS1”. The following input statements using LOG and NOLOG keywords:
LOG VERB1 KEYWORD1=(&SYSNAME.) NOLOG VERB2 KEYWORD2=(OPERAND2)
Logged to the system log as:
CAMS504I LOG CAMS504I VERB1 KEYWORD1=(&SYSNAME.) CAMS505I VERB1 KEYWORD1=(XE97) CAMS504I NOLOG
Parentheses
Opening left, ‘(‘, and closing right, ‘)’, parentheses are searched for. If found, the whitespace between in parentheses is compressed.
Parentheses checking are only done when an opening parenthesis is found. If a closing parenthesis is found before finding an opening parenthesis, the parenthesis is treated as a non-special character.
Pair parentheses. If a left parenthesis is found on a parameter statement, and a right parenthesis is not found before the end of the statement is reached, a syntax error occurs. The statement on where the error was found is returned.
More syntax checking for nesting parentheses is not done. For example, if multiple opening parentheses are found, only one closing parenthesis must be found before the end of the statement is reached to prevent a syntax error.
For example, the following input statement using parentheses:
VERB KEYWORD=(OPERAND0,
OPERAND1,
OPERAND2,
OPERAND3)
Returned as:
VERB KEYWORD=(OPERAND0,OPERAND1,OPERAND2,OPERAND3)
Quoted Strings
The Quoted strings can begin with either a single quote (‘) or a double quote ("). The Quoted strings must be terminated on the same line using a matching ending quote. If a quoted string does not terminate with a matching ending quote on the same line, a syntax error occurs. The statement where the error was found is returned.
Within a parameter file, the quoted strings are not restricted to use single or double quotes as long as each quoted string terminates with the same type of quote that the string started. One exception to that rule that takes effect when concatenating quoted strings with the concatenation operator. See the description on concatenation for more information.
No "sanitization" occurs on data that is determined to be inside of a quoted string. Parentheses, comments, and keywords are not checked for inside of a quoted string.
The double quotes that are used inside of a single quoted string remain unchanged. Likewise, single quotes that are used inside of a double quoted string remain unchanged.
Example
The following input statement would be returned unchanged:
TEXT=’Sample text "string" using double quotes.’
To use quotes inside of a quoted string of the same kind, use two consecutive quotes or the escape character backslash (\) immediately preceding the quote.
Example
The following input statements using double quotes inside of a double quoted statement:
TEXT="Sample text \"string\" using double quotes." TEXT="Sample text ""string"" using double quotes."
Returned as:
TEXT="Sample text "string" using double quotes."
Example
The following input statements using single quotes inside of a single quoted statement (a space is added between the two consecutive single quotes for emphasis):
TEXT=’Sample text ‘\’string\ ’ using single quotes.’ TEXT=’Sample text ‘ ’string’ ’ using single quotes.’
Returned as:
TEXT=’Sample text ‘string’ using single quotes.’
|
Copyright © 2014 CA Technologies.
All rights reserved.
|
|