\section{The SIC Monitor}

\subsection{Basic Features}

\subsubsection{Syntax}

All commands parsed by SIC must have the following syntax:\\
{\tt [LANG$\backslash$]COMM [ARG1 [ARG2 [...]]] [/OPT1 [ARG11 [...]] [/OPT2
  [...]]}

Where {\tt LANG} is the language name, {\tt COMM} the command name, {\tt
  OPT1} and {\tt OPT2} are option names, {\tt ARGs} are the arguments of
command and options, and brackets indicate optional fields.

The language, command and option names can be abbreviated and \sic\ checks
for ambiguities.  Arguments are separated by any number of separators
(Spaces or Tabs).  An option is a word beginning with a Slash. The options,
like the commands, may have arguments.  The syntax analyzer converts to
upper case letters, strips useless separators, translate the symbols (See
\ref{sub:symbols}, expands the command and option names by looking
through its current ``dictionary''.

The language field is optional. If present, it restricts the resolution of
command name abbreviations to all languages of which it is an abbreviation.
Otherwise, all languages are searched for.

The first action of the syntax analyzer is to suppress redundant
separators. This is of course not always wanted (e.g. a figure caption) and
\sic\ offers one way to circumvent this problem: the so-called strings,
which are arguments included between double quotes ({\tt "}). Strings are
not modified by the syntax analyzer, but the outer double quotes will be
ignored when the argument is used. However, strings are not protected
against symbol substitution.

The program calling \sic\ may expect arguments of various types: character
strings, real numbers, integers or logicals. For a specified type, e.g. a
real number, the argument can be either a constant value (e.g. 3.14159), a
variable (e.g. PI), or an expression (e.g. 2*ASIN(-1.0)). Conversion to the
specified type is done automatically if possible at all (See command
{\tt SIC PRECISION} in \ref{sub:sic}).

A ``-'' sign as the last significant character in a command line indicates
that a continuation follows on the next line, e.g.  \index{HELP}
\begin{verbatim}
          SIC> HELP -
          SIC> EDIT
\end{verbatim}
is interpreted as
\begin{verbatim}
          SIC> HELP EDIT
\end{verbatim}

No special procedure is used to cut strings for continuation lines. It is
simply done according to the following example
\begin{verbatim}
          SIC> LABEL "A very long-
          SIC>  string must be cut"
\end{verbatim}
which is interpreted as
\begin{verbatim}
          SIC> LABEL "A very long string must be cut"
\end{verbatim}

Comments may appear at the end of any line. The comment area starts with a
``$!$'' sign; all the following text is ignored. Comments can be used in
conjunction with the continuation mark :
\begin{verbatim}
          SIC> DRAW RELOCATE 13-       !This is an example of comments
          SIC> .45 15.00 /USER         ! and continuation
\end{verbatim}
is interpreted as
\begin{verbatim}
          SIC> DRAW RELOCATE 13.45 15.00 /USER
\end{verbatim}
BUT do not try this one
\begin{verbatim}
          SIC> LABEL "A lon-    ! A long string
          SIC> g caption"       ! with continuation mark
\end{verbatim}
which produces the message
\begin{verbatim}
          E-INTER,  Unbalanced quote count
\end{verbatim}
immediately after the first line as been typed in, because the syntax
analyzer was considering the - and $!$ signs as part of a string.  Comments
may be convenient to self-document complex procedures.

\subsubsection{The Prompt}

The prompt is defined by the calling program. In addition, \sic\ modifies
the prompt aspect according to the execution level. In this example the
calling program is assumed to pass the string {\tt 'GAG'} to \sic.  Then
the following prompts may appear :

\begin{verbatim}
        GAG>     ! Lowest execution level
        GAG_3>   ! Third execution level
        GAG_5:   ! Compile mode for the Loop buffer at level 5
\end{verbatim}

\subsubsection{The on-line HELP}

The \com{HELP} utility of \sic\ is structured at three different levels.
Without an argument, {\tt HELP} gives the list of available help.  Since
\sic\ is a multi-language system, {\tt HELP Language\_Name$\backslash$}
prints one line description of all commands of the named language.  For
example, {\tt HELP SIC$\backslash$} gives a one line description of all the
\sic\ monitor commands.  {\tt HELP Command\_Name} prints more detailed
information on that command.  For some command, the help text is divided in
subtopics which can be accessed by typing {\tt HELP Command\_Name
  Subtopic}.

If you consult a long {\tt HELP} text, you may use the {\tt PAGE} mode. You
will then be prompted for continuation when the screen is full. The page
mode is usually set by default on ``intelligent'' terminals, and you can
switch between {\tt PAGE} and {\tt SCROLL} mode for the help using command
\begin{verbatim}
        SIC> SIC HELP PAGE     or     SIC HELP SCROLL
\end{verbatim}

On-line access to the documentation can be obtained by
\begin{verbatim}
        SIC> SIC HELP CONTENT  or     SIC HELP INDEX
\end{verbatim}
In {\tt CONTENT} mode, {\tt HELP Command} displays the documentation page
indicated for the specified {\tt Command} by the table of content, while in
{\tt INDEX} mode, the first page indicated in the index is displayed.

\subsubsection{The Stack}

The Stack is an internal buffer where commands are automatically placed.
It may be considered as a real time logfile, from which you can retrieve
commands. The stack buffer is organized as a circulating buffer, with a
{\tt "first in - first out"} replacement procedure when the buffer is full,
or when the maximum number of commands is reached. The command number
always increase, even when the buffer fills up.

The command \index{RECALL}
\begin{verbatim}
        RECALL [Arg]
\end{verbatim}
recalls command from the stack for execution. Depending on whether line
editing mode is possible (see keypad line editing), the recalled command
may be edited prior to submission, or not.  If no argument is present, the
last command is recalled. If the argument is a number N, the N-th command
of the stack is recalled. If the argument is a string, the stack is scanned
backwards to find a command beginning by this string.

If line editing is possible, commands may also be retrieved from the stack
using the Up and Down arrows on the terminal keyboard
\textbf{a documenter plus correctement}.

The command \index{EDIT}
\begin{verbatim}
        EDIT
\end{verbatim}
without arguments will dump the stack on a file named {\tt stack.DefExt}
(where {\tt DefExt} is the current default procedure extension), and calls
the default editor to edit this file. It can then be executed as any other
procedure.

\subsubsection{Line Editing Facility}

Line editing is normally available to edit command lines prior to
submission. The following control keys can be used
\begin{verbatim}
  <^A>            Move to beginning of line
  <^B>            Backspace one character (BACKWARD)
  <^F>            Advance one character (FORWARD)
  <^H>            Delete previous character (BACKSPACE)
  <^J>            Delete to beginning of word, or previous word
  <^M>            Submit command line (RETURN key)
  <^N>            Recover Next command
  <^P>            Recover Previous command
  <^U>            Delete to beginning of line
  <DEL>           Delete previous character
\end{verbatim}
These commands are identical to the standard line editing in the Emacs
editor.

\textbf{SG: Is it still valid?} If you are using an ANSII compatible terminal (VT100 series and upwards),
the numeric keypad is also available to perform additional actions
\begin{verbatim}
  <PF4>           Delete to end of line
  <->             Delete to end of word, or next word
  <LF>            Delete to beginning of word, or previous word
  <,>             Delete character
  <DEL>           Delete previous character
  <1>             Move to next word
  <2>             Move to end of line
  <4>             Set advance mode (for WORD moves)
  <5>             Set backup mode (for WORD moves)
  <ENTER>         Submit the command line
  <RETURN>        Same as above
  <Up Arrow>      Retrieve previous command of Stack
  <Down Arrow>    Retrieve next command of Stack
  <Left Arrow>    Backward one character
  <Right Arrow>   Advance one character
\end{verbatim}

For lines longer than the screen width, the display uses a window and
automatically centers it on the current character when the cursor position
reaches one end.

\textbf{SG: Is that still true?} The keypad editing mode can be turned off by the {\tt SIC EDIT
  OFF}\index{SIC!EDIT} command and turned on by the {\tt SIC EDIT ON}
command. Line editing mode affects the error recovery system and the RECALL
command.

\subsubsection{The Log File}

The {\em Log File} is a post-mortem listing of all commands issued and
successfully executed during a working session.  It is kept on leaving
\sic\ (by using {\tt EXIT}).  Some commands like {\tt HELP} are not put
into the {\em Log File}.  Most programs using \sic\ put the {\em Log File}
in the {\tt GAG\_LOG:} area (usually your default directory, but see
``Customizing'') to avoid multiplication of files in a directory tree, and
purge it upon exit keeping the last two or three versions. {\em Log Files}
can be used as the basis of subsequent procedures. If you are short of disk
space, purge and delete yourself the log files.

\subsubsection{Symbols}
\label{sub:symbols}
\sic\ allows the user to define symbols, which are abbreviations of any
character string.  Any command line is first parsed for symbols in the
symbol table.  The command interpretor assumes that the following entities
may be symbols :
\begin{itemize}
\item the first word of command line (e.g. {\tt AA} in command {\tt AA
    /OPTION})
\item any string (without spaces) included between single quotes (e.g.
  {\tt 'AA'}). This syntax may also indicate a character variable (See
  ``Character Variables and Implicit Formatting'').
\end{itemize}
There is no recursive analysis of the line for the symbol translation.
Note that, contrary to character variables, the symbol translation occurs
even within strings, and that case does not matter.

\index{SYMBOL}

Symbols are defined by issuing the following command
\begin{verbatim}
        SIC> SYMBOL TOTO "Whatever you want"
\end{verbatim}
A symbol definition may refer to an other already defined symbol.  Whenever
{\tt 'TOTO'} is found in a command line, it will be replaced by the string
Whatever you want e.g.
\begin{verbatim}
        SIC> LABEL "Units 'TOTO'"
\end{verbatim}
will be interpreted as
\begin{verbatim}
        SIC> LABEL "Units Whatever you want"
\end{verbatim}

The Symbol Table can be listed using command {\tt SYMBOL} without
arguments.  If {\tt SYMBOL} has a symbol name for argument, the translation
of this symbol is given. {\tt DELETE /SYMBOL TOTO} will delete symbol {\tt
  TOTO} from the \index{DELETE!/SYMBOL} current symbol table. Note that
symbols should only include alphanumeric characters.

\subsection{Variables and Expressions}
\label{sub:variables}
Most of the power of \sic\ comes from its ability to handle variables and
perform operations (arithmetic or logical) on them. When used in
combination with the \greg\ program for display, \sic\ variables can be
used to performed efficient data analysis.

\subsubsection{Definitions and Assignments}

\sic\ supports variables and arithmetic or logical expressions evaluation.
Variables can be defined either by the program or by the user.
Program-defined variables may have the Read-Only attribute which prevents
them from being overwritten by the user (see \sic\ PROGRAMMING MANUAL).
Variable names are up to 64 characters long, case insensitive, and must
begin with a letter. A variable can be LOCAL or GLOBAL. GLOBAL variables
are valid at any execution level in \sic . On the opposite, LOCAL variables
are valid only in the procedure where they have been declared, or in any
loop started within this procedure, or in any interactive level generated
from this procedure (by a {\tt PAUSE} or an error).  Variables declared by
a program are always GLOBAL.

Arithmetic and logical expressions are automatically evaluated when used as
arguments to commands. The evaluation is done in single or double precision
arithmetic, according to command \comm{SIC}{PRECISION}. Parentheses are
allowed, but there is a limit on the complexity of arithmetic and logical
expressions. A local variable has precedence over a global variable of the
same name. Local variables are deleted when the creating procedure
terminates.

Variables may be defined using command \com{DEFINE}, and assigned values
using command \com{LET}. \sic\ is a declarative language in which all
variables must be defined before being used. For convenience, command {\tt
  LET} has an option {\tt /NEW}\index{LET!/NEW} which allows declaration of
the assigned variable. Five type of variables are allowed : {\tt REAL,
  INTEGER, LOGICAL, DOUBLE} (for double precision real variables), and {\tt
  CHARACTER}.

Variable values may be typed using the \com{EXAMINE} command, which also
indicates whether the variable is GLOBAL or LOCAL, and in the latter case,
the corresponding procedure level.


\subsubsection{Functions and Operators}
\label{sub:operators}

For arithmetic expressions, the known operators are
\begin{verbatim}
      -         Subtraction
      +         Addition
      *         Multiplication
      / or |    Division (the | sign has been added because the /
                          is the option separator)
      ** or ^   Exponentiation

\end{verbatim}
Known single argument functions are
\begin{verbatim}
      ABS       Absolute value
      ACOS      Arc Cosine
      ASIN      Arc Sinus
      ATAN      Arc Tangent
      COS       Cosine
      COSH      Hyperbolic Cosine
      EXP       Exponential
      INT       Integer Part
      LOG       Natural logarithm
      LOG10     Decimal Logarithm
      NINT      Nearest Integer
      FLOOR     Integer floor
      CEILING   Integer ceiling
      SIN       Sinus
      SINH      Hyperbolic Sinus
      SQRT      Square Root
      TAN       Tangent
      TANH      Hyperbolic Tangent

\end{verbatim}
Known two arguments functions are
\begin{verbatim}
      ATAN2   Arc tangent with two arguments
      MAX     Maximum of two values
      MIN     Minimum of two values
      MOD     Modulo (true modulo, even for negative numbers)
      SIGN    Sign transfer

\end{verbatim}
For logical expressions, the operators are
\begin{verbatim}
      .OR.      .AND.     .NOT.
      .GT.      .GE.      .LT.      .LE.
      .NE.      .EQ.
\end{verbatim}
Note that there must be no blanks in the logical expressions.

The known functions are
\begin{verbatim}
      EXIST   Returns .TRUE. if its argument is a defined variable
      FILE    Returns .TRUE. if its argument is an existing file.
\end{verbatim}
Additional arithmetic functions may be declared by the calling programs.
Two special functions are always declared :
\begin{verbatim}
      NOISE(x)     Gaussian Noise of Sigma X
      RANDOM(x)    Random Number between 0 and X
\end{verbatim}
These additional functions, and their number of arguments, can be listed
using command \comm{EXAMINE}{/FUNCTION}.

\subsubsection{Vector Operations}

\sic\ supports {\em array variables} of up to 7 dimensions. Array
dimensions are specified between brackets (not parentheses) with the comma
as separators. {\tt CHARACTER} and {\tt LOGICAL} variables can also be
arrays. Arithmetic operations always work on arrays on an element by
element basis. Scalar variables are considered like arrays of any size. For
example,
\begin{verbatim}
      DEFINE REAL A[5] B[5]
      LET A = ABS(B)
      LET B = 1.0
\end{verbatim}
assigns to each element of A the absolute value of the corresponding
element of B, and then assigns to each element of B the value 1.0.
Dimensions of arrays must match in arithmetic expressions.

Any subset of an array variable can be referenced in an expression, for
example
\begin{verbatim}
      DEFINE REAL A[5] B[5,10] C[5,10,3]
      LET B[,6] = A
      LET C[,10,1] = B[,3]
\end{verbatim}
Dimensions of the sub-arrays must also match. Transposition is now
supported : e.g. in the precedent example, C[1,,1] could have replaced
C[,10,1]. The indices can be previously defined scalar variables. Leading
commas may be omitted.
\begin{verbatim}
      DEFINE REAL A[5] B[5,10] C[5,10,3]
      LET B[,6] = A
      LET C[,10,1] = B[,3]
\end{verbatim}
It is also possible to specify a range of indexes rather than a single
index.
\begin{verbatim}
      DEFINE REAL A[5] B[3,10] C[4,4,4]
      LET B[,6] = A[2:4]
      LET A[:3] = B[,8]
      LET A[2:5] = C[3,,4]
\end{verbatim}

\subsubsection{Implicit Loops}

It is sometimes convenient to assign to an array values which are functions
of the array indices.  This can be done using ``implicit loops'', such as
\begin{verbatim}
      DEFINE REAL A[10,10]
      LET A[I,J] = EXP(-((I-5)|2)**2-((J-6)|3)**2)
\end{verbatim}
in which I and J have NOT been declared as known variables. I and J are
known as ``implicit variables''.  The preceding expression is equivalent to
the following commands
\begin{verbatim}
      DEFINE REAL A[10,10]
      FOR J 1 TO 10
      FOR I 1 TO 10
      LET A[I,J] = EXP(-((I-5)|2)**2-((J-6)|3)**2)
      NEXT
      NEXT
\end{verbatim}
but it executes thousands of times faster... Mixing of implicit and
declared (or loop) variables is strictly forbidden at present. It can
usually be avoided by using intermediate arrays.

\subsubsection{Conditional Assignment}

Another convenient function is to assign to an array new values only in for
some parts of the array, based on a logical mask or logical expression. The
option {\tt /WHERE}\index{LET!/WHERE} of command {\tt LET} allows such
operations. For example
\begin{verbatim}
      DEFINE REAL A[10,10]
      LET A[I,J] = EXP(-((I-5)|2)**2-((J-6)|3)**2) /WHERE (I+J).LT.10
\end{verbatim}
will set only a part of the A array (note that I and J are ``implicit
variables'').

The preceding expression is equivalent to the following commands
\begin{verbatim}
      DEFINE REAL A[10,10]
      FOR J 1 TO 10
      FOR I 1 TO 10
        IF (I+J).LT.10 THEN
          LET A[I,J] = EXP(-((I-5)|2)**2-((J-6)|3)**2)
        ENDIF
      NEXT
      NEXT
\end{verbatim}
but it executes thousands of times faster...

Conditional assignment can be mixed with implicit loops, as shown above,
but there are some syntax restrictions: please refer to the internal help
for more details.

\subsubsection{Size casting}

Typing the explicit dimensions when declaring a new variable may be
tedious. SIC allows to create arrays of dimensions identical to those of
existing variables through the {\tt /LIKE} option.  \index{LET!/LIKE} For
example, if A is an existing integer variable of dimensions 10,5,30 the
following command
\begin{verbatim}
      DEFINE REAL B C D /LIKE A
\end{verbatim}
is equivalent to
\begin{verbatim}
      DEFINE REAL B[10,5,30] C[10,5,30] D[10,5,30]
\end{verbatim}
and defines three real arrays of dimension [10,5,30]. This feature, called
size casting, is specially convenient to declare arrays that match images
(see below).

\subsubsection{GILDAS Images}

Variables are normally allocated using virtual memory, and hence are lost
once the program terminates. It is possible to allocate variables as disk
files, called {\bf Images}, which are mapped into the virtual memory of the
program, using command
\begin{verbatim}
        DEFINE IMAGE Variable File Keyword
\end{verbatim}
where
\begin{description}
\item{\tt Variable} is the desired variable name. This variable name should
  be at most 3 characters to hold the header variables.
\item{\tt File} is the name of the file holding the image. Default
  extension is {\tt .gdf} (\gildas\ Data Format), but any extension is
  valid.
\item{\tt Keyword} indicates how the file must be used and may be
\begin{description}
\item{\tt READ} use an existing image as Read-Only variable
\item{\tt WRITE} use an existing image as Read-Write variable. The user
  must have Write access to the file.
\item{\tt EXTEND} Allows to extend the last dimension of an existing image.
  The user must have write access to it.
\item{\tt REAL} create a new image of type {\tt REAL}
\item{\tt DOUBLE} create a new image of type {\tt DOUBLE}
\item{\tt INTEGER} create a new image of type {\tt INTEGER}.
\end{description}
\end{description}
For already existing images ({\tt READ, WRITE}), the type and size of
variable are determined by the program. For new images, the size must be
specified in the variable name, and the variable is always declared as
Read-Write. To {\tt EXTEND} image, the new value of the last dimension must
be specified in the variable name. Header variables (see next section) are
defined with the same status (Read or Write) as the image.

{\bf Images} (i.e. files in the \gildas\ data format) are used by most
programs distributed by the Groupe d'Astrophysique. See the \gildas\
(Grenoble Image and Line Data Analysis Software) documentation. {\bf
  Tables} usually refer to images with 2 dimensions, but more generally to
images which do not define a coordinate system.

The \comm{DEFINE}{IMAGE} command has two variants, \comm{DEFINE}{TABLE} and
\comm{DEFINE}{HEADER}. \comm{DEFINE}{TABLE} only defines a single variable
pointing to the image content. On the opposite \comm{DEFINE}{HEADER} defines
only the header variables, as described in next section.

\subsubsection{GILDAS Headers}
\label{sub:headers}

The \comm{DEFINE}{IMAGE} command allows \sic\ to access not only to the
content of an image (the data value), but also to all its associated
parameters; \comm{DEFINE}{HEADER} allows access only to these associated
parameters. The header variables have names derived from the generic name
by adding the special character \% and an extension (such as e.g. {\tt
  NDIM} for the number of dimensions) to the generic header name. For
example, command {\tt DEFINE HEADER VAR file.gdf READ} also creates the
following variables:
\begin{verbatim}
       VAR%GENE       Integer        Length of general section
       VAR%NDIM       Integer        Number of dimensions (ReadOnly)
       VAR%DIM        Integer[7]     Dimensions           (ReadOnly)
       VAR%CONVERT    Double[3,7]    Conversion formulae for the 7 axes:
                                     Reference pixel,
                                     Value at reference pixel,
                                     Increment
       VAR%BLAN       Integer        Length of blanking section
       VAR%BLANK      Real[2]        Blanking and tolerance
       VAR%EXTREMA    Integer        Length of extrema section
       VAR%MAX        Real           Maximum
       VAR%MIN        Real           Minimum
       VAR%MINLOC     Integer[7]     Position of min value
       VAR%MAXLOC     Integer[7]     Position of max value
       VAR%DESC       Integer        Length of units and system section
       VAR%UNIT       Char*12        Image unit
       VAR%UNIT1      Char*12        First axis type
       VAR%UNIT2      Char*12        Second axis type
       VAR%UNIT3      Char*12        Third axis type
       VAR%UNIT4      Char*12        Fourth axis type
       VAR%SYSTEM     Char*12        Coordinate system
       VAR%POSI       Integer        Length of position section
       VAR%SOURCE     Char*12        Source name
       VAR%RA         Double         Right Ascension
       VAR%DEC        Double         Declination
       VAR%LII        Double         Galactic longitude
       VAR%BII        Double         Galactic latitude
       VAR%EQUINOX    Real           Equinox of coordinates
       VAR%PROJ       Integer        Length of projection section
       VAR%PTYPE      Integer        Projection type (code)
       VAR%A0         Double         first coordinate of projection center
       VAR%D0         Double         second coordinate of projection center
       VAR%ANGLE      Double         position angle of projection
       VAR%X_AXIS     Integer        First projected axis
       VAR%Y_AXIS     Integer        Second projected axis
       VAR%SPEC       Integer        Length of spectroscopy section
       VAR%LINE       Char*12        Line name
       VAR%FREQRES    Double         Frequency resolution
       VAR%IMAGFRE    Double         Image Frequency
       VAR%RESTFRE    Double         Rest Frequency
       VAR%VELRES     Real           Velocity resolution
       VAR%VELOFF     Real           Velocity offset
       VAR%F_AXIS     Integer        Frequency/Velocity axis
       VAR%BEAM       Integer        Length of beam section
       VAR%MAJOR      Real           Major axis of beam
       VAR%MINOR      Real           Minor axis of beam
       VAR%PA         Real           Position angle of beam
       VAR%SIGMA      Integer        Noise section length
       VAR%NOISE      Real           Theoretical noise
       VAR%RMS        Real           Actual noise
       VAR%PROPER     Integer        Proper motion section length
       VAR%MU         Real[2]        along RA and DEC, in mas/yr
       VAR%PARALLAX   Real           Parallax in mas
\end{verbatim}
In addition, the following variables are also created when accessing
\gildas\ {\bf UV Tables} through the \comm{DEFINE}{UVTABLE} command:
\begin{verbatim}
       VAR%NCHAN      Integer        Number of channels
       VAR%NVISI      Integer        Number of visibilities
       VAR%NSTOKES    Integer        Number of Stokes parameters
       VAR%NATOM      Integer        Complex visibility size
       VAR%BASEMIN    Real           Minimum baseline
       VAR%BASEMAX    Real           Maximum baseline
\end{verbatim}
{\tt VAR} becomes a dummy variable of type header, which can only be
referenced in a further \comm{DELETE}{/VARIABLE} command. The {\tt
  VAR\%item} variables are ReadOnly or ReadWrite according to the
keyword following the filename, except for the dimension variables
({\tt VAR\%DIM} and {\tt VAR\%NDIM}), which cannot be modified.
{\tt VAR\%READONLY} indicates whether the variable can be modified
or not.

Full headers can be copied to one another, using the command \index{LET}
\begin{verbatim}
    LET A% = B%
\end{verbatim}
which copies the header of image B into that of image A (dimensions
are not modified, however). Thus a full copy of a 4 dimensions
\gildas\ data file can be obtained within \sic\ as follows:
\begin{verbatim}
    DEFINE IMAGE A Oldfile.gdf READ
    DEFINE INTEGER N1 N2 N3 N4
    LET N1 A%DIM[1]
    LET N2 A%DIM[2]
    LET N3 A%DIM[3]
    LET N4 A%DIM[4]
    DEFINE IMAGE B[N1,N2,N3,N4] Newfile.gdf REAL
    LET B A      !  Copy A data into B
    LET B% A%    ! Copy A header into B header
    DELETE /VARIABLE B ! Deletes the SIC variables, but not the file...
\end{verbatim}
A simpler (and more generic) way to declare new images is to use the
size casting provided by the {\tt /LIKE} option:
\begin{verbatim}
    DEFINE IMAGE A Oldfile.gdf READ
    DEFINE IMAGE B Newfile.gdf REAL /LIKE A  ! Define B like A...
    LET B A      !  Copy A data into B
    LET B% A%    !  Copy A header into B header
    DELETE /VARIABLE B ! Deletes the SIC variables, but not the file...
\end{verbatim}

\subsubsection{Structures}
\label{sub:structure}
 \sic\ variables can also be structures, which are related
 ensembles of variables similar to the derived types in Fortran-90.
 The naming conventions follows the Fortran-90, with structure elements
 separated by the \% sign.

 A structure is defined by
\begin{verbatim}
    DEFINE STRUCTURE A
\end{verbatim}
 and any element then by
\begin{verbatim}
    DEFINE REAL A%B
\end{verbatim}
Sub-structures can be defined, too
\begin{verbatim}
    DEFINE STRUCTURE A%C
    DEFINE REAL A%C%E
\end{verbatim}
An entire structure (e.g. A as above) and all its element can be deleted using
\begin{verbatim}
    DELETE /VAR A
\end{verbatim}

Structures can be assigned as a whole by command {\tt LET}. This command
will copy all elements of the same name, and leave the others untouched.
{\tt HEADER}s are actually special structures.


\subsubsection{Character Variables and Implicit Formatting}

In contrast with the Symbols, which are substituted in the command
line before the parsing, variables and expressions are evaluated after
the command line analysis. In general, a real (resp. integer and
logical) argument is considered as a mathematical (logical) expression
and evaluated when read by the program calling \sic{}. The command
line stored in the stack and logfile contains the mathematic
expression, not the current value.

The behaviour for Character variables is slightly different, in the sense
that only items included between single quotes are considered as possible
character variables, if they have not yet been expanded as known symbols of
course. Using character variables in logical expressions is an exception to
this rule because translation should be avoided in this case, see next
chapter.  Contrary to Symbols, Character variables translation does not
occur in strings.

Not only Character variables but also any mathematical and logical
expression may be included between quotes. Mathematical expressions are
evaluated and formatted using the shortest possible format. Logical
expressions are evaluated as YES or NO.  The formatted command string is
substituted to the expression and quotes, and used in the string returned
as character argument to a command.  This feature is known as ``Implicit
Formatting''. In this way, non-character variables and expressions can be
used where a character argument is required. The reverse is not true
however: Implicit Formatting should not be used if a non-character argument
is expected.

Any variable can be typed using the \com{EXAMINE} command which will
display the variable name followed by its current value. More than one
variable may be displayed at the same time using the \com{SAY} command.

Concatenation of variables is easily obtained by mixing explicit strings
(between double-quotes) and implicitely formatted variables.  For example,
is A is character variable of content "I am", the following command
\begin{verbatim}
   LET B "You know "'A'" happy"
\end{verbatim}
attributes to B the content "You know I am happy".

\subsubsection{Initializing variables from external files}

\sic\ allows easy initialization of variable from files in ``foreign''
format (i.e. not \gildas\ images). This can be done with the \com{ACCEPT}
command, which allows reading variables from formatted or unformatted
files. This command is available in 3 major modes
\begin{itemize}
\item{\comm{ACCEPT}{/ARRAY}}\\
  {\tt ACCEPT Var /ARRAY File [/FORMAT String] [/LINE Begin [End]]} \\
  reads in free format or user specified format variable {\tt Var} from
  file {\tt File}, selecting a line range if specified. {\tt Var} may have
  up to 4 dimensions.
\item{\comm{ACCEPT}{/BINARY}}\\
  {\tt ACCEPT Var /BINARY File [Skip]}\\
  reads the binary file {\tt File} to set variable {\tt Var}. {\tt Skip} is
  a number of BYTEs to skip before reading. Note that there is no type
  conversion in this command: the binary content of the file must match the
  type declared for the variable.
\item{\comm{ACCEPT}{/COLUMN}}\\
  {\tt ACCEPT V1 [V2 [...]] /COLUMN File [/FORMAT String] [/LINE Begin [End]]} \\
  reads the formatted file {\tt File} to set one or several 1-dimensional
  variables {\tt V1 V2 \ldots}. Free format is used by default, unless the
  {\tt /FORMAT} option is specified. The special argument {\tt *} can be
  used instead of the variable name to indicate a ``dummy'' variable, which
  is read from the file, but not assigned. This allows to skip a column in
  the input file.
\end{itemize}

\subsection{SIC as a programming language}

The second most important power of the SIC command language is its
programming features. SIC supports command procedures, loops and
conditional execution of statements in procedures.

\subsubsection{Procedures (or Command Files)}

\sic\ has command procedure capabilities.  A procedure is an external
file containing valid commands.  The \sic\ variables PRO\%NARG (number
of arguments) and PRO\%ARG[:] (arguments as an array of character
strings) can be accessed from within the procedure; they describe the
arguments passed to the procedure when it was invoked. The tokens \&1,
\&2, ..., \&8 can also be used in the body of the procedure, its
arguments will be substituted for these tokens.  Substitution occurs
also within the character strings. A procedure is executed by
\index{@}
\begin{verbatim}
        SIC> @ Procedure_Name [P1 ... PN]
\end{verbatim}

Commands are read from the file Procedure\_Name (with a default
extension depending on the calling program or the user) and executed.
P1 is a parameter string to be evaluated from PRO\%ARG[1] or
substituted to the token \&1 during execution.  Up to 32 parameters
may be passed to the procedure.  The commands are echoed to the user's
terminal if the {\tt VERIFY} switch is set {\tt ON}.  Most programs
using \sic\ define a default procedure extension equal to the program
name (such as {\tt .greg .class, etc\ldots}). If not specified, the
default macro extension is {\tt .pro}. It can be listed and changed
using command \comm{SIC}{EXTENSION}.

Procedures (or any text file indeed) can be typed from within \sic\ using
the command \com{TYPE}.
\begin{verbatim}
        SIC> TYPE Procedure_Name
\end{verbatim}
If no argument is given to {\tt TYPE}, the stack buffer is listed.

\subsubsection{Loops}
\index{FOR} \index{NEXT}

\begin{verbatim}
        FOR Variable List
\end{verbatim}
opens a {\tt FOR-NEXT} loop to be executed for values given in the list.

This command may have the following format :
\begin{verbatim}
        FOR I n1 n2 n3 to n4 by n5 n6 to n7
\end{verbatim}
where I is the loop variable name. Loop variables must not be previously
defined, and are undefined when the loop execution is finished. The prompt
changes to {\tt 'SIC\_n: '}, where n is the current \sic\ execution level,
and all subsequent commands until {\tt NEXT} are the body of the loop.  The
loop variable can be used as any other \sic\ variable, e.g. in arithmetic
expressions such as EXP(-(I+3.5)**2). In addition, it can be used in a
formatted way when it is included between quotes, e.g.
in {\tt  NAME.EXT.'I'}. In this case, the substitution occurs also within the
character strings (see ``Implicit Formatting'').  The commands are echoed
to the user's terminal if the {\tt VERIFY} switch is set {\tt ON}.

Up to 127 loop, procedure or {\tt IF} block levels can be nested,
and there is no restriction upon the loop and procedure nesting, e.g.
\begin{verbatim}
          SIC> FOR I List1
          SIC> FOR J List2
          SIC> ..
          SIC> NEXT
          SIC> FOR J List3
          SIC> ...
          SIC> NEXT
          SIC> NEXT
\end{verbatim}
is perfectly valid.

\index{FOR!/WHILE}
\begin{verbatim}
        FOR /WHILE Logical_Expression
\end{verbatim}
This is another possible syntax for {\tt FOR-NEXT} loops. The loop is
executed conditionally provided ``Logical\_Expression'' is {\tt TRUE}.
``Logical\_Expression'' must be any valid logical expression, possibly
including arithmetic sub-expressions in it.

\subsubsection{Structured Programming and Logical Expressions}

\sic\ includes structured logical tests of the form (if-blocks):
\index{IF}\index{ELSE}\index{ELSE IF}\index{ENDIF}
\begin{verbatim}
      IF Logical_Expression [THEN]
        ...
      ELSE IF Logical_Expression [THEN]
        ...
      ELSE
        ...
      ENDIF
\end{verbatim}
or of the form (if-statements):
\begin{verbatim}
      IF Logical_Expression One_Command_Line
\end{verbatim}
The if-block form is similar to FORTRAN with two differences. First,
the {\tt THEN} keyword is optional. Second, {\tt ELSE} and {\tt IF}
must be separated by at least one space or tab in the {\tt ELSE IF}
command.  In addition, provided the restriction on the total number of
loops, procedures and {\tt IF} blocks is met, any nesting between
loops, procedures and {\tt IF} blocks is allowed.

Variables can appear in the logical expressions, and this is one of the
most frequent use for variables. An {\tt IF} block must be complete in a
procedure or loop, otherwise an error occurs.

Logical expressions may include operations on arithmetic, logical or
character variables. In logical expressions, strings (i.e. text included
between double quotes) are recognized as character constants.  Character
variables should not be included between single quotes, since their current
values would be substituted by \sic\ before logical expression analysis.
Arithmetic sub-expressions are allowed.

Assuming {\tt GOOD} is a character variable whose current value is {\tt
  "Let it be"}, and {\tt PI = 3.1415926535897932} (Double precision),
examples of valid logical expressions are :
\begin{verbatim}
        L = ("I am happy".EQ.GOOD) (.FALSE.)

        L = ("Let it be".EQ.GOOD) (.TRUE.)

        L = ("I am happy".EQ."'GOOD'") (.FALSE.)
    evaluated literally since GOOD is not substituted in a string

        L = PI.EQ.ACOS(-1.0) (.TRUE.)

        L = 'PI'.EQ.2*ASIN(1.0) (.FALSE.)
    evaluated as 3.141592653589793.EQ.2*ASIN(1.0)
    because of implicit formatting, one digit being lost in the
    formatting because of binary to decimal conversion.

        L = ("I am happy".NE.GOOD).OR.(PI.EQ.ACOS(-1.0))
\end{verbatim}
But the following expressions are invalid :
\begin{verbatim}
        L = (PI.EQ.GOOD) Variable type mismatch.

        L = ("I am happy".NE.'GOOD')
    Because it is evaluated as ("I am happy".NE.Let it be).
\end{verbatim}

\subsubsection{Execution Level}

Procedures and Loops can be nested.  Hence, \sic\ may operate at different
{\em Levels of Execution}. Commands are provided to activate some level
({\tt @, FOR}), suspend ({\tt PAUSE}), resume ({\tt CONTINUE}) or abort its
execution ({\tt NEXT, QUIT, BREAK, RETURN}).  Errors occuring within a
non-interactive execution level generate a {\tt PAUSE}, which returns
interactive control to the user at a level immediately higher. The prompt
at level I changes to {\tt 'SIC\_I> '} to remind the user what \sic\ is
doing.

It is also possible to interrupt a sequence of commands (procedure or loop)
by pressing {\tt <\^{}C>} at any time. The current command is then normally
completed (unless it traps the {\tt <\^{}C>} by itself), but a {\tt PAUSE}
is generated when the command terminates.

Related commands :
\begin{description}
  \index{BREAK}
\item{BREAK}\\
  Aborts Loop execution without generating an error. The loop is considered
  to have completed successfully, and execution resumes at the command line
  following the NEXT command of the loop.  \index{CONTINUE}
\item{CONTINUE}\\
  resumes Procedure or Loop execution after a \com{PAUSE}, either explicit
  or generated because of an error condition. {\em C is always a non
    ambiguous abbreviation of} {\tt CONTINUE}, unless you redefine it as a
  Symbol.  \index{EXIT}
\item{EXIT}\\
  exit from the program.  \index{NEXT}
\item{NEXT}\\
  The effect of this command depends on the context:
\begin{itemize}
\item If encountered while entering loop commands (during loop
  compilation), it ends the loop definition and activates its execution.
\item If encountered during loop execution, all commands left in the loop
  are skipped and loop execution starts again for next index value. This
  typically occurs when it is specified as error handling ({\tt ON ERROR
    NEXT}), or typed interactively after a {\tt PAUSE} has occured.
\end{itemize}
\index{PAUSE}
\item{PAUSE}\\
  sets a break point in the Loop or a Procedure. \com{PAUSE} returns
  control to the user when executed in any of the non-interactive modes
  (Loop and Procedures).  Any valid command can be executed while in
  interrupt mode.  The normal execution of the interrupted level can be
  resumed by typing \com{CONTINUE}.  {\tt NEXT} and {\tt QUIT} may also be
  valid continuation sequences.  The PAUSE command can be followed by a
  character string argument which is printed before the PAUSE becomes
  effective.  \index{QUIT}
\item{QUIT}\\
  If \com{QUIT} is typed after a {\tt PAUSE} occured in a Procedure or
  Loop, the execution of the interrupted procedure is aborted, and one
  returns to the previous level of execution.  In this case, an error
  condition is transmitted to the previous level to allow the user to take
  the appropriate decision.  \index{RETURN}
\item{RETURN}\\
  Terminates procedure execution, and returns to the previous level of
  execution. An implicit {\tt RETURN} is always executed at the end of the
  command file. Command {\tt RETURN BASE}\index{RETURN!BASE} returns to the
  normal interactive level (level 0). Command {\tt RETURN ERROR}
  \index{RETURN!ERROR} returns to the previous level of execution, but also
  transmit an error status to this level.

\end{description}

\subsubsection{Error Recovery}
\index{ON ERROR}

\sic\ has a powerful error recovery system. Every command returns to the
\sic\ monitor a status to indicate if any error occured. If so, by default
\sic\ attempts to make a {\tt PAUSE}. In an interactive session, there is a
(presumably intelligent) user to decide what to do, and who can hopefully
correct the error (a typing mistake for example) and then type {\tt
  CONTINUE} to proceed. In a non-interactive session (Batch or command
procedure), no such intelligent decision is possible and the {\tt PAUSE}
causes an Abort of the program.

If line edition is possible, the command which caused the error is
automatically displayed for correction by the user.
%The prompt is put in inverse video to indicate that edition is going on.
The corrected line will be submitted whenever {\tt <RETURN>} or {\tt <ENTER>} keys are
pressed.

It is possible to override this default behaviour by command
\begin{verbatim}
        ON ERROR [Other command]
\end{verbatim}
After this command has been issued, any error will attempt to execute the
{\tt "Other command"}. If this command happens to fail, \sic\ will try to
make a {\tt PAUSE}. This command can be any command of the program,
including {\tt @, CONTINUE, EXIT, NEXT}. They will behave exactly has
usual, except command {\tt QUIT}.

In interactive mode, the \com{QUIT} command is usually typed to abort an
erroneous procedure. In this case, it decreases the execution level by 2,
and transmit an error to this new level to signal an abnormal end of some
procedure. In error recovery mode, {\tt QUIT} directly transmits the error to the
previous level. It is in fact translated into {\tt RETURN ERROR}.

Judicious use of the {\tt ON ERROR} command may enable you to make batch
jobs very conveniently. In particular, think of the behaviour of {\tt ON
  ERROR NEXT} and {\tt ON ERROR BREAK} when using loops, and {\tt ON ERROR
  RETURN} when using procedures.

The {\tt ON ERROR} command is a {\em local} command: that means it is only valid
within the procedure which declared it (and loops executed within this
procedure). However, if a {\tt PAUSE} occured from a procedure (or loop), an
interactive execution of the {\tt ON ERROR} command will reset the error
processing behaviour of the interrupted procedure.

\subsection{The {\bf GUI} (``{\bf G}raphics-{\bf U}ser-{\bf I}nterface'') Mode}
\index{GUI Mode}

\sic\ provides facilities (called GUI
mode) to create documented input windows (``widgets'') by which the user can modify
variables and execute pre-defined commands.

\sic\ can create 3 types of widgets:
\begin{itemize}
\item Detached menus\\
  \index{PANEL!/DETACH} which are menu bars created by the {\tt
    GUI$\backslash$PANEL /DETACH} command. These menus have no associated
  parameters, but run in parallel with the main program.  Pre-defined
  commands are activated by pressing the various buttons.
\item Main panel window\\
  \index{Main panel window} which is created by the
  \com{GUI$\backslash$PANEL} command. The user can modify variables using
  widgets, and execute one or several actions by pressing the appropriate
  buttons. The variables are actually modified only when a button is
  pressed.
\item Sub-panels\\
  \index{Sub-panels} which are created by the
  \com{GUI$\backslash$BUTTON} command. Such windows are associated with a specific
  command, and are hidden by default. They are typically used to hold
  variables which are seldom modified by the user. The variables defined in
  these windows and in the main window are modified when the {\tt GO}
  button is pressed.
\end{itemize}
User input with this system is fairly intuitive. Help is available by
clicking on the help button(s) or on the prompt area for each variable.

The following description rather concerns advanced users who want to create
their own window interfaces.

\subsubsection{Detached menus}

Detached menus are created using the \comm{GUI$\backslash$PANEL}{/DETACH}
command. Once created, buttons and pulldown menus can be defined within the
detached menu using respectively the \com{GUI$\backslash$BUTTON} and
\com{GUI$\backslash$MENU} commands respectively.  There are no associated
variables to the detached menus. Help is available through a Help button.
The menu is mapped when the \com{GUI$\backslash$GO} command is typed.

The following procedure illustrates how to create a detach menu; it creates
a menu bar with 3 pulldown menus and a help button.
\begin{verbatim}
!
GUI\PANEL "GRAPHIC X-Window interface" PR:GRAPHIC_SIC.HLP /DETACH
!
GUI\MENU  "SIC"
GUI\BUTTON "SIC\PAUSE" PAUSE
GUI\BUTTON "SIC\CONTINUE" CONTINUE
GUI\BUTTON "SIC\QUIT" QUIT
GUI\BUTTON "SIC\NEXT" NEXT
GUI\BUTTON "SIC\BREAK" BREAK
GUI\BUTTON "SIC\EXIT" "Exit"
!
GUI\MENU "Graphic"
GUI\BUTTON "DEVICE IMAGE WHITE"  DEVICE
GUI\BUTTON "CLEAR PLOT"    CLEAR
GUI\BUTTON "ZOOM"          ZOOM
GUI\BUTTON "HARDCOPY /PRINT" HARDCOPY
GUI\MENU /CLOSE
!
GUI\MENU "Program(s)"
GUI\BUTTON "@ PR:X_WHOLE.GRAPHIC"    "Interfero"
GUI\BUTTON "@ PR:X_DISPLAY.GRAPHIC"  "Display"
!
GUI\GO
\end{verbatim}

Several detached menus can be activated at once.

\subsubsection{Assigning variables in ``Window'' mode}

When the ``Main panel window'' has been created, the LET command behaves in
a different way when any of the following options is set: {\tt /PROMPT,
  /CHOICE, /INDEX, /RANGE, /FILE}

Rather than taking the variable value from the keyboard-typed command line,
the LET command has no immediate action, but defines a widget in the ``Main
panel window'' (or ``sub-panels''). This widget will allow the user to
define the variable value using the windowing system. 5 types of widgets
are available:
\begin{itemize}
\item Text widget\\
  \index{LET!/PROMPT} This is the default widget created when option {\tt
    /PROMPT} is present.  The content of the text widget will be used to
  set the variable.
\item Slider widget\\
  \index{LET!/RANGE} This widget is activated when option {\tt /RANGE} is
  present. The widget consists both in a numeric area and a slider limited
  by the given range, and can be used to set a real or integer variable.
\item Choice widget\\
  \index{LET!/CHOICE} This widget is activated when option {\tt /CHOICE} is
  present. The widget consists in a text widget and a pulldown menu
  containing all specified choices.  The user can select its choice with
  this menu. If the last choice is a ``*'', any other text can also be
  entered.
\item Index widget\\
  \index{LET!/INDEX} This widget is activated when option {\tt /INDEX} is
  present. This widget is similar to the Choice widget, but the returned
  value is an integer corresponding to the sequence number of the selected
  choice.
\item File widget\\
  \index{LET!/FILE} This widget is activated when option {\tt /FILE} is
  present. The widget consists in a text widget and a file selection widget
  with the specified file filter.
\end{itemize}
The ``Main panel window'' is actually created with all defined widgets when
command \com{GUI$\backslash$GO} is typed.

\subsubsection{Actions and Buttons in ``Window'' mode}

The ``Main panel window'' is created when command \com{GUI$\backslash$GO}
is typed.  Four buttons are defined by default in this window:
\begin{itemize}
\item the OK button,\\
  which sets all variables defined in the main {\em and sub-panel} windows.
  This button also executes the command passed as argument to the {\tt
    GUI$\backslash$GO} command (if specified).
\item the UPDATE button,\\
  which sets all variables defined in the main {\em and sub-panel} windows,
  without executing the (optional) command passed as argument to the {\tt
    GUI$\backslash$GO} command.
\item the ABORT button.\\
  Variables are not modified, and an error is
  sent to the main program.\\
\item the HELP button. \\
  This button displays the help file specified in the
  \com{GUI$\backslash$PANEL} command.
\end{itemize}
Additional buttons can also be added to the ``main panel window'' using the
\com{GUI$\backslash$BUTTON} command. Two types of buttons exist
\begin{itemize}
\item Buttons with no associated parameters. These buttons appear just
  after the 3 main buttons.
\item Buttons with optional parameters. These buttons appear sequentially
  with the variables, and have an associated parameter or ``{\em
    optional}'' window. When such a button is defined, all subsequent {\em
    LET} commands create a widget in a ``sub-panel'' window. This window is by
  default hidden, but can be unveiled by the user.
\end{itemize}
The ``sub-panel'' windows provide a way to hide some non-essential
parameters, and/or to create a ``main window'' with a control panel
defining many actions, each action having its own input window and separate
help.

\subsubsection{Help file structure}

Command \com{GUI$\backslash$PANEL} allows to associate an help file to the
main window or detached menus, and command \com{GUI$\backslash$BUTTON} does
the same for optional windows.

The {\tt HELP} files format should be
\begin{verbatim}
      1 Description
          General help for the window or menu
      2 NAME1
          help for variable NAME1
      2 NAME2
          help for variable NAME2
      1 ENDOFHELP
\end{verbatim}
where 1 and 2 are in the first column of the text file, and followed by a
single space.

Clicking on the HELP button will display the complete help file in a
scrolled window. Clicking in the prompt area of an input variable will
display the associated variable name and the help for this variable (if it
exists).

\subsection{Interacting with the Operating System}

Since \sic\  was designed to be portable on various operating systems
(Unix, Mac-OS, MS-Windows, and in the past the defunct VMS), interaction with the operating
system is normally kept to a minimum.

However, many operations eventually deal with files handled by the
operating system. To avoid platform dependencies, SIC allows some basic
file operations through the \com{SIC} command.

When control is desired at the operating system level, the command
\com{SYSTEM} can be used to access it without loosing the SIC context.  For
user convenience, SIC also accepts the short-cut
\begin{verbatim}
        $ operating_system command
\end{verbatim}
instead of the more conventional SIC-like syntax
\begin{verbatim}
        SYSTEM "operating_system command"
\end{verbatim} %$

\subsubsection{File Operations}
\label{sub:file}
Operations on the file system can be done directly within \sic ,
using the \com{SIC} command.

\begin{description}
\item{\tt SIC> SIC DIRECTORY [NewDir]}\index{SIC!DIRECTORY}\\
  to control the working directory.
\item{\tt SIC> SIC MKDIR NewDir}\index{SIC!MKDIR}\\
  to create a new directory.
\item{\tt SIC> SIC$\backslash$SIC APPEND FileIn FileOut}\\
  \index{SIC!APPEND} Appends file {\tt FileIn} to {\tt FileOut}.
\item{\tt SIC> SIC$\backslash$SIC COPY FileIn FileOut}\\
  \index{SIC!COPY} Copies file {\tt FileIn} to {\tt FileOut}.
\item{\tt SIC> SIC$\backslash$SIC DELETE File}\\
  \index{SIC!DELETE} Deletes file named {\tt File}. Caution: no
  confirmation is required.
\item{\tt SIC> SIC$\backslash$SIC RENAME FileOld FileNew}\\
  \index{SIC!RENAME} Renames file {\tt FileOld} to {\tt FileNew}.
  Both files should reside on the same disk. To move files across
  different disks, use {\tt SIC COPY} and {\tt SIC DELETE}.
\item{\tt SIC> SIC$\backslash$SIC FIND FileFilter}\\
  \index{SIC!FIND} search for files with names matching the specified
  filter, and return the result in a structure named {\tt dir\%}.
  {\tt dir\%nfiles} is the number of files found, and {\tt dir\%files[1:dir\%nfiles]}
  their names. See the internal help for details.
\end{description}

The file operations through the SIC command should be used preferentially
to operations through the {\tt SYSTEM} command for portability, specially
in command procedures.

\subsubsection{SYSTEM Command: Unix-like operating system}
{\tt SYSTEM ["Command"]}

Without argument, the \com{SYSTEM} command will create a subshell, using
the user's default shell (sh, csh, ksh, etc\ldots). Control will return to
the calling program once the subshell terminates (i.e.  using the 'exit' or
'bye' or 'logout' command).

With an argument, the {\tt SYSTEM} command will execute the corresponding
Unix command in a subshell.

Note that because subshells are used, you cannot change environment
variables in this way. In particular, to change your working directory use
the \comm{SIC}{DIRECTORY} command.

\subsection{Customizing}

\subsubsection{Logical Names}

All programs based on \sic\ read in files specifying {\em Logical names}
which are used when \sic must refer to external files (such as procedure or
images). {\em Logical names} are similar in syntax and functions to VMS
logical names. Two files define general logical names required for \sic\
based programs to work properly (where to find help files for example) and
site-specific features (such as printer name, scratch space, etc...).

On UNIX and Mac-OS systems, users can specify there own logical names in
the file
\begin{verbatim}
   $HOME/.gag.dico
\end{verbatim}
On MS-Windows systems, ``personal'' logical names should be set in the file
\begin{verbatim}
   $GILDAS\dico.lcl
\end{verbatim}
where {\tt \$GILDAS} is the top directory of the Gildas software as defined
at installation (normally {\tt
  $\backslash$Program\_file$\backslash$Iram$\backslash$Gildas} see in the
{\tt autoexec.bat} file on Windows-95).

% On VMS systems, standard VMS logical names are used.

Logical names can also be added or modified at run time using the
\comm{SIC}{LOGICAL} command.

\subsubsection{User Defined Commands}

\sic\ allows the user to define new command, by means of the
\comm{DEFINE}{COMMAND} command. The syntax is the following:
\begin{verbatim}
    DEFINE COMMAND Newcom "Old Command with arguments" [Help_File]
\end{verbatim}
where {\tt NEWCOM} is the name of the new command and {\tt HELP\_FILE} is
an optional text file used to provide help about the command.  Because {\tt
  DEFINE COMMAND} does not provide any specific syntax to specify the use
of the new command arguments, it is in practice used essentially to allow
documented access to procedures, as for example in
\begin{verbatim}
    DEFINE COMMAND INPUT "@ gag_pro:p_input.greg" gag_pro:input_greg.hlp
\end{verbatim}

\subsubsection{Initialization File}

Although this is not a default feature of \sic, many programs using \sic\
call a initialization macro at run time to define symbols, execute startup
commands and so on. This file is typically named
\begin{verbatim}
        GAG_INIT:INIT.DefExt
\end{verbatim}
where {\tt DefExt} is the default macro extension used by the program, and
is usually the program name. Consult the specific programs documentation.
{\tt GAG\_INIT} is a {\em logical name} that normally points to your login
directory, or (by default) on \$HOME/.gag/init/ on Unix-like systems.

\subsubsection{The SIC Command}
\label{sub:sic}

The \com{SIC} command controls several internal parameters of the \sic\
monitor. It has several categories of actions
\begin{description}
\item File system related operations, described in Sect.\ref{sub:file}
{\tt APPEND COPY DELETE DIRECTORY FIND MKDIR MODIFIED PARSE RENAME}
\item Procedure related operations:
{\tt EXPAND EXTENSION MACRO OUTPUT SAVE VERIFY WHICH}
\item Customization
{\tt EDIT HELP INTEGER LOGICAL MESSAGE PRECISION SYSTEM TIMER WINDOW}
\item Command interpretation
{\tt Language$\backslash$ PRIORITY SYNTAX}
\item Miscellaneous actions
{\tt BEEP CPU DATE DEBUG DELAY FLUSH LOCK RANDOM\_SEED USER WAIT}
\end{description}

The {\tt SIC} command without arguments produces a summary of the internal
\sic\ status, and (when that makes sense) with a single argument it shows the status of that
argument. Please refer to the internal HELP for details.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "sic"
%%% End:
