Websydian v6.1 online documentationOnline documentation - WebsydianExpress v3.5

Implementing callback functions - RPG Developer

Overview

This document will show how you can implement your own callback function for the callback points provided by the WebsydianExpress runtime.

The callback functions offers the possibility to add custom functionality to the functionality performed by the WebsydianExpress runtime in specific situations.

The document also contains a short description of each of these callback points.

For each callback point you can specify any number of callback functions.

Creating the function

Create a ILE RPG function that includes the EXPRESS_H header:

 

D/COPY *libl/QRPGLESRC,EXPRESS_H 

The interface of the function must be a 7 character return code - for example:

 

D ReturnCode      S              7A                            
                                                               
C     *ENTRY        PLIST                                      
C                   parm                    ReturnCode         

Retrieving input

As the callback functions are called dynamically by the runtime, you can't specify any parameters additional parameters for the function.

But there is still some of the callback points that transfers information for the callback functions. This information can be retrieved by calling the API CallbackInputGet.

When calling this function you must specify the name of the parameter to get. For each parameter used by the system defined callback points, constants has been specified in the WICALB_H header file - the description for each callback point found below specifies which parameters you can retrieve.

Setting output

For some of the callback functions there is also the option to return some information. You make this information available for the calling function by calling the API CallbackOuputSet.

As for the CallbackInputGet function, you must provide the name of the field together with the value - information about which information you can set is of course also found in the description of the callback points found below.

Adding the callback function to the callback point

After implementing your custom functionality and compiling the function, you must specify that the function should be called for the callback point. This is done using the administration interface menu item Callback functions.

System defined callback points

ApplicationServiceEnd

Interface

No input or output parameters.

Called when

ApplicationServiceEnd is called when the Application Service exists.

Influence on later functionality

None.

Example of use

Used to perform clean-up processing that must be done before the Application Service exits.

If you have used the ApplicationServiceStart callback point to connect/logon to a back-end system (e.g. an ERP system), you need want to disconnect from/log off this system.

ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.

 

ApplicationServiceStart

Interface

No input or output parameters.

Called when

ApplicationServiceStart is called when the Application Service starts.

Influence on later functionality

None.

Example of use

Used to allocate resources that should be used by the Application Service and are shared by all requests; e.g. connection to back-end systems (for example ERP systems).

ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.

 

BeforeRequestStart

Interface

Field Type Constant Description
ContinueHandling Output CB_CONTINUE Specifies whether the request should be handled by the Websydian Runtime

Call the API CallbackOutputSet to return the information to the calling function.

Called when

BeforeRequestStart is called after the request has been received by the runtime, but before any handling of the request has been performed.

Influence on later functionality

Setting the output parameter to Yes will let the normal handling proceed.

Setting the output parameter to No will stop all handling of the request.

This means that the callback function offers the possibility to take full control of the handling of a request.

Please note that this includes all handling - including calling a PageGenerator function if you want anything to be sent to the browser.

You must also note that the request has not been parsed or in any way interpreted by this function. If you do need to use this function contact websydian support with a description of your case to obtain information about how you can retrieve the relevant request headers and the request body.

Example of use

The case for this callback function was an installation, where it also was necessary to be able to process web service requests.

By checking the content type header it was possible to find the requests that contained xml - and to let the function call a service function that was specially designed to handle the web service requests. After calling the service function that handled the web service request, the ContinueHandling flag was set to No to prevent the normal handling of the request.

 

HandlingRequestStart

Interface

No input or output parameters.

Called when

HandlingRequestStart is called when a request is received and the request parameter string has been parsed and written to memory.

Influence on later functionality

None.

Example of use

At this point, you can use the GetInput API to retrieve information about the parameters specified on the request.

ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.

 

HandlingRequestEnd

Interface

No input or output parameters.

Called when

HandlingRequestEnd is called when the processing of a request is ended.

Influence on later functionality

None.

Example of use

Used to perform any clean-up processing that must be done at the end of a request.

ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.

 

IsSessionInIntranet

Interface

Field Type Condition Description
Session ID Input CB_SESSIONID The unique identifier for the session.
IPIntranetMask Input CB_INTRAMASK The IP intranet mask specified on site settings.
IsIPInIntranet Input CB_IPINTRANET The current setting of the Flag determining if the session is in the intranet.
IsIPInIntranet Output CB_IPINTRANET Set to Y if the IP address on the session belongs to the specified IP intranet mask. Set to N otherwise.

Use the API CallbackGetInput to retrieve the input parameters and the API CallbackOutputSet to return the output parameter to the calling function.

Called When

The functions is called when a session is created in order to determine whether a session belongs to the Intranet or the Extranet.

The function is called immediately after the runtime has determined whether the session is in the intranet based on the intranet mask specified in the site settings.

Influence on later functionality

Based on the value of the field IsIPInIntranet the assignment of roles to the session will be affected.

Example of use

The IP intranet mask in WebsydianExpress is specified as a partial IP address, e.g. "192.168.".

In more complex network environments it could be necessary to specify a more advanced IP mask. E.g. like "192.168.0.0/255.254.0.0". In this case it will be necessary to implement this callback function and check whether the IP address on the session belongs to the specified IP mask.

