CL command parameter types

Different types of parameters are used in CL commands.

The basic parameter types are (parameter TYPE value given in parentheses) as follows:

  • 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 single quotation marks 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 single quotation marks removed, is left-aligned, 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-aligned 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 single quotation marks 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 single quotation marks removed, is left-aligned, 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 single quotation marks, 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. You can declare binary numbers in a CL procedure or program as variables of TYPE(*INT). You can also use TYPE(*CHAR) and process them with the %BINARY built-in function.
  • Unsigned integer (*UINT2 or *UINT4). The parameter value is an integer that is passed as a 2-byte or 4-byte unsigned binary number. You can declare binary numbers in a CL procedure or program as variables of TYPE(*UINT). You can also use 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, a decimal point, or all of them; 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-aligned 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 the IBM® i operating system, you must enclose the name in single quotation marks.
  • 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.