Object. LassoSession is the interface through which database activity is performed. Although one LassoSession object is pre-created when any JavaScript is executed (see the lasso.defaultSession property), LassoSessions may be created at any time.
A LassoSession object allows the scripter to set the InputParameters so the session can be executed and the ResultSet can be accessed.
The LassoSession object also allows variables to be set and retrieved. These variables are shared among all the LassoSession objects for the current request and persist until the page is returned to the HTTP client. LassoSession variables can be useful for sharing information between the LDML and JavaScript portions of a Lasso format file. LassoSession variables are not JavaScript properties and can only be accessed using the provided variable related methods.
The LassoSession object has the following methods:
|
Method |
Description |
|---|---|
| execute | Executes the session. Performs the actions specified in the input parameters and creates the result set. |
| getResultCode | Returns the result code generated by the session. |
| getResultMessage | Returns the result message generated by the session. |
| getVariable | Returns a specified session variable. |
| setVariable | Sets the value of a specified session variable. |
| getVariableCount | Returns the number of values a specified session variable has. |
| getVariables | Returns an array of all the current session variables. |
| hasExecuted | Returns true if the session has been executed at least once; otherwise it returns false. |
| getResultSet | Returns the ResultSet object for the session. |
| getInputParameters | Returns the InputParameters object for the session. |
Calling Lasso substitution tags
Method. Executes the current session. Performs the actions specified in the InputParameters object and creates the ResultSet.
execute()
None.
Nothing.
execute should be called after all the input parameters for the database activity have been set. The database activity specified in the session's input parameters object will be performed and the result set will be created. A session can be executed multiple times, but only after the result set has been closed (after which hasExecuted will return false).
See the examples provided for the LassoSession object.
Method. Returns the result code for the session.
getResultCode()
None.
A numeric result code.
A session's result code is automatically generated based on the result of the database activity. Lasso generated error codes are detailed in the Lasso documentation. A result code of zero indicates that no errors occurred.
This example will retrieve the result code then test it to see if it is non-zero.
var res = mySession.getResultCode();
if ( res != 0 ) // an error has occurred
{
write( "We have problems: " , res );
}
See the examples provided for the LassoSession object.
Method. Returns the textual result message for the session.
getResultMessage()
None.
A String containing the result message.
A session's result message is automatically generated based on the result of the database activity. All Lasso generated error codes have textual messages associated with them and are detailed in the Lasso documentation.
This example will access the current result code and test it to see if it is non-zero. If it is, it will print the result message to the client.
var res = mySession.getResultCode();
if ( res != 0 )
{
write( "We have a problem: ", mySession.getResultMessage() );
}
See the examples provided for the LassoSession object.
Method. Returns the value for a specified variable.
getVariable( varName[, varIndex] )
varName is the name of the variable to retrieve.
varIndex is the optional index of the variable value to retrieve.
A String containing the value.
This method is used to return the value of a specified variable. Variables can have multiple values and getVariable can take an optional index as the second parameter to specify which variable value to return. Indexes to the variable values are zero based (i.e. variable value 0 is the first value).
This example will retrieve the second value of a variable.
var theVal = mySession.getVariable( "MyVariable", 1 ); // 0 is the first, 1 is the second
Method. Sets the value for the specified variable.
setVariable( varName, varValue[, varIndex] )
varName is the name of the variable to set.
varValue is the value to set the variable to.
varIndex is the option index of the variable value to set.
Nothing.
setVariable can be used to create a new variable or to replace the value of an already existing variable. Variables can have multiple values and setVariable takes an optional index parameter to indicate which variable value to set.
This example sets the second value of a variable.
mySession.setVariable( "MyVariable", "A Value", 1 );
Method. Returns the number of values a variable has.
getVariableCount( varName )
varName is the name of the variable to check.
A number indicating the number of values the variable has.
var varCount = mySession.getVariableCount( "MyVariable" );
Method. Returns all the variables currently defined.
getVariables()
None.
An object containing a property named after each variable.
This method returns an object containing a property named after each variable. Each of these properties is an array containing the variable values.
This example creates a new session and sets some variables. It then outputs all the variables.
var mySession = new LassoSession(); mySession.setVariable( "Var1", "Val1", 0 ); mySession.setVariable( "Var1", "Val2", 1 ); mySession.setVariable( "Var2", "Val1", 0 ); mySession.setVariable( "Var2", "Val2", 1 ); mySession.setVariable( "Var2", "Val3", 2 ); write( mySession.getVariables().toSource() );
The output of this example is:
{Var1:["Val1", "Val2"], Var2:["Val1", "Val2", "Val3"]}
Method. Used to determine if the session has been executed..
hasExecuted()
None.
True is the session has executed and the session's ResultSet is still open. False if the session has not executed or the session's ResultSet has been closed.
This example shows how to determine if a session has been executed.
if ( mySession.hasExecuted() )
{
write( "The session has been executed." );
}
Method. Returns the ResultSet object for the session.
getResultSet()
None.
A ResultSet object.
This method is used to obtain the database results after a session has been executed.
This example shows how to access the result set after executing a session.
// create a new session var mySession = new LassoSession(); ... // execute the session mySession.execute(); // get the result set var mySet = mySession.getResultSet();
See the examples provided for the LassoSession object.
Method. Returns the InputParameters object for the session.
getInputParameters()
None.
An InputParameters object.
This method returns the InputParameters object that belongs to the session.
This example shows how to access the InputParameters object of a new Lasso session.
// Create a new session var mySession = new LassoSession(); // get a reference to the InputParameters object var myInput = mySession.getInputParameters();
See the examples provided for the LassoSession object.
The Lasso JavaScript Module allows Lasso Substitution Tags to be called using JavaScript syntax. Any regular Lasso Substitution tag can be called as if it were a function of any LassoSession object. Container or Command tags can not be called in this manner.
Tag parameters are passed to the tag using SearchColumn objects to hold the name and value of the parameters. If a tag parameters is just one value, it is passed as the name of the SearchColumn.
Example 1. This example will call the Lasso Substitution tag "field" as a JavaScript function.
lasso.defaultSession.field( new SearchColumn( '"TheFieldName"', '') );
The output of the above statement is the equivalent of using the Lasso field tag in the following manner.
[field: 'TheFieldName']
Note how the parameter is surrounded by single quotes. This indicates that the parameter should be treated as a literal.
Example 2. Multiple parameters can be passed to a tag by using multiple SearchColumn objects.
lasso.defaultSession.field( new SearchColumn( '"TheFieldName"', ''), new SearchColumn( 'EncodeURL', '' ) );
The output of the above statement is the equivalent of using the Lasso field tag in the following manner.
[Field: "TheFieldName", EncodeURL]
Note how the EncodeURL parameter is not double quoted. This is because it should be interpreted by the field tag as a keyword and not a literal value.
Example 3. If a tag required a name/value pair as a parameter, the value can be passed as the value property of the SearchColumn object.
lasso.defaultSession.cookie_set( new SearchColumn( '"CookieName"', '' ), new SearchColumn( 'path', '"/"' ) );
The effect of the above statement is the same as calling the substitution tag in the following manner.
[cookie_set: "CookieName", path="/"]
The operator property of the SearchColumn object is not used when calling Lasso Substitution Tags.