.ec _
.ll 76
.ad b
.in 4
.\"====================================================================
.ti -4
1 Language
.ce
SIC_\ Command Language Summary

.nf
ACCEPT        : Read variable in various format.
BEGIN         : Begin a sub-procedure, help file or data file.
BREAK         : Exit without error from a FOR-NEXT loop.
COMPUTE       : Execute non-arithmetic operations on variables.
CONTINUE      : Resume macro or loop execution after PAUSE.
DATETIME      : Convert date and/or time to/from various formats
DEFINE Type V : Define new variables.
DELETE        : Delete variables or symbols.
DIFF Var1 Var2: List the differences between two variables or files.
EDIT [File]   : Edit a file or a dump of the Stack.
ELSE [IF Log] : Alternate IF block directive.
END           : End IF block structure or a sub-procedure.
EXECUTE       : Execute a command line
EXAMINE Var   : Type the current value of the specified variable.
EXIT [Code]   : Exit from the program.
FOR           : Open a FOR-NEXT loop. Also FOR /WHILE or FOR /IN.
HELP XX[_\]    : Give an explanation of command XX or language XX_\.
IF Logical    : Start a conditional IF block.
IMPORT Package: Dynamically import another package in current one.
LET           : Assign value to variable.
MESSAGE       : Send a message to screen and/or message file.
MFIT A=F(B,p) : Fit a formula into SIC variables.
MODIFY        : Modify the spectroscopic axis of a cube.
NEXT          : End FOR loop definition and activates the execution.
ON ERROR COMM : Change the current error recovery action.
PAUSE         : Set a break point in a Loop or a Macro.
PYTHON        : Start/End intercommunication between SIC and PYTHON.
QUIT          : Abort an execution interrupted by PAUSE.
RETURN        : Terminate procedure execution.
SAY "text"    : Type a text or variable or expression value.
SIC Arg       : List or Change some SIC internal status.
SORT Key Vars : Sort variables according to another one.
SYMBOL        : Define, list and delete symbols.
SYSTEM        : Create or attach sub-processes, run system commands.
TIMER         : Check or customize the SIC timer.
TYPE [XX]     : List file XX or the stack.
@ XX [P1 ...] : Read commands from macro XX and executes them.
.fi
.\"====================================================================
.ti -4
1 ACCEPT
.ti +4
[SIC_\]ACCEPT Var__Name /ARRAY File__Name [/options]
.ti +4
[SIC_\]ACCEPT Var__Name /BINARY File__Name Offset
.ti +4
[SIC_\]ACCEPT Var__1 [Var__2 [...]] /COLUMN File__Name [Separator] [/options]

Read SIC variables from formatted or binary files. This command has 3
major modes: /ARRAY to read in a FORMATTED way a SINGLE n-dimensional
variable, /BINARY to read in BINARY form a SINGLE n-dimensional
variable, and /COLUMN to read in a FORMATTED way SEVERAL 1-dimensional
variables.
.\"--------------------------------------------------------------------
.ti -4
2 /ARRAY
.ti +4
[SIC_\]ACCEPT Var__Name /ARRAY File__Name [/FORMAT String] [/LINE Begin End]

Read a N-Dimensional variable of name Var__Name from a formatted file
File__Name, using list-directed (free) format, or a user specified
format if /FORMAT option is present. The /LINE option can be used to
skip some lines before starting reading. Not recommended for character
arrays.
.\"--------------------------------------------------------------------
.ti -4
2 /BINARY
.ti +4
[SIC_\]ACCEPT Var__Name /BINARY File__Name [Skip]

Read a N-Dimensional variable of name Var__Name from a binary file
File__Name. The optional Skip argument indicates how many BYTEs to
skip before starting reading.

