SATURN MANUAL (V10.

8)

Control Procedures (DOS Batch Files)

14. Control Procedures (DOS Batch Files)

This section describes how to run SATURN programs using .bat file procedures
(essentially) under dos or equivalent operating environments (e.g. Command
Prompt under Windows) and the conventions adopted (which are essentially
common to both environments).

To a large extent the batch mode of running SATURN programs has been
superseded by the introduction of the SATWIN front end which operates under
WINDOWS. However SATWIN itself uses .bat files (although essentially invisible
to the casual user) and there are facilities within SATWIN (see 3.6) for essentially
do-it-yourself .bat file creation. It also makes use of the same “command line”
conventions as the .bat files and, in effect, SATWIN generates the command line
for you. Thus, like the study of Latin, there are still advantages in knowing
something about .bat files!

14.1 Introduction to Control Procedures / Command Lines

On all computers there are a number of ways in which the same job may be run
with varying amounts of „job control language‟ (JCL) being required of the user.
For example under DOS (or its equivalent “Command Prompt” under Windows)
the user can initiate a job by typing in a “command line” such as:

SATEASY network trips

from the terminal, where „network‟ and „trips‟ specify particular network and trip
matrix files which need not be further specified. Alternatively, under “pure”
Windows, one might select SATEASY as an icon or from a SATWIN list and then
select the files interactively. In the first case a „control procedure‟ or bat file
„SATEASY.bat‟ has been set up in order to remove most of the hard work.

For every program in the Suite there is an equivalent .bat file with the same
“name” as the .exe file (so that the SATEASY.bat procedure runs the
$SATEASY.exe program) and which requires a Command Line containing a
particular sequence of keywords and/or file names. The .bat files exist under both
DOS and/or Windows, although their functionality may differ within different
operating environments.

The main function of the bat file is to form a “bridge” between the user and the
program exe file such that file names etc get passed back and forwards between
the two. Previously under 16-bit “pure” dos this involved, to a greater or lesser
extent, logical checks and steps within the .bat file; with 32-bit programs and/or
Windows the emphasis has changed and the .bat file simply transfers the
command line into the program and the logic all takes place within the program.
This may make it more difficult for “users” to set up their own “clever” bat files to
control SATURN programs. But not impossible; see 14.11.

5101396 / May 11 14-1

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

Command line parameters or “tokens” (e.g. “network” and “trips” in the above
example) may be divided into mandatory and optional with the mandatory
parameters coming first in a fixed order followed by the optional parameters in any
order. For example to run SATEASY there are two mandatory parameters as in:

SATEASY livnet livtrips

whereas an example of the use of the optional parameters might be:

SATEASY livnet livtrips KR choice

In the documentation mandatory input is separated from the optional by a single

opening bracket (which the user need not type).

The optional parameters may be divided into specific “keywords” such as KR

above which are fixed and “parameters” such as choice above (typically
filenames) which the user selects. Certain rules cover the order in which they
must appear. In the documentation keywords are given in upper case letters and
the parameters in lower case but, generally speaking, command line tokens are
case-insensitive. (Thus either KR or kr could be used above.)

A “help” facility is provided whereby if you type in simply the name of the
procedure without any further parameters, a brief description of the format of the
procedure appears on the screen. For example, typing simply “SATSIM” would
give condensed instructions as to how to use SATSIM.bat.

Finally users should note that the .bat files supplied with SATURN are not “tablets
carved in stone” and may, unlike the .exe files, be modified by the users
themselves. Indeed, given the inherent flexibility of the SATURN programs, users
are positively encouraged to explore alternative and innovative ways of linking the
programs together, for which alternative .bat files can be extremely useful. Some
suggestions are given in 14.11.

14.2 File Specification within Control Procedures

14.2.1 General Principles

In order to run a program, e.g. SATALL, all the individual input and output files
need to be specified. This may be done in three ways:

 Via the command line

 Via filenames included in other input files (primarily .dat files)

 Interactively via the terminal

5101396 / May 11 14-2

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

or by combinations of all three. Thus the command:

SATALL net trips

specifies input files net.ufn and trips.ufm plus output files net.ufs and net.lpt
through the command line.

However the trip matrix name could also have been defined in the original data file
net.dat under &PARAM (see 6.3.4) via FILTIJ = „trips.ufm‟ and passed to SATALL
via net.ufn - (option ii above), in which case the command line:

SATALL net

would be sufficient. Indeed this method is highly recommended, in particular

since it makes subsequent command procedures considerably simpler and more
fool-proof.

Interactive file specification is used as and when files not already defined under i)
or ii) are needed. Generally speaking this is most common with the purely
interactive programs such as PIX whereas the non-interactive programs such as
SATNET or SATALL should only use methods i) and ii).

Command line filename definitions may include the extension but it is not
essential; it may also be implied either by its position in the command line or by
keywords immediately before or after. For example:

PIX livnet.ufs

will run P1X on a file livnet.ufs. Alternatively

PIX livnet

will also input livnet.ufs where the extension .ufs is implied by default.

Alternatively either:

PIX livnet UFT

or P1X livnet.uft

both define an input file “livnet.uft”. In the former case UFT is an example of a
keyword which appears after the filename it amplifies; in the latter case the
extension is explicit.

Note, however, that:

PIX livnet.uft UFT

5101396 / May 11 14-3

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

would imply a file “livnet.uft.uft”, presumably not the required file.

Equally

SATEASY net trips REDMEN tij

implies an input file tij.ufm under the REDMEN option where here the keyword
REDMEN appears before the filename it describes.

Note that the “names” used in the command line may be based on either
“filenames” or “pathnames”. Thus either:

SATNET net

or

SATNET C:/JOB/DAT/net

