RequestStream domain’s specific gates

Table 89 summarizes the RequestStream domain’s specific gates. It shows the level-1 trace point IDs of the modules providing the functions for the gates, and the functions provided by the gates. None of the functions are available through the exit programming interface (XPI).

Table 89. RequestStream domain specific gates
Gate Trace Function XPI
RZSO
RZ 0110
RZ 0111
CREATE
SEND_REQUEST
RECEIVE_REPLY
LEAVE
JOIN
IS_ID_LOCAL
NO
NO
NO
NO
NO
NO
RZTA
RZ 0120
RZ 0121
RECEIVE_REQUEST
SEND_REPLY
GET_PUBLIC_ID
GET_SERVER_DATA
GET_CURRENT
GET_JOIN_DATA
TERMINATE
NO
NO
NO
NO
NO
NO
NO
RZRT
RZ 0170
RZ 0171
SET_EXIT_PROGRAM NO
RZRJ
RZ 0180
RZ 0181
PERFORM_JOIN NO

RZSO gate, CREATE function

Create a RequestStream and return a (local region) source RequestStream token for it.

The target process(or) is identified either by USERID and TRANID or by HOST_IP_ADDRESS and PORT_NUMBER. Precisely one of these groups must be provided.

(The HOST_IP_ADDRESS is a character string as expected by the internal sockets domain interfaces.)

The SERVER_DATA may be retrieved at the target (RZTA) interface and is copied (and fixed) on this call.

The response is (exception, service_not_available) if it is not possible to resolve the target, or to set up a connection to the target. (Success does not guarantee that this exception will not occur on the SEND function.)

The response is (exception, target_unknown) if the HOST_IP_ADDRESS character string is malformed (as detected by the sockets domain interfaces).

The response is invalid when the parameters are badly formed, in particular if there is not the right combination of target identification parameters.

Input parameters

[USERID]
Userid under which the requests are to be processed.
[TRANID]
TranId of the transaction which runs the target processor.
[HOST_IP_ADDRESS]
Identification of the target which is to process the requests.
[PORT_NUMBER]
Further identification of the target.
[SERVER_BLOCK]
Data associated with the RequestStream available at the target end by the server using the RZTA interface.
[SSL_REQUIRED]
Values: YES, NO

Whether to use SSL on a socket transport. Otherwise ignored.

[CERTIFICATE_NAME]
Further information for an SSL socket transport. Otherwise ignored.

Output parameters

RS_TOKEN
Token by which RequestStream is identified on all subsequent requests from this task on this region.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVICE_NOT_AVAILABLE
TARGET_UNKNOWN

RZSO gate, SEND_REQUEST function

The source RequestStream token and the request (coded as a RUEI or as a contiguous data block) is passed as input. Either a ruei or a block must be used, not both. If this is not so then an invalid response is returned.

The request is deemed to be entire and may be presented to the target. Data may be transported across the transport mechanism during this call. The request may be of zero length, this does not imply that nothing is transported.

If the source RequestStream token does not exist (in the local region) the response (exception, rs_token_unknown) is returned.

If a transport mechanism fails to respond, or is not functional, then the response (exception, service_not_available) is returned. If it fails during transmission then (exception, transport_failure) is returned. The distinction is that in the former case there is no transport mechanism and in the latter there is still one (albeit inoperational).

Input parameters

RS_TOKEN
Token returned on CREATE by which RequestStream is identified.
[REQUEST_RUEI]
Reusable-extended-Iliffe Vector which describes contiguous bytes to send as a request, supplied in possibly discontiguous blocks. Exclusive with REQUST_BLOCK.
[REQUEST_BLOCK]
Request data to send described as a single block. Exclusive with REQUEST_RUEI.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
RS_TOKEN_UNKNOWN
TRANSPORT_FAILURE
SERVICE_NOT_AVAILABLE

RZSO gate, RECEIVE_REPLY function

A reply is returned (blocks until one is available).

The "reply_buffer" is set with as much data as will fit. The total number of bytes possible to be transferred is returned in the buffer as well as as many bytes of the reply that will fit. The "reply_buffer" size +is not set+ although the number of bytes to be set in the buffer is set as usual. The call can be re-issued before any other calls to the RequestStreams source interface (using this token) to receive the remaining reply bytes. Reply data is not redelivered.

