Control Language (CL) Concepts

Command parts

This figure illustrates the parts of a command, which includes: command label (optional), command name (mnemonic), and one or more parameters. The parameter includes a keyword and a value.

Parts of a Command

For information about the parts of a command, see the following:

In addition, see the following for additional information about command coding:

For additional information about commonly used parameters, see Commonly used parameters: Expanded descriptions.

Command label

Command labels identify particular commands for branching purposes in a CL program. Labels can also be used to identify statements in CL programs that are being debugged. They can identify statements used either as breakpoints or as starting and ending statements for tracing purposes.

Start of changeThe label is typed just before the command name. The standard rules for specifying simple names (*SNAME) apply. The label is immediately followed by a colon. Blanks are allowed, though not required, between the colon and the command name. The label can contain as many as 10 characters, in addition to the colon. End of change START: and TESTLOOP: are examples of command labels.

Command labels are not required, but a label can be placed on any command. For labels that are placed on commands that cannot be run (for example, the Declare CL Variable (DCL) command), when the program branches to that label, the next command following the label is run. If the command following the label cannot be run, the program will move to the next command that can be run. Similarly, you can specify only one label on a line. If a command is not located on that line, the program will jump to the next command that can be run.

To specify multiple labels, each additional label must be on a separate line preceding the command as shown:

LABEL1:
LABEL2:  CMDX

No continuation character (+ or -) is allowed on the preceding label lines.

Command name

The command name identifies the function that will be performed by the program that is called when the command is run. The command name is an abbreviation of the command description. For example, the name MOVOBJ identifies the CL command (Move Object) that moves an object from one library to another. Like other objects, a command name can be optionally qualified by a library name.

For more information about object names and how CL commands are named, see Simple and qualified object names and Object naming rules.

Command parameters

Most CL commands have one or more parameters that specify the objects and values used to run the commands. When a command is entered, the user supplies the command object name, the parameter keyword names, and the parameter values used by the command. The number of parameters specified depends upon the command. Some commands (like the DO (Do) command and the ENDBCHJOB (End Batch Job) command) have no parameters, and others have one or more.

The specification of a group of values on one parameter is described under List of values.

In this topic, the word parameter usually refers to the combination of the parameter keyword and its value. For example, the Move Object (MOVOBJ) command has a parameter called OBJ that requires an object name to be specified. OBJ is the parameter keyword, and the name of the object is the value entered for the OBJ parameter.

See the following topics:

Required, optional, and key parameters

A command can have parameters that must be coded (required parameters) and parameters that do not have to be coded (optional parameters). Optional parameters are usually assigned a system-defined default value if another value is not specified for the parameter when the command is entered.

A command can also have key parameters which are the only parameters shown on the display when a user prompts for the command. After values are entered for the key parameters, the remaining parameters are shown with actual values instead of the default values (such as *SAME or *PRV).

Parameters in keyword and positional form

You can specify parameters in CL using keyword (page ***) form, positional (page ***) form, or in a combination (page ***) of the two.

Parameters in keyword form

A parameter in keyword form consists of a keyword followed immediately by a value (or a list of values separated by blank spaces) enclosed in parentheses. You cannot use blanks between the keyword and the left parenthesis preceding the parameter value. You can place blanks between the parentheses and the parameter value. For example, LIB(MYLIB) is a keyword parameter specifying that MYLIB is the name of the library that is used in some way, depending upon the command in which this LIB parameter is used.

When command parameters are all specified in keyword form, they can be placed in any order. For example, the following two commands are the same:

CRTLIB   LIB(MYLIB)  TYPE(*TEST)
CRTLIB   TYPE(*TEST)  LIB(MYLIB)

Parameters in positional form

A parameter in positional form does not have its keyword coded; it contains only the value (or values, if it is a list) whose function is determined by its position in the parameter set for that command. The parameter values are separated from each other and from the command name by one or more blank spaces. Because there is only one positional sequence in which parameters can be coded, the positional form of the previous CRTLIB (Create Library) command first example is:

CRTLIB   MYLIB  *TEST