could both be used to specify the file C:/JOB/DAT/net.dat, where the first definition
relies on the current home directory and/or “append” search definitions to locate
the file. SATURN uf* files store both a “filename” and a “pathname” to help locate
the required files at later stages.

14.2.2 Specifying Multiple Files plus Extensions

If, for example, the user wishes to examine 2 or more input files under P1X the
command:

P1X net1 net2

would imply the two input files net1.ufs and net2.ufs since net2 is neither a
standard extension nor keyword and .ufs is the default extension. Equally:

P1X net1.ufs net2.ufs

(or variants thereof) would have the same effect.

An alternative more complicated (and somewhat out of date) general method used
by several bat files to specify multiple files on command lines is via a 3-part
specification such as:

S 9 NET1

indicating that a file NET1.UFS is input/output on channel 9 - the extension .UFS

is implied by the S. Thus in the above example we would use:

P1X net1 S 2 net2

5101396 / May 11 14-4

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

Other forms include:

A 11 NET2 ==> NET2.UFA on 11

M 3 FILE ==> FILE.UFM on 3

T 2 FILE ==> FILE.UFT on 2

Thus the initial letter - S, A, T or M - specifies the extension and must be one of
those 4, the second parameter is the channel number (with certain values being
invalid) while the third parameter gives the filename.

Two (or more) file specifications may be given, e.g., by:

S 1 NET1 A 2 NET2 M 10 MATRIX

14.2.3 Interactive File Control Procedures

Typing the program name followed immediately by the single parameter I runs
that program under the “file interactive mode” whereby the program itself requests
the names of all files, both input and output, to be entered via the
terminal/keyboard. For example:

SATLOOK I

runs SATLOOK “interactively” in terms of file definitions. This use is largely

historical and is not recommended.

Similarly the essentially “batch-style” programs SATCH and SATME2 may be run
in a form of “file interactive mode” via “SATCH I” or “SATME2 I” but equally this
usage is not recommended.

14.3 The „SATURN‟ Procedures

This section describes how to run the iterative SATURN model illustrated in
Figure 3.1 using the „SATURN‟ control procedures. Thus there are two essential
input files to be prepared by the user: (1) A network “DAT” file; and (2) A “UFM”
file describing the trip matrix to be assigned. Outputs include both binary UF* files
and ascii line printer files.

A basic distinction is whether or not the simulation/assignment loop is carried out

by one program, SATALL - the strongly recommended technique - or by two
programs, SATEASY and SATSIM, the traditional approach. Both are currently
available via, respectively, procedures SATURN and SATURN8. Thus if you
definitely want the old-style loop use SATURN8, otherwise use SATURN.

In order to run SATURN the user must issue a command of the form:

5101396 / May 11 14-5

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

SATURN network

or, if the trip matrix filename trips.ufm is not defined in the network .dat file
(which it should be!):

SATURN network trips

The following files must already exist:

network.DAT the “ascii” file containing the network data.

trips.UFM the trip matrix.
while the following will be created:
network.UFN the network file produced by SATNET
network.UFS the UF file produced by SATALL or (SATURN8) the (final) run
of the simulation.
network.LPN the line-printer file output from SATNET.
network.LPT the line printer output from SATALL
or (SATURN8)
network.UFA the final UF file produced by an assignment
network.LPA the line-printer file produced by the last assignment.
network.LPS the line-printer file produced by the last simulation

This does not of course imply that the network file must have the name
„network.DAT‟ - the user can choose any filename for the input file, but it must
have the extension DAT. Similarly all other files have a user-supplied filename
but fixed extensions as defined above.

In the case of buffer-only networks under SATURN8 the simulation program

SATSIM is not run and therefore no UFS or LPS files are created directly;
however the final output .ufa file is renamed as a .ufs file to maintain consistency.
Equally with SATURN the output file from a buffer network is always .ufs.

14.4 Extended SATURN Procedures

The basic SATURN procedure may be extended to cope with various options by
specifying certain keywords, specifically PASSQ, UPDATE, PLOD and RESTART,
plus (optionally) file names. These are described below.

N.B. These particular options cannot only be run using special bat files; they may
also be activated by setting parameters plus file names in the original .dat file. In
fact this is probably a more convenient method to follow, given that if you need to
edit a .dat file to specify PASSQ=T you might just as well specify the extra
filename as well.

5101396 / May 11 14-6

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

14.4.1 The PASSQ option: (See Section 17.3)

SATURN net2 trips PASSQ net1

executes a normal SATURN run, starting with the network „net2.DAT‟, but any
queues detected by previously running SATURN on „net1‟ are passed to „net2‟. In
other words „net2‟ represents the time period immediately following that simulated
by „net1‟.

Logically, the &OPTION namelist record in „net2.DAT‟ should define PASSQ = T

but, if not and a PASSQ file is defined, PASSQ is automatically set to T. In either
case file „net1.UFS‟ must exist.

The alternative method to invoke PASSQ using just input to the net2 .dat file
would involve the following namelist specification:
&OPTION
PASSQ = T
PQFILE = „net1.ufs‟
…
&END

In this case the command line would simply read:

SATURN net2 trips

as per normal.

Note that if, belt‟n‟braces, the PASSQ file is defined both under &OPTION and on
the command line then the file on the command line is always used.

14.4.2 The UPDATE option: (See Section 15.3)

SATURN net2 trips UPDATE net1

executes a normal SATURN run but with the data input file „net2.DAT‟ being an
improved version (and presumably representing the same time period) as a
previous run based on net1.

Logically, the &OPTION namelist record in net2.dat should define UPDATE = T

but, if not and an UPDATE file is defined via the SATURN command line,
UPDATE is automatically set to T within SATNET. In either case file „net1.UFS‟
must exist.