The final call to "receive_reply" indicates that all of the data to be transferred fit within the buffer passed. The final call to "receive_reply" will allow the transport to change direction, which means that further calls to "receive_reply" will be an error and will give a response "(exception, transport_failure)". If a "notify" callback has been called before this function is issued then "receive_reply" will be satisfied. The status of the "notify" callback is not affected by this call ("notify" is disabled automatically when it is issued) except that if there is data to deliver, and a "notify" callback is enabled with "listen", and has not been called, then the "notify" callback will be called as part of the processing of this function. This can be avoided, if necessary, by issuing a "cancel" beforehand.

If the RequestStream token is not known then the response is "(exception, rs_token_unknown)". If the transport service is not open then the response "(exception, service_not_available)" is returned. If the transport service is still open but gives some sort of error (for example, is not in the correct state to receive a reply) then the response is "(exception, transport_failure)". If the request processor cannot, for some reason, process the request, and returned an exception, or failed during execution, then the response is "(exception, request_processor_failure)". Processor failure, when it can be ascertained, takes precedence over transport failure.

Input parameters

RS_TOKEN
Token returned on CREATE by which RequestStream is identified.
[REPLY_BUFFER]
Buffer in which reply bytes are assembled.
[MINIMUM_DATA_LENGTH]
Minimum amount of data to accept (multiple transfers may occur until this amount is received).

Output parameters

[REPLY_DATA_LENGTH]
Total length of reply (even if not all received in one call).
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
RS_TOKEN_UNKNOWN
SERVICE_NOT_AVAILABLE
TRANSPORT_FAILURE
REQUEST_PROCESSOR_FAILURE

RZSO gate, LEAVE function

Remove this source from its RequestStream. The RequestStream is modified so that the "rs_token" (which must denote a source end of the RequestStream) is no longer valid. (A token value may or may not be reissued by "RZ" on another "create" or "join" request - however the caller must not rely on its value after "leave".)

If the RequestStream "rs_token" is valid but does not denote a source end of a RequestStream known in this region the response "(exception, rs_token_not_source)" is returned.

If the transport mechanism fails then the response "(exception, transport_failure)" is returned, +however the RequestStream source token is still invalidated+.

If a "notify" is enabled for this RequestStream token (with a "listen" call) then the "notify" callback is called with the "CLOSE" parameter prior to removing the RequestStream source.

Input parameters

RS_TOKEN
The token returned on CREATE identifying the RequestStream for this region.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
RS_TOKEN_UNKNOWN
TRANSPORT_FAILURE
RS_TOKEN_NOT_SOURCE

RZSO gate, JOIN function

"Join" the RequestStream identified by the "public_id".

If the required transport mechanism is not available, or fails in use, the appropriate exception is returned as for "create".

If the RequestStream, identified by the "public_id", does not exist (because the target end does not exist) then this call does not detect this. Instead a new request processor will be created implicitly just as for "create".

The "userid" (if supplied) must match that used on the "create", otherwise an error may occur later in (Request Processor) processing. This is not detected at this call. The "tranid" and the "server_data" is supplied in case the RequestStream is recreated on this call, otherwise they are ignored. They may be omitted as in *create*.

If the "public_id" is not valid, or cannot be interpreted then the response "(exception, public_id_invalid)" will be returned.

The "rs_token" for the local source RequestStream is returned as result.

Input parameters

PUBLIC_ID
Public RequestStream Identifier -- valid for all participating regions in the logical server -- of the target RequestStream, which may be in a separate region.
[USERID]
The security userid under which the target RequestStream should be executing.
[TRANID]
The transaction identifier for the target RequestStream task.
[SERVER_BLOCK]
The server data that was specified. This parameter and Tranid are used only if a new target RequestStream needs to be created owing to the omission of the target RequestStream processor.

Output parameters

RS_TOKEN
The local region token by which the source RequestStream (that connects to the target) is known on all subsequent calls.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVICE_NOT_AVAILABLE
TRANSPORT_FAILURE
PUBLIC_ID_INVALID

RZSO gate, IS_ID_LOCAL function

Return "yes" if the "public_id" refers to the local region as the target region for the RequestStream. Otherwise "no".

