Sessions: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
m (misc cleanup)
Line 1: Line 1:
   
   
<var class="product">Sirius Mods</var> provides several $functions to support
<var class="product">SOUL</var> provides several $functions to support sessions.
sessions.
A '''session''' is a workstream that might extend beyond a
A '''session''' is a workstream that might extend beyond a
<var class="product">Model 204</var> login session and might even be transferred among multiple
<var class="product">Model&nbsp;204</var> login session and might even be transferred among multiple
<var class="product">Model 204</var> threads or users.
<var class="product">Model&nbsp;204</var> threads or users.
Sessions are especially useful for web applications that require some
Sessions are especially useful for web applications that require some
context to be maintained over multiple web requests, each of which
context to be maintained over multiple web requests, each of which
Line 26: Line 25:
they are considered to be "owned by *", that is, owned by all users).
they are considered to be "owned by *", that is, owned by all users).
Non-privileged users can only create, access, and delete public sessions
Non-privileged users can only create, access, and delete public sessions
and those owned by themselves, that is, by their own userids.
and those owned by themselves, that is, by their own user IDs.
Privileged, that is system manager or system administrator users, can
Privileged, that is system manager or system administrator users, can
create, access, and delete public sessions and those owned by any user.
create, access, and delete public sessions and those owned by any user.
Line 32: Line 31:
To reestablish a session between logins (or within a login), each session
To reestablish a session between logins (or within a login), each session
requires an identifier called a '''session ID'''.
requires an identifier called a '''session ID'''.
The session ID is established when the session is created, and it can be changed
The session ID is established when the session is created, and it can be changed as needed.
as needed.
A session ID must be unique for a user ID, or for an entire Online if the
A session ID must be unique for a userid, or for an entire Online if the
session is public.
session is public.
   
   
Line 42: Line 40:
and changed whenever the session is closed.
and changed whenever the session is closed.


Arguments on <var>$Session_<i>xxx</i></var> calls, and some system parameters, control the timeout value of sessions.  One of these parameters, <var>[[SESMAXTO parameter|SESMAXTO]]</var>, can be reset to ensure that all sessions have a timeout value no more than the new value of <var>SESMAXTO</var>; this can result in immediate timeout of some sessions.
Arguments on <var>$Session_<i>xxx</i></var> calls, and some system parameters, control the timeout value of sessions.  One of these parameters, <var>[[SESMAXTO parameter|SESMAXTO]]</var>, can be reset to ensure that all sessions have a timeout value no greater than the new value of <var>SESMAXTO</var>; this can result in immediate timeout of some sessions.
   
   
There are several system parameters that control the availability
There are several system parameters that control the availability
Line 50: Line 48:
</th><td>The maximum number of private sessions that can be active. Setting this value allocates about 160 bytes of virtual storage for each possible session. The default value for <var>SESNPRV</var> is 0, which means that no private sessions can be created.
</th><td>The maximum number of private sessions that can be active. Setting this value allocates about 160 bytes of virtual storage for each possible session. The default value for <var>SESNPRV</var> is 0, which means that no private sessions can be created.
</td></tr>
</td></tr>
<tr><th><var>SESNPUB</var>
<tr><th><var>SESNPUB</var>
</th><td>The maximum number of public sessions that can be active. Setting this value allocates about 160 bytes of virtual storage for each possible session. The default value for <var>SESNPUB</var> is 0, which means that no public sessions can be created.
</th><td>The maximum number of public sessions that can be active. Setting this value allocates about 160 bytes of virtual storage for each possible session. The default value for <var>SESNPUB</var> is 0, which means that no public sessions can be created.
</td></tr>
</td></tr>
<tr><th><var>SESUMAX</var>
<tr><th><var>SESUMAX</var>
</th><td>The maximum number of private sessions that can be active for a single owner (userid). The default value for <var>SESUMAX</var> is 0, which means that a given userid can only have one session active at a time.
</th><td>The maximum number of private sessions that can be active for a single owner (user ID). The default value for <var>SESUMAX</var> is 0, which means that a given user ID can only have one session active at a time.
</td></tr>
</td></tr>
<tr><th><var>SESOPT</var>
<tr><th><var>SESOPT</var>
</th><td>A bitmask parameter that controls the behavior of the session feature. The meaning of the bits are:
</th><td>A bitmask parameter that controls the behavior of the session feature. The meaning of the bits are:
<table> <tr><th>X'01' </th><td>Clean up timed out sessions. If this bit is on and the X'02' bit is off, every <var>$Session_Create</var>, <var>$Session_Open</var>, <var>$Session_Close</var>, and <var>$Session_Delete</var> call cleans up timed out sessions. This cleanup could occur well after the timeout occurred if $Sessionxxx calls are relatively infrequent.
<table class="thJustBold">  
<tr><th>X'01' </th>
<td>Clean up timed-out sessions. If this bit is on and the X'02' bit is off, every <var>$Session_Create</var>, <var>$Session_Open</var>, <var>$Session_Close</var>, and <var>$Session_Delete</var> call cleans up timed-out sessions. This cleanup could occur well after the timeout occurred if $Session<i>xxx</i> calls are relatively infrequent.
<p>
<p>
Use this option if timed-out session cleanup is desired but it is not worth incurring the overhead of having a <var>PST</var> to do the cleanups. Since timed out sessions are now always immediately cleaned up, this bit is irrelevant. </p></td></tr>
Use this option for cleaning up a timed-out session, but it is not worth incurring the overhead of having a <var>PST</var> to do the cleanups. Since timed out sessions are now always immediately cleaned up, this bit is irrelevant. </p></td></tr>
 