Alternatively the update file may be specified using the UPFILE parameter under
&PARAM as per PASSQ in 14.4.1 above. Note that if, belt‟n‟braces, the UPDATE

5101396 / May 11 14-7

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

file is defined both under &OPTION and on the command line then the file on the
command line is always used.

Note as well that a network can “update itself”; i.e., the command:

SATURN net trips UPDATE net

Would use the file net.ufs as the update file input to SATNET in order to
supplement the data in file net.dat. Ultimately, post SATALL, the original file
net.ufs would be over-written by the new version. This option enables the user to
edit the file net.dat without having to create a new filename for the file.

14.4.3 The RESTART option: (See Section 15.4)

SATALL network trips RESTART

executes the normal iterative sequence of assignment and simulation but, instead
of starting with the default flow-delay curves from a .ufn network file as input from
the network build program SATNET, the procedure starts with flow-delay curves
from the file network.ufs which had previously been processed by SATALL. At
the end of the program the file network.ufs will have been over-written.

The RESTART option is useful either for continuing a SATURN run to obtain
improved convergence or, much more frequently, to re-run an existing network
with a new trip matrix, e.g., as obtained from the update program SATME2.

N.B. Previously the RESTART option could also be used with a batch file
“SATURN8.BAT” which was equivalent to SATURN.BAT but, instead of using
SATALL, used an explicit loop over the programs SATSIM and SATEASY. Its
use is no longer recommended.

14.4.4 The PLOD option: (See Section 15.5)

SATURN net2 trips PLOD net1

executes a normal SATURN run with the data input file, „net2.DAT‟, but with the
total assigned flows from a SATURN output file „net1.UFS‟ being pre-loaded as
fixed flows onto net2.

Note that the extension of net1 above may be explicitly included in the command
line, e.g.:

SATURN net2 trips PLOD net1.ufa

But if no extension is included the extension “.ufs” is assumed and added.

Alternatively, if an extension which is not .ufs or .ufa is used, e.g., if the input
command line were:

5101396 / May 11 14-8

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

SATURN net2 trips PLOD flows.dat

Then the fixed flows would be read from a text file flows.dat; see 15.5.4.

As above the &OPTION namelist record in net2.DAT should define PLOD = T but,
if not and if a PLOD file is defined in the command line, PLOD is automatically set
to T. In either case the pre-load file “net1.UFS”, “flows.dat” etc. must exist.

Alternatively the pre-loaded file may be defined via the parameter PLDFIL (6.1) in
net2.dat, in which case the PLOD specification above is unnecessary in the
command line.

Note that, unlike PASSQ and UPDATE above, if a pre-load file is defined both
within &OPTION and on the Command Line then the file set under &OPTION is
used.

14.5 “LOG”, “KEY” and “VDU” Files: Running Interactive Programs “Off-
line”

14.5.1 Basic Principles

Log Files

All interactive programs automatically create a “log file” which contains a complete
record of all user inputs. “Inputs” include not only keyboard responses, filenames
etc. but also mouse operations. The “format” of the file distinguishes between the
different input styles; see 14.5.2 and 14.5.3 for details.

Log files have standard filenames based on the program names such as
PIXn.LOG, SATDBn.LOG, etc. where the ”generation number” n is appended
each time a program is run (within that particular subdirectory). This feature is
provided to deal with multi-tasking but - N.B.!! - it requires frequent file cleaning on
the part of the user. The maximum generation number is 99.

Key Files

The main use of the LOG files is to create “KEY files” which are used to re-run
interactive programs such as SATDB, MX or P1X in an “off-line” or “quasi-batch”
mode whereby the normal commands which are supplied by the user via the
keyboard and/or mouse are instead taken (in sequence) from a “dummy terminal”
or “key” file. Thus the second key-based run of SATDB would follow exactly the
same series of instructions as the first, the difference being that the sequence of
commands is read from successive records in the key file rather than being
directly generated by the user. This means that, for example, having performed a
particular operation interactively on file-1 it is possible to automatically repeat the
identical operations on file-2 without having to laboriously repeat the same
sequence of keyboard operations.

5101396 / May 11 14-9

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

More precise details as to how log/key files are constituted and applied are given
in sections 14.5.2 to 14.5.10.

A similar facility to KEY files is also available under command line options as
described in 14.7. Note however that KEY files are, from the point of view of a
SATURN user as opposed to the SATURN developers, far more flexible.

VDU Files

In addition there is a further option available in conjunction with the KEY option
whereby the terminal output from an interactive program may be directed either to
a terminal screen or to a dummy “VDU” file. The latter is probably a “purer” form
of off-line or batch processing; the former is more useful in a sort of demonstration
mode where a program may be run apparently on-line but with the viewer only
having to hit the <return> key and/or click the mouse at each pause rather than
having to decide on the input.

(N,B. A very useful alternative to clicking the mouse in order to advance at each
stage of a graphical routine is to use Alt-F4!)

Command Line Definition of KEY and/or VDU Files

In order to run, say, SATDB with a key file the standard command line should
(normally) contain the “keyword” KEY followed by a filename whose (implied)
extension is .key. Thus:

SATDB LIVNET KEY JAN16

runs SATDB on an input file LIVNET.UFS with terminal commands taken from a
file JAN16.KEY which has been copied (/renamed) from a .LOG file from a
previous, purely interactive run of SATDB.

The extension “.KEY” is implied and, prior to Version 10.9.21, was obligatory.
However, post November 2010, key files may either have an extension .key or
.log and may be set with or without the keyword KEY.

Thus a LOG file may be used directly as a KEY file without being renamed with its
extension changed. For example:

SATDB LIVNET KEY satdb16.log

would run SATDB with its terminal commands taken from a file satdb16.log,
presumably output as a LOG file from a previous run of SATDB.