If you do not want to enter a value for one of the parameters, the predefined value *N (null) can be entered in that parameter's position. The system recognizes *N as an omitted parameter, and either assigns a default value or leaves it null. In the previous CRTLIB command second example, if you coded *N instead of *TEST for the TYPE parameter, the default value *PROD is used when the command is run, and a production library named MYLIB is created. The description of the CRTLIB command contains the explanation for each parameter.

Notes:

Combining keyword and positional forms

A command may also have its parameters coded in a combination of keyword and positional forms. The following examples show three ways to code the Declare CL Variable (DCL) command.

Keyword form:

DCL   VAR(&QTY)  TYPE(*DEC)  LEN(5)  VALUE(0)

Positional form:

DCL   &QTY  *DEC  5  0

Positional and keyword forms together:

DCL   &QTY  *DEC  VALUE(0)

In the last example, because the optional LEN parameter was not coded, the VALUE parameter must be coded in keyword form.

Note: You cannot specify parameters positionally after a parameter specified in keyword form.

For additional information, see Summary of general command coding rules.

Parameter values

A parameter value is user-supplied information used during the running of a command. An individual value can be specified in any one of the following:

A parameter can specify one or a group of such values, depending on the parameter's definition in a command. If a group of values is specified, the parameter is called a list parameter because it can contain a list of values.

On commands with key and positional parameters, values can be specified in keyword form, positional form, or a combination of both forms. Parameter values must be enclosed in parentheses if any of the following conditions are true:

For additional information, see Summary of general command coding rules.

Constant value

A constant value is an actual numeric value or a specific character string whose value does not change. Three types of constants can be used by the control language: character string (quoted or unquoted), decimal, and logical.

For more information about constant value, see the following:

Character string

A character string is a string of any EBCDIC characters (alphanumeric and special) that are used as a value, including date (page ***) and hexadecimal (page ***) values. A character string can have two forms: quoted string or unquoted string. Either form of character string can contain as many as 5000 characters.

A quoted character string is a string of alphanumeric and special characters that are enclosed in apostrophes. For example, 'Credit limit has been exceeded' is a quoted character string.

The quoted string is used for character data that is not valid in an unquoted character string. For example, user-specified text can be entered in several commands to describe the functions of the commands. Those descriptions must be enclosed in apostrophes if they contain more than one word because blanks are not allowed in an unquoted string.

An unquoted character string is a string consisting of only alphanumeric characters and the special characters that are shown in the Unquoted String column in the Quoted and Unquoted Character Strings (page ***) table. The table summarizes the main EBCDIC characters that are valid in unquoted and quoted character string values. An X in the last column indicates that the character on the left is valid; refer to the specific notes following the figure that indicate why the character is valid as described. The special characters allow the following to be unquoted character string values:

Any of these unquoted strings can be specified for parameters defined to accept character strings. In addition, some parameters are defined to accept predefined values, names, or decimal values either singly or in combinations.

Quoted and Unquoted Character Strings


Name of
Character
Character Unquoted
String
Quoted
String
Ampersand & See Note 5 X
Apostrophe ' See Note 7 -
Asterisk (*) * See Notes 5, 6 X
At sign @ X X
Blank     X
Colon :   X
Comma , See Note 1 X
Digits 0-9 See Note 1 X
Dollar sign $ X X
Equal = See Notes 5, 8 X
Greater than > See Notes 5, 8 X
Left parenthesis ( See Note 4 X
Less than < See Notes 5, 8 X
Letters (lowercase) a-z See Note 2 X
Letters (uppercase) A-Z X X
Minus - See Notes 1, 5 X
Not not symbol
See Notes 5, 8 X
Number sign # X X
Percent %   X
Period . See Notes 1, 11 X
Plus + See Notes 1, 5 X
Question mark ?   X
Quotation marks " " See Note 10 X
Right parenthesis ) See Note 4 X
Semicolon ;   X
Slash / See Notes 3, 5 X
Underscore _ See Note 9 X
Vertical bar | See Notes 5, 8 X

