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.
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 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.
The 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.
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.
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.
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:
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).
You can specify parameters in CL using keyword (page ***) form, positional (page ***) form, or in a combination (page ***) of the two.
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)
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.
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:
Note: If only one value is specified for a list, no parentheses are required.
For additional information, see Summary of general command coding rules.
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:
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 |
![]() | 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:
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.
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
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.
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.
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.
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
. The following are examples of logical values:
Constant | Value | Meaning |
---|---|---|
'0' | 0 | Off, no, or false |
'1' | 1 | On, yes, or true |
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.
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 |
![]() ![]() |
Logical | Logical or character |
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.
The constants or variables can be character, decimal, integer, or
logical.
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.
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.
Note: *N cannot be specified in a simple list, but it can be specified in a mixed list. Also, individual parameters passed on the CALL and CALLPRC commands cannot be lists.
The following are 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.
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 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:
The following delimiters are used in the OS/400(R) control language:
Because an apostrophe inside a quoted string is paired with the opening apostrophe (delimiter) and is interpreted as the ending delimiter, an apostrophe inside a quoted string must be specified as two apostrophes. A pair of adjacent apostrophes used this way is counted as a single character.
Within a CL program, when a question mark precedes a command name, a prompt display is presented. You can enter parameter values not specified on the command in the program.
Prompting characters may be put into a command in two forms. A single question mark (?) may be coded before the command name (either before or after the command label in a CL program) to cause the entire command to be prompted. Selective prompt characters (?? or ?*) may be coded before any parameter keyword to cause that parameter to be prompted when the command is run.
If a question mark is entered before the command name on the command entry display, the effect is the same as pressing the F4 (Prompt) key after the command is entered.
Within a CL program, when a question mark precedes the command name, a prompt display is presented. This display is of the same format as that presented when pressing the F4 key from the command entry display. Parameters of the command for which the program has coded values are shown for informational purposes, but the user cannot change the values supplied by the program. Parameters for which no value was coded are shown as input fields so you can enter values to be used in processing the command.
Selective prompting allows you to identify specific command parameters to
be prompted. To call selective prompting, the characters ??, ?*, or ?-
are coded immediately preceding the keyword name of the parameter(s) to be
prompted. More information on prompting is available in the CL Programming
book.
Notes:
Either form of prompting, but not both, is allowed on a single command in a CL program. If the character ? precedes the command name and selective prompt characters (except ?-) precede any keyword, an error message is returned and the program is not created.
For additional information, see Summary of general command coding rules.
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.
Whether continued or not, the total command length cannot exceed 32,702
characters.
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:
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.
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.
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:
For example, to enter the double-byte character literal ABC, enter the
following, where
represents the shift-out character and
represents the shift-in character:
'
ABC
'
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.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.