Interfacing with the user interface
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,
file selection and management,
obtaining numeric, string-valued or element-valued data,
selecting, loading and saving cases, and
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
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
The following statements illustrate valid examples of the use of the
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.
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.
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.
PageRefreshAllEnsure 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.
The AIMMS WinUI is deprecated, please refer to AIMMS Product Lifecycle. You may use the WebUI instead.
AIMMS provides a printing capability in the form of print pages.
The following functions are available for printing print pages in AIMMS.
PrintPage(page[,filename][,from][,to]) Print page to file filename.
PrintStartReport(title[,filename]) Start a print job with name title.
PrintEndReportEnd the current print job.
PrintPageCount(page) The number of sheets needed to print page.
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.
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.
The following functions are available for directory manipulation.
DirectorySelect(directoryname[,directory][,title]) Select an existing directory.
DirectoryCreate(directoryname) Create a directory
DirectoryExists(directoryname) Is directoryname an existing directory.
DirectoryGetCurrent(directoryname) Return the directory.
DirectoryDelete(directoryname[,delete_readonly_files) Delete a directory.
DirectoryCopy(oldname,newname[,confirm]) Copy a directory
DirectoryMove(oldname,newname[,confirm]) Move or rename a directory.
Dialog Box Functions
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
discussed in Page Functions.
Information dialog boxes
The following functions are available in AIMMS for displaying information to the user.
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.
DialogGetString(message,reference[,title]) Get a string.
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.
Here the arguments are:
case, case1 and case2 are element parameters in
url, case-path, and filename are strings.
contents an element of
contentType an element parameter in
keepUnreferencedRuntimeLibs, 0 or 1, default 1.
absolute-tolerance, relative-tolerance and output-precision arguments are numerical, scalar values.
Case dialog functions
The following functions are available that handle the dialogs around case management, but do not perform the actual case management tasks:
CaseDialogConfirmAndSave() Handles the standard “Save your data before continuing” dialog.
CaseDialogSelectForLoad(url) Handles the dialog for selecting a case file.
CaseDialogSelectForSave(url, contentType) Handles the dialog for saving data and selecting a content type.
CaseDialogSelectMultiple(caseSelection) Handles the selection of multiple cases.
Here the arguments are:
url a string parameter
contentType an element parameter in
caseSelection a subset of
Data manamement functions
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
Data menu functions
These functions emulate the default menu items of the Data menu, they do not have any arguments.
CaseCommandLoadAsActive() The default action behind the Data - Load Case - As Active menu item.
CaseCommandLoadIntoActive() The default action behind the Data - Load Case - Into Active menu item.
CaseCommandMergeIntoActive() The default action behind the Data - Load Case - Merging into Active menu item.
CaseCommandNew() The default action behind the Data - New Case menu item.
CaseCommandSave() The default action behind the Data - Save Case menu item.
CaseCommandSaveAs() The default action behind the Data - Save Case As menu item.
Case file related identifiers
There are a number of predeclared identifiers available for the management of case files. They are:
AllCases, a subset of
AllDataFiles, contains the references to the case files accessed during the current AIMMS session,
AllCasesis the reference to the current case,
CurrentCaseFileContentTypespecifies the default case content type,
AllCaseFileContentTypescontains those subsets of
AllIdentifiersthat are used to save data, and
the string parameter
CaseFileURLcontains, for each case file referenced, the url as a string.
Execution Control Functions
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.
The following execution control functions are available in AIMMS.
Debugging Information Functions
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.
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.
The following licensing functions are available in AIMMS.