Chapter 1: Overview

1.1 Introduction

This manual describes the graphics command language DISGCL which is an interpreter based on the graphics software DISLIN. All DISLIN statements can be written to a script file and then be executed with DISGCL, or can be entered in an interactive mode.

Similar to programming languages such as Fortran and C, high-level language elements can be used within DISGCL. These are variables, operators, expressions, array operations, loops, if and switch statements, user-defined subroutines and functions, and file I/O routines.

An easy to use interface for data input is given to include data into DISGCL jobs. The format of data files is very simple and useful for most DISLIN plotting routines.

Several quick plots are offered by DISGCL which are collections of DISLIN statements to display data with one command.

1.2 Syntax of the DISGCL Command

The DISGCL command has the following syntax:

Command: DISGCL [filename[.gcl]] [args] [options]

filename is the name of a DISGCL script file. The extension '.gcl' is optional.

args are optional arguments that can be passed to DISGCL scripts. The arguments are stored in the system variables %ARG1, %ARG2, ..., %ARGn, or can be requested with the function GETARG (i), 1 <= i <= n. The number of passed arguments is stored in the system variable %NARGS.

options is an optional field of keywords separated by blanks:

-D=device defines the format of the metafile created by DISLIN. This parameter will overwrite the keyword in the DISLIN routine METAFL and can have the same values as the parameter in METAFL.

-F=file defines the file used for data input. This parameter will overwrite the file parameter in the routine DATFIL.

-I=file replaces the file parameter of the first INCLUDE statement in a DISGCL script file. This option can be used to initialize variables with different values.

-f means that the extension '.gcl' is not added to the filename.

-o opens a console window on Window systems.

-v prints program version and author.

Additional notes:

If no parameters are specified, DISGCL runs in interactive mode.
DISGCL searches the current working directory for the DISGCL script file. If the search fails, DISGCL searches the directory defined by the environment variable GCL_PATH.
On UNIX systems, an DISGCL script file can be executed directly if the following line is included at the beginning of the script file:
#! /path/disgcl -f
where path is the directory containing the disgcl executable.

1.3 Syntax of DISGCL Script Files

DISGCL script files must have the following syntax:

