As said previously, it is recommended that an application open explicit sessions, as this provides more control over the system’s resources and performance.

To request an explicit session, an

ssan3_open call

should be done passing a Session-ID of -1. This will cause a new valid Session-ID to be allocated and returned to the calling program (example, Session-ID 1048576), providing SSA-NAME3 with a handle to the initialized resources. It is this Session-ID (example, 1048576) that should be used for all subsequent SSA-NAME3 calls in the current transaction/ process in order for it to use the same session.

Do not pass a value of "-1" in the Session-ID field of a function unless you wish to force SSA-NAME3 to do an implicit

ssan3_open

again.

A session allocated through an

ssan3_open call

is locked and cannot be re-used by another session until released through the

ssan3_close call

, or by exceeding an inactivity time-out value as discussed below.

Once a session is finished with, it should be released through the

ssan3_close

call using the allocated Session-ID (example, 1048576). The Session-ID is then set to -1 by the

ssan3_close

call.

If it is likely to be common that sessions will be left open and become inactive, without being explicitly closed, then it is possible to control the length of time a session is held by SSA-NAME3. An inactivity time-out value (in seconds) may be passed in the

ssan3_open

call, or if using the SSA-NAME3 server, may be specified as a server start-up parameter. Once a period of inactivity has reached the time-out value, the session may be closed and reallocated to another caller. If the original caller tries to later reuse that session, it will be allocated a new Session-ID and cause the initialization process to be repeated.

If an explicit

ssan3_open

call is not made, an implicit or "ephemeral" session is initiated for the calling application. An ephemeral session will be created if:

While ephemeral opens save the application from issuing the

ssan3_open

call, if SSA-NAME3 at some stage runs out of session handles, it may allocate a new session to an existing ephemeral session slot.

This means that the next call from the application who’s ephemeral session was re-used will cause the initialization process to be repeated, and may lead to some performance degradation.

SSA-NAME3 will overwrite ephemeral sessions before checking for timed-out sessions.

Once a session is finished with, it should be released through the

ssan3_close

call.