\chapter{SIC Programming Manual - Partially updated on Oct.2008}

\section{Introduction}

\sic\ (*) is a command line interpretor, written in FORTRAN and callable as
a subroutine by any program.  It provides a command language, with the
following major features:

\begin{itemize}
\item resolution of command abbreviations
\item definition of symbols
\item macro capabilities with arguments substitution during execution
\item log file
\item multi-language structure
\item loop buffers for repetitive actions
\item variables, arithmetic and logical expressions evaluation
\item structured logical tests
\item error recovery
\item stack buffer
\item editing of command lines
\item GUI interface on Motif, OS/X and MS-Windows systems
\item optionally, a Python interface
\end{itemize}

This section concerns the programmer who wants to use \sic\ as the monitor
of a simple or complex, evolutive, 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 Standard Input
  This is called {\tt Read Mode}.
\item Can be called as a subroutine to execute a single command ({\tt
    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 Is portable on all Unix-like systems (including Mac OS/X) and MS-Windows.
\end{itemize}

The section \ref{sic:vocab} describes the command vocabulary structure, and
the initialization sequence of \sic . 
% Section \ref{sic:model} gives the archetype of the structure of a program using \sic\ as its monitor. 
Section \ref{sic:help} indicates how to write the corresponding {\tt HELP} files.
Section \ref{sic:arg} describes how to retrieve arguments from a \sic\
command line. Section \ref{sic:lib} indicates how to complete the program
so that it can also be a library of routines.  Finally, Section
\ref{sic:var} indicates how to use \sic\ variables, and Section
\ref{sic:routines} give all entry points of the \sic\ monitor.

\sic\ programming interface is designed for the Fortran language.
Interfacing with C language requires some system dependent precautions
concerning argument passing mechanism, in particular for character strings.

\section{Initializing SIC: Languages and Packages}
\label{sic:vocab}


\sic\ is a multi-package multi-language interpretor. A package is a collection
of tools logically grouped together to provide some related applications, e.g.
a plotting ensemble like GreG. A package can reference several languages: for
example, GreG contains 4 languages: GREG1, GREG2, GREG3 for 1-D,
2-D and 3-D data plotting, and GTV for the basic plot actions. \sic\ itself has 5 languages: 
SIC, VECTOR, ADJUST, GUI and TASK, with the last two in  ``Library only'' mode.

\subsection{Packages}
A main program using \sic\ is reduced to practically nothing: For example, the main
program of \texttt{Mapping} is
\begin{verbatim}
program mapping
  !----------------------------------------------------------------------
  ! Main astro program
  !----------------------------------------------------------------------
  external :: mapping_pack_set
  !
  call gmaster_run(mapping_pack_set)
  !
end program mapping
\end{verbatim}
All the job is done by \texttt{gmaster\_run} which declares \texttt{Mapping} as the
master program, and calls its package setup routine \texttt{mapping\_pack\_set}.

This package setup routine named \texttt{name\_pack\_set},
where \texttt{name} is the package name, contains e.g. for \mapping\
\begin{verbatim}
subroutine mapping_pack_set(pack)
  use gpack_def
  !
  type(gpack_info_t), intent(out) :: pack
  !
  external :: greg_pack_set
  external :: mapping_pack_init
  external :: mapping_pack_on_exit
  !
  pack%name='mapping'
  pack%ext = '.map'
  pack%depend(1:1) = (/ locwrd(greg_pack_set) /)
  pack%init=locwrd(mapping_pack_init)
  pack%on_exit=locwrd(mapping_pack_on_exit)
  pack%authors="J.Pety, N.Rodriguez-Fernandez, S.Guilloteau, F.Gueth"
  !
end subroutine mapping_pack_set
\end{verbatim}
\texttt{pack} is here a Fortran derived-type variable, with the following
elements
\begin{itemize}\itemsep 0pt
\item \texttt{pack\%name}  The package name  (Character(len=12))
\item \texttt{pack\%ext}  The default extension for procedures (Character(len=12))
\item \texttt{pack\%depend}  The addresses of the package setting routines
required by this package (an integer array of type Address\_Length,
32 or 64 bits depending on the machine).  Note that a package may depend
on several other ones. The dependent packages are automatically loaded.
\item \texttt{pack\%init}  The address of the initialization routine
(an integer of type Address\_Length)
\item \texttt{pack\%init}  The address of the cleaning on exit routine
(an integer of type Address\_Length)
 \item \texttt{pack\%authors}  A character string handling the authors name
\end{itemize}

The initialisation routine referred to by \texttt{pack\%init} must setup all
the package languages, and execute any code require to provide the initial
setup of the package. In addition, it is recommended to setup the messaging
facility: in the example below this is done using \texttt{name\_message\_set\_id}.

\begin{verbatim}
subroutine mapping_pack_init(gpack_id,error)
  use sic_def
  !----------------------------------------------------------------------
  !
  !----------------------------------------------------------------------
  integer :: gpack_id
  logical :: error
  !
  ! Local language
  call init_clean
  !
  ! One time initialization
  call map_message_set_id(gpack_id)  ! Set library id
  !
  ! Language priorities
  call exec_program('SIC'//backslash//'SIC PRIORITY 1 CLEAN')
  !
  ! Specific initializations
  !
end subroutine mapping_pack_init
\end{verbatim}

\subsection{Language Definition} 
A language contains an ensemble of commands. Each language must be
initialized by means of an appropriate call to the routine SIC\_BEGIN.
This routine has the following calling list: \index{ROUTINES!SIC\_BEGIN}
\begin{verbatim}

          SIC_BEGIN(LANG,HELP,MCOM,VOCAB,VERSION,Dispatch,Error)
\end{verbatim}
{\tt LANG} is a Character constant 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} constants in which the first
character is a reserved code. Lower case characters are \textbf{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}
  integer :: sic_commands
  parameter (sic_commands=76)
  character(len=12) :: sic_vocab(sic_commands)
  data sic_vocab/                   &
    ' HELP',                        &  ! Must be the first one...
    ' @',                           &  ! Others by alphabetic order
    ' ACCEPT',  '/ARRAY','/BINARY','/COLUMN','/FORMAT','/LINE',        &
    ' BEGIN',                       &
    ' BREAK',                       &
    ' COMPUTE', '/BLANKING',        &
    ' CONTINUE',                    &
    ' DEFINE',  '/GLOBAL','/LIKE',  &
    ' DELETE',  '/SYMBOL','/VARIABLE','/FUNCTION',                     &
    ' EDIT',                        &
    ' ELSE',                        &
    ' EXAMINE', '/GLOBAL','/FUNCTION','/HEADER','/ADRESS','/ALIAS',    &
    '#EXIT',                        &
    ' END',                         &
    ' FOR',     '/WHILE',           &
    ' IF',                          &
    ' IMPORT',  '/DEBUG',           &
    ' LET',     '/NEW','/PROMPT','/WHERE','/RANGE','/CHOICE','/FILE',  &
                '/INDEX','/SEXAGESIMAL','/LOWER','/UPPER','/FORMAT',   &
                '/FORMULA','/REPLACE','/STATUS',                       &
    ' MESSAGE',                     &
    ' MFIT',    '/START','/STEP','/WEIGHTS','/EPSILON','/METHOD',      &
                '/ITERATIONS','/QUIET','/BOUNDS',                      &
    ' NEXT',                        &
    ' ON',                          &
    ' PAUSE',                       &
    ' PYTHON',  '/END',             &
    '#QUIT',                        &
    '#RECALL',                      &
    ' RETURN',                      &
    ' SAY',     '/FORMAT',          &
    ' SIC',                         &
    ' SORT',                        &
    ' SYMBOL',  '/INQUIRE',         &
    ' SYSTEM',                      &
    ' TYPE'/
\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.

{\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}

\texttt{Dispatch} is a subroutine to handle the dispatching of actions for all
commands in the language.

\texttt{ErrorRoutine} is a subroutine to perform the error recovery action in
case the execution of a command of this language returns an error. It may do nothing.


\subsection{The command dispatching and handling}
The dispatching routine is typically a big SELECT CASE based on the
command name, like this one
\begin{verbatim}
subroutine run_clean (line,comm,error)
  use gbl_message
  !----------------------------------------------------------------------
  ! CLEAN Main routine
  !     Call appropriate subroutine according to COMM
  !----------------------------------------------------------------------
  character(len=*), intent(inout) :: line  ! Command line
  character(len=*), intent(in)    :: comm  ! Command name
  logical,          intent(out)   :: error ! Logical error flag
  !
  call map_message(seve%c,'CLEAN',line)
  !
  ! Analyze command
  select case (comm)
  case ('LOAD')
     call load_buffer(line,error)
  case ('READ')
     call read_image(line,error)
  case ('CLARK')
     call clark_clean(line,error)
  case ('FIT')
   ... etc...
  case default
     call map_message(seve%i,'CLEAN',comm//' not yet implemented')
  end select
  !
end subroutine run_clean
\end{verbatim}

A handling routine for the a command looks like
\begin{verbatim}
      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}
The command line buffer \texttt{LINE} must be passed by argument, never in a
Module, to allow modularity and multi-language use.


\section{The Help File}
\label{sic:help}
The {\tt HELP} files are simple 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 easy 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\_BEGIN} call, or given explicitly.


\section{Retrieving Arguments}
\label{sic:arg}
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 98 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.

Arguments in \sic\ command lines are positional.  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} \index{ROUTINES!SIC\_KE}
\index{ROUTINES!SIC\_DE}
\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
          Character         SIC_KE           (Upcase converted keyword)
          Any               SIC_DE           (Get variable descriptor)
