|
The following section describes the parameters you specify when
calling the Set_Allocate_Queue_Notification service.
- Notify_type
- Supplied parameter
- Type: Structure
- Length: 4-8 bytes
Specifies the type of processing and notification (synchronous
or asynchronous) requested for this service. The possible types are:
- None
No notification is requested. APPC/MVS processes this
call synchronously, and returns control to the caller when processing
is complete. APPC/MVS sets all returned parameters on return to the
caller. To specify no notification, set this parameter to a four-byte
structure that contains binary zeroes.
- ECB
Programs can request asynchronous processing by specifying
an ECB to be posted when processing completes. To specify an ECB,
set this parameter to an eight-byte structure that contains a fullword
binary one (X'00000001'), followed by the address of a fullword
area to be used as the ECB. The ECB must reside in the caller's home
address space.
When you specify an ECB, APPC/MVS returns control
to the caller before processing is complete, with only the return
code set. If APPC/MVS accepts the asynchronous request, it sets the
return code to 0 to show that it is processing the service asynchronously.
APPC/MVS fills in the other returned parameters during asynchronous
processing, and posts the specified ECB when it has set all the returned
parameters. The completion code field in the ECB contains the return
code for the service. APPC/MVS places the reason code, if any, in
the server's reason_code parameter.
- Allocate_queue_token
- Supplied parameter
- Type: Character string
- Length: 8 bytes
Specifies the allocate queue token that indicates the particular
allocate queue for which you are requesting notification, or cancelling
a previous notification request. (The allocate queue token is returned
as output from a successful call to the Register_For_Allocates service.)
- Event_notification_type
- Supplied parameter
- Type: Integer
- Length: 32 bits
Specifies one-time or continuous notification, or cancels
notification that the server requested previously through one or more
calls to this service.
Valid values for this parameter are:
- Value
- Meaning
- 1
- atbcts_set_one_time_notify
Request one-time notification
for the event. APPC/MVS notifies the server after the first occurrence
of the event and stops monitoring for the event. The server can restore
this notification request if necessary by calling the Set_Allocate_Queue_Notification
service again with the same parameter values.
- 2
- atbcts_set_continuous_notify
Request continuous notification
for an event. APPC/MVS notifies the server every time the event occurs
until the server cancels this request or the APPC/MVS address space
ends.
- 3
- atbcts_cancel_notify
Cancel a particular notification request
(specified in this call by the combination of the event_code and event_notification_type
parameters). APPC/MVS also deletes from the server's event queue any
unreceived event elements that were queued because of the request
to be cancelled. If this is the last active notification request for
the server and the server has an outstanding call to the Get_Event
service, APPC/MVS cancels the Get_Event service. The server receives,
as output from the Get_Event service, a return code of 16 (atbcts_request_unsuccessful)
and a reason code of 31 (atbcts_event_notify_cancelled).
- 4
- atbcts_cancel_all_notify
Cancel all active
event notification requests from the server for a particular allocate
queue (specified by the allocate_queue_token parameter). APPC/MVS
also deletes any unreceived event elements related to the allocate
queue from the server's event queue. If this is the server's last
active notification request, and the server has an outstanding call
to the Get_Event service, APPC/MVS cancels the call to the Get_Event
service. The server receives, as output from the Get_Event service,
a return code of 16 (atbcts_request_unsuccessful) and a reason code
of 31 (atbcts_event_notify_cancelled).
- Event_code
- Supplied parameter
- Type: Integer
- Length: 32 bits
Specifies the type of threshold (minimum or maximum) for which
the server is to be notified, or the notification request to be cancelled.
When the event_notification_type parameter is set to 1 or 2, this
is the type of threshold for which the server is requesting notification.
When the event_notification_type parameter is set to 3 or 4, this
is the type of threshold for which the server is cancelling notification.
Valid
values for this parameter are:
- Value
- Meaning
- 1
- atbcts_allocate_queue_min
Specifies a minimum threshold.
For a notification request (event notification type 1 or 2), APPC/MVS
is to notify the server when the allocate queue (specified by the
allocate_queue_token parameter) decreases to the number of allocate
requests specified by the event_qualifier parameter.
For a cancel
notification request (event notification type 3 or 4), APPC/MVS is
to cancel notification for this minimum threshold.
- 2
- atbcts_allocate_queue_max
Specifies a maximum threshold.
For a notification request (event notification type 1 or 2), APPC/MVS
is to notify the server when the allocate queue (specified by the
allocate_queue_token parameter) increases to the number of allocate
requests specified by the event_qualifier parameter.
For a cancel
notification request (event notification type 3 or 4), APPC/MVS is
to cancel notification for this maximum threshold.
- Event_qualifier
- Supplied parameter
- Type: Integer
- Length: 32 bits
Specifies the number (in decimal) of allocate requests for
the minimum or maximum threshold. The range of possible values for
this parameter depends on whether the threshold is a minimum or maximum
(specified through the event_code parameter). The threshold ranges
are as follows:
- For a minimum threshold, this parameter may be set to a value
from 0 to ((2**32)-2)
- For a maximum threshold, this parameter may be set to a value
from 1 to ((2**32)-1).
- Reason_code
- Returned parameter
- Type: Integer
- Length: 32 bits
Contains additional information about the result of the call
when the return_code parameter contains a non-zero value other than
decimal 64 (atbcts_appc_not_available).
Table 1 lists
the valid reason codes.
- Return_code
- Returned parameter
- Type: Integer
- Length: 32 bits
Contains the result of the call. If the return_code parameter
contains zero or decimal 64 (atbcts_appc_not_available), there is
no reason code. For other return codes, check the reason_code parameter
for additional information about the result of the call.
Table 1 lists the valid return and reason codes for the Set_Allocate_Queue_Notification
service.
Table 1. Return and
Reason Codes for Set_Allocate_Queue_NotificationReturn Code (Decimal) |
Reason Code (Decimal) |
Symbolic Value |
---|
0 |
|
atbcts_ok |
8 |
|
atbcts_parameter_error |
|
17 |
atbcts_inval_alloc_queue_token |
|
18 |
atbcts_inval_notify_type |
|
26 |
atbcts_inval_event_notif_type |
|
27 |
atbcts_inval_event_code |
|
29 |
atbcts_inval_event_code_qual |
16 |
|
atbcts_request_unsuccessful |
|
8 |
atbcts_cannot_hold_locks |
|
20 |
atbcts_request_cancelled |
32 |
|
atbcts_service_failure |
|
16 |
atbcts_appc_service_failure |
64 |
|
atbcts_appc_not_available |
For more detailed information about these return codes
and reason codes, see Explanation of Return and Reason Codes.
|