Control Language (CL) Concepts

CL programs

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:

CL character sets and values

This section explains the usage of the EBCDIC character sets, special characters, and IBM(R) -defined fixed values called predefined values.

See the following:

Character sets

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:

1
Lowercase letters (a through z) are accepted, but they are translated into the corresponding uppercase letters by the system except when they are included within a quoted character string or a comment, or they are specified for a value on a parameter that has the character (*CHAR) or the path name (*PNAME) attribute for its TYPE parameter and the mixed case (*MIXED) attribute for its CASE parameter in the command definition.

2
The underscore (__) is an alphanumeric connector that can be used in OS/400(R) CL to connect words or alphanumeric characters to form a name (for example, PAYLIB__01). This use of the underscore might not be valid in other high-level languages.

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.

Special character use

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:

Delimiters


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:

1
Because this character does not resolve in the online version of this book, b is used to represent a blank space only when the character cannot be clearly explained in another manner.

2
Valid only when the job date separator value specifies the same character.

3
Valid only when the job time separator value specifies the same character.

Symbolic operators

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 not symbol2
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:

1
Valid only when the job date separator value specifies the same character.

2
In some character sets, including the multinational character set, the character ^ replaces the not symbol character. Either ^ or *NOT can be used as the logical NOT operator in those character sets.

3
In some character sets, including the multinational character set, the character ! replaces the | character. Either ! or *OR can be used as the logical OR operator, and either || or *CAT can be used as the concatenation operator in those character sets.


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

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.

Naming within commands

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.

Start of changeSee the following for more information about naming within commands:

Allowable Characters for *NAME, *SNAME, and *CNAME


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:

 
1   The system converts lowercase letters to uppercase letters.
2   Double quotes can only be used for basic names (*NAME).
3   Both the first and last characters must be a double quote (").

*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:

  1. Periods (.) and underscores (_) cannot be used.
  2. For IBM commands, *CNAME is limited to 8 characters.

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 and document names

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:

Notes:

  1. In CL commands, folder path names must be enclosed in apostrophes to prevent the system from processing them as qualified (library/object) names. If an apostrophe is to be part of the name, it must be specified as two consecutive apostrophes.

  2. A number of CL commands act on either documents or folders, and some act on both. The abbreviation DLO (document library object) is used when referring to either a document or folder.

  3. In CL commands, folder and document names must be enclosed in apostrophes if they contain characters that are CL delimiters.

  4. The system does not recognize graphic characters; it recognizes only code points and uses the following assumptions:

    More information on code pages that are supported by OS/400 is in Chapter 5 of the Local Device Configuration Link to PDF 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.

Expressions in CL 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

Arithmetic expressions

Start of changeThe operands in an arithmetic expression must be decimal constants or decimal or integer CL variables. End of change 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.

Start of changeArithmetic 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. End of change 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.

Character string expressions

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:

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.

Example: 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:


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:

Relational 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 (=, >, <, >=, <=, not symbol=, not symbol>, not symbol<) 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 ' ')

Logical expressions

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 not symbol) 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 in expressions

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, =).

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 symbol2
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 symbol=2
Not equal Relational operator
*NG not symbol>2
Not greater than Relational operator
*NL not symbol<2
Not less than Relational operator
Notes:

1
In some national character sets and in the multinational character set, the character | (hexadecimal 4F) is replaced by the character ! (exclamation point). Either ! or *OR can be used as the OR operator and either || or *CAT, !> or *BCAT, and !< or *TCAT can be used for concatenation in those character sets.

2
In some national character sets and in the multinational character set, the character not symbol (hexadecimal 5F) is replaced by the character *. Either * or *NOT can be used as the NOT operator in those character sets.

Priority of operators when evaluating expressions

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, not symbol
2 * , /
3 +, - (when used between two operands)
4 *CAT, ||, *BCAT, |>, *TCAT, |<
5 *GT, *LT, *EQ, *GE, *LE, *NE, *NG, *NL, >, <, =, >=, <=, not symbol=, not symbol>, not symbol<
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.

Built-in functions for CL

CL provides the following built-in functions:

%BINARY

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:

Sample %BINARY syntax

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.

%SUBSTRING

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.

Sample %SUBSTRING syntax

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.

%SWITCH

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.

0
The corresponding job switch is tested for a 0 (off).

1
The corresponding job switch is tested for a 1 (on).

X
The corresponding job switch is not tested.

 
The value in the switch does not affect the result of %SWITCH.

Sample %SWITCH syntax

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.

Monitoring messages

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.

Start of changeDocumentation 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. End of change

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 Link to PDF book for information concerning messages that are sent to the QSYSMSG message queue.


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