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).
“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:
- 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)