CICS command argument values

The data associated with a command option is called its argument. Each type of argument can contain different data types; some arguments return information from CICS® to the program and others are set by the program.

Options in a CICS command can take the following argument values:
  • data-value
  • data-area
  • cvda (CICS-value data area)
  • ptr-value
  • ptr-ref
  • name
  • filename
  • systemname
  • label
  • hhmmss
For AMODE(64) programs only, options in a CICS command can also take the following argument values:
  • data-area64
  • ptr-value64
  • ptr-ref64

Data areas and data values

Data areas and data values are the basic argument types. The difference between them is the direction in which information flows when a task executes a command. A data-value is always, can only be, a sender; it conveys data to CICS that CICS uses to process the command. A data-area is a receiver; CICS uses it to return information to the caller. A data-area can also be a sender, for example when the data to convey to CICS is variable length (as in FROM), or where a field is used both for input and output.

COBOL argument values

The argument values can be replaced as follows:
  • data-value can be replaced by any COBOL data name of the correct data type for the argument, or by a constant that can be converted to the correct type for the argument. The following table shows how to define the correct data type:
    Data type COBOL definition
    Halfword binary PIC S9(4) COMP
    Fullword binary PIC S9(8) COMP
    Doubleword unsigned binary PIC 9(18) COMP
    Character string PIC X(n) where n is the number of bytes
    UTF-8 character string PIC X(n) where n is the number of bytes
  • data-area can be replaced by any COBOL data name of the correct data type for the argument. The following table shows how to define the correct data type:
    Data type COBOL definition
    Halfword binary PIC S9(4) COMP
    Fullword binary PIC S9(8) COMP
    Doubleword unsigned binary PIC 9(18) COMP
    Character string PIC X(n) where n is the number of bytes
    UTF-8 character string PIC X(n) where n is the number of bytes

    Where the data type is unspecified, data-area can refer to an elementary or group item.

  • cvda is described in CICS-value data areas (cvdas).
  • ptr-value can be replaced by a pointer variable or ADDRESS special register.
  • ptr-ref can be replaced by a pointer variable or ADDRESS special register.
  • name can be replaced by either of the following values:
    • A character string specified as an alphanumeric literal. If this string is shorter than the required length, it is padded with blanks.
    • A COBOL data area with a length equal to the required length for the name. The value in data-area is the name to be used by the argument. If data-area is shorter than the required length, the excess characters are undefined, which might cause unpredictable results.

    filename, as used in FILE(filename), specifies the name of the file. The name must contain 1–8 characters from the range A–Z, 0–9, $, @, and #.

    systemname, as used in SYSID(systemname), specifies the name of the system to which the request is directed. The name must contain 1–4 characters from the range A–Z, 0–9, $, @, and #.

  • label can be replaced by any COBOL paragraph name or a section name.
  • hhmmss can be replaced by a decimal constant or by a data name of the form PIC S9(7) COMP-3. The value must be of the form 0HHMMSS+ where:
    HH
    Represents hours from 00 through 99.
    MM
    Represents minutes from 00 through 59.
    SS
    Represents seconds from 00 through 59.

In COBOL, you do not need to code the LENGTH option unless you want the program to read or write data of a length that is different from that of the referenced variable.

C argument values

The argument values can be replaced as follows:
  • data-value can be replaced by any C expression that can be converted to the correct data type for the argument. The following table shows how to define the correct data type:
    Data type C definition
    Halfword binary short int
    Fullword binary long int
    Doubleword binary char[8]
    Character string char[n] where n is the number of bytes
    UTF-8 character string char[n] where n is the number of bytes

    data-value includes data-area as a subset.

  • data-area can be replaced by any C data reference that has the correct data type for the argument. The following table shows how to define the correct data type:
    Data type C definition
    Halfword binary short int
    Fullword binary long int
    Doubleword binary char[8]
    Character string char[n] where n is the number of bytes
    UTF-8 character string char[n] where n is the number of bytes

    If the data type is unspecified, data-area can refer to a scalar data type, array, or structure. The reference must be to contiguous storage.

  • cvda is described in CICS-value data areas (cvdas).
  • ptr-value (which includes ptr-ref as a subset) can be replaced by any C expression that can be converted to an address.
  • ptr-ref can be replaced by any C pointer type reference.
  • name can be replaced by either of the following values:
    • A character string in double quotation marks (that is, a literal constant).
    • A C expression or reference whose value can be converted to a character array with a length equal to the maximum length allowed for the name. The value of the character array is the name to be used by the argument.

    filename, as used in FILE(filename), specifies the name of the file. The name must have 1–8 characters from the range A–Z, 0–9, $, @, and #.

    systemname, as used in SYSID(systemname), specifies the name of the system to which the request is directed. The name must have 1–4 characters from the range A–Z, 0–9, $, @, and #.

  • label is not supported in the C language.
  • hhmmss can be replaced by an integer constant; otherwise the application is responsible for ensuring that the value passed to CICS is in packed decimal format. The language does not provide a packed decimal type.
    HH
    Represents hours from 00 through 99.
    MM
    Represents minutes from 00 through 59.
    SS
    Represents seconds from 00 through 59.

