Application initialization and termination with libraries

When an AIMMS application is launched, the initialization procedures are executed before all else. Likewise, when the app is shut down the termination procedures are executed. See also this section in the language reference

If you want some action to happen each time you open the app, say reading data from a database - you can refer to the corresponding AIMMS procedure in one of the initialization procedures. A thoughtful model builder, before coding, may consider the questions:

  1. But which initialization procedure (design)?

  2. And what are the consequences of placing such a call in an initialization procedure (evaluate)?

  3. And does it make sense to place a data read procedure in the initialization (evaluate)?

The purpose of this article to give you a better understanding of the initialization and termination of an AIMMS app. With this understanding, you can provide an informed answer to the above questions and to the questions below, in the context of the app being developed:

  1. Which are the initialization procedures available to an application (knowledge)?

  2. When can you rely on a library to be initialized (understanding)?

  3. Does the order in which libraries are declared matter to the initialization and termination of an application (understanding)?

  4. Do initialization and termination depend on the way the application is deployed (knowledge)?

  5. How to stop a running application (knowledge)?

In this article, the above questions are not answered directly. But the answer follows by creating a small app and testing with it as presented below.

Example application to do the analysis

To investigate initialization and termination in detail, the app InitTerm is created that can be downloaded here. The InitTerm app has the following overall structure:

../../_images/app-overall-structure.png

The visit procedure

The purpose of the procedure pr_visit is to mark the visiting procedures.

The procedure pr_visit has the following simple code:

1p_visits += 1 ;
2sp_node := callerNode(1);
3sp_line := formatString("Visit %2i from: %s", p_visits, sp_node);
4pr_log(sp_line);

whereby the procedure pr_log outputs the line either into the session log or to a file, depending on how the app is called.

Subsequently, a call to pr_visit is placed at every procedure that might be involved in the initialization or termination. In addition, a case is saved whereby the value of p_visits is set to 50. This case is set to the startup case.

Running the InitTerm app

Opening the app in AIMMS developer, and pressing the Bye button in the opened WinUI page results in the following visit.txt file:

 1Visit  1 from: MainInitialization
 2Visit  2 from: a::LibraryInitialization
 3Visit  3 from: b::LibraryInitialization
 4Visit  4 from: c::LibraryInitialization
 5Visit  5 from: d::LibraryInitialization
 6Visit 51 from: PostMainInitialization
 7Visit 52 from: a::PostLibraryInitialization
 8Visit 53 from: b::PostLibraryInitialization
 9Visit 54 from: c::PostLibraryInitialization
10Visit 55 from: d::PostLibraryInitialization
11Visit 56 from: pr_startup
12Visit 57 from: pr_openPageWinUI
13Visit 58 from: pr_actionFinish
14Visit 59 from: pr_closePageWinUI
15Visit 60 from: d::PreLibraryTermination
16Visit 61 from: c::PreLibraryTermination
17Visit 62 from: b::PreLibraryTermination
18Visit 63 from: a::PreLibraryTermination
19Visit 64 from: PreMainTermination
20Visit 65 from: d::LibraryTermination
21Visit 66 from: c::LibraryTermination
22Visit 67 from: b::LibraryTermination
23Visit 68 from: a::LibraryTermination
24Visit 69 from: MainTermination

There are several remarks to be made about this log:

  1. The order in which the libraries are initialized is top to bottom, and in which they are terminated is bottom to top.

    Tip

    Consequently, it is practical to put the system libraries AimmsProLibrary and AimmsWebUI at the top of the library list. This permits other libraries to use the functionalities of these libraries even in their LibraryInitialization and LibraryTermination procedures.

  2. The p_visit value jumps to 51 on line 6. This implies that the startup case is loaded just before PostMainInitialization is run.

  3. On line 13 the procedure pr_actionFinish is visited. This procedure initiates the shutdown of the session (lines 15-24) after closing the only WinUI page of app (line 14).

Deployment dependent actions taken

The following lists which actions are taken by application start or application finish:

Developer

WebUI

Solver

WinUI

AimmsCmd

runonly

initialData

MainInitialization

LibraryInitialization

Load of startup case

PostMainInitialization

PostLibraryInitialization

Startup procedure

Page open of WinUI page

Page close of WinUI page

Page open of WebUI page

Page close of WebUI page

Read input case

Write output case

PreLibraryTermination

PreMainTermination

LibraryTermination

MainTermination

The columns of the above table are:

  1. AIMMS Developer: the actions taken by AIMMS Developer by opening and closing the InitTerm application.

  2. WebUI: the actions taken by a WebUI application published on AIMMS PRO by opening and closing the InitTerm application.

    Tip

    Many users appreciate a quick start of an application as this will as this will put them at ease knowing that the system is up and running. In addition, they appreciate progress information during a long running data read procedure, perhaps via webui::SetProgressMessage. Please consider placing long running data read procedures as an explicit action to be invoked by the user.

    Note

    A published WebUI app can be closed in two ways:

    1. By running the procedure pro::sessionmanager::FinishSession().

    2. By closing all browser tabs, and waiting a minute.

  3. Solver: A solver session submitted by pro::delegateToServer.

    1. The input case is the case constructed by the data session (WinUI or WebUI) to provide input to the solver session.

    2. The output case is the case constructed by the solver session to pass the results to the data session.

    Tip

    It may be redundant to read in data in an initialization procedure of a solver session when that data is also provided in the input case.

  4. WinUI: the actions taken by a WinUI application published on AIMMS PRO by opening and closing the InitTerm application.

    Note

    WinUI is not available in the community edition and it is on the deprecate list

    Note

    A published WinUI app can be closed in two ways:

    1. By running the procedure ExitAimms.

    2. By closing the window.

  5. AimmsCmd: Running the InitTerm application via AimmsCmd and just opening and closing it.

  6. runonly: Running aimms.exe with the –run-only command line argument (using AIMMS 4.87.4 or newer).

References and further reading

  1. Language reference: Model Initialization and Termination

  2. The Help on the options in the category Project > Startup & authorization:

    1. startup case

    2. startup procedure

    3. startup page

  3. AIMMS The User’s guide:

    1. AIMMS command line options