The command COMPUTE LINES /BLANK can be used to count the number of
(useful) lines in a file and to define the output arrays with the
appropriate size.
.\"--------------------------------------------------------------------
.ti -4
2 /COLUMN
.ti +4
[SIC_\]ACCEPT Var__1 [Var__2 [...] /COLUMN File__Name [Separator]
[/FORMAT String] [/LINE L1 [L2]]

Read ONE or SEVERAL 1-Dimensional variables in a flexible
format from a formatted file File__Name. Each variables can be of any
length, from 0 (scalar) to N. They are filled by reading each
associated column, starting from first line. Data is read in as many
lines as required. If end of file is reached in the meantime, an error
is raised.

Characters after a "!" are considered as comments and are
ignored. Blank or full comment lines (starting with a "!") are
skipped. The starting line number can be selected with /LINE option.

A * as an argument of the ACCEPT command indicates a dummy variable
used to skip a column in the input file. For example, the command
.ti +4
ACCEPT A * B C /COLUMN TEST.DAT
.br
reads A,B and C from columns 1,3 and 4 of file TEST.DAT, since the *
indicates to skip the second column.

Option /FORMAT can also be used to specify a fixed Fortran-like format.

By default, the format is the equivalent of the Fortran list-directed
(*) format. In this format, character strings must be included between
quotes. The default can be changed by specifying a separator as a
second argument of option /COLUMN. The separator can be " " ( which
gives a behaviour like the COLUMN command of GreG), or any other
character. For example, specifying "\;" as a separator can allow to
read CSV files (e.g. Excel data files).

Example of list-directed read (note the quotes are taken into
account):
.nf
    SIC> type test.dat
    123 "Hello, world!" 3.14
    SIC> define integer i
    SIC> define character c*16
    SIC> define real r
    SIC> accept i c r /column test.dat
    SIC> exa i c r
    I               =          123           ! Integer GLOBAL
    C               = Hello, world!          ! Character*16 GLOBAL
    R               =    3.140000            ! Real    GLOBAL
.nf
In most cases, a list-directed is equivalent to use space as
separator. Only when quotes or blanks in strings are involved makes a
difference.

Example of blank-separated read (in this case, providing the blank
separator or not makes no difference):
.nf
    SIC> type test.dat
    123 Hello 3.14
    SIC> accept i c r /column test.dat " "
    SIC> exa i c r
    I               =          123           ! Integer GLOBAL
    C               = Hello                  ! Character*16 GLOBAL
    R               =    3.140000            ! Real    GLOBAL
.fi

Example of blank-separated read (in this case, the blank separator
MUST be given):
.nf
    SIC> type test.dat
    123 1.23" 4.56"
    SIC> define character l*12 m*12
    SIC> accept i l m /column test.dat " "
    SIC> exa i l m
    I               =          123           ! Integer GLOBAL
    L               = 1.23"                  ! Character*12 GLOBAL
    M               = 4.56"                  ! Character*12 GLOBAL
.fi
.\"--------------------------------------------------------------------
.ti -4
2 /FORMAT
.ti +4

Specify a fortran format to read the input file for command ACCEPT
/ARRAY or ACCEPT /COLUMN. Mixing CHARACTER and NUMERIC (REAL,...)
arrays is not available yet, and only one character array can be read
at a time. Blank or commented lines are not skipped.

Example:
.in +4
.nf
SIC> TYPE cities.dat
  Toulouse          1.111    11.11111
  Bordeaux          2.222    22.22222
  Grenoble          3.333    33.33333
  Marseille         4.444    44.44444
(truncated)
SIC> DEFINE CHARACTER CITY*16[44]
SIC> DEFINE REAL X[44] Y[44]
SIC> ACCEPT X Y /COLUMN "cities.dat" /LINE 4 /FORMAT "20x,F8.3,1x,F8.3"
SIC> ACCEPT CITY /COLUMN "cities.dat" /LINE 4 /FORMAT "2x,A16"
.fi
.in -4

This option is invalid with /BINARY.
.\"--------------------------------------------------------------------
.ti -4
2 /LINE
.ti +4
[SIC_\]ACCEPT Var__Name /LINE L1

Indicate the first line to be read in the input file for command
ACCEPT /ARRAY or ACCEPT /COLUMN. Blank and commented lines have to be
taken into account in L1.

This option is invalid with /BINARY.
.ti -4
2 Excel

Excel (TM) datafile may be readable by command ACCEPT. They must be converted
to CSV format (Comma Separated Values). A suitable use of the dummy variables
in ACCEPT command allows to skip the non-numeric fields. The proper separator
must then be specified using the second argument of option /COLUMN: e.g.
.br
ACCEPT * Var1 Var2 /File Excel.csv ";" /LINES 2 20
.br
will read Var1 and Var2 from lines 2 to 20 of the corresponding Excel file,
from Excel columns "B" and "C" (second and third).

To be documented: Can character variables also be read with numeric ones provided
some adequate /FORMAT option ?
.\"====================================================================
.ti -4
1 BEGIN
.ti +4
[SIC_\]BEGIN Procedure|Help|Data FileName

Begin a new Procedure, Help file, or ASCII Data file. All lines until
the corresponding END Procedure|Help|Data FileName command is found
are considered to be the body of the new file. Such files are located
in the directory designated by the logical name GAG__PROC:.
.\"====================================================================
.ti -4
1 BREAK
.ti +4
[SIC_\]BREAK

Terminate a loop execution. The two uses of command BREAK are usually
.nf
    ON ERROR BREAK
    FOR I 1 TO 3 BY 0.5
      ...
    NEXT
or
    LET A = C               ! A is a known variable
    FOR I 1 TO 100 BY 1
      ...
      IF I+A.EQ.0  BREAK
    NEXT
.fi
BREAK differs from QUIT because it does not transmit any error.
.\"====================================================================
.ti -4
1 COMPUTE
.ti +4

[SIC_\]COMPUTE OutVar OPERATION InVar [Parameters] [/BLANKING Bval [Eval]]

Perform operations or transformations on variables that are not
directly supported by the array capabilities of the SIC command
interpretor. OutVar is the output variable, InVar the input
variable. Outvar must be defined beforehand.

The following operations are available on INTEGER, REAL and DOUBLE
PRECISION arrays, regardless of their nature:
.in +4
.ti -2
- MAX
.br
MIN
.br
MEAN
.br
RMS (standard deviation)
.br
SUM
.br
PRODUCT
.br
MEDIAN
.br
QUANTILE
.br
for which InVar is an array of rank 1 to 7 (a 1-D to 7-D array), and
OutVar must be an array of lesser rank (i.e., one or more dimension
less than InVar, down to a number), AND of identical shape as InVar
for the dimensions in common. See subtopic for QUANTILE specifications.
.br
Example (if A[4,12,2,8] and B[4,12]):
.ti +8
COMPUTE B MAX A
.br
Sections, implicit transpositions, etc... permitted by SIC are
supported.
.ti -2
- HISTOGRAM: see subtopic HISTOGRAM for details.
.in -4
Blanking values Bval and Eval allow to ignore values of the Invar
array if at Eval from Bval, for these operations only. At least Bval
must be passed to option /BLANKING, and default is 0.0 for Eval.
SET_ BLANKING has no effect here since it is a command of the GREG1_\
language.
.br
In case of no valid result, NaN is returned, or Bval if blanking is
enabled. This may occur in particular when all InVar values are
blanked.

The following transformations are available:
.in +4
.ti -2
- GATHER
.br
Return the list of different input values (see subtopic for details)
.ti -2
- RANKORDER
.br
Return the ordering of the input values.
.ti -2
- INTEGRAL or DERIVATIVE
.br
Integral or derivative of the input variable
.ti -2
- FFT+ or FFT-
.br
Direct or Inverse Fast Fourier Transform: see subtopic FFT for
details.
.ti -2
- FOURT+ or FOURT-
.br
Direct or Inverse Fast Fourier Transform: see subtopic FOURT for
details.
.ti -2
- COMPLEX
.br
Populates the Real and (optionally) Imaginary part of OutVar (complex variable) with InVar
(real) and (optionally) the Imaginary part by the following (real) variable name.
.ti -2
- REAL
.br
OutVar = REAL part of InVar. OutVar is Real, InVar is Complex .
.ti -2
- IMAG
.br
OutVar = IMAGE part of InVar. OutVar is Real, InVar is Complex.
.ti -2
- ABS
.br
OutVar = AMPLITUDE (InVar). OutVar is Real, InVar is Complex.
.ti -2
- PHASE
.br
OutVar = PHASE (InVar). OutVar is Real, InVar is Complex.
.ti -2
-_ CMP* operations as in "COMPUTE OutVar CMPMUL InVar1 InVar2". All
variables must be complex arrays of identical size.
.ti +2
CMPADD: OutVar = InVar1 + InVar2.
.ti +2
CMPSUB: OutVar = InVar1 - InVar2.
.ti +2
CMPMUL: OutVar = InVar1 * InVar2.
.ti +2
CMPDIV: OutVar = InVar1 / InVar2.
.in -4

Operations on files:
.ti +2
- DATE: File last modification time
.ti +2
- FILESIZE: File size in bytes
.ti +2
- LINES: Number of lines in a formatted file

Miscellaneous operations (see subtopics for details):
.in +4
.ti -2
- DIMOF
.ti -2
- GAG__DATE
.ti -2
- LOCATION
.ti -2
- BTEST Test bit values
.ti -2
- IS__A__SIC__VAR
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 QUANTILE
.ti +4
[SIC_\]COMPUTE OutVar QUANTILE InVar

Compute the k-quantiles (i.e. the k-1 values which split the data in
k subsets of equal or almost-equal sizes) of the InVar array in
OutVar. For convenience the 0-th (minimum value) and the k-th (maximum
value) quantiles of the InVar array are also computed.

OutVar must be an array of shape [...,k+1]. The leading dimensions,
if any, must match the leading dimensions of the InVar array.

In practice this means:
.br
- the median (2-quantile) needs k+1=3 (return min, median, max),
.br
- the quartiles need k+1=5,
.br
and so on.
.\"--------------------------------------------------------------------
.ti -4
2 DATE
.ti +4
[SIC_\]COMPUTE Modification__Date DATE Filename

Return the last modification date of the file Filename into the
integer variable Modification__Date. Used in procedures to check when
file has last been changed.

If the output variable is a 4-bytes integer (Fortran I*4), returned
value is in seconds since 01-jan-1970. As the value will overflow
after 19-JAN-2038, this syntax is obsolescent and will be removed at
some point. Consider using I*8 output variable (in nanoseconds) or the
SIC MODIFIED command.

If the variable is a 8-bytes integer (Fortran I*8), returned value is
in nanoseconds since 01-jan-1970. In the latter case, your system
(e.g. Linux >= 2.5.48) AND filesystem (e.g. ext4) must support
timestamp granularity below the second. If not, value precision is
limited to 1 second.
.\"--------------------------------------------------------------------
.ti -4
2 FILESIZE
.ti +4
[SIC_\]COMPUTE OutVar FILESIZE FileName

Return the file size of FileName in bytes into the integer variable
OutVar.

For large files, prefer an I*8 (DEFINE LONG) output variable. With
I*4, values above 2 GiB are not representable.
.\"--------------------------------------------------------------------
.ti -4
2 DIMOF
.ti +4
[SIC_\]COMPUTE OutVar DIMOF InVar

Return the shape of array InVar in OutVar[1:7], and its rank in
OutVar[8]. For this purpose, OutVar must be an INTEGER array of
dimension [8]. Undefined dimensions are set to 0.

See also HELP FUNCTION RANK and HELP FUNCTION SIZE.
.\"--------------------------------------------------------------------
.ti -4
2 FFT
.ti +4
[SIC_\]COMPUTE OutVar FFT+|FFT- InVar [REAL]

FFT+ performs Direct Fast Fourier Transform, while FFT- performs
Inverse Fast Fourier Transform.

Command accepts REAL or COMPLEX variables. OutVar is a 2-D array with
second dimension equals 2, storing respectively the Real and Imaginary
part of the (complex) output Fourier transform. By default, InVar is
like OutVar, but if parameter REAL is specified InVar is a 1-D array.
.\"--------------------------------------------------------------------
.ti -4
2 FOURT
.ti +4
[SIC_\]COMPUTE OutVar FOURT+|FOURT- InVar

FOURT+ performs Direct Fast Fourier Transform, while FOURT- performs
Inverse Fast Fourier Transform.

Operates on input and output on COMPLEX arrays of dimension [2,NX,NY].
.\"--------------------------------------------------------------------
.ti -4
2 GATHER
.ti +4
[SIC_\]COMPUTE OutArray GATHER InArray

Returns in a NEW 1-D variable named OutArray the list of values found in
the (existing) n-D variable InArray.  The output array must not exists
and is created by the program itself. It is of the same type as the input
array.

NaN and Blanked values are ignored.

.\"--------------------------------------------------------------------
.ti -4
2 GAG__DATE
.ti +4
[SIC_\]COMPUTE IntDate GAG__DATE "15-DEC-2035"
.ti +4
[SIC_\]COMPUTE StrDate GAG__DATE 4127

GAG__DATE keyword converts a string date into a "radio Julian date"
(integer value), or vice-versa. The kind of the output variable
(resp. integer or character) rules the expected kind for input
variable (resp. character or integer). The output variable must be
scalar and writeable, and the date string should be 11 characters at
least.

A "radio Julian date" (or "Jansky Julian date") starts as -2^15 on the
date of the first radio observation by Karl Jansky. It is thus the
Modified Julian date minus 60549. That choice was made to maximize the
time interval over which radio astronomical data could be usefully
stored in an integer*2, back when 2 bytes of header space per spectrum
were a significant consideration. This date has little meaning outside
the rather sparse community of souls gathered around the CLASS
program, however.
.\"--------------------------------------------------------------------
.ti -4
2 HISTOGRAM
.ti +4
[SIC_\]COMPUTE OutVar HISTOGRAM InVar [Hmin] [Hmax] [/BLANKING Bval [Eval]]

Put in variable OutVar (dimension [n,2]) the histogram of values of
n-D variable InVar, eventually between the cuts Hmin and Hmax, and
with blanking values Bval and Eval (that is, values of the Invar array
are not taken in account for the histogram if at Eval from
Bval). These parameters can be absent. One can use '*' to omit any of
them.

The number of bins is dictated by the first dimension of the array
OutVar. In the absence of said cuts, the cuts used are the maximum and
minimum values of the InVar array. The OutVar variable contains the
histogram in its first column (OutVar[1]) and the corresponding bin
value in the second column (OutVar[2]).
.\"--------------------------------------------------------------------
.ti -4
2 IS__A__SIC__VAR
.ti +4
[SIC_\]COMPUTE OutVar IS__A__SIC__VAR InVar

Determines whether InVar (Character string) is the name of an
existing SIC Variable or not.
OutVar must be a scalar Logical variable.

The functionality is similar to the build-in SIC function EXIST,
but EXIST would complain about invalid filenames as arguments.
Here, InVar can be any arbitraray string.

This command is used in some scripts to determine silently
whether its arguments are File names,
variable names or other expressions (see e.g. p__load.greg for
an application.)
.\"--------------------------------------------------------------------
.ti -4
2 LINES
.ti +4
[SIC_\]COMPUTE OutVar LINES FileName [/BLANK]

Count the number of lines in a formatted file. More precisely, it
counts the number of carriage returns (same as Linux shell "wc
-l"). Be careful of missing carriage return at the end of your files.

The option /BLANK can be used to ignore blank and comment (starting
with "!") lines, in the same way the command ACCEPT does.
.\"--------------------------------------------------------------------
.ti -4
2 LOCATION
.ti +4
[SIC_\]COMPUTE OutVar LOCATION InVar Value

Search for Value in the array InVar, and puts in OutVar the 2 nearest
indices of InVar for which its values surrounds Value. These variables
have some requirements:
.in +4
.ti -2
- InVar_  must be a 1D-array of REAL or DOUBLE values,
.ti -2
- Value_  must be scalar numeric,
.ti -2
- OutVar must be a 1D-array of 2 INTEGER values.
.in -4
InVar is also intended to be ordered (ascending or descending), or
else the result is unpredictable. Use SIC_\SORT to sort arrays.
.\"--------------------------------------------------------------------
.ti -4
2 RANKORDER
.ti +4
[SIC_\]COMPUTE OutVar RANKORDER InVar

Compute the order (sorting array) corresponding to the values in
InVar, e.g.
.nf
  SIC> define real a[4] b[4]
  SIC> let a 10 15 12 9
  SIC> compute b rankorder a
  SIC> exa b
  B               is a real Array     of dimensions  4
     4.000000       1.000000       3.000000       2.000000
.fi

InVar and OutVar are R*4 or R*8 variables, assumed to be 1-D
variables. This can be used e.g. for statistical non-parametric tests
like the Spearman test.
.\"--------------------------------------------------------------------
.ti -4
2 INTEGRAL
.ti +4
[SIC_\]COMPUTE OutVar INTEGRAL InVar

Compute the integral of the InVar variable, in the classical sense, i.e.
.ti +2
OutVar[i] = InVar[1]+Invar[2]+...+Invar[i]
.br
InVar and OutVar are assumed to be 1-D variables
.\"--------------------------------------------------------------------
.ti -4
2 DERIVATIVE
.ti +4
[SIC_\]COMPUTE OutVar DERIVATIVE InVar

Compute the derivative of the InVar variable, in the classical sense, i.e.
.ti +2
OutVar[i] = InVar[i+1]-Invar[i]
.br
InVar and OutVar are assumed to be 1-D variables, of size N.
OutVar[N] is linearly extrapolated from the N-1 and N-2 values.

.\"--------------------------------------------------------------------
.ti -4
2 BTEST
.ti +4
[SIC_\]COMPUTE OutVar BTEST InVar [Ibit]

Bit-test one or several bit values of the input variable, and return
true for each bit equal to 1.

The optional integer argument Ibit indicate which bit should be
tested. The default is to check all the bits.

If all the bits of (a single element of) InVar are tested, OutVar must
be an array with its first dimension equal to this number of bits,
e.g. 32 for INTEGERs, 64 for DOUBLEs, etc. InVar may be a
multi-dimensional array, in which case OutVar must have the same
extra-dimensions.

In details, this tool is an overlay to the BTEST Fortran function
(except that bit numbering starts at 1 here). Note that this hides the
machine dependencies (IEEE, EEEI, etc) by using a unique integer model
regardless of its physical layout. For more information, please refer
to the Fortran documentation.

Examples:

.nf
SIC> define integer i
SIC> let i 2
SIC> define logical one
SIC> compute one btest i 1  ! First bit value
SIC> exa one
ONE             = F                          ! Logical GLOBAL

SIC> define logical all[32]
SIC> compute all btest i  ! All bit values
SIC> exa all
ALL             is a logical Array     of dimensions  32
 F T F F F F F F F F F F F F F F F F F F F F F F
 F F F F F F F F

SIC> define integer i2[3]
SIC> let i2 1 2 3
SIC> define logical one2[3]
SIC> compute one2 btest i2 2  ! Second bit values of the 3 elements
SIC> exa one2
ONE2            is a logical Array     of dimensions  3
 F T T

SIC> define logical all2[32,3]
SIC> compute all2 btest i2  ! All bit values of all elements
SIC> exa all2[1] all2[2] all2[3]
ALL2[1]         is a logical Sub-Array of dimensions  32
 T F F F F F F F F F F F F F F F F F F F F F F F
 F F F F F F F F
ALL2[2]         is a logical Sub-Array of dimensions  32
 F T F F F F F F F F F F F F F F F F F F F F F F
 F F F F F F F F
ALL2[3]         is a logical Sub-Array of dimensions  32
 T T F F F F F F F F F F F F F F F F F F F F F F
 F F F F F F F F
.fi
.\"====================================================================
.ti -4
1 CONTINUE
.ti +4
[SIC_\]CONTINUE_ _ _ _ _ or_ _ _ _ _ C

Resume loop or macro execution after a PAUSE (explicit or caused by
an error or a <^C>). Typing C instead of CONTINUE will always do
exactly the same thing. This is the only superior abbreviation
installed in SIC.
.\"====================================================================
.ti -4
1 DATETIME
.ti +4
[SIC_\]DATETIME /FROM Date-Time-Spec /TO Outvar1 Outformat1
[... OutvarN OutformatN]

Convert a date and/or time between various formats, storing result in
one or more output variables. The options /FROM and /TO must be
present.
.\"--------------------------------------------------------------------
.ti -4
2 /FROM
.ti +4
[SIC_\]DATETIME /FROM NOW
.ti +4
[SIC_\]DATETIME /FROM Val1 Form1 ... ValN FormN

The option /FROM is used to define a single and non-ambiguous
date-time. The date-time is fully specified as the combination of a
year, month, day, hour, minute, and seconds. They can be described
with the following pairs:
.ti +2
Iye YEAR (integer, default 1970)
.ti +2
Imo MONTH (integer, default 1)
.ti +2
Ida DAY (integer, default 1)
.ti +2
Iho HOUR (integer, default 0)
.ti +2
Imi MINUTE (integer, default 0)
.ti +2
Nse SECONDS (real, default 0.0)

The pairs can be combined in any order, but each field must be defined
once at most. If a field is not specified, its default value is
used. The day, hour, minute, and seconds fields can go beyond their
usual ranges: the resulting date-time is shifted accordingly. For
example:
.nf
  DATETIME /FROM 2015 YEAR                 ! 2015-01-01 00:00:00.000
  DATETIME /FROM 2015 YEAR 11 MONTH 16 DAY ! 2015-11-16 00:00:00.000
  DATETIME /FROM 2015 YEAR 100 DAY         ! 100-th day of year 2015
.fi


The keyword NOW can be used alone to specify the current UTC
date-time. The values PREVIOUS or NEXT can also be used for each
field: they resolve as the previous or next quantity with respect to
the current UTC date-time. These syntaxes define all the fields at
once, i.e. they can not be combined with other pairs of values. For
example:
.nf
  DATETIME /FROM NOW           ! Now (UTC)
  DATETIME /FROM PREVIOUS DAY  ! Yesterday, same time
  DATETIME /FROM NEXT HOUR     ! Today or tomorrow, in 1 hour from now
.fi


The option /FROM also recognizes specific date and/or time formats:
.nf
  JULIAN       Julian date with fractional day (e.g. 2457343.227256944)
  MJD          Modified Julian Date (e.g. 57342.72725694445)
  ISO          ISO date (e.g. 2015-11-16T17:27:15.000)
  GAG__DATE     GAG date integer format (e.g. -3207)
  YYYYMMDD     date with all numbers (e.g. 20151116)
  DD-MMM-YYYY  date where MMM is the month in letters (e.g. 16-NOV-2015)
  RADIAN       time of day in radians, usually betwen 0 and 2*pi
  SEXAGESIMAL  time of day using sexagesimal notation (e.g. 17:27:15.000)
.fi

JULIAN, MJD and ISO define the 6 date and time fields: they can not be
combined with anything else. GAG__DATE, YYYYMMDD, and DD-MMM-YYYY
define the date: they can be combined with a time specifier. RADIAN
and SEXAGESIMAL define the time: they can be combined with a date
specifier. For example:
.nf
  DATETIME /FROM 2015-11-16T17:27:15.000 ISO
  DATETIME /FROM 57342.72725694445 MJD
  DATETIME /FROM -3207 GAG__DATE 4.569490147 RADIAN
.fi

The inputs can be either explicit scalar values, scalar variables, or
array variables. They can be mixed as long as arrays have equal
size. For example
.nf
  DATETIME /FROM "16-NOV-2015" DD-MMM-YYYY ArrayVar RADIAN
.fi
results in an array specification, where all the specified values
share the same date but each time is taken in ArrayVar.
.\"--------------------------------------------------------------------
.ti -4
2 /TO
.ti +4
[SIC_\]DATETIME /TO Outvar1|* Outformat1 [... OutvarN|* OutformatN]

The date-time(s) defined by the /FROM option is converted and
transfered to the output targets. A target can be a variable (given
its name) or the terminal (if * is given). There is no restriction on
their kinds and numbers, i.e. you can convert the date-time to all the
possible formats, or repeat the same conversion for several
targets. Supported formats are:

.nf
  YEAR         year value as integer
  MONTH        month value as integer
  DAY          day value as integer
  HOUR         hour value as integer
  MINUTE       minute value as integer
  SECONDS      seconds value  as real value
  JULIAN       Julian date with fractional day (e.g. 2457343.227256944)
  MJD          Modified Julian Date (e.g. 57342.72725694445)
  ISO          ISO date (e.g. 2015-11-16T17:27:15.000)
  GAG__DATE     GAG date integer format (e.g. -3207)
  YYYYMMDD     date with all numbers (e.g. 20151116)
  DD-MMM-YYYY  date where MMM is the month in letters (e.g. 16-NOV-2015)
  RADIAN       time of day in radians (betwen 0 and 2*pi)
  SEXAGESIMAL  time of day using sexagesimal notation (e.g. 17:27:15.000)
.fi

If input the date-time specification is an array, the output
variable(s) must be arrays of the same size.
.\"====================================================================
.ti -4
1 DEFINE
.ti +4
[SIC_\]DEFINE Type Var1 [Keys...] [Var2 [Keys...] [...]] [/GLOBAL]
[/LIKE VarLike] [/TRIM [Rank]]

If Type is FUNCTION, define a user-function. If Type is COMMAND or
LANGUAGE, define a new user command or language
respectively. Otherwise, define new variables of the specified
type. Type can then be REAL, INTEGER, DOUBLE (for double precision
real values), LOGICAL, CHARACTER, or TABLE, HEADER, IMAGE, UVTABLE,
STRUCTURE, FITS or ALIAS. By default, new variables are LOCAL,
i.e. valid only within the current macro and all loops or interactive
levels called by this macro. When the /GLOBAL switch is specified, the
variables are valid at all levels. Local variables are examined before
global variables.
.\"--------------------------------------------------------------------
.ti -4
2 ALIAS
.ti +4
[SIC_\]DEFINE ALIAS AliasName TargetVar [/GLOBAL]

Define a new variable AliasName pointing towards (a subset of) an
existing variable. The new alias shares all the properties of its
target: type, Local or Global status, Readonly attribute. The
TargetVar can be a sub-array, but implicit transposition is not
allowed.

If the /GLOBAL option is present, the TargetVar must be a Global
variable.

Aliases can be deleted using the standard DELETE /VAR command: this
does not delete the TargetVar variable. On the contrary, when a
standard variable is deleted, all aliases attached to it are also
deleted, since the variable content disappears.

Structures cannot have aliases, but structure members can.
.\"--------------------------------------------------------------------
.ti -4
2 CHARACTER
.ti +4
[SIC_\]DEFINE CHARACTER Var1*Lvar1[DIM1] [...]
.ti +4
[SIC_\]DEFINE CHARACTER*Length Var1[DIM1] [...]

CHARACTER variables can be scalar or multi-dimensional. The length of
CHARACTER variable is specified after an * either after CHARACTER keyword
or after the name of the variable. When both are present, the per-variable
length has precedence. The dimension field (same syntax as for other arrays)
should follow the length declaration.  The CHARACTER keyword can be
abbreviated, i.e. this is a valid statement
.ti +4
DEFIN CHAR*12 Var1  Var2*36 Var3[16]

Character substrings can be accessed for reading and writing with the
[charmin:charmax] specification, e.g.
.nf
    DEFINE CHARACTER C*128
    LET C[3:4] "AB"
    EXAMINE C[3:4]
    IF C[3:4].EQ."AB"  SAY "Yes"
.fi
The substring specification MUST be provided with the column ":", even
for a single character, e.g. C[1:1]. If the character variable has one
or more dimensions, the substring specification can be applied to a
scalar subarray, e.g.
.nf
    DEFINE CHARACTER*128 D[3,4]
    EXAMINE D[1,2][3:4]
.fi
It is an error to apply a substring specification to an array, e.g.
.nf
    EXAMINE D[1,][3:4]  ! Invalid
.fi
.\"--------------------------------------------------------------------
.ti -4
2 COMMAND
.ti +4
[SIC_\]DEFINE COMMAND NAME "Equivalent command" [Help__File]

Define a new user-defined SIC command.

By default, the new command will be part of the USER_\
language. USER_\ language is implicitely created if required without
invoking DEFINE LANGUAGE. If the command is prefixed by another user
language, it will be part of it. Attempting to add a command of a
program language is an error.

Help__File is an optional argument indicating the name of the
associated help text to be used by the command HELP. The standard
rules for help syntax applies (see SIC documentation for details). If
no help file is provided, the one of the parent language will be used.

User defined commands are translated into their equivalent command at
execution time. They appear in the list of command displayed by HELP,
and can be abbreviated as normal "program-defined" commands. For
example
.ti +4
DEFINE COMMAND INPUT "@ input.greg" pr:input__greg.hlp
.br
define a new command USER_\INPUT, which will execute procedure
input.greg.
.\"--------------------------------------------------------------------
.ti -4
2 DOUBLE
.ti +4
[SIC_\]DEFINE DOUBLE Var1[DIM1] [Var2[DIM2] [...]] [/GLOBAL]

DOUBLE variables can be multi-dimensional. Up to 7 dimensions can be
specified in the optional DIM field, with the following syntax:
.ti +4
Var[n1] or Var[n1,n2] etc... up to Var[n1,n2,n3,n4,n5,n6,n7]
.br
where Var is the variable name and n1 to n7 are integer constants or
variables.
.\"--------------------------------------------------------------------
.ti -4
2 FITS
.ti +4
[SIC_\]DEFINE FITS Var File [HEADER] [ [index] [T] [B] ]  [/GLOBAL]

Define variables associated to the keywords and data of a FITS file.
The defined variables depend on the FITS file content. Both "basic"
FITS files and FITS extension (XTENSION) are handled.

The HEADER keyword indicates to read only the FITS Headers (which
includes any Extension), not the main data array.

An 'index' value may be added to read only the 'index'-th extension.

With 'B' code (stands for Basic): define only the basic keywords, not
proprietary keywords. In particular suppress HIERARCH keyword
structure present in ESO FITS headers.

The 'T' code may be added to get all multidimensional arrays
transposed (depending on how the FITS file was written, sometimes the
dimensionality of the SIC variables created from the FITS structure is
not handy. Using the transposition code can be a solution then).

The 'index', 'T' and 'B' codes can appear in any order.

For basic FITS data, the following variables are defined
.nf
   VAR%NDIM       Integer        Number of dimensions
   VAR%DIM        Integer[4]     Dimensions
   VAR%CONVERT    Double[3,4]    Conversion formulae for the 4 axes:
                                 Reference pixel, Value at reference
                                 pixel, Increment
   VAR%DATA       Real           FITS data array
.fi
The variables are defined as part of a structure. GreG command LIMITS
/RGDATA A recognizes such a basic FITS structure in much the same way
as GILDAS images.

The DEFINE_ FITS command tries to define a SIC structure which
contains all FITS keywords, as well as all binary and ASCII tables
located in FITS extensions.

Support for Random groups (although this is an obsolescent FITS
structure, it is still widely used) is also available.

DEFINE FITS only works to read FITS files, but not to create them.
See VECTOR_\FITS to write FITS files (and also read them, but only
the main array so far).
.\"--------------------------------------------------------------------
.ti -4
2 FUNCTION
.ti +4
[SIC_\]DEFINE FUNCTION NAME(X,Y,Z) Expression(X,Y,Z)

Define an arithmetic user function of several variables. The maximum
number of variables is 8. The function definition can reference any of
the known mathematic operators and intrinsic or program defined
functions, but not previously defined user functions (i.e. user
function definition is not recursive).
.\"--------------------------------------------------------------------
.ti -4
2 HEADER
.ti +4
[SIC_\]DEFINE HEADER Var1 File1 Key1 [Var2 File2 Key2 [...]]
                [/GLOBAL] [/TRIM [Rank]] [/LIKE OtherVar]

Define variables associated to the HEADER of the GILDAS images
located in the files specified by File1, File2, etc... 
The keywords Key1, Key2, etc... must be either READ or WRITE.

FileJ can be * to define a virtual header. In this case,
KeyJ must be IMAGE or UVDATA. VarJ must include the dimensions,
or the /LIKE option should be present to derive them from
an existing image.

The following variables are defined:
.nf

   ! General section
   VAR%GENE       Integer        Length of section
   VAR%NDIM       Integer        Number of dimensions (ReadOnly)
   VAR%DIM        Integer[7]     Dimensions           (ReadOnly)
   VAR%CONVERT    Double[3,7]    Conversion formulae for the 7 axes:
                                 Reference pixel,
                                 Value at reference pixel,
                                 Increment

   ! Blanking section
   VAR%BLAN       Integer        Length of section
   VAR%BLANK      Real[2]        Blanking and tolerance

   ! Extrema section
   VAR%EXTREMA    Integer        Length of section
   VAR%MAX        Real           Maximum of data
   VAR%MIN        Real           Minimum of data
   VAR%MINLOC     Integer[7]     Position of min
   VAR%MAXLOC     Integer[7]     Position of max

   ! Units and coordinates system section
   VAR%DESC       Integer        Length of section
   VAR%UNIT       Char*12        Image unit
   VAR%UNIT1      Char*12        First axis type
   VAR%UNIT2      Char*12        Second axis type
   VAR%UNIT3      Char*12        Third axis type
   VAR%UNIT4      Char*12        Fourth axis type
   VAR%SYSTEM     Char*12        Coordinate system

   ! Position section
   VAR%POSI       Integer        Length of section
   VAR%SOURCE     Char*12        Source name
   VAR%RA         Double         Right Ascension
   VAR%DEC        Double         Declination
   VAR%LII        Double         Galactic longitude
   VAR%BII        Double         Galactic latitude
   VAR%EQUINOX    Real           Equinox of coordinates

   ! Projection section
   VAR%PROJ       Integer        Length of section
   VAR%PTYPE      Integer        Projection type (code)
   VAR%A0         Double         First coordinate of projection center
   VAR%D0         Double         Second coordinate of projection center
   VAR%ANGLE      Double         Position angle of projection
   VAR%X__AXIS     Integer        First projected axis
   VAR%Y__AXIS     Integer        Second projected axis

   ! Spectroscopy section
   VAR%SPEC       Integer        Length of section
   VAR%LINE       Char*12        Line name
   VAR%FREQRES    Double         Frequency resolution
   VAR%IMAGFRE    Double         Image Frequency
   VAR%RESTFRE    Double         Rest Frequency
   VAR%VELRES     Real           Velocity resolution
   VAR%VELOFF     Real           Velocity offset
   VAR%F__AXIS     Integer        Frequency/Velocity axis
   VAR%DOPPLER    Real           Doppler factor
   VAR%VTYPE      Integer        Velocity type (code)

   ! Beam section
   VAR%BEAM       Integer        Length of section
   VAR%MAJOR      Real           Major axis of beam
   VAR%MINOR      Real           Minor axis of beam
   VAR%PA         Real           Position angle of beam

   ! Noise section
   VAR%SIGMA      Integer        Length of section
   VAR%NOISE      Real           Theoretical noise
   VAR%RMS        Real           Actual noise

   ! Proper motion section
   VAR%PROPER     Integer        Length of section
   VAR%MU         Real[2]        Along RA,DEC in mas/year
   VAR%PARALLAX   Real           Parallax in mas

   ! Telescope section
   VAR%TELE__SEC   Integer        Length of section
   VAR%NTEL       Integer        Number of telescopes
   ! For each telescope i=1 to NTEL:
   VAR%TELi%LON   Double         Telescope longitude
   VAR%TELi%LAT   Double         Telescope latitude
   VAR%TELi%ALT   Real           Telescope altitude [m]
   VAR%TELi%DIAM  Real           Telescope diameter [m]
   VAR%TELi%NAME  Char*12        Telescope name

.fi
where VAR is the specified variable name for the header. VAR becomes a
dummy variable of type header, which can only be referenced in a
further DELETE_ /VARIABLE command, in structure assignments through
command LET, or in the HEADER command. The VAR%item variables are ReadOnly
if the keyword Key is READ, ReadWrite otherwise (including of course
virtual headers), except for the dimension variables which cannot 
be modified.
.\"--------------------------------------------------------------------
.ti -4
2 IMAGE
.ti +4
[SIC_\]DEFINE IMAGE Var1 File1 Key1 [Var2 File2 Key2 [...]]
              [/GLOBAL] [/TRIM [Rank]]

Define variables associated to both the content and the header of the
GILDAS images located in the files, if specified. This command acts as
a combination of DEFINE_ HEADER and DEFINE_ TABLE. It accepts the same
keywords (KeyN) as DEFINE_ TABLE. If the keyword is READ, the header
variables are mapped ReadOnly, otherwise they are mapped ReadWrite.

See HELP_ DEFINE_ HEADER for a description of the individual header
variables.

FITS cubes can also be loaded as a Gildas image variable, using the
FITS file name in place of the file name. There will be no
disk-to-disk translation: at load time, the FITS header will be
translated on-the-fly to the GDF header elements, and the data will
also be converted on-the-fly if needed.
.br
This feature is only available for cube-like data in Primary HDU. To
load other HDUs, use disk-to-disk conversion with the command V\FITS
/HDU.
.\"--------------------------------------------------------------------
.ti -4
2 INTEGER
.ti +4
[SIC_\]DEFINE INTEGER Var1[DIM1] [Var2[DIM2] [...]] [/GLOBAL]

INTEGER stands for SHORT (I*4) or LONG (I*8) integers depending on the
current SIC INTEGER rule.

INTEGER variables can be multi-dimensional. Up to 7 dimensions can be
specified in the optional DIM field, with the following syntax:
.ti +4
Var[n1] or Var[n1,n2] etc... up to Var[n1,n2,n3,n4,n5,n6,n7]
.br
where Var is the variable name and n1 to n7 are integer constants or
variables.
.\"--------------------------------------------------------------------
.ti -4
2 LANGUAGE
.ti +4
[SIC_\]DEFINE LANGUAGE Name [Help__File]

Define a new user language. User languages can be filled with user
commands with DEFINE COMMAND. Their precedence against other languages
is set by default to Automatic, use SIC PRIORITY afterwards to change
it.

If an help file is provided, the command HELP will look into this file
for the language help (see SIC documentation for details). Else it
will display a summary of all the language commands and their
translations.
.\"--------------------------------------------------------------------
.ti -4
2 LOGICAL
.ti +4
[SIC_\]DEFINE LOGICAL Var1[DIM1] Var2[DIM2] [...] [/GLOBAL]

LOGICAL variables can be multi-dimensional. Up to 7 dimensions can be
specified in the optional DIM field, with the following syntax:
.ti +4
Var[n1] or Var[n1,n2] etc... up to Var[n1,n2,n3,n4,n5,n6,n7]
.br
where Var is the variable name and n1 to n7 are integer constants or
variables.
.\"--------------------------------------------------------------------
.ti -4
2 REAL
.ti +4
[SIC_\]DEFINE REAL Var1[DIM1] [Var2[DIM2] [...]] [/GLOBAL]

REAL variables can be multi-dimensional. Up to 7 dimensions can be
specified in the optional DIM field, with the following syntax:
.ti +4
Var[n1] or Var[n1,n2] etc... up to Var[n1,n2,n3,n4,n5,n6,n7]
.br
where Var is the variable name and n1 to n7 are integer constants or
variables.
.\"--------------------------------------------------------------------
.ti -4
2 STRUCTURE
.ti +4
[SIC_\]DEFINE STRUCTURE Str [/GLOBAL] [/LIKE MoldStr]

Define a new structure name. Structure naming follows the Fortran-90
convention, i.e. Str%SubStr%SubStrElement. Structure elements
(including sub-structures if needed) can be defined using command
.ti +4
DEFINE REAL Str%Element
.br
etc.  The %DATA element field is reserved to handle the N-Dimensional 
data area associated to the structure, allowing Structure to mimick
Images if needed. 

An entire structure and all its associated members is deleted by a
single command DELETE_ Str_ /VARIABLE.  A Structure can be defined
like another one using the /LIKE option.

.\"--------------------------------------------------------------------
.ti -4
2 TABLE
.ti +4
[SIC_\]DEFINE TABLE Var1 File1 Key1 [Var2 File2 Key2 [...]] [/GLOBAL]

Define variables associated to GILDAS images located in the files, if
specified. The variable type and dimensions are derived according to
the value of the keyword Key and the file content:
.in +4
.ti -2
-_ READ or WRITE: use the type and dimensions from the file, and
connect the image in Readonly or ReadWrite access. The variable name
must not include any dimension field.
.ti -2
-_ DOUBLE, INTEGER or REAL: create a new table of the specified
type. The dimensions must then be specified in the dimension field of
the variable name, as for a standard variable. The associated file is
created, unless a star ('*') is used as file name.
.ti -2
-_ EXTEND: take type and first dimensions from the file, but extend
the last dimension to the value specified in the dimension field. The
full syntax in this case is thus
.ti +8
DEFINE TABLE Var[Ldim] File EXTEND
.br
where Ldim is the new value for the last dimension.
.in -4

DEFINE_ TABLE does not create any additional variables for the image
header. See DEFINE_ IMAGE and DEFINE_ HEADER for this information.
.\"--------------------------------------------------------------------
.ti -4
2 UVTABLE
.ti +4
[SIC_\]DEFINE UVTABLE Var1 File1 Key1 [Var2 File2 Key2 [...]] [/GLOBAL]

Define variables associated to both the content and the header of the
GILDAS UV Table located in the specified files. The files must be UV
Tables, a version of 2-D tables with some conventions for the
interpretation of columns and an image-like header.

When creating a new file, if the file name has the extension ".tuv",
the command creates a TUV table (transposed UVT) with the
corresponding header elements transposed.

See HELP_ DEFINE_ HEADER for a description of the individual header
variables.
.\"--------------------------------------------------------------------
.ti -4
2 /GLOBAL
.ti +4
[SIC_\]DEFINE Type Var1 [Var2 [...]] /GLOBAL

The /GLOBAL option specifies that the variables are global, instead of being
local to the current procedure. Local variables have precedence over global
variables.

The /GLOBAL option is incompatible with DEFINE_ FUNCTION and DEFINE
COMMAND.
.\"--------------------------------------------------------------------
.ti -4
2 /LIKE
.ti +4
[SIC_\]DEFINE Type Var1 [Var2 [...]] /LIKE VarLike
.ti +4
[SIC_\]DEFINE IMAGE Var1 File1 Key1 [...]] /LIKE VarLike
.ti +4
[SIC_\]DEFINE STRUCTURE Struct1 [Struct2 [...]] /LIKE StructLike

The /LIKE option allows definition of Type REAL, LOGICAL, DOUBLE or
INTEGER arrays with dimensions identical to those of the (existing)
VarLike array. IMAGEs and TABLEs can also be defined in this way. The
dimension field must not be specified in such a case. 

/LIKE can also be used in structure context: the new structure 
will be filled with a tree identical to the StructLike one (which
can be a HEADER or an IMAGE). However, the %DATA area of Structures 
and Images is ignored in this process, and should be defined 
separately if needed.

The /LIKE option is incompatible with DEFINE_ FUNCTION, DEFINE
COMMAND, as well as DEFINE HEADER and DEFINE FITS.
.\"--------------------------------------------------------------------
.ti -4
2 /TRIM
.ti +4
[SIC_\]DEFINE IMAGE|HEADER Var1 File1 Key1 [Var2 File2 Key2 [...]]
              /TRIM [Rank] [/GLOBAL]

Attempt to trim trailing degenerate dimensions up to the specified Rank.
If no Rank is given, trim all possible trailing degenerate dimensions.

If Rank is positive, the defined header or image will have exactly Rank
dimensions. An error occur if the corresponding file has non-degenerate
dimensions beyond this rank.  If the file is of lower dimensionality
than the specified Rank, its dimensionality is extended by  adding
degenerate dimensions up to Rank.

If Rank is negative, trim all possible trailing degenerate dimensions,
and return an error if the final dimensionality remains larger than Rank.

Examples:
.br
  Assume file.gdf contains a 3-D array of dimensions [Nx,Ny,1]
.nf
  DEFINE IMAG A file.gdf READ
    will return the 3-D array A[Nx,Ny,1]
  DEFINE IMAG A file.gdf READ /TRIM 4
    will return the 4-D array A[Nx,Ny,1,1]
  DEFINE IMAG A file.gdf READ /TRIM 1
    will produce an error (same with /TRIM -1)
  DEFINE IMAG A file.gdf READ /TRIM -4
    will return the 2-D array A[Nx,Ny]
  DEFINE IMAG A file.gdf READ /TRIM
    will also return the 2-D array A[Nx,Ny]
.fi
.\"====================================================================
.ti -4
1 DELETE
.ti +4
[SIC_\]DELETE /VARIABLE|/SYMBOL|/FUNCTION Name1 [Name2 [...]]

Delete specified variables, symbols or functions. For IMAGE
variables, also frees the corresponding file.
.\"====================================================================
.ti -4
1 DIFF
.ti +4
[SIC_\]DIFF Var1|File1 Var2|File2

List the differences between two entities. Each entity can be either a
Sic variable name or a GDF file name (images, cubes, UV
tables,...). Comparison is made on their headers (if both variables
provide a header) and/or their data (if both variables provide a data
array).

The result of the last comparison (true/false) is saved in the logical
variable SIC%DIFF.
.\"====================================================================
.ti -4
1 EDIT
.ti +4
[SIC_\]EDIT [File__Name]

Without argument, EDIT dumps the Stack on a file named STACK.DEFEXT
where DEFEXT is the default macro extension specified by the program
or by the user using command SIC_\SIC_ EXTENSION, and then calls a
text editor to edit this file. If a file name is given, the specified
file is edited.

The editor to be chosen is defined by the logical name GAG__EDIT,
which you can define in your $HOME/.gag.dico file. Command SIC_ EDIT
NewEditor can also be used to re-define the choice of the editor.
.\"====================================================================
.ti -4
1 ELSE
.ti +4
[SIC_\]ELSE [IF Logical__expression [THEN]]

Conditional directive in an IF-END IF block. Similar to Fortran ELSE
and ELSEIF statements, but note that here the space between ELSE and
IF is compulsory, while the THEN keyword is optional. If the
compulsory space bothers you, just define the following symbol
.ti +4
SYMBOL ELSEIF "SIC_\ELSE IF"
.\"====================================================================
.ti -4
1 END
.ti +4
[SIC_\]END Procedure|Help|Data|If

.ti +4
[SIC_\]END IF

Mark the end of an IF block. Normal execution resumes. The symbol
ENDIF is defined as an abbreviation of SIC_\END_ IF.

.ti +4
[SIC_\]END Procedure|Help|Data

Terminate the definition of a new Procedure, Help file, or Data file.
See command BEGIN for details.
.\"====================================================================
.ti -4
1 EXECUTE
.ti +4
[SIC_\]EXECUTE CommandString

Execute the command line given as argument. It can be an explicit
character string, a string variable contents, or a mixture of
both. For example:

.nf
! Simple command
SIC> SIC_\EXECUTE EXAMINE

! Command with several words
SIC> SIC_\EXECUTE "EXAMINE /GLOBAL"

! Command stored in variable
SIC> DEFINE CHARACTER*32 COMMAND
SIC> LET COMMAND "EXAMINE /GLOBAL"
SIC> SIC_\EXECUTE 'COMMAND'

! Command stored in several variables
SIC> DEFINE CHARACTER*32 COMMAND OPTION
SIC> LET COMMAND "EXAMINE"
SIC> LET OPTION "/GLOBAL"
SIC> SIC_\EXECUTE 'COMMAND'" "'OPTION'
.fi

The error status of the executed command is propagated to the EXECUTE
command, except for @ (errors raised by @ are lost).
.\"====================================================================
.ti -4
1 EXAMINE
.ti +4
[SIC_\]EXAMINE [Name1] [Name2] [...] [NameN] [/GLOBAL] [/HEADER]
[/ADDRESS] [/ALIAS] [/PAGE] [/SAVE]

List variables.

EXAMINE without argument gives the list of known variables with their
respective types. Each variable name is followed by its definition and
the keywords "GBL" for GLOBAL (interpreter level 0) variables,
LCL(lev) for LOCAL variables at interpretor level "lev" (viz., in a
procedure), WR for READ/WRITE variables, RD for READONLY
variables. The option /PAGE can be used to examine long outputs page
by page.

With one or more arguments, EXAMINE will usually type the content of
the specified variables (local variables have priority). But:
.in +4
.ti -2
-_ If the argument ends by the % character, it is assumed to indicate
a structure or an image header, and all associated header variables
are listed.
.ti -2
-_ Wildcarding is permitted: if the argument contains one or more "*"
character, all compatible variables names are listed.
.ti -2
-_ In any case, typing an ambiguous variable name will generate a list
of choices.
.in -4

With the /GLOBAL option, lists only the GLOBAL variables, as opposed
to LOCAL variables (i.e, in a loop or a macro)

With the /HEADER option, lists only the variables having an associated
header (i.e., the known images).

With the /ALIAS option, lists only the Aliases and their association.

The /ADDRESS option is used for debugging. It gives the internal
variable descriptor.
.\"--------------------------------------------------------------------
.ti -4
2 /SAVE
.ti +4
[SIC_\]EXAMINE Variable /SAVE OutputFile

THIS OPTION IS EXPERIMENTAL AND MIGHT BE REMOVED OR RENAMED IN THE
FUTURE WITHOUT ADVISE.

The output of the command EXAMINE is written in the named file instead
of terminal. The output is specially formatted under the form

.nf
  Variable = Value
or
  Array = Val1 Val2 Val3  ! i.e. flatened array
.fi

This way, the output file can be replayed in Sic as a procedure in a
save-and-reload process. This makes most sense when examining
structures with the syntax EXA MYSTRUCT% /SAVE MYOUTPUT.
.\"====================================================================
.ti -4
1 EXIT
.ti +4
[SIC_\]EXIT [Code] [/NOPROMPT]

EXIT always ends SIC execution, at any level. An error status can be
set on return to the shell by passing an integer code (default 0). In
interactive sessions, <^D_> has the same behaviour as EXIT.

On the opposite <^Z_> only ends the current level of execution, so
that when typed at the top level, <^Z_> also ends the session. Note
that <^Z_> may be trapped when interactive editing is enabled.

The option /NOPROMPT will disable any prompt at exit time, for
programs (or their dependencies) which prompt for an answer before
leaving.

Note that end of SIC execution does not necessarily means end of
program execution: SIC may be entered again later by the calling
program.
.\"====================================================================
.ti -4
1 FOR
.ti +4
[SIC_\]FOR Loop__Variable n1 n2 n3 TO n4 BY n5 n6 TO n7
.ti +4
[SIC_\]FOR Loop__Variable /IN List__Variable
.ti +4
[SIC_\]FOR /WHILE Logical__Expression

Open a FOR-NEXT loop to be executed for real values in the list (FOR
Variable), or any values (including strings) given in the /IN option, 
 or until a logical expression becomes false (FOR /WHILE). 
  
Up to 9 loops may be nested in any way. The loop can be
exited at any time with the command BREAK (see HELP BREAK for
details).

If the loop is entered interactively at the prompt, the last character
of the prompt becomes a ':' instead of '>', and all subsequent
commands typed in until NEXT are the body of the loop.

* Indexed loops: FOR Loop__Variable n1 n2 n3 TO n4 BY n5 n6 TO n7
  See HELP FOR Indexed
  
* Generalized loops: FOR Loop__Variable /IN List
  See HELP FOR /IN

* Conditional loops: FOR /WHILE Logical__Expression
  See HELP FOR /WHILE
  
The Loop_Variable is the name of a SIC variable created by the 
FOR command and must not be an existing variable name. 

.ti -4
2 Indexed
.ti +4
[SIC_\]FOR Loop__Variable n1 n2 n3 TO n4 BY n5 n6 TO n7

.in +4
The loop specified in this example will execute for the following
values of the index :
.nf
        n1
        n2
        n3, n3 + n5, n3 + 2 n5, n3 + 3 n5, ... , n4
        n6, n6 + 1, n6 + 2, ... , n7
.fi
(assuming that n4-n3 is a multiple of n5, n7-n6 an integer). 
.in -4

Loop variables are undefined outside the loop, and must not be previously
defined. Here, the loop variables are Double Precision numbers,
and non-integer start, end, and step can be used. Invalid
ranges are ignored at execution time: e.g. in the previous example,
the loop would not be executed for n3 TO n4 BY n5 if n5*(n4-n3) < 0,
but no error is signaled. Increments of 0 produce an error. The index
of the loop will be substituted to the loop variable Loop__Variable
during loop execution.

.ti -4
2 /IN
.ti +4
[SIC_\]FOR Loop__Variable /IN List__Variable 

Execute a generalized loop, for all the values in List__Variable. 
List__Variable is a 1-D (or scalar) variable 
of any type,  i.e. numerics, logicals, or character strings.
The
loop variable is undefined outside the loop, and must not be
previously defined. It will be implicitly defined as a scalar with the
same type and kind as the List__Variable. For example:
.nf
        DEFINE CHARACTER*8 files[3]
        LET files "a.txt" "b.txt" "c.txt"
        FOR f /IN files
          SAY 'f'
        NEXT f
.fi
The loop executes with the Loop__Variable
taking the value of each element of the List__Variable, in order.

.ti -4
2 /WHILE
.ti +4
[SIC_\]FOR /WHILE Logical__Expression

Conditional loops execute until the logical expression becomes false.
For example FOR /WHILE .TRUE. will execute forever.

Such loops have no associated loop variable.

.\"====================================================================
.ti -4
1 HELP
.ti +4
[SIC_\]HELP [FUNCTION|TASK|RUN|GO] [Topic [Subtopic|*]]

Display the help of various Gildas tools. There may be two levels of
help available. In this case, a wildcard will display all the subtopic
helps at once. You can use the switch SIC HELP to customize the way
long helps are displayed (see HELP SIC HELP).

.in +2
.ti -2
HELP
.br
Without an argument, HELP gives the list of available languages and
commands.

.ti -2
HELP LangName\
.br
With a language name followed by a backslash (e.g. HELP SIC\), HELP
gives a one line description of all commands specific to this
language.

.ti -2
HELP Command [Subtopic]
.br
With a command name, the help for this command is
displayed. Ambiguities can be fixed by prefixing the command by its
parent language (e.g. HELP SIC\DEFINE). A subtopic (e.g. an option
name) can be given as second argument.

Subtopics which appear in capital letters when listed by HELP Command
are not case-sensitive, while Subtopics appearing in mixed-cases are 
case-sensitive.

.ti -2
HELP FUNCTION [Name]
.br
With the keyword FUNCTION alone, it gives a list of all functions
available. With a function name added, it gives a detailed help for
this function. There are 3 kind of functions: 1) functions with native
support in the SIC interpreter, 2) program-defined functions (specific
to each program), 3) user-defined functions (defined with DEFINE
FUNCTION).

.ti -2
HELP TASK [Group|?]
.br
With the keyword TASK, it gives a one line description of all
available tasks. A task group name can be given as second to restrict
the list to this group. Type HELP TASK ? for the list of available
groups.

.ti -2
HELP RUN TaskName [VarName]
.br
With the keyword RUN followed by a task name, the help for this task
is displayed.

.ti -2
HELP GO ProcName [Subtopic]
.br
With the keyword GO followed by a procedure name (lower case
sensitive), the help for this procedure is displayed.

.ti -2
HELP SIC SYNTAX
.br
Get some basic help on the SIC interpreter syntax.
.in -2
.\"====================================================================
.ti -4
1 IF
.ti +4
[SIC_\]IF Logical__Expression [THEN]
.ti +4
[SIC_\]IF Logical__Expression Command [Arguments]

The first form starts a conditional IF block. The behaviour of IF
blocks is similar to structured Fortran. The THEN keyword is optional.
.br
The second form defines a logical IF statement, i.e. it uses a single
line with no possibility of alternate execution (no ELSE choice). When
the argument following the logical expression is not THEN, it is
assumed to be a command which will be interpreted, together with the
next arguments, if the logical expression evaluates as true.

This command can only be used within a procedure: interactive users
are expected to be able to make their decisions themselves.

