CL Programming
You can define as many as 75 parameters for each command. To define
a parameter, you must use the PARM statement.
On the PARM statement, you specify the following:
- Name of the keyword for the parameter
- Whether or not the parameter is a key parameter
- Type of parameter value that can be passed
- Length of the value
- If needed, the default value for the parameter.
In addition, you must consider the following information when defining
parameters. (The associated PARM statement parameter is given in
parentheses.)
- Whether a value is returned by the command processing program
(RTNVAL). If RTNVAL (*YES) is specified, a return variable must be
coded on the command when it is called, if you want to have the value
returned. If no variable is specified for a RTNVAL(*YES) parameter, a
null pointer is passed to the command processing program.
- Whether the parameter is not to appear on the prompt to the user but is to
be passed to the command processing program as a constant (CONSTANT).
- Whether the parameter is restricted (RSTD) to specific values (specified
on the VALUES, SPCVAL, or SNGVAL parameter) or can include any value that
matches the parameter type, length, value range, and a specified
relationship.
- What the specific valid parameter values are (VALUES, SPCVAL, and
SNGVAL).
- What tests should be performed on the parameter value to determine its
validity (REL and RANGE).
- Whether the parameter is optional or required (MIN).
- How many values can be specified for a parameter that requires a simple
list (MIN and MAX).
- Whether unprintable data (any character with a value of hexadecimal
00 through 3F or FF can be entered for the
parameter value (ALWUNPRT).
- Whether a variable name can be entered for the parameter value
(ALWVAR).
- Whether the value is a program name (PGM).
- Whether the value is a data area name (DTAARA).
- Whether the value is a file name (FILE).
- Whether the value must be the exact length specified (FULL).
- Whether the length of the value should be given with the value
(VARY).
- Whether expressions can be specified for a parameter value (EXPR).
- Whether attribute information should be given about the value passed for
the parameter (PASSATR).
- Whether to pass a value to the command processing program or validity
checking program if the parameter being defined is not specified
(PASSVAL).
- Whether the case value is preserved or the case value is converted to
uppercase (CASE).
- Whether list within list displacements (LISTDSPL) are 2-byte or 4-byte
binary values.
- What the message identifier is or what the prompt text for the parameter
is (PROMPT).
- What valid values are shown in the possible choices field on the prompt
display (CHOICE).
- Whether the choice values are provided by a program (CHOICEPGM).
- Whether prompting for a parameter is controlled by another parameter
(PMTCTL).
- Whether values for a PMTCTL statement are provided by a program (for
parameters referred to in CTL keywords) (PMTCTLPGM).
- Whether the value is to be hidden in the job log or hidden when the
command is being prompted (DSPINPUT).
The name of the keyword you choose for a parameter should be descriptive of
the information being requested in the parameter value. For example,
USER for user name, CMPVAL for compare value, and OETYPE for order entry
type. The keyword can be as long as 10 alphanumeric characters, the
first of which must be alphabetic.
The basic parameter types are (parameter TYPE value given in
parentheses):
- Decimal (*DEC). The parameter value is a decimal number, which is
passed to the command processing program as a packed decimal value of the
length specified on the LEN parameter. Values specified with more
fractional digits than defined for the parameter are truncated.
- Logical (*LGL). The parameter value is a logical value,
'1' or '0', which is passed to the command processing
program as a character string of length 1 (F1 or
F0).
- Character (*CHAR). The parameter value is a character string, which
can be enclosed in apostrophes and which is passed to the command processing
program as a character string of the length specified on the LEN
parameter. The value is passed with its apostrophes removed, is
left-justified, and is padded with blanks.
- Name (*NAME). The parameter value is a character string that
represents a basic name. The maximum length of the name is 256
characters. The first character is alphabetic (A-Z), $, #, or
@. The remaining characters are the same as the first character,
but can also include the numbers 0 through 9, underscores (_), and periods
(.). The name can also be a string of characters that begin and
end with double quotation marks ("). The system passes the value to the
command processing program as a character string of the length specified in
the LEN parameter. The value is left-justified and padded with
blanks. Normally, you use the *NAME type for object names. If
you can enter a special value such as *LIBL or *NONE for the name parameter,
you must describe the special value on the SPCVAL parameter. Then, if
the display station user enters one of the allowed special values for the
parameter, the system bypasses the rules for name verification.
- Simple name (*SNAME). The parameter value is a character string
that follows the same naming rules as *NAME, except that no periods (.)
are allowed.
- Communications name (*CNAME). The parameter value is a character
string that follows the same naming rules as *NAME, except that no periods
(.) or underscores (_) are allowed.
- Path name (*PNAME). The parameter value is a character string,
which can be enclosed in apostrophes and which is passed to the command
processing program as a character string of the length specified on the LEN
parameter. The value is passed with its apostrophes removed, is
left-justified, and is padded with blanks.
- Generic name (*GENERIC). The parameter value is a generic name,
which ends with an asterisk (*). If the name does not end with an
asterisk, then the generic name is assumed to be a complete object
name. A generic name identifies a group of objects whose names all
begin with the characters preceding the asterisk. For example, INV*
identifies the objects whose names begin with INV, such as INV, INVOICE, and
INVENTORY. The generic name is passed to the command processing program
so that it can find the object names beginning with the characters in the
generic name.
- Date (*DATE). The parameter value is a character string that is
passed to the command processing program. The character string uses the
format cyymmdd (c = century digit, y = year,
m = month, d = day). The system sets the century
digit based on the year specified on the date parameter for the
command. If the specified year contained 4 digits, the system sets the
century digit to 0 for years that start with 19. The system sets the
century digit to 1 for years that start with 20. For years that are
specified with 2 digits, the system sets the century digit to 0 if yy equals a
number from 40 to 99. However, if yy equals a number from 00 through
39, the system sets the century digit to 1. The user must enter the
date on the date parameter of the command in the format that is specified by
the date format (DATFMT) job attribute. The date separator (DATSEP) job
attribute determines the optional separator character to use for entering the
date. Use the Change Job (CHGJOB) command to change the DATFMT and
DATSET job attributes . The program reads dates with 2-digit
years to be in the range of January 1, 1940, to December 31, 2039.
Dates with 4-digit years must be in the range of August 24, 1928, to May
9, 2071.
- Time (*TIME). The parameter value is a character string. The
system passes this string to the command processing program in the format
hhmmss (h = hour, m = minute, s =
second). The time separator (TIMSEP) job attribute determines the
optional separator to use for entering the time. Use the Change Job
(CHGJOB) command to change the TIMSEP job attribute.
- Hexadecimal (*HEX). The parameter value is a hexadecimal
value. The characters specified must be 0 through F. The value
is passed to the CPP as hexadecimal (EBCDIC) characters (2 hexadecimal digits
per byte), and is right adjusted and padded with zeros. If the value is
enclosed in apostrophes, an even number of digits is required.
- Zero elements (*ZEROELEM). The parameter value is considered to be
a list of zero elements for which no value can be specified in the
command. This parameter type is used to prevent a value from being
entered for a parameter that is a list even though the command processing
program (CPP) expects a value. For example, if two commands use the
same CPP, one command could pass a list for a parameter, and the other command
may not have any values to pass. The parameter for the second command
would be defined with TYPE(*ZEROELEM).
- Integer (*INT2 or *INT4). The parameter value is an integer that is
passed as a 2-byte or 4-byte signed binary number. CL does not support
a binary variable type. However, you can declare binary numbers in a CL
procedure or program as variables of TYPE(*CHAR) and process them with the
%BINARY built-in function.
- Unassigned integer (*UINT2 or *UINT4). The parameter value is an
integer that is passed as a 2-byte or 4-byte unsigned binary number. CL
does not support a binary variable type. However, you can declare
binary numbers in a CL procedure or program as variables of TYPE(*CHAR) and
process them with the %BINARY built-in function.
- Null (*NULL). The parameter value is a null pointer, which is
always passed to the command processing program as a place holder. The
only PARM keywords valid for this parameter type are KWD, MIN, and MAX.
- Command string (*CMDSTR). The parameter value is a command.
You can use CL variables to specify parameters in the command that are
specified in the *CMDSTR parameter. However, you cannot use them to
specify the entire *CMDSTR parameter. For example, "SBMJOB CMD(DSPLIB
LIB(&LIBVAR))" is valid in a CL Program or procedure, but "SBMJOB
CMD(&CMDVAR)" is not.
- Statement label. The statement label identifies the first of a
series of QUAL or ELEM statements that further describe the qualified name or
the mixed list being defined by this PARM statement.
The following parameter types are for IBM-supplied commands only.
- Expression (*X). The parameter value is a character string,
variable name, or numeric value. The value is passed as a numeric value
if it contains only digits, a plus or minus sign, and/or a decimal point;
otherwise, it is passed as a character string.
- Variable name (*VARNAME). The parameter value is a variable name,
which is passed to the command processing program as a character
string. The value is left-justified and is padded with blanks. A
variable is a name that refers to an actual data value during
processing. A variable name can be as long as 10 alphanumeric
characters (the first of which must be alphabetic) preceded by an ampersand
(&); for example, &PARM. If the name of your variable does
not follow the naming convention used on OS/400, you must enclose the name in
apostrophes.
- Command (*CMD). The parameter value is a command. For
example, the CL command IF has a parameter named THEN whose value must be
another command.
You can also specify a length (LEN parameter) for parameter values of the
following types. For parameter types of date or time, date is always 7
characters long and time is always 6 characters long. The following
shows the maximum length for each parameter type and the default length for
each parameter type for which you can specify a length.
Data Type
| Maximum Length
| Default Length
|
*DEC
| 24 (9 decimal positions)
| 15 (5 decimal positions)
|
*LGL
| 1
| 1
|
*CHAR
| 5000
| 32
|
*NAME
| 256
| 10
|
*SNAME
| 256
| 10
|
*CNAME
| 256
| 10
|
*GENERIC
| 256
| 10
|
*HEX
| 256
| 1
|
*X
| (256 24 9)
| (1 15 5)
|
*VARNAME
| 11
| 11
|
*CMDSTR
| 20K
| 256
|
*PNAME
| 5000
| 32
|
The maximum length that is shown here is the maximum allowed length for
these parameter types when the command runs. However, the maximum
length that is allowed for character constants in the command definition
statements is 32 characters. This restriction applies to the CONSTANT,
DFT, VALUES, REL, RANGE, SPCVAL, and SNGVAL parameters. There are
specific lengths for input fields available when prompting for a CL
command. The input field lengths are 1 through 12 characters and 17,
25, 32, 50, 80, 132, 256, and 512 characters. If a particular parameter
has a length that is not allowed,the input field displays with the next larger
field length. The prompter displays a 512-character input field
for parameters that can be longer than 512 characters.
If you are defining an optional parameter, you can define a value on the
DFT parameter to be used if the user does not enter the parameter value on the
command. This value is called a default value. The
default value must meet all the value requirements for that parameter (such as
type, length, and special values). If you do not specify a default
value for an optional parameter, the following default values are used.
Data Type
| Default Value
|
*DEC
| 0
|
*INT2
| 0
|
*INT4
| 0
|
*UINT2
| 0
|
*UINT4
| 0
|
*LGL
| '0'
|
*CHAR
| Blanks
|
*NAME
| Blanks
|
*SNAME
| Blanks
|
*CNAME
| Blanks
|
*GENERIC
| Blanks
|
*DATE
| Zeros ('F0')
|
*TIME
| Zeros ('F0')
|
*ZEROELEM
| 0
|
*HEX
| Zeros ('00')
|
*NULL
| Null
|
*CMDSTR
| Blanks
|
*PNAME
| Blanks
|
The following example defines a parameter OETYPE for a command to call an
order entry application.
PARM KWD(OETYPE) TYPE(*CHAR) RSTD(*YES) +
VALUES(DAILY WEEKLY MONTHLY) MIN(1) +
PROMPT('Type of order entry:')
The OETYPE parameter is required (MIN parameter is 1) and its value is
restricted (RSTD parameter is *YES) to the values DAILY, WEEKLY, or
MONTHLY. The PROMPT parameter contains the prompt text for the
parameter. Since no LEN keyword is specified and TYPE(*CHAR) is
defined, a length of 32 is the default.
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.