Alternatively (post 10.9.22), the “pre-word” KEY is not an absolute necessity but
may be implied by the extension of a filename given on the command line such
that:

SATDB LIVNET JAN16.KEY

5101396 / May 11 14-10

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

or

SATDB LIVNET satdb16.log

runs SATDB on an input file LIVNET.UFS with terminal commands taken from
JAN16.KEY or satdb16.log respectively.

The inclusion/exclusion of a VDU output file is determined in the “standard” high-

level procedures by a keyword VDU followed by a file name. Hence;

SATDB LIVNET KEY JAN16 VDU FRED

runs SATDB on LIVNET.UFS with terminal input from JAN16.KEY and terminal
output to FRED.VDU. Nothing therefore appears on the screen.

Alternatively (post 10.9.22) the keyword VDU may be dropped by simply entering
a filename with an extension .VDU as in:

SATDB LIVNET KEY JAN16 FRED.VDU

Combined KEY and VDU Definitions

It is also possible to combine the KEY and VDU functions into a single command
line keyword KEYVDU such that:

SATDB LIVNET KEYVDU JAN16

is equivalent to:

SATDB LIVNET KEY JAN16 VDU JAN16

This is particularly useful when there are a large number of entries on the
command line since it saves, in effect, two words.

14.5.2 Simple KEY Files based on Keyboard Inputs; Macros

For programs such as SATLOOK, SATDB, etc. which are based purely on
keyboard (text) inputs (see 19.2) the key file contains a listing of those keyboard
inputs; more complicated structures, including inputs via the mouse, are dealt with
in 14.5.3

For example, the following key file “FUEL.KEY” creates, using SATDB, a data
array which is a linear combination of link time and distance representing fuel
consumption, and then creates a new “extended” UF file in which fuel
consumption is stored in DA array 4603. (N.B. the weighting parameters are
totally arbitrary!)

Note the use of comment lines commencing with a „*‟ (see 14.5.7).

5101396 / May 11 14-11

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

0
4
1893
4013
0
8
1
* Linear combination of distance (X1) and time (X2)
0.01*X1 + 0.0023*X2
FUEL CONSUMPTION IN MILLILITRES
4603
0
16
0
0
2
0
0
Y

Note that once an appropriate “KEY file” has been set up it may be used as part of
a standard “macro” to automatically repeat the same function but with different
network files. For example, you may automatically extend any .ufs network file
using FUEL.KEY with a standard procedural call such as:

SATDB NET S 11 NETX KEY FUEL VDU SCRATCH

which will extend NET.UFS to include fuel consumption in file NETX.UFS. The
terminal output responses would be stored in SCRATCH.VDU. (Although you
probably never need to look at this file; it is only there to make the procedure fully
“batch”.)

The procedure could be further implemented within a DOS batch (.bat) file called
by, e.g.:

DBFUEL net netx

which, at its very simplest, might consist of the single line file DBFUEL.BAT

call satdb %1 S 11 %2 KEY FUEL VDU scratch

14.5.3 Key files containing Mouse Commands etc.

Key files may contain “choices” which have been originally input in a variety of
different “formats” (as described in Section 19) including:

 normal keyboard inputs (key(s) followed by <enter>, 19.6)

 lines selected from the banner in P1X (19.4);

5101396 / May 11 14-12

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

 an item selected from a menu bar (19.5);

 an item selected from a Windows list box (19.7);

 inputs from edit boxes and/or screen editing (19.9);

 “pure” mouse input (i.e., point and click on a particular point on the screen);

 etc. etc.

All of these appear within the log/key files in differing formats, the exact details of
which need not concern the casual user. Their primary purpose is to indicate to
the program which is “reading” the key file the precise form of the input command.

Note, however, that .log files generally do not include any inputs made within
“external Windows” operations. For example, within P1X network editing it is
possible at certain stages to request “screen editing” to edit segments of text. The
request to enter Screen Editing would be recorded in the .log file but any changes
made to the text under screen edit itself are Windows operations and will not be
recorded in the .log file. Similarly if you ask to print a file any options selected
within the standard Windows Print window are not recorded in the .log file. It is
therefore recommended that such Windows-based operations should be avoided
if the intention is to re-use the inputs as a key file. See Section 14.5.9 for further
information.

An example of a log file generated by a run of P1X which uses several different
forms of inputs, as well as comments, is given below:

5101396 / May 11 14-13

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

1056 90 68 0 Display menu (Mouse pixels/status/Line)

*
* Select the list of flow options and then choose Demand:
*
1051 72 67 0 Choice of (Mouse pixels/status/Line)
1049 153 50 0 2-Flows (Mouse pixels/status/Line)
5 - Demand Flow Downstream
Menu bar: &Box 4040
376 440 1 (Mouse pixels + status)
565 279 1 (Mouse pixels + status)
1065 277 81 0 Q - Return (Mouse pixels/status/Line)
1054 403 81 0 Q - Return (Mouse pixels/status/Line)
1055 358 81 0 Q - Return (Mouse pixels/status/Line)
1052 278 66 0 SATDB Opts (Mouse pixels/status/Line)
4
0
4503
0
15
Menu bar: &Down
Menu bar: &Quit
0
1054 371 81 0 Quit = Exit (Mouse pixels/status/Line)
Yes OK to exit the program?

Thus the first choice made by the user was the line “Display menu” in the P1X
banner. 1056 and 90 indicate the precise pixel coordinates of the mouse when the
left hand button was clicked, 68 represents the ascii value of the character D (the
single highlighted character in that line), 0 gives a “status” (which is a bit too
complicated to explain and you don‟t really need to know about it!) while “Display
menu” was the text in the selected banner line. Of these the only vital piece of
information is the ascii code 68 which is used by the program to “branch”
correctly.

Thus if you were to use this command line to run a job on a different computer
with a different screen resolution the pixel coordinates of the Display menu line
might be quite different – the critical thing is that a banner line with a highlighted
character whose ascii code was 68 (i.e., D) was selected.

The line “5 - Demand Flow Downstream” simply indicates that the 5th line from a
window containing various options was selected and that the text in that line was
as indicated. Again the vital piece of information is the 5.

The two lines following &Box indicate the precise pixel coordinates used to define
the position of the box (i.e., format (e) above). Problems may occur here if the job
is re-run on a machine with a different screen resolution and/or a different window
since, in that case, the pixel position (376,440) may point to a different position in
the network as displayed. They may however be used relatively reliably by using
full screen windows to create the log/key file and re-running on an identical
machine.

5101396 / May 11 14-14

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

Note further down that, following the entry “SATDB Opts” where the input mode
becomes keyboard-based, the key file resembles that described in 14.5.2.
However, when within SATDB the user chose option 15, display to the terminal,
the commands “down” and “quit” were entered via the menu bar.

Running jobs with key files such as the one above is identical to running jobs with
“simple” key files as regards keyboard inputs (i.e., just hit <return>) but when a
mouse input is required the user must either click the left hand mouse button to
continue or, if a small window appears with the next instruction displayed, close
that window. On the other hand, if the VDU option is invoked, then the job will run
automatically without any user intervention.

(N,B. A very useful alternative to clicking the mouse in order to close the window
at each stage of a graphical routine is to use Alt-F4!)Creating standard “batch-
style” macros such as DBFUEL described in 14.5.2 becomes more difficult,
though not impossible, with mouse-based inputs. Thus a key file based on
SATDB is likely to be more reliable than one based on P1X.

14.5.4 Automatic Running of Interactive Programs

As a variation on the use of the KEY facility described above to run interactive
programs whereby the user needs to hit <return> in order to advance the program
from one (dummy) input command to the next, it is possible to run the same
programs under an “auto-timer” option such that the program pauses for a fixed
number of seconds each time an input is required before reading the input and
carrying on. Thus the program runs on the screen “unattended” so that this facility
is essentially intended to run demonstrations of SATURN programs.

In order to run programs automatically you must:

1) Type in the appropriate command line with a KEY file but ...

2) without any VDU request (otherwise the program will run in a “background”
mode) and ...

3) an extra first line inserted in the KEY file with:

(i) characters “AUTO” in columns 1-4 and

(ii) the number of (integer) seconds to pause in columns 6-7

Thus the demonstration KEY file listed in 14.5.2 would need to start:
AUTO 10
0
4
1893
etc.

in order to run with automatic pauses of 10 seconds between screens.

5101396 / May 11 14-15

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

14.5.5 The “Break” Option in Key Files

It is possible to transfer from the “batch mode” using a KEY file to “interactive
mode” by including a “break command” within the KEY file. Thus you may
continue a previous run, for example using the first run (i.e. the KEY file) to set up
various standard default options in a similar fashion to a preferences file (15.2).

A break command can be included in one of two ways:

1) By the characters “break” or “BREAK” in columns 1 to 5 of lines which

normally contain numerical input; or

2) By the single character “b” or “B” in the first line in a KEY file which contains
the response “Y” to the question do you wish to terminate.

Use (2) would probably be more convenient for most applications.

A simple file is as follows:

0
4
1893
4013
0
VDU
8
1
0.01*X1 = 0.0023*X2
FUEL CONSUMPTION IN MILLILITRES
4603
0
16
0
0
2
0
0
B N.B. Previously Y)

To use a key file “setup.key” such as the above to “initiate” a run of, say, SATDB
one could use a command line such as:

SATDB net keyvdu setup

So that the commands in setup.key would run automatically in “background

mode”, terminating at the “break line” and leaving the user free to continue from
there.

5101396 / May 11 14-16

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

14.5.6 Changing the Automatic Timer and/or VDU Options

It is possible to change the length of the „automatic pause‟ under the KEY option
by including one or more further „AUTO‟ records within the KEY file. For example
the following file starts with an automatic delay of 10 seconds but switches to 5
seconds after the input „4033‟:
AUTO 10
0
4
1893
4003
AUTO 5
0
...

Any number of AUTO records may be included.

Note that a record of the form „AUTO 0‟ or simply „AUTO‟ cancels the automatic
delay and returns you to the normal KEY mode whereby the program pauses with
each input until a key is depressed.

In addition it is also possible to revert from the automatic to the normal KEY mode
by depressing the key „Q‟ (or „q‟). This can be done „on the spur of the moment‟
from the terminal as opposed to inserting an „AUTO 0‟ record in the KEY file which
must be done in advance.

Finally it is possible to change from the VDU mode (terminal output to a fil) to the
normal terminal output to the screen mode by including a record VDU‟ in the KEY
file; e.g.:
0
4
1893
4013
0
VDU
8
1
0.01*X1 + 0.0023*X2
FUEL CONSUMPTION IN MILLILITRES
4603
0
16
...

Thus in the above example the „terminal‟ output would be initially directed to a file,
and thus be „invisible‟ to the user, but would revert to the terminal part way
through. Use this option to skip over the „boring‟ parts of a demonstration run.

5101396 / May 11 14-17

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

Equally you can switch from terminal output back to file output by a VDU record
which is therefore a „toggle‟ between the two modes. Note however that this
facility can only be used if you start with a VDU external file.

14.5.7 Comments in KEY Files

Comment records are indicated in KEY files by records with a „*‟ in the first column
as illustrated below. When these are met by programs taking their input from a
key file they are copied verbatim to the screen until a “non-comment” record is
read.
.......
1
*
* Linear combination of distance (X1) and time (X2)
*
0.01*X1 + 0.0023*X2
FUEL CONSUMPTION IN MILLILITRES
4603
0
.........

