Variables in CL commands
A variable is a named changeable value that can be accessed or changed by referring to its name.
A CL source program consists of CL commands. Each command consists of a command name, parameter keyword names, and parameter values.
Parameter values can be expressed as variables, constants, or expressions.
Variables can be used as substitutes for most parameter values on CL commands.
When a CL variable is specified as a parameter value and the command containing it is run, the value of the variable is used as the parameter value.
Every time the command is run, a different value can be substituted for the variable.
Variables and expressions can be used as parameter values only in CL procedures and programs.
Variables are not stored in libraries, and they are not objects. Their values are destroyed when the program or procedure that contains them is no longer active.
Declaring variables to a CL program or procedure
All variables must be declared (defined) to the CL program or procedure before they can be used by the program or procedure.
There are two ways of declaring variables:
Declare variable. Defining it is accomplished using the Declare CL Variable (DCL) command and consists of defining the attributes of the variable. These attributes include type, length, and initial value.
DCL VAR(&AREA) TYPE(*CHAR) LEN(4) VALUE(BOOK)
Declare file. If your CL program or procedure uses a file, you must specify the name of the file in the FILE parameter on the Declare File (DCLF) command.
DCLF FILE(MCGANN/GUIDE)
Rules for using the Declare CL Variable command
In its simplest form, the Declare CL Variable (DCL) command has the following parameters.
When you use a DCL command, you must use the following rules:
1. The CL variable name must begin with an ampersand (&) followed by as many as 10 characters. The first character following the & must be alphabetic and the remaining characters alphanumeric. For example, &PART.
2. The CL variable value must be one of the following:
– A character string as long as 5000 characters.
– A packed decimal value totaling up to 15 digits with as many as 9 decimal positions.
– A logical value '0' or '1', where '0' can mean off, false, or no, and '1' can mean on, true, or yes. A logical variable must be either '0' or '1'.
– An integer value of two, four, or eight bytes.
– A pointer value which can hold the location of data in storage.
3. If you do not specify an initial value, the following is assumed:
– '0' for decimal variables.
– Blanks for character variables.
– '0' for logical variables.
– '0' for integer variables.
– Null for pointer variables
4. Declare the parameters as variables in the program DCL statements.
Uses for based variables
Based variables can be used to map variables passed to the program or manipulate arrays of values.
The basing pointer must be set using the ADDRESS keyword on the Declare (DCL Command) or with the %ADDRESS built-in function before being used.
After the basing pointer is set, the variables will work like local variables.
In the following example, the basing pointer &PTR is declared to be equal to the address of &AUTO.The variable &BASED then has the value of the first 10 bytes addressed by the pointer variable &PTR. Later in the procedure, the value of variable &BASED is checked for equality against the first 10 bytes of variable &AUTO. If the values are the same, meaning pointer &PTR addresses the first byte of &AUTO, the pointer offset is changed to address byte 11 of variable &AUTO. Now variable &BASED has a value equal to bytes 11-20 of variable &AUTO.
PGM
DCL &AUTO *CHAR 20
DCL &PTR *PTR ADDRESS(&AUTO)
DCL &BASED *CHAR 10 STG(*BASED) BASPTR(&PTR)
:
IF COND(%SST(&AUTO 1 10) *EQ &BASED) +
THEN(CHGVAR %OFS(&PTR) (%OFS(&PTR) + 10))
:
ENDPGM
Uses for defined variables
Defined variables make it easy to manage complex data structures in control language (CL) by eliminating the need to substring values out of a large variable.
Defined variables can be used to map different parts of the defined on variable or the same part of a given variable in different ways.
In the following example, the variable &OBJNAME is equal to the first 10 bytes of &OBJECT and the variable &LIBNAME is equal to the last 10 bytes of &OBJECT. Using the defined variables &OBJNAME and &LIBNAME improves the readability of the code and makes it easier to work with. The variable &OBJECT provides the storage for both the &LIBNAME and &OBJNAME variables.
PGM
DCL &OBJECT *CHAR 20
DCL &OBJNAME *CHAR 10 STG(*DEFINED) DEFVAR(&OBJECT)
DCL &LIBNAME *CHAR 10 STG(*DEFINED) DEFVAR(&OBJECT 11)
:
IF COND(&LIBNAME *EQ ’*LIBL ’) +
THEN(...))
:
ENDPGM
This example shows how a defined variable can be used to change values in a variable.
PGM
DCL &MESSAGE *CHAR 25 VALUE(’LIBRARY NNN IS XXXXXXXXXX’)
DCL &SEQUENCE *CHAR 3 STG(*DEFINED) DEFVAR(&MESSAGE 9)
DCL &MSGLIBN *CHAR 10 STG(*DEFINED) DEFVAR(&MESSAGE 16)
DCL &COUNTER *INT 2
DCL &LIBL *CHAR 165
DCL &PTR *PTR ADDRESS(&LIBL)
DCL &LIBLNAME *CHAR 10 STG(*BASED) BASPTR(&PTR)
:
RTVJOBA SYSLIBL(&LIBL)
CHGVAR &COUNTER 0
DOFOR &COUNTER FROM(1) TO(15)
IF (&LIBLNAME *EQ ’ ’) THEN(LEAVE)
CHGVAR &SEQUENCE &COUNTER
CHGVAR &MSGLIBN &LIBLNAME
SNDPGMMSG MSGID(CPF9898) MSGF(QSYS/QCPFMSG) MSGDTA(&MESSAGE)
CHGVAR %OFS(&PTR) (%OFS(&PTR) + 11)
ENDDO
:
ENDPGM
Variables to use for specifying a list or qualified name
The value on a parameter can be a list. For example, the Change Library List (CHGLIBL) command requires a list of libraries on the LIBL parameter, each separated by blanks.
The elements in this list can be variables: CHGLIBL LIBL(&LIB1 &LIB2 &LIB3)
When variables are used to specify elements in a list, each element must be declared separately:
DCL VAR(&LIB1) TYPE(*CHAR) LEN(10) VALUE(QTEMP)
DCL VAR(&LIB2) TYPE(*CHAR) LEN(10) VALUE(QGPL)
DCL VAR(&LIB3) TYPE(*CHAR) LEN(10) VALUE(DISTLIB)
CHGLIBL LIBL(&LIB1 &LIB2 &LIB3)
Variable elements cannot be specified in a list as a character string.
Cases of characters in variables
There are restrictions on the cases used for characters in CL variables.
Reserved values, such as *LIBL, that can be used as variables must always be expressed in uppercase letters.
DCL VAR(&LIB) TYPE(*CHAR) LEN(10) VALUE(’*LIBL’)
DLTPGM &LIB/MYPROG;
However, it would be incorrect to specify the VALUE parameter this way:
DCL VAR(&LIB) TYPE(*CHAR) LEN(10) VALUE(’*libl’)
Variables that replace parameter values
CL source program that substitutes a character variable for the JOBSEP value.
PGM
DCL &NRESP *CHAR LEN(6)
DCL &SEP *CHAR LEN(4)
DCL &FILNAM *CHAR LEN(10)
DCL &FILLIB *CHAR LEN(10)
DCLF.....
.
.
.
LOOP: SNDRCVF.....
IF (&SEP *EQ IGNR) GOTO END
ELSE IF (&SEP *EQ NONE) CHGVAR &NRESP ’0’
ELSE IF (&SEP *EQ NORM) CHGVAR &NRESP ’1’
ELSE IF (&SEP *EQ SAME) CHGVAR &NRESP ’*SAME’
CHGOUTQ OUTQ(&FILLIB/&FILNAM) JOBSEP(&NRESP)
GOTO LOOP
END: RETURN
ENDPGM
Changing the value of a variable
You can change the value of a CL variable using the Change Variable (CHGVAR) command.
The value can be changed:
CHGVAR VAR(&INVCMPLT) VALUE(0)
CHGVAR &INVCMPLT 0
CHGVAR VAR(&A) VALUE(&B)
CHGVAR &A &B
CHGVAR VAR(&A) VALUE(&A + 1)
CHGVAR &A (&A + 1)
CHGVAR VAR(&A) VALUE(%SST(&B 1 5))
CHGVAR VAR(&A) VALUE(%CHECKR(’*’ &B)
CHGVAR VAR(&A) VALUE(%TRIMR(&B ’*’))
Writing comments in CL programs or procedures
To write comments or add comments to commands in your CL programs or procedures, use the character pairs /* and */.
The comment is written between these symbols.