Integrate GuardServerSession library with your AIMMS Application

This article describes how to use the GuardServerSession library to delegate jobs from your AIMMS app. The following steps need to be considered:

  1. Adding the library

  2. Change in delegation

  3. Change in input and output cases.

  4. Change in actions

Adding the library

The library is available from the AIMMS Library Repository.

This library is dependent on the libraries:

  1. AimmsProLibrary

  2. AimmsWebUI

Change in delegation

We will use the attached AIMMS project as an example for this section: FlowShop.zip

In addition, we assume here that delegation is done as follows:

1if pro::GetPROEndPoint() then
2    if pro::DelegateToServer( waitForCompletion  :  1,
3                  completionCallback :  'pro::session::LoadResultsCallBack' ) then
4        return 1;
5    endif ;
6endif ;
7
8pr_WorkSolve();

We change this to:

1if pro::GetPROEndPoint() then
2    if pro::DelegateToServer( waitForCompletion  :  1,
3                  completionCallback :  'gss::LoadResultsCallBack' ) then
4        return 1;
5    endif ;
6endif ;
7
8gss::pr_GuardAndProfileServerJob( 'pr_WorkSolve' );

  • Line 3: The procedure gss::LoadResultsCallBack will call pro::session::LoadResultsCallBack(sp_requestID) and subsequently copy the error and profiling information to the tracked sessions container.

  • Line 8: Instead of directly calling the workhorse, we guard it with the procedure gss::pr_GuardAndProfileServerJob. This procedure will handle any errors during execution and at the end, collect profiling information.

Change in input and output cases

The set of identifiers saved in a case by the data session as input for the solver session is stored in pro::ManagedSessionInputCaseIdentifierSet. The set of identifiers saved in a case by the solver session for the data session is stored in pro::ManagedSessionOutputCaseIdentifierSet.

If your application does not adapt these sets from their default contents Between Client and Solver Sessions before integrating with the GuardServerSession library, you do not need to do so after the integration either.

if your application does modify these sets from their default contents, then please add:

  1. s_inputCaseIdentifiers to pro::ManagedSessionInputCaseIdentifierSet in the data session.

  2. s_outputCaseIdentifiers to pro::ManagedSessionOutputCaseIdentifierSet in each solver session.

Change in actions

The WebUI provides various ways to invoke AIMMS procedures, including status bar, buttons, upload button, download button, item menus, widget menus, and page open. Each such invoked procedure should have the following pattern:

 1Procedure pr_actionTemplate {
 2    Body: {
 3        pr_enter(sp_gssTime, p_gssMiU, ep_logLev: 'info');
 4        block
 5            ! Call procedure to do the actual work.
 6        onerror ep_err do
 7            gss::pr_appendError( ep_err );
 8            errh::MarkAsHandled( ep_err );
 9        endblock ;
10        pr_leave(sp_gssTime, p_gssMiU, ep_logLev: 'info');
11    }
12    Comment: "Sample action procedure""    DeclarationSection gss_logging_declarations {
13        StringParameter sp_gssTime;
14        Parameter p_gssMiU;
15    }
16    DeclarationSection error_reference_declaration {
17        ElementParameter ep_err {
18            Range: errh::PendingErrors;
19        }
20    }
21}

Remarks:

  • Lines 3 and 10: pr_enter and pr_leave these are used to generate contents for the .actionLog File.

    AIMMS How-to: Tracing Procedures explains the workings of these procedures.

  • Lines 4, 6, and 9 delineate the business logic (line 5) from the error handling logic (lines 7,8).

  • Line 7: The procedure gss::pr_appendError stores the information of each error in the error container of the active session.

  • Line 8: Mark the error as handled; the action procedure is usually the bottom of an execution stack - so it is the bottom of the error handling stack as well.