CSLSCRQS: send request

A request in an IMSplex can contain both input and output data (from the target member's perspective). This contrasts to a message that can only contain input data (again, from the target member's perspective). The data of a request is copied to the target member's address space. The function is processed, and the output is returned to the requestor's address space. If the request included an ECB, control is returned to the requesting module after the request has been processed by SCI. The requestor must then wait on the ECB.

The ECB is posted when the request processing has completed. The requestor then looks at the RETCODE and RSNCODE fields to determine the outcome of the request. If no ECB is included in the request, the RETCODE and RSNCODE fields can be used to determine the outcome of the request when the requesting module gets control back from SCI.

CSLSCRQS parameters

ECB=symbol

ECB=(r1-r12)

(Optional) - Specifies the address of a z/OS® ECB used for asynchronous requests. When the request is complete, the ECB specified is posted. If an ECB is not specified, the task is suspended until the request is complete. If an ECB is specified, the invoker of the macro must issue a WAIT (or equivalent) after receiving control from CSLSCRQS, before using or examining any data returned by this macro (including the RETCODE and RSNCODE fields).

FUNCTYPE=DEST

FUNCTYPE=SENDER

(Optional) - Specifies that the MBRFUNC and MBRSFUNC are defined by the DEST (destination) of this request or the SENDER of the request. This indicator is passed to the recipient of the request in the SCI Input exit parameter list.

MBRFUNC= symbol

MBRFUNC= (r1-r12)

(Required) - Specifies a 4-byte member function code that is passed to the destination of the request in the SCI Input exit parameter list. This function code, along with the MBRSFUNC, identifies the request that is being sent.

If MBRFUNC is a symbol, the symbol points to a four-byte area of storage that contains the function code.

MBRPARM= symbol

MBRPARM= (r1-r12)

(Required) - Specifies the address of a pre-built parameter list. This parameter list must be built by the requesting module and consists of sets of triplets. Each triplet describes a single parameter in the member parameter list and consists of:

parameterlength

Four-byte parameter that specifies the length of the member parameter.

parameteraddress

Four-byte parameter that specifies the address of the member parameter.

datatype

Four-byte parameter that specifies how this parameter is to be handled by SCI. Equates are provided for each type (included with CSLSCODE). These equates can be used to set the value of data type. Possible values are:

IN

The parameter is an input parameter. It is copied to the destination address space with the request.

OUT

The parameter is an output parameter. It is copied back to the requesting address space when the request is completed by the server. The storage for the parameter must be allocated before the request is issued.

IO

The parameter is both an input and an output parameter. It is copied to the target address space with the request and it is copied back to the requesting address space when the request is complete.

SCI

The parameter is an SCI allocated output parameter. The storage for the parameter is allocated in the requestor's address space when the request is complete. The address of the storage will be returned in the parameter address field and the length will be returned in the parameter length field. The storage must be released by the requestor using the CSLSCBFR request. The eight bytes immediately in front of the address returned for an SCI-allocated output parameter are available for use by the requestor. These eight bytes are not cleared, and might contain residual data from a prior use of the buffer.

The two methods for passing parameters in a parameter list are by address and by value. Both of these methods can be used when passing parameters in a CSLSCRQS request. The triplet must be setup so that SCI will handle the parameter properly.

• By address

  To pass a parameter by address, the address of the parameter must be passed in parameteraddress and the length of the parameter must be passed in parameterlength. SCI will get the parameter from parameteraddress for data type IN and IO and will store the parameter at parameteraddress for data type OUT and IO. The address at which the parameter is stored and its length is returned for data type SCI.

• By value

  To pass a parameter by value, the parameter must be passed in parameteraddress and zero must be passed in parameterlength. When the length is zero, SCI will copy the value contained in parameteraddress to the destination for data type IN. All other data types must be passed by address since SCI requires an address to store any output parameters.

Member Parameter List: The user parameters specified here are presented to the program that receives the request in the member parameter list, the address of which is contained in the Input Exit Parm area field INXP_MBRPLPTR. Each parameter is represented by eight bytes, the first four bytes contain parameterlength and the second four bytes contain parameteraddress (if parameteraddress is an address, the second four bytes point to storage in the local address space, not the requesting address space). If the parameter's data type is SCI, the first four bytes will contain a length of four and the second word's value is unpredictable.