Notes:

  1. An unquoted string of all numeric characters, an optional single decimal point (. or ,), and an optional leading sign (+ or -) are valid unquoted strings. Depending on the parameter attributes in the command definition, this unquoted string is treated as either a numeric or character value. On the CALL command or in an expression, this unquoted string is treated as a numeric value; a quoted string is required if character representation is desired. Numeric characters used in any combination with alphanumeric characters are also valid in an unquoted string.

  2. In an unquoted string, lowercase letters are translated into uppercase letters unless the string is specified for a parameter that has the attribute CASE(*MIXED).

  3. A slash can be used as a connector in qualified names and path names.

  4. In an unquoted string, parentheses are valid when used to delimit keyword values and lists, or in expressions to indicate the order of evaluation.

  5. In an unquoted string, the characters +, -, *, /, &, |, not symbol, <, >, and = are valid by themselves. If they are specified on a parameter that is defined in the command definition with the EXPR(*NO) attribute, they are treated as character values. If they are specified on a parameter that is defined in the command definition with the EXPR(*YES) attribute, they are treated as expression operators.

  6. In an unquoted string, the asterisk is valid when followed immediately by a name (such as in a predefined value) and when preceded immediately by a name (such as in a generic name). For further information on unquoted strings in expressions, see Expressions.

  7. Because an apostrophe within a quoted string is paired with the opening apostrophe (delimiter) and is interpreted as the ending delimiter, an adjacent pair of apostrophes ('') must be used inside a quoted string to represent an apostrophe that is not a delimiter. When characters are counted in a quoted string, a pair of adjacent apostrophes is counted as a single character.

  8. In an unquoted string, the characters <, >, =, not symbol, and | are valid in some combinations with another character in the same set. Valid combinations are: <=, >=, not symbol=, not symbol>, not symbol<, ||, |<, and |>. If the combination is specified on a parameter that is defined in the command definition with the EXPR(*NO) attribute, it is treated as a character value. If it is specified on a parameter that is defined in the command definition with the EXPR(*YES) attribute, it is treated as an expression operator.

  9. In an unquoted string, the underscore is not valid as the first character or when used by itself.

  10. Quotation marks are used to delimit a quoted name.

  11. A period is valid in a basic name, except as the first character.

The following are examples of quoted string constants:

Constant Value
'1,2,' 1,2,
'DON''T' DON'T
'24 12 20' 24 12 20

The following are examples of unquoted strings:

Constant Meaning
CHICAGO CHICAGO
FILE1 FILE1
*LIBL Library list
LIBX/PGMA Program PGMA in library LIBX
1.2 1.2

More information and examples can be found in Character string expressions.

Date values

A date value is a character string that represents a date. Its format is specified by the system value QDATFMT. The length of the date value varies with the format used and whether a separator character is used. For example, if no separator character is used, the length of a date in a Julian format is five characters, and the length of a date in a non-Julian format is six characters. If a separator character is used, the length will be greater. More information on system value QDATFMT is in the System values topic.

The system value QDATSEP specifies the optional separator character that can be used when the date is entered. If a separator character is used, the date must be enclosed in apostrophes. For additional information on system value QDATSEP, see the Work Management Link to PDF book on the V5R1 Supplemental Manuals Web site.

A date value can be specified for the parameters of type *DATE. A year value equal to or greater than 40 indicates a year from 1940 through 1999. A year value less than 40 indicates a year from 2000 through 2039. For additional information on parameter value *DATE, see the PARM (Parameter) statement description.

Hexadecimal values

A hexadecimal value is a constant made up of a combination of the hexadecimal digits A through F and 0 through 9. All character strings except names, dates, and times can be specified in hexadecimal form. To specify a hexadecimal value, the digits must be specified in multiples of two, be enclosed in apostrophes, and be preceded by an X. Examples are: X'F6' and X'A3FE'.

Note: Care should be used when entering hexadecimal values in the range of 00 through 3F, or the value FF. If these characters are shown or printed, they may be treated as device control characters producing unpredictable results.

Decimal values

A decimal value is a numeric string of one or more digits, optionally preceded by a plus (+) or minus (-) sign. A decimal value can contain a maximum of 15 digits, of which no more than nine can follow the decimal point (which can be either a comma or a period). Therefore, a decimal value can have no more than 17 character positions including the plus or minus sign and decimal point (if any). The following are examples of decimal values.