<tr><th>X'02' </th>
<tr><th>X'02' </th>
<td>Create a <var>PST</var> to clean up timed out sessions. If this bit is on, a <var>PST</var> is attached in the Online whenever there is an active but not open session. If a session times out, the <var>PST</var> immediately deletes the session, freeing up the <var>CCATEMP</var> pages used by the session.
<td>Create a <var>PST</var> to clean up timed-out sessions. If this bit is on, a <var>PST</var> is attached in the Online whenever there is an active but not open session. If a session times out, the <var>PST</var> immediately deletes the session, freeing up the <var>CCATEMP</var> pages used by the session.
<p>
Use this option if cleaning up sessions very quickly is worth the (probably slight) cost of having a <var>PST</var> to do the cleanup. </p></td></tr>
</table>
<p>
<p>
Use this option if cleaning up sessions very quickly is worth the (probably slight) cost of having a <var>PST</var> to do the cleanup. </p></td></tr></table>
The default value for <var>SESOPT</var> is 0, which means that timed out sessions are not cleaned up and, in fact, can still be opened after timeout, if they have yet to be deleted. Under the default settings, sessions are only deleted when they are timed out, a new private or public sessions is being created, and the maximum like-typed (private or public) sessions are active. In this case, the oldest like-typed session is deleted. </p>
The default value for <var>SESOPT</var> is 0, which means that timed out sessions are not cleaned up and, in fact, can still be opened after timeout, if they have yet to be deleted. Under the default settings, sessions are only deleted when they are timed out, a new private or public sessions is being created, and the maximum like-typed (private or public) sessions are active. In this case, the oldest like-typed session is deleted.
<p>
Since a PST is now attached whenever there are any active sessions in an Online, this bit is irrelevant. The attached <var>PST</var> always actively deletes any timed-out sessions immediately. </p></td></tr>
Since a PST is now attached whenever there are any active sessions in an Online, this bit is irrelevant. The attached <var>PST</var> always actively deletes any timed-out sessions immediately.
 
</td></tr>
<tr><th><var>SESDEFTO</var> </th>
<tr><th><var>SESDEFTO</var> </th>
<td>Sets the default timeout value for a session if one is not specified in the $session_create call. The default value for <var>SESDEFTO</var> is 900, which indicates a default timeout of 900 seconds, or 15 minutes. If a session is not re-opened within the timeout value of the <var>$Session_Close</var>, it is considered timed-out and liable to deletion under control of the <var>SESOPT</var> flags, or immediately under <var class="product">Sirius Mods</var> 6.6 and later. The <var>SESDEFTO</var> setting can be overridden in many of the $SESSIONxxx functions.
<td>Sets the default timeout value for a session if one is not specified in the <var>$Session_Create</var> call. The default value for <var>SESDEFTO</var> is 900, which indicates a default timeout of 900 seconds, or 15 minutes. If a session is not re-opened within the timeout value of the <var>$Session_Close</var>, it is considered timed-out and liable to deletion under control of the <var>SESOPT</var> flags, or immediately. The <var>SESDEFTO</var> setting can be overridden in many of the <var>$Session<i>xxx</i></var> functions.
</td></tr>
</td></tr>
<tr><th><var>SESDEFOW</var>
 
