CICS command argument values

The parenthesized argument values that follow options in a CICS® command are specified as follows:

  • data-value
  • data-area
  • cvda (CICS-value data area)
  • ptr-value
  • ptr-ref
  • name
  • label
  • hhmmss
  • filename
  • systemname

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, and exclusively 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. Note that a data-area can also be a sender, for example when the data to be conveyed 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 data type can be specified as one of the following:
    • 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
  • “data-area” can be replaced by any COBOL data name of the correct data type for the argument. The data type can be specified as one of the following:
    • 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

    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).
  • Start of change“ptr-value” can be replaced by a pointer variable or ADDRESS special register.End of change
  • Start of change“ptr-ref” can be replaced by a pointer variable or ADDRESS special register.End of change
  • “name” can be replaced by either of the following:
    • A character string specified as an alphanumeric literal. If this 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 lead to unpredictable results.

    “filename”, as used in FILE(filename), specifies the name of the file. It has 1–8 characters from A–Z, 0–9, $, @, and #.

    “systemname”, as used in SYSID(systemname), specifies the name of the system the request is directed to. It has 1–4 characters from 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, there is no need to code the LENGTH option unless you want the program to read or write data of a length 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 data type can be specified as one of the following:
    • Halfword binary — short int
    • Fullword binary — long int
    • Doubleword binary — char[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 data type can be specified as one of the following:
    • Halfword binary — short int
    • Fullword binary — long int
    • Doubleword binary — char[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:
    • 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. It has 1–8 characters from A–Z, 0–9, $, @, and #.

    “systemname”, as used in SYSID(systemname), specifies the name of the system the request is directed to. It has 1–4 characters from 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, the LENGTH option must be specified if SET is used; the syntax of each command and its associated options show whether or not 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 data type can be specified as one of the following:
    • 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

    “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 data type can be specified as one of the following:
    • 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

    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 two length bytes, 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 length bytes followed by data up to the length you specified.

  • “cvda” is described in CICS-value data areas (cvdas).
  • “ptr-value” (which includes “ptr-ref” as 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:
    • 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. It has 1–8 characters from A–Z, 0–9, $, @, and #.

    “systemname”, as used in SYSID(systemname), specifies the name of the system the request is directed to. It has characters from 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

In general, an argument may 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.

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

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 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. It has 1–8 characters from A–Z, 0–9, $, @, and #.

    “systemname”, as used in SYSID(systemname), specifies the name of the system the request is directed to. It has 1–4 characters from 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 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.

For example:
xxx DC CL8
 .
 .
EXEC CICS ... LENGTH(L'xxx)