Decimal Value Examples

Logical values

A logical value is a single character (1 or 0) enclosed in apostrophes. It is often used as a switch to represent a condition such as on or off, yes or no, and true or false. When used in expressions, it can be optionally preceded by *NOT or
not symbol
. The following are examples of logical values:


Constant Value Meaning
'0' 0 Off, no, or false
'1' 1 On, yes, or true

Floating-point constants

A floating-point constant is a representation of a number that consists of:

All floating-point constants are stored as double-precision values. No blanks are allowed between any of the parts of a floating-point constant, and the parts must be in the order listed above.

Some commands have parameters for which floating-point constants can be specified:

For more information about floating-point constants, see the DDS information in the Programming topic.

Variable name

A variable contains a data value that can be changed when a program is run. The variable is used in a command to pass the value that it contains at the time the command is run. The change in value can result if one of the following conditions occur: the value is received from a data area, a display device file field, or a message; the value is passed as a parameter; a Change Variable (CHGVAR) command is run in the program; or another program that is called changes the value before returning it.

The variable name identifies a value to be used; the name points to where the actual data value is. Because CL variables are valid only in CL programs, they are often called CL program variables or, simply, CL variables. CL variable names must begin with an ampersand (&).

CL variables can be used to specify values for almost all parameters of CL commands. When a CL variable is specified as a parameter value and the command containing it is run, the current value of the variable is used as the parameter value. That is, the variable value is passed as if the user had specified the value as a constant.

Because it is generally true that CL variables can be used for most parameters of commands in CL programs, the command descriptions usually do not mention CL variables. For parameters that are restricted to constants only (such as in the DCL command), to CL variables only (such as all of the parameters of the Retrieve Job Attributes (RTVJOBA) command), or to specific types of variables (such as on the RTVJOBA or Retrieve Message (RTVMSG) command), the individual parameter descriptions specify those limitations. Otherwise, if the command is allowed in a CL program, CL variables can be used in place of a value, even with parameters that accept only predefined values. For example, a KEEP parameter having only predefined values of *YES and *NO can have a CL variable specified instead; its value can then be changed to *YES or *NO, depending on its value when the command is run.

A CL variable must contain only one value; it may not contain a list of values separated by blanks.

The value of any CL program variable can be defined as one of the following types:



If value is: CL variable can be declared as:
Name Character
Date or time Character
Character string Character
Numeric Start of change Decimal or integer or character End of change
Logical Logical or character

Expressions

An expression is a group of constants or variables, separated by operators, that produces a single value. The operators specify how the values are combined to produce the single value or result. The operators can be arithmetic, character string, relational, or logical. Start of change The constants or variables can be character, decimal, integer, or logical. End of change For example, the expression (&A + 1) specifies that the result of adding 1 to the value in the variable &A is used in place of the expression.

Character string expressions can be used in certain command parameters defined with EXPR(*YES) in CL programs. An expression can contain the built-in functions %BINARY (or %BIN), %SUBSTRING (or %SST), and %SWITCH, which are covered in detail in Expressions in CL commands. The types of expressions and examples of each are described there.

List of values

A list of values is one or more values that can be specified for a parameter. Not all parameters can accept a list of values. A list parameter can be defined to accept a specific set of multiple values that can be of one or more types. Values in the list must be separated by one or more blanks. Each list of values is enclosed by parentheses, indicating that the list is treated as a single parameter. Parentheses are used even when a parameter is specified in positional form. To determine whether a list can be specified for a parameter, and what kind of list it can be, refer to the parameter description under the appropriate command description.

A list parameter can be defined to accept a list of multiple like values (a simple list) or a list of multiple unlike values (a mixed list). Each value in either kind of list is called a list element. List elements can be constants, variables, or other lists; expressions are not allowed.

The following are examples of lists:

art - examples of lists

