1 ACCEPT [SIC\]ACCEPT Var_Name /ARRAY File_Name [/options ] [SIC\]ACCEPT Var_Name /BINARY File_Name Offset [SIC\]ACCEPT Var_1 [Var_2 [...]] /COLUMN File_Name [/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. 2 /ARRAY [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. 2 /BINARY [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. 2 /COLUMN [SIC\]ACCEPT Var_1 [Var_2 [...] /COLUMN File_Name [/FORMAT String] [/LINE Begin End] Read ONE or SEVERAL 1-Dimensional variables in list-directed (free) format from a formatted file File_Name. Mixing CHARACTER and NUMERIC (REAL, etc...) arrays is not available yet, and only one character array can be read at a time. The user can specify a format using the /FORMAT option, and select a line range using the /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 ACCEPT A * B C /COLUMN TEST.DAT reads A,B and C from columns 1,3 and 4 of file TEST.DAT, since the * indicates to skip the second column. 2 /FORMAT Specifies a fortran format to read the input file for command ACCEPT /ARRAY or ACCEPT /COLUMN. This option is invalid with /BINARY. example: DEFINE CHARACTER CITY*16[44] DEFINE REAL X[44] Y[44] ACCEPT X Y /COLUMN "cities.dat" /LINE 4 / FORMAT "20x,F8.3,1x,F8.3" ACCEPT CITY /COLUMN "cities.dat" /LINE 4 / FORMAT "2x,A16" 2 /LINE Indicates the line range to be read in the input file for command ACCEPT/ARRAY or ACCEPT/COLUMN. This option is invalid with /BINARY 1 @ [SIC\]@ Macro_Name [Par1 [Par2 [...]]] Reads commands from macro Macro_Name and executes them. Up to 8 parameters can be given. These parameters will be substituted to the tokens 1, 2, ..., 8 found in the body of the macro, even within character strings (e.g. Par1 for token 1). Default file extension is program dependent (usually the program name, or .pro), and can be changed using command SIC EXTENSION. 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 (EDT, TPU, EDU or EVE on VMS, Emacs or Vi on Unix, NotePad or WordPad on MS-Windows), by typing command EDIT with the macro file name as argument (see EDIT). 1 BEGIN [SIC\]BEGIN Procedure|Help|Data FileName Begins 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:. 1 BREAK [SIC\]BREAK Terminates a loop execution. The two uses of command BREAK are usually 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 END IF NEXT BREAK differs from QUIT because it does not transmit any error. 1 COMPUTE [SIC\]COMPUTE OutVar OPERATION InVar [Parameters] 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 REAL and DOUBLE_PRECISION arrays, regardless of their nature: - MAX MIN MEAN RMS SUM PROD for which InVar is an array of rank 1 to 4 (a 1-D to 4-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. Example (if A[4,12,2,8] and b[4,12]): "COMPUTE B MAX A" Sections, implicit transpositions, etc... permitted by SIC are supported. - HISTOGRAM Example: "COMPUTE outvar HISTOGRAM invar [hmin] [hmax] [bval] [eval]" which puts 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 min 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]). The following transformations are available: - FFT+ (Direct Fast Fourier Transform) - FFT- (Inverse Fast Fourier Transform) which accept REAL or COMPLEX parameters. 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. - FOURT+ (Direct Fast Fourier Transform) - FOURT- (Inverse Fast Fourier Transform) Which operates on input and output on COMPLEX Arrays of dimension [2,NX,NY] - DATE as in COMPUTE creation_date DATE filename Where 'filename' is a file name and returns the last modification date in the integer variable 'creation_date'. Used in procedures to check if file has been changed, etc... - GAG_DATE as in COMPUTE idate GAG_DATE "15-DEC-2035 11:42" stores the date "15-DEC-2035 11:42" as a modified Julian date in the integer variable 'idate' - COMPLEX ABS REAL IMAG CMPMUL PHASE which operate on COMPLEX arrays and are undocumented. 1 CONTINUE [SIC\]CONTINUE or C Resumes 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. 1 SYSTEM [SIC\]SYSTEM ["Command"] [/PROCESS Process_Name] See HELP SYSTEM VMS or HELP SYSTEM UNIX for operating-system dependent help. 2 VMS [SIC\]SYSTEM ["Command"] [/PROCESS Process_Name] VMS Help version Execute the VAX-VMS command specified by Command, or attach or spawns a sub-process. If specified with an argument, the SYSTEM command tries to execute the requested VMS command by creating a temporary sub-process executing the requested command. Control is returned to SIC after completion of the command and the sub-process deleted. This mode is NOT RECOMMENDED, because it is time consuming. If no command is specified, the SYSTEM command spawns a sub-process or attaches the terminal to an existing one. The sub-process prompts for SYSTEM commands at the user's terminal, with a $$ prompt to distinguish it from the parent process. Type QUIT to return to SIC. The first time the SYSTEM command is used, the SIC monitor looks for all existing sub- processes and asks the user the name of the sub-process to attach. Anwser by specifying the complete name, or press RETURN to create a new sub-process. If no sub-process is available, the SYSTEM command creates automatically a new one. If a sub-process creation fails, the SYSTEM command identifies your current sub-processes, and prompts you to which one you want to attach. Following executions of the SYSTEM command simply attach to the same sub-process. Any sub-process created with the SYSTEM command is not deleted when you exit from the program running SIC, so that you may connect to it by VMS command ATTACH later (or by other program using SIC with the SYSTEM command of course). To kill the sub-process, type LOGOUT (in the sub- process !) instead of QUIT to return to SIC. You can also stop your unwanted sub-processes (from the parent process) by the VMS command $ STOP If the option /PROCESS is specified, the SYSTEM command attaches the terminal to the specified process, which may have been created in any manner. No command is allowed in this case. 2 UNIX [SIC\]SYSTEM ["command name"] Unix version If no argument is given, start a subshell by running the default user shell (sh, csh or ksh). The subshell can be terminated by typing 'exit' or 'bye' or 'logout', depending on Unix version, and controls return to SIC in this case. If an argument is given, execute the Unix command in a subshell. Note that new Unix environment variables canot be defined in such a way, since it is a subshell. In particular, use command SIC DIRECTORY to change your working directory. SHORT CUTS: Unix commands can also be executed directly from the SIC level using the token, e.g. No case conversion occurs in such a case, and the "unix is directly executed in a subshell. 1 DEFINE [SIC\]DEFINE Type Var1 [Keys...] [Var2 [Keys...] [...]] [/GLOBAL] [/LIKE VarLike] If Type is FUNCTION, define a user-function. If Type is COMMAND, define a new user command. 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, STRUCTURE or FITS. 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. 2 CHARACTER [SIC\]DEFINE CHARACTER Var1*N1[DIM1] [...] CHARACTER variables can be scalar or multi-dimensional. The length of CHARACTER variable is specified after an * after the name of the variable. The dimension field (same syntax as for other arrays) should follow the length declaration. 2 COMMAND DEFINE COMMAND NAME "Equivalent command" [Help_File] defines a new SIC command. The new command will be part of the USER\ language, and will be translated into its equivalent command at execution time. Help_File is an optional argument indicating the name of the associated help text. The standard rules for help syntax applies (see SIC documentation for details). User defined commands appear in the list of command displayed by HELP, and can be abbreviated as normal "program-defined" commands. For example DEFINE COMMAND INPUT "@ input.greg" pr:inputeg.hlp define a new command USER\INPUT, which will execute procedure input.greg 2 DOUBLE [SIC\]DEFINE DOUBLE Var1[DIM1] [Var2[DIM2] [...]] DOUBLE variables can be multi-dimensional. Up to 4 dimensions can be specified in the optional DIM field, with the following syntax: Var[n1] or Var[n1,n2] etc... up to Var[n1,n2,n3,n4] where Var is the variable name and n1 to n4 are integer constants or variables. 2 FITS DEFINE FITS Var File [/GLOBAL] defines 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. For basic FITS data, the following variables are defined 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 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 (an obsolescent FITS structure) is not implemented. DEFINE FITS only works to read FITS files, but not to create them. 2 FUNCTION DEFINE FUNCTION NAME(X,Y,Z) Expression(X,Y,Z) defines an arithmetic user function of several variables. The maximum number of variables is 4. 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). 2 HEADER DEFINE HEADER Var1 File1 Key1 [Var2 File2 Key2 [...]] [/GLOBAL] defines variables associated to the HEADER of the GILDAS images located in the specified files. The Keyword must be either READ or WRITE. The following variables are defined: VAR%GENE Integer Length of general section VAR%NDIM Integer Number of dimensions (ReadOnly) VAR%DIM Integer[4] Dimensions (ReadOnly) VAR%CONVERT Double[3,4] Conversion formulae for the 4 axes: Reference pixel, Value at reference pixel, Increment VAR%BLAN Integer Length of blanking section VAR%BLANK Real[2] Blanking and tolerance VAR%EXTREMA Integer Length of extrema section VAR%MAX Real Maximum VAR%MIN Real Minimum VAR%WHERE Integer[4,2] Position of max and min VAR%DESC Integer Length of units and coordinate system section VAR%UNIT Char*12 Image unit VAR%UNIT1 Char*12 First axis type VAR%UNIT2 Char*12 Second axis type VAR%UNIT3 Char*12 Third axis type VAR%UNIT4 Char*12 Fourth axis type VAR%SYSTEM Char*12 Coordinate system VAR%POSI Integer Length of position section VAR%SOURCE Char*12 Source name VAR%RA Double Right Ascension VAR%DEC Double Declination VAR%LII Double Galactic longitude VAR%BII Double Galactic latitude VAR%EPOCH Real Epoch of coordinates VAR%PROJ Integer Length of projection section VAR%PTYPE Integer Projection type (code) VAR%A0 Double first coordinate of projection center VAR%D0 Double second coordinate of projection center VAR%ANGLE Double position angle of projection VAR%X_AXIS Integer First projected axis VAR%Y_AXIS Integer Second projected axis VAR%SPEC Integer Length of spectroscopy section VAR%LINE Char*12 Line name VAR%FREQRES Double Frequency resolution VAR%FREQOFF Double Frequency offset VAR%RESTFRE Double Rest Frequency VAR%VELRES Real Velocity resolution VAR%VELOFF Real Velocity offset VAR%F_AXIS Integer Frequency/Velocity axis VAR%BEAM Integer Length of beam section VAR%MAJOR Real Major axis of beam VAR%MINOR Real Minor axis of beam VAR%PA Real Position angle of beam 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. the VAR\%item variables are ReadOnly or ReadWrite according to the keyword Key, except for the dimension variables, which cannot be modified. 2 IMAGE DEFINE IMAGE Var1 File1 Key1 [Var2 File2 Key2 [...]] [/GLOBAL] defines variables associated to both the content and the header of the GILDAS images located in the specified files. 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. 2 INTEGER [SIC\]DEFINE INTEGER Var1[DIM1] [Var2[DIM2] [...]] INTEGER variables can be multi-dimensional. Up to 4 dimensions can be specified in the optional DIM field, with the following syntax: Var[n1] or Var[n1,n2] etc... up to Var[n1,n2,n3,n4] where Var is the variable name and n1 to n4 are integer constants or variables. 2 LOGICAL [SIC\]DEFINE LOGICAL Var1[DIM1] Var2[DIM2] [...] LOGICAL variables can be multi-dimensional. Up to 4 dimensions can be specified in the optional DIM field, with the following syntax: Var[n1] or Var[n1,n2] etc... up to Var[n1,n2,n3,n4] where Var is the variable name and n1 to n4 are integer constants or variables. 2 REAL [SIC\]DEFINE REAL Var1[DIM1] [Var2[DIM2] [...]] REAL variables can be multi-dimensional. Up to 4 dimensions can be specified in the optional DIM field, with the following syntax: Var[n1] or Var[n1,n2] etc... up to Var[n1,n2,n3,n4] where Var is the variable name and n1 to n4 are integer constants or variables. 2 STRUCTURE DEFINE STRUCTURE Str [/GLOBAL] defines 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 DEFINE REAL Str%Element etc... An entire structure and all its associated members is deleted by a single command DELETE Str /VARIABLE. 2 TABLE DEFINE TABLE Var1 File1 Key1 [Var2 File2 Key2 [...]] [/GLOBAL] defines variables associated to GILDAS images located in the specified file. The variable type and dimensions are derived according to the value of the keyword Key and the file content: - 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. - DOUBLE, INTEGER or REAL: create a new image of the specified type. The dimensions must then be specified in the dimension field of the variable name, as for a standard variable. - 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 DEFINE TABLE Var[Ldim] File EXTEND where Ldim is the new value for the last dimension. DEFINE TABLE does not create any additional variables for the image header. See DEFINE IMAGE and DEFINE HEADER for this information. 2 /LIKE [SIC\]DEFINE Type Var1 [Var2 [...]] /LIKE VarLike DEFINE IMAGE Var1 File1 Key1 [...]] /LIKE VarLike 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. The /LIKE option is incompatible with the DEFINE FUNCTION and DEFINE HEADER commands. 1 DELETE [SIC\]DELETE [/VARIABLE] [/SYMBOL] [/FUNCTION] Name1 [Name2 [...]] Deletes specified variables, symbols or functions. For IMAGE variables, also frees the corresponding file. 1 EDIT [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 editted. Different editors are available : TPU and EDT on VMS systems, Emacs and Vi on Unix systems, possibly more if your system manager has defined others. The default behaviour is the following : - On VMS systems, the TPU editor is called, with the default section as defined by logical name TPUSECINI. TPUSECINI usually points to a section using the TPU editor with EDT interface and additional features added by the Groupe d'Astrophysique such as double window mode, but you may have redefined it to your own section. - On Unix systems, Emacs with EDT mode is normally used. The behaviour can be changed using the command SIC EDIT, or specifying at system level a logical name for GAG_EDIT. For example to use the EDT editor, you could type SIC> SIC EDIT EDT within a program using SIC. EDT will then be used for any EDIT command typed during the program execution. Alternatively, you could define your default SIC editor by, on VMS systems, using the DCL command DEFINE GAG_EDIT EDT on Unix systems, inserting the following command in your $HOME/.gag.dico file GAG_EDIT emacs 1 ELSE [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 SYMBOL ELSEIF "SIC\ELSE IF" 1 END [SIC\]END Procedure|Help|Data|If [SIC\]END IF Marks the end of an IF block. Normal execution resumes. The symbol ENDIF is defined as an abbreviation of SIC\END IF. [SIC\]END Procedure|Help|Data Terminates the definition of a new Procedure, Help file, or Data file. See command BEGIN for details. 1 EXAMINE [SIC\]EXAMINE [Name] [/GLOBAL] [/FUNCTION] [/HEADER] List variables or functions. If the /FUNCTION option is not present, 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. With argument, EXAMINE will usually type the content of the specified variable (local variables have priority). But: - If the argument ends by the % character, it is assumed to indicate an image header, and all associated header variables are listed. - Partial wildcarding is permitted: if the argument begins or/and ends with the "*" character, all compatible variables names are listed. - In any case, typing an ambiguous variable name will generate a list of choices. With the /FUNCTION option, lists the definition of the specified or all (no command argument) user-defined functions. 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). 1 EXIT [SIC\]EXIT EXIT always ends SIC execution, at any level. 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. Note that end of SIC execution does not necessarily means end of program execution: SIC may be entered again later by the calling program. 1 FOR [SIC\]FOR Loop_Variable n1 n2 n3 TO n4 BY n5 n6 TO n7 or [SIC\]FOR /WHILE Logical_Expression Open a FOR-NEXT loop to be executed for values in the list (FOR Variable), or until a logical expression becomes false (FOR /WHILE). The last character of the prompt becomes a ':' instead of '>', and all subsequent commands typed in until NEXT are the body of the loop. Up to nine loops may be nested in any way. The index of the loop will be substituted to the loop variable Loop_Variable during loop execution. The substitution occurs also within character strings if the loop variable name is included between single quotes. Note that the index values may be real. [SIC\]FOR Loop_Variable n1 n2 n3 TO n4 BY n5 n6 TO n7 The loop specified in this example will execute for the following values of the index : n1 n2 n3, n3 + n5, n3 + 2 n5, n3 + 3 n5, ... , n4 n6, n6 + 1, n6 + 2, ... , n7 (assuming that n4-n3 is a multiple of n5, n7-n6 an integer). Loop variables are undefined outside the loop, and must not be previously defined. 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. Conditional loops execute until the logical expression becomes false. For example FOR/WHILE .TRUE. will execute forever... 1 HELP [SIC\]HELP Name[\] [Subtopic] Without an argument, HELP gives the list of available help. If the "\" character is present, Name is assumed to be a language name, and HELP gives a one line description of all commands specific to this language. If the "\" is not present, Name is a command, and HELP gives more information about it. Twol levels of Help are available. The subtopic may be a command option (and a * to get information on all subtopics of the command). 1 IF [SIC\]IF Logical_Expression [THEN] Starts a conditional IF block. The behaviour of IF blocks is similar to structured FORTRAN. Any text following the logical expression is ignored, but if this text is not THEN, an error message is produced. This command can only be used within a procedure: interactive users are expected to be able to make their decisions themselves... Within logical expressions, two special logical functions can be used: EXIST(Name) Returns .TRUE. if Name is an existing variable FILE(Name) Returns .TRUE. if Name is an existing file and composite expressions are allowed. 1 Language SIC\ Command Language Summary ACCEPT : Reads variable in various format. BEGIN : Begin a sub-procedure, help file or data file BREAK : Exits without error from a FOR-NEXT loop. CONTINUE : Resumes macro or loop execution after PAUSE. COMPUTE : Execute non-arithmetic operations on variables. DEFINE Type V : Define new variables. DELETE : Delete variables or symbols EDIT [File] : Edit a file or a dump of the Stack. ELSE [IF Log] : Alternate IF block directive. END : Ends IF block structure or a sub-procedure. EXAMINE Var : Types the current value of the specified variable. EXIT : Exits from the program. FOR [/WHILE] : Opens a FOR-NEXT loop. HELP XX[\] : Gives an explanation of command XX or language XX\. IF Logical : Starts a conditional IF block. LET [/WHERE] : Assigns value to variable. MFIT A=F(B,p) : Fit a formula into SIC variables. NEXT : Ends FOR loop definition and activates the execution. ON ERROR COMM : Changes the current error recovery action. PAUSE : Set a break point in a Loop or a Macro. QUIT : Aborts an execution interrupted by PAUSE. RECALL [Text] : Recalls line from stack, and edit it if possible. RETURN : Terminates procedure execution. SAY "text" : Type a text or variable or expression value. SIC Arg ON : Changes some SIC internal status. SYMBOL : Defines, lists and deletes symbols. SYSTEM : Create or attach sub-processes, run system commands. TYPE [XX] : List file XX or the stack. @ XX [P1 ...] : Reads commands from macro XX and executes them. GUI\ Command Language Summary BUTTON : Associate a command with a button GO : Activate the currently defined window PANEL : Define a new input window or menubar MENU : Create a pulldown menu for next buttons WAIT : Wait for GO button in the current window 2 NEWS Version 9.0 History Version 9.0 introduces a major syntax change: the need for a space before the option delimiter, and the suppression of case conversion when not needed. This modified syntax allows more rigorous analysis and simpler access to file names. * New BEGIN command to create sub-procedures and help or data files within procedures * New END command to delineate the end of the above files. ENDIF is now a symbol equivalent to SIC\END IF. * New DEFINE STRUCTURE command to create SIC Structures (Fortran-90 syntax for an ensemble of variables) * New DEFINE FITS command to allow easy reading of FITS files. Version 8.2 History * Changed slightly the options of MFIT (see HELP MFIT). * COMPUTE now accept a new 'operation': HISTOGRAM. Version 8.0 History Version 8.0 enhances the mathematic capabilities of SIC, a (hopefully) better syntax for mathematic operations, and presents a first implementation of a Graphic-User-Interface input mode on X-Window systems. * Implicit transposition and sub-array extraction is allowed in variable assignement: e.g. LET A[10:2,3:4] = B[11:3,1:2] * The COMPUTE [MIN,MAX,PROD,SUM,RMS,MEAN] now supports arrays. * The syntax related to "implicit formatting" and mathematic operations has been slightly modified (but is upward compatible). * A new language, GUI, its new commands, PANEL, BUTTON, MENU, GO and WAIT, and a complete set of options to command LET have been introduced to allow variable assignment through the Graphic-User- Interface available on the user terminal. The GUI mode is currently supported on X-Window terminals only. The GUI commands allow procedures to define menus to assign variables. See command LET and the "GUI (Graphics-User-Interface)" chapter. * The credits and version number of the languages are now given by the command SIC VERSION. Version 7.0 History Version 7.0 introduces some new mathematic capabilities which significantly enhance the power or speed of the SIC command language. * MFIT command allowing fitting functions to SIC variables. * Size casting in variable declaration (DEFINE /LIKE) * Conditional assignement (LET /WHERE) * Full support for character and logical arrays * "Free syntax": A = 2 is now a valid command if A is a known variable. See SIC SYNTAX. Version 6.0 History * Portable version available on VMS, Ultrix, AIX, SUN-OS, HPUX and in general UNIX operating systems. * Extensive support for image headers introduced. Command DEFINE TABLE, DEFINE HEADER and DEFINE IMAGE to connect the data of an image (TABLE), the header of an image (HEADER) or both (IMAGE). The image header is a pseudo-structure (set of variables with common root). See HELP DEFINE for details. * Bug correction in loops: aborting a compilation of a 3rd loop when at PAUSE level from 2 nested loops caused SIC to complain about invalid nesting. Now corrected. Version 5.0 History * Specific command DCL renamed in SYSTEM for portable version * Command COMPUTE for non-arithmetic operations on array variables (FFT, TRANSPOSE, but also RMS, MIN, MAX, MEAN of arrays). * Extensive support for array variables. * Some library-mode bug suppressions Version 4.6 History * IF, ELSE, ELSE IF, ENDIF conditional structures * Extended loop nesting. Loop variables in command FOR * Conditional loops (FOR/WHILE Condition) * Arithmetic and logical expressions * BREAK and RETURN commands to stop loops and procedures execution respectively. * Variables: commands DEFINE, LET, EXAMINE and SAY. Entry points added in SIC to deal with variables. * Modification of stack: circulating buffer used, GO command suppressed. 1 LET [SIC\]LET Variable = Expression [/NEW Type [Attr]] [SIC\]LET Variable = Expression /WHERE Conditionmask [SIC\]LET Variable [= Expression] /PROMPT "Explanatory text" [SIC\]LET Variable [= Expression] /RANGE Min Max [SIC\]LET Variable [= Expression] /CHOICE Value_1 Value_2 ... Value_n [SIC\]LET Variable [= Expression] /INDEX Value_1 Value_2 ... Value_n [SIC\]LET Variable [= Expression] /FILE Filter Assigns a value to a variable. The variable must already be defined (see DEFINE) unless the /NEW option is present. In this case, Type is the type of the variable (REAL, INTEGER, DOUBLE for double precision, or LOGICAL). 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 Attr argument is used to specify whether the newly created variable is LOCAL (default) or GLOBAL. If no value is assigned to the Variable, the user will be prompted for the variable value. 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: 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 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", i.e. functions of the array indices such as DEFINE REAL A[4,5] LET A[I,J] = (I-J)**2 Implicit loops cannot be mixed with variable index values. 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. FREE SYNTAX: The LET command may be omitted if no option is present, and is the SIC syntax is set to FREE. In case of conflict between a variable name and a (complete) command name, an error message is issued. See SIC command. 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 XGO. 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. 2 /WHERE [SIC\]LET Variable = Expression /WHERE Conditionmask 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 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 is equivalent (in terms of results, but about 500 times faster) to the loops 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 Note in the example above that implicit variables can be used. However, the following syntax is non valid, LET A[I,J] = SIN(I+J) /WHERE B[I,J].GT.5 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 following syntax is also non valid LET A = B /WHERE B[I,J].GT.LOG(I+J) because implicit variables cannot be defined by an operand array (B), but only by the result array. The correct syntax would be LET A[I,J] = B /WHERE B.GT.LOG(I+J) 2 /PROMPT [SIC\]LET Variable [= Expression] /PROMPT "Explanatory text" Created 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 XGO. 2 /RANGE [SIC\]LET Variable [= Expression] /RANGE Min Max Activate a slider widget to return a value within the specified range. The widget will be created by command XGO. 2 /CHOICE [SIC\]LET Variable [= Expression] /CHOICE Value_1 Value_2 ... Value_n Activate a choice widget which will return a value among the specified list. The widget will be created by command XGO. If the last specified value is an asterisk, any value is also valid. 2 /INDEX [SIC\]LET Variable [= Expression] /INDEX Text_1 Text_2 ... Text_n 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 XGO. 2 /FILE [SIC\]LET Variable [= Expression] /FILE Filter Activate a "file" widget to select a file according to the specified filter. The widget will be created by command XGO. 1 MFIT [SIC\]MFIT Yvar=Func(Xvar,&A,&B,...) [/START A1,B1,...] [/STEP A2,B2,...] [/EPSILON e] [/WEIGHTS w] [/METHOD m] or [SIC\]MFIT Filename [/START A1,B1,...] [/STEP A2,B2,...] [/EPSILON e] [/WEIGHTS w] [/METHOD m] Performs a least squares fit using the SIMPLEX (default) or POWELL algorithm (if option /METHOD P is selected) from Numerical Recipes, see Press et al. for details. 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. /START A1,B1,... (comma-separated list WITHOUT BLANKS) is used to pass starting guesses for the parameters &A &B (defaulted to 0.1), /STEP A2,B2,...(comma-separated list WITHOUT BLANKS) is used to pass the unity vectors (steps) for the iteration on parameters &A &B (defaulted to 1.0). 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 real variable MFIT. Option /EPSILON can be used to specify the desired precision, which means the deviation of the mean squared difference of two fit iterations. This might NOT be the absolute error of the fit parameters. An array with weights may be given by option /WEIGHT. 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 uses the following global SIC variables: MFIT : Fit parameters MFITMATH : Text string containing the formula with replaced dummies MFITOUT : Found approximation (the application of MFITMATH) MFIT_RES : Residuals (i.e. MFITOUT-Yvar) MFIT_SUM : Mean squared residuals MFIT_ERR : .FALSE. on successful completion. 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 MFIT Y=(&A*X^3+&B*X^2+&C*X+&D) /WEIGHTS Z The MFIT command will print the used formula: I-MFIT, Formula (stored in variable MFITMATH) : (MFIT[01]*X^3+MFIT[02]*X^2+MFIT[03]*X+MFIT[04]) The array MFIT will contain MFIT[1]=value of '&A', and so on... To be used afterwards. 1 NEXT [SIC\]NEXT Depending on the context, NEXT has one of two possible interpretation: - If typed during loop definition, NEXT indicates the end of the definition and starts the execution. - 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). The commands will be echoed to the terminal if the VERIFY switch is on. 1 ON [SIC\]ON ERROR [Command] This command changes the current error recovery action. By default, a PAUSE is automatically generated by any error during execution. This can be changed and any other valid command line Command can be activated instead of PAUSE when an error occur, using the command ON ERROR Command. However, options cannot be present into the command line 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. 1 PAUSE [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 excution 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). 1 QUIT [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. 1 RECALL [SIC\]RECALL [Arg] This command retrieves command lines from the stack. The retrieved line is edited if possible or immediately executed if not. If no argument is present, the last command line is retrieved. If the argument is a number, the specified command is retrieved. If it is a character string, the first (most recently entered) command which begins by this string is recalled (in this case, the string may include a full language name or nor language at all). When line editing is possible, commands can also be retrieved using the Up arrow (or ^P) to recover the previous command, and Down arrow (or ^N) to recover the next command. On VMS systems, press the GOLD (PF1) key before to bypass VMS line editing recovering function. If no line editing is available, you are prompted whether to execute or not the recalled command. 1 RETURN [SIC\]RETURN [BASE|ERROR] Ends 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. 1 SAY [SIC\]SAY ["Text"] ['Expression'] ['Variable'] Display strings or character variable or implicitly formatted arithmetic (or logical) expressions in the shortest possible format. By default, SAY writes its output text both on the current output and on the file opened by command SIC\SIC OUTPUT. In GUI mode (see command GUI\PANEL), SAY writes the text in the current window. SAY without parameters inserts a separator. 1 SIC [SIC\]SIC Arg1 Arg2 [... ArgN] (1) System-like commands: SIC COPY FileOld FileNew Copy FileOld to FileNew SIC DELETE File Delete the designated file. Caution: there is no confirmation required !. SIC DIRECTORY Directory_name will change the working directory for the session. SIC RENAME OldFile NewFile Rename Oldfile to NewFile (2) Internal status of the command monitor SIC BEEP [N] will sound 1 or N beeps. SIC DATE will obtain the date and time from the operating system and set the symbol SYS_DATE. SIC EDIT ON or OFF enables or disables line keypad editing. SIC EDIT EDITOR_NAME forces use of the specified text editor in command EDIT. The text editor used by SIC can also be defined by assigning the logical name GAG_EDIT to the editor name (in the "User Dictionary" file). SIC ERROR list the current error recovery command. SIC EXTENSION .SOMETHING controls the default macro extension used by commands @ and EDIT. This default extension is program dependent: for all GAG softwares, it is the program name, while many user created applications use the generic default extension .PRO. SIC HELP PAGE | SCROLL | INDEX | CONTENT | MOSAIC | NETSCAPE controls whether the HELP command outputs the text page by page (PAGE), or continuously (SCROLL). SIC HELP INDEX indicates the HELP command should display the page referenced first in the index of the PostScript documentation. SIC HELP CONTENT indicates the HELP command should display the page referenced first in the table of contents from the PostScript documentation. The last two options use the GhostView facility on X-Window terminals. SIC HELP MOSAIC or NETSCAPE indicate the HELP command should refer the HTML version of the documentation and use the appropriate browser to display it. SIC Language\ ON or OFF places a language in the active scope or removes it. Languages not in active scope are not searched for their commands, unless the language name is explicitly given. SIC LOG Logical_name Translation sets or replace a logical name. SIC LOG Logical_name will give the translation of the logical name. SIC LOG without second argument will list all logical names. SIC MEMORY ON or OFF enables or disables automatic insertion of successful commands into the stack. SIC OUTPUT File_name will redirect SIC\SAY output to a file. SIC OUTPUT without argument will close the opened output file, and redirect SIC\SAY output to the terminal. SIC PRECISION Keyword selects the precision of all computations using SIC variables. Valid keywords are SINGLE (or REAL), DOUBLE, and AUTO. SIC USER will get the user name from the operating system, and set the symbol SYS_INFO. SIC VERIFY ON or OFF controls the listing of macros, loop or stack during execution. SIC SYNTAX FIXED or FREE controls the syntax for mathematic operations. In FIXED syntax, the LET command is compulsory. In FREE syntax, commands lines like A[I,J] = SIN((2*I+J)/PI) where A is a known variable, are recognized as assignement and automatically expanded to the equivalent FIXED syntax LET A[I,J] = SIN((2*I+J)/PI) Free syntax cannot be used for the LET /WHERE command. SIC VERSION Returns the version number and credits or copyrights for the languages or subprograms currently used. 1 SYMBOL [SIC\]SYMBOL [X ["Translation"]] [/INQUIRE "Prompt Text"] This commands defines, lists and deletes symbols. SYMBOL Lists the Symbol table SYMBOL X Gives the translation of the symbol X SYMBOL X "Translation" Define a new symbol or update the precedent symbol definition. SYMBOL X /INQUIRE "Prompt Text" 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 can be deleted when they are no longer usefull, using command DELETE /SYMBOL. 1 SYNTAX\ SYNTAX of SIC commands The SIC syntax is the following : [LANG\]COMM [Arg1 [Arg2 [...]]] [/OPT1 [p1 [...]] [/OPT2 [...]] 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 "The real number PI is equal to "'ACOS(-1.0)' 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. DEFINE CHARACTER C*6 LET C 3.14159 DEFINE REAL A LET A 'C'/PI EXAMINE A A = 0.9999705 1 TYPE [SIC\]TYPE [Macro_Name] TYPE lists the commands of the named macro. If no argument is given, the Stack is listed. 1 BUTTON GUI\BUTTON "Command" Button ["Title" Helple [OptionTitle]] Creates a button widget to execute the specified "Command". If no "Title" is given, the button will have no associated variables, and will appear with other similar buttons at the top of the window. If a "Title" argument is present, a "secondary parameters" window is created. In the main window, the "title" appears followed by 3 buttons: one with the button name, one pointing to the secondary parameters window, and a "HELP" button. All subsequent LET commands will create widgets in this secondary window, until a new GUI\BUTTON command is typed. "Helple" specifies a text file where the help for the variables can be found, and "OptionTitle" is a title for the secondary window (and associated button). 1 END GUI\END Reads all parameters from the current window(s) and set the modified variables accordingly. Normally reserved for programming applications. 1 GO GUI\GO ["Command"] Map the windows defined by the previous GUI\PANEL command and its associated GUI\BUTTON and LET commands. "Command" is an optional command to be executed when button "GO" is pressed. 1 PANEL GUI\PANEL "Title" HelpFile [/DETACH] Activate the Graphic-User-Interface input mode for variables. A window with the specified title is created, but not mapped to the screen. Successive LET commands will create widgets in this window to allow to modify variables by entering values in the widgets. Command GUI\GO "Command" will map the window to the screen. Once the proper input has been defined, clicking on the "GO" button will setup all the related variables in the main program, and execute the associated command. Clicking on button "UPDATE" will only set the variables. Clicking on button "ABORT" will return without modifying the variables. Help is available in the window through the "HELP" button, but also clicking in any prompt area. See LET command for details. If option /DETACH is present, a menubar is created instead of a normal window. Several buttons can be attached to this menubar using the GUI\BUTTON and GUI\MENU commands, but no variables can be set in this mode. The menubar is mapped when command GUI\GO is typed. 1 MENU GUI\MENU "Title" [/CLOSE] Creates a pulldown menu to group a set of buttons without associated parameters. Subsequent GUI\BUTTON commands will add buttons in the pulldown menu. When option /CLOSE is present, closes the current pulldown menu. Subsequent GUI\BUTTON commands will creates buttons on the main menubar. This command is valid only when creating a detached menubar, i.e. after a GUI\PANEL/DETACH command has been typed. 1 WAIT GUI\WAIT Wait for button "GO" "UPDATE" or "ABORT" to be pressed. The command monitor stays in hold state until one of these buttons in the main window are pressed. 1 END_OF_FILE