Parameters for Set_Allocate_Queue_Notification
- 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_Notification Return 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.