|
|
|
|
The lu0_read function receives a complete chain of data sent by the host to the LU0 application's LU. It can either wait until data is available, or return immediately if a complete chain of data is not available when it is issued.
int lu0_read (
AP_UINT32 *handle,
int options,
LU0_CALLBACK callback,
void *user,
int buffer_length,
char *buffer,
int *length,
int *qualifier
);
The application supplies the following parameters:
The identifier that was returned on the original lu0_init function call for the LU0 session.
Specifies whether the function should wait for data to be received, or return immediately if no data is available.
To wait for data if a complete chain of data is not available when lu0_read is issued, set this parameter to zero.
If lu0_read is issued asynchronously, the callback routine will not be called until a complete chain of data has been received and can be passed to the application.
If lu0_read is issued synchronously, the function will block until a complete chain of data has been received and can be passed to the application. The function may block indefinitely if the host does not send data.
To return immediately if a complete chain of data is not available when lu0_read is issued, specify the following value:
The function returns immediately if a complete chain of data is not available when it is issued.
If lu0_read is issued asynchronously, the callback routine is called with an event parameter indicating that no data is available. The application does not receive further callbacks if data arrives subsequently; it must periodically issue lu0_read to check for received data.
If lu0_read is issued synchronously, the function will return quickly and allow the application to continue with other processing.
To use the synchronous version of lu0_read, specify a NULL pointer.
To use the asynchronous version of lu0_read, specify a pointer to a callback routine within the application. See Synchronous and Asynchronous LU0 Operation for more details.
If the application uses the synchronous version of lu0_read
, the function may block indefinitely if no data is available.
To avoid this, it can use the
This parameter is used only for asynchronous calls.
A pointer to an optional user data string supplied by the application; typically used for the application's session identifier or for a pointer to a control block. The format of this data is defined by the application; SNAP-IX does not use this data, but returns it unchanged as a parameter to the callback routine when returning information related to this function call. This allows the application to correlate the callback with the original request.
The length in bytes of the supplied data buffer. This can be any value from 1 to the maximum value of an integer (a length of zero is not allowed).
A data area into which LU0 can write the received data.
If the application uses the asynchronous version of lu0_read , the data area must remain valid until the callback function has completed. This means that the data area must not be declared on the stack.
If a callback routine was specified, the function does not block, and returns a value to indicate whether the function was issued successfully. If it was successful, the received data (if any) is then reported using the application's callback routine.
The function returns one of the following values:
The function was issued successfully. Received data (or a session failure event if this occurs first) will be reported to the application using the supplied callback routine.
LU0 could not process the function, either because the application supplied parameters that were not valid (for example, it tried to issue a second lu0_read before the first has completed) or because an error occurred within SNAP-IX. The SNAP-IX error log file contains more details of the error. The supplied callback routine will not be called for this function.
The asynchronous version of lu0_read does not return any parameters. The application can supply a null pointer for the qualifier and length parameters.
If the return value from the lu0_read function is LU0_EVENT_IN_PROGRESS, LU0 calls the application's callback routine when data is received or to report a session failure. The parameters supplied to the callback routine are as follows.
The session handle that was returned on the lu0_init function.
The user data that was supplied on the lu0_read function. This allows the application to correlate the callback with the original request.
The event being reported. This is one of the following:
A complete chain of data has been received from the host and written to the application's specified data area.
The application should use the data_length and data parameters supplied to the callback routine to read and process the data.
A complete chain of data has been received from the host, but the application's specified buffer length was too short to contain it. The start of the data has been written to the application's data area, but the excess bytes have been discarded.
The application should use the data_length and data parameters supplied to the callback routine to read and process the data.
LU0 did not have a complete chain of data received from the host when
the application issued lu0_read, and the application
specified the
No further calls will be made to the callback routine, even if data is subsequently received. The application must issue further lu0_read calls to obtain any subsequent data.
The application issued lu0_term (or lu0_init to restart the session) while lu0_read was outstanding. No data will be returned.
The session termination event is reported to the lu0_read function's callback routine to ensure that the routine is always called once, and to allow the application to do any cleanup processing specific to this routine.
This parameter is not used for the asynchronous version of lu0_read. The application can supply a null pointer to the function call.
If event is set to LU0_EVENT_DATA_OK or LU0_EVENT_DATA_TRUNCATED, this parameter specifies the length of valid data passed to the callback routine in the data parameter. This may be shorter than the buffer length supplied by the application in the lu0_read request parameters; the application should not attempt to use data beyond this length.
A returned data length of zero is valid, and indicates that the host sent a null-length chain of data.
If event is set to any other value, this parameter is not used.
This parameter points to the buffer parameter supplied on the lu0_read function call. If event is set to LU0_EVENT_DATA_OK or LU0_EVENT_DATA_TRUNCATED, this buffer now contains the received data. If event is set to any other value, this parameter is not used.
Whatever event is reported in the callback function, LU0 has now finished using the data area. If the application obtained this memory dynamically, it may need to free it.
If a callback routine was not specified, the function may either block or return immediately. The function returns immediately if one of the following is true:
LU0 detects an error in the supplied parameters.
A complete chain of data is already available when the function is issued.
A SHUTD or UNBIND has been received from the host, or LU0 has detected that the session has failed, but this has not yet been reported to the application.
A complete chain of data is not available, and the application
specified the
Otherwise, the function blocks until one of the following occurs:
A complete chain of data is received from the host.
A SHUTD or UNBIND is received from the host, or LU0 detects that the session has failed.
The function then returns with a value indicating whether data was received successfully.
The function returns one of the following values:
A complete chain of data has been received from the host and written to the application's specified data area.
The application should use the returned length and buffer parameters to read and process the data.
A complete chain of data has been received from the host, but the application's specified buffer length was too short to contain it. The start of the data has been written to the application's data area, but the excess bytes have been discarded.
The application should use the returned length and buffer parameters to read and process the data.
LU0 did not have a complete chain of data received from the host when
the application issued lu0_read, and the application
specified the
LU0 could not process the function, either because the application supplied parameters that were not valid or because an error occurred within SNAP-IX. The SNAP-IX error log file contains more details of the error. No data was returned.
The session failed, or an UNBIND was received from the host, before lu0_read was issued or while it was outstanding. LU0 will supply all available data to the application before it returns this value.
The application must not issue any further lu0_read or lu0_write calls. It can either terminate the session or restart it.
To terminate the session, it issues lu0_term.
To restart the session, it issues lu0_init using the existing session handle and LU name.
The host has sent SHUTD. All data received by LU0 has already been passed to the application, and no more data will be returned.
The application can use lu0_write function calls to send any outstanding data. It must then either terminate the session to leave the LU available for use by other applications, or attempt to restart it. The host will expect the application to do this as quickly as possible.
To terminate the session, it issues lu0_term.
To restart the session, it issues lu0_init using the existing session handle and LU name.
If the function executes successfully, LU0 returns the following parameters.
If the return value is LU0_EVENT_DATA_OK or LU0_EVENT_DATA_TRUNCATED, this parameter points to the received data.
For any other return value, this parameter is not used.
If the return value is LU0_EVENT_DATA_OK or LU0_EVENT_DATA_TRUNCATED, this parameter specifies the length of valid data returned in the buffer parameter. This may be shorter than the buffer length supplied by the application in the lu0_read request parameters; the application should not attempt to use data beyond this length.
A returned data length of zero is valid, and indicates that the host sent a null-length chain of data.
For any other return value, this parameter is not used.
If the return value is LU0_EVENT_READ_SESS_FAIL, and there is an SNA sense code or LU0-specific sense code associated with the failure, this parameter contains the sense code. Otherwise this parameter is not used.
|
|
|
 |
|