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).
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 |
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.
Whether to use SSL on a socket transport. Otherwise ignored.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION |
SERVICE_NOT_AVAILABLE TARGET_UNKNOWN |
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).
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION |
RS_TOKEN_UNKNOWN TRANSPORT_FAILURE SERVICE_NOT_AVAILABLE |
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.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION |
RS_TOKEN_UNKNOWN SERVICE_NOT_AVAILABLE TRANSPORT_FAILURE REQUEST_PROCESSOR_FAILURE |
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.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION |
RS_TOKEN_UNKNOWN TRANSPORT_FAILURE RS_TOKEN_NOT_SOURCE |
"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.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION |
SERVICE_NOT_AVAILABLE TRANSPORT_FAILURE PUBLIC_ID_INVALID |
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.
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.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION | PUBLIC_ID_INVALID |
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.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION |
REQUESTSTREAM_NOT_CURRENT SERVICE_NOT_AVAILABLE TRANSPORT_FAILURE |
INVALID | INVALID_BUFFER |
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.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION |
REQUESTSTREAM_NOT_CURRENT CORRELATION_ID_UNKNOWN SERVICE_NOT_AVAILABLE TRANSPORT_FAILURE |
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.)
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION |
REQUESTSTREAM_NOT_CURRENT SERVER_BLOCK_TOO_SMALL |
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.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION |
REQUESTSTREAM_NOT_CURRENT PUBLIC_ID_UNKNOWN |
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.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION | REQUESTSTREAM_NOT_CURRENT |
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.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION | REQUESTSTREAM_NOT_CURRENT |
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+.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION |
REQUESTSTREAM_NOT_CURRENT RS_TOKEN_UNKNOWN SERVICE_NOT_AVAILABLE TRANSPORT_FAILURE CANNOT_TERMINATE_NORMALLY |
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.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
DISASTER | ABEND |
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.
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
RESPONSE | Possible REASON values |
---|---|
EXCEPTION |
TRANSPORT_FAILURE JOIN_NOT_POSSIBLE |