The logical expression must be a single argument (no blanks);
composite expressions using .AND. or .OR. operators are
supported. Logical functions like EXIST, FILE, or FUNCTION can also be
used (see HELP FUNCTION for details).
.\"====================================================================
.ti -4
1 IMPORT
.ti +4
[SIC_\]IMPORT Package

Dynamically import a package (i.e. load its languages and perform its
initialization) in current scope. This allows to load another package
without closing (and loosing) the current session.

This feature is currently only available for: ASTRO, CLASS and
MAPPING.
.\"====================================================================
.ti -4
1 LET
.ti +4
[SIC_\]LET Variable [=] [Expression]
.ti +4
[SIC_\]LET Variable [=] Expression /CHOICE Value__1 ... Value__n
.ti +4
[SIC_\]LET Variable [=] Expression /FILE Filter
.ti +4
[SIC_\]LET Variable [=] Expression /FORMAT format__string
.ti +4
[SIC_\]LET Variable [=] Expression /FORMULA
.ti +4
[SIC_\]LET Variable [=] Expression /INDEX Value__1 ... Value__n
.ti +4
[SIC_\]LET Variable [=] Expression /LOWER
.ti +4
[SIC_\]LET Variable [=] Expression /NEW Type [Attr]
.ti +4
[SIC_\]LET Variable [=] Expression /PROMPT "Explanatory text"
.ti +4
[SIC_\]LET Variable [=] Expression /RANGE Min Max
.ti +4
[SIC_\]LET Variable [=] OldVariable /REPLACE
.ti +4
[SIC_\]LET Variable [=] Value__1 ... Value__n /RESIZE
.ti +4
[SIC_\]LET Variable [=] Expression /SEXAGESIMAL
.ti +4
[SIC_\]LET Variable [=] Val1 ... ValN /RESIZE
.ti +4
[SIC_\]LET Variable /STATUS Read|Write
.ti +4
[SIC_\]LET Variable [=] Expression /UPPER
.ti +4
[SIC_\]LET Variable [=] Expression /WHERE Condition__mask

Assign a value to a variable. The variable must already be defined
(see HELP DEFINE) unless the /NEW option is present. Logical expression
results cannot be assigned to non logical variables, and vice
versa. All numerical expression evaluations are done in double
precision, and automatically converted to the type of (numerical)
variable assigned.

The equal sign may be always omitted EXCEPT when using Free Syntax
(see HELP LET Free__Syntax).

If no value is assigned to the Variable, the user will be prompted for
the variable value. The Prompt text can be defined with the /PROMPT
Option.

VECTOR OPERATION:

Operations are vectorial, i.e. a full array is computed at the same
time. The variable name can define a subset of an known array, such
as:
.nf
    DEFINE REAL A[4,5,6] B[4]
    LET A[,,3]  = 1.0  ! or equivalently  LET A[3] = 1.0
    LET A[,2,2] = B    ! or equivalently  LET A[2,2] = B
.fi
These commands assign the value 1.0 to A[i,j,3], with i running from 1
to 4 and j from 1 to 5, and B[k] to A[k,2,2] for k from 1 to 4.
Implicit transposition is now allowed, though still somewhat
experimental: both A[,2,3] and A[2,,3] are valid. A range of indexes
can be specified rather than one index: for the above example A[3:5]
is a valid 4x5x3 array, A[2:4,,] is a 3x5x6 array.

IMPLICIT LOOPS:

In addition to vector computing, it is possible to assign an array
using "implicit loops" with implicit (undeclared) integer variables,
i.e. functions of the array indices such as
.nf
    DEFINE REAL A[4,5]
    LET A[I,J] = (I-J)**2
.fi
A few rules apply:
.in +2
.ti -2
- In the assigned array (left-hand side argument), the implicit
variables can only appear as indices. They cannot be mixed with
explicit index values. For example in the LET A[I,J] assignment, if
I was defined with DEFINE INTEGER I (i.e. an explicit variable),
then J can not be implicit.
.ti -2
- In the evaluated expression (right-hand side argument), the
implicit variables can only appear as variables, not indices (e.g.
LET A[I,J] B[I] is invalid). They can be omitted if relevant (e.g.
LET A[I,J] I**2 with no use of J).
.in -2

CONDITION MASK (/WHERE option):

Vector assignment can be done only where a specified logical array (or
logical array expression) is true, using the /WHERE option. See HELP
LET /WHERE.

.ti -4
2 Free__Syntax
.ti +4

The LET command may be omitted if no option is present, and if the SIC 
syntax is set to FREE. In this case, the = sign is mandatory. 
In FIXED syntax, the LET command is compulsory, but the = sign
optional. In FREE syntax, commands lines like
.nf
       A[I,J] = SIN((2*I+J)/PI)
.fi
where A is a known variable, are recognized as assignement and
automatically expanded to the equivalent FIXED syntax
.nf
       LET A[I,J] SIN((2*I+J)/PI)
.fi
In case  of conflict between a variable name and a (complete) command 
name, an error message is issued. Free syntax cannot be used for the 
LET_ /WHERE command. Command SIC SYNTAX [Free|Fixed] can be used to 
toggle between Fixed and Free syntax if needed.

.ti -4
2 GUI__Widget
.ti +4
GUI (Graphic-User-Interface) input mode:

If command GUI_\PANEL has been issued before, the LET command defines
widgets in the master window defined by GUI_\PANEL. The widget is a
simple prompt when option /PROMPT is set, a slider if option /RANGE is
present, a list of choices if option /CHOICE or /INDEX is given, and a
selection of files with the specified filter when option /FILE is
specified. If neither of these options is present, the LET command
works in the usual way.

The widgets are created and activated by command GUI_\GO. Standard
input can be used, and pressing button GO will define all the
variables as specified. If button ABORT is pressed instead, none of
the variables are modified and an error is returned. Error handling is
available.

Options related to the GUI Widget mode are:
/CHOICE,  /FILE, /FORMULA, /INDEX, /PROMPT and /RANGE

.ti -4 
2 Structure
.ti +4
LET OutStructure% [=] InStructure%

Assign, in as much as possible, a structure to another one.
The structures do not need to be identical: only matching structure
elements are copied.  

In addition, the DATA area of Structures
are ignored in this process: if needed, they must be copied
separately, e.g.
.ti +4  
  OutStructure%DATA = InStructure%DATA
.ti -4
  
