Accessing an existing session

To allow an ITP/Server job to access to an existing session, the session identifier must be passed from the client application to ITP/Server when the job is submitted. This is similar to how the job ID is specified. The called job will then be associated with the session that was specified, and the scripts will be able to access the data stored in the session. It is not possible for a job that is already running, and that is not yet associated with a session, to associate with an existing session. For more information on how to pass a session identifier to ITP/Server when submitting a job, refer to the documentation of the ITP/Server API that is being used, in the ITP/Server Manual, chapter Integrating.

When a script requires access to a session, it should always check that it is actually running in a session by testing the value of _session_active, as follows:

If Not _session_active Then

  ThrowError Message("This service requires a session.");

Fi;

Note:

When a client application passes a session identifier to ITP/Server that does not correspond to an existing session, the job will proceed to run normally. No error will be generated. This is an additional reason to always include a check for an active session, at the beginning of each script that requires the use of a session.

If the script is running in a session, it can use the data from the session's storage directory, for instance the file "data.xml" that was stored in the preceding example:

ITPRun

  Model("mymodel")

  Keys( "data.xml" [_sessiondir, ] );

The script can also retrieve string values from stored session parameters, for example:

Var Text X = get_sessionparameter ("my_stored_info");  # returns "3.14"

Note:

ITP/Server will not simultaneously run multiple jobs that are submitted with the same session identifier. If two jobs are simultaneously submitted with the same session identifier, they are run in series. The reason for this behavior is to prevent simultaneous access to the same session storage by multiple scripts. Such simultaneous access could lead to conflicts and hard-to-reproduce problems.

It is important to realize that this serialization also takes place when the session identifiers of the submitted jobs do not correspond to valid sessions. This means that passing a fixed, non-empty session ID to jobs is currently not acceptable, because the jobs will not be able to use the resources of more than one Document Processor. This behavior is an implementation detail and is subject to future change. We strongly advise to avoid depending on this behavior.