DCL

DCL (Declare CL Variable)

DCL Command syntax diagram

Purpose

The Declare CL Variable (DCL) command defines control language (CL) program variables used in CL programs. CL variables are used to store and update data and to receive parameters from another program on a call. CL variables are known by name only within the program that declares them. They cannot be used outside a CL program except when they are referred to by some commands (such as the DSPPGMVAR command) used for debugging programs. If a variable is declared, but not referred to by another command in a CL program, the variable is not included in the program when it is compiled. However, the value in the variable can be passed to another program as a parameter. Each DCL command defines the attributes of one CL variable and declares its name in the program in which it is used.
Each CL variable in a program must be identified by one of the two declare commands. The Declare File (DCLF) command declares CL variables for display device files and data areas. The DCL command declares all other CL variables.
Restriction: The DCL command is valid only within a CL program. All declare commands (COPYRIGHT, DCL, and DCLF) must follow the PGM (Program) command and must precede all other commands in the program. The three types of declare commands can be intermixed in any order.

Required Parameters

VAR

Specifies the name of the CL variable being declared in the CL program. The variable exists only within the program in which it is defined. It can be passed as a parameter on a call to another program, in which case it can be processed by the called program. The variable name must start with an ampersand (&).

TYPE

Specifies the type of value contained in the CL variable being declared. The value of the variable can be a character constant, a decimal constant, or a logical '1' or '0'. The value for this parameter cannot be specified by a CL variable. Specify one of the following types:
*DEC: A decimal variable that contains a packed-decimal value.
*CHAR: A character variable that contains a character string value.
*LGL: A logical variable that contains a logical value of either '1' or '0'.

Optional Parameters

LEN

Specifies the length of the CL variable being declared. If the variable is a decimal value, the number of decimal digits to the right of the decimal point can be optionally specified. The value for this LEN parameter cannot be specified by a CL variable. The maximum lengths and the defaults for each of the three types are shown in Table 1.
length: Specify the number of characters that the value in this CL variable can have. The length cannot be greater than the maximum for this type of variable.
decimal-positions: This option is valid only for decimal variables. The length of the value in the variable includes the number of decimal positions in the value. The maximum length of the decimal value is 15 digits, including the digits to the right of the decimal point. Up to nine decimal positions can be specified. If nine decimal positions are specified, the value to the left of the decimal point can never be greater than 999,999 because only 6 of the 15 digits are left for the integer value.
If a length (in digits) is specified for a decimal variable and the number of decimal positions is not specified, 0 decimal positions is assumed.

VALUE

Specifies the initial value assigned to the CL variable when it is declared in the program. The value must be of the type specified by the TYPE parameter. If no value is specified, a character variable is set to blanks, a decimal variable is set to a value of 0, and a logical variable is set to '0'. The value for the VALUE parameter cannot be specified by a CL variable.
If the name of the declared variable is specified on the PARM parameter of the PGM command in the same program in which the variable is declared, an initial value cannot be specified for the variable. In that case, the variable receives its value from the calling program.

Table 1. Variable Lengths

Type Maximum Length Default Length¹

Decimal 15 digits, 9 decimal positions 15 digits, 5 decimal positions

Character 9999 characters² 32 characters

Logical 1 character 1 character

¹

For decimal and character types, the default length is the same as the length of the initial value, if one is specified in the VALUE parameter.

²

The initial value (specified on the VALUE parameter) of a CL variable can be no greater than 3000 characters.

Examples for DCL
Example 1: Specifying the CL Variable Length
DCL &ABLE *DEC LEN(5 2)

This command declares a CL variable named &ABLE that contains a decimal value. The value can never be greater than 999.99 because LEN specifies up to 5 digits, of which two are to the right of the decimal point. Because the VALUE parameter was not specified, and it is a numeric value, &ABLE is set to a value of zero (000.00).
Example 2: Specifying a Logical Value
DCL &SWITCH *LGL

This command declares a CL variable named &SWITCH to contain a logical value. Because the type parameter specifies logical, the variable is one character long and it is set to '0'.
Example 3: Specifying Initial Value of CL Variable
DCL &FILNAM *CHAR VALUE(FILEA)

This command declares a CL variable named &FILNAM whose value is FILEA. Because the value contains 5 characters and the LEN parameter was not specified, the length of the variable is also 5 characters.
Error messages for DCL
None

Type	Maximum Length	Default Length¹
Decimal	15 digits, 9 decimal positions	15 digits, 5 decimal positions
Character	9999 characters²	32 characters
Logical	1 character	1 character
¹ For decimal and character types, the default length is the same as the length of the initial value, if one is specified in the VALUE parameter. ² The initial value (specified on the VALUE parameter) of a CL variable can be no greater than 3000 characters.