Asynchronous Requests
When Read Structured Fields is requested
asynchronously (the A option in the data string), the application cannot assume:
- The return code is correct.
- The data in the communications buffer (read buffer) is correct.
- The host is no longer processing the Read Structured Fields request.
When requested asynchronously, EHLLAPI returns the following values:
- A 16-bit Request ID in positions 13–14 (9–10 for standard interface) of the data string
- The address of a event object in positions 17—20 of the data string
These are used to complete the asynchronous Read Structured Fields call.
The following steps must be completed to determine the outcome
of an asynchronous Read Structured Fields function
call:
- If the EHLLAPI return code is not zero, the request failed. No asynchronous request has been made. The application must take appropriate actions before attempting the call again.
- If the return code is zero, the application should wait until the event object is in the signaled state by using the Get Request Completion (125) function or Wait For Single Object. The event object should not be reused. The event object is valid only for the duration of the Read Structured Fields function call through the completion of the Get Request Completion (125) function call.
- Once the event object is in the signaled state, use the returned 16-bit Request ID as the Request ID parameter in a call to the Get Request Completion (125) function. The data string returned from the Get Request Completion (125) function call contains the final return code of the Read Structured Fields function call.
When Read Structured Fields is requested
asynchronously (the M option in the data string), the application cannot assume:
- The return code is correct.
- The data in the communications buffer (read buffer) is correct.
- The host is no longer processing the Read Structured Fields request.
When requested asynchronously with the M option, EHLLAPI returns
the following values:
- A 16-bit Request ID in positions 13–14 (9–10 for standard interface) of the data string
- Task ID of asynchronous message mode in positions 17–18 (11–12 for standard interface) of the data string.
These are used to complete the asynchronous Read Structured Fields call.