As for all the callback points, several callback functions can be defined for the IsSessionInIntranet callback point. This means that there is the possibility that the one runtime has determined that the session is not in the intranet, one callback function has determined that the session is in the intranet and yet another function has determined that it is not in the intranet (all based on the rules implemented by the callback functions). In all these cases, the output last callback function determines whether the session will be handled as being in the intranet.

To make it possible for the callback function to take the results of the runtime and any previously called callback functions for the callback point into consideration, the current state of the IsIPInIntranet is transferred as an input parameter to the callback function. It is up to the developer to determine whether he will take this value into account.

You can specify the sequence in which the callback functions will be called using the administration interface menu item callback functions.

 

SessionAfterCreate

Interface

Field Type Condition Description
Session ID Input CB_SESSIONID The unique identification of the session that has been created

Call the API CallbackInputGet to retrieve the session id.

Called when

SessionAfterCreate is called immediately after the session has been created by the initial request. This is done before the site is loaded.

Influence on later functionality

No direct effect - but the possibility to e.g. add roles to the session can result in significant effects on the site load.

Example of use

If the initial request contains information that can be used to log a user in to the session, the user check and the update of the session can be done here. By updating the user and roles for the session (e.g. by calling the API SetUserAndUpdate) the site will be loaded as if the user had logged in using the "standard" login page.

 

UserAfterCreate

Interface

Field Type Condition Description
UserID Input USERID The unique identification of the user

Call the API CallbackInputGet to retrieve the user id.

Called when

The function is called from the Insert event handler function on the Insert User page. It is called just after the call to the function creating the user if the creation has been successful.

Influence on later functionality

None.

Example of use

An example could be the case where the WebsydianExpress user table and other user tables used inside the company must be synchronized. Every time a new user is created in WebsydianExpress a corresponding user must be created in the other user tables.

The implemented callback function can read the information for the created user by calling the server API UserGet. It is then possible to call functions for creating users in the other tables.

 

UserAfterDelete

Interface

Field Type Condition Description
User ID Input CB_USERID The unique identification of the user.
Login Name Input CB_LOGIN The login used by the deleted user.
UserSitekey Input CB_USERSITE Identifies the site the user was assigned to. The combination of login name and site uniquely identifies the user.

Call the API CallbackInputGet to retrieve the information.

Called when

The function is called from the Delete event handler function on the Confirm Delete User page. It is called just after the call to the function deleting the user if the deletion has been successful.

Influence on later functionality

None.

Example of use

The WebsydianExpress user table and other user tables used inside the company must be synchronized. Every time a user is deleted in WebsydianExpress the corresponding users must be deleted in the other user tables.

As the user at this point has been deleted more information cannot be found by calling API functions, but depending on how the user tables references each other either the user surrogate or the combination of login name and site key should be sufficient to identify the records in the other tables.

 

UserAfterLogin

Interface

Field Type Condition Description
Session ID Input CB_SESSIONID The unique identification of the session.

Call the API CallbackInputGet to retrieve the information.

Called when

The function is called just after a user has logged into WebsydianExpress and the session has been updated with the user and user roles.

Influence on later functionality

None.

Example of use

This callback function can be used to add extra roles to the session after a user has logged in, based on some external information; e.g. an ERP system.

 

Examples

An example of an implemented callback function for the callback point session after create can be found below.

This implementation  retrieves the session id, writes it to the message log, uses the session id to read all of the session data and writes the IP address to the message log.

 
H DFTACTGRP(*NO) ACTGRP(*CALLER) BNDDIR('QC2LE' : 'WIEXPRESS')         
D/COPY *libl/QRPGLESRC,EXPRESS_H                                       
 **********************************************************************
 * Test of callback function for session after create                  
 *---------------------------------------------------------------------
 * The function writes a message to the message log containing the     
 * callbackinput parameter specifying the session id                   
 * After this, the retrieved value is used to read the session data    
 * and the IP address is written to the log.                            
 **********************************************************************
D RC              S             10I 0 inz(0)                           
D Value           S                   like(ParmCallback.ParmValue)     
D ReturnCode      S              7A                                    
D P               DS                  likeds(ParmSess) inz(*likeds)    
                                                                       
C     *ENTRY        PLIST 
C                   parm                    ReturnCode             
                                                                   
C                   eval      ReturnCode = ''                      
 * Retrieve the session id from memory - write it to the log       
C                   eval      RC = CallbackInputGet(CB_SESSIONID:  
C                             Value)                               
                                                                   
C                   eval      RC = Writelog(EC_INFORMATION:        
C                             'RPG ' +                             
C                             'SessionAfterCreate. SessionID: ' +      
C                             Value)                                   
                                                                       
 * Retrieve the session information and write the IP adress to the log 
C                   eval      P.SessionID = %dec(Value:15:0)           
C                   eval      RC = SessionGet(P.SessionID:             
C                             P.SiteKey:                               
C                             P.FolderListID:                          
C                             P.UserID:      
C                             P.Status:                                
C                             P.IPAddress:                             
C                             P.CreationDate:                          
C                             P.CreationTime:                          
C                             P.LastReqDate:                           
C                             P.LastReqTime:                           
C                             P.RequestCount)                          
                                                                       
C                   eval      RC = WriteLog(EC_INFORMATION:                                                                                   
C                             'IP: ' + P.IPAddress)         
                                                            
C                   RETURN