TOP language

TOP is an interpreter of a scripting language specialized for certain areas. Its use includes programs MODELLER and ASGL. Its syntax resembles that of FORTRAN.

The source file

Each TOP program or include file is stored in a file named 'program.top'. The .top extension is mandatory.

The TOP program consists of a series of commands. The order of commands is important. An example of the TOP program that writes integers 1 to 10 to the output file is:

# Define a variable:
DEFINE_INTEGER VARIABLES = IVAR

# Open a file for appending
OPEN IO_UNIT = 21, OBJECTS_FILE = 'output.file', FILE_ACCESS = 'APPEND'

# Loop from 1 to 10:
DO  IVAR = 1, 10, 1
  # Append IVAR to the output file:
  WRITE IO_UNIT = 21, OBJECTS = IVAR
END_DO

# Close a file
CLOSE IO_UNIT = 11

# Exit:
STOP

There can be at most one command per line. Each command or line can be at most LENACT (512) characters long. The command can extend over several lines if a continuation character `;' is used to indicate the end of the current line. Everything on that line after the continuation character is ignored.

A comment character `#' can be used anywhere on the line to ignore everything that occurs after the comment character.

Blank lines are allowed. They are ignored.

TAB characters are replaced by blank characters.

TOP converts all commands to upper case, except for the string constants that are quoted in single quotes '. Thus, TOP is case insensitive, except for the quoted strings.

There are two groups of commands: flow control commands and commands that perform certain tasks. The next two sections describe the flow control commands and those `performing' commands that are an integral part of TOP. There are also additional commands specific to each application of TOP, such as MODELLER and ASGL, which are described elsewhere.

The usual UNIX conventions are used for typesetting the rules. Table 4.1 explains the shorthand used to describe different variables and constants:

Table 4.1:

$\langle{\tt integer:1}\rangle$	an integer variable or constant
$\langle{\tt real:1}\rangle$	a real variable or constant
$\langle{\tt string:1}\rangle$	a string variable or constant
$\langle{\tt logical:1}\rangle$	a logical variable or constant
$\langle{\tt var\_:1}\rangle$	prefix for a variable
$\langle{\tt const\_:1}\rangle$	prefix for a constant
$\langle{\tt variable:1}\rangle$	$\langle{\tt var\_integer:1}\rangle$ | $\langle{\tt var\_real:1}\rangle$ | $\langle{\tt var\_string:1}\rangle$ | $\langle{\tt var\_logical:1}\rangle$
$\langle{\tt constant:1}\rangle$	$\langle{\tt const\_integer:1}\rangle$ | $\langle{\tt const\_real:1}\rangle$ | $\langle{\tt const\_string:1}\rangle$ | $\langle{\tt const\_logical:1}\rangle$
$\langle{\tt number:1}\rangle$	$\langle{\tt integer:1}\rangle$ | $\langle{\tt real:1}\rangle$
$\langle{\tt quantity:1}\rangle$	$\langle{\tt variable:1}\rangle$ | $\langle{\tt constant:1}\rangle$
$\langle{\tt quantity:0}\rangle$	a vector of any length with elements $\langle{\tt quantity:1}\rangle$
$\langle{\tt quantity:N}\rangle$	a vector of $N$ elements $\langle{\tt quantity:1}\rangle$

All the variables are formally vectors. When a variable is referred to in a scalar context its first element is used. All elements of one vector are of the same type. All variables, including a vector of the variable length, must have at least one element.

There are four different variable types: integer, real, string and logical.

The real constant is (FORTRAN real number representation):

  [+|-][digits][.][digits][{e|E|d|D}{+|-}digits]

The integer constant is (FORTRAN integer number representation):

  [+|-][digits]

The logical constant can be either on or off (case insensitive).

The string constant can contain any character except for a prime '. It can be optionally enclosed in primes. If it is not quoted it is converted to upper case and its extent is determined by the position of the blanks on each side of the contiguous string of non-blank characters.

TOP Commands

There are `flow control' and `performing' commands. If general, the `performing' commands have the following syntax:

ACTION [ASSIGNMENT, ASSIGNMENT, ..., ASSIGNMENT]

ACTION specifies what action to take. ASSIGNMENT sets the variable to the specified value. The values assigned in this way are kept until the next assignment. For example, CALL ROUTINE = 'routine_name', IVAR = 3 sets the integer variable IVAR to 3 and then calls routine routine_name; if IVAR is not changed in the routine, its value will remain to be 3 after the call to the routine.

There can be any number of assignments in a command. They must be separated by commas. The assignment is of the form:

$\langle{\tt variable:0}\rangle$ = [-] $\langle{\tt quantity:0}\rangle$

The `=' character is optional (can be replaced with a blank).

$\langle{\tt integer:1}\rangle$ and $\langle{\tt real:1}\rangle$ can be assigned to each other. When a real number is assigned to an integer variable, the decimal places are ignored. That is, the result is the same as if the FORTRAN function IFIX() was used. There must be no space between the optional $-$ and $\langle{\tt quantity:0}\rangle$. If a vector variable is assigned to a variable, all its elements are used.

Real, integer, and logical variables can also be assigned to a string variable. The conversion of a real variable to a string value is guided by the TOP variable NUMBER_PLACES which is of type $\langle{\tt integer:2}\rangle$. The first element of NUMBER_PLACES sets the number of places before the decimal point, and the second element the number of places after the decimal point. If the latter is $-1$, an integer number without a decimal point is obtained, if 0 there is a decimal point without any decimal places.

Assignments can follow any command, except DO, END_DO, GO_TO, LABEL, STOP, and END_SUBROUTINE.

DEFINE_INTEGER -- define integer variables

Options:

Description:

This command defines user integer variables. All variables used in the TOP program must be defined. An exception are the pre-defined TOP variables listed at the end of this section.

DEFINE_LOGICAL -- define logical variables

Options:

Description:

This command defines user logical variables.

DEFINE_REAL -- define real variables

Options:

Description:

This command defines user real variables.

DEFINE_STRING -- define string variables

Options:

Description:

This command defines user string variables.

SET -- set variable

Command:

SET [ASSIGNMENT, [ASSIGNMENT, ...[ASSIGNMENT]]]

Description:

This command sets the values of variables of any of the four types. See the description of ASSIGNMENT above.

There can be UNIX shell environment variables in any input or output filename. The environment variables have to be in the format ${VARNAME} or $(VARNAME). Also, four predefined macros are available for string variables:

Four predefined macros are available for string variables:

• '${LIB}' is expanded into $LIB_APPLICATION shell environment variable, where APPLICATION is the name-version of the program (, MODELLER5);
• '${DIR}' is expanded into the TOP variable DIRECTORY,
• '${JOB}' is expanded into the root of the TOP script filename,
• '${DEFAULT}' is expanded into (ROOT_NAME)(FILE_ID)(ID1)(ID2)(FILE_EXT), where ROOT_NAME, FILE_ID, ID1, ID2, and FILE_EXT are TOP variables. FILE_ID is a string that may be set to 'default'. In that case, a hard-wired short string is used instead of FILE_ID. Otherwise, the explicitly specified FILE_ID is applied instead. In any case, FILE_ID is not modified by the filename generation routine so that it can be used more than once without resetting it to the 'default' value. Four digits are used for both ID1 and ID2. For example, '2ptn.B99990001' results from ROOT_NAME = '2ptn', FILE_EXT = '.B', ID1 = 9999, and ID2 = 1.

OPERATE -- perform mathematic operation

Options:

Description:

This command performs a specified mathematical operation. There can be up to MRPRM (120) operands for the 'SUM' and 'MULTIPLY' operations, but only two for 'DIVIDE' and 'POWER'. The RESULT value has to be the name of a real variable.

STRING_OPERATE -- perform string operation

Options:

Description:

This command performs a specified string operation. There can be up to MSPRM (130) operands for the CONCATENATE operation. The RESULT value has to be a name of the string variable.

RESET -- reset TOP

Description:

This command resets the internal state of TOP and its predefined variables to their initial values. It does this by calling the initialization routine that reads the 'top.ini' file. This command also undefines all user defined variables.

OPEN -- open input file

Options:

Description:

This command opens a specified file on the specified I/O stream for formatted access. FORTRAN conventions apply to FILE_ACCESS and FILE_STATUS.

WRITE -- write TOP objects

Options:

Description:

This command writes the specified objects to a single line which is then written to a selected I/O stream. Each element of the OBJECTS vector is first tested if it is a name of a variable of any type. If it is the contents of that variable is written out. If it is not, the element is treated as a string constant. The first and second element of NUMBER_PLACES set the numbers of places before and after the decimal point, respectively, for real and integer objects.

READ -- read record from input file

Options:

Description:

This command reads a line from the file on the I/O channel IO_UNIT. The line goes into the string variable RECORD.

CLOSE -- close an input file

Options:

Description:

This command closes a specified I/O stream.

WRITE_TOP -- write the TOP program

Options:

Description:

This command writes the current TOP program in memory to a specified file.

SYSTEM -- execute system command

Options:

Description:

This command executes the specified UNIX command.

INQUIRE -- check if file exists

Options:

Description:

This command assigns 1 to FILE_EXISTS if the specified file exists, otherwise it assigns 0. You can use it with a subsequent IF command for the flow control.

GO_TO -- jump to label

Command:

GO_TO $\langle{\tt string:1}\rangle$

Description:

The `go_to' statement, which transfers execution to the TOP statement occurring after the LABEL statement with the same name.

LABEL -- place jump label

Command:

LABEL $\langle{\tt string:1}\rangle$

Description:

This command labels a target position for the GO_TO statement with the same name.

INCLUDE -- include TOP file

Options:

Description:

This command includes a TOP file INCLUDE_FILE. You do not have to specify the .top extension. First, the given filename is tried. Second, the directory specified in the $BIN_APPLICATION environment variable is prefixed and the open function is tried again. INCLUDE command is useful for including standard subroutines.

CALL -- call TOP subroutine

Options:

Description:

This command calls a TOP subroutine ROUTINE.

SUBROUTINE -- define TOP subroutine

Options:

Description:

This command is the first TOP statement for any routine. It has to have a matching END_SUBROUTINE. No nesting of subroutine definitions is allowed, although the definitions can be located anywhere in a file.

RETURN -- return from TOP subroutine

Description:

This command will exit the execution from the current routine. It is optional.

END_SUBROUTINE -- end definition of TOP subroutine

Description:

This command has to be present at the end of each routine. Possibly used instead of RETURN if RETURN not present.

DO -- DO loop

Command:

DO VAR = START, END, STEP
commands
END_DO

Description:

Commas after START and END can be omitted. This loop is exactly like a FORTRAN DO loop except that real values are allowed for any of the four controlling variables. VAR must be a variable, while START, END and STEP can also be constants.

IF -- conditional statement for numbers

Options:

Description:

This command performs conditional IF operation on two real arguments. The possible operations are equal (EQ), greater than (GT), less than (LT), greater or equal (GE), less or equal (LE), and not equal (NE). If the condition is true, the command specified in the THEN variable is executed. Otherwise the command in the ELSE variable is executed. Typically, these commands are GO_TO statements.

STRING_IF -- conditional statement for strings

Options:

Description:

This command performs conditional IF operation on two string arguments. The possible operations are equal (EQ), not equal (NE), and the FORTRAN index() function (INDEX), which returns true if there is `argument2' substring within `argument1'. If the condition is true, the command specified in the THEN variable is executed. Otherwise the command in the ELSE variable is executed. Typically, these commands are GO_TO statements.

STOP -- exit TOP

Description:

This command stops the execution of the TOP program.

Predefined TOP variables

Table 4.2:

Name	Type
ARGUMENTS	$\langle{\tt real:0}\rangle$
IO_UNIT	$\langle{\tt integer:1}\rangle$
ID1	$\langle{\tt integer:1}\rangle$
ID2	$\langle{\tt integer:1}\rangle$
NUMBER_PLACES	$\langle{\tt integer:2}\rangle$
FILE_EXISTS	$\langle{\tt integer:1}\rangle$
OUTPUT_CONTROL	$\langle{\tt integer:4}\rangle$
STOP_ON_ERROR	$\langle{\tt integer:1}\rangle$
ERROR_STATUS	$\langle{\tt integer:1}\rangle$
OBJECTS	$\langle{\tt string:0}\rangle$
VARIABLES	$\langle{\tt string:0}\rangle$
ROUTINE	$\langle{\tt string:1}\rangle$
ROOT_NAME	$\langle{\tt string:1}\rangle$
DIRECTORY	$\langle{\tt string:1}\rangle$
FILE_ID	$\langle{\tt string:1}\rangle$
OPERATION	$\langle{\tt string:1}\rangle$
RESULT	$\langle{\tt string:1}\rangle$
STRING_ARGUMENTS	$\langle{\tt string:0}\rangle$
OBJECTS_FILE	$\langle{\tt string:1}\rangle$
INCLUDE_FILE	$\langle{\tt string:1}\rangle$
FILE	$\langle{\tt string:1}\rangle$
RECORD	$\langle{\tt string:1}\rangle$
THEN	$\langle{\tt string:1}\rangle$
ELSE	$\langle{\tt string:1}\rangle$
COMMAND	$\langle{\tt string:1}\rangle$
FILE_EXT	$\langle{\tt string:1}\rangle$
OUTPUT_DIRECTORY	$\langle{\tt string:1}\rangle$
FILE_ACCESS	$\langle{\tt string:1}\rangle$
FILE_STATUS	$\langle{\tt string:1}\rangle$