\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} and {\tt SIC\_KE} are slightly different, because they also
return the length of the character string:
\begin{verbatim}
          CALL SIC_CH (LINE,IOPT,IARG,Arg,Larg,PRESENT,ERROR)
          CALL SIC_KE (LINE,IOPT,IARG,Arg,Larg,PRESENT,ERROR)
where
          Larg        Integer, true length of Arg
\end{verbatim}
While {\tt SIC\_CH} returns any character string, with implicit formatting
if necessary, but no case conversion, {\tt SIC\_KE} returns upcase
keywords.\\

{\tt SIC\_DE} is similar to the other subroutines, except it returns a
variable descriptor ({\tt sic\_descriptor\_t}) instead of a Fortran
scalar value. This gives the possibility for the user to pass to the
command either an explicit value (\eg\ 1.23, ``Hello'') or a SIC
variable name of any kind and \emph{any rank}, while the other
subroutines above are not able to deal with non-scalar values. If the
user has passed a variable name, its descriptor is returned. If he has
passed an explicit value, a SIC scratch variable is created in memory:
it must be destroyed at some point with a call to {\tt
  sic\_volatile}. The calling sequence is equivalent to the other
subroutines:
\begin{verbatim}
          CALL SIC_DE (LINE,IOPT,IARG,DESC,PRESENT,ERROR)
