Parameters for Get_Event

The following section describes the parameters you specify when calling the Get_Event 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.

Event_get_type
Supplied parameter
  • Type: Integer
  • Length: 32 bits

Specifies whether the call is allowed to wait for a new event element to be added to the event queue, if the event queue currently contains no elements.

Valid values for this parameter are:
Value
Meaning
1
atbcts_immediate

Control is to be returned to the caller immediately, regardless of whether an event element can be retrieved. If an event element is not immediately available, APPC/MVS sets return_code to 16 (atbcts_request_unsuccessful) and reason_code to 30 (atbcts_no_event_available).

2
atbcts_wait

This call remains active until an event element can be retrieved, or the call is cancelled.

Event_code
Returned parameter
  • Type: Integer
  • Length: 32 bits

Contains a value that indicates which event has occurred.

Possible values returned for this parameter are:
Value
Meaning
1
atbcts_allocate_queue_min

The allocate queue indicated in the event element has decreased to its minimum threshold.

2
atbcts_allocate_queue_max

The allocate queue indicated in the event element has increased to its maximum threshold.

Event_timestamp
Returned parameter
  • Type: Character string
  • Char Set: N/A
  • Length: 8 bytes

Contains a timestamp that shows when the event occurred. This timestamp is in the format provided by the STORE CLOCK (STCK) assembler instruction.

Event_buffer_length
Supplied parameter
  • Type: Integer
  • Length: 32 bits

Specifies the length, in bytes, of the event buffer (the event_buffer parameter) where the event element is to be placed.

Event_buffer
Supplied/Returned parameter
  • Type: Character string
  • Char Set: No restriction
  • Length: Variable (specified in event_buffer_length parameter)

Specifies an area of storage where the event element is to be placed. The event buffer must reside in the caller's primary address space and be accessible to the caller's PSW key.

If the buffer you specify is large enough to contain the event element, APPC/MVS places the event element in this buffer on return to the caller. APPC/MVS sets the event_element_size parameter to the length of the storage used to contain the returned element.

If the buffer you specify is not large enough, APPC/MVS fails the Get_Event request with return code 16 (atbcts_request_unsuccessful) and reason code 41 (atbcts_buffer_too_small). APPC/MVS sets the event_element_size parameter to the length of storage it requires to satisfy this request. To retrieve the event element successfully, specify an event buffer equal to the event_element_size and call the Get_Event service again.

To determine whether the event was a minimum or maximum threshold, check the value returned in the event_code parameter. Table 1 shows the contents of event_buffer, based on the event_code value:
Table 1. Relationship Between Event_code and Event_buffer
Event_code Value: Event_buffer Contents:
1 The event buffer contains two fields (12 bytes):
  • Allocate_queue_token (character string - 8 bytes). Indicates the allocate queue for which this event applies.
  • Minimum queue size (integer - 32 bits). Indicates that the specified allocate queue decreased to this size.
2 The event buffer contains two fields (12 bytes):
  • Allocate_queue_token (character string - 8 bytes). Indicates the allocate queue for which this event applies.
  • Maximum queue size (integer - 32 bits). Indicates that the specified allocate queue increased to this size.
Event_element_size
Returned parameter
  • Type: Integer
  • Length: 32 bits

Contains the length of the event element that was retrieved, or the length that APPC/MVS requires to satisfy this request (if the call is unsuccessful).

To determine whether the request was successful, check the value in the return_code parameter, as follows:
  • If return_code contains zero, the event_buffer parameter contains the event element. APPC/MVS sets event_element_size to the length of the event element that was returned.
  • If return_code contains 16 (atbcts_request_unsuccessful), and reason_code contains 41 (atbcts_buffer_too_small), event_element_size contains the length required to satisfy the request. To retrieve the event element successfully, create a larger event buffer equal to this length and call the Get_Event service again.
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 2 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 2 lists the valid return and reason codes for the Get_Event service.
Table 2. Return and Reason Codes for Get_Event
Return Code (Decimal) Reason Code (Decimal) Symbolic Value
0   atbcts_ok
8   atbcts_parameter_error
  18     atbcts_inval_notify_type
  37     atbcts_inval_event_get_type
16   atbcts_request_unsuccessful
  7     atbcts_parameter_inaccessible
  8     atbcts_cannot_hold_locks
  20     atbcts_request_cancelled
  30     atbcts_no_event_available
  31     atbcts_event_notify_cancelled
  32     atbcts_get_event_outstanding
  33     atbcts_notify_not_set
  41     atbcts_buffer_too_small
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, refer to Explanation of Return and Reason Codes.

Parent topic: Get_Event