.\"--------------------------------------------------------------------
.ti -4
2 /CHOICE
.ti +4
[SIC_\]LET Variable [= Expression] /CHOICE Val1 ... ValN [*] [/PROMPT "Prompt Text]
.ti +4
[SIC_\]LET Variable [= Expression] /CHOICE List [/PROMPT "Prompt Text]
.ti +4
[SIC_\]LET Variable = Expression  /CHOICE [/PROMPT "Prompt Text]
.ti +12
(GUI input mode)

Activate a choice widget which will return a value among the specified
list. The widget will be created by command GUI_\GO. This option
is usually combined with a /PROMPT option. If the last
specified value is an asterisk, the choice widget will be editable and
any value will be valid.

The choice list can also be given as a character array variable.

If the /CHOICE has no argument, the Variable will be displayed, but
cannot be modified. This mode can be useful to display control 
parameters in a menu, or variables which result from operations
with other variables.

.\"--------------------------------------------------------------------
.ti -4
2 /FILE
.ti +4
[SIC_\]LET Variable [= Expression] /FILE Filter [/PROMPT "Prompt Text]
.ti +12
(GUI input mode)

Activate a "file" widget to select a file according to the specified
filter. The widget will be created by command GUI_\GO. This option
is usually combined with a /PROMPT option.
.\"--------------------------------------------------------------------
.ti -4
2 /FORMAT
.ti +4
[SIC_\]LET Variable [=] Expression /FORMAT format__string

Use the specified format to convert the expression into a character
string and assign it to the requested (character) variable. For
example:
.nf
  define character c*6
  LET C acos(-1.0) /FORMAT F6.3
  exa c
  c = 3.142
.fi
.\"--------------------------------------------------------------------
.ti -4
2 /FORMULA
.ti +4
[SIC_\]LET Variable [=] Expression /FORMULA [/other__option]
.ti +12
(GUI input mode)

Use Expression as a formula in GUI input mode, rather than only the
value of the expression. This option can be combined with any
other GUI related option, in particular /PROMPT. 
.\"--------------------------------------------------------------------
.ti -4
2 /INDEX
.ti +4
[SIC_\]LET Variable [= Expression] /INDEX Text__1 Text__2 ... Text__n
.ti +12
(GUI input mode)

Activate a choice widget which will return an integer value
corresponding to the index of the selected text among the specified
list. The widget will be created by command GUI_\GO.
.\"--------------------------------------------------------------------
.ti -4
2 /LOWER
.ti +4
[SIC_\]LET Variable [=] Expression /LOWER

Convert the output to lower case prior to assignment. To convert a
variable, use e.g. for variable C
.br
   let c 'c' /lower
.\"--------------------------------------------------------------------
.ti -4
2 /NEW
.ti +4
[SIC_\]LET Variable [=] Expression /NEW Type [Attr]

Define the variable and assign it at the same time. Type is the type
of the variable (INTEGER, REAL, DOUBLE, LOGICAL, or
CHARACTER). INTEGER stands for SHORT or LONG integer depending on the
current SIC INTEGER rule.

The optional Attr argument is used to specify whether the newly
created variable is LOCAL (default) or GLOBAL. See also the
SIC_\DEFINE command.
.\"--------------------------------------------------------------------
.ti -4
2 /PROMPT
.ti +4
[SIC_\]LET Variable [=] [Expression] /PROMPT "Explanatory text"
.ti +12
(GUI input mode and Command line mode)

Create a text widget, with a specified prompt, to return a value or
valid expression for the variable. The text widget can be pre-loaded
with an expression or value(s). Standard input will be available once
the widget is created by command GUI_\GO.
.\"--------------------------------------------------------------------
.ti -4
2 /RANGE
.ti +4
[SIC_\]LET Variable [=] [Expression] /RANGE Min Max
.ti +12
(GUI input mode)

Activate a slider widget to return a value within the specified range.
The widget will be created by command GUI_\GO.
.\"--------------------------------------------------------------------
.ti -4
2 /REPLACE
.ti +4
[SIC_\]LET NewVariable [=] OldVariable /REPLACE

Rename OldVariable into NewVariable. The content and location of the
variable remains unchanged: only the name is modified. If the variable
is a structure, its elements are renamed accordingly.
.\"--------------------------------------------------------------------
.ti -4
2 /RESIZE
.ti +4
[SIC_\]LET Variable [=] Val1 ... ValN /RESIZE

Automatically resize the variable according to the number of values to
be stored in the output variable. For example:
.nf
    SIC> define integer a[2]
    SIC> let a 1 2 3 /resize
    W-LET,  Resizing array A to length 3
    SIC> exa a
    A               is an integer Array     of dimensions  3
                1            2            3
.fi

This feature makes sense when the array size is not known at the time
the procedure in written, but have to be decided instead from
unpredictable inputs at run time (e.g. user input in widgets). It
applies (only) to 1D arrays of any kind (numeric, logical,
character). The type, kind, rank and level (global/local) of the
output variable is not modified during the process. Read-only and
program-defined variables can not be resized.
.\"--------------------------------------------------------------------
.ti -4
2 /SEXAGESIMAL
.ti +4
[SIC_\]LET Numeric [=] [+|-]DD[:MM[:SS.SS]] /SEXAGESIMAL [D|H|R] [D|H]
.ti +4
[SIC_\]LET String [=] Value /SEXAGESIMAL [D|H] [D|H|R]

The /SEXAGESIMAL option allows to use sexagesimal expressions in
assignments. This option is only valid for scalar variables. Units of
the operands can be provided by optional characters chosen in
D)egrees, H)ours or R)adian. The first unit is for the output, the
second for the input. Radian is an invalid unit for the sexagesimal
string. Degrees are assumed by default for both operands.

The first form converts the sexagesimal expression into a numerical
value stored in the assigned variable. Mathematical expressions can be
used for each elements, provided they are separated by a semicolon.

The second form converts a numerical value into the sexagesimal
notation stored in the assigned character variable.
.\"--------------------------------------------------------------------
.ti -4
2 /STATUS
.ti +4
[SIC_\]LET Variable /STATUS Read|Write

Modify a variable status to/from ReadOnly from/to Writeable.
.\"--------------------------------------------------------------------
.ti -4
2 /UPPER
.ti +4
[SIC_\]LET Variable [=] Expression /UPPER

Convert the output to upper case prior to assignment. To convert a
variable, use e.g. for variable C
.br
   let c 'c' /upper
.\"--------------------------------------------------------------------
.ti -4
2 /WHERE
.ti +4
[SIC_\]LET Variable = Expression /WHERE Condition__mask

The LET command allows setting variables only where a given condition
mask is .TRUE.. The condition mask can be a logical array or a logical
expression (of same dimension as the result variable). Implicit loops
can be used in conjunction to the /WHERE option.

For example
.nf
   DEFINE REAL A[4,5] B[4,5]
   LET B[I,J] = I+J
   LET A[I,J] = (I-J)**2 /WHERE COS(I).GT.SIN(J)  ! 1
   LET A[I,J] = SIN(I+J) /WHERE B.GT.5            ! 2
.fi
is equivalent (in terms of results, but about 500 times faster) to the
loops
.nf
   DEFINE REAL A[4,5] B[4,5]
   LET B[I,J] = I+J
! 1
   FOR J 1 to 5
     FOR I 1 to 4
       IF (COS(I).GT.SIN(J)) THEN
         LET A[I,J] = (I-J)**2
       ENDIF
     NEXT
   NEXT
! 2
   FOR J 1 to 5
     FOR I 1 to 4
       IF (B[I,J].GT.5) THEN
         LET A[I,J] = SIN(I+J)
       ENDIF
     NEXT
   NEXT
.fi

Note in the example above that implicit variables can be used.
However, the following syntax is non valid,
.nf
   LET A[I,J] = SIN(I+J) /WHERE B[I,J].GT.5
.fi
because implicit variables cannot appear as indexes to an operand
array (B), but only as indexes to the result array (A) or as variables
as in SIN(I+J). The correct syntax would be
.nf
   LET A[I,J] = SIN(I+J) /WHERE B.GT.5
.fi
The following syntax is also non valid
.nf
   LET A = B /WHERE B[I,J].GT.LOG(I+J)
.fi
because implicit variables cannot be defined by an operand array (B),
but only by the result array. The correct syntax would be
.nf
   LET A[I,J] = B /WHERE B.GT.LOG(I+J)
.fi
.\"====================================================================
.ti -4
1 MESSAGE
.ti +4
[SIC_\]MESSAGE Severity ProcedureName "Message"
.ti +4
[SIC_\]MESSAGE Severity ProcedureName Arg1 Arg2 ... ArgN [/FORMAT Fmt1
Fmt2 ... FmtN]

Print a message using the same mechanism as the one used by Gildas
programs. In particular, it will be printed or not, to the terminal
and/or to the message file, depending on the filters that currently
apply to messages.
.br
.in +2
.ti -2
-_ The severity must be a single letter from one of the following:
F)atal, E)rror, W)arning, R)esult, I)nfo, D)ebug, T)race, C)ommand,
U)nknown.
.ti -2
- The procedure name is a free character string.
.ti -2
- The message must have at least one component. Multiple remaining
arguments will be printed out spaced by a single space. Enclose with
double-quote a character string if you want to use more than one
space.
.ti -2
- If /FORMAT option is invoked, each argument is displayed using its
associated format. Formats are Fortran ones (so may be slightly
machine-dependent) like a10, i2, f5.2 and so on.
.in -2

Example:
.nf
SIC> MESSAGE I FOO "Hello world!"
I-FOO,  Hello world!
.fi

For more information on message filters, see the HELP for the
SIC_ MESSAGE command.
.\"====================================================================
.ti -4
1 MFIT
.ti +4
[SIC_\]MFIT Yvar=Func(Xvar,&A,&B,...) [/START_ A1 B1 ...] [/STEP A2 B2 ...]
[/EPSILON e] [/WEIGHTS w] [/METHOD m] [/QUIET]
.ti +8
or
.ti +4
[SIC_\]MFIT Filename [/START_ A1 B1 ...] [/STEP_ A2 B2 ...] [/EPSILON e]
[/WEIGHTS w] [/METHOD m] [/QUIET]

Perform a least squares fit using the specified Method. The least
square fit tries to adjust function Func of variable Xvar and
parameters &A, &B, ... to match variable Yvar.

Any function or combination of functions known by SIC may be
used. Blanks are supported in the formula. The '=' sign is required.

Fit parameter DUMMY names are &A...&Z . Already defined SIC variables
may be used in the formula as long as they don't match the variables
used by MFIT. The resulting parameters will be stored in the structure
variable MFIT%.  An array with weights may be given by option
/WEIGHTS. It must match the dimension of the formula result (defaulted
to uniform weight).

The formula can also be provided by a disk file (default
extension .GRF), where lines beginning with an exclamation mark are
treated as comments. Inside the file, blanks can be used in the
formula, which may be spread over several lines.

The command MFIT defines the following global SIC variables to hold
its results:
.nf
    MFIT%PAR    : Fit parameters
    MFIT%ERRORS : The parameter errors, if they have been computed
    MFIT%MATH   : Text string containing the formula with replaced dummies
    MFIT%FIT    : Found approximation (the application of MFIT%MATH)
    MFIT%RES    : Residuals  (i.e. Yvar-MFIT%FIT)
    MFIT%STATUS : .FALSE. on successful completion.
.fi

Suppose you read X,Y=f(X) and Z (errorbar on Y) in the 3 arrays X, Y
and Z.  You could change Z into weights (for example SIC\LET Z 1|Z^2
), then fit a cubic polynomial regression in variables X,Y by typing:
.ti +4
MFIT Y=(&A*X^3+&B*X^2+&C*X+&D) /WEIGHTS Z
.br
The MFIT command will print the used formula:
.ti +4
I-MFIT,  Formula (stored in variable MFIT%MATH) :
.ti +4
(MFIT%PAR[01]*X^3+MFIT%PAR[02]*X^2+MFIT%PAR[03]*X+MFIT%PAR[04])
.br
The array MFIT%PAR will contain MFIT%PAR[1]=value of '&A', and so
on... to be used afterwards.
.\"--------------------------------------------------------------------
.ti -4
2 /EPSILON
.ti +4

This option is used to specify the desired tolerance. Its
interpretation is method dependent. For SIMPLEX and POWELL, it means
the relative deviation of the mean squared difference of two fit
iterations. For SLATEC, which uses non-reduced chi-2, it is the
absolute difference between two iterations. For ANNEAL, its
interpretation is totally different.

Use default value 0 to let the program guess. In subtle cases, or to
gain speed in case a coarse result is desired, use values around 1D-5
for SIMPLEX and POWELL, and of order 1 for SLATEC. For ANNEAL, see
details in the /METHOD option.

Note that this is not the absolute error of the fit parameters.
.\"--------------------------------------------------------------------
.ti -4
2 /METHOD
.ti +4
.in +4
.ti -2
ANNEAL_ _ Simulated annealing technique. This may require a very large
number of function evaluation.
.ti -2
POWELL_ _ Gradient using the Powell method (see Press et al. for
details).
.ti -2
SIMPLEX_ Classical Simplex amoeba search
.ti -2
ROBUST_ _ A combination of Simplex + Slatec, to be used with large
initial steps.
.ti -2
SLATEC_ _ Modified Levenberg Marquardt method with adaptive steps, as
implement in the Slatec library.
.in -4

All methods require a proper choice of initial values and steps. The
ANNEAL method is much more robust against poor guesses, but may
require 10 to 100 times more function evaluations than any other.
.\"--------------------------------------------------------------------
.ti -4
2 /QUIET
.ti +4

Require MFIT to be silent (useful to avoid too many messages in
loops).
.\"--------------------------------------------------------------------
.ti -4
2 /START
.ti +4
  [SIC_\]MFIT Y=f(X,&a,...) /START A1 B1 ...

A1 B1 ... are used to pass
starting guesses for the parameters &A &B (defaulted to 1.0). The
starting values should not be too far from a potential solution,
otherwise the convergence may not be possible.
.\"--------------------------------------------------------------------
.ti -4
2 /STEP
.ti +4
  [SIC_\]MFIT Y=f(X,&a,...) /STEP A2 B2 ...

A2 B2 ... are used to pass the unity vectors (steps) for the iteration
on parameters &A &B (defaulted to 0.25). Poor choice of initial steps
may lead to non convergence. Too small steps will not help converging
when one starts too far from the solution. Too large steps may lead to
incorrect evaluation of the parameter errors. The optimal step for the
determination of the errors is about the error bar, so that all
parameters become dimensionless.
.\"====================================================================
.ti -4
1 MODIFY
.ti +4
[SIC_\]MODIFY VarName|GDFName [/FREQUENCY Linename RestFreq]
[/VELOCITY Velocity] [/SPECUNIT FREQUENCY|VELOCITY]

Modify consistently the spectroscopic axis of a lmv cube or a Sic
structure of type IMAGE, HEADER, or UVTABLE.

The spectroscopic axis can be changed to the alternate unit with the
option /SPECUNIT. By default, the unit is unchanged.
.\"====================================================================
.ti -4
1 NEXT
.ti +4
[SIC_\]NEXT

Depending on the context, NEXT has one of two possible
interpretations:
.in +4
.ti -2
-_ If typed during loop definition, NEXT indicates the end of the
definition and starts the execution.
.ti -2
-_ If encountered during loop execution, NEXT will skip all
instructions remaining in the Loop Buffer and resumes the Loop
execution at its first line for the next value of the index. This
typically occurs as an error recovery (ON ERROR NEXT).
.in -4
The commands will be echoed to the terminal if the VERIFY switch is
ON.
.\"====================================================================
.ti -4
1 ON
.ti +4
[SIC_\]ON Status [Command]

Perform the Command when Status in encoutered. Only the ON_ ERROR case
is available. See subtopic ERROR for details.
.\"--------------------------------------------------------------------
.ti -4
2 ERROR
.ti +4
[SIC_\]ON ERROR [Command]

This command changes the current error recovery action.

By default, a PAUSE is automatically generated by any error during
execution. Without argument, ON ERROR resets to this default. Use the
SIC command (without argument) to display the current ON ERROR status.

The error recovery can be changed and any other valid command line
Command can be activated instead of PAUSE when an error occurs, using
the command ON ERROR Command. A very useful error recovery command for
loops is NEXT, which enables skipping the remaining commands of the
loop when something went wrong, and resumes the loop at for the
following index value.

Note that the ON ERROR command does not affect the behaviour on <^C_>
trapping, which always returns a PAUSE. The ON_ ERROR command is only
valid within the procedure which declared it.
.\"====================================================================
.ti -4
1 PARSE
.ti +4
[SIC_\]PARSE [/OptionName1 [Nargmin [Nargmax]]] ... [/OptionNameN ...]

Parse the array PRO%ARG in order to mimic the options mechanism
provided by a standard command.

When a procedure is executed, the array PRO%ARG is filled with the
arguments passed to the procedure. If you invoke the command PARSE
with some option names and required number of arguments, it will parse
the arguments to gather them by options and option arguments into the
structure PRO%PARSE%. The command PARSE will check that the caller has
provided known options and correct number of arguments, else an error
will be raised.

For example, if you invoke your procedure like this:

.nf
    SIC> @ myprocedure 123 /MYOPTION "ABC"
.fi

the PRO%ARG array will contain
.nf
    SIC__3> EXA PRO%ARG
    PRO%ARG    is a character*256 Array of dimensions 3
    123
    /MYOPTION
    ABC
.fi

Invoking the command PARSE in your procedure e.g.
.nf
    SIC__3> PARSE /MYOPTION /OTHEROPTION
.fi

will gather the command and the 2 option arguments like this:
.nf
    SIC__3> EXA PRO%PARSE%
    PRO%PARSE%                                    ! Structure GLOBAL
    PRO%PARSE%COMMAND                             ! Structure GLOBAL
    PRO%PARSE%COMMAND%NARG =            1         ! Integer GLOBAL RO
    PRO%PARSE%COMMAND%ARG is a character*256 Array of dimensions 1
    PRO%PARSE%MYOPTION                            ! Structure GLOBAL
    PRO%PARSE%MYOPTION%NARG =            1        ! Integer GLOBAL RO
    PRO%PARSE%MYOPTION%ARG is a character*256 Array of dimensions 1
    PRO%PARSE%OTHEROPTION                         ! Structure GLOBAL
    PRO%PARSE%OTHEROPTION%NARG =           -1     ! Integer GLOBAL RO
.fi

Namely: the command was passed 1 argument (available in the associated
ARG array), the option MYOPTION was passed 1 argument, and the option
OTHEROPTION was absent (NARG=-1). An option is present if NARG>=0.

You can control the number of required of arguments to the command and
the options. Syntax is "/OptionName [Nargmin [Nargmax]]". If Nargmax
is absent, it defaults to Nargmin. If Nargmin is absent, it means no
specific constraint. For example:

.nf
    SIC__3> PARSE 1 /MYOPTION 2 3 /OTHEROPTION
.fi

means that exactly 1 argument must be passed to the command (before
the options), that at least 2 and at most 3 arguments are required for
/MYOPTION, and that there is no check for /OTHEROPTION.
.\"====================================================================
.ti -4
1 PAUSE
.ti +4
[SIC_\]PAUSE "Message"

Set a break point in a Loop or a Macro. PAUSE returns control to user
when executed in a macro. The prompt is changed to indicate the
execution level. Any valid command can be executed while in interrupt
mode. The execution can be resumed by typing CONTINUE, aborted by QUIT
(or RETURN, depending whether an error status is desired). NEXT may
also be used for the Loop.

If PAUSE is followed by an argument, this argument is typed when the
pause occurs. When typed in interactive, PAUSE generates a traceback
of the levels of execution in SIC.

A pause is generated after completion of the current command if you
type <^C> on the keyboard. This allows you to interrupt any sequence
of commands (even if ON ERROR CONTINUE has been typed).
.\"====================================================================
.ti -4
1 PYTHON
.ti +4
[SIC_\]PYTHON
.ti +4
[SIC_\]PYTHON PythonCommandLine
.ti +4
[SIC_\]PYTHON PythonScript.py

Any form of the PYTHON command starts the Python interpreter and
intercommunication between SIC and Python at first call. Subsequent
call do not repeat this initialization step.

Three main interaction schemes are available:
.in +4
.ti -2
- Without argument, the user is exposed to the PYTHON prompt.

