
\subsection{Introduction}

This section concerns the programmer who wants to use \sic\ as
the monitor of a simple or complex, evolutive, self-documented 
interactive program.
It assumes that the reader is already familiar with all capabilities of
\sic , so that he should be able to design a program (or better a system)
around the \sic\ monitor.
It is in fact essentially a ``CookBook'' giving 
a list of recipes to build a program using \sic , or interface \sic\ with 
a preexisting ensemble of routines. Following these recipes should 
result in a complete success, that is, a program fulfilling the
following requirements:
\begin{itemize}
\item Works in interactive or batch, reading commands on the logical
unit 5 (Read Mode)
\item Can be called as a subroutine to execute a single command
(Execute Mode). In case of error or if a {\tt PAUSE} is encountered, the 
system switches to Read Mode for interactive error recovery or to
read commands after the {\tt PAUSE}.
\item Is completed by a library version
\item The library version can be used to make another language
around it
\item Can be installed as shareable image under most operating
systems (VAX/VMS, HP-UX, etc...).
\end{itemize}
The section 4.2 describes the command vocabulary structure, and the
initialization sequence of \sic . Section 4.3 gives the archetype of the 
structure of a program using \sic\ as its monitor. Section 4.4 indicates 
how to write the corresponding {\tt HELP} files. 
Section 4.5 describes how to retrieve arguments from a \sic\
command line. Section 4.6 indicates how to 
complete the program so that it can also be a library of routines.
Finally, Section 4.7 indicates how to use \sic\ variables, and
Section 4.8 give all entry points of the \sic\ monitor.

\subsection{Initializing SIC: The Command Language Structure}

\sic\ is a multi-language interpretor. Each language must be initialized 
by means of an appropriate call to the routine SIC\_LOAD. This routine 
has the following calling list:
\index{ROUTINES!SIC\_LOAD}
\begin{verbatim}
          SIC_LOAD(LANG,HELP,MCOM,VOCAB,VERSION)
\end{verbatim}
{\tt LANG} is a Character constant (less than 12 characters) which gives 
the name of the language. {\tt LANG} need not be distinct from the command 
names, and it must not include the character $\backslash$ which will appear 
in the internal {\tt HELP} of \sic\.
{\tt MCOM} is the number of commands and options appearing in the language
vocabulary {\tt VOCAB.} All commands in a \sic\ language are 
{\tt CHARACTER*12} constants in
which the first character is a reserved code. Lower case characters 
are NOT allowed, but the special character {\tt "\_"} may appear.
All other special characters have (or may have in the future) some specific 
meaning in \sic\. The following is
the {\tt DATA} initialization statement of \sic\ itself given as an example of
language. 
\begin{verbatim}

        CHARACTER*12 VOCAB(MVOCAB)
        INTEGER SIC_COMMANDS,USER_COMMANDS
        PARAMETER (SIC_COMMANDS=34)
        PARAMETER (USER_COMMANDS=MVOCAB-SIC_COMMANDS)
        DATA VOCAB/
     +  ' BREAK',       ' CONTINUE',    '$DCL',         '/PROCESS',
     +  ' DEFINE',      '/GLOBAL',      ' DELETE',      '/SYMBOL',
     +  '/VARIABLE',    '#EDIT',        ' ELSE',        ' ENDIF',
     +  ' EXAMINE',     '/GLOBAL',      '#EXIT',        ' FOR',
     +  '/WHILE',       '*HELP',        ' IF',          ' LET',
     +  '/NEW',         '/PROMPT',      ' NEXT',        ' ON',
     +  ' PAUSE',       '#QUIT',        ' RETURN',
     +  ' SAY',         ' SIC',         '$SYMBOL',      '/INQUIRE',
     +  '*TYPE',        ' @',           USER_COMMANDS*' '/

