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.
- data-value
- data-area
- cvda (CICS-value data area)
- ptr-value
- ptr-ref
- name
- filename
- systemname
- label
- hhmmss
- 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
- 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
- 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
- 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.
- 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
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.
- 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.
xxx DC CL8
.
.
EXEC CICS ... LENGTH(L'xxx)