A Control Language (CL) program is a program that is created from source statements consisting entirely of control language commands.
See the following for concepts relating to CL programs:
This section explains the usage of the EBCDIC character sets, special characters, and IBM(R) -defined fixed values called predefined values.
See the following:
The control language uses the extended binary-coded decimal interchange
code (EBCDIC) character set. For convenience in describing the
relationship between characters used in the control language and those in the
EBCDIC character set, the following control language categories contain the
EBCDIC characters shown:
Category | Characters Included |
---|---|
Alphabetic1 | 26 letters (A through Z), $, #, and @ |
Numeric | 10 digits (0-9) |
Alphanumeric1,2 | A through Z, 0 through 9, $, #, @, period (.), and underscore (__) |
Special Characters | All other EBCDIC characters (for those having special uses in CL, see Special character use) |
Notes:
|
The first three categories contain the characters that are allowed in quoted and unquoted character strings, in comments, and in CL names, such as in names of commands, labels, keywords, variables, and OS/400 objects. Special characters in the last category can only be used in quoted character strings and comments; they cannot be used in unquoted strings. However, some have special syntactical uses when coded in the proper place in CL commands. These uses are given in the Special character use chart.
The following special EBCDIC characters are used by the CL in various ways. They are most frequently used as delimiters (which are covered in Command delimiters) and as symbolic operators in expressions. For more information about symbolic operators, see:
Special characters can be used only in these special ways or inside quoted character strings or comments. The special characters, as shown in the following table, have assigned meanings when coded in control language commands:
Name | Symbol | Meanings |
---|---|---|
Apostrophe | ' ' | Single apostrophe delimiters indicate the beginning and end of a quoted character string (a constant). |
Begin and end comment | /* */ | Indicates the beginning and end of a comment. |
Blank | b1 | Basic delimiter for separating parts of a command (label, command name, and its parameters), and for separating values inside lists. |
Colon | : | Ending delimiter for command labels. Separates parts of time values.3 |
Comma | , | In many countries, used as decimal point in numeric values. Separates parts of date values.2 |
Left and right parentheses | ( ) | Grouping delimiter for lists and parameter values, and for evaluating the order of expressions. |
Period | . | Decimal point. Used to separate the name and extension of a document and folder name and to separate the parts of date values.2 |
Quote | " " | Start of a quoted object name. |
Slash | / | Connects parts of qualified names or path names. |
Slashes | // | Identifying characters used in positions 1 and 2 of BCHJOB, ENDBCHJOB, and DATA commands in the job stream. Also, used as a default delimiter on inline data files. |
Notes:
|
The following characters are used as symbolic operators in CL
commands.
Name | Symbol | Meanings |
---|---|---|
And | & | Symbolic logical operator for AND. |
Asterisk | * | Multiplication operator. Indicates a generic name when it is the last character in the name. Indicates OS/400(R) reserved values (predefined parameter values and expression operators) when it is the first character in a string. |
Concatenation | |>, |<, and ||3 | Character string operator (indicates both values are to be joined). See Expressions for more information on the differences between these concatenation operators. |
Equal | = | Symbolic equal relational operator. |
Greater than | > | Symbolic greater than relational operator. |
Less than | < | Symbolic less than relational operator. |
Minus (hyphen) | - | Subtraction operator, command continuation operator, and negative signed value indicator. Separates parts of date values.1 |
Not |
![]() | Symbolic NOT relational operator. |
Or | |3 | Symbolic logical operator for OR. |
Plus | + | Addition operator, command continuation character, and positive signed value indicator. |
Slash | / | Division operator. Separates parts of date values.1 Used as the separator between parts of a qualified name. |
Notes:
|
Note: | The symbolic operators can also be used in combinations as listed in the chart under Operators in expressions. |
Symbolic operators: Other uses
Symbolic operators can also be used in the following ways:
Name | Symbol | Meanings |
---|---|---|
Ampersand | & | Identifies a CL variable name when it is the first character in the string. |
Percent | % | Identifies a built-in system function when it is the first character in the string. |
Question mark | ? | Specifies a prompt request when it precedes a command name or keyword name. |
Predefined values are IBMR-defined fixed values that have predefined uses in the CL and are considered to be reserved in the OS/400(R) system. Predefined values have an asterisk (*) as the first character in the value followed by a word or abbreviation, such as *ALL or *PGM. The purpose of the * in predefined values is to prevent possible conflicts with user-specified values, such as object names. Each predefined value has a specific use in one or more command parameters, and each is described in detail in the command description.
Some predefined values are used as operators in expressions, such as *EQ and *AND. The predefined value *N is used to specify a null value and can be used to represent any optional parameter. A null value (*N) indicates a parameter position for which no value is being specified; it allows other parameters that follow it to be entered in positional form. To specify the characters *N as a character value (not as a null), the string must be enclosed in apostrophes ('*N') to be passed. Also, when the value *N appears in a CL program variable at the time it is run, it is always treated as a null value.
The type of name you specify in the OS/400(R) control language determines the characters you can use to specify a name. For certain types of names, there are restrictions on the use of certain characters to represent the name. Those types of names are *NAME, *SNAME, and *CNAME.
Note: For a description of how to specify these names when you use command definitions to create commands, see the PARM (parameter) and ELEM (element) statements in Command definition statements.
The characters allowed for the *NAME, *SNAME, and *CNAME names and the rules you use to specify them are shown in Allowable Characters for *NAME, *SNAME, and *CNAME.
See the following for more information about naming within commands:
Type of Name | First Character | Other Characters | Min. Length | Max. Length |
---|---|---|---|---|
*NAME1 |
A-Z, $, #, @
|
A-Z, 0-9, $, #, @, _, .
| 1 | 256 |
*SNAME1 |
A-Z, $, #, @
|
A-Z, 0-9, $, #, @, _
| 1 | 256 |
*CNAME1 |
A-Z, $, #, @
|
A-Z, 0-9, $, #, @
|
|
|
Quoted name2 |
"3
| Any except blank, *, ?, ', ", X'00'-X'3F', and X'FF' | 3 | 256 |
Notes:
|
*NAME (Basic Name): Every basic name can begin with the characters A-Z, $, #, or @ and can be followed by up to nine characters. The remaining characters can include the same characters as the first but can also include numbers 0-9, underscores (_), and periods (.). Lowercase letters are changed to uppercase letters by the system. Basic names used in IBM(R)-supplied commands can be no longer than 10 characters. However, in your own commands, you can define parameters of type *NAME (specified on the TYPE parameter of the PARM or ELEM statements) with up to 256 characters.
Examples of basic names are shown below:
A987@.442# ONE_NAME LIB_0690 $LIBX
Names can be entered in quoted or unquoted form. If you use the quoted form, the following rules and considerations also apply:
*NAME (Basic Name in Quoted Form): Every quoted name must begin and end with a quotation mark ("). The middle characters of a quoted name can contain any character except , *, ?, ', ", hex 00 through 3F, or hex FF, and is delimited by a slash. Quoted names allow you to use graphic characters in the name. The quoted form of basic names used in IBM-supplied commands can be no longer than 8 characters (not including the double quotes). In your own commands, you can define parameters of type *NAME in quoted form with up to 254 characters (not including the double quotes).
Note: Only basic names can be used in quoted form.
Examples of quoted names are shown below:
"A" "AA%abc" "ABC%%abc"
When you use quoted names, you should be aware of certain restrictions:
If a name enclosed in quotation marks is a valid unquoted basic name, the quotation marks are removed. Thus, "ABC" is equivalent to ABC. Because the quotation marks are removed, they are not included in the length of the name. "ABCDEFGHIJ" is, therefore, a valid name on IBM* commands even though it is longer than 10 characters.
*SNAME (Simple Name): Simple names are the same as unquoted basic names but with one exception: periods (.) cannot be used. Simple names are used for CL variables, labels, and keywords to simplify the syntax of the control language.
Some examples of simple names are as follows:
NEWCMD LIB_2
*CNAME (Communications Name): Communications names are the same as unquoted basic names with the following exceptions:
An example of a communications name is shown below:
APPN3@@
Note: Because restricted character sets are sometimes used by other IBM systems, use caution when choosing names that use the special characters #, $, and @. These special characters might not be on the remote system's keyboard. The names that may be exchanged with the remote systems include the following:
Folder names should describe the contents of a folder. The names must be unique and should be easy to type, as well as descriptive to a user. To find a particular folder on the system and change a document stored in it, you must either supply the folder name or select it from a list of names.
Document names should describe the contents of the document. You should give careful consideration to the names you use to help you find the document later. The names must be unique in the folder and should be easy to type, as well as descriptive.
The name you use for a folder or a document must follow these rules:
Character | Special uses |
---|---|
Asterisk (*) | Multiplication operator, indicates generic names, and indicates OS/400(R) reserved values |
Slash (/) | Division operator, delimiter within system values, and separates parts of qualified object names |
Question Mark (?) | Initiates requests for system help |
Folder names should not begin with Q because the system-supplied folder names begin with Q. The following are examples of permitted folder names and folder paths:
@LETTERS FOLDER.PAY PAYROLL/FOLDER.PAY #TAX1/FOLD8.TAX/$1988/PAYROLL/FOLDER.PAY
Notes:
More information on code pages that are supported by OS/400 is in Chapter 5
of the Local Device Configuration
book and in the description of the CRTDEVDSP (Create
Device Description (Display)) command.
In addition to the folder and document names previously described, folders and documents are internally classified in the system by their system object names. These are 10-character names derived from date/time stamps, and, while they are generally not known to the user, they may be specified on some CL commands by specifying *SYSOBJNAM for the folder or document name and by specifying the system object name in a separate parameter.
For more information, see Naming within commands.
A character string expression can be used for any parameter, element, or qualifier defined with EXPR(*YES) in the command definition object. Any expression can be used as a single parameter in the Change Variable (CHGVAR) and If (IF) commands. An expression in its simple form is a single constant, a variable, or a built-in function. An expression usually contains two operands and an operator that indicates how the expression is to be evaluated. Two or more expressions can be combined to make a complex expression.
The following types of expressions are supported in CL programs:
A complex expression contains multiple operands, operators that indicate what operation is performed on the operands, and parentheses to group them. Only one operator is allowed between operands, except for the + and - signs when they immediately precede a decimal value (as a signed value), and the *NOT operator when it is used in a logical expression.
No complex expression can have more than five nested levels of parentheses, including the outermost (required) level.
Arithmetic and character string expressions can be used together in a complex expression if they are used with relational and logical operators; for example: (A=B&(1+2)=3). A pair of arithmetic expressions or a pair of character string expressions can be compared within a relational expression. Also, relational expressions can be used within a logical expression
The operands in an arithmetic expression must be decimal constants or decimal
or integer CL variables.
An arithmetic operator (only in symbolic form) must be between the
operands. The results of all arithmetic expressions are decimal values,
which may be stored in a CL variable.
Note: The division operator (/) must be preceded by a blank if the operand that precedes it is a variable name. (For example, &A /2, not &A/2.) All other arithmetic operators may optionally be preceded or followed by a blank.
Arithmetic operands can be signed or unsigned; that is, each operand
(whether it is a numeric constant or a decimal or integer CL variable) can be
immediately preceded by a plus (+) or minus (-) sign, but a sign is not
required.
When used as a sign, no blanks can occur between the + or - and its
value. For example, a decimal constant of 23.7 can be expressed
as +23.7 or -23.7 (signed) or as 23.7 (unsigned).
The following are examples of arithmetic expressions:
| (&A + 1) | (&A + &B -15) |
| (&A - &F) | (&A+&B-15) |
| (&A + (-&B)) |
|
If the last nonblank character on a line is a + or -, it is treated as a continuation character and not as an arithmetic operator.
The operands in a character string expression must be quoted or unquoted character strings, character variables, or the substring (%SUBSTRING or %SST) built-in function. The value associated with each variable or built-in function must be a character string. The result of concatenation is a character string.
There are three operators that can be used in character string expressions. These operators concatenate (or join) two character strings, but each has a slightly different function. They are:
The *CAT operator concatenates two character strings. For
example:
ABC *CAT DEF becomes ABCDEF
Blanks are included in the concatenation. For example:
'ABC '
*CAT 'DEF ' becomes 'ABC DEF '
The *BCAT operator truncates all trailing blanks in the first character
string; one blank is inserted, then the two character strings are
concatenated. Leading blanks on the second operand are not
truncated. For example:
ABC *BCAT DEF becomes ABC DEF
'ABC ' *BCAT DEF becomes 'ABC DEF'
The *TCAT operator truncates all trailing blanks in the first character
string, then the two character strings are concatenated. All leading
blanks on the second operand are not truncated. For example:
ABC *TCAT DEF becomes ABCDEF
'ABC ' *TCAT DEF becomes 'ABCDEF'
ABC *TCAT ' DEF' becomes 'ABC DEF'
'ABC '*TCAT ' DEF' becomes 'ABC
DEF'
All blanks that surround the concatenation operator are ignored, but at least one blank must be on each side of the reserved value operator (*CAT, *BCAT, or *TCAT). If multiple blanks are wanted in the expression, a quoted character string (a character string enclosed within apostrophes) must be used.
See the following examples for more information about character string expressions.
The following are examples of string expressions. Assume the
following variables:
Variable | Value |
---|---|
&AA | 'GOOD ' |
&BB | 'REPLACEMENT' |
&CC | 'ALSO GOOD' |
&DD | 'METHOD' |
Expression | Result |
---|---|
(&AA || &BB) | GOOD REPLACEMENT |
(&AA||&BB) | GOOD REPLACEMENT |
(&AA *CAT &BB) | GOOD REPLACEMENT |
(&CC |> &DD) | ALSO GOOD METHOD |
(&CC *BCAT &DD) | ALSO GOOD METHOD |
(A *CAT MOUSE) | AMOUSE |
('A ' *CAT MOUSE) | A MOUSE |
|
|
(FAST *CAT MOUSE) | FASTMOUSE |
('FAST ' *BCAT MOUSE) | FAST MOUSE |
('FAST ' *TCAT MOUSE) | FASTMOUSE |
|
|
('AB' *CAT 'CD') | ABCD |
('AB' *BCAT 'CD') | AB CD |
('AB' *TCAT 'CD') | ABCD |
|
|
(%SST(&AA 1 5) *CAT (%SST(&BB 3 5)) | GOOD PLACE |
(%SST(&CC 1 9) *BCAT (%SST(&BB 3 5)) | ALSO GOOD PLACE |
|
|
(&AA *CAT ' TIME') | GOOD TIME |
(&CC *BCAT TIME) | ALSO GOOD TIME |
For another example using character strings and variables:
See Code disclaimer information (page ***) for information pertaining to code examples.
The following example shows how several character variables and character strings can be concatenated to produce a message for a work station operator. The example assumes that the variables &DAYS and &CUSNUM were declared as character variables, not decimal variables.
DCL VAR(&MSG)TYPE(*CHAR) LEN(100) * * CHGVAR &MSG ('Customer' *BCAT &CUSNAMD + *BCAT'Account Number' *BCAT + &CUSNUM *BCAT 'is overdue by' + *BCAT &DAYS *BCAT 'days.')
After the appropriate variables have been substituted, the resulting message might be:
Customer ABC COMPANY Account Number 12345 is overdue by 4 days.
If the variables &DAYS and &CUSNUM had been declared as decimal variables, two other CHGVAR commands would have to change the decimal variables to character variables before the concatenation could be performed. If, for example, two character variables named &DAYSALPH and &CUSNUMALPH were also declared in the program, the CHGVAR commands would be:
CHGVAR &DAYSALPH &DAYS CHGVAR &CUSNUMALPH &CUSNUM
Then instead of &DAYS and &CUSNUM, the new variables &DAYSALPH and &CUSNUMALPH would be specified in the CHGVAR command used to concatenate all the variables and character strings for &MSG.
For another example using character string expressions:
The operands in a relational expression can be arithmetic or character string expressions; they can also be logical constants and logical variables. Only two operands can be used with each relational operator. The data type (arithmetic, character string, or logical) must be the same for the pair of operands. The result of a relational expression is a logical value '0' or '1'.
Refer to the table under Operators in expressions for the meanings of the relational operators, which can be
specified by symbols (=, >, <, >=, <=,
=,
>,
<) or their reserved values (*EQ, *GT, *LT, *GE, *LE, *NE, *NG,
*NL).
If an operation involves character fields of unequal length, the shorter field is extended by blanks added to the right.
Arithmetic fields are compared algebraically; character fields are compared according to the EBCDIC collating sequence.
When logical fields are compared, a logical one ('1') is greater than logical zero ('0'). Symbolically, this is ('1' > '0').
The following are examples of relational expressions:
(&X *GT 25) (&X > 25) (&X>25) (&NAME *EQ GSD) (&NAME *EQ &GSD) (&NAME *EQ 'GSD') (&BLANK *EQ ' ')
The operands in a logical expression consist of relational expressions, logical variables, or constants, separated by logical operators. Two or more of these types of operands can be used in combinations, making up two or more expressions within expressions, up to the maximum of five nested levels of parentheses. The result of a logical expression is a '0' or '1' that can be used as part of another expression or saved in logical variables.
The logical operators used to specify the relationship between the operands are *AND and *OR (as reserved values), and & and | (as symbols). The AND operator indicates that both operands (on either side of the operator) have to be a certain value to produce a particular result. The OR operator indicates that one or the other of its operands can determine the result.
The logical operator *NOT (or
) is used to negate logical variables or logical constants. All *NOT
operators are evaluated before the *AND or *OR operators are evaluated.
All operands that follow *NOT operators are evaluated before the logical
relationship between the operands is evaluated.
The following are examples of logical expressions:
((&C *LT 1) *AND (&TIME *GT 1430)) (&C *LT 1 *AND &TIME *GT 1430) ((&C < 1) & (&TIME *GT 1430)) ((&C<1)&(&TIME>1430)) (&A *OR *NOT &B) (&TOWN *EQ CHICAGO *AND &ZIP *EQ 60605)
Two examples of logical expressions used in the IF command are:
IF &A CALL PROG1 IF (&A *OR &B) CALL PROG1
Operators are used in expressions to indicate an action to be performed on the operands in the expression or the relationship between the operands. There are four kinds of operators, one for each of the four types of expressions:
Each operator must be between the operands of the expression in which it is used; for example, (&A + 4). Operators can be specified as a predefined value (for example, *EQ) or as a symbol (for example, =).
(&VAR *EQ 7)
Where the division operator follows a variable name, the division operator must be preceded by a blank. For example, (&VAR / 5) or (&VAR /5) is valid; (&VAR/5) is not valid.
The following character combinations are the predefined values and symbols
that represent the four kinds of operators; they should not be used in
unquoted strings for any other purpose.
Predefined values and
symbols representing the four kinds of operators
Predefined Value | Predefined Symbol | Meaning | Type |
---|---|---|---|
| + | Addition | Arithmetic operator |
| - | Subtraction | Arithmetic operator |
| * | Multiplication | Arithmetic operator |
| / | Division | Arithmetic operator |
*CAT | ||1 | Concatenation | Character string operator |
*BCAT | |>1 | Blank insertion with concatenation | Character string operator |
*TCAT | |<1 | Blank truncation with concatenation | Character string operator |
*AND | & | AND | Logical operator |
*OR | |1 | OR | Logical operator |
*NOT |
![]() | NOT | Logical operator |
*EQ | = | Equal | Relational operator |
*GT | > | Greater than | Relational operator |
*LT | < | Less than | Relational operator |
*GE | >= | Greater than or equal | Relational operator |
*LE | <= | Less than or equal | Relational operator |
*NE |
![]() | Not equal | Relational operator |
*NG |
![]() | Not greater than | Relational operator |
*NL |
![]() | Not less than | Relational operator |
Notes:
|
When multiple operators occur in an expression, the expression is evaluated in a specific order depending upon the operators in the expression. Parentheses can be used to change the order of expression evaluation. The following table shows the priority of all the operators used in expressions, including signed decimal values.
Priority | Operators |
---|---|
1 | signed (+ and -) decimal values, *NOT,
![]() |
2 | * , / |
3 | +, - (when used between two operands) |
4 | *CAT, ||, *BCAT, |>, *TCAT, |< |
5 | *GT, *LT, *EQ, *GE, *LE, *NE, *NG, *NL, >, <, =, >=, <=,
![]() ![]() ![]() |
6 | *AND, & |
7 | *OR, | |
A priority of 1 is the highest priority (signed values are evaluated first); a priority of 7 is the lowest priority (OR relationships are evaluated last). When operators with different priority levels appear in an expression, operations are performed according to priorities.
When operators of the same priority appear in an expression, operations are performed from left to right within the expression. Parentheses can always be used to control the order in which operations are performed. The value of a parenthetical expression is determined from the innermost level to the outermost level, following the priorities stated above within matching sets of parentheses.
CL provides the following built-in functions:
The binary (%BINARY) built-in function operates on a character string that is contained in a CL character variable.
%BINARY or %BIN can be used in expressions and as either operand (receiver) of the Change Variable (CHGVAR) command. See the CHGVAR command description for more information.
Notes:
The syntax of the binary built-in function is:
>>-&BINARY(-character-variable-name-+-------------------------+--)-> '-starting-position-+-2-+-' '-4-' >--------------------------------------------------------------><
The binary built-in function treats the contents of the specified CL character variable, starting at the position specified for a length of 2 or 4 characters, as a signed binary integer.
When the binary built-in function is used with the VAR parameter on the CHGVAR command, the decimal number or arithmetic expression in the VALUE parameter is converted to a 2-byte or 4-byte signed binary integer. A decimal fraction is not included.
If the starting position and length are not specified, then a starting position of 1 and the length of the character variable specified is used. The length of the character variable must be declared as 2 or 4.
The following are examples of how the %BINARY built-in function can be used.
See Code disclaimer information (page ***) for information pertaining to code examples.
Example 1: Converting binary to decimal
DCL VAR(&N) TYPE(*DEC) LEN(3 0) DCL VAR(&B2) TYPE(*CHAR) LEN(2) VALUE(X'0012') CHGVAR &N %BINARY(&B2)
The content of character variable &B2 is treated as a 2-byte signed binary number and is converted to its decimal equivalent of 18. It is then assigned to the decimal variable &N.
Example 2: Converting decimal to binary
CHGVAR %BIN(&B2) &N
The number contained in the decimal variable &N is converted to a 2-byte signed binary number and is placed in the first and second bytes of the character variable &B2.
Example 3: Used within an arithmetic expression
CHGVAR &N VALUE(%BIN(&B2) + 4)
The contents of character variable &B2 is treated as a 2-byte signed binary integer and is converted to its decimal equivalent of 18. The decimal number 4 is then added and the sum, 22, is assigned to the decimal variable &N.
Example 4: Converting decimal to binary with truncation
CHGVAR %BINARY(&B2) VALUE(122.567)
The number 122.567 is truncated to the whole number 122 and is then converted to a 2-byte signed binary integer and assigned to the character variable &B2. Character variable &B2 will then contain the hexadecimal equivalent of X'007A'.
Example 5: Converting a negative number
DCL VAR(&B4) TYPE(*CHAR) LEN(4) CHGVAR %BIN(&B4) VALUE(-45)
The value -45 is converted to a 4-byte signed binary integer assigned to the character variable &B4. Character variable &B4 then contains the hexadecimal equivalent of X'FFFFFFD3'.
Example 6: Used on the IF command
IF COND(%BIN(&B4) *EQ 0) THEN(GOTO ENDIT)
The content of character variable &B4 is treated as a 4-byte signed binary integer and is compared to the decimal number 0. If they are equal, the command following the label ENDIT is run. If they are not equal, the command following the IF command is run.
Example 7: Varying length character string to CPP
PGM PARM(&P ... ) DCL VAR(&P) TYPE(*CHAR) LEN(202) DCL VAR(&L) TYPE(*DEC) LEN(5 0) DCL VAR(&C) TYPE(*CHAR) LEN(200) * * * CHGVAR &L %BINARY(&P 1 2) CHGVAR &C %SST(&P 3 &L) * * * ENDPGM
This program is the command processing program CPP for a command with a first parameter defined with the attributes TYPE(*CHAR), LEN(200) and VARY(*YES). The first two bytes of character variable &P contain the length of the parameter as *INT2, a 2-byte signed binary integer. The character string specified on the command starts in position 3 of the variable &P. The maximum length of the character string is 200 characters.
The first CHGVAR command retrieves the length from the first two character positions of variable &P and treats the 2 bytes as a signed binary integer. The bytes are converted to the decimal equivalent of the signed binary integer, and are assigned to the decimal variable &L.
The second CHGVAR command retrieves the contents of the parameter by making variable &P a substring and assigning it to variable &C.
Example 8: Converting binary to integer
DCL VAR(&N) TYPE(*INT) DCL VAR(&B2) TYPE(*CHAR) LEN(2) VALUE(X'0012') CHGVAR &N %BINARY(&B2)
The content of character variable &B2 is treated as a 2-byte signed binary number and is converted to its integer equivalent of 18. It is then assigned to the integer variable &N.
The substring built-in function operates on a character string that is contained in a CL character variable or in a local data area. %SUBSTRING or %SST can be used in expressions and as either operand (receiver) of the Change Variable (CHGVAR) command. For more information, see the description of the CHGVAR command. This built-in function can be coded as either %SUBSTRING or %SST.
The syntax of the substring built-in function is:
>>-&SST(-+-*LDA--------------------+--starting-position--length---)-> '-character-variable-name-' >--------------------------------------------------------------><
This built-in function produces a substring from the contents of the specified CL character variable or local data area. The substring begins at the specified starting position in the value and continues for the length specified. For example:
%SST(&TEST 5 3)
In this example, a portion of the variable &TEST is referenced. That position (or substring) is 3 characters long and begins with the fifth character position. If &TEST contains ABCDEFGHIJ, the resulting substring will be EFG.
CL variables can also be used to specify the starting position and the length values in the function. For example:
CHGVAR &X %SST(*LDA &B &C)
The value of the character variable named &X is to be replaced by the value in the job's local data area, starting at the position obtained from variable &B and continuing for the length specified by the value in &C.
RTVJOBA SWS(&JOBSWS) CHGVAR VAR(&CURSW4) VALUE(%SST(&JOBSWS 4 1))
In this example, the Retrieve Job Attributes (RTVJOBA) command is used to retrieve the current value of the job's eight job switches. The CHGVAR command is then used to extract the current value of the fourth job switch only and store it in the variable &CURSW4. If the value of the eight job switches retrieved in &JOBSWS is 10010000, the second 1 would be stored in &CURSW4.
The built-in function %SWITCH tests one or more of the eight job switches in the current job and returns a logical value of 1 or 0. If every job switch tested by %SWITCH has the value indicated, the result is a 1 (true); if any switch tested does not have the value indicated, the result is a 0 (false).
The 8-character mask is used to indicate which job switches are tested, and what value each switch is tested for. Each position in the mask corresponds with one of the eight job switches in a job. Position 1 corresponds with job switch 1, position 2 with switch 2, and so on. Each position in the mask can be specified as one of three values: 0, 1, or X.
The syntax of the switch built-in function is:
>>-&SWITCH(--)-------------------------------------------------><
If %SWITCH(0X111XX0) is specified, job switches 1 and 8 are tested for 0s, switches 3, 4, and 5 are tested for 1s, and switches 2, 6, and 7 are not tested. If each job switch contains the value (1 or 0 only) shown in the mask, the result of %SWITCH is true (1).
Function %SWITCH can be used in the Change Variable (CHGVAR) and If (IF) commands. On the CHGVAR command, it can be used in place of a logical variable in the VALUE parameter. On the IF command, it can be used in the COND parameter as the logical expression to be tested.
The following two examples show how the same mask can be used to control a branch in a program (the IF command), or to set the value of a variable (the CHGVAR command).
IF COND(%SWITCH(0X111XX0)) THEN(GOTO C) CHGVAR VAR(&A) VALUE(%SWITCH(0X111XX0))
If job switches 1, 3, 4, 5, and 8 respectively contain 0, 1, 1, 1, and 0 respectively when %SWITCH(0X111XX0) is specified in the IF command, the result is true and the program branches to the command having label C. If one or more of the switches tested do not have the values indicated in the mask, the result is false and the branch does not occur. If the same mask is used in the CHGVAR command and the result is true, the variable &A is set to a '1'; if the result is false, &A is set to a '0'. Note that &A must be declared as a logical variable.
Monitorable messages are those *ESCAPE, *STATUS, and *NOTIFY messages that can be issued by each CL command that can be used in a program. You can use this information to determine which messages you want to monitor for in your program.
Using the Monitor Message (MONMSG) CL command, you can monitor for one or more messages and then specify (on the MONMSG command) what action you want taken when any of those messages are issued by the commands(s) being monitored.
Documentation for each command contains a section that lists the monitorable
messages issued by the command. You can display documentation for a
command using the CL command finder.
If you have a V4R2 or later system, you can refer to the online help for an individual command to obtain its monitorable message information. To view the online command help on an iSeries(TM) computer, type the command name on a command line and press F1 (Help). The error message information follows the brief description of the purpose for the command.
Refer to Chapter 8 of the CL Programming
book for information concerning messages that are sent to the QSYSMSG message
queue.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.