|
|
|
|
The lu0_init function activates a session for an LU0 application, and brings it up to the state where the LU session is ready for use.
int lu0_init (
AP_UINT32 *handle,
int options,
LU0_CALLBACK callback,
void *user,
char *local_lu,
char *partner_lu,
char *mode,
int *qualifier
);
The application supplies the following parameters:
An identifier for the LU0 session:
To start a new LU0 session (the normal case), specify a pointer to a value of zero.
To bring down and restart an existing LU0 session, specify the handle that was returned on the original lu0_init function call for the session. This is like issuing lu0_term followed by lu0_init. Any data that is queued within LU0 (waiting to be returned to the application or sent to the host) will be discarded; if there is an asynchronous lu0_read or lu0_write call outstanding, its callback routine will be called.
If the existing session has failed with a return_code of LU0_EVENT_INIT_FAILED, the session handle is no longer valid and you cannot use lu0_init to restart the session.
SNA options for the session. To use the default options, set this parameter to zero.
To control SNA options for the session, specify one or more of the following options, combined using a bitwise OR (|):
Send an INITSELF to the host to request the PLU to send a BIND. If this option is not specified, SNAP-IX waits for an unsolicited BIND from the host.
Set the RQD1 (definite response) flag on all RUs sent to the host. If this option is not specified, SNAP-IX sets RQE (exception response) on data RUs sent to the host.
If you use this option, lu0_write function calls on this session will not complete (and will block if issued synchronously) until the host sends a response.
This option is used only when restarting an existing session (as specified by the handle parameter), and is ignored when starting a new session.
Soft termination: terminate the existing session by sending SHUTC if SHUTD has been received, or RSHUTD otherwise, and waiting for UNBIND from the host. If this option is not specified, SNAP-IX terminates the existing session by sending UNBIND.
To use the synchronous version of lu0_init, specify a NULL pointer.
To use the asynchronous version of lu0_init, specify a pointer to a callback routine within the application. See Synchronous and Asynchronous LU0 Operation for more details.
If the application needs to check the BIND parameters supplied by the host, or intends to use asynchronous LU0 functions for later processing on this session, it must use the asynchronous version of lu0_init to start the session. If it uses the synchronous version, it cannot check the BIND parameters, and can use only synchronous LU0 functions for later processing.
The callback routine supplied on lu0_init is used throughout the lifetime of the session to return information about session events, as well as returning the results of the lu0_init function call. It must remain valid until the application receives a successful response to an lu0_term to end the session (or to an lu0_init function to restart the session with a new callback routine).
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 name in ASCII of the LU or LU pool for which you want to start the session. This must match the name of an LU of type 0, or of an LU pool, configured for SNAP-IX. If lu0_init is being used to restart an existing session (as specified by the handle parameter), this LU name must be the same as on the original lu0_init function that started the session.
This parameter is a string of 1-8 A-string characters followed by a NULL character.
Only one LU0 session can use the LU at a time. After lu0_init has completed successfully, the LU is reserved for use by this session until the application successfully issues lu0_term to terminate the session.
This parameter is used only if the options parameter
is set to
The name in ASCII of the primary LU to connect to. Check with your host personnel to determine the name to use.
This parameter is a string of 1-8 A-string characters followed by a NULL character.
This parameter is used only if the options parameter
is set to
The name in ASCII of the mode that LU0 should use to send INITSELF. Check with your host personnel to determine the name to use.
This parameter is a string of 1-8 A-string characters followed by a NULL character.
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, some supplied parameters are returned immediately, before a callback is made. The progress of the session initialization, and any subsequent session events, are then reported using the application's callback routine.
The function returns one of the following values:
Session initialization has begun. Initialization progress, and later session events, will be reported using the supplied callback routine. The handle parameter is now valid, and can be used to identify the session if the application needs to issue lu0_term before initialization has completed.
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. The supplied callback routine will not be called for this function.
If lu0_init was being used to start a new session, no session was started. The handle parameter is not valid and must not be used.
If lu0_init was being used to restart an existing session, the session state is unchanged.
If the return value is LU0_EVENT_IN_PROGRESS, lu0_init returns the following parameters.
If lu0_init is being used to start a new session (as specified by the handle parameter), LU0 returns a handle identifying the new session. The application can use this handle to identify the session if it needs to issue lu0_term before initialization has completed. After the session activation has completed (as reported to the callback routine by an event parameter of LU0_EVENT_ACTIVE), the application then uses this handle on subsequent lu0_read or lu0_write function calls to identify this session.
This parameter is not used for the asynchronous version of lu0_init. The application can supply a null pointer on the lu0_init call.
If the return value from the lu0_init function is LU0_EVENT_IN_PROGRESS, LU0 calls the application's callback routine to report the progress of the session initialization or to report subsequent session events. 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_init function. This allows the application to correlate the callback with the original request.
The initialization event or session event being reported.
The following events can occur during initialization:
An ACTLU has been received from the host. This is reported to the application for information only; no action is required.
A BIND has been received from the host. The received BIND RU is supplied to the callback routine in the data parameter, and its length is supplied in the data_length parameter.
Any BIND checking required by the application must be done within the callback routine:
To accept the BIND, the callback routine simply returns without making any further LU0 function calls.
To reject the BIND, the callback routine issues lu0_term for the session. It must use the asynchronous version of lu0_term because the callback routine must not block.
When the callback routine terminates, LU0 responds to the BIND (with a negative response if the callback routine issued lu0_term, and a positive response otherwise).
The session has been initialized successfully (SDT has been received). The application can now send and receive data on the session.
Session initialization has failed. If there is a sense code associated with the failure, it is reported to the callback routine in the qualifier parameter. The SNAP-IX error log file contains more details of the failure.
The session has been terminated, and the handle provided on the lu0_init call is no longer valid. The application cannot make any further LU0 function calls using this session handle.
The following session events can be reported after initialization has completed:
The session has failed, either because the host has sent UNBIND or because an error occurred. If there is a sense code associated with the failure, it is reported to the callback routine in the qualifier parameter. The SNAP-IX error log file contains more details of the failure.
The application can still read any queued data from the host that was received before the session failed, but it is not required to do so. It must then either terminate the session to leave the LU available for use by other applications, or attempt to 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.
When the application terminates or restarts the session, any remaining queued data is discarded.
The host has sent SHUTD.
The application can use lu0_write function calls
to send any outstanding data, or lu0_read function calls
(typically with the
After dealing with any outstanding data, the application can either terminate the session or restart it. The host will expect the application to do this quickly.
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 CLEAR.
The application must not make any more lu0_write
function calls, but can make lu0_read function calls
(typically with the
The host will normally follow CLEAR with either SDT (reported to the callback routine using an event value of LU0_EVENT_ACTIVE) or UNBIND (reported to the callback routine using an event value of LU0_EVENT_INIT_SESS_FAIL ).
The host has sent an SDT following a previous CLEAR. The application can now send and receive data on the session.
If event is set to LU0_EVENT_INIT_FAILED or LU0_EVENT_INIT_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.
If event is set to LU0_EVENT_BIND , this parameter specifies the length of the BIND RU passed to the callback routine in the data parameter; otherwise it is not used.
If event is set to LU0_EVENT_BIND , this parameter points to a copy of the BIND RU received from the host; otherwise it is not used.
The application should check the contents of the BIND to determine whether to accept or reject it, but must not modify the supplied data.
If a callback routine was not specified, the function blocks until the session has been established (or until LU0 determines that the session cannot be established), and then returns with a value indicating whether the session was established successfully.
The function returns one of the following values:
The session has been initialized successfully. The application can now send and receive data on the session.
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.
If lu0_init was being used to start a new session, no session was started.
If lu0_init was being used to restart an existing session, the session was not restarted and its state is unchanged.
Session initialization has failed. If there is a sense code associated with the failure, it is reported to the callback routine in the qualifier parameter. The SNAP-IX error log file contains more details of the failure.
The session has been terminated, and the application cannot make any further LU0 function calls for it.
If the function executes successfully, LU0 returns the following parameters.
If lu0_init was used to start a new session (as specified by the handle parameter), and the return value is LU0_EVENT_ACTIVE, LU0 returns a handle identifying the new session. The application then uses this handle on subsequent function calls to identify this session. For other return values, indicating that the session was not started successfully, this parameter is not used.
If the return value is LU0_EVENT_INIT_FAILED, 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.
This function must be the first LU0 function issued for the session. Until this function has completed successfully, the only other LU0 function that can be issued for this session is lu0_term (which will terminate a pending asynchronous lu0_init ).
All other functions issued on this session must identify the session using the handle parameter returned on this function.
The lu0_init function completes after the host has sent ACTLU, BIND, and SDT. If necessary, the verb waits indefinitely. If an ACTLU has already been received prior to the lu0_init function, LU0 sends a NOTIFY to the host to inform it that the LU is ready for use.
Once the lu0_init function has completed successfully, the application has exclusive use of the LU for which the session was started. No other session (from this or any other application) can use the LU until the lu0_term function has completed.
|
|
|
 |
|