DCL — Declare CL Variable
Contents
Summary
The DCL command is used in CLP programs to declare the definition for a program variable. Such variables may either be to receive parameter values passed to the CLP program, for work variables that are only used within the CLP program, or for variables that are to be passed to other commands and programs called by the CLP program.
Command definition
DCL VAR() TYPE() STG() LEN() VALUE() +
BASPTR() DEFVAR() ADDRESS()
Note: Some of these parameters were added at subsequent release levels and the values for these parameters also changed at subsequent release levels. Some parameters are mutually exclusive depending on which parameters and their values are specified.
Parameters
CL variable name (VAR)
This is the name of the CL variable and may be up to 10 characters in length — not including the required ampersand (&) prefix.
Type (TYPE)
This is the data type for the CL variable — as follows.
| Keyword | Data type |
|---|---|
| *CHAR | A variable with a character string value. |
| *DEC | A variable with a packed decimal value. |
| *LGL | A variable with a Boolean logical value of '0' (false) or '1' (true). |
| *PTR | A variable with an address pointer value. |
| *INT | A variable with a signed binary value. |
| *UINT | A variable with an unsigned binary value. |
Storage (STG)
This is the storage type for the variable — as follows.
| Keyword | Storage type |
|---|---|
| *AUTO | The variable's storage is automatically allocated. |
| *BASED | The variable's storage is based on the storage address of another variable. The BASPTR parameter must be specified for this variable. |
| *DEFINED | The variable's storage is provided by a variable that has already been defined. The DEFVAR parameter must be specified for this variable. |
Length of variable (LEN)
This is the length for the variable. The value for this parameter is either the number of characters (up to 32,767), bytes, or the total number of digits (left and right of the implied decimal point, up to 15) that can be contained in the variable. If an integer variable, the number of bytes must be 2, 4, or 8 (ILE, only). If a decimal variable, a second value may be specified that is the number of digits (up to 9) to the right of the implied decimal point (the default is zero if not specified).
Note: Pointer variables have a default fixed length of 16 bytes and this parameter cannot be specified.
Initial value (VALUE)
This is an optional initial value for the variable. By default, character variables are blank, numeric variables are zero, logical variables are '0', and pointer variables are *NULL. Incoming parameter variables cannot have an initial value specified because they receive their value from the calling program.
Basing pointer variable (BASPTR)
The value for this parameter must be the CL variable name of a pointer variable.
Defined on (DEFVAR)
The first value for this variable is the name of the defined variable over which this variable will be defined — based on the second value for this parameter. The second value is this variable's starting position in the defined variable (where one (1) indicates the beginning of that CL variable).
Address (ADDRESS)
This is an optional initial address for a pointer variable — which may be specified as *NULL. The value for this parameter may be the name of another CL variable with a second value that is an offset from that variable (where zero (0) indicates the beginning of that CL variable).
Example data structure defined in CL
Data structures can now easily be handled in CLP programs by using variables whose storage is defined over the top of (overlayed on) other CL variables. The following shows the variable definitions necessary not only to create such a data structure but to also have an array of such data structures overlayed on a single CL variable.
/******************************************************************************/
/* Data Structure for a message information array passed between programs. */
/*----------------------------------------------------------------------------*/
/* &MSG_INFID is the message id from the message file indicated below; */
/* &MSG_INFTPE is the type (*DIAG, *ESCAPE, etc.) for the indicated message; */
/* &MSG_INFFLE is the message file for the indicated message id; */
/* &MSG_INFFLB is the library for the indicated message file; */
/* &MSG_INFDLN is the length of the following substitution data; and, */
/* &MSG_INFDTA is the substitution data for the indicated message id. */
/******************************************************************************/
DCL VAR(&MSGINFO) TYPE(*CHAR) LEN(30390) /* array with 10 elements */
DCL VAR(&MSGINFP) TYPE(*PTR) ADDRESS(&MSGINFO)
DCL VAR(&MSGINFE) TYPE(*CHAR) STG(*BASED) LEN(3039) BASPTR(&MSGINFP)
DCL VAR(&MSG_INFID) TYPE(*CHAR) LEN(7) STG(*DEFINED) DEFVAR(&MSGINFE 1)
DCL VAR(&MSG_INFTPE) TYPE(*CHAR) LEN(10) STG(*DEFINED) DEFVAR(&MSGINFE 8)
DCL VAR(&MSG_INFFLE) TYPE(*CHAR) LEN(10) STG(*DEFINED) DEFVAR(&MSGINFE 18)
DCL VAR(&MSG_INFFLB) TYPE(*CHAR) LEN(10) STG(*DEFINED) DEFVAR(&MSGINFE 28)
DCL VAR(&MSG_INFDLN) TYPE(*UINT) LEN(2) STG(*DEFINED) DEFVAR(&MSGINFE 38)
DCL VAR(&MSG_INFDTA) TYPE(*CHAR) LEN(3000) STG(*DEFINED) DEFVAR(&MSGINFE 40)
For comparison, the following is the same data structure array defined in RPG free-format.
dcl-ds MsgInfo dim(10) qualified;
Id char(7);
Type char(10);
File char(10);
FLib char(10);
Data varchar(3000);
end-ds;