Many commands involve the transfer of data between the application program and CICS. In most cases, if SET is used, the LENGTH option must be specified; the syntax of each command and its associated options show whether this rule applies.

PL/I argument values

The argument values can be replaced as follows:
  • data-value can be replaced by any PL/I expression that can be converted to the correct data type for the argument. The following table shows how to define the correct data type:
    Data type PL/I definition
    Halfword binary FIXED BIN(15)
    Fullword binary FIXED BIN(31)
    Doubleword binary CHAR (8)
    Character string CHAR(n) where n is the number of bytes
    UTF-8 character string CHAR(n) where n is the number of bytes

    data-value includes data-area as a subset.

  • data-area can be replaced by any PL/I data reference that has the correct data type for the argument. The following table shows how to define the correct data type:
    Data type PL/I definition
    Halfword binary FIXED BIN(15)
    Fullword binary FIXED BIN(31)
    Doubleword binary CHAR (8)
    Character string CHAR(n) where n is the number of bytes
    UTF-8 character string CHAR(n) where n is the number of bytes

    If the data type is unspecified, data-area can refer to an element, array, or structure; for example, FROM(P–>STRUCTURE) LENGTH(LNG). The reference must be to connected storage.

    The data area must also have the correct PL/I alignment attribute: ALIGNED for binary items, and UNALIGNED for strings.

    If you use a varying data string without an explicit length, the data passed begins with a two-byte length field, and its length is the maximum length declared for the string. If you explicitly specify a length in the command, the data passed has this length; that is, the two-byte length field followed by data up to the length you specified.

  • cvda is described in CICS-value data areas (cvdas).
  • ptr-value (which includes ptr-refas a subset) can be replaced by any PL/I expression that can be converted to POINTER.
  • ptr-ref can be replaced by any PL/I reference of type POINTER ALIGNED.
  • name can be replaced by either of the following values:
    • A character string in single quotation marks (that is, a literal constant).
    • A PL/I expression or reference whose value can be converted to a character string with a length equal to the maximum length allowed for the name. The value of the character string is the name to be used by the argument.

    filename, as used in FILE(filename), specifies the name of the file. The name must have 1-8 characters from the range A–Z, 0–9, $, @, and #.

    systemname, as used in SYSID(systemname), specifies the name of the system to which the request is directed. The name must have 1-4 characters from the range A–Z, 0–9, $, @, and #.

  • label can be replaced by any PL/I expression whose value is a label.
  • hhmmss can be replaced by a decimal constant or an expression that can be converted to a FIXED DECIMAL(7,0). The value must be of the form 0HHMMSS+ where:
    HH
    Represents hours from 00 through 99.
    MM
    Represents minutes from 00 through 59.
    SS
    Represents seconds from 00 through 59.

If the UNALIGNED attribute is added to the ENTRY declarations generated by the CICS translator by a DEFAULT DESCRIPTORS statement, data-area or pointer-reference arguments to CICS commands must also be UNALIGNED. Similarly for the ALIGNED attribute, data-area or pointer-reference arguments must be ALIGNED.

Many commands involve the transfer of data between the application program and CICS. In most cases, the length of the data to be transferred must be provided by the application program. However, if a data area is specified as the source or target, it is not necessary to provide the length explicitly, because the command-language translator generates a default length value of either STG(data-area) or CSTG(data-area), as appropriate.

Assembler-language argument values for AMODE(24) and AMODE(31) programs

In general, an argument can be either the address of the data or the data itself (in assembler language terms, either a relocatable expression or an absolute expression).

A relocatable expression must not contain unmatched brackets (outside quotation marks) or unmatched quotation marks (apart from length-attribute references). If this rule is obeyed, any expression can be used, including literal constants, such as =AL2(100), forms such as 20(0,R11), and forms that use the macro-replacement facilities.

An absolute expression must be a single term that is either a length-attribute reference, or a self-defining constant.

Use care with equated symbols, which should be used only when referring to registers (pointer references). For example, if an equated symbol is used for a length, it is treated as the address of the length and an unpredictable error occurs.

