Interfacing with the user interface

Interface functions

At particular times, for instance during the execution of user-activated procedures, you may have to specify an interaction between the model and the user through dialog boxes and pages. To accommodate such interaction, AIMMS offers a number of interface functions that perform various interactive tasks such as

  • opening and closing pages,

  • printing pages,

  • file selection and management,

  • obtaining numeric, string-valued or element-valued data,

  • selecting, loading and saving cases, and

  • execution control.

Return values

All interface functions have an integer return value. For most functions the return value is 1 (success), or 0 (failure), which allows you to specify logical conditions based on these values. If you are not interested in the return value, the interface functions can still be used as procedures.

Limited use in certain cases

There are some interface functions that also return one or more output arguments. In order to avoid possible side effects, the return values of such functions can only be used in scalar assignments, and then they must form the entire right hand side.

Obtaining the error message

Whenever an interface function fails, an error message will be placed in the predefined AIMMS string parameter CurrentErrorMessage. The contents of this identifier always refer to the message associated with the last encountered error, i.e. AIMMS does not clear its contents. Within the execution of your model, however, you are free to empty CurrentErrorMessage yourself.

Example

The following statements illustrate valid examples of the use of the interface functions FileExists, DialogAsk, and FileDelete.

if ( FileExists( "Project.lock" ) ) then
    Answer := DialogAsk( "Project is locked. Remove lock and continue?",
                         Button1 : "Yes", Button2 : "No" ) ;

    if ( Answer = 1 ) then
        FileDelete( "Project.lock" ) ;
    else
        halt;
    endif ;
endif ;

The interface function DialogAsk has a return value of 1 when the first button is pressed, and 2 when the second button is pressed.

Page Functions

Warning

The AIMMS WinUI is deprecated, and thus Page functions as well. Please refer to AIMMS Product Lifecycle. You may use the WebUI instead, and the WebUI System Library.

Model page control

The possibility of opening pages from within a model provides flexibility compared to page tree-based navigation. Depending on a particular condition you can decide whether or not to open a particular page, or you can open different pages depending on the current status of your model.

Page functions

The following functions for manipulating pages are available in AIMMS.

  • PageOpen(page) Opens page page.

  • PageOpenSingle(page) Opens page page and closes all other.

  • PageClose([page]) Closes page page, if page is not specified, closes active page.

  • PageGetActive(page) Returns the active page in page.

  • PageGetFocus(page,tag) Returns the name of the page and object that have focus in pagePar and tag

  • PageSetFocus(page,tag) Sets the focus to object tag on page page.

  • PageSetCursor(page,tag,scalar-reference) Position the cursor of object tag on page page to scalar-reference.

  • PageRefreshAll Ensure that the open pages are refreshed with the current data.

  • PageGetChild(page, childpage) Return the name of the page that is the first child of page in childpage, if any.

  • PageGetParent(page, parentpage) Return the name of the page that is the parent of page in parentpage.

  • PageGetPrevious(page, previouspage) Return the name of the page that is the previous page of page in previouspage.

  • PageGetNext(page, result-page) Return the name of the page that is the next page of page in nextpage.

  • PageGetNextInTreeWalk(page, nextpage) Return the name of the page that is the next page of page in a depth first tree walk over the page tree.

  • PageGetTitle(pageName, pageTitle) Return the title of a specific page.

  • PageGetUsedIdentifiers(page, identifier_set) Return the identifiers used in identifier_set.

File Functions

File manipulation

The interactive execution of your model may involve various forms of file manipulation. For instance, the user might indicate which names to use for particular input and output files, or in which directory they are (to be) stored.

File functions