\end{verbatim}
The first character code is interpreted as follow
\begin{description}
\item{\tt <space>} Usual command
\item{\tt /} Option of the preceding command
\item{\tt \#} Command forbidden in the stack and in procedures. Commands
of this type are still written in the Log\_File.
\item{\tt \$} Special command which must not be inserted automatically
in the stack. Commands of this type are written in the
Log\_File
\item{\tt *} Purely informative command, which is only useful in an
interactive session. Commands of this type are not 
written in the Log\_File and not inserted in the Stack.
\end{description}

The {\tt *} code can also be used for complex commands using
alphanumeric keywords that you wish to expand yourself 
before saving them in the Log\_File and the Stack, or
for commands that may require to output several records
(See {\tt SIC\_INSERT,} {\tt SIC\_LOG} and {\tt SIC\_LIRE).} The \greg\
command {\tt DRAW} is an example of this.

The programmer should be careful about deciding what attribute to give to 
any command. All the options referring to a command must immediately 
follow it. At initialization time, \sic\ recognizes the options and set 
up a table of pointers connecting the options to their respective 
commands. A failure to respect the adequate order results in a very 
strange vocabulary.

Finally, {\tt VERSION} is a character string which must contain the version 
number, and may contain the date of last modification, the name of the
programmer,... The following example is recommended for optimum 
presentation (respect the alignment of the date for different 
languages):
\begin{verbatim}
          VERSION='1.0   21-APR-1984   Programmer Name'
\end{verbatim}

In addition to setting the vocabulary, the programmer must decide 
the program prompt, the log file and the Stack usage. This is 
entirely optional because \sic\ provides default setups, and it is
done using routine 
\index{ROUTINES!SIC\_OPT}
\begin{verbatim}
          SIC_OPT (PROMPT,LOGFILE,MEMORY)
\end{verbatim}
where {\tt PROMPT} is a character string (less than 8 characters)
defining the prompt (\sic\ adds automatically the caret $>$ at end of
prompt), {\tt LOGFILE} is a character string defining the Log\_File
for the session and {\tt MEMORY} is a logical flag defining the Stack
usage. There two modes for Stack usage: the first mode defines the
Stack as an internal procedure which is entirely at the disposition of
the user {\tt (MEMORY=.FALSE.),} the second mode defines the stack as
an internal Log\_File, in which almost all commands (with the
restriction in the command code) typed at the top level in Read Mode
are automatically written to the Stack {\tt (MEMORY=.TRUE.}). This
mode provides a playback capability for interactive sessions. Modes
can be commuted at run time using \sic\ command \comm{SIC}{MEMORY}.

Default values are {\tt 'SIC', 'LOG'} and {\tt .TRUE.} respectively.
Hence, if you use the defaults, the Log\_File can also be defined by
an assignation to logical name {\tt LOG}.  The call to {\tt SIC\_OPT}
is completely effective if placed before any call to {\tt SIC\_LOAD}.
Otherwise, only the prompt will be changed.

\subsection{The Program Structure}

In this section a complete example is described. The language name is 
set to {\tt USER}, and it is highly recommended to use the same normalization 
conventions for the subroutine names. 
The example takes advantage of the multi-language capabilities 
of the \sic\ monitor by making also the \greg\ system available in
addition to the user's commands. The extra code involved is marked
by the flag {\tt !!GREG!!} and can be removed without affecting the 
user commands. 

The list of routines described here is, in current order :
\begin{verbatim}

        USER            The main program
        LOAD_USER       The initialization routine (#)
        EXEC_USER       To enter Execute Mode. Execute a single 
                        SIC/USER valid command (may be a call to a
                        procedure) and returns (#). 
                        Switches to Read Mode on an error condition
                        (Interactive session only) or if a PAUSE
                        is encountered. Switches back to Execute Mode
                        with CONTINUE or EXIT.
        PLAY_USER       To enter Read Mode with a SIC/USER valid
                        command passed as the first thing to do (#)
        ENTER_USER      To enter Read Mode (#). Reads commands on the
                        logical unit 5. Error recovery is provided for
                        interactive sessions only.
        RUN_USER        Dispatching program to execute the user commands
        COM1            Example of interface between a "simple" 
                        Fortran subroutine and a SIC command.
        US_EXEC         Interface routine for the Library Version
        US_ERROR        idem.

(#)     The inclusion of the extra code flagged as !!GREG!! gives
also access to the command of GREG in the three routines EXEC_USER
PLAY_USER and ENTER_USER.

\end{verbatim}
In addition, the ``true'' library mode is accessible by calling {\tt
US\_EXEC}, which is described completely in Section 4.6. This is a
complete example which really contains all the relevant structure. The
rules for building conventional names are quite obvious.

\begin{verbatim}

* (Source program available in VMS GAG_UTIL:SICUSER.FOR, 
*  and UNIX $GAG_REF/help/sic/sicuser.f)
      PROGRAM USER
      INTEGER ICODE,LENC,L,NL,SIC_PURGE
      CHARACTER*80 FILE,COMMAND,CHAIN,NAME*12
      CHARACTER BACKSLASH*1
      LOGICAL EXIST
*
* Build the names of the log file.
      NAME = 'USER'
      CALL SIC_PARSEF (NAME,FILE,'GAG_LOG:','.LOG')
* Purge older versions of the log file
      ICODE = SIC_PURGE (FILE,1)
      IF (MOD(ICODE,2).EQ.0) CALL SYSEXI(ICODE)
*
* Initialize the command monitor with a nice Prompt, and stack capability
      NAME = 'USER'
      CALL SIC_OPT(NAME,FILE,.TRUE.)
* Then load all languages
      CALL LOAD_USER
* Demonstration of multi-language capabilities
      CALL LOAD_GREG('LIBRARY')          !!GREG!!
* Define a default macro extension
      CHAIN = 'SIC'//BACKSLASH//'SIC EXTENSION .USER'
* Execute the "login" macro
      NAME = 'INIT'
      CALL SIC_PARSEF (NAME,FILE,'GAG_INIT:','.USER')
      L = LENC(FILE)
      INQUIRE (FILE=FILE(1:L),EXIST=EXIST)
      IF (EXIST) THEN
         CHAIN = '@ ``!'//FILE(1:L)//''''
         CALL EXEC_USER (CHAIN)
      ENDIF
* Activate the monitor 
      IF (NL.NE.0) THEN
* First executing the foreign argument if available
         CALL PLAY_USER(COMMAND(1:NL))
      ELSE
* Or not
         CALL ENTER_USER
      ENDIF
      END



      SUBROUTINE LOAD_USER
      INTEGER MCOM
      PARAMETER (MCOM=3)
      CHARACTER*12 VOCAB(MCOM)
      DATA VOCAB / ' COM1' , '/GAG' , ' COM2' /
      CALL SIC_LOAD('USER','GAG_HELP:SICUSER.HLP',MCOM,VOCAB,
     $    '4.0    24-AUG-1984')
      END

\end{verbatim}
Two types 
of complete calls to the {\tt SIC/USER} system are demonstrated. 
\index{ROUTINES!SIC\_RUN}
\index{EXAMPLE!EXEC\_USER}
\index{EXAMPLE!PLAY\_USER}
\index{EXAMPLE!ENTER\_USER}
\begin{verbatim}

      SUBROUTINE EXEC_USER(BUFFER)
      LOGICAL ERROR
      CHARACTER*(*) BUFFER
      CHARACTER LINE*256, COMM*12, LANG*12
      INTEGER ICODE,OCODE
*
      LINE = BUFFER
      ICODE = -1
      GOTO 10
*
      ENTRY PLAY_USER(BUFFER)
      LINE = BUFFER
      ICODE = 2
      GOTO 10
*
      ENTRY ENTER_USER
      ICODE = 1
      GOTO 10
*
* Call the monitor again after completion of every user command.
10    CALL SIC_RUN (LINE,LANG,COMM,ERROR,ICODE,OCODE)
      IF (OCODE.EQ.0) THEN
         IF (LANG.EQ.'USER') THEN
            CALL RUN_USER (LINE,COMM,ERROR)
         ELSEIF (LANG.EQ.'GREG1') THEN !!GREG!! 
            CALL RUN_GREG1 (LINE,COMM,ERROR) !!GREG!!
         ELSEIF (LANG.EQ.'GREG2') THEN !!GREG!!
            CALL RUN_GREG2 (LINE,COMM,ERROR) !!GREG!!
         ELSEIF (LANG.EQ.'GTVL') THEN !!GREG!!
            CALL RUN_GTVL  (LINE,COMM,ERROR) !!GREG!!
            IF (COMM.EQ.'CLEAR') CALL GRESET !!GREG!!
         ELSE
            WRITE(6,*) 'Unrecognized Language ',LANG
            ERROR = .TRUE.
         ENDIF
      ELSEIF (OCODE.EQ.-1) THEN
* Must return immediately from the Execute Mode, 
         RETURN 
      ELSEIF (OCODE.EQ.1) THEN
* Any other code may be added before returning to the main program
         RETURN
      ENDIF
      ICODE = 0
      GOTO 10
      END

\end{verbatim}
In the Execute Mode, all \sic\ capabilities are enabled. A more 
restrictive Library Mode, in which only the command line 
interpretor of \sic\ is used will be shown in Section 4.6.2.
\index{EXAMPLE!RUN\_USER}
\begin{verbatim}

      SUBROUTINE RUN_USER(LINE,COMM,ERROR)
      CHARACTER*(*) LINE,COMM
      LOGICAL ERROR
*
* Call appropriate subroutine according to COMM
      IF (COMM.EQ.'COM1') THEN
         CALL COM1(LINE,ERROR)
      ELSEIF (COMM.EQ.'COM2') THEN
         WRITE (6,*) 'Command COM2 activated'
*        CALL COM2(LINE,ERROR)
      ENDIF
      END


      SUBROUTINE COM1(LINE,ERROR)
      CHARACTER*(*) LINE
      LOGICAL ERROR
      LOGICAL SIC_PRESENT
      INTEGER IARG1_OPT1
      REAL ARG1
*
* Test presence of option 1, and if so
*       Decode Argument 1 of this option with a default value
      IF (SIC_PRESENT(1,0)) THEN
          IARG1_OPT1 = 10
          CALL SIC_I4 (LINE,1,1,IARG1_OPT1,.FALSE.,ERROR)
          IF (ERROR) RETURN
          WRITE (6,*) 'Option 1 Set With Argument',IARG1_OPT1
      ENDIF
*
* Retrieves and decode first argument of the command 
      CALL SIC_R4 (LINE,0,1,ARG1,.TRUE.,ERROR)
      IF (ERROR) RETURN
      WRITE (6,*) 'Command COM1 activated. ARG1',ARG1
* End of interface analysis, call a standard FORTRAN routine with 
* all parameters now defined
*     CALL SUB1(ARG1,ARG2,...,IARG1,...,ERROR)
      RETURN
      END

\end{verbatim}
As in this example, it is HIGHLY RECOMMENDED to pass the command 
buffer {\tt LINE} by argument and NOT IN A COMMON. This will allow later an 
easy implementation of a multi-language program if necessary, and the 
possibility of sharing languages with other users. Use of 
commons may break these possibilities. It is also recommended to have an 
``interface'' routine for each command which takes all the decoding 
functions. However, for very simple commands, this may not be necessary 
and the interface may be in the {\tt RUN\_USER} routine.

\subsection{The Help File}

The {\tt HELP} files are simpled text files with two levels of help.
The list of help topics in the library should be identical to the list
of commands of the program. In addition, a specific topic named {\tt
LANGUAGE} should include a one line description of all commands, with
a subtopic named {\tt NEWS} which describe the latest news on the
specific language.

The {\tt HELP} files format is the following
\begin{verbatim}

      1 TOPIC
          help for this topic
      2 SUBTOPIC
          help for a subtopic of the previous topic
      1 OTHER_TOPIC
          text for other_topic
      1 ENDOFHELP

\end{verbatim}
where 1 and 2 are in the first column of the text file, and followed by a
single space. This format is easier to modify as it is a simple text file,
but much slower to access because it is sequential. The {\tt 1 ENDOFHELP}
(with no trailing characters) sequence indicates the end of the help file.

The help file name should be assigned to the logical name specified
in the {\tt SIC\_LOAD} call, or given explicitly.

\subsection{Retrieving Arguments}

To properly interface your program, you must know how to retrieve an
argument from the command buffer processed by \sic\. In standard \sic\ offers
for each command up to 9 options, and for each option (or command) up to
98 arguments, the total number of arguments and options in a command
line being limited to 99.
The position of argument number {\tt IARG} of option number {\tt IOPT}
of the current command is kept in \sic\ by means of internal pointers,
By convention, argument number 0 refers to the option (or command) 
itself, and option number 0 to the command itself. 
Four standard routines are provided to decode the following
type of arguments. All these routines do not modify the value of the 
argument if it is missing in the command buffer. They may return an error
condition and output an error message if requested in this case.
\index{ROUTINES!SIC\_CH}
\index{ROUTINES!SIC\_L4}
\index{ROUTINES!SIC\_I4}
\index{ROUTINES!SIC\_R4}
\index{ROUTINES!SIC\_R8}
\begin{verbatim}

          Argument Type   Routine Name
          Integer*4         SIC_I4
          Real*4            SIC_R4
          Real*8            SIC_R8
          Logical*4         SIC_L4
          Character         SIC_CH
\end{verbatim}
The first four routines routines have the following calling list
\begin{verbatim}
          CALL SIC_name (LINE,IOPT,IARG,Arg,PRESENT,ERROR)
in which
          LINE        The command buffer
          IOPT        The option number (0=command)
          IARG        The argument number (0=command or option)
          Arg         The argument to be retrieved
          PRESENT     A flag indicating whether an error must occur if
                      the argument is not present in the command line
          ERROR       An error flag set in case of decoding errors,
                      or for missing argument when PRESENT is set.

\end{verbatim}
{\tt SIC\_CH} is slightly different, because it also returns 
the length of the character string:
\begin{verbatim}
          CALL SIC_CH (LINE,IOPT,IARG,Arg,Larg,PRESENT,ERROR)
where
          Larg        Integer, true length of Arg
\end{verbatim}

Two additional routines provide a way of testing the presence of an argument
{\tt SIC\_PRESENT(IOPT,IARG)} returns the logical value {\tt .TRUE.} if the
required argument is present, and {\tt SIC\_LEN(IOPT,IARG)} returns the actual
length of the argument (0 means the argument is missing). A last routine, {\tt
SIC\_NARG(IOPT)} indicates how many arguments are actually present for option
{\tt IOPT}. 

Note that due to the structure of \sic\ vocabulary, {\tt IOPT} is always the
sequential number of the option as defined by the ordering in the {\tt DATA}
statement. Hence {\tt IOPT} is not dependent on the order in which the options
appear in the command buffer currently analysed. 

\sic\ also includes some general character string manipulation routines which
may be of interest in many other problems. All these routines are 
described more completely in section 4.7.

\subsection{The Library Version}
\subsubsection{Creating the Library Interface}

Once you have completed the previous operations, an interactive system 
is available. The system can also be used in batch or within command
procedures. It is very easy to make a Fortran callable version of this 
system by adding only one extra subroutine. Taking again the same 
example this subroutine will be:
\index{EXAMPLE!US\_EXEC}
\index{EXAMPLE!US\_ERROR}
\begin{verbatim}

      FUNCTION US_ERROR(dummy)
*
*       Library version of the user program.
*       All the user commands are accessible through calls 
*       in the form:
*
*       CALL US_EXEC ('This_command')
*
*       The error status can be checked and reset using the
*       function US_ERROR(). If an error exist, the program
*       aborts when trying to execute the next command.
*
      INCLUDE 'inc:errcod.inc'
* The above line defines the FATALE error code used below
      LOGICAL ERROR, US_ERROR
      CHARACTER*(*) BUFFER
      CHARACTER LINE*256, COMM*12, LANG*12, MESSAGE*60
      INTEGER NL, DUMMY, LENC
* Save the error code from last call
      SAVE ERROR
*
* Transmit error status, and reset it
      US_ERROR = ERROR
      ERROR = .FALSE.
      RETURN
*
      ENTRY US_EXEC(BUFFER)
*
* Check error status, abort if not cleared
      IF (ERROR) THEN
         WRITE(6,*) MESSAGE
         WRITE(6,*) LINE(1:NL)
         CALL SYSEXI (FATALE)
      ENDIF
*
* Copy the command line in argument to the local buffer LINE
* Analyse it
      LINE = BUFFER
      NL=LENC(LINE)
      CALL SIC_BLANC(LINE,NL)
      CALL SIC_ANALYSE(COMM,LINE,NL,ERROR)
      IF (ERROR) THEN
         MESSAGE = 'E-US_EXEC,  Error Interpreting Line'
         RETURN
      ENDIF
* 
* If your application is multi-language, then make sure that the 
* command belongs to your language.
      CALL SIC_LANG(LANG)
      IF (LANG.NE.'USER') THEN
         ERROR = .TRUE.
         MESSAGE = 'E-US_EXEC,  Language Mismatch Line'
         RETURN
      ENDIF
*
* Execute it
      CALL RUN_USER(LINE,COMM,ERROR)
      IF (ERROR) THEN
         MESSAGE 'E-US_EXEC,  Error Executing Line'
      ENDIF
      END

\end{verbatim}
\index{ROUTINES!SIC\_BLANC}
\index{ROUTINES!SIC\_ANALYSE}
\index{ROUTINES!SIC\_LANG}
A program can then be written just by typing the same commands as in
interactive. Of course, this is not always convenient, but you should
be able to provide additional routines to make the formatting of the
line, or give a more direct argument transmission. Note that all
errors are absolutely fatal in this Library Mode, and must be handled
by the calling program. This is in contrast with the {\tt EXEC\_USER}
routine which provided a \sic\ like error recovery, but at the expense
of a compulsory interactive use of the program.

\subsubsection{Library Only Mode}

It is sometimes a burden to have complex languages such as {\tt
GREG1$\backslash$} in your {\tt HELP} when you just want to use the library
version of the language. \sic\ provides a way to load a language in ``Library
Only'' mode. This means that the commands are accessible only through a {\tt
US\_EXEC} like program and not through \sic\ monitor capabilities. This mode is
useful for building another more elaborate language from one (or more) lower
level languages (pay attention to possible recursive programming in doing so
however). This mode is called by loading the corresponding language with a null
help specification : 
\index{ROUTINES!SIC\_LOAD}
\begin{verbatim}

           SIC_LOAD(LANG,' ',MCOM,VOCAB,VERSION)

\end{verbatim}

\subsubsection{Reserved logical unit numbers: VMS}

\sic\ has the following usage of Fortran logical unit numbers:
\begin{verbatim}
          5        Input of Commands, shareable 
          6        Output of messages, shareable
\end{verbatim}
Units 5 and 6 are respectively accessed via usual {\tt READ} and {\tt
WRITE} instructions. 
In addition, the terminal is accessed via {\tt QIO} on an
assigned channel for keypad line editing. The associated logical names are {\tt
FOR005} and {\tt FOR006} and the default assignments provided by the system VMS
are: 
\begin{verbatim}
          ASSIGN SYS$INPUT FOR005
          ASSIGN SYS$OUTPUT FOR006
\end{verbatim}
If you wish to be able to reassign the input or/and output of your 
program to a file, you should also make your input and output in the same
way (or use the {\tt SIC\_WPR, SIC\_WPRN} routine). If you mix {\tt
READ(5,format)} and {\tt WRITE(6,format)} instructions with {\tt TYPE, ACCEPT,
READ(*,format) or WRITE(*,format)} instructions, you might experience some
problems to properly re-assign input or output. As a hint for this, remember the
default logical names for Input/Output on VAX/VMS : 
\begin{verbatim}
      Statement             Fortran Log Name        System Log Name
      READ(nnn,f) list        FORnnn                  SYS$INPUT
      READ(*,f) list          FOR$READ                SYS$INPUT
      READ(f) list            FOR$READ                SYS$INPUT
      ACCEPT f,list           FOR$ACCEPT              SYS$INPUT
      WRITE(nnn,f) list       FORnnn                  SYS$OUTPUT
      WRITE(*,f) list         FOR$PRINT               SYS$OUTPUT
      PRINT f,list            FOR$PRINT               SYS$OUTPUT
      TYPE f,list             FOR$TYPE                SYS$OUTPUT
\end{verbatim}

The monitor uses additional logical units for the {\tt LOG} file, for opening
temporary files and for active macro's. These units are reserved 
dynamically by calls to the VAX-VMS appropriate services and do not
interfere with any Fortran unit numbers used within the user program,
except that a program may use too many logical units.

\subsubsection{Reserved logical unit numbers: UNIX}

\sic\ has the following usage of Fortran logical unit numbers:
\begin{verbatim}
          5        Input of Commands, shareable 
          6        Output of messages, shareable
          50 to 99 Used by SIC_GETLUN
\end{verbatim}
Units 5 and 6 are respectively accessed via usual {\tt READ} and {\tt
WRITE} instructions. 
If you wish to be able to reassign the input or/and output of your 
program to a file, you should also make your input and output in the same
way (or use the {\tt SIC\_WPR, SIC\_WPRN} routine). If you mix {\tt
READ(5,format)} and {\tt WRITE(6,format)} instructions with {\tt 
PRINT, READ(*,format) or WRITE(*,format)} instructions, you might experience 
some problem. Mixing with {\tt C} output ({\tt printf} routine for example)
may yield to disordered output because of buffering. Use of routine
{\tt GAGOUT} \index{ROUTINES!GAGOUT} is recommended to printout messages.

Units 50 to 99 are assumed to be available for the routine {\tt
SIC\_GETLUN} \index{ROUTINES!SIC\_GETLUN}. This subroutine returns the
next available logical unit in this range, and keeps track of their
usage. Conflict may occur if the user directly opens a file under a
unit in this range without allocating the unit through a call to {\tt
SIC\_GETLUN}. Other units are never used by \sic\ and other \gildas\
programs.


\subsubsection{Linking on VMS}

In order to avoid an overhead in program size and link time,
the \sic\ system takes advantage of the shareable library facilities.
All the \sic\ system is contained in the module {\tt SICSHR}
available in the library {\tt GAG\_ROOT:[SHARED]GAGSHARE.OLB}.

The access to this library is automatic on some computers.
Issue the command 
\begin{verbatim}
        $ SHOW LOGICAL LNK$LIB*
\end{verbatim}
to know if automatic linking is enabled.

If not enabled, you may either make an explicit reference in the link as:
\begin{verbatim}
        $ LINK PROG1,PROG2,...,GAG_ROOT:[SHARED]GAGSHARE/LIB
\end{verbatim}
either add the following assignment in your LOGIN.COM for automatic linking
to this library:
\begin{verbatim}
        $ ASSIGN GAG_ROOT:[SHARED]GAGSHARE.OLB  LNK$LIBRARY
\end{verbatim}
Note that is you wish to use the \greg\ library together with \sic\,
you must also reference the library {\tt GAG\_ROOT:[SHARED]GREGLIB.OLB} as
described in the \greg\ manual.

\subsubsection{Linking on UNIX}

On Unix system, the location of the GAG software environment
is normally defined by the {\tt \$GAG\_ROOT} environment variable.
If not, ask your system manager to add the definition of {\tt \$GAG\_ROOT} 
in a system-wide ``login'' script.

Several libraries are needed to run the \sic\ system. Libraries may
be shareable or simple archive: the operating system will normally
decided which one to use. All libraries are in the directory 
{\tt \$GAG\_ROOT/lib}. The link command should look like (e.g. for 
Fortran program on HP-UX systems):
\begin{center}
{\tt fort77 -L\$GAG\_ROOT/lib -o prog prog.o -lsic -limage -lgag -lrary}
\end{center}
Other compilers (such as {\tt cc}, the {\tt C} compiler) will have similar
options, but note however that the Fortran libraries will be needed in
the link. Beware that the order of the libraries is significant. For
systems not supporting the {\tt -L} option, you will have to
explicitly mention the full names of the libraries.

\subsection{Using Variables}

\sic\ allows the definition and use of variables. Variables can be
declared by the user, or by the program. In the latter case, \sic\
only remembers the address of the variable, examining its content
only when required (command {\tt EXAMINE} for example or any reference 
to the variable name in a command). This imposes two
precautions in the FORTRAN code.
\begin{enumerate}
\item The attribute of the \sic\ variable ({\tt READ-ONLY} or 
{\tt READ-WRITE}) should be chosen carefully (e.g. a real-time application 
in which the time is declared as a \sic\ variable).
\item The corresponding FORTRAN variable must be {\tt SAVE}d (or appear 
in a {\tt SAVEd COMMON}) to prevent the compiler to allocate it on
the stack. 
%{\tt READ-WRITE} variables must ALWAYS be declared {\tt VOLATILE}.
\end{enumerate}

\subsubsection{Definition}

There are 5 variable declaration routines following the same 
calling conventions
\index{ROUTINES!SIC\_DEF\_DBLE}
\index{ROUTINES!SIC\_DEF\_REAL}
\index{ROUTINES!SIC\_DEF\_INTE}
\index{ROUTINES!SIC\_DEF\_CHAR}
\index{ROUTINES!SIC\_DEF\_LOGI}
\begin{verbatim}
          Argument Data Type      Name of Subroutine
                REAL*8                  SIC_DEF_DBLE
                REAL*4                  SIC_DEF_REAL
                INTEGER*4               SIC_DEF_INTE
                CHARACTER*(*)           SIC_DEF_CHAR
                LOGICAL*4               SIC_DEF_LOGI

The calling syntax is the following 
          CALL SIC_DEF_Name (NAME,VARIABLE,READONLY,ERROR)
for LOGI and CHAR, and
          CALL SIC_DEF_Name (NAME,VARIABLE,NDIM,DIM,READONLY,ERROR)
for DBLE, REAL, and INTE, NDIM being the number of dimensions,
and DIM the dimensions of the array VARIABLE.

\end{verbatim}
{\tt NAME} is the name of the \sic\ variable, {\tt VARIABLE} the name of the
corresponding FORTRAN variable, {\tt READONLY} a logical indicating whether the
variable should be Read-Only {\tt (.TRUE.)} or Read-Write {\tt (.FALSE.)}. {\tt
ERROR} is a logical error flag set by \sic\ if the variable could not be
defined. 

Variable names must be at most 15 characters, upper case only, and 
beginning with a letter. Special characters must be avoided, except
the ``\_'' (underscore) sign.

\subsubsection{Assignment and Examination}

\sic\ variables can be assigned new values, and examined using 
the following routines.
\index{ROUTINES!SIC\_LET\_DBLE}
\index{ROUTINES!SIC\_LET\_REAL}
\index{ROUTINES!SIC\_LET\_INTE}
\index{ROUTINES!SIC\_LET\_CHAR}
\index{ROUTINES!SIC\_LET\_LOGI}
\index{ROUTINES!SIC\_GET\_DBLE}
\index{ROUTINES!SIC\_GET\_REAL}
\index{ROUTINES!SIC\_GET\_INTE}
\index{ROUTINES!SIC\_GET\_CHAR}
\index{ROUTINES!SIC\_GET\_LOGI}

\begin{verbatim}
          Argument Data Type      Assignment    Examination Subroutine
          REAL*8                  SIC_LET_DBLE   SIC_GET_DBLE
          REAL*4                  SIC_LET_REAL   SIC_GET_REAL
          INTEGER*4               SIC_LET_INTE   SIC_GET_INTE
          LOGICAL*4               SIC_LET_LOGI   SIC_GET_LOGI
          CHARACTER*(*)           SIC_LET_CHAR   SIC_GET_CHAR

The calling syntax is the following 
          CALL SIC_LET_Name (NAME,VARIABLE,ERROR)
          CALL SIC_GET_Name (NAME,VALUE,ERROR)
except for SIC_GET_CHAR
          CALL SIC_GET_CHAR (NAME,STRING,LENGTH,ERROR)
\end{verbatim}
These a-priori useless routines can be used to modify variables
defined in completely independent parts of a program such as
the codes supporting two different \sic\ languages. For example
the {\tt GRAPHIC$\backslash$} language interacts with 
{\tt GREG1$\backslash$}  and {\tt GREG2$\backslash$}  through
\sic\ variables.

For assignment routines, the data type of the {\tt VARIABLE} argument
and of the \sic\ variable must match exactly. For retrieving routines,
the data type to specify is the type of the {\tt VALUE} argument; implicit
conversion from the type of the \sic\ variable is done if possible, 
an error is returned otherwise. 

Only {\tt SCALAR} variables can be assigned or examined in this way.
For {\tt ARRAY} variables, you should use the subroutine {\tt SIC\_DESCRIPTOR}.
\index{ROUTINES!SIC\_DESCRIPTOR}
\begin{verbatim}

          CALL SIC_DESCRIPTOR (VARIABLE,DESC,FOUND)

  - VARIABLE (input) is the variable name (general syntax A[i,j]
    allowed)
  - DESC (output) is the descriptor of the variable, an instance of
    the derived type 'SIC_DESCRIPTOR_T' provided by the module
    'GKERNEL_TYPES', containing:
      DESC%TYPE     Variable type:
          * DESC%TYPE > 0 : Character string of length DESC%TYPE
          * DESC%TYPE < 0 may have the value
                  FMT_R4 for REAL(KIND=4) variable
                  FMT_R8 for REAL(KIND=8) variable
                  FMT_I4 for INTEGER(KIND=4) variable
                  FMT_I8 for INTEGER(KIND=8) variable
                  FMT_L  for LOGICAL(KIND=4) variable
                  FMT_BY for INTEGER(KIND=1) variable
                  FMT_C4 for COMPLEX(KIND=4) variable
      DESC%NDIM     Number of dimensions
      DESC%DIMS(7)  Dimensions
      DESC%ADDR     Variable address
      DESC%SIZE     Size of allocation (4-bytes words)
      DESC%STATUS   Origin of variable
               0       program defined
               < 0     user defined
               > 0     image
      DESC%READONLY True if the variable is read-only for the user.
   - FOUND (output) is a logical indicating whether the specified
     variable exists or not.
\end{verbatim}

The parameters {\tt FMT\_R4, FMT\_R8, FMT\_I4, FMT\_I8, FMT\_L,
  FMT\_BY} and {\tt FMT\_C4} are defined in the module {\tt
  gbl\_format}.

Three other routines may be required for variable handling:
\index{ROUTINES!SIC\_MATERIALIZE}
\index{ROUTINES!SIC\_INCARNATE}
\index{ROUTINES!SIC\_VOLATILE}

\begin{verbatim}
        CALL SIC_MATERIALIZE(VARIABLE,DESC,FOUND)
\end{verbatim}
is like SIC\_DESCRIPTOR, but allow implicit transposition and sub-arrays in the
variable name. An intermediate variable will be created to handle such cases.

{\tt SIC\_INCARNATE} is used to create an "incarnation" of
a variable under a specified type {\tt (REAL, DOUBLE, INTEGER)}.
\begin{verbatim}
        CALL SIC_INCARNATE(FORM,DESC,INCA,ERROR)
where
    - FORM is the format of the desired incarnation (FMT_R4, FMT_I4
      or FMT_R8)
    - DESC is the descriptor of the variable 
    - INCA is the descriptor of the incarnation
    - ERROR is a logical error flag
\end{verbatim}

{\tt DESC} and {\tt INCA} are instances of the derived type {\tt
  SIC\_DESCRIPTOR\_T}. {\tt DESC} should have been obtained by a
previous call to {\tt SIC\_DESCRIPTOR}.

Once used, the incarnation may be deleted using routine {\tt SIC\_VOLATILE}
\begin{verbatim}
    CALL SIC_VOLATILE(INCA)
where
    - INCA is the descriptor of the incarnation.
\end{verbatim}

\subsubsection{Mathematical Formula Handling}

\index{ROUTINES!SIC\_MATH}
\index{ROUTINES!SIC\_LOGICAL}
\index{ROUTINES!SIC\_SEXA}
Two subroutines are available to decode mathematical or logical 
expressions, {\tt SIC\_MATH} and {\tt SIC\_LOGICAL}. In addition, a subroutine
is available to decode generalized sexagesimal notation, {\tt SIC\_SEXA}.
The calling syntax is the following 
\begin{verbatim}
          CALL SIC_name (EXPRESSION,LENGTH,VARIABLE,ERROR)
\end{verbatim}
where {\tt EXPRESSION} is a character string containing the mathematical or
logical expression to be evaluated, {\tt LENGTH} is the number of characters
of this expression, {\tt VARIABLE} a {\tt REAL*8} (or {\tt LOGICAL*4}) 
variable to receive the expression value, and {\tt ERROR} a logical error flag.
A generalized sexagesimal notation is for example A:B:C or A:B, where
A, B and C may be variables or expressions or numbers. B and C values
must of course be greater than or equal to 0 and less than 60. The
value is returned in units of A, the leftmost field.

\subsubsection{Deleting Variables}

Declared variables can be deleted when no longer needed, using
routine {\tt SIC\_DELVARIABLE}. 
\index{ROUTINES!SIC\_DELVARIABLE}
The calling syntax is the following 
\begin{verbatim}
          CALL SIC_DELVARIABLE (NAME,USER,ERROR)
\end{verbatim}
where {\tt NAME} is the \sic\ variable name, {\tt USER} a logical indicating
whether program-defined variable are protected against deletion
{\tt (.TRUE.)} or can be deleted {\tt (.FALSE.)}, and
{\tt ERROR} a logical error flag.


\subsection{Using Functions}

It is possible to define user callable functions which are recognized
in the mathematical formulae evaluations, using subroutine 
{\tt SIC\_DEF\_FUNC} as follows
\index{ROUTINES!SIC\_DEF\_FUNC}
\begin{verbatim}
    CALL SIC_DEF_FUNC(NAME,SF,DF,NARG,ERROR)
where
    NAME    is the function name
    SF      is the address of the single precision implementation of
            the function
    DF      is the address of the double precision implementation of
            the function
    NARG    is the number of arguments of the function.
    ERROR   is an error flag
    HLPFILE is a file name or SIC logical value where function help
            can be found (optional argument)
\end{verbatim}
Both single and Double precision routines will be called like as
(e.g. for two arguments)
\begin{verbatim}
    S = SF(arg1,arg2)      and      D = DF(arg1,arg2)
\end{verbatim}

\subsection{SIC Callable Routines}
 
\subsubsection{Monitor interface routines}
\begin{verbatim}

Available subroutines:
        SIC_LOAD        SIC_OPT         SIC_RUN 
        SIC_INSERT      SIC_LOG         SIC_LANG        
Available functions:
        SIC_CTRLC       SIC_LIRE        SIC_INTER_STATE

\end{verbatim} 
To build a program around the \sic\ monitor, different routines
are provided. Some must always be used ({\tt SIC\_LOAD}
and {\tt SIC\_RUN}), others are simply provided for additional capabilities. 
These routines have a standard {\tt SIC\_} like name and are fully 
described in this section.
 
\index{ROUTINES!SIC\_RUN}
{\tt SIC\_RUN (LINE,LANG,COMMAND,ERROR,ICODE,OCODE)}

This subroutine is used to enter SIC, retrieve and analyse a command line
for further execution. All \sic\ possibilities, including execution levels
and error recoveries, made accessible (In particular, the {\tt LINE} 
command line can be a call to a macro file).

\begin{itemize}
\item {\tt LINE   Character*(*) (maximum size is 2048)}\\
        Command line to be executed. Modified by \sic\.
        No need to initialize it when ICODE = 0 or 1, but
        must be initialized is ICODE = -1 or 2
\item {\tt LANG    Character*12}\\
        Name of the language returned by \sic\
\item {\tt COMMAND Character*12}\\
        Name of the command returned by \sic\
\item {\tt ERROR   Logical}\\
        Return error code
\item {\tt ICODE   Operation code}\\
\begin{itemize}
\item{ICODE = -1}\\
      Analyse the command line passed as argument LINE, and return 
      to calling program to execute it.
\item{ICODE = 0}\\
      Loop into SIC to retrieve a new command line LINE, and return to 
      calling program to execute it.
\item{ICODE = 1}\\
      Start SIC, and retrieve a first command line. 
\item{ICODE = 2}\\
      Start SIC, analyse the command line passed as argument,
      and return to calling program to execute it.
\end{itemize}
\item {\tt OCODE   Return code}\\
\begin{itemize}
\item{OCODE = -1}\\
      End of execution in sub-routine mode. Program must return
      immediately to its caller.
\item{OCODE = 0}\\
      Successful analysis of a command. Program must execute it,
      and then loop again on {\tt SIC\_RUN} with ICODE=0 to get 
      further commands.
\item{OCODE = 1}\\
      End of execution caused by typing the EXIT command.
      Program should perform any necessary action (close files,
      etc...) and return to its caller.
\end{itemize}
\end{itemize}

\index{ROUTINES!SIC\_LOAD}
{\tt SIC\_LOAD (LANG,HELP,NCOM,CCOM,VERSION)}

This subroutine initialize a \sic\ language and thus is usually the first
one called. All arguments are unchanged by the routines and may be 
passed as immediate values.
\begin{itemize}
\item {\tt LANG    Character*(*).}\\
        The language name, as it will appear in the {\tt HELP} and will be
        returned by \sic\ after command line processing. It is truncated
        to 12 characters if necessary.
\item {\tt HELP    Character*(*).}\\
        The logical name for the {\tt HELP} file corresponding to the language
        being initialized.
\item {\tt NCOM    Integer.}\\
        The number of command and options, i.e. the dimension of the {\tt CCOM}
        character array
\item {\tt CCOM    Character*12 array of dimension NCOM.}\\
        Contains the vocabulary of the language. The structure of the 
        command vocabulary is described elsewhere in this document.
\item {\tt VERSION Character*(*).}\\
        A string to indicate the version number, the last modified date, 
        the programmer name,... which will appear as a message with the 
        language name at run time.
\end{itemize}

\index{ROUTINES!SIC\_OPT}
{\tt SIC\_OPT (PROMPT,LOGFILE,MEMORY)}

This routine is not compulsory. It is used to set the prompt 
the log file name and the stack usage. This routine only changes
the prompt if called after {\tt SIC\_LOAD}.
\begin{itemize}
\item  {\tt PROMPT      Character*(*).}\\
        The prompt to be used in interactive mode, truncated to 8
        characters if necessary. Default is {\tt SIC.} Note that the caret
        {\tt >} and other alterations such as : or {\tt \_1>} are added by 
        \sic\ at run time and should not be included.
\item {\tt LOGFILE Character*(*).}\\
        The log file name. Default is {\tt LOG}.
\item {\tt MEMORY  Logical.}\\
        Indicates whether the Stack is used or not.
\end{itemize}

\index{ROUTINES!SIC\_INSERT}
{\tt SIC\_INSERT(LINE)}

This routine is only useful when the Stack Buffer is used to store
commands. This is the default, and the case when the flag {\tt MEMORY} was set
to {\tt .TRUE.} in the first call to {\tt SIC\_OPT}. It can be changed with the
{\tt SIC MEMORY} command. {\tt SIC\_INSERT} is used to put a command line 
into the Stack buffer, a 
very useful possibility for some applications, when several lines must 
be put or when the command line must be expanded by the user program
before the insertion is made.

Note however that command lines are automatically inserted in the
Stack Buffer by the monitor for usual commands. This is the
standard way of using the Stack insertion mode, since it automatically
takes into account many things like the execution level before deciding
whether an insertion must occur. Using directly {\tt SIC\_INSERT} usually
implies to disable the automatic insertion by the monitor (using the
character code * in the definition of the associated command, c.f.
Section 4.2). You need also to perform a call to {\tt SIC\_LIRE} to check 
the \sic\ 
\index{ROUTINES!SIC\_LIRE}
execution mode (you should only call {\tt SIC\_INSERT} 
when {\tt SIC\_LIRE()} is equal to 0) and associated calls to {\tt SIC\_LOG} 
to write the same information in the {\tt LOG} file. 
The insertion does not occur if the memory flag is turned off
({\tt SIC MEMORY OFF}).
\begin{itemize}
\item {\tt LINE    Character*(*)}. May be passed by value if convenient
\end{itemize}

\index{ROUTINES!SIC\_LOG}
{\tt SUBROUTINE SIC\_LOG (LINE,NL,LIRE)}

This subroutine writes {\tt LINE(1:NL)} into the Log\_File if {\tt LIRE=0.} 
{\tt LIRE} is
here necessary for consistency with the internal pointer indicating if \sic\
is processing a macro, the stack or the loop. This pointer can be
retrieved by the function {\tt SIC\_LIRE}. A call to {\tt SIC\_LOG} when 
{\tt LIRE} is not 0 has no action. 
\begin{itemize}
\item {\tt LINE    Character*(*)}          Input
\item {\tt NL      Integer}                Input
\item {\tt LIRE    Integer}                Input
\end{itemize}

\index{ROUTINES!SIC\_LANG}
{\tt SUBROUTINE SIC\_LANG(LANG)}

This subroutine returns the name of the language corresponding to the last
command analysed. It is called only when building the library version of a
multi-language application. 
\begin{itemize}
\item {\tt LANG   Character*(*)} is returned by the routine
\end{itemize}
 
\index{ROUTINES!SIC\_CTRLC}
{\tt LOGICAL FUNCTION SIC\_CTRLC ( )}

\sic\ itself traps the {\tt <\^{}C>} by generating a {\tt PAUSE} at the end of
the command which was being executed when {\tt <\^{}C>} was pressed.
You may want in time-consuming applications to check yourself at
specific points whether {\tt <\^{}C>} has been pressed.  {\tt
SIC\_CTRLC} allows you to do so, and resets an internal flag to {\tt
.FALSE.} when called. It returns {\tt .TRUE.} if {\tt <\^{}C>} has
been pressed since either the last command completed execution or the
last time it was called (using the most recent event), {\tt .FALSE.}
otherwise.

\index{ROUTINES!SIC\_LIRE}
{\tt INTEGER FUNCTION SIC\_LIRE ( )}

This subroutine returns the internal pointer of \sic\ indicating where \sic\
is currently reading its commands. {\tt SIC\_LIRE} may take the values 
\begin{itemize}
\item -10 Subroutine mode
\item -2  Reading in the Loop buffer
\item -1  Called from {\tt SIC\_RUN} with {\tt ICODE = -1}
\item 0   Interactive mode
\item I$>$0 Reading in macro number I 
\end{itemize}
 
\index{ROUTINES!SIC\_INTER\_STATE}
{\tt LOGICAL FUNCTION SIC\_INTER\_STATE ( )}

This subroutine returns {\tt .TRUE.} if the session is interactive,
{\tt .FALSE.} otherwise. This is the case if \sic\ is ran during a
batch process, or if the logical unit FOR005 is assigned to a file
(either directly or through an assignment of {\tt SYS\$INPUT}).

\subsubsection{SIC Arguments Retrieving Routines}
\begin{verbatim}

Available subroutines:
          SIC_L4          SIC_I4          SIC_R4          SIC_R8
          SIC_CH          SIC_NEXT
 
Available functions:
          SIC_PRESENT     SIC_LEN         SIC_NARG        SIC_START

\end{verbatim} 

There are 5 retrieving routines following similar calling conventions
\index{ROUTINES!SIC\_CH}
\index{ROUTINES!SIC\_I4}
\index{ROUTINES!SIC\_L4}
\index{ROUTINES!SIC\_R4}
\index{ROUTINES!SIC\_R8}
\begin{verbatim}
          Argument Data Type      Name of Subroutine
                REAL*8                  SIC_R8
                REAL*4                  SIC_R4
                INTEGER*4               SIC_I4
                LOGICAL*4               SIC_L4
                CHARACTER*(*)           SIC_CH

The calling syntax is the following 
          CALL SIC_Name (LINE,IOPT,IARG,ARGUM,PRESENT,ERROR)
Except for SIC_CH
          CALL SIC_CH   (LINE,IOPT,IARG,ARGUM,LARG,PRESENT,ERROR
\end{verbatim}
\begin{itemize}
\item {\tt LINE    Character*(*)}\\
        is the last command line processed from which arguments are to 
        be retrieved.
\item {\tt IOPT    Integer}\\
        is the number of the option. 0 means the command.
        Options are numbered in the order where they appear in the 
        vocabulary array after the command name.
\item {\tt IARG    Integer}\\
        is the number of the argument of the option/command to be 
        retrieved. 0 means the option/command itself.
\item {\tt ARGUM   (Type depending on the subroutine called)}\\
        is the argument to be returned
\item {\tt LARG    Integer}\\
        is the returned number of characters for {\tt SIC\_CH}
\item {\tt PRESENT Logical}\\
        is a logical indicating whether the argument must be present
        {\tt (.TRUE.)} or not {\tt (.FALSE.)}. 
\item {\tt ERROR    An logical error flag}\\
        which is set if either
           i)  {\tt PRESENT} = {\tt .TRUE.} and the argument is missing
        or ii) a decoding error occured.
\end{itemize}
 
In addition there are other functions related to the arguments:
\index{ROUTINES!SIC\_PRESENT}

{\tt LOGICAL FUNCTION SIC\_PRESENT(IOPT,IARG)}

returns a logical value indicating the presence of the {\tt IARG-th}
argument of the {\tt IOPT-th} option.
 
\index{ROUTINES!SIC\_LEN}
{\tt INTEGER FUNCTION SIC\_LEN(IOPT,IARG)}

returns the total length of the {\tt IARG-th} argument of the {\tt IOPT-th}
option. Returns 0 if {\tt SIC\_PRESENT(IOPT,IARG)=.FALSE}.
 
\index{ROUTINES!SIC\_START}
{\tt INTEGER FUNCTION SIC\_START(IOPT,IARG)}

returns a pointer to the address of the argument in the character
string. Returns 0 if {\tt SIC\_PRESENT(IOPT,IARG)=.FALSE.}. This routine can
be used with {\tt SIC\_LEN} for special processing of arguments, such as
sexagesimal decoding.

\index{ROUTINES!SIC\_NARG}
{\tt INTEGER FUNCTION SIC\_NARG(IOPT)}

returns the number of arguments present for option {\tt IOPT}.

\index{ROUTINES!SIC\_NEXT}
{\tt SUBROUTINE SIC\_NEXT(LINE(NEXT:),ARGUM,LARG,NEXT)}

This subroutine can be used for special processing of text with a
syntax similar to command lines, i.e. text in which the delimiters are
single spaces or slashes, strings being included between double
quotes. Provided it is called with the text restricted to the current
delimiter position {\tt LINE(NEXT:)}, it returns the position of the
next delimiter {\tt NEXT} (space or slash, skipping strings), the
character string included between these delimiters, {\tt ARGUM} and
its length {\tt LARG}. This string may further be decoded as double
precision value using routine {\tt SIC\_MATH} or {\tt SIC\_SEXA},
logical value using routine {\tt SIC\_LOGICAL}, or used as character
constant.

For command lines already parsed by \sic\, you may retrieve directly
the argument {\tt IARG} of option {\tt IOPT} by
\begin{verbatim}
        ARGUM = LINE(SIC_START(IOPT,IARG):
     +  SIC_START(IOPT,IARG)+SIC_LEN(IOPT,IARG)-1)
\end{verbatim}

\subsubsection{Command Line Interpretor Subroutines}
 
\index{ROUTINES!SIC\_ANALYSE}
{\tt SUBROUTINE SIC\_ANALYSE (COMMAND,LINE,NLINE,ERROR)}

This subroutine analyses the command line {\tt LINE}, set up all the internal
pointers for argument retrieval, and returns the name of the command
found. The line must have been formatted by {\tt SIC\_BLANC} before being
analysed. All active languages are considered, even the ``Library Only''
languages
\begin{itemize}
\item {\tt COMMAND} Character*12, Command name (returned)
\item {\tt LINE   } Character*(*), Line to be analysed. It is modified by 
{\tt SIC\_ANALYSE}
\item {\tt NLINE  } Integer. Current length of {\tt LINE}, modified on return.
\item {\tt ERROR  } Logical. Return error code
\end{itemize}

\index{ROUTINES!SIC\_BLANC}
{\tt SUBROUTINE SIC\_BLANC(LINE,NLINE)}

This subroutine does an adequate formatting of any line for later
processing by the \sic\ interpretor. It does not use any internal common of
\sic\, and thus may be accessed independently and considered as a more
general routine. 
\begin{itemize}
\item {\tt LINE   } Character*(*), Line to be formatted.
\item {\tt NLINE  } Integer, Current length of {\tt LINE.} It is modified 
by {\tt SIC\_BLANC} and must be initialized so that only trailing spaces 
appear in {\tt LINE} after {\tt NLINE}. A good policy is to initialize 
{\tt NLINE} to {\tt LENC(LINE)}.
\end{itemize}

\subsubsection{All Purpose General Subroutines}
 
\begin{verbatim}

Available subroutines:
          SIC_LOWER       SIC_PARSEF      SIC_UPPER       SIC_WPR
          SIC_WPRN
Available functions
          SIC_GETVM       FREE_VM         LENC
\end{verbatim} 

These routines are of more general use than \sic\ itself.

\index{ROUTINES!SIC\_GETVM}
{\tt INTEGER FUNCTION SIC\_GETVM(N32|N64,ADDR)}

{\tt SIC\_GETVM} allocates virtual memory for {\tt N32} 32-bit or {\tt N64}
64-bit words, and returns the allocated address space into variable {\tt ADDR}.
{\tt SIC\_GETVM} is a generic interface which accepts either 32 or 64-bit
words: it has to be loaded first through the module {\tt GILDAS\_INTERFACES}.
The function value on return is set to 1 in case of success, to other values
otherwise.

\index{ROUTINES!FREE\_VM}
{\tt SUBROUTINE FREE\_VM(N32,ADDR)}

{\tt FREE\_VM} can be used to free the corresponding adress space when
no longer needed.

\index{ROUTINES!SIC\_LOWER}
\index{ROUTINES!SIC\_UPPER}
{\tt SUBROUTINE SIC\_LOWER(LINE) - SIC\_UPPER(LINE)}

Converts the string LINE to lower or upper case letters  respectively.

\index{ROUTINES!SIC\_PARSEF}
{\tt SUBROUTINE SIC\_PARSEF (NAME,FILE,DEF,EXT)}

Parses the file name {\tt FILE} for a default directory {\tt DEF} and 
extension type {\tt EXT}. These item are added to {\tt FILE} if needed, 
and {\tt NAME} returns the short {\tt NAME} of the file, that is, the 
name without extension or directory. All arguments are Character*(*). 
This is the standard way to obtain a file name in the \gildas\ environment:
this routine takes care of logical names, VMS-like syntax, upper/lower
cases, etc...
 
\index{ROUTINES!SIC\_WPR}
{\tt SUBROUTINE SIC\_WPR(PROMPT,LINE)}

Reads the string {\tt LINE} with the prompt {\tt PROMPT}. 
It tries to obtain a non-blank string, prompting again if it reads a blank
string. If it receives a {\tt <\^{}Z>} code, it returns the string 
{\tt "EXIT"}. The prompt is automatically disabled if the session is 
not interactive. 
\begin{itemize}
\item {\tt PROMPT } Character*(*),  Unchanged by {\tt SIC\_WPR}
\item {\tt LINE   } Character*(*),  Returned line.
\end{itemize}

\index{ROUTINES!SIC\_WPRN}
{\tt SUBROUTINE SIC\_WPRN(PROMPT,LINE,N)}

Reads the string {\tt LINE} with the prompt {\tt PROMPT}. Returns N 
the number of
characters read. Returns N=0 if it reads a blank line, or receives
a {\tt <\^{}Z>} code. The prompt is automatically disabled if the session is 
not interactive. 
\begin{itemize}
\item {\tt PROMPT } Character*(*),   Unchanged by {\tt SIC\_WPRN}
\item {\tt LINE   } Character*(*),   Returned line.
\item {\tt N      } Integer,         Number of characters in {\tt LINE}
\end{itemize}
 
\index{ROUTINES!LENC}
{\tt INTEGER FUNCTION LENC(LINE)}

Returns the ``current'' length of the string {\tt LINE}, that is the
position of the last significant character. It thus allows to ignore
trailing blanks.

\subsubsection{Symbol Manipulation Routines}

Three routines are available to define, translate and delete symbols
within a program using \sic\ without using the {\tt SYMBOL} command.

\index{ROUTINES!SIC\_SETSYMBOL}
{\tt SUBROUTINE SIC\_SETSYMBOL(SYMBOL,TRANSLATION,ERROR)}

Defines a symbol of name {\tt SYMBOL} (Character*(*), maximum 12 characters),
translation {\tt TRANSLATION} (Character*(*), maximum 132 characters). An
error flag ({\tt ERROR} logical) is returned if the symbol could not be
defined. Any previous definition is overridden.

\index{ROUTINES!SIC\_GETSYMBOL}
{\tt SUBROUTINE SIC\_GETSYMBOL(SYMBOL,TRANSLATION,ERROR)}

Obtains the current translation of a given symbol. If {\tt TRANSLATION} is
too short, the translation is truncated without warning or error. {\tt ERROR}
is returned if the symbol is undefined only.

\index{ROUTINES!SIC\_DELSYMBOL}
{\tt SUBROUTINE SIC\_DELSYMBOL(SYMBOL,ERROR)}

Deletes a symbol definition. {\tt ERROR} is returned if the symbol was not
defined.