where
          DESC is of type(sic_descriptor_t)
\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 \ref{sic:routines}.

\section{The messaging facility}
This needs to be documented.



\subsection{Writing on files: Fortran logical unit number}
\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.

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}, or of the messaging facility,
is recommended to printout information.

The monitor uses additional logical units for the {\tt LOG} file, for
opening temporary files and for active procedures. These units are taken
in the range 50 to 99. 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.

\subsection{Linking on Linux: TO BE UPDATED}

On Unix system, the location of the GILDAS software environment is normally
defined by executing a simple starting script, like this one, typically
in the .bash\_profile of the user.
\begin{verbatim}
export GAG_ROOT_DIR=/home/Guilloteau/gildas/gildas-exe-dev
export GAG_EXEC_SYSTEM=pc-cygwin-gfortran
source $GAG_ROOT_DIR/etc/bash_profile
\end{verbatim}

The development environment can be accessed by typing
\begin{verbatim}
 source $GAG_ROOT_DIR$/admin/gildas-env.sh
\end{verbatim}
which selects the default compilers to build the system. The development environment architecture
uses Makefiles, and the best to develop a new program is just to clone some architecture
(see \texttt{contrib/example} for a full working example \textbf{To be Done}).

\section{The Library Version}
\label{sic:lib}