Comments may either be inserted in a key file AFTER it has been produced by an
interactive run (i.e., into the LOG file) or else they may be directly included in the
log file by typing in records commencing with a „*‟. Thus in the above example the
line „0.01*X1 ...‟ is an equation which is required by the previous menu response
of 1; if the user had typed: *<enter>, * Linear .. <enter>, *<enter>, 0.01 .. <enter>
the log file would have appeared as above.

Comments are very useful for indicating the reason for the line following and are
often used within key files which are used as tutorials to demonstrate particular
features of SATURN programs since they appear directly on the screen. They are
also very useful in key files which are used within standard “macros”, just in case
later versions of SATURN have a different sequence of input commands (they
always do!) and old key files no longer work.

14.5.8 Using Key Files “Again”

A simple key-file option is provided under program bat files for PIX, SATDB,
SATLOOK, SATED and MX to repeat the immediately preceding run of that
program via a special keyword “AGAIN”. Thus the sequence:

SATDB net1

SATDB net2 AGAIN

runs SATDB on net2.ufs using the same sequence of commands as for net1. It
does this by copying the .log file from the first run into a temporary .key file (the
actual filename used is again.key but the user need not take any notice of this)

5101396 / May 11 14-18

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

and using this as a normal “KEY file” in the second run. It is therefore equivalent
to:

SATDB net1

copy satdb.log repeat.key

SATDB net2 KEY repeat

The procedure could be repeated for further runs as in:

SATDB net3 AGAIN

as long as of course no other run of SATDB is executed in between.

14.5.9 Edit Box Operations in LOG/KEY Files

User inputs within SATURN may be sub-divided into “internally controlled” and
“externally controlled” operations, whereby externally controlled inputs occur, for
example, when a Windows edit box or a screen edit window (see 19.9) is created
and control is effectively passed to a Windows operation in order to change the
values set for certain variables and/or text.

The problem that externally controlled processes create for LOG files is that it is
no longer possible for SATURN programs to “know” exactly which keyboard and
mouse inputs have been invoked by the user and therefore it is not possible to
record the exact sequence within a LOG file as with “internally controlled” inputs.

On the other hand, and in principle, it is possible to compare the data that was
passed to the external process and returned in order “to infer” the inputs. Thus,
when possible, SATURN creates an entry in a log file containing the text “ Edit
Box:” in columns 1 to 10 followed by a stream of data values detailing the outputs.
For example, if an edit box is created to set values for 5 separate variables (e.g.,
saturation flow, lane choices etc. for a turn under node editing) then the returned
values of those 5 variables may be listed in the LOG file.

When a KEY file process encounters an Edit Box record it may then read the
following inputs and proceed accordingly.

Note that this option is not generally available with screen editing operations
where the data passed is generally much longer than can be stored on a single
record.

14.5.10 Opening Files within Key files: Potential Pitfalls

Programs which are run using KEY files (and equally the original interactive
program run that created the LOG/KEY file) very often open files interactively and

5101396 / May 11 14-19

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

this may create certain problems as described next. N.B. These problems have
been largely eliminated from release 10.6.16 onwards.

For example, if the original program creates an output file “jim.dat” whose name is
set interactively (i.e., via a Windows dialog box) then the name of that file will
appear as a separate line within the LOG – and therefore the KEY – file. If jim.dat
were an existing file in the first place then the user would have been prompted
with the query “Do you wish to over-write jim.dat?”, to which the answer would
have been presumably Yes and the next line in the LOG/KEY file would be Y to
record that response. Thus the appropriate segment of the .log file might have
read:
0
jim.dat
y
0
On the other hand if the file jim.dat did not exist then the query to over-write would
not have existed and the LOG/KEY file would read:
0
jim.dat
0
Let us call the two alternative versions A and B respectively.

The first potential problem occurs if, at the time that the KEY file procedure is run,
the file jim.dat does not exist and version A above is being used in the key file. In
this situation the query about over-writing would not be relevant, the line
containing Y would not be needed and the “correct” version of the key file would
be B.

The second problem occurs in the reverse situation: jim.dat exists but Version B
(without the Y line) is incorrectly used as the KEY file. (Indeed it is this situation
which occurs most frequently when a new output file jim.dat is created in the initial
run and still exists when the KEY file run is executed, )

In older versions of SATURN the end effect was the same in both cases: the
program crashed.

1) However release 10.6.16 now solves both problems by checking the

instruction line following a file definition line. If it contains a Y which is not
needed the line is skipped; if it does not contain Y but a response is required
then an additional Y line is effectively added. Both situations are flagged as
Non-fatal errors.

2) (N.B. The latter case above assumes that the desired response is always Y,
over-write the file, although clearly a N reply (do not over-write, choose
another file) is also possible. However, it is somewhat “sloppy procedure” to
have a key file which defines the “wrong” file as implied by an N. Hence the
assumption is always that if a Y/N line is not provided then the desired
answer should be Y.)

5101396 / May 11 14-20

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

3) Alternative Procedures. Alternatively, there are several ways around both

these potential problems (and, prior to 10.6.16., one of these would have
been necessary)

The first is to ensure that the “status” of all files prior to a KEY run is identical
to that prior to the original run. This could involve deleting any existing files
which are due to be created as new files.

A second is to manually edit in or out the required Y or N lines as required

in the KEY file (but even then you have to be careful that the edited KEY file
is consistent with the status of all relevant files every time you come to use
it).

A third method, which has the advantage of simplicity, is to set the

parameter GO4IT (as described in Appendix Y) to .FALSE. in both the
original and repeat runs. In this case all existing files are automatically over-
written, questions regarding over-writing never occur and both the original
.log file and the “correct” key file will be as per the second data segment
above, i.e., no line “y”.

