4.3.7 WAM Session Example

It is important to understand the SessionStatus property for managing your WAM sessions.

The following is an example of a typical WAM which a manages a session:

FUNCTION OPTIONS(*DIRECT)
BEGIN_COM ROLE(*EXTENDS #PRIM_WAM) SESSIONSTATUS(Active) SESSIONTIMEOUT(300)
 
*The following line declares Session state #CUSTNAME field
WEB_MAP FOR(*NONE) FIELDS(#CUSTNAME) OPTIONS(*PERSIST)
 
WEBROUTINE NAME(Start) DESC('Initial Page') OnEntry(*SessionStatus_None)
WEB_MAP FOR(*OUTPUT) FIELDS(#USERID #PASSWORD)
ENDROUTINE
 
WEBROUTINE NAME(Logon) DESC('Logon Page') OnEntry(*SessionStatus_None)
WEB_MAP FOR(*INPUT) FIELDS(#USERID #PASSWORD)
…
* Some authentication logic, if authentication fails can TRANSFER back to Start page
 
* The following line will create a session, when WEBROUTINE exits
#COM_SELF.SessionStatus := Active
 
TRANSFER TOROUTINE(WelcomePage)
ENDROUTINE
 
WEBROUTINE NAME(WelcomePage) DESC('Welcome Page')
ENDROUTINE
 
WEBROUTINE NAME(Logoff) DESC('Logoff page')
#COM_SELF.SessionStatus := Invalid
ENDROUTINE
 
* The following event handler will handle invalid sessions and
* TRANSFER back to starting page, for logon
EVTROUTINE HANDLING(#COM_OWNER.SessionInvalid) OPTIONS(*NOCLEARMESSAGES *NOCLEARERRORS)
TRANSFER TOROUTINE(Start)
ENDROUTINE
 
END_COM

• SessionStatus is set to Active. By default ,WEBROUTINEs in this WAM require a session to be valid before they are executed. SessionTimeout is 5 minutes.

• Two WEBROUTINEs, Start and Logon, override SessionStatus to None, by using OnEntry(*SessionStatus_None) keyword. The Start WEBROUTINE presents a page requesting logon details. Since this is an initial page, it must be executed whether there is a valid session or not. Hence, a SessionStatus of None.

• Logon WEBROUTINE is invoked from a Start page, when a button to logon is pressed. At this point, there is still no valid session so this WEBROUTINE must also be allowed to execute without a session.

• Logon validates the user id and password and, if valid, sets SessionStatus to Active. Setting SessionStatus from None to Active will create a new session when Logon WEBROUTINE exits.

• Logon WEBROUTINE performs a TRANSFER to WelcomPage WEBROUTINE. We now have an Active session, so WelcomePage is allowed to execute (it requires an Active session). When WelcomePage exits, a session key for the new session is passed back to the browser. This session key will be returned from now on for every new WEBROUTINE request from the same browser and allows the server to identify the session.

• There is also a SessionInvalid handler which simply TRANSFERs to Start page. This handler is invoked whenever there is an attempt to invoke a WEBROUTINE with a non-existent or invalid session key or when a valid session key is provided but the session has expired (no requests for more than 5 minutes). When a session is invalid or expired, a Start page requesting user id and password is always displayed in the browser.

• You can also provide a Logout button or menu in your WAM application so the session is explicitly invalidated. In such circumstances, the button invokes a Logoff WEBROUTINE, which sets SessionStatus to Invalid and invalidates the session on WEBROUTINE exit.