Using the command-level interface

Command format

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 (;).

Argument values

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:

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: 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: 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: 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: 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: 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: 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 ]]