Understanding and Using Session Variables

IN THIS PAGE

Session Variable Types
How to Create and Reference a Session Variable
Session Variable Availability

Description

When you create an Xbasic variable inside an A5W page, the variable is not available to other pages. If you want to reference a variable on multiple A5W pages, you must use a session variable to store the value. Session variables are available for the duration of a session to all A5W pages in an application.

Locally defined Xbasic variables in an A5W page are not accessible to other A5W pages. For example, suppose you would like to capture the user's first name on one A5W page and display a message using the user's first name on another A5W page. On the first A5W page, you may write:

<%a5 dim firstname as c = "George" %>

And on the second A5W page, you may try the following:

<%a5 ? "My name is " + firstname %>

Unfortunately, this will not work. On the second A5W page, instead of seeing the message "My name is George", you will see an error message:

500 Internal Server Error
Script Error
Error:Script:" /LivePreview/$$E120.a5w" line:17
? "My name is " + firstname
Variable "firstname" not found.

The second A5W page has no knowledge of the firstname variable or its value. This is because firstname was defined local to the page. When the A5W page is loaded, the firstname variable is created. When the same A5W page is unloaded, the firstname variable is deleted. To save a value that spans multiple pages, you must use a session variable. To create a session variable, simply name it session.varname. It will then be persistent across all page views and can be later referenced as session.varname in subsequent pages.

<%a5 session.firstname = "George" %>

Session Variable Types

A variable in Xbasic has a type. This can be character, numeric, date, time, shorttime, etc. However, session variables should only be character variables. If you try to set a session variable to a non-character value, the Xbasic Error log will show a warning:

Warning: Illegal session variable value.
    Session.my_date
    Session variables are restricted to character type only.
    The variable Session.my_date is about to be set with as non-character value.
    This code will no longer function in a future software release.

To prevent the warning, you must cast the value you want to store in a session variable to a character value before setting the session variable. The easiest way to cast a value to a character is to concatenate it with an empty character value. For example:

dim number as n = 5
dim string as c
string = "" + number

When you read the value from the session variable, you can use the convert_type method to cast the data to the desired type. convert_type allows you to convert any data type to any other data type. If you have stored numeric values in a session variable, you would use convert_type(session.number,"N") to cast the session variable to a numeric type. For example:

dim num as n
num = 5

' Convert num to a character value
session.number = "" + num
? session.number
= "5"

dim num2 as n
' Convert session.number to a number
num2 = convert_type(session.number, "N")

? num2
= 5

The next example shows how you would store a date object in a session variable and set another date variable to the value of the session variable using convert_type.

dim today as d = date()

session.today = "" + today
? session.today
= "06/03/2016"

dim today2 as d
today2 = convert_type(session.today, "D")

? today2
= {06/03/2016}

Array and pointer variables can also be saved in session variables. However, they must first be serialized to a character string. This is done using the json_generate method to convert the array or pointer variable to a json object. For example:

dim p as p
p.name = "John Smith"
p.city = "Boston"
p.state = "MA"

' Serialize p to a character string
session.obj = json_generate(p) 
? session.obj
= {
	"name": "John Smith",
	"city": "Boston",
	"state": "MA"
}

To convert the json object back to a pointer variable, the json_parse method is used:

dim p2 as p

' Deserialize session.obj to a pointer variable
p2 = json_parse(session.obj)

? p2
= city = "Boston"
name = "John Smith"
state = "MA"

When deserializing an array, you must store it in a pointer variable. This is because the json_parse method returns a pointer variable and not an array.

How to Create and Reference a Session Variable

To demonstrate the use of session variables, we will create two new pages. The first page will set a session variable called session.myname to the value of "George". The second page will print the session variable.

In the Web Projects Control Panel click New > Web Page (A5W) > OK.
Display the Source tab of the editor.

Type the following text into the editor:

<html>
    <head>
        <meta name="generator" content="Alpha Anywhere HTML Editor">
        <title>Set Session Variable</title>
    </head>
    <body>
        <%a5
            session.myname = "George"
        %>
        <p> </p>
    </body>
</html>

Select File > Save As.
Enter "Set Session Variable" in the File name field and click Save.
Click the 'X' icon to close the HTML Editor.
In the Web Projects Control Panel click New > Web Page (A5W) > OK.
Display the Source tab of the editor.

Type the following text into the editor.

<html>
    <head>
        <meta name="generator" content="Alpha Anywhere HTML Editor">
        <title>Read Session Variable</title>
    </head>
    <body>
        <p> </p>
        <%a5
            ? "My name is " + session.myname
        %>
    </body>
</html>

Select File > Save As.
Enter "Read Session Variable" in the File name field and click Save.
Click the 'X' icon to close the HTML Editor.
Select the "Read_Session_Variable" page, then right click and select Publish (Local Webroot) and open. This will open the page (which is blank) in your browser.
Close the browser and return to the Web Projects Control Panel.
Select the "Read_Session_Variable" page, then right click and select Publish (Local Webroot) and open. This will open the page in your browser. The page will display the value of session.myname, which was set in the "Set_Session_Variable" page. The page should look like this:
Message shown on the Read Session Variable page

Session Variable Availability

A session variable will remain available for the duration of the session. The session will remain active as long as the following conditions are met:

The Application Server is not stopped or restarted.
The next interaction (page request or update) occurs within the Application Server within the session lifetime interval. The minimum value for this interval is 300 seconds (5 minutes).
The session is not reset or abandoned.

Report an issue with this page