There are several ways to ensure GO4IT = F. Firstly, it may be set

interactively by locating the menu containing the “General SATURN
Parameters” menu and re-setting GO4IT as necessary. Secondly, it may be
set within the preferences files P1X0.DAT etc. for all the main interactive
programs: P1X, SATLOOK, SATDB and MX. Finally, GO4IT may also be
universally set within SAT10KEY.DAT but this practice is not entirely to be
recommended since it removes a useful general safeguard; see Appendix Y.

14.6 Namelist Parameters Set on the Command Line

Within certain programs and their associated bat files it is possible to include
namelist parameter definitions as the final entries on the command line. For
example:

SATALL net &PARAM GONZO 1.2

runs SATALL on the file net.ufn but over-rides the existing value of GONZO to
1.2. The effect is the same as:

SATALL net KR control

where control.dat contains

&PARAM

GONZO = 1.2

&END

5101396 / May 11 14-21

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

However for one-off parameter changes it is much easier to include the change on
the command line than to create a new control file.

Note that due to a quirk of DOS it is not possible to include equal signs on the
command lines; “GONZO = 1.2” is treated as “GONZO 1.2 1.2”. However since
namelist input does not require “=” (see Appendix A) this is not a problem.

It is possible to use both a control file containing namelist definitions and

command line definitions, in which case the control file is processed first and the
command line definitions over-ride as necessary. Thus the facility is not dissimilar
to the PS files used by SATNET (see 15.2.3)

The facility is at the moment provided only for the following programs and only for
namelist &PARAM although it may well be extended later:

SATALL, SATSIM, SATEASY and SATME2

It cannot be used with “composite” bat files such as SATURN which call a further
series of individual bat files, and it cannot be used with interactive programs such
as PIX or SATDB.

14.7 Command Line Options and Batch Procedures

In SATURN certain programs, e.g., MX, allow certain options to be specified on

the command line using a /option convention so that, e.g.

$MX trips /BUILD

implies that $MX.EXE will follow a pre-defined sequence of “build” operations in

order to create a .ufm file from an input file trips.dat.

The end result is very similar to using a key file, the main difference being that the
sequence of choices is not user-set but fixed. This is useful for certain “standard”
options such as matrix building. It has the further advantage that it does not use
key files which may become invalid with newer versions of SATURN.

The facility may be further extended and simplified (from the user‟s point of view)
by creating standard “Batch Procedures” so that, for example, to dump a matrix
.UFM file TIJ.UFM into a CSV ascii formatted file (see 10.20.15) the user could
either type in directly:

$MX matrix TIJ /DUMP5

or use the as-provided batch procedure UFM2CSV:

UFM2CSV TIJ

5101396 / May 11 14-22

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

where DUMP5 above is a special keyword which implies “dump into CSV format”.
The batch file UFM2CSV.BAT simply re-creates the previous command line in
order to run the program MX to carry out the same function.

A number of standard applications within MX based on this methodology are

described in Section 10.20. In addition further examples may also be found using
SATLOOK, SATDB and P1X.

14.8 Extended Command Line Files: Using .XCL Files

There is a DOS-imposed upper limit of 10 “tokens” (i.e., “words”) on a normal

command line which, in general, is sufficient for most applications but not all. For
example, a run of MX may need to input up to 9 .ufm files plus other options and
outputs and therefore exceed the above limit of 10 tokens.

Release 10.7 introduced an option to effectively extend the number of words on a

Command Line using so-called “.XCL files”. Thus the command:

MX mat1 XCL list

would open a text (ascii) file list.xcl and concatenate its contents to the right of
“mat1”. Thus, if list.xcl contained a single line:

mat2 mat3 OUT matnew

then, in effect, the complete Command Line would be:

MX mat1 mat2 mat3 OUT matnew

Alternatively a .XCL file may contain several lines (records) so that, for example,
the file list.xcl illustrated above might also be written:

Mat2

Mat3

OUT matnew

with the same effect.

There is no limit to the number of words which may be contained within a .XCL file
nor, therefore, to the number of words on the combined Command Line.

Currently the .XCL option is only available with MX (where it is most likely to be
needed) but, in principle, it could be used with any SATURN batch file. Requests
to DVV for alternative applications.

5101396 / May 11 14-23

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

Note that whenever XCL + filename are read on a command line then the
processing transfers to the new file immediately; i.e., any further tokens on the
original command line are ignored. Therefore any additional tokens should be
included within the continuation record(s).

14.9 QUIET Command Lines

In general when a program is run from a Command Line a window to hold

“terminal” output is created by the program and displayed on the desktop. For
certain programs, e.g., interactive programs such as SATLOOK, the terminal
window is essential; for others which, once initiated, essentially run without any
further user intervention, such as SATME2, the information displayed in the
terminal window such as listings of files used, etc. is provided simply to remind the
user what is happening and is not essential.

However, one of the problems with terminal windows is that they tend to “grab
focus”. Thus if, say, a user has set up a batch file to run a long sequence of
SATURN programs “in the background” and they wish to do something in Word
while the SATURN programs are running, each time a new program starts and a
new terminal window is created the user will have to minimise that window before
they can continue with Word. Not fatal but mildly annoying!

Note that this problem does not occur when interactive programs such as
SATLOOK are run with KEY + VDU modes in force since, in that case, no
terminal windows are set up.

In order to allow other programs to run “quietly” in the background as well a

special Command Line parameter QUIET has been set up such that, e.g., the
command:

SATALL net trips QUIET

will run SATALL without creating a terminal window or “grabbing focus”.

Presently the parameter QUIET is restricted certain programs only, specifically

SATNET, SATALL, SATSIM, SATEASY, SATPIJA, SATPIG, SATSUMA,
SATCH and SATME2 since these are the programs that users are most likely to
want to run in the background. Requests for the same facility in other programs to
Atkins.