</th><td>Sets the default open wait time value for a session if one is not specified in the <var>$Session_Open</var> call. The default value for <var>SESDEFTO</var> is 0, which means a <var>$Session_Open</var> call will not wait if the request session is in-use, that is, open by another thread.
<tr><th><var>SESDEFOW</var></th>
If a session is still in-use after the open wait time, a return code of 2 is set by <var>$Session_Open</var> to indicate the problem. The <var>SESDEFOW</var> setting can be overridden in the <var>$Session_Open</var> call.
<td>Sets the default open wait-time value for a session if one is not specified in the <var>$Session_Open</var> call. The default value for <var>SESDEFTO</var> is 0, which means a <var>$Session_Open</var> call will not wait if the request session is in-use, that is, open by another thread.
</td></tr></table>
If a session is still in-use after the open wait time, a return code of 2 is set by <var>$Session_Open</var> to indicate the problem.  
<p>
The <var>SESDEFOW</var> setting can be overridden in the <var>$Session_Open</var> call. </p></td></tr>
</table>
   
   
Sessions can contain both system and <var class="product">User Language</var> objects.
Sessions can contain both system and <var class="product">SOUL</var> objects.
When a session is closed, any objects associated with a session name,
When a session is closed, any objects associated with a session name,
either via [[Global and session objects#Binding global/session names to a variable|the Session keyword]] on a variable declaration or via a
by [[Global and session objects#Binding global/session names to a variable|the Session keyword]] on a variable declaration or by a
<var>[[Global and session objects#setsession|SetSession]]</var> method in the object class, &ldquo;follow the closed session&rdquo;
<var>[[Global and session objects#setsession|SetSession]]</var> method in the object class, "follow the closed session" and become logically owned by the session <var>PST</var>.
and become logically owned by the session <var>PST</var>.
   
   
In addition, any objects accessible indirectly from a session name
In addition, any objects accessible indirectly from a session name
also &ldquo;follow the session.&rdquo;
also "follow the session."
That is, if an object can be accessed via a session name and that
That is, if an object can be accessed by a session name and that
object contains a reference to another object, the latter object
object contains a reference to another object, the latter object
also &ldquo;follows the session&rdquo; when the session is closed.
also "follows the session" when the session is closed.
Because determining which objects can be accessed directly or
Because determining which objects can be accessed directly or
indirectly from a session name is very much like object
indirectly from a session name is very much like object
Line 96: Line 104:
Many of the data structures associated with sessions are also
Many of the data structures associated with sessions are also
associated with system-wide resources such as <var>CCATEMP</var> pages,
associated with system-wide resources such as <var>CCATEMP</var> pages,
virtual storage, record locks, <var class="product">Janus</var> threads, file locks, and
virtual storage, record locks, <var class="product">Janus</var> threads, file locks, and so on.
so on.
When a session is closed but not deleted, these resources are
When a session is closed but not deleted, these resources are
considered to be &ldquo;owned&rdquo; by the session <var>PST</var>, and so,
considered to be "owned" by the session <var>PST</var>; where possible, <var class="product">[[SirMon]]</var> tries to indicate this ownership.
where possible, <var class="product">[[SirMon]]</var> tries to indicate this ownership.


==See also==
==See also==

Revision as of 21:11, 9 October 2017

SOUL provides several $functions to support sessions. A session is a workstream that might extend beyond a Model 204 login session and might even be transferred among multiple Model 204 threads or users. Sessions are especially useful for web applications that require some context to be maintained over multiple web requests, each of which requires a login and logout. Sessions do not, of course, survive the cycling of the Online in which they were established, and they cannot be passed between Onlines.

Sessions are a collection of data structures that are accessible while the session is open and that persist as long as the session persists. These data structures include session $lists, session Longstrings, and session XmlDocs. Sessions can also contain objects, that is, instances of a class.

Sessions can be created with $Session_Create, re-opened with $Session_Open, closed with $Session_Close, and deleted with $Session_Delete. Only a single session may be open at a time on a thread, and any session that is open when a user logs off is automatically closed. A session can only be open on a single thread at any given time.

Sessions are owned by a specific user, or they are public (in which case they are considered to be "owned by *", that is, owned by all users). Non-privileged users can only create, access, and delete public sessions and those owned by themselves, that is, by their own user IDs. Privileged, that is system manager or system administrator users, can create, access, and delete public sessions and those owned by any user.

To reestablish a session between logins (or within a login), each session requires an identifier called a session ID. The session ID is established when the session is created, and it can be changed as needed. A session ID must be unique for a user ID, or for an entire Online if the session is public.

Inactive sessions, that is, those that haven't been opened in a long time, are considered timed out and are eligible for deletion. The inactivity time for a timeout can be set at session creation time and changed whenever the session is closed.

Arguments on $Session_xxx calls, and some system parameters, control the timeout value of sessions. One of these parameters, SESMAXTO, can be reset to ensure that all sessions have a timeout value no greater than the new value of SESMAXTO; this can result in immediate timeout of some sessions.

There are several system parameters that control the availability and behavior of the session feature:

SESNPRV The maximum number of private sessions that can be active. Setting this value allocates about 160 bytes of virtual storage for each possible session. The default value for SESNPRV is 0, which means that no private sessions can be created.
SESNPUB The maximum number of public sessions that can be active. Setting this value allocates about 160 bytes of virtual storage for each possible session. The default value for SESNPUB is 0, which means that no public sessions can be created.
SESUMAX The maximum number of private sessions that can be active for a single owner (user ID). The default value for SESUMAX is 0, which means that a given user ID can only have one session active at a time.
SESOPT A bitmask parameter that controls the behavior of the session feature. The meaning of the bits are:
X'01' Clean up timed-out sessions. If this bit is on and the X'02' bit is off, every $Session_Create, $Session_Open, $Session_Close, and $Session_Delete call cleans up timed-out sessions. This cleanup could occur well after the timeout occurred if $Sessionxxx calls are relatively infrequent.

Use this option for cleaning up a timed-out session, but it is not worth incurring the overhead of having a PST to do the cleanups. Since timed out sessions are now always immediately cleaned up, this bit is irrelevant.

X'02' Create a PST to clean up timed-out sessions. If this bit is on, a PST is attached in the Online whenever there is an active but not open session. If a session times out, the PST immediately deletes the session, freeing up the CCATEMP pages used by the session.

Use this option if cleaning up sessions very quickly is worth the (probably slight) cost of having a PST to do the cleanup.

The default value for SESOPT is 0, which means that timed out sessions are not cleaned up and, in fact, can still be opened after timeout, if they have yet to be deleted. Under the default settings, sessions are only deleted when they are timed out, a new private or public sessions is being created, and the maximum like-typed (private or public) sessions are active. In this case, the oldest like-typed session is deleted.

Since a PST is now attached whenever there are any active sessions in an Online, this bit is irrelevant. The attached PST always actively deletes any timed-out sessions immediately.

SESDEFTO Sets the default timeout value for a session if one is not specified in the $Session_Create call. The default value for SESDEFTO is 900, which indicates a default timeout of 900 seconds, or 15 minutes. If a session is not re-opened within the timeout value of the $Session_Close, it is considered timed-out and liable to deletion under control of the SESOPT flags, or immediately. The SESDEFTO setting can be overridden in many of the $Sessionxxx functions.
SESDEFOW Sets the default open wait-time value for a session if one is not specified in the $Session_Open call. The default value for SESDEFTO is 0, which means a $Session_Open call will not wait if the request session is in-use, that is, open by another thread.

If a session is still in-use after the open wait time, a return code of 2 is set by $Session_Open to indicate the problem.

The SESDEFOW setting can be overridden in the $Session_Open call.

Sessions can contain both system and SOUL objects. When a session is closed, any objects associated with a session name, by the Session keyword on a variable declaration or by a SetSession method in the object class, "follow the closed session" and become logically owned by the session PST.

In addition, any objects accessible indirectly from a session name also "follow the session." That is, if an object can be accessed by a session name and that object contains a reference to another object, the latter object also "follows the session" when the session is closed. Because determining which objects can be accessed directly or indirectly from a session name is very much like object garbage collection, a $Session_Close causes garbage collection to be performed for the invoking thread.

Many of the data structures associated with sessions are also associated with system-wide resources such as CCATEMP pages, virtual storage, record locks, Janus threads, file locks, and so on. When a session is closed but not deleted, these resources are considered to be "owned" by the session PST; where possible, SirMon tries to indicate this ownership.

See also