The following functions are available for file manipulation in AIMMS.

  • FileSelect(filename[,directory][,extension][,title]) Dialog to select an existing file.

  • FileSelectNew(filename[,directory][,extension][,title]) Dialog to select a new file.

  • FileDelete(filename[,delete_readonly_files) Delete a file.

  • FileCopy(oldname,newname[,confirm]) Copy a file.

  • FileMove(oldname,newname[,confirm]) Rename or move a file.

  • FileAppend(filename,appendname) Append to an existing file.

  • FileExists(filename) Is filename an existing file?

  • FileView(filename[,find]) Opens filename in read only mode.

  • FileEdit(filename[,find]) Opens filename for text editing.

  • FilePrint(filename) Print a text file to printer.

  • FileTime(filename,filetime) Return the modification time.

  • FileTouch(filename,newtime) Set the modification time to now.

Directory functions

The following functions are available for directory manipulation.

Dialog Box Functions

Warning

The AIMMS WinUI is deprecated, please refer to AIMMS Product Lifecycle. You may use the WebUI instead, and use Dialog Pages, Status Bar, Download Widget and Upload Widget.

Two types of dialog boxes

During the execution of your model, it is very likely that you must communicate particular information with your user at some point in time. AIMMS supports two types of dialog boxes for user communication:

  • information dialog boxes, and

  • data entry dialog boxes.

In addition to these standard dialog boxes available in AIMMS, it is also possible to create customized dialog boxes using dialog pages, and open these using the PageOpen function discussed in Page Functions.

Information dialog boxes

The following functions are available in AIMMS for displaying information to the user.

  • DialogMessage(message[,title]), and DialogError(message[,title]) Both show message until OK button is pressed. They differ in icons displayed.

  • DialogAsk(message,button1,button2[,button3]) Show message and offer two or three choices.

  • DialogProgress(message[,percentage]) Show message and progress bar. Execution is continued.

  • StatusMessage(message) Show message at the bottom of the AIMMS window.

Data entry dialog boxes

The following functions are available in AIMMS for scalar data entry dialog boxes.

Case Management Functions

There are several functions and identifiers available to support case management tasks. The functions can be divided into three groups:

  • Basic - These functions perform the core case management tasks; they do not involve any dialogs.

  • Dialog - These functions handle the dialogs around case management functions; they do not do any basic case management tasks.

  • Menu Replacement - These functions execute similarly as the default actions behind the data menu.

Each of these three groups of functions, and the predeclared identifiers, are briefly presented below. For details about a particular function or identifier, the reader is referred to the Function Reference.

Basic case functions

The following functions are available in AIMMS for performing basic case management tasks without invoking dialogs.

  • CaseFileLoad(url[,keepUnreferencedRuntimeLibs]) Load a case file and use its name as the active case.

  • CaseFileMerge(url[,keepUnreferencedRuntimeLibs]) Merge a case file in.

  • CaseFileSave(url,contents) Save the data to a file.

  • CaseFileGetContentType(url,contentType) Get the current content type.

  • CaseFileURLtoElement(url[,caseFileElement]) Find or create an element in corresponding to url.

  • CaseCompareIdentifier(case1,case2,identifier,suffix,mode) Check whether the data of an identifier differs in two case files.

  • CaseCreateDifferenceFile(case,filename,diff-types
    .8cm,absolute-tolerance,relative-tolerance,output-precision)

Here the arguments are:

Case dialog functions

The following functions are available that handle the dialogs around case management, but do not perform the actual case management tasks:

Here the arguments are:

Data manamement functions

The function DataManagementExit() checks whether any data should be saved according to the active data management style. If any of the data needs saving, a dialog box is displayed, in which the user can select to save the data, not to save the data, or to cancel the current operation.

Data menu functions

These functions emulate the default menu items of the Data menu, they do not have any arguments.

Case file related identifiers

There are a number of predeclared identifiers available for the management of case files. They are:

Execution Control Functions

Execution control

During the execution of your AIMMS application you may need to execute other programs, delay the execution of your model, get the command line arguments of the call to AIMMS, or even close your AIMMS application.

Control functions

The following execution control functions are available in AIMMS.

Debugging Information Functions

Debugging information

To help you investigate the execution of your model AIMMS offers several functions to control the debugger and profiler from within your model. In addition, a number of functions are available that help you investigate memory issues during execution of your model.

Execution information functions

The following execution information functions are available in AIMMS.

Profiler control

The following profiler control functions are available in AIMMS.

Obtaining License Information

License information functions

The licensing functions discussed in this section allow you to retrieve licensing information during the execution of your model. Based on this information you may want to issue warnings to your end-user regarding various expiration dates, or adapt the execution of your model according to the capabilities of the license.

License functions

The following licensing functions are available in AIMMS.