Once you have completed the previous operations, an interactive system is
available. The system can also be used in batch or within command
procedures. 
Each command handled interactively can also be executed from a program, using either
\texttt{exec\_command} (for simple commands), or \texttt{exec\_program} (to execute a
procedure, or complex commands calling such procedures).

\index{ROUTINES!EXEC\_COMMAND} \index{ROUTINES!EXEC\_PROGRAM}
\begin{verbatim}
   call exec_command{command,error}
   call exec_program(command)
\end{verbatim}
where \texttt{command} is a character string containing the command to be executed.
\texttt{exec\_command} is reserved to execute atomic commands, and return an error
in case of problems. On the other hand, \texttt{exec\_program} is typically called 
with \texttt{command= '@ MyProcedure'}. It cannot return an error, but the procedure
or code being executed must have its own error handling mechanism.


\subsection{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. Commands of such languages are accessible only through
the \texttt{exec\_command} mechanism (or an equivalent coding). 
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 negative size specification :
\index{ROUTINES!SIC\_BEGIN}
\begin{verbatim}
           SIC_BEGIN(LANG,HELP,-MCOM,VOCAB,VERSION,Dispatch,ErrorRoutine)
\end{verbatim}

A language loaded in such a mode can still be accessed interactively or in procedures: the
command name must be given with the full language name in it to resolve the
command. Similarly, the HELP can be accessed by giving the full language and
command names.


\section{Using Variables}
\label{sic:var}
\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 to prevent the
compiler to allocate it on the stack.
\end{enumerate}

\subsection{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}
\index{ROUTINES!SIC\_DEF\_LOGIN}
\index{ROUTINES!SIC\_DEF\_CHARN}
\index{ROUTINES!SIC\_DEF\_STRN}
\index{ROUTINES!SIC\_DEFSTRUCTURE}
\begin{verbatim}
          Argument Data Type      Name of Subroutine
                REAL(KIND=8)            SIC_DEF_DBLE
                REAL(KIND=4)            SIC_DEF_REAL
                INTEGER(KIND=4)         SIC_DEF_INTE
                CHARACTER(LEN=*)        SIC_DEF_CHAR, SIC_DEF_STRN, SIC_DEF_CHARN
                LOGICAL(KIND=4)         SIC_DEF_LOGI, SIC_DEF_LOGIN

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, INTE, CHARN, and LOGIN,  NDIM being the number of dimensions,
and DIM the dimensions of the array VARIABLE, and
          CALL SIC_DEF_STRN (NAME,VARIABLE,LEN,READONLY,ERROR)
LEN being the length of 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.

In addition, \texttt{SIC\_DEFSTRUCTURE(Name,readonly,error)} can be used to
define SIC structures.

\subsection{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(kind=8)            SIC_LET_DBLE   SIC_GET_DBLE
          REAL(KIND=4)            SIC_LET_REAL   SIC_GET_REAL
          INTEGER(KIND=4)         SIC_LET_INTE   SIC_GET_INTE
          LOGICAL(KIND=4)         SIC_LET_LOGI   SIC_GET_LOGI
          CHARACTER(LEN=*)        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 materialization or incarnation may be deleted using routine {\tt SIC\_VOLATILE}
\begin{verbatim}
    CALL SIC_VOLATILE(INCA)
where
    - INCA is the descriptor of the incarnation/materialization.
\end{verbatim}

\subsection{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.

\subsection{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.


\section{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,HLPFILE)
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}

\section{SIC Callable Routines}

\subsection{Monitor interface routines}
\label{sic:routines}
\begin{verbatim}

Available subroutines:
        SIC_BEGIN       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, like {\tt SIC\_BEGIN},
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\_BEGIN}
\noindent {\tt SIC\_BEGIN (LANG,HELP,NCOM,CCOM,VERSION,Dispatch,Error)}

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*(*) 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 when using the SIC VERSION command
\item \texttt{Dispatch} The dispatching routine
\item \texttt{Error} The error handling routine
\end{itemize}


\index{ROUTINES!SIC\_INSERT}
\noindent  {\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 \ref{sic:vocab}). 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*(*)}.
\end{itemize}

\index{ROUTINES!SIC\_LOG}
\noindent  {\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} 
\noindent {\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} 
\noindent {\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} 
\noindent {\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}
\noindent {\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.

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

Available subroutines:
          SIC_L4          SIC_I4          SIC_R4          SIC_R8
          SIC_CH          SIC_KE          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\_KE} \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(KIND=8)            SIC_R8
                REAL(KIND=4)            SIC_R4
                INTEGER(KIND=4)         SIC_I4
                LOGICAL(KIND=4)         SIC_L4
                CHARACTER(LEN=*)        SIC_CH, SIC_KE

The calling syntax is the following
          CALL SIC_Name (LINE,IOPT,IARG,ARGUM,PRESENT,ERROR)
Except for SIC_CH and SIC_KE
          CALL SIC_CH   (LINE,IOPT,IARG,ARGUM,LARG,PRESENT,ERROR)
          CALL SIC_KE   (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} and {\tt SIC\_KE}
\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}
\texttt{SIC\_KE} is like \texttt{SIC\_CH}, but expects a ``keyword'', and thus 
returns the argument after upper case conversion.

In addition there are other functions related to the arguments:


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

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

\index{ROUTINES!SIC\_PRESENT}
\noindent {\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\_AMBIGS}
\noindent {\tt SUBROUTINE SIC\_AMBIGS(FACILITY,NAME,FULL,VOCAB,MVOC,IVOC,ERROR)}

search for {\tt NAME} in the vocabulary {\tt VOCAB}, and returns the
corresponding pointer {\tt IVOC} in the vocabulary and corresponding
keyword {\tt FULL = VOCAB(IVOC)} if {\tt NAME} is a non-ambiguous
abbreviation of {\tt FULL}.
\begin{itemize}
\item {\tt FACILITY   Character*(*)}\\
  A character string containing the name of the calling subroutine. This
  string is printed before any failure message (ambiguous or non existing
  keyword).
\item {\tt NAME   Character*(*)}\\
  The input name to be searched for in the vocabulary
\item {\tt FULL   Character*(*)}\\
  The complete keyword returned.
\item {\tt IVOC   Integer}\\
  The keyword number in the vocabulary.
\item {\tt MVOC   Integer}\\
  The number of keywords in the vocabulary.
\item {\tt VOCAB  Character*(*)(MVOC)}\\
  The vocabulary.
\item {\tt ERROR  Logical}\\
  An error flag set if the input name was ambiguous, invalid or not found
  in the vocabulary.
\end{itemize}
Typically, \texttt{NAME} will have been recovered by a call to \texttt{SIC\_KE}

\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\_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, 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, 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.

\subsection{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\_FORMAT}
before being analysed. All active languages are considered, even the
``Library Only'' languages
\begin{itemize}
\item {\tt COMMAND} Character(LEN=*), Command name (returned)
\item {\tt LINE } Character(LEN=*), 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\_FORMAT} {\tt SUBROUTINE SIC\_FORMAT(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\_FORMAT} 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}

\subsection{All Purpose General Subroutines}

\begin{verbatim}

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

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


\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 (in the SIC meaning).

\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}


\subsection{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.


\section{Obsolescent Features}

\subsection{Function}
\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. It is obsolescent, as the Fortran-90 intrinsic LEN\_TRIM
provides the same functionality.

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

{\tt SIC\_GETVM} allocates virtual memory for {\tt N32} 32-bit words, and
returns the allocated address space into the \texttt{KIND=ADDRESS\_LENGTH}
variable {\tt ADDR}. {\tt  SIC\_GETVM} 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.

{\tt SIC\_GETVM} and {\tt FREE\_VM} use is being deprecated, as the ALLOCATE/DEALLOCATE
mechanism of Fortran-90 offers an equivalent functionality.

\subsection{Routines for Library usage (Obsolescent, for record only)}


\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\_BEGIN}.
\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\_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}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "gildas-prog"
%%% End:
