The format of an API command when issued through the command-level interface is EXECUTE CPSM (or EXEC CPSM)
followed by the name of the required command and possibly by one or more options,
as follows:
EXEC CPSM command option(arg)....
where:
- command
- Describes the operation required (for example, CONNECT).
- option
- Describes any of the required or optional facilities available with
each command. Some options are followed by an argument in parentheses. You
can write options (including those that require arguments) in any order.
- arg
- Which is short for argument, is a value such as data-value or data-ref. A data-value can be a constant. This means that an
argument that sends data to CICSPlex® SM is generally a data-value. An
argument that receives data from CICSPlex SM must be a data-ref.
Here is an example of an EXEC CPSM command:
EXEC CPSM CONNECT
USER(JONES) VERSION(0310)
CONTEXT(EYUPLX01) SCOPE(EYUCSG01)
THREAD(THRDTKN)
RESPONSE(RESPVAR) REASON(REASVAR)
You must add an end-of-command delimiter that
is valid for the programming language you are using. In COBOL programs, for
example, the end-of-command delimiter is an END-EXEC statement. In PL/I and C programs, the delimiter is
a semicolon (;).
For the command-level interface, the parenthesized argument values that follow options in
an API command are specified as follows:
- data-value
- A sending argument used to pass data from your program to CICSPlex SM.
The data you pass can be fullword binary data, fixed or variable length character
data, or unspecified. If the data type is unspecified, CICSPlex SM assumes a composite
data structure made up of multiple fields of varying data types. The
argument can be in one of these forms:
- Variable name
- Self-defining term
- Expression.
data-value includes data-ref as a subset.
- data-ref
- A receiving (or sending and receiving) argument used primarily to pass
data from CICSPlex SM to your program.
The data can be any of the same types
allowed for data-value arguments. However, the argument must be a
named variable.
In some cases, you can use a data-ref argument
to provide input to CICSPlex SM before CICSPlex SM returns its output to you (the COUNT
option on the FETCH command is an example of this).
- data-area
- A sending or receiving argument used to identify a buffer that contains
data. A data-area argument can be considered a data-ref argument
with an unspecified data type. A data-area cannot be defined by a
self-defining term or expression; it must be a named variable.
- ptr-ref
- A receiving argument used to pass pointer values from CICSPlex SM to your
program.
A ptr-ref argument is a special form of data-ref argument. The data being passed is an address pointer, rather than binary
or character data.
- cpsm-token
- A sending or receiving argument used to pass identifying tokens that
are generated by CICSPlex SM. A cpsm-token argument can be considered
a data-ref argument with an unspecified data type.
Tokens are
created by CICSPlex SM to identify API processing threads, result sets, filters,
and notifications.
Because token values are created by CICSPlex SM, your
program must receive a token into a variable before it can specify that token
on subsequent commands. A token cannot be defined by a self-defining term
or expression; it must be a named variable.
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) USAGE BINARY
- Fullword binary -- PIC S9(8) USAGE BINARY
- Character string -- PIC X(n) where "n" is the number of bytes.
data-value includes data-ref as a subset.
- data-ref
- 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) USAGE BINARY
- Fullword binary -- PIC S9(8) USAGE BINARY
- Character string -- PIC X(n) where "n" is the number of bytes.
Where the data type is unspecified, data-ref can refer to an
elementary or group item.
- data-area
- Can be replaced by any COBOL data name with a data type of halfword
binary (PIC S9(4) COMP), fullword binary (PIC S9(8) COMP), or character string
(PIC X(n)).
- ptr-ref
- Can be replaced by a pointer variable or an ADDRESS special register.
- cpsm-token
- Can be replaced by any COBOL data name with a data type of fullword
binary, PIC S9(8) COMP.
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
- Character array -- char[n] where "n" is the number
of bytes in the field (the field must be padded with blank spaces).
data-value includes data-ref as a subset.
- data-ref
- 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
- Character array -- char[n] where "n" is the number
of bytes in the field (the field is padded with blank spaces).
If the data type is unspecified, data-ref can refer to a scalar
data type, array, or structure. The reference must be to contiguous storage.
- data-area
- Can be replaced by any named variable with a data type of halfword binary
(short int), fullword binary (long int), or character array (char[n]).
- ptr-ref
- Can be replaced by any C pointer type reference.
- cpsm-token
- Can be replaced by any named variable with a data type of fullword binary,
long int.
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)
- Character string -- CHAR(n) where "n" is the number of bytes.
data-value includes data-ref as a subset.
- data-ref
- 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)
- Character string -- CHAR(n) where "n" is the number of bytes.
If the data type is unspecified, data-ref 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.
- data-area
- Can be replaced by any named variable with a data type of halfword binary
(FIXED BIN(15)), fullword binary (FIXED BIN(31)), or character string (CHAR(n)).
- ptr-ref
- Can be replaced by any PL/I reference of type POINTER ALIGNED.
- cpsm-token
- Can be replaced by any named variable with a data type of fullword binary,
FIXED BIN(31).
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-ref
- Can be replaced by a relocatable expression that is an assembler-language
reference to data of the correct type for the argument.
- data-area
- Can be replaced by a relocatable expression that is an assembler-language
reference to data with a type of halfword (DS H), fullword (DS F), or character
string (CLn).
- ptr-ref
- Can be replaced by any absolute expression that is an assembler-language
reference to a register.
- cpsm-token
- Can be replaced by a relocatable expression that is an assembler-language
reference to data with a type of fullword, DS F.
[[ Contents Previous Page | Next Page Index ]]