The last two examples contain two lists nested inside a list: the first list contains values of A and B, and the second list contains values of 1 and 2. The space between the two nested lists is not required. Blanks are the separators between the values inside each nested list, and the sets of parentheses group the nested values into larger lists.

Command syntax

Commands have the following general syntax. The brackets indicate that the item within them is optional; however, the parameter set may or may not be optional, depending upon the requirements of the command.

[//] [?] [label-name:][library-name/]command-name
[parameter-set]

Note: The // is valid only for a few batch job control commands, such as the DATA command. The // identifies those types of commands sent to the spooling reader that reads the batch job input stream.

Command delimiters

Command delimiters are special characters or spaces that identify the beginning or end of a group of characters in a command. Delimiters are used to separate a character string into the individual parts that form a command: command label, command name, parameter keywords, and parameter values. Parameter values can be constants, variable names, lists, or expressions. The following diagram shows various delimiters for a command:

Command Delimiters

The following delimiters are used in the OS/400(R) control language:

For additional information, see Summary of general command coding rules.

Command continuation

Commands can be entered in free format. This means that a command does not have to begin in a specific location on a coding sheet or on the display. A command can be contained entirely in one record, or it can be continued on several lines or in several records. Start of change Whether continued or not, the total command length cannot exceed 32,702 characters. End of change Either of two special characters, the plus sign (+) or the minus sign (-), is entered as the last nonblank character on the line to indicate that a command is continued. Blanks immediately preceding a + or - sign are always included; blanks immediately following a + or - in the same record are ignored. Blanks in the next record that precede the first nonblank character in the record are ignored when + is specified but are included when - is specified.

The + is generally useful between parameters or values. At least one blank must precede the sign when it is used between separate parameters or values. The difference between the plus and minus sign usage is particularly important when continuation occurs inside a quoted character string.

The example that follows shows the difference. See Code disclaimer information (page ***) for information pertaining to code examples.

CRTLIB LIB(XYZ) TEXT('This is CONT+
   INUED')
 
CRTLIB LIB(XYZ) TEXT('This is CONT-
   INUED')
 
For + : CRTLIB LIB(XYZ) TEXT('This is CONTINUED')
 
For - : CRTLIB LIB(XYZ) TEXT('This is CONT   INUED')

Notes:

Entering comments in commands

Comments can be inserted either inside or outside a command's character string wherever a blank is permitted. However, because a continuation character must be the last nonblank character of a line (or record), comments may not follow a continuation character on the same line.

For readability, it is recommended that each comment be specified on a separate line preceding or following the command it describes, as shown here:

MOVOBJ   OBJA  TOLIB(LIBY)
        /* Object OBJA is moved to library LIBY. */
DLTLIB  LIBX
        /* Library LIBX is deleted. */

Comments can include any of the 256 EBCDIC characters. However, the character combination */ should not appear within a comment because these characters end the comment. To begin a comment, the characters /* must be placed in the first position of the command, be preceded by a blank, or be followed by either a blank or an asterisk.

Summary of general command coding rules

This section contains a summary of general information needed to properly code CL commands.

Delimiters

Parameters

Parameter Values

Note: When you are using parameters that have the same name in different commands, the meaning of (and the values for) that parameter in each command may be somewhat different. Refer to the correct command description for the explanation of the parameter you are using. For some parameters, you can also refer to Commonly used parameters: Expanded descriptions for both general information about a parameter and an expanded description of its values coded in commands.

Double-byte character text in CL commands

You can use double-byte character data anywhere in a CL command that descriptive text can be used.

Enter double-byte character text as follows:

  1. Begin the double-byte character text with an apostrophe (').
  2. Enter a shift-out character.
  3. Enter the double-byte character text.
  4. Enter a shift-in character.
  5. End the double-byte character text with an apostrophe (').

Start of change

For example, to enter the double-byte character literal ABC, enter the following, where Shift-out character represents the shift-out character and Shift-out character represents the shift-in character:

' Shift-out characterABC Shift-out character'

End of change

Limit the length of a double-byte character text description of an object to 14 double-byte characters, plus the shift control characters, to make sure that the description is properly displayed and printed.


[ Top of Page | Previous Page | Next Page | Table of Contents ]