Alternatively QUIET may be set to .TRUE. using a toggle provided within

SATWIN, in which case it will be applied automatically to all programs which
recognise the QUIET option (as listed above). See 15.55.

14.10 QUICK Command Lines

If a command line contains the keyword “QUICK” this signifies that the program is
to be run with the minimum number of iterations, loops, etc. etc. so that it runs
with minimal cpu time. For example (and indeed this is virtually the only example),

5101396 / May 11 14-24

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

if a SATALL command line contains QUICK then MASL is set to 1, NITA and
NITA_M to 3, NITA_S to 2 and NITS and NITS_M to 5.

The basic objective of using QUICK is to test whether or not complicated batch
files which call a large number of programs and need to pass files between them
have been correctly set up before leaving them to run, say, over the weekend.

Alternatively QUICK may be set to .TRUE. using a toggle provided within

SATWIN, in which case it will be applied automatically to all programs which
recognise the QUICK option (as listed above). See 15.55.

14.11 Create Your Own BATCH Files: A Beginners‟ Guide

Batch files – or .bat files to use their standard extension – are files which
individual SATURN users may create to run one or more SATURN .exe files
and/or other procedures. As such they may save considerable time and effort, in
particular for standard operations which are repeated multiple times, e.g. with
different networks and/or matrices each time. This is available through the DOS
Command Shell in SATWIN (see Section 3.6 et al)

Under 16-bit .bat files operated within the standard dos operating system; with 32-
bit they operate under Command Prompt. The latter appears to lack some of the
functionality of dos but, for simple operations, it is difficult to spot the differences.

As an example, to update a trip matrix file using SATME2 may require running
three programs in succession by commands such as:

SATALL net1 trips1

SATPIJA trips1 counts
SATME2 trips2 counts PRIOR trips1

where SATALL, SATPIJA and SATME2 are themselves .bat files which call the
equivalent .exe files.

The above three commands may themselves be subsumed into a single .bat file,
say UPME2 .bat, which could be written as:

CALL SATALL %1 %2
CALL SAPIJA %2 %3
CALL SATME2 %4 %3 PRIOR

so that typing:

UPME2 net1 trips1 Counts

would have the same effect as the original three commands. Note the use of %1,
%2 etc within the bat file to represent the successive arguments on the command
line; at execution net1 would be substituted for %1 in the call to SATALL etc

5101396 / May 11 14-25

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

Note that .bat files may themselves call other .bat files (but see below for
problems under 32-bit windows) which themselves call other .bat files to produce
a hierarchical structure.

Calls to standard dos functions may also be included, for example one file may be
copied into another so that UPME2 above might include a final line.

COPY %4.UFM LATEST.UFM

in order to save the “latest” trip matrix file with a standard name. Equally
temporary files may be deleted etc.

.Bat files may also include certain error checks and internal logic. For example
one may check whether or not an essential input file exists and take the
appropriate action if not, or the “convergence status” of a particular operation
monitored in order to terminate at the required level. Dos manuals may be
consulted for further information.

Within Windows, and Command Prompt, one particular problem arises which is
that Windows does not (apparently) wait for one program to terminate before
starting the next. Thus, in the above example, SATPIJA may begin before
SATALL has finished and therefore before the necessary file net1.ufs has been
created. A solution to this problem involves 2 “tricks”,

1) Use direct calls to exe files rather than to .bat files;

2) Use the command “start/W” as below.

Thus the UPME2.bat file above under Windows would become:

Start/W $SATALL %1 %2
Start/W $SATPIJA %2 %3
Start/W $SATME2 %4 %3 PRIOR %2

Empirically this guarantees that SATPIJA will only be initiated once SATALL has
terminated and all necessary files are available. For an example please look at
SATURN.bat.

There may of course be other “tricks” available within Windows to accomplish the
same ends. We only report what works for us!

5101396 / May 11 14-26

10_09_24_Section 14.doc
SATURN MANUAL (V10.8)

Control Procedures (DOS Batch Files)

14.12 Version Control

JOB NUMBER: 5101396 DOCUMENT REF : Section14.doc

Revision Purpose / Description

Originated Checked Reviewed Authorised Date

1 Re-formatted (Final to DVV) TF / BG NS IW IW 06/05/06

2 S14.5.9 Updated DVV 25/05/06

3 Upgrade to V2 Template IW 22/06/06

3.1 14.5.9 updated again DVV 09/07/06

3.2 Web release – Sept 06 DVV NP IW IW 08/09/06

3.3 Web release – Jan 07 DVV NP IW IW 04/01/07

3.4 SATURN v10.7 DVV NP IW IW 12/03/07

3.4.1 V10.7.10 Release DVV NP IW IW 24/04/07

3.5 Web release – Jul 07 DVV NP IW IW 19/07/07

14.9 QUIET DVV 06/08/07

3.6 SATURN v10.8 Release DVV NP IW IW 26/01/08

3.7 Web release – Jul 08 DVV NP IW IW 07/07/08

3.8 Web release – Dec 08 DVV NP IW IW 12/12/08

3.8.21 Web release – Feb 09 DVV NP IW IW 16/02/09

3.8.22 Web release – Jun 09 DVV NP IW IW 16/06/09

10.9.10 SATURN v10.9 Release DVV DG IW IW 04/09/09

10.9.12 SATURN v10.9 Release (Full) DVV DG IW IW 22/10/09

10.9.17 Web release – Jun 10 DVV NP IW IW 22/06/10

10.9.22 Web release – Dec 10 DVV AG IW IW 06/12/10

10.9.24 SATURN v10.9 Release (Full) DVV AG IW IW 06/05/11

5101396 / May 11 14-27

10_09_24_Section 14.doc