This is a non-blocking call that gives the response "(exception, public_id_invalid)" if the "public_id" is detectably invalid (e.g. has the wrong format) and otherwise has no exceptions.

Input parameters

PUBLIC_ID
Public RequestStream Identifier -- valid for all participating regions in the logical server -- of a target RequestStream, which may be in a separate region.

Output parameters

LOCAL
Values:

YES|NO indicating whether the identified PUBLIC_ID is in the local region or not. There is no guarantee that it exists in either case.

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION PUBLIC_ID_INVALID

RZTA gate, RECEIVE_REQUEST function

Get the next request. This call blocks if there is no request ready, and returns when a request becomes available or if the RequestStream is destroyed while waiting ("terminate"d). This call will be satisfied without undue waiting if a "notify" callback has been invoked.

A request is delivered by means of a buffer. The total length of the buffer data available is placed in the buffer content value, and as many bytes as will fit are copied to the buffer data area. If there are more bytes than will fit in the buffer area then another receive request may be issued to receive more, and more will be copied until all are delivered.

Should a request not be fully delivered on this interface then the underlying transport will not be reversed (as in half-duplex communications) until another receive is issued. Only when all of the request is delivered will the request be deemed to be delivered and the underlying transport be able to flip.

Should other interface calls be issued on this RequestStream (target) then data bytes of this request may be lost. The request data are bound to the task which is issuing the receive request commands, and the task cannot change in the middle of receiving a request.

The "correlation_id" (optionally received and identical on all the calls for one request) identifies the source from which the request comes and is required when sending a reply on this RequestStream (with "send_reply"). It is guaranteed distinct for each distinct source of this RequestStream. The reply to this request (if there is one) should be accompanied by the same "correlation_id" (on "send_reply") otherwise no guarantee can be made that the reply will return to the correct source.

Input parameters

REQUEST_BUFFER
Buffer into which the request is received.
[MINIMUM_DATA_LENGTH]
The minimum data length that should secure a response if not all the request is received. Multiple transfers may occur if not enough data is available when the request is issued.

Output parameters

[CORRELATION_ID]
The identifier of the requester using this RequestStream. It is used when replying to this request (using SEND_REPLY on this RequestStream) so as to identify the source from which the request was issued. It is valid only while this RequestStream is available to this transaction.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
Returned when RESPONSE is EXCEPTION or INVALID. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
REQUESTSTREAM_NOT_CURRENT
SERVICE_NOT_AVAILABLE
TRANSPORT_FAILURE
INVALID INVALID_BUFFER

RZTA gate, SEND_REPLY function

Send a reply to a source identified by "correlation_id".

The "correlation_id" must be one returned by the "receive_request" function for the current RequestStream, or else the exception "correlation_id_unknown" may be returned.

A reply may consist of the empty sequence of bytes in which case an empty reply is sent.

The usual exceptions are returned for transportation failures.

Input parameters

REPLY_BLOCK
A block containing the complete contiguous reply.
CORRELATION_ID
The correlation id received on RECEIVE_REQUEST for the request to which this is the reply.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
Returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
REQUESTSTREAM_NOT_CURRENT
CORRELATION_ID_UNKNOWN
SERVICE_NOT_AVAILABLE
TRANSPORT_FAILURE

RZTA gate, GET_SERVER_DATA function

Return the server data for the current RequestStream.

If there is a current RequestStream then server data are available. If there is no current RequestStream the response "(exception, requeststream_not_current)" is returned. If the server data are known but empty (zero-length sequence of bytes), then the outputs are set to indicate zero-length content.

The "server_block" is input so that it may be filled on return. If the data area is too small then the response "(exception, server_block_too_small)" is returned +and no data is transferred+. In this case the output "server_data_length" is set to indicate the total number of bytes in the server data.

Server data do not change while the RequestStream remains current. (A RequestStream may be recreated as a result of a "join" if it has previously been destroyed or terminated. At this point the server data may be different from the original values.)

Input parameters

SERVER_BLOCK
Block in which the server data is placed on output.

Output parameters

SERVER_DATA_LENGTH
The number of bytes of the server data, even if not all were returned.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
Returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
REQUESTSTREAM_NOT_CURRENT
SERVER_BLOCK_TOO_SMALL

