The PUT Statement

Customized text reports

AIMMS provides two statements to create a customized text output report in either a file or in a text window in the user interface. They are the PUT and the DISPLAY statements. The result of these statements must always be directed to either a single file or a window.

Basic steps

The following steps are required to create a customized text report:

• direct the output to the appropriate File identifier, and

• print one or more strings, set elements, numerical items, or tabular arrangements of data to it.

These basic operations are the subject of the subsequent subsections. At the end of the section, an extended example will illustrate most of the discussed features.

Stream versus page mode

AIMMS can produce text reports in two modes. They are:

• stream mode, in which all lines are printed consecutively, and

• page mode, where the report is divided into pages of equal length, each consisting of a header, a footer and a data area.

Most aspects, such as opening files, output direction, and formatting, are the same for both reporting modes. Only the structuring of pages is an extra aspect of the page mode, and is discussed in Structuring a Page in Page Mode.

Opening Files and Output Redirection

Opening files

Disk files and windows are opened automatically as soon as output is written to them. You can send output to a particular file by providing the associated File identifier as the first argument of a PUT statement, which designates the file as the current file.

PUT without file identifier

If you use the DISPLAY statement or any of the PUT operators listed in this table without a file identifier, AIMMS will direct the output to the current file, i.e., the file last opened through the PUT statement.

Undirected output

When you have not yet selected a current file yet, AIMMS will send the output of any PUT or DISPLAY statement to the standard listing file associated with your model.

Example

The following statements illustrates how to send output to a particular file.

PUT ResultFile ;
PUT "The model results are:" ;
DISPLAY Transport ;
PUTCLOSE;

The first PUT statement sets the current file equal to ResultFile, causing the output of the subsequent PUT and DISPLAY statements to be directed to it. The final PUTCLOSE statement will close ResultFile.

File identifiers only

Unlike other statements like READ and WRITE which allow you to represent files by strings or string parameters as well, the PUT statement requires that you use a File identifier to represent the output file. The way in which output to a file is generated by the PUT statement is completely controlled by the suffices associated with the corresponding File identifier (see also Structuring a Page in Page Mode).

Accessing the current file

AIMMS has two pre-defined identifiers that provide access to the current file. They are

• the element parameter CurrentFile (into the set AllIdentifiers) containing the current File identifier, and

• the string parameter CurrentFileName, containing the file name or window title associated with the current file identifier.

The parameter CurrentFileName is output only.

Changing the current file

To select another current file, you can use either of two methods:

• use the PUT statement to (re-)direct output to a different file, or

• set the identifier CurrentFile to the File identifier of your choice.

Closing external files

Closing an external file can be done in two ways:

• automatically, by quitting AIMMS at the end of a session, or

• manually by calling “PUTCLOSE file-identifier” during execution.

Files left open

If you leave a file open during the execution of a procedure, AIMMS will temporarily close it at the end of the current execution, and re-open it in append mode at the beginning of a subsequent execution. This enables you to inspect the PUT files in between runs.

Formatting and Positioning PUT Items

Besides selecting the current file, the PUT statement can be used to output one or more individual strings, numbers or set elements to an external text file or window. Each item can be printed in either a default or in a customized manner. The syntax of the PUT statement follows.

Syntax

put-statement:

PUT operators

All possible variants of the PUT operator are listed in this table. The PUT and PUTCLOSE operators can be used in both stream mode and page mode. The operators PUTHD, PUTFT and PUTPAGE only make sense in page mode, and are discussed in Structuring a Page in Page Mode.

Statement	Description	Stream mode	Page mode
PUT	Direct output or write output	\(\bullet\)	\(\bullet\)
PUTCLOSE	PUT and close current file	\(\bullet\)	\(\bullet\)
PUTHD	Write in header area		\(\bullet\)
PUTFT	Write in footer area		\(\bullet\)
PUTPAGE	PUT and output current page		\(\bullet\)

Put items are always scalar

All PUT operators only accept scalar expressions. For each scalar item to be printed you can optionally specify a format field, with syntax:

Syntax

format-field:

Format fields

With the format field you specify

• whether the item is to be centered, left aligned or right aligned,

• the field width associated with an identifier, and

• the precision.

Customized default values for the justification, field width and precision can be specified through PUT-related options, which can be set via the Options menu. The following table shows a number of examples of format fields, where \(m\) and \(n\) are expressions evaluating to integers.

PUT argument	Justification	Field width (characters)	Precision
item	default	default	default
item:\(m\)	default	\(m\)	default
item:\(m\):\(n\)	default	\(m\)	\(n\)
item:<\(m\):\(n\)	left	\(m\)	\(n\)
item:>\(m\):\(n\)	right	\(m\)	\(n\)
item:<>\(m\):\(n\)	centered	\(m\)	\(n\)

Interpretation of precision

For numerical expressions the precision is the number of decimals to be displayed. For strings and set elements the precision is the maximum number of characters to be displayed. The numbers or characters are placed into a field with the indicated width, and are positioned as specified.

Using the FormatString function

The PUT syntax for formatting and displaying multiple items on a single line is somewhat similar to the reporting syntax in programming languages like FORTRAN or PASCAL. If you are a C programmer, you may prefer to construct and format a single line of text using the FormatString function (see also Formatting Strings). In this case you only need the PUT statement to send the resulting string to a text report or window.

Position determination

For advanced reporting the PUT statement allows you to directly position the cursor at a given row or column. The syntax is shown in the following syntax diagram.

position-determination:

How to position

There are three special arguments for the PUT statement that can be used to position printable items in a file:

• the @ operator-for horizontal positioning on a line,

• the # operator-for vertical positioning, and

• the newline operator /.

These three operators are explained in this table, where the symbols \(k\) and \(l\) are expressions evaluating to integers.

Table 62 Position determination

Operator	Meaning
@\(k\)	Start printing the next item at column \(k\) of the current line.
#\(l\)	Goto line \(l\) of current page (page mode only).
/	Goto new line.

Page mode only

Using the vertical positioning operator # only makes sense when you are printing in page mode. When printing in stream mode all lines are numbered consecutively from the beginning of the report, and added to the output file or window as soon as AIMMS encounters the newline character /. In page mode, AIMMS prints pages in their entirety, and lines are numbered per page. As a result, you can write to any line within the current page.

Extended Example

Example

This example builds upon the transport model used throughout the manual. The following group of statements will produce a text report containing the contents of the identifiers Supply(i), Demand(j) and Transport(i,j), in a combined tabular format separated into right aligned columns of length 12.

The statements

! Direct output to ResultFile
put ResultFile ;

! Construct a header for the table
put @13, "Supply":>12, @30, "Transport":>12, /, @30 ;

for ( j ) do   put j:>12 ;   endfor ;
put // ;

! Output the values for Demand
put "Demand", @30 ;
for ( j ) do   put Demand(j):>12:2 ;   endfor ;
put // ;

! Output Supply and Transport
for ( i ) do
    put i:<12, Supply(i):>12:2, @30 ;
    for ( j ) do   put Transport(i,j):>12:2 ;   endfor;
    put / ;
endfor ;

! Close ResultFile
putclose ResultFile ;

The produced report

For a particular small data set containing only three Dutch cities, the above statements could result in the following report being generated.

                  Supply        Transport
                                Amsterdam   Rotterdam    Den Haag

Demand                               5.00       10.00       15.00

Amsterdam          10.00             2.50        2.50        5.00
Rotterdam          12.50             2.50        5.00        5.00
Den Haag            7.50             0.00        2.50        5.00