$Session Create: Difference between revisions

Latest revision as of 12:19, 10 July 2017

Create a new session

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Session_Create function is the SetSession subroutine.

$Session_Create creates a new session, and it returns a zero, indicating success, or a number indicating the cause of error, if there is one.

Syntax

%rc = $Session_Create(sesid, [owner], [timeout], [opts])

sesid The ID to be given to the new session. This is a required argument.

owner The userid that will own this session. An owner value of asterisk (*) means that the session is public, that is available to all users. Only a system administrator can create a non-public session for a user other than itself. This optional argument defaults to the creating user's userid.

timeout The time after a $Session_Close (or logout) after which the session is considered timed-out, that is, eligible for deletion. A value of -1 means use the SESDEFTO parameter value. This optional argument defaults to -1, that is the SESDEFTO parameter value.

opts

A blank-delimited set of options to control the create process. The options are:

OPEN	Automatically open the session upon creating it. This is the default behavior.
NOOPEN	Don't automatically open the session upon creating it. This is not the default behavior but might be useful if creating a session for another user or creating many sessions at once.

Return codes

%rc is set to 0 or to an error indicator.

0 - No errors 1 - Session id already exists for user 2 - Online session limit exceeded 3 - User session limit exceeded

Example

The following example creates a session called GROUCHO, followed by a timestamp then sets a cookie for a web application so that the session can be easily located on subsequent web requests.

%sesid = 'GROUCHO' WITH $SirTime %rc = $Session_Create(%sesid, , 3600) %rc = $Web_Set_Cookie('SESID', %sesid)

Products authorizing $Session_Create

@@ Line 2: / Line 2: @@
 <span class="pageSubtitle">Create a new session</span>
-<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Session_Create function is <b>[[to be entered]]</b>.</p>
+<p class="warn"><b>Note:</b> Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Session_Create function is the <var>[[SetSession (Object subroutine)|SetSession]]</var> subroutine.</p>
-<var>$Session_Create</var> creates a new [[Sessions|session]], accepts four arguments and returns a zero, indicating success, or a number indicating the cause of error, if there is one.
+<var>$Session_Create</var> creates a new [[Sessions|session]], and it returns a zero, indicating success, or a number indicating the cause of error, if there is one.
-The first argument is the ID to be given to the new session. This is a required argument.
+==Syntax==
+<p class="syntax"><span class="term">%rc</span> = <span class="literal">$Session_Create</span>(<span class="term">sesid</span>, [<span class="term">owner</span>], [<span class="term">timeout</span>], [<span class="term">opts</span>])
+</p>
+<table>
+<tr><th>sesid</th>
+<td>The ID to be given to the new session. This is a required argument.</td></tr>
-The second argument is the userid that will own this session. An '''owner''' of "*" means that the session is public, that is available to all users. Only a system administrator can create a non-public session for a user other than itself. This optional argument defaults to the creating user's userid.
+<tr><th>owner</th>
+<td>The userid that will own this session. An '''owner''' value of asterisk (<tt>*</tt>) means that the session is public, that is available to all users. Only a system administrator can create a non-public session for a user other than itself. This optional argument defaults to the creating user's userid. </td></tr>
-The third argument is the time after a <var>[[$Session_Close]]</var> (or logout) after which the session is considered '''timed-out''', that is, eligible for deletion. A value of -1 means use the <var>[[SRSDEFTO parameter|SRSDEFTO]]</var> parameter value. This optional argument defaults to -1, that is the <var>SRSDEFTO</var> parameter value.
+<tr><th>timeout</th>
+<td>The time after a <var>[[$Session_Close]]</var> (or logout) after which the session is considered '''timed-out''', that is, eligible for deletion. A value of -1 means use the <var>[[SESDEFTO parameter|SESDEFTO]]</var> parameter value. This optional argument defaults to -1, that is the <var>SESDEFTO</var> parameter value. </td></tr>
-The fourth argument is a blank delimited set of options to control the create process. The options are:
+<tr><th>opts</th>
-<table class="syntaxTable">
+<td>A blank-delimited set of options to control the create process. The options are:
+<table class="thJustBold">
 <tr><th>OPEN</th>
 <td>Automatically open the session upon creating it. This is the default behavior.</td></tr>
 <tr><th>NOOPEN</th>
 <td>Don't automatically open the session upon creating it. This is not the default behavior but might be useful if creating a session for another user or creating many sessions at once.
+</td></tr></table>
 </td></tr></table>
-==Syntax==
+===Return codes===
-<p class="syntax"><span class="term">%rc</span> = <span class="literal">$Session_Create</span>(<span class="term">sesid</span>, <span class="term">owner</span>, <span class="term">timeout</span>, <span class="term">opts</span>)
+<p>
-</p>
+<var class="term">%rc</var> is set to 0 or to an error indicator.</p>
-<p class="caption">$Session_Create function
+<p class="code">0 - No errors
-</p>
+- Session id already exists for user
-<p>%RC is set to 0 or to an error indicator.</p>
+- Online session limit exceeded
-<p class="code">
+- User session limit exceeded
-- No errors
-- Session id already exists for user
-- Online session limit exceeded
-- User session limit exceeded
-</p>
-<p class="caption">$Session_Create return codes
 </p>
-The following example creates a session called "GROUCHO" followed by a timestamp then sets a cookie for a web application so that the session can be easily located on subsequent web requests.
+==Example==
-<p class="code"> %SESID = 'GROUCHO' WITH $SirTime
+The following example creates a session called <code>GROUCHO</code>, followed by a timestamp then sets a cookie for a web application so that the session can be easily located on subsequent web requests.
- %RC = $Session_Create(%SESID, , 3600)
+<p class="code">%sesid = 'GROUCHO' WITH $SirTime
- %RC = $WEB_SET_COOKIE('SESID', %SESID)
+%rc = $Session_Create(%sesid, , 3600)
+%rc = $Web_Set_Cookie('SESID', %sesid)
 </p>
 ==Products authorizing {{PAGENAMEE}}==
 <ul class="smallAndTightList">
-<li>[[Sirius functions]]</li>
+<li>[[List of $functions|Sirius functions]]</li>
 <li>[[Fast/Unload User Language Interface]]</li>
-<li>[[Janus Open Client]]</li>
+<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
-<li>[[Janus Open Server]]</li>
+<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
 <li>[[Janus Sockets]]</li>
 <li>[[Janus Web Server]]</li>
-<li>[[Japanese functions]]</li>
+<li>Japanese functions</li>
-<li>[[Sir2000 Field Migration Facility]]</li>
+<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
 </ul>
-<p>
-</p>
 [[Category:$Functions|$Session_Create]]