RequestStream domain formats

Table 91 shows the formats owned by the requeststream domain, and shows the functions performed. The modules that issue requests in this format make them to RZ.

Table 91. Generic formats owned by the RequestStream domain.
Format Module called Calling modules Functions
LSTN DFHRZLN
DFHIIDM
DFHIIRP
DFHIIRR
REGISTER
LISTEN
CANCEL
DEREGISTER
NOTI
DFHIIRP
DFHIIRR
DFHRZLN NOTIFY

LSTN gate, REGISTER function

Register the notify interface with the server domain. The calback_gate is the gate number +in the caller’s domain+. The caller’s domain is inferred by kernel linkage.

Returns the "notify_token" which identifies this registration.

Returns ("exception, registration_rejected") if the domain is not ready to allow registrations (initializing or quiescing, for example), or if it cannot issue any more tokens (due to resource limitations, for example). This response is given if the other functions of the domain are not compromised by this failure. Higher severity responses may be given otherwise.

The caller must supply the parameters "call_domain()" and "call_gate()" on this function. See design file for details.

Input parameters

CALLBACK_GATE
The gate number of the Domain Gate to be called for notification.

Output parameters

NOTIFY_TOKEN
The token identifying this notification registration. Used on Listen, Cancel, and Notify functions.
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 REGISTRATION_REJECTED

LSTN gate, LISTEN function

Listen to the server object and notify the registered notify callback gate, identified by "notify_token", if the object requires service. Pass the supplied "client_token" on the notify call.

Exceptions:

"notify_token_unknown"
the notify token cannot be found by this server domain;
"notify_token_in_use"
the notify token is being used and this server does not allow multiple uses;
"notify_token_misused"
the notify token belongs to another domain and this server does not allow multiple client access to it;
"server_token_unknown"
the server does not recognize the server token;
"server_token_in_use"
the object denoted by the server token already has a listen outstanding, and this server does not allow multiple listens.

The caller must supply the parameters "call_domain()" and "call_gate()" on this function. See design file for details.

Input parameters

NOTIFY_TOKEN
Token that identifies the registration for this listen request.
SERVER_TOKEN
Token that identifies the server-owned object being listened to.
CLIENT_TOKEN
Token for the client, returned on Notify to identify this listen request.

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
NOTIFY_TOKEN_UNKNOWN
NOTIFY_TOKEN_IN_USE
NOTIFY_TOKEN_MISUSED
SERVER_TOKEN_UNKNOWN
SERVER_TOKEN_IN_USE

LSTN gate, CANCEL function

Cancel an outstanding listen request. Ensure that it is not driven upon return from this call. The "notify_token" and the "server_token" are to be specified, and optionally the "client_token" that was specified on the "listen" request can be retrieved.

Exceptions:

"notify_token_unknown"
the notify token cannot be found by this server domain;
"notify_token_misused"
the notify token belongs to another domain and this server does not allow multiple client access to it;
"server_token_unknown"
the server does not recognize the server token;
"listen_not_outstanding"
the object denoted by the server token does not have a listen outstanding.

The caller must supply the parameters "call_domain()" and "call_gate()" on this function. See design file for details.

Input parameters

NOTIFY_TOKEN
Token that identifies the registration for this cancel request.
SERVER_TOKEN
Token that identifies the server-owned object being listened to.

Output parameters

[CLIENT_TOKEN]
Client Token that was passed on LISTEN and would have been passed to NOTIFY.
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
NOTIFY_TOKEN_UNKNOWN
NOTIFY_TOKEN_MISUSED
SERVER_TOKEN_UNKNOWN
LISTEN_NOT_OUTSTANDING

LSTN gate, DEREGISTER function

Call outstanding notifies on this registration (identified by "notify_token") with a normal termination notification, and then remove the registration of the client (caller) domain from this server domain. The "notify_token" is no longer valid.

Exceptions:

"notify_token_unknown"
the notify token cannot be found by this server domain;
"notify_token_misused"
the notify token belongs to another domain and this server does not allow multiple client domain access to it;

The caller must supply the parameters "call_domain()" and "call_gate()" on this function. See design file for details.

Input parameters

NOTIFY_TOKEN
Token that identifies the registration token being deregistered.

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
NOTIFY_TOKEN_UNKNOWN,
NOTIFY_TOKEN_MISUSED

NOTI gate, NOTIFY function

Call the client domain notify gate registered as "notify_token" passing the "server_token" and the "client_token" given on the "listen" call, and with a status indicating the notification reason. The listen is considered discharged after this call, and this notify will not be called again unless another "listen" request is made.

If the callback returns an exception response then the registration should be deleted. This is equivalent to a "deregister" call, including the call of this same notify callback gate for any other outstanding "listen" requests.

If the callback returns a response more serious than exception ("disaster", "purged", etc.) then the registration should be deleted but no other callbacks are to be made to outstanding "listen"s for this registration. In particular a kernel error, or an "invalid" response, should not attempt to recall the same gate again. This is deemed to be a severe internal error.

The caller (the server domain) will use "call_gate()" with the value of the callback gate supplied on registration, and "call_domain()" with the client domain who registered. This must refer to a valid gate or a kernel error will result.

Input parameters

NOTIFY_TOKEN
Token that identifies the registration for this notify request.
SERVER_TOKEN
Token that identifies the server-owned object being notified.
CLIENT_TOKEN
Token supplied by the client on the listen request.
NOTIFY_STATUS
Values: NOTIFY, CLOSE, ABEND, TIMEOUT

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 NOTIFY_CALLBACK_FAILED
[[ Contents Previous Page | Next Page Index ]]