Syntax rules

Follow these rules when you code CARLa commands:

• CARLa commands generally consist of a command keyword and parameters.¹
• Separate parameters with blanks or commas; multiple blanks and commas are allowed.
• Start a string literal with a quotation mark (single, double, or left quotation mark).
• End a string literal with a matching quotation mark. (A string can contain other quotation marks or comment markers.)
• Start a comment with /* (forward slash followed by an asterisk).
• End a comment with */ (reverse the characters used to start the comment). A comment can contain quotation marks. The /* begin-comment marker has no special meaning within the comment.
• String literals and comments can cross a line boundary.² No other parameters can cross a line boundary.
• A sequence of DBCS (Double-byte Character Set) characters in a line is initiated by a shift-out character and terminated by a shift-in character in the same line.
• Within a string literal crossing a line boundary, if a continuation line starts with a shift-out (SO) character, optionally preceded by SBCS (Single-byte Character Set) space characters, lines immediately preceding this line are trimmed away if they entirely consist of SBCS spaces. Trailing SBCS spaces in the line before these blank lines, if any, are trimmed away as well. If the trimmed line ends with a shift-in (SI) character and the continuation line starts with an SO character, these SI and SO characters are trimmed away, too.
  For instance, if a string literal line ends with 監, an SI character, and an SBCS space, and if the next line starts with an SO character and 査, the CARLa parser interprets this as 監査, without any characters between 監 and 査.
  If SBCS spaces before a DBCS string are significant, for example, for alignment purposes, these spaces can sometimes be placed before the SO character initiating the DBCS string, in the same line as the SO. Alternatively, pairs of SBCS spaces can be represented as DBCS space characters right after the SO. If the number of significant SBCS spaces is odd, a single SBCS space can be placed right before the SO, in the same line as the SO. If the SO is found at the beginning of a line, and if it is inconvenient to insert space characters around it in the same line, it is possible to add a prefix to a new line containing significant SBCS spaces, an SO character, an SI character, and trailing SBCS spaces.
• Commands can cross a line boundary; this generally requires a comma at the end of the line to indicate that more parameters will follow.
• A semi-colon can be used to end a command; otherwise, it ends at the end of a line (when not within a string literal) in the absence of a continuation comma, for example:

  newlist type=racf; select class=program segment=base; sortlist key memlist

• Empty lines are allowed.
• Commands and parameters can be entered in any case; case is significant within string literals. Case is also significant for fields and values that are case-sensitive in the RACF database.
• Some parameters are simple keywords that directly imply a particular function; others have values, for example:

  newlist type=RACF name=EXAMPLE nopage

• Many parameters use the equal sign (=) to assign a specific value. Other operators that signify comparisons can be used in some contexts as well, for example:

  select class=USER segment=BASE passdate<TODAY-30 /* users that 
       did not change their password in the last month */

• Some commands allow the use of parentheses, for example:

  copy user(model) touser(newuser)

• Commands like SELECT and SIMULATE allow relevant parameters to be specified in the same way they are specified in RACF commands, for example:

  simulate setropts protectall(fail)
  select omvs(uid(0))
  /* alternate for: s s=omvs uid=0 */

• For parameters that allow specifying lists, use parentheses and commas, for example:

  select class=(MQQUEUE,MXQUEUE)

• Some commands have a global effect and can be placed anywhere in the query, but the order of commands is generally significant. Some hints:
  • SUPPRESS MSG=msgno starts suppressing messages after it is encountered.
  • DEBUG options that show processing during command parsing start showing messages after they have been encountered.
  • OPTION DD=ddname changes the default output specification at this point in the parse; it will remain in effect depending on scope.
  • An OPTION statement within a NEWLIST query applies only to that NEWLIST query.
  • An OPTION statement directly following BUNDLE stays in effect until ENDBUNDLE.
  • In a NEWLIST query, SELECT and EXCLUDE commands must precede SORTLIST and DISPLAY, which must precede SUMMARY (if all are present).
  • DEFINE variable must be specified before use of the variable.
  • A MERGE ... ENDMERGE specification allows a different set of commands within its scope.
  • A STANDARD ... ENDSTANDARD specification allows a different set of commands within its scope.
  • You cannot change the basic characteristics of an output file if you have already directed output to the file.
  • Some global specifications (for example, ALLOC NOESTAE) must be done in the PARM string passed to the program.