Null Parameters: In some cases a request processing module expects a set number of parameters with a defined order. If a request is to be sent that does not contain all the parameters, null parameters must be sent to ensure the data buffer contains everything that is expected. Null parameters can be sent by specifying zero for parameterlength and parameteraddress. The eights bytes that represent the parameter in the data buffer will contain zeros. This is true for any data type (IN, OUT, IO or SCI) or method of passing parameters (by address or by value).

MBRPCNT=symbol

MBRPCNT=(r1-r12)

(Required) - Specifies a 4-byte field that contains the number of member parameters that are included in MBRPARM.

MBRSFUNC=symbol

MBRSFUNC=(r1-r12)=

(Optional) - Specifies a 4-byte member subfunction code that is passed to the destination of the request in the SCI input exit parameter list. This subfunction code, along with the MBRFUNC, identifies the request that is being sent.

If MBRSFUNC is a symbol, the symbol points to a 4-byte area of storage that contains the sub-function code.

NAME=symbol

NAME=(r1-r12)

(Optional) - Specifies the address of an 8-byte member name of the destination of this request. This name can be obtained from the Notify exit (when the member joins the IMSplex) or by issuing a CSLSCQRY request.

Note: One of the routing parameters (NAME, TOKEN or TYPE) must be included.

PARM=symbol

PARM=(r1-r12)

(Required) - Specifies the address of a parameter list used by the request to pass the parameters to SCI. The length of the storage must be at least equal to the value of SRQS_LN.

RETCODE=symbol

RETCODE=(r1-r12)

(Required) - Specifies the address of a 4-byte field to receive the CSLSCRQS return code. SCI return codes are defined in CSLSRR. Possible return codes for CSLSCRQS are described in the following table.

RETNAME=symbol

RETNAME=(r1-r12)

(Optional) - Specifies the address of an 8-byte field to receive the name of the SCI that processes the request.

RETTOKEN=symbol

RETTOKEN=(r1-r12)

(Optional) - Specifies the address of a 16-byte field to receive the SCI token of the SCI that processes the request.

RSNCODE=symbol

RSNCODE=(r1-r12)

(Required) - Specifies the address of a 4-byte field to receive the CSLSCRQS reason code. SCI reason codes are defined in CSLSRR. Possible reason codes for CSLSCRQS are described in the following table.

SCITOKEN=symbol

SCITOKEN=(r1-r12)

(Required) - Specifies a 16-byte field containing the SCI token. This token uniquely identifies this connection to SCI. The SCI token was returned by a successful CSLSCREG FUNC=REGISTER request.

TOKEN=symbol

TOKEN=(r1-r12)

(Optional) - Specifies the address of the 16-byte SCI token of the destination of this request. This token can be obtained either from the Notify exit (when the member joins the IMSplex) or by issuing a SLSCQRY message.

Note: One of the routing parameters (NAME, TOKEN, TYPE) must be included.

TYPE=symbol

TYPE=(r1-r12)

TYPE='AOP'

TYPE='BATCH'

TYPE='CQS'

TYPE='DBRC'

TYPE='IMS'

TYPE='IMSCON'

TYPE='ODBM'

TYPE='OM'

TYPE='OTHER'

TYPE='RM'

TYPE='SCI'

Input parameter that specifies the IMSplex member type of the IMSplex member to which this request should be routed. The IMSplex member type routing can be further qualified by using the SUBTYPE parameter. If TYPE is specified, SCI chooses the IMSplex member of the requested type to which the request is sent.

If member type is specified as a literal, the literal must be enclosed in single quotes. If this parameter is passed as a symbol or register, the symbol or register must contain the member type code. The member type code can be obtained by using the CSLSTPIX macro.

Note: One of the routing parameters (NAME, TOKEN, TYPE) must be included.

CSLSCRQS return and reason codes

The following table lists the return and reason codes that can be returned on a CSLSCRQS macro request. Also included is the meaning of a reason code (that is, what possibly caused it).