For AMODE(24) and AMODE(31) assembler language programs, the argument values can be replaced as follows:
  • data-value can be replaced by a relocatable expression that is an assembler-language reference to data of the correct type for the argument, or by a constant of the correct type for the argument.
  • data-area can be replaced by a relocatable expression that is an assembler-language reference to data of the correct type for the argument.
  • cvda is described in CICS-value data areas (cvdas).
  • ptr-value can be replaced by an absolute expression that is an assembler-language reference to a register.
  • ptr-ref can be replaced by an absolute expression that is an assembler-language reference to a register.
  • name can be replaced either by a character string in single quotation marks, or by an assembler-language language relocatable expression reference to a character string. The length is equal to the maximum length allowed for the name. The value of the character string is the name to be used by the argument.

    filename, as used in FILE(filename), specifies the name of the file. The name must have 1–8 characters from the range A–Z, 0–9, $, @, and #.

    systemname, as used in SYSID(systemname), specifies the name of the system to which the request is directed. The name must have 1–4 characters from the range A–Z, 0–9, $, @, and #.

  • label refers to a destination address to which control is transferred. It can be replaced by the label of the destination instruction or by the label of an address constant for the destination. This constant must not specify a length.

    You can also use the expression =A(dest) where dest is a relocatable expression denoting the destination.

    For example, the following commands are equivalent: 
    HANDLE CONDITION ERROR(DEST)
HANDLE CONDITION ERROR(ADCON)
HANDLE CONDITION ERROR(=A(DEST))
⋮
DEST  BR 14
ADCON DC A(DEST)
  • hhmmss can be replaced by a self-defining decimal constant, or an assembler-language reference to a field defined as PL4. The value must be of the form 0HHMMSS+ where:
    HH
    Represents hours from 00 through 99
    MM
    Represents minutes from 00 through 59
    SS
    Represents seconds from 00 through 59
Many commands involve the transfer of data between the application program and CICS. In most cases, the application program must provide the length of the data to be transferred. However, if a data area is specified as the source or target, it is not necessary to provide the length explicitly, because the command-language translator generates a default length. For example: 
xxx DC CL8
 .
 .
EXEC CICS ... LENGTH(L'xxx)

Assembler-language argument values for AMODE(64) programs

In general, an argument can be either the address of the data or the data itself (in assembler language terms, either a relocatable expression or an absolute expression).

A relocatable expression must not contain unmatched brackets (outside quotation marks) or unmatched quotation marks (apart from length-attribute references). If this rule is obeyed, any expression can be used, including literal constants, such as =AL2(100), forms such as 20(0,R11), and forms that use the macro-replacement facilities.

An absolute expression must be a single term that is either a length-attribute reference, or a self-defining constant.

Use care with equated symbols, which should be used only when referring to registers (pointer references). For example, if an equated symbol is used for a length, it is treated as the address of the length and an unpredictable error occurs.

For non-Language Environment® (LE) AMODE(64) assembler language programs, argument values can be replaced as follows:
  • data-value can be replaced by a relocatable expression that is an assembler-language reference to data of the correct type for the argument, or by a constant of the correct type for the argument.
  • data-area can be replaced by a relocatable expression that is an assembler-language reference to data of the correct type for the argument.
  • data-area64 can be replaced by a relocatable expression that is an assembler-language 64-bit reference to data of the correct type for the argument.
  • cvda is described in CICS-value data areas (cvdas).
  • ptr-value can be replaced by an absolute expression that is an assembler-language reference to a register.
  • ptr-value64 can be replaced by an absolute expression that is an assembler-language 64-bit reference to a register.
  • ptr-ref can be replaced by an absolute expression that is an assembler-language reference to a register.
  • ptr-ref64 can be replaced by an absolute expression that is an assembler-language 64-bit reference to a register.
  • name can be replaced either by a character string in single quotation marks, or by an assembler-language language relocatable expression reference to a character string. The length is equal to the maximum length allowed for the name. The value of the character string is the name to be used by the argument.

    filename, as used in FILE(filename), specifies the name of the file. The name must have 1–8 characters from the range A–Z, 0–9, $, @, and #.

    systemname, as used in SYSID(systemname), specifies the name of the system to which the request is directed. The name must have 1–4 characters from the range A–Z, 0–9, $, @, and #.

  • hhmmss can be replaced by a self-defining decimal constant, or an assembler-language reference to a field defined as PL4. The value must be of the form 0HHMMSS+ where:
    HH
    Represents hours from 00 through 99
    MM
    Represents minutes from 00 through 59
    SS
    Represents seconds from 00 through 59

label is not supported for AMODE(64) programs.

Many commands involve the transfer of data between the application program and CICS. In most cases, the application program must provide the length of the data to be transferred. However, if a data area is specified as the source or target, it is not necessary to provide the length explicitly, because the command-language translator generates a default length. For example: 
xxx DC CL8
 .
 .
EXEC CICS ... LENGTH(L'xxx)