.ti -2
- With a Python command line as argument (any string following the
command), the command is transparently executed and the user recover
the SIC prompt. Arguments starting with a slash (/) should be
protected by double-quotes: this avoids SIC to interpret it as a
command option. Remember also that Python is case sensitive and the
string should take care of this. For example:
.nf
    SIC> PYTHON print "Hello world!"
    Hello world!
    SIC> PYTHON def f(x): return x*x
    SIC> PYTHON print f(2)
    4
    SIC>
.fi

.ti -2
- With a PythonScript.py as first argument (i.e. ending with ".py"),
the Python script is executed and then the user recover the SIC
prompt. Arguments following the script name can be recovered in the
sys.argv Python list. These arguments are interpreted by SIC before
being sent to the script. For example:
.nf
    SIC> TYPE show__args.py
    import sys
    for i in sys.argv:
      print i, type(i)
    SIC>
    SIC> PYTHON show__args.py PI 'PI' 1.234
    show_args.py <type 'str'>
    PI <type 'str'>
    3.1415926535898 <type 'str'>
    1.234 <type 'str'>
    SIC>
.fi
.in -4
.\"====================================================================
.ti -4
1 QUIT
.ti +4
[SIC_\]QUIT [ALL]

When typed after a pause, QUIT aborts the execution of the interrupted
level. QUIT returns an error to the previous level to signal this
anomalous end. The previous level is then also interrupted to allow a
complete error recovery. Note that this behaviour depends on the
ON_ ERROR command. QUIT can also be used to abort FOR-NEXT loop
compilation.

If argument ALL is present, all nested procedures are aborted, and SIC
goes back to base level.

In interactive sessions, QUIT should be used instead of BREAK and
RETURN because it allows extra decision at run time. QUIT used as the
error recovery command is equivalent to RETURN ERROR.
.\"====================================================================
.ti -4
1 RETURN
.ti +4
[SIC_\]RETURN [BASE|ERROR]

End a procedure execution, transmitting or not an error if argument
ERROR is present.

If argument BASE is present, RETURN will end all nested procedures,
and give back control to base level, without transmitting any error.
.\"====================================================================
.ti -4
1 SAY
.ti +4
[SIC_\]SAY ["Text"] ['Expression'] ['Variable'] [/FORMAT ...]
[/NOADVANCE]

Display strings or character variable or implicitly formatted
arithmetic (or logical) expressions in the shortest possible format,
unless the /FORMAT option is used.

.in +4
.ti -4
Simple text:
.br
Simple text can be displayed by passing double-quoted strings to the
command, e.g.
.nf
    SIC> say "Hello, world!"
    Hello, world!
.fi
An unquoted argument will also be displayed "as is", like a simple
string.

.ti -4
Variable:
.br
The contents of a scalar variable can be displayed by evaluating it
with single-quotes, e.g.
.nf
    SIC> say 'pi'
    3.1415926535898
.fi
Single quotes tell Sic to evaluate the variable and build a
representating string showing its contents. Then this string is passed
to SAY for display. Though Sic does its best to format the result, you
can customize the format with the option /FORMAT. Array variables can
not be displayed all at once using single quotes (but scalar subsets
can be evaluated e.g. SAY 'A[1]'), use SAY /FORMAT to display arrays.

.ti -4
Expression:
.br
Expressions can be evaluated using single quotes, e.g.
.nf
    SIC> say '2*pi'
    6.2831853071796
.fi
Like for variables, Sic evaluates the result and builds a
representative string passed to SAY for display. Here also, the result
must be scalar.

.ti -4
Multiple arguments:
.br
SAY can display as many strings as there are arguments to the
command. Remember that in Sic, arguments are separated by one or more
spaces. Each argument can be of any kind explained above. For example:
.nf
  SIC> say "PI ="   'pi'
  PI = 3.1415926535898
.fi
Note that the number spaces separating the input arguments are not
significant. In return, SAY will implicitely separate each string by
one blank.

.ti -4
Concatenated arguments:
.br
Arguments can be concatenated by gluing any of the 3 basic kinds
together. For example:
.nf
    SIC> say "("'pi'")"
    (3.1415926535898)
.fi
Note that there is no space between the components. In this case, Sic
does its best to evaluate each component and produce a single
temporary string concatenating all the individual
representations. Then this formatted string is passed to the command
SAY for display. Note that SAY sees only one argument (no blank = no
separator => one argument).
.br
This syntax is not specific to SAY: it is a Sic feature which can be
used in other commands. Be careful you have no control on the format
choosen by Sic at concatenation time: /FORMAT is useless as it would
affect only the single temporary string seen by SAY after formatting
by Sic.

.ti -4
Output:
.br
By default, SAY writes its output text on the terminal. However, it
can be redirected to a file thanks to the command SIC_\SIC OUTPUT (see
HELP for details)..

.ti -4
GUI mode:
.br
In GUI mode (see command GUI_\PANEL), SAY writes the text in the
current window. SAY without parameters inserts a separator.
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 /FORMAT
.ti +4
[SIC_\]SAY Arg1 Arg2 [... ArgN] /FORMAT fmt1 fmt2 [...fmtn]

where fmt1 applies to Arg1, and so on. The format used is a Fortran
format (so it may be slightly machine-dependent). Use formats like
a10, i2, f5.2, and so on. For example:
.nf
    SIC> say '2*pi' /format F4.2
    6.28
.fi
Be careful that each argument must be separated by blanks (see
"Multiple arguments" vs "Concatenated arguments" in the main HELP
SAY).

Formatting a scalar variable:
.in +4
Note also that the /FORMAT context, SAY is able to format a variable
without a pre-evaluation by Sic. For example:
.nf
    SIC> say pi
    pi
    SIC> say 'pi'
    3.1415926535898
    SIC> say pi /format F4.2
    3.14
    SIC> say 'pi' /format F4.2
    3.14
.fi
.in +3
.ti -3
1) In the first case, SAY considers unquoted arguments as simple
strings to be displayed "as is".
.ti -3
2) In the second case, using single-quotes, Sic translates the
variable contents to a text representation which is then given to SAY
(SAY is not aware that a floating point variable is involved here).
.ti -3
3) In the third case, a floating point format is requested: this is an
indication to SAY that the argument must be a numeric variable which
has to be converted in a specific way. Here SAY knows it is dealing
with a variable.
.ti -3
4) And finally, the last form should be avoided! The single-quotes are
a request to Sic to translate the variable to a string using its best
format (same as second case). Then this string is passed to SAY. As
the /FORMAT option is present, SAY re-interprets the ASCII string into
a floating-point value, and then this value is finally formatted to
its final representation. In other words, the following sequence
occured: read variable name -> get its floating-point value -> format
as ASCII string -> read as floating-point value -> format as ASCII
string. There are two useless steps, even if the result is correct as
Sic avoids precision loss when representing numeric values.
.in -3
.in -4

Formatting an array variable:
.in +4
If the argument is an array variable, the associated format is applied
repeatedly to all its individual values:
.nf
    SIC> define real a[4]
    SIC> let a 1.2 3.4 5.6 7.8
    SIC> say a /format f6.2
      1.20  3.40  5.60  7.80 
    SIC> say a /format 4(f6.2)  ! Equivalent
      1.20  3.40  5.60  7.80 
.fi
Note however that the format can be used to display array values
grouped per line, e.g.
.nf
    SIC> say a /format 2(f6.2)  ! Group 2 values per line
      1.20  3.40
      5.60  7.80 
.fi
.in -4

Mixture of explicit values, evaluated expressions, scalar, and array
variables:
.in +4
.nf
    SIC> define integer n
    SIC> let n 4
    SIC> define integer id[n]
    SIC> let id[i] i
    SIC> say "My interferometer has " n " antennas numbered" -
    SIC-? id " providing " 'n*(n-1)/2' " baselines." -
    SIC-? /format a i0 a i3 a i0 a
    My interferometer has 4 antennas numbered  1  2  3  4 providing 6 baselines. 
.fi
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 /NOADVANCE
. ti +4
[SIC_\]SAY Arg1 Arg2 [... ArgN] /FORMAT fmt1 fmt2 [...fmtn] /NOADVANCE

Do not put a Carriage Return at end. This allows to add several
variables on the same output line in subsequent SAY commands.
For example
.nf
  SAY Arg1 /Format fmt1 /NOADVANCE
  SAY Arg2 /Format fmt2
.fi
is equivalent to SAY Arg1 Arg2 /Format fmt1 fmt2

The /NOADVANCE option is only active with the /FORMAT option, and
if the output (defined by SIC OUTPUT) is not the terminal.
.\"====================================================================
.ti -4
1 SIC
.ti +4
[SIC_\]SIC Arg1 Arg2 [... ArgN]

The SIC command has 5 categories of actions:

(1) File System Handling actions: (HELP SIC FileSystem)
.br
These are used to manipulate files in a system independent ways from
SIC procedures.
.in +4
.br
APPEND COPY DELETE DIRECTORY FIND GREP MKDIR MODIFIED PARSE RENAME
.in -4
(2) Procedure related operations (HELP SIC Procedure)
.in +4
.br
EXPAND EXTENSION MACRO OUTPUT SAVE VERIFY WHICH
.in -4
(3) Customization and status  (HELP SIC Customize)
.in +4
.br
These are used to toggle some mode of the SIC monitor, or control some
SIC monitor parameter. When called with no further argument, the
status of the item will be displayed.
.br
EDIT ERROR HELP INTEGER LOGICAL MESSAGE PRECISION SYSTEM TIMER WINDOW
.in -4
(4) Command interpretation (HELP SIC Command)
.in +4
.br
Language_\ PRIORITY SYNTAX
.in -4
(5) Miscellaneous actions (HELP SIC Miscellaneous)
.in +4
.br
BEEP CPU DATE DEBUG DELAY FLUSH LOCK RANDOM__SEED USER UV WAIT
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 FileSystem

.ce
SIC File System handling commands

.in +4
.br
SIC APPEND File FileAppended
.br
SIC COPY FileOld FileNew
.br
SIC DELETE File
.br
SIC DIRECTORY Directory
.br
SIC FIND FileFilter
.br
SIC GREP String File
.br
SIC MKDIR New__Directory
.br
SIC MODIFIED FileName StrName
.br
SIC PARSE Filename Name [Ext [Dir]]
.br
SIC RENAME FileOld FileNew
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 Procedure

.ce
SIC Procedure related operations

.in +4
.br
SIC EXPAND Infilename Outfilename
.br
SIC EXTENSION MacroExtension
.br
SIC MACRO [ProcedurePath]
.br
SIC OUTPUT [File [NEW|APPEND]]
.br
SIC SAVE FileNew Command
.br
SIC VERIFY [ON|OFF|MACRO] [ON|OFF|STEP]
.br
SIC WHICH Procedure
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 Customize

.ce
SIC Customization commands

.in +4
.br
SIC EDIT [Editor[_&]]
.br
SIC ERROR
.br
SIC HELP [HelpMode]
.br
SIC INTEGER [SHORT|LONG]
.br
SIC LOGICAL [LogName [Translation]]
.br
SIC MESSAGE [Code]
.br
SIC PRECISION [Single|Double]
.br
SIC SYSTEM
.br
SIC TIMER [Value]
.br
SIC WINDOW [On|Off]
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 Command

.ce
Command interpretation rules

.in +4
.br
SIC Language_\ [Status]
.br
SIC PRIORITY [Level Language [...]]
.br
SIC SYNTAX [Fixed|Free]
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 Miscellaneous

.ce
SIC Miscellaneous operations and controls

.in +4
.br
SIC BEEP [N]
.br
SIC CPU
.br
SIC DATE
.br
SIC DEBUG Item
.br
SIC FLUSH
.br
SIC LOCK LockFile
.br
SIC RANDOM__SEED Value
.br
SIC USER
.br
SIC UV
.br
SIC WAIT Seconds
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 APPEND
.ti +4
[SIC_\]SIC APPEND FirstFile FileAppended

Append file "FirstFile" to file "FileAppended". It is equivalent to
Unix command
.ti +8
cat FirstFile >> FileAppended
.br
but system independent.

The error status on return is ruled by the switch SIC SYSTEM (see HELP
for details). The default is to raise an error if an error occurs
during the concatenation.
.\"--------------------------------------------------------------------
.ti -4
2 BEEP
.ti +4
[SIC_\]SIC BEEP [N]

Will beep 1 or N times.
.\"--------------------------------------------------------------------
.ti -4
2 CPU
.ti +4
[SIC_\]SIC CPU [VERBOSE]

Will return the User CPU and System CPU times in real variables USER
and SYSTEM resp. These variables are holded by two structures
SIC%CPU%RAW% and SIC%CPU%CUMUL% which record times since last and
first calls of SIC_ CPU resp. These structures also provide elapsed
time in variables ELAPSED.

If the extra argument VERBOSE is present, the CPU times are evaluated,
the Sic structures are filled (same as above), and additionally a
summary is printed to the terminal.
.\"--------------------------------------------------------------------
.ti -4
2 DATE
.ti +4
[SIC_\]SIC DATE

Will return the current date and time in symbol SYS__DATE.
.\"--------------------------------------------------------------------
.ti -4
2 DEBUG
.ti +4
[SIC_\]SIC DEBUG LUN [Number]
.ti +4
[SIC_\]SIC DEBUG IMAGE [Number]
.ti +4
[SIC_\]SIC DEBUG MEMALIGN
.ti +4
[SIC_\]SIC DEBUG MESSAGE
.ti +4
[SIC_\]SIC DEBUG GFORTRAN
.ti +4
[SIC_\]SIC DEBUG RESOURCES
.ti +4
[SIC_\]SIC DEBUG PYTHON
.ti +4
[SIC_\]SIC DEBUG VARIABLES
.ti +4
[SIC_\]SIC DEBUG LOCALE [Value]
.ti +4
[SIC_\]SIC DEBUG SYSTEM ON|OFF

Debugging command.

The first two keywords LUN and IMAGE print the status of reserved
Logical UNit numbers (LUN), or of allocated image slots (IMAGE).

The MEMALIGN keyword will check if dynamically allocated buffers are
aligned on 4, 8, 16 and 32 bytes. Some applications (e.g. FFTW3) are
more or less faster dependending on the buffer alignment in memory.

The MESSAGE keyword swaps ON or OFF the debugging mode for messages.
When turning it ON, all messages to both screen and message files are
enabled. In this case it is a shortcut of the commands:
.nf
   SIC MESSAGE GLOBAL ON
   SIC MESSAGE GLOBAL A=FEWRIDTCU
.fi
When turning it OFF, standard message filters (maybe customized by
user) are re-enabled. It is a shortcut of the command:
.nf
   SIC MESSAGE GLOBAL OFF
.fi
Default is debug mode turned OFF, unless a '-d' option has been
provided when invoking the Gildas executable.

The GFORTRAN keyword will check if the program is able to read and
write correctly Gildas binary files. Some versions of the Gfortran
compiler have an issue on this point, this command is intended to give
a clear status to the user.

The RESOURCES keyword will display current resource usage and limits
(memory, files, etc). See man pages for getrusage and getrlimit for
details (Linux only).

The PYTHON keyword will display the Python version which was used to
compile Gildas against the one used at run time. If they are
different, this probably means troubles.

The VARIABLES keyword will display a technical list of the variables
defined in Sic.

The LOCALE keyword, with no more argument, will display the current
LC__ALL locale and some of its details. The current locale can be
changed with an extra argument. Take care that Gildas is
English-speaking, e.g. decimal point should be ".". If not, you are in
trouble! It is wise to use the standard default, i.e. the "C" locale.

The SYSTEM keyword enables (argument ON) or disables (argument OFF) a
debugging message displayed when a system() call is
performed. system() calls are convenient and flexible to execute shell
commands, but under Linux they need to fork a sub-process, duplicating
temporarily the memory consumed by the current process. This may be a
limiting factor on many cases. Default is OFF, i.e. message are
disabled.
.\"--------------------------------------------------------------------
.ti -4
2 COPY
.ti +4
[SIC_\]SIC COPY FileOld FileNew
.ti +4
[SIC_\]SIC COPY File Directory

Copy FileOld to FileNew, or copy File to the named Directory. It is
equivalent to Unix command
.ti +8
cp FileOld FileNew
.br
but system independent.

The error status on return is ruled by the switch SIC SYSTEM (see HELP
for details). The default is to raise an error if an error occurs
during the copy.
.\"--------------------------------------------------------------------
.ti -4
2 DELAY
.ti +4
[SIC_\]SIC DELAY Seconds
.ti +4
[SIC_\]SIC DELAY

Delay the execution of commands. SIC DELAY is used in two times. The
first call is given a duration as argument. Added to the current date
and time, this defines a virtual milestone in the future. The next
call without argument will wait for this milestone if it has not been
reached yet, or will return without waiting if the limit is already
past. During the waiting time, CTRL-C can be used to exit the command.

An application of SIC DELAY is to slow down the execution of loops
which display or draw useful informations to the user. In the example
below, we ensure that the loops are executed every second (or more),
instead of depending on the CPU speed which varies over machines and
epochs:
.nf
   FOR I 1 to 10
     SIC DELAY 1.0
     Do something
     SIC DELAY
   NEXT
.fi
.\"--------------------------------------------------------------------
.ti -4
2 DELETE
.ti +4
[SIC_\]SIC DELETE File

Delete the specified file. It is equivalent to Unix command
.ti +8
rm File
.br
but system independent.
.\"--------------------------------------------------------------------
.ti -4
2 DIRECTORY
.ti +4
[SIC_\]SIC DIRECTORY Directory

Change the working directory to the specified name. It is equivalent
to Unix command
.ti +8
cd Directory
.br
but system independent.
.\"--------------------------------------------------------------------
.ti -4
2 EDIT
.ti +4
[SIC_\]SIC EDIT [ON|OFF|EditorName]

List or change the status of the command line editing mode, or the
default text editor used by command EDIT.
.\"--------------------------------------------------------------------
.ti -4
2 ERROR
.ti +4
[SIC_\]SIC ERROR

List the current error recovery command, defined by command ON ERROR.
.\"--------------------------------------------------------------------
.ti -4
2 EXPAND
.ti +4
[SIC_\]SIC EXPAND InFileName OutFileName

Add the language name before each command of the macro file InFileName
and write the results into the new macro file OutFileName. This
command should be used in a program where the InFileName macro does
not produce any command name ambiguity. The resulting macro file will
then be usable in any program.

The symbols are not touched because some procedures may need to
redefine symbols on the fly.

Right now the SIC commands are not transformed because it would cause
trouble to the procedure structure if some commands like FOR, IF,
etc... would be changed.
.\"--------------------------------------------------------------------
.ti -4
2 EXTENSION
.ti +4
[SIC_\]SIC EXTENSION [Extension1 ... ExtensionN]

Without arguments, print the list of extensions used by commands @ and
EDIT, with precedence given from the left to the right. Defaults are
program dependent: for all Gildas softwares, it is the program name,
while many user created applications use the generic default
extension ".pro".

With one or more arguments, add the input extension(s) at the
beginning of the list, i.e. with highest precedence. If extension was
already known, SIC_ EXTENSION also brings it back at the beginning.
.\"--------------------------------------------------------------------
.ti -4
2 FIND
.ti +4
[SIC_\]SIC FIND [FileFilter [Directory]]

Search for all files matching the specified FileFilter in the
specified Directory. Matching files are returned in a SIC structure
named DIR%. DIR%NFILE is the number of found files, and
DIR%FILE[1:DIR%NFILE] a character array containing the filenames.

The FileFilter can contain a directory name. In this case the returned
file names will include it. On the contrary, if the FileFilter does
not contain a directory name, and a "Directory" argument is specified,
the returned names will not contain the Directory name.

The default file filter is *.*
.\"--------------------------------------------------------------------
.ti -4
2 FLUSH
.ti +4
[SIC_\]SIC FLUSH

Flush message and log files buffers onto disk.
.\"--------------------------------------------------------------------
.ti -4
2 GREP
.ti +4
[SIC_\]SIC GREP String File

Parse line by line the named (ASCII) file and search if the string
appears in each line. The number of matching lines is saved in the
output variable GREP%N. The matching lines themselves are saved in the
array GREP%LINES; this array is defined only if GREP%N is non-zero.
.\"--------------------------------------------------------------------
.ti -4
2 HELP
.ti +4
[SIC_\]SIC HELP [PAGE|SCROLL|HTML]

With no argument, print how the HELP command behaves. Otherwise,
controls whether it outputs the text page by page (PAGE), or
continuously (SCROLL).

.in +4
.ti -2
-_ SIC_ HELP_ PAGE_ _ _ _ indicates the HELP command should display
page per page.
.ti -2
-_ SIC_ HELP_ SCROLL_ _ indicates the HELP command should display the
the help in continuuous scrolling mode.
.ti -2
-_ SIC_ HELP_ HTML_ _ _ _ _ indicates the HELP command should refer
the HTML version of the documentation and use the appropriate browser
to display it.
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 INTEGER
.ti +4
[SIC_\]SIC INTEGER [SHORT|LONG]

Define the default SIC integer kind (i.e. used by DEFINE
INTEGER). SHORT refers to Fortran's INTEGER*4 (with a limit value of
2**31-1) while LONG refers to INTEGER*8 (with a limit value of
2**63-1). Default is SHORT.

Without argument, the command displays the current default SIC integer
kind.
.\"--------------------------------------------------------------------
.ti -4
2 LANGUAGE
.ti +4
[SIC_\]SIC Language_\ [ON|OFF]

Place a language in the active scope, or removes it, or list its
status. Languages not in active scope are not searched for their
commands, unless the language name is explicitly given.
.\"--------------------------------------------------------------------
.ti -4
2 LOCK
.ti +4
[SIC_\]SIC LOCK [LockFile]

With no argument, display the list of lock files owned by the current
program session. With a file name as argument, create this file as a
lock file. Attempting to create a lock file which already exists is a
fatal error. Lock files owned by the current program session are
implicitely deleted when exiting.

This command is intended to protect some user's resources,
e.g. invoking it in a procedure ensures that this procedure can not be
run twice in the same or in another session.
.\"--------------------------------------------------------------------
.ti -4
2 LOGICAL
.ti +4
[SIC_\]SIC LOGICAL LogName Translation
.ti +4
[SIC_\]SIC LOGICAL LogName
.ti +4
[SIC_\]SIC LOGICAL [Pattern]

The first syntax sets or replaces a logical name.

SIC_ LOG_ LogName will give the translation of that precise logical
name.

Finally, SIC_ LOG Pattern will search for all logical names matching
the pattern. A wilcard '*' means 0 or more characters. Without second
argument the pattern '*' is used, i.e. it will list all the logical
names.
.\"--------------------------------------------------------------------
.ti -4
2 MACRO
.ti +4
[SIC_\]SIC MACRO MacroPath

Change the search path for the procedures. Procedures executed by @
are searched in a path specified by the special logical name
MACRO#DIR: . This command allows to list or change the content of
MACRO#DIR: .
.\"--------------------------------------------------------------------
.ti -4
2 MEMORY
.ti +4
[SIC_\]SIC MEMORY [ON|OFF]

Enable or disable automatic insertion of successful commands into the
stack.
.\"--------------------------------------------------------------------
.ti -4
2 MESSAGE
.ti +4
[SIC_\]SIC MESSAGE
.ti +4
[SIC_\]SIC MESSAGE Pack1 [[[S|L|A]-|=|+]F|E|W|R|I|D|T|C|U]
[PackN...]
.ti +4
[SIC_\]SIC MESSAGE Global [[[S|L|A]-|=|+]F|E|W|R|I|D|T|C|U] [ON|OFF]
.ti +4
[SIC_\]SIC MESSAGE * [[[S|L|A]-|=|+]F|E|W|R|I|D|T|C|U]
[PackN...]
.ti +4
[SIC_\]SIC MESSAGE /COLOR [Args]

The command SIC MESSAGE allows to customize the general verbosity of
all the GILDAS commands, or to customize the color of the messages
depending on their kinds (see HELP SIC /COLOR for details).

Modify and display the messaging filters for one or more
packages. Messages are usually printed on screen and into a message
file in the GAG__LOG: directory. Depending on its kind (from trace to
fatal errors), a message may be printed or not to one of these
outputs. Messaging filters allow the user to fine tune the kinds of
messages he wants to see. Filters are either global (i.e. all the
messages are filtered whathever the package they belong to) or
package-dependent (i.e. the messages are filtered depending on the
package they belong to).

The command SIC_ MESSAGE,
.in +4
.ti -2
-_ without argument, outputs the messaging filters for all active
packages;
.ti -2
-_ with one or more package name as arguments, displays the associated
filters, e.g. :
.in +4
.nf
GREG> SIC MESSAGE SIC GLOBAL
sic    on-screen  active   filter: FEWRI---U
sic    to-mesfile active   filter: FEWRIDTCU
global on-screen  inactive filter: FE-------
global to-mesfile inactive filter: FEWRIDTCU
.fi
.in -4
First column shows the package name, second column the output device,
third column the filter status, last column the associated filter;
.ti -2
-_ with a package name followed by a messaging rule (see below),
updates its the filter value and displays it. The filters of several
packages can be changed on the same command line, e.g. SIC MESSAGE SIC
S+D GREG L-W
.in -4

The package name can additionally have two special values:
.in +4
.ti -2
-_ *_ : all the package filters are modified according to a
single input rule;
.ti -2
-_ GLOBAL_ : set a global filter which can override all the package
filters without loosing them. This global behavior is activated and
deactivated by the ON or OFF keyword.
.in -4

A rule to change a filter is a single string composed of three parts,
from left to right:
.in +4
.ti -2
-_ A, S and/or L as first argument to modify All, Screen, or Logfile
filters. This must be unique but is optional, default is Screen only.
.ti -2
-_ +, - or = as second argument to add to, remove from, or redefine
filter values. This operator must be unique, and it is optional:
default is +.
.ti -2
-_ F, E, W, R, I, D, T, C and/or U as last argument(s) to modify the
filters on Fatal, Error, Warning, Result, Info, Debug, Trace, Command
and Unknown messages. This argument is mandatory, and the letters may
be associated.
.in -4

The message kinds are:
.in +4
.ti -2
F)atal: Program will cleanly end now because a fatal error occured,
e.g. a required initialization of the program could not occur or an
error can not be safely recovered or the program is in an unstable
status and can not go on.
.ti -2
E)rror: Command or action could not be executed to its end. Such
errors can be recovered, and program can continue to run safely.
.in +2
.ti -2
-_ It denotes an attempt to do something not allowed or not
implemented in the command.
.ti -2
-_ Command can not run to the end as it will not produce the expected
result.
.in -2
.ti -2
W)arning: Command or action will go on executing without an error, but
.in +2
.ti -2
- the user must be warned about a strange behavior;
.ti -2
- a result is produced, but user must be careful with its
interpretation.
.in -2
.ti -2
R)esult: Information directly requested by the user. It concerns all
the results returned by active commands. This should be understand as:
.ti +2
- "You asked for this, as a result, that happened"
.ti +2
- "This was created/changed accordingly to your request"
.ti +2
- "Here is what you asked for (some values,...) "
.ti -2
I)nfo: Additional information not directly expected by the user when
he runs the command. It gives secondary informations on current
actions, or it concerns more or less the result and the processes to
obtain it, but it is not the result itself.
.ti -2
D)ebug: High level debugging, e.g. follow the steps of complex
computation.  By default, it will not be printed. User can activate it
if strange non-fatal behavior occurs.
.ti -2
T)race: Low-level debugging, e.g. track the program execution.  By
default, it will not be printed. User must use it wisely because it
may produce thousands of messages in a row (for example, in
loops). User can activate it in case of unforeseen fatal behavior.
.ti -2
C)ommand: Each command typed on the terminal is resolved and can
printed back to terminal and to logfile. This is equivalent to the
obsolescent SIC_ VERIFY_ ON behavior.
.ti -2
U)nknow: It is reserved for the migration from the old message
facilities to the new one, and to handle internal errors in messaging
process.
.in -4

Simple examples:
.in +4
.nf
SIC> SIC MESSAGE
sic     on-screen  active   filter: FEWRI---U
sic     to-mesfile active   filter: FEWRIDTCU
SIC> SIC MESSAGE SIC GLOBAL
sic     on-screen  active   filter: FEWRI---U
sic     to-mesfile active   filter: FEWRIDTCU
global  on-screen  inactive filter: FE-------
global  to-mesfile inactive filter: FEWRIDTCU
SIC> SIC MESSAGE SIC S+D
sic     on-screen  active   filter: FEWRID--U
sic     to-mesfile active   filter: FEWRIDTCU
SIC> SIC MESSAGE SIC L-DT
sic     on-screen  active   filter: FEWRID--U
sic     to-mesfile active   filter: FEWRI--CU
SIC> SIC MESSAGE SIC A=FEWRI
sic     on-screen  active   filter: FEWRI----
sic     to-mesfile active   filter: FEWRI----
SIC> SIC MESSAGE GLOBAL ON
Turning ON global filtering rules
SIC>
.fi
.in -4

.in +3
.ti -3
Q:_ I've lost all messages, SIC_ MESSAGE is silent, what happens?
.ti -3
A:_ Many message kinds are certainly disabled, in particular Results
printed to Screen. This is why SIC_ MESSAGE is also silent. Consider
typing SIC_ MESSAGE_ SIC_ S+R and you should see back messaging
filters.
.in -3
.\"--------------------------------------------------------------------
.ti -4
2 /COLOR
.ti +4
[SIC_\]SIC MESSAGE /COLOR
.ti +4
[SIC_\]SIC MESSAGE /COLOR ON|OFF
.ti +4
[SIC_\]SIC MESSAGE /COLOR [kind1=color1] [kind2=color2] ...

Customize the message colors in the terminal depending on the message
kind.

Without argument, show the current color (if relevant) of all the
message kinds, and the available colors.

With ON or OFF as argument, enable or disable the message coloring.

With one or more arguments of the form "kind=color", customize the
color of the given message kind. Type SIC MESSAGE /COLOR without
argument to know the various message kinds and available colors. Use
color "NONE" to revert to the default terminal color. For example, the
default at startup is:
.nf
  SIC> SIC MESSAGE /COLOR F=RED E=RED W=ORANGE
.fi
.\"--------------------------------------------------------------------
.ti -4
2 MKDIR
.ti +4
[SIC_\]SIC MKDIR New__Directory

Create a new directory. It is equivalent to Unix command
.ti +8
mkdir -p New__Directory
.br
but system independent. No error is raised if the directory already
exists.
.\"--------------------------------------------------------------------
.ti -4
2 MODIFIED
.ti +4
[SIC_\]SIC MODIFIED FileName StrName

Check if a "file" was modified since last call, and fill the Sic
structure named "StrName" accordingly. The file can be a regular file
or a directory. If file is a symbolic link, evaluation is made on its
target. On first call, the structure is set up and the file is assumed
modified. On subsequent calls, file and calling dates are compared and
modification status is evaluated. In case of doubt (e.g. modification
time unchanged at the file system precision), a modification is
assumed.

The output structure has the following (scalar) components:
.in +2
- StrName%FILE: the file name (character string),
.br
- StrName%MTIME: the file modification time (long integer, in
  nanoseconds since 01-jan-1970),
.br
- StrName%PTIME: last time a modification was proved (long integer, in
  nanoseconds),
.br
- StrName%MODIF: file was (or may have been) modified or not since
  last call (logical)
.in -2
The structure must be a user-defined, global, variable. If the
structure or its elements are missing, they will be created at first
call.
.\"--------------------------------------------------------------------
.ti -4
2 OUTPUT
.ti +4
[SIC_\]SIC OUTPUT [?|FileName [NEW|APPEND]]

Redirect the output of the SIC_\SAY command to the specified file.

If NEW is passed after the file name, the file name is suffixed
(renamed) with a ~ if it was existing and a new empty file is
created. This is the default if this keyword is omitted.

If APPEND is passed after the file name, the file is reopened for
appending text at the end if it was existing before. Else, a new empty
file is created.

If ? is passed as file name, the command prints the current output
name (terminal or file name).

If no argument is present, any currently opened output file will be
closed, and the output of command SAY is re-directed to the terminal.
.\"--------------------------------------------------------------------
.ti -4
2 PARALLEL
.ti +4
[SIC_\]SIC PARALLEL [Nthread]

Check or set the number of threads for parallel executions. Nthread is
either an integer indicating the desired number of threads, or "*" to
use all the cores of the current machine.

The current and maximum number of threads are visible in variables
SIC%OPENMP%NTHREADS and SIC%OPENMP%MTHREADS respectively.

Only active when compiled with Open-MP mode.
.\"--------------------------------------------------------------------
.ti -4
2 PARSE
.ti +4
SIC PARSE Filename Name [Ext [Dir]]

Parse an input filename, and return the short Name, and optionally the
Extension and Directory into pre-defined SIC character variables.
.\"--------------------------------------------------------------------
.ti -4
2 PRECISION
.ti +4
[SIC_\]SIC PRECISION [SINGLE|REAL|DOUBLE|AUTO]

Select the precision of all computations using SIC variables.
Automatic precision will use the highest precision present in an
expression.
.\"--------------------------------------------------------------------
.ti -4
2 PRIORITY
.ti +4
[SIC_\]SIC PRIORITY [Level1 Lang1 ... [LevelI LangN ...]]

SIC_ PRIORITY redefines the languages precedence when an ambiguous
command (same name in several languages) is encountered: the lower the
precedence level, the higher the priority. By default, they are all
the same (level is set to 1), i.e. there is no automatic ambiguity
resolution.

The priority levels can be changed for one, some, or all
languages. LevelI is an integer, which must be followed by one or more
languages:
.in +7
.ti -5
>_ 0:_ the level value is used directly, the lower level the higher
priority,
.ti -5
=_ 0:_ the level value is Automatic, i.e. the priority comes after the
languages with an explicit positive value and before the ones with a
negative value,
.ti -5
<_ 0:_ set the priority from the end of the list, e.g. -1 means that
the language must have the lowest priority.
.in -7

Example:
.nf
  Level  Priority
   +1       1
   +2       2
   +4       3
    0       4
   -2       5
   -1       6
.fi
Note that the priority list is compressed if the values are
discontinued.

A call to SIC_ PRIORITY without arguments prints the current levels
for all languages.
.\"--------------------------------------------------------------------
.ti -4
2 RANDOM__SEED
.ti +4
[SIC_\]SIC RANDOM__SEED [DATETIME|URANDOM|Value]

This command resets the Fortran random seed used to initialize the
sequence of pseudorandom numbers returned by the functions RANDOM and
NOISE. Several arguments are allowed:
.in +4
.ti -2
-_ DATETIME: compute a seed based on current date and time. This is
portable but not highly random, e.g. 2 processes running at the same
time can end with the same seed.
.ti -2
-_ URANDOM: use the operating system special file /dev/urandom as a
random number generator, if available. This is the best choice but it
is not fully portable.
.ti -2
-_ Value: the user can specify its own seed (integer value). Reusing
the same value will ensure the same sequence of pseudorandom numbers
later on, which can be useful depending on the context.
.in -4
Note that this command affects the seed, i.e. the starting point of
the sequence of pseudo-random numbers. It does not affect the
randomness of those numbers (i.e. you can safely use the Value 1 if
you want).

The default at startup is DATETIME, i.e. the sequence will always be
different from one session to another. This default can be overriden
by setting the Sic logical GILDAS__RANDOM__SEED to DATETIME, URANDOM,
or an integer value in the file $HOME/.gag.dico

Without argument, the command displays the current Fortran random seed
in use. For debugging purpose.
.\"--------------------------------------------------------------------
.ti -4
2 RENAME
.ti +4
[SIC_\]SIC RENAME FileOld FileNew

Rename an existing file. It is equivalent to Unix command
.ti +8
mv FileOld FileNew
.br
but system independent.

.\"--------------------------------------------------------------------
.ti -4
2 SAVE
.ti +4
[SIC_\]SIC SAVE [FileName Symbol]

This is a specific command (currently) used by the ALMA simulator to copy
into an output file (a procedure) the name of any newly defined SIC variable,
prefixed by whatever Symbol is given here.

Without argument, just closes the current "save" file.

Can be used whenever you need to apply different actions to
the same set of variables, or get two sets of variables with similar
names (one prefixed, the other not) e.g. to store default values or
last values. Redefining the Symbol and executing the created
procedure will do the desired job on the list of variables defined
when SIC SAVE was active...

.nf
   sic save define__all TOTO
   define a Bunch Of Variables Here /global ! Only global stuff, though...
   sic save
   !
   symbol TOTO "EXA &1 "   ! Examine the Variable name
   @ gag__proc:define__all   ! for all variables in this list...
   !
   sic output init__all.sic
   symbol TOTO "@ sicvar__init"   ! Look into gag__pro:clone__var.sic
   @ gag__proc:define__all         ! for further explanation
   sic output
   @ init__all.sic                ! Initialize them
   !
   define structure CLONE% /global
   sic output clone__all.sic
   symbol TOTO "@ sicvar__clone CLONE% "   ! Will actually create a
   @ gag__proc:define__all         ! copy of all variables into structure CLONE%
   sic output
   symbol TOTO continue
   @ clone__all.sic                ! Duplicate them into CLONE% structure
.fi
.\"--------------------------------------------------------------------
.ti -4
2 SEARCH
.ti +4
[SIC_\]SIC SEARCH FileName

(Obsolescent).
.br
Search for the specified file, and set the logical SIC%EXIST to YES if
the file exists, NO if not.

This is an obsolescent feature. The same functionality is available
through the logical function FILE("FileName").
.\"--------------------------------------------------------------------
.ti -4
2 SYNTAX
.ti +4
  SYNTAX of SIC commands
.br
 and
.ti +4
[SIC_\]SIC SYNTAX [FIXED|FREE]

The SIC syntax is the following :
.ti +4
[LANG_\]COMM [Arg1 [Arg2 [...]]] [/OPT1 [p1 [...]] [/OPT2 [...]]
.br
where [] indicates optional fields.

Language, command and options can be abbreviated. The language field
(LANG_\) is optional but may help resolve ambiguities.

First, the line is stripped of duplicate separators (spaces or
tabs). Character strings (entities included between double quotes) are
not affected by this formatting.

Then symbols (entities included between simple quotes, plus the
language-command field) and tokens (macros parameters _&1 _&2 etc...)
are translated, even within character strings.

Finally, the line is analysed for ambiguities and the language,
command and option names are expanded. An option is a word beginning
by a slash (e.g. /OPT1 is an option in the above example).

All arguments can be character or mathematical variables or
expressions, depending on the type required by the program. Character
expressions can be concatenated with implicit formatting of variables
and mathematical expressions, such as in
.ti +4
"The real number PI is equal to "'ACOS(-1.0)'
.br
Variable and expressions are not evaluated during the parsing, but
only during the execution. Character variables must be included
between quotes for translation, e.g.
.nf
      DEFINE CHARACTER C*6
      LET C 3.14159
      DEFINE REAL A
      LET A 'C'/PI
      EXAMINE A
        A       =    0.9999705

.fi        
.ti +4
[SIC_\]SIC SYNTAX [FIXED|FREE]

controls the syntax for mathematic operations. In FIXED syntax, the
LET command is compulsory. In FREE syntax, commands lines like
.nf
       A[I,J] = SIN((2*I+J)/PI)
.fi
where A is a known variable, are recognized as assignement and
automatically expanded to the equivalent FIXED syntax
.nf
       LET A[I,J] SIN((2*I+J)/PI)
.fi
Free syntax cannot be used for the LET_ /WHERE command. 

.ti +4

.\"--------------------------------------------------------------------
.ti -4
2 SYSTEM
.ti +4
[SIC_\]SIC SYSTEM [ERROR|NOERROR]

Indicate if the commands SIC_\SYSTEM, SIC_\SIC COPY, and SIC_\SIC
APPEND can raise errors or not, i.e. if any error occuring when
executing the string command (SIC_\SYSTEM), or occuring when
copying/appending a file should stop the Sic execution flow. Default
is true. The current status is also available in the logical variable
SIC%SYSTEMERROR.
.\"--------------------------------------------------------------------
.ti -4
2 TIMER
.ti +4
[SIC_\]SIC TIMER [Time [HOURS|MINUTES|SECONDS]]

All Gildas programs can be automatically closed (normal exit) after a
defined period of inactivity at the prompt level. This period is
defined by the Sic timer. The timer is unset (i.e. no timer) by
default.

With a Time argument, set the timer to the input value. Unit is a
keyword which can be Hours, Minutes, or Seconds (default Hours). A
null or negative value disables the timer.

Without argument, display the current value of the timer.

The timer can be customized in a Sic logical named SIC__TIMER (integer
value, in hour unit). This value is evaluated once at startup from one
of the Sic logical dictionaries. Later changes are ignored.

See also the command SIC_\TIMER for advanced possibilities.
.\"--------------------------------------------------------------------
.ti -4
2 USER
.ti +4
[SIC_\]SIC USER

THIS COMMAND IS OBSOLESCENT. Use instead variables SIC%USER and
SIC%HOST defined at startup.

SIC USER will return the user name (usually with host name) in symbol
SYS__INFO.
.\"--------------------------------------------------------------------
.ti -4
2 UVT__VERSION
.ti +4
[SIC_\]SIC UVT__VERSION Version

[EXPERIMENTAL -- Reserved for developpers so far]

Select the UV Table version being used by SIC.  The Version can be
FREQUENCY,  DOPPLER or SYSTEM.  It affects the way the spectral axis
is interpreted to define spectral and spatial resolution.

FREQUENCY is the "old" historical behaviour, which is only suitable
for small field of views and number of channels.

DOPPPLER is suitable for large number of channels, but may be
limited to small field of views in case of data spanning several
observation dates

SYSTEM is more accurate, but requires an extra column in the
UV Tables to hold time dependent Doppler tracking.
.\"--------------------------------------------------------------------
.ti -4
2 VERIFY
.ti +4
[SIC_\]SIC VERIFY
.ti +4
[SIC_\]SIC VERIFY ON|OFF
.ti +4
[SIC_\]SIC VERIFY MACRO ON|OFF|STEP

Control the listing of macros, loop or stack during execution. Without
argument, SIC VERIFY shows its current status.

SIC VERIFY ON enables echoing each command in the terminal before
execution. This is mostly useful for debugging. Note that numerous
outputs in the terminal slow down considerably the procedure
execution. Default is OFF.

SIC VERIFY MACRO ON adds feedback in the terminal when entering and
leaving a procedure (procedure file name, number of arguments,
arguments). It also waits for the user to type <Return> before
starting the procedure execution. SIC VERIFY MACRO STEP adds feedback
in the terminal before executing each command (similar to SIC VERIFY
ON), but it also waits for the user to type <Return> before executing
the command. Default is OFF, i.e. no feedback is shown, and no need to
type <Return>.
.\"--------------------------------------------------------------------
.ti -4
2 VERSION
.ti +4
[SIC_\]SIC VERSION

Return the version number and credits or copyrights for the languages
or subprograms currently used.
.\"--------------------------------------------------------------------
.ti -4
2 WAIT
.ti +4
[SIC_\]SIC WAIT Seconds

Will wait for the required number of seconds. Fraction of seconds can
be specified.
.\"--------------------------------------------------------------------
.ti -4
2 WHICH
.ti +4
[SIC_\]SIC WHICH Procedure

Return the full path of the procedure or macro which will be executed
by "@_ Procedure" or "TYPE Procedure" calls.

See HELP_ @ for details on which directories procedures and macros are
searched in.
.\"--------------------------------------------------------------------
.ti -4
2 WINDOW
.ti +4
[SIC_\]SIC WINDOW [ON|OFF]

Allow or disallow use of GUI mode.
.\"====================================================================
.ti -4
1 SORT
.ti +4
[SIC_\]SORT KeyVar [Var1 [... VarN]]

Sort an ensemble of 1-D or 2-D SIC variables by increasing values of the
(1-D only) KeyVar variable. A standard use is to sort a complete GILDAS
table, using
.nf
  DEFINE TABLE A MyFile WRITE
  SORT A[3] A
  DELETE /VAR A
.fi
As shown in the example, the command handles the case where KeyVar is a
subset of any of the variables to be sorted. However, if there is aliasing
between any of the Var1 ... VarN variables, the result is unpredictable.

The command can be useful for further use of the COMPUTE LOCATION
command, or plots using GreG. To mimic the behaviour of the (obsolete)
GREG_\SORT command, use
.ti +4
    SIC_\SORT Key Var2 Var3
.br
where Key is any of X Y Z, and Var2 and Var3 the two other ones.
.\"====================================================================
.ti -4
1 SYMBOL
.ti +4
[SIC_\]SYMBOL [X ["Translation"]] [/INQUIRE "Prompt Text"]

This commands defines, lists and deletes symbols.

.ti +2
SYMBOL
.ti +4
Lists the Symbol table

.ti +2
SYMBOL_ X
.ti +4
Gives the translation of the symbol X

.ti +2
SYMBOL_ X_ "Translation"
.ti +4
Defines a new symbol or update the precedent symbol definition.

.ti +2
SYMBOL_ X_ /INQUIRE_ "Prompt_ Text"
.ti +4
Inquires the definition of a symbol with the specified prompt (for
interactive session only).

A symbol is an abbreviation of any character string. The symbol
translations are substituted to the corresponding symbols when found
in a command line. In a command line, symbol TOTO must appear inside
simple quotes (like 'TOTO') to be translated, except for the line
beginning where SIC assumes the first word might be a symbol. A symbol
definition may refer to another already defined symbol. The
substitution occurs everywhere, even within the character strings.

Symbols in FOR-NEXT loops are substituted at compilation time
(i.e. when the command line is written but not yet executed), using
their current value. In a loop, redefining a symbol which is already
defined out of the loop has no effect since its occurences are
substituted before the execution of all the commands.

Symbols can be deleted when they are no longer usefull, using command
DELETE /SYMBOL.
.\"====================================================================
.ti -4
1 SYSTEM
.ti +4
[SIC_\]SYSTEM ["Command"]
.ti +4
$ Command

Execute a command from the operating system, or create a subshell.

.in +2
.ti -2
Interactive shell (no argument)

If no argument is given, start a subshell based on the SIC logical
GAG__PROCESS. If it is not defined, the user $SHELL environment
variable is used. If it is also not defined, the last fallback is
/bin/sh. The subshell can be terminated by typing `exit' or `bye' or
`logout', depending on the shell, and controls return to SIC in this
case.

.ti -2
Script/command execution (one string argument)

If an argument is given, execute the command in a /bin/sh subshell
(note that /bin/sh is system-dependent and might behave differently
from one system to another). It must be a single argument: use
double-quotes to enclose multiple arguments separated by blanks. Note
that an error is raised if the shell command returns a non-zero
status. This behavior can be modified in 2 manners:
.in +2
.ti -2
- use dedicated command options, if any, to ensure it does not return
a non-zero status (for example -q option for grep),
.ti -2
- catch the error in the shell way, e.g. terminate the command line
with " || true" which executes the "true" command if an error
occurs. Obviously ignoring errors is at your own risk.
.in -2

Processes started in background from SYSTEM (for example with "&")
belong to SIC process group and are terminated when SIC exits. To keep
such a process running after SIC termination, start it with `setsid'
(for example `SYSTEM "setsid ./job.sh &"'). This creates a new
session/process group detached from SIC. Such detached processes are
not managed by SIC anymore and must be terminated by other means.

Note that Unix environment variables cannot be defined in such a way,
since it is a subshell (i.e. the environment modifications are lost
when the subshell ends). In particular, use command SIC_ DIRECTORY to
change your working directory.

.ti -2
$ Command (direct command execution)

At the interactive prompt, system commands can also be executed
directly from the SIC level using the $ token. "Command" must be a
valid operating system command in the default shell of the user
(e.g. $ls -l). The $ token is invalid in procedures.
.in -2
.\"====================================================================
.ti -4
1 TIMER
.ti +4
[SIC_\]TIMER
.ti +4
[SIC_\]TIMER ON|OFF
.ti +4
[SIC_\]TIMER [Time [Unit]] [/COMMAND String]

All Gildas programs can be automatically closed (normal exit) after a
defined period of inactivity at the prompt level. This period is
defined by the Sic timer. The timer starts as soon as the program
prompt is available (i.e. inactivity). The timer is stopped when a
command starts running. It restarts from the beginning when the prompt
is back. The timer is unset (i.e. no timer) by default.

Without argument, display the timer status.

With the keyword ON or OFF as argument, enable or disable the
timer. The timer is enabled by default.

With a Time argument, set the timer to the input value. Unit is a
keyword which can be HOURS, MINUTES, or SECONDS (default
HOURS).

The command executed once the timer is done can be customized with the
option /COMMAND. The command string must be a single argument,
possibly double-quoted if blanks are needed, e.g.
.nf
  SIC> TIMER /COMMAND EXIT
  SIC> TIMER /COMMAND "EXAMINE PI"
  SIC> TIMER /COMMAND "SAY ""Hello from timer"""
.fi
Default command at startup is EXIT.

The timer duration can be customized in a Sic logical named SIC__TIMER
(integer value, in hour unit). This value is evaluated once at startup
from one of the Sic logical dictionaries. Later changes are
ignored.
.\"====================================================================
.ti -4
1 TYPE
.ti +4
[SIC_\]TYPE Macro__Name
.ti +4
[SIC_\]TYPE [/OUTPUT OutFile]

TYPE lists the commands of the named macro. The same search rules as
for command SIC_\@ apply (see HELP_ @). The command SIC_ WHICH can be
used if you have doubts on the TYPE'd macro. Use SIC COPY to
duplicate a macro to a custom file.

If no argument is given, the command stack is listed to the terminal.
The output can be redirected to a file thanks to the option /OUTPUT
(prefer SIC_\EDIT if you plan to get and edit the stack).
.\"====================================================================
.ti -4
1 @
.ti +4
[SIC_\]@ Macro__Name [Arg1 [Arg2 [...]]]

Read commands from macro (or procedure) Macro__Name and execute them.

Default file extension is program dependent (usually the program name,
or .pro), and can be changed using command SIC_ EXTENSION. Procedures
are searched for according to the following rules:
.br
.in +4
.ti -2
- first in the directory designated by the logical name GAG__PROC:
.ti -2
- then, in order, in all the directories in the path specified by the
logical name MACRO#DIR: (see command SIC_ MACRO).
.in -4
One can use the command SIC_ WHICH to be sure of the macro which will
be executed.

All commands will be echoed to the terminal when executed if the
VERIFY switch is ON (see command SIC_ VERIFY).

Macros (as any other text files) can be edited using a standard text
editor by typing command EDIT with the macro file name as argument
(see EDIT and SIC_ EDIT).
.\"--------------------------------------------------------------------
.ti -4
2 ARGUMENTS
.ti +4
[SIC_\]@ Macro__Name [Arg1 [Arg2 [...]]]

The arguments passed to the macro are described by the structure PRO%:
.in +4
- PRO%NAME: calling procedure name,
.br
- PRO%NARG: number of arguments passed,
.br
- PRO%ARG: a character array (size PRO%NARG) providing all the
  arguments. This array is not defined if PRO%NARG is 0.
.in -4
The structure is updated when entering each macro. Up to 32 parameters
can be given.

Note that the arguments are all saved as character strings. A typical
use is:
.nf
    SIC> LET MYVAR 'PRO%ARG[1]'
.fi
to substitute the character string by its content. See also HELP PARSE
for advanced argument parsing.

The old-fashion way to access the arguments is to use the tokens &1,
&2, ..., &9. They are substituted to the corresponding arguments as
they are found in the body of the procedure, even within character
strings. For example
.nf
    SIC> say "a&1b"
.fi
will display the first argument value surrounded by "a" and "b". Note
that these tokens can be used to access the 9 first arguments only.
.\"====================================================================
.ti -4
1 ENDOFHELP