RZTA gate, GET_PUBLIC_ID function

The public identifier of the RequestStream for the current transaction is returned. (If the target of the RequestStream is not internal to the plex there may not be a public identifier, for example in the case of outbound RequestStreams. In this case the response is "(exception, public_id_unknown)". However, this should never happen on this interface, since such a RequestStream will never be set in the "RZ" transaction manager token for a transaction instance.)

The response "(exception, RequestStream_not_current)" is returned if the XM token is not valid in the local region, or if no XM token for the RequestStream is set.

Output parameters

PUBLIC_ID
Public RequestStream Identifier -- valid for all participating regions in the logical server -- of the current target RequestStream which must be attached to this task/transaction.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
Returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
REQUESTSTREAM_NOT_CURRENT
PUBLIC_ID_UNKNOWN

RZTA gate, GET_CURRENT function

The token for the RequestStream for the current transaction is returned. If the "XM" token is not set, or is set to an invalid value, then the response "(exception, RequestStream_not_current)" is returned.

Output parameters

RS_TOKEN
Token for current target RequestStream which must be attached to this task.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
Returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION REQUESTSTREAM_NOT_CURRENT

RZTA gate, GET_JOIN_DATA function

This is a utility function used by the join task which can thereby reduce the number of domain calls to RZ when acting as intermediary to another task on remote join.

If there is no current RequestStream the response "(exception, requeststream_not_current)" is returned.

Output parameters

USERID
The userid of the request processor to be joined.
TRANID
The transid of the request processor to be joined.
PUBLIC_ID
The public id of the target RequestStream on the processor to be joined.
REQUEST_DATA_LENGTH
The data length of the request to be passed to the processor to be joined.
RESPONSE
Values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
Returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION REQUESTSTREAM_NOT_CURRENT

RZTA gate, TERMINATE function

Terminate the current (target) RequestStream either normally or abnormally. After this call the "XM" token in the transaction instance is cleared and no longer denotes a RequestStream.

If no "rs_token" is specified and there is no current RequestStream ("XM" token) then the response "(exception, RequestStream_not_current)" is returned.

If "rs_token" is specified it is taken as the token of the RequestStream to terminate.

If the RequestStream token is not in the +RegionRSTable+ (or else is not a +target+ RequestStream in that table) then the response "(exception, rs_token_unknown)" is returned.

If the termination is "normal" then transports are tested for being in a state that accepts normal termination and if they are they are closed and storage associated with the RequestStream is returned and the local region token is invalidated. The +ResionRSTable+ has the "rs_token" removed, and the current RequestStream is unset (the "XM" token is cleared but only if the "rs_token" was +not+ specified on the call). If any transports are +not+ in a correct state then no action is taken and the response "(exception, cannot_terminate_normally)" is returned.

If the termination is "abnormal" then the transports are closed in whatever state they are found, and the RequestStream is terminated as for normal termination.

The usual exceptions concerning the transport mechanism (if used) are possible however +the RequestStream was still terminated even if a transport exception is returned+.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
Returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
REQUESTSTREAM_NOT_CURRENT
RS_TOKEN_UNKNOWN
SERVICE_NOT_AVAILABLE
TRANSPORT_FAILURE
CANNOT_TERMINATE_NORMALLY

RZRT gate, SET_EXIT_PROGRAM function

The following defines the syntax of the SET_EXIT_PROGRAM function.

This is used to identify the name of the distributed routing user-replaceable program at domain initialization time and when the program name is dynamically changed. During CICS® initialization the local sysid is also passed to "RZ" from Parameter Manager via this interface.

Input parameters

PROGRAM_NAME
The name of the user-replaceable program for the Distributed Dynamic Routing program.
[LOCAL_SYSID]
The SYSID for the local CICS region to recognize it in routing user-replaceable program responses.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
Returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER ABEND

RZRJ gate, PERFORM_JOIN function

This function reduces the calls necessary from the join task (in remote join capability) to the RZ domain. It initiates the procedures necessary to pass an attached RequestStream to a local processor.

Output parameters

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
REASON
Returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
TRANSPORT_FAILURE
JOIN_NOT_POSSIBLE
[[ Contents Previous Page | Next Page Index ]]