A DISGCL script file must begin with the indentifier '%GCL'.
Each line may contain up to 132 characters.
The current statement can be continued on the next line if a masterspace (@) is used at the end of the line.
Lines are allowed to carry trailing comment fields, following a double slash (//) or the '#' character. Empty lines are also be interpreted as comment lines.
Keywords and routine names can be in upper and lowercase letters.
String constants must be enclosed in a pair of either apostrophes or quotation marks.

Example:

%GCL
SUM = 0
DO I = 1, 10 
  SUM = SUM + I 
END DO 
PRINT SUM

1.4 Syntax of Statements

The following statements can be used in DISGCL script files, or can be typed directly at the DISGCL prompt.

 -----------------------------------------------------------
 | %GCL                       | Identifier for DISGCL      |
 |                            | script files.              |
 -----------------------------------------------------------
 | // comment or # Comment    | Comment line and inline    |
 |                            | comments.                  |
 -----------------------------------------------------------
 | Routine (parameter list)   | Call of a DISLIN or DIS-   |
 |                            | GCL routine                |
 -----------------------------------------------------------
 | CALL routine (param. list) | Call of a user-defined     |
 |                            | subroutine.                | 
 -----------------------------------------------------------
 | v = function (parameter    | Call of a DISLIN, DISGCL   |
 |                   list)    | or user-defined function.  |
 -----------------------------------------------------------
 | v = expression             | Assigns the value of the   |
 |                            | expression to the variable |
 |                            | v.                         |     
 -----------------------------------------------------------
 | Command  [parameter list]  | DISGCL command.            |
 |                            |                            |
 -----------------------------------------------------------
 | vray = { constant list }   | Creates and initializes an |
 |                            | integer or floating point  |
 |                            | array.                     |
 -----------------------------------------------------------
 | if (expression) statement  | IF statement (conditional  |
 |                            | statement).                |
 -----------------------------------------------------------
 | if (expression)            | IF construct. Up to 8 IF   |
 |   statements               | constructs can be nested.  |
 | else if (expression)       | The ELSE IF and the ELSE   |
 |   statements               | parts are optional.        |
 | else                       |                            |
 |   statements               |                            |
 | end if                     |                            |
 -----------------------------------------------------------
 | do v = expr1, expr2        | DO loop. Up to 8 loops can |
 |                [,expr3]    | be nested.                 | 
 |   statements               |                            |
 | end do                     |                            |
 -----------------------------------------------------------
 | while (expr)               | WHILE loop. Up to 8 loops  |
 |   statements               | can be nested.             |
 | end while                  |                            |
 -----------------------------------------------------------
 | switch (iexpr)             | SWITCH statement where     |   
 |   case n1:                 | iexpr must be an integer   |
 |     statements             | expression and n1, n2, ... |
 |   case n2:                 | integer constants.         |
 |     statements             | Up to 8 SWITCH statements  |
 |   ......                   | can be nested.             |
 |   default:                 |                            |
 |     statements             |                            |
 | end switch                 |                            |
 -----------------------------------------------------------
 | label:                     | Label statement.           |
 -----------------------------------------------------------
 | goto label                 | GOTO statement.            |
 -----------------------------------------------------------
 | $command                   | Executes a system command. |
 -----------------------------------------------------------
                 Figure 1.1: DISGCL Statements

1.5 Data Types

Variables in DISGCL are dynamic. They don't have to be declared, and they can change their types during the lifetime of a DISGCL session. The following data types are known by DISGCL:

CHAR an 8-bit integer in the range -128 to 127.

BYTE an 8-bit integer in the range 0 to 255.

SHORT an 16-bit integer in the range -32768 to 32767.

INT an 32-bit integer in the range -2147483648 to 2147483647.

FLOAT an 32-bit floating point number in the range 1.2E-38 to 3.4E+38 and with 7-digit precision.

DOUBLE an 64-bit floating point number in the range 2.2E-308 to 1.8E+308 and with 15-digit precision.

COMPLEX a pair of 32-bit floating point numbers in the range 1.2E-38 to 3.4E+38.

STRING a sequence of characters. Strings are stored as CHAR arrays terminated with the ASCII value zero.

1.6 Expressions

An expression is an combination of operands and operators. The operands can be constants, variables and functions, and may be scalars or arrays. Expressions can be assigned to variables or can be passed as parameters to subroutines and functions.

Example:

a = 60
x = exp (sin (a * 3.14159))

1.7 Quick Plots

DISGCL offers several quick plots which are collections of DISLIN routines that can display data with one command. For example, the DISGCL command PLOT displays two-dimensional curves.

Example:

x = falloc (100)
plot x, sin (x/5)

Figure 1.1: Example of the PLOT Command

Additional note:

All quick plots have corresponding widget interfaces that can be executed with the command
disgcl quickplot
where quickplot is the name of a quick plot. The widget interfaces for quick plots expect data in the form of data files described in chapter 8, 'Data Files'.

Next | Contents

filename	is the name of a DISGCL script file. The extension '.gcl' is optional.
args	are optional arguments that can be passed to DISGCL scripts. The arguments are stored in the system variables %ARG1, %ARG2, ..., %ARGn, or can be requested with the function GETARG (i), 1 <= i <= n. The number of passed arguments is stored in the system variable %NARGS.
options	is an optional field of keywords separated by blanks:
-D=device	defines the format of the metafile created by DISLIN. This parameter will overwrite the keyword in the DISLIN routine METAFL and can have the same values as the parameter in METAFL.
-F=file	defines the file used for data input. This parameter will overwrite the file parameter in the routine DATFIL.
-I=file	replaces the file parameter of the first INCLUDE statement in a DISGCL script file. This option can be used to initialize variables with different values.
-f	means that the extension '.gcl' is not added to the filename.
-o	opens a console window on Window systems.
-v	prints program version and author.

CHAR	an 8-bit integer in the range -128 to 127.
BYTE	an 8-bit integer in the range 0 to 255.
SHORT	an 16-bit integer in the range -32768 to 32767.
INT	an 32-bit integer in the range -2147483648 to 2147483647.
FLOAT	an 32-bit floating point number in the range 1.2E-38 to 3.4E+38 and with 7-digit precision.
DOUBLE	an 64-bit floating point number in the range 2.2E-308 to 1.8E+308 and with 15-digit precision.
COMPLEX	a pair of 32-bit floating point numbers in the range 1.2E-38 to 3.4E+38.
STRING	a sequence of characters. Strings are stored as CHAR arrays terminated with the ASCII value zero.