## Chapter 19ICL

19.1 Syntax
19.2 Commands
19.3 Functions
19.4 Exceptions

### 19.1 Syntax

This section gives a summary of the ICL language syntax. Square brackets imply that the enclosed part of the construct is optional.

Operational Mode
Direct:

Statements are executed as they are entered.

Procedure:

Statements are first entered into a procedure, then the procedure is executed.

Data types —
Real
Integer
Logical
String
Expression—

value [operator value operator value ...]
Value—
Constant:
Real
-        1.234E-5,  3.14159
Integer
-     123,  %B100110,  %O377,  %Xffff
Logical
-     TRUE,  FALSE
String
-      ’This is a string’,  "So is this"
Variable:
Name
- Letter followed by letters, digits, or underscores (15 significant)
Function:

See below.

Operator—
 1 ** 2 *  / 3 +  - 4 =  >  <  >=  <=  <>  : 5 NOT  AND  OR  &
&
performs string concatenation.
:
is formatting operator (X:n:m is X converted to an n character string with m decimal places).
Statement—

Normally one statement per line. A tilde (~) at the end of a line indicates that the statement continues on the next line.

Direct Statement:

These statements can be used in any operational mode.

Comment
-

Any line starting with the characters ‘{’ or ‘;’.

Immediate Statement
-

= expression (prints value of expression)

Assignment Statement
-

variable = expression (assignment to variable)

Command
-

command_name p1 p2 …(command or procedure call)

In commands or procedure calls, parameters are separated by a comma or spaces. Expressions or variables should be enclosed in parentheses.

Control Statement:

These statements can only be used in the Procedure operational mode.

IF Statement
-

IF expression
statements
[ELSE IF expression
statements]
[ELSE
statements]
END IF
LOOP Statement
-

LOOP
statements
END LOOP

[LOOP] FOR var = exp1 TO exp2 [STEP exp3]
statements
END LOOP

[LOOP] WHILE expression
statements
END LOOP

You can escape from a loop via a BREAK statement.

PROCEDURE Statement
-

[HIDDEN] PROC name p1 p2 ....
statements
END PROC
EXCEPTION Statement
-

EXCEPTION name
statements
END EXCEPTION
Command Search Path—
(1)
User defined commands (defined by DEFSTRING, DEFUSER, DEFPROC)
(2)
User written procedures (defined by PROC)
(3)
(4)
(5)
Other ICL built-in commands (see below)

### 19.2 Commands

The commands which are likely to be of most use in data analysis are classified below. Commands relevant mainly to data acquisition are omitted. A full list is contained in SG/5.

Information & Escape—
HELP:
Display on-line documentation.
EXIT:
Exit from ICL.
Defining user commands—
DEFSTRING:
Associate a command with an equivalence string.
DEFINE:
DEFUSER:
Associate a command with a user written subroutine.
DEFPROC:
Associate a command with a procedure.
I/O—
Terminal I/O:
PRINT:
Output to the terminal.
INPUT:
Input a string.
INPUTI:
Input integers.
INPUTL:
Input logical values.
INPUTR:
Input real numbers.
Screen mode:
SET SCREEN:
Set screen I/O mode.
SET NOSCREEN:
Set normal I/O mode.
SET ATTRIBUTES:
Set attributes for text written with the LOCATE command.
LOCATE:
Write to screen at specified position.
CLEAR:
Clear lines in a specified range.
Keyboard facilities:
KEY:
Define an equivalence string for a key.
KEYTRAP:
Specify trapping of a key.
KEYOFF:
Turn off trapping of a key.
File I/O:
CREATE:
Create a file and open it for output.
OPEN:
Open an existing file for input.
APPEND:
Open an existing file for appending.
CLOSE:
Close a file opened with CREATE, OPEN, or APPEND.
WRITE:
Write to a file.
Read a string from a file.
Read logical values from a file.
Read real numbers from a file.
General:
\$:
Issue a DCL command.
SPAWN:
Spawn a subprocess to issue one or more DCL commands.
DEFAULT:
Set/Show default directory.
Managing tape drives:
ALLOC:
Allocate a device.
DEALLOC:
Deallocate a device.
MOUNT:
Mount a tape.
DISMOUNT:
Dismount a tape.
Parameters—
SETPAR:
Set the value of a parameter where the program has an associated command.
GETPAR:
Get the value of a parameter where the program has an associated command.
CREATEGLOBAL:
Create a global parameter.
SETGLOBAL:
Set the value of a global parameter.
GETGLOBAL:
Get the value of a global parameter into an ICL variable.
Procedures—
Listing and editing:
LIST:
List a procedure.
PROCS:
List procedure names.
VARS:
List procedure variables.
EDIT:
Edit a procedure.
SET EDITOR:
Change the editor (TPU, EDT, or LSE) used by EDIT.
SAVE:
Save a procedure.
Accept commands from a saved procedure.
DELETE:
Delete a procedure.
Tracing execution:
SET TRACE:
Switch tracing of procedures ON.
SET NOTRACE:
Switch tracing of procedures OFF.
Errors and Exceptions—
SIGNAL:
Signal an ICL exception.
Help system—
DEFHELP:
Define the source of help information.
Miscellaneous—
SAVEINPUT:
Save previous input lines in a text file.
SETPRECISION:
Set the number of decimal digits precision for unformatted conversions of real values to strings.

### 19.3 Functions

The following functions are available for use in expressions (N.B. The ‘$\ast$’ symbol in the Type column stands for ‘Real or Integer’).

Mathematical Functions—
 Name Type Definition SIN(X) Real Trig. functions (x in radians). COS(X) Real TAN(X) Real SIND(X) Real Trig. functions (x in degrees). COSD(X) Real TAND(X) Real ASIN(X) Real ${sin}^{-1}x\phantom{\rule{2.77695pt}{0ex}}where-1\le x\le 1$; $-\pi /2\le result\le \pi /2$. ACOS(X) Real ${cos}^{-1}x\phantom{\rule{2.77695pt}{0ex}}where-1\le x\le 1$; $0\le result\le \pi$. ATAN(X) Real ${tan}^{-1}x$; $-\pi /2\le result\le \pi /2$. ATAN2(X1,X2) Real ${tan}^{-1}\left({x}_{1}/{x}_{2}\right)$; $-\pi . ASIND(X) Real Inverse trig functions in degrees. ACOSD(X) Real ATAND(X) Real ATAN2D(X1/X2) Real SINH(X) Real Hyperbolic functions. COSH(X) Real TANH(X) Real ABS(X) * $\mid x\mid$. DIM(X1,X2) * Positive difference between ${x}_{1}$ and ${x}_{2}$. EXP(X) Real ${e}^{x}$. LOG(X) Real $lnx$. LOG10(X) Real ${log}_{10}x$. MIN(X1,X2,...) * Minimum of two or more arguments. MAX(X1,X2,...) * Maximum of two or more arguments. MOD(X1,X2) * Remainder when ${x}_{1}$ is divided by ${x}_{2}$. SIGN(X1,X2) * Transfer of sign $\mid {x}_{1}\mid$ Sign ${x}_{2}$. SQRT(X) Real $\sqrt{x}$.
Formatting and String Handling Functions—
 BIN(I,n,m) String Integer I formatted in binary into an n char string with m significant digits. DEC(I,n,m) String Integer I formatted in decimal into an n char string with m significant digits. HEX(I,n.m) String Integer I formatted in hexadecimal into an n char string with m significant digits. OCT(I,n,m) String Integer I formatted in octal into an n char string with m significant digits. DECL(S) Real Declination in radians from string in degrees, minutes, seconds. DEC2S(R,NDP,SEP) String String in DMS with separator SEP and NDP decimal places on seconds, from Dec in radians. RA(S) Real Right Ascension in radians from a string in hours, minutes, seconds. RA2S(R,NDP,SEP) String String in HMS with separator SEP and NDP decimal places on seconds, from RA in radians. CHAR(I) String Character with ASCII value I. ICHAR(S) Integer ASCII value of first character of string S. INDEX(S1,S2) Integer Position of first occurrence of string S2 in string S1. LEN(S) Integer Length of string. ELEMENT(I,DELIM,S) String Ith element of delimited string. SUBSTR(S,n,m) String Substring of S beginning at n of length m. SNAME(S,n,m) String Name derived by concatenating string S with integer n formatted into m characters including leading zeros. UPCASE(S) String String S converted to upper case. LGE(S1,S2) Logical True if S1 $\ge$ S2 (ASCII collating sequence). LGT(S1,S2) Logical True if S1 $>$ S2 (ASCII collating sequence). LLE(S1,S2) Logical True if S1 $\le$ S2 (ASCII collating sequence). LLT(S1,S2) Logical True if S1 $<$ S2 (ASCII collating sequence).
Bitwise Logical Operations—
 IAND(I1,I2) Integer Bitwise AND. IOR(I1,I2) Integer Bitwise OR. IEOR(I1,I2) Integer Bitwise Exclusive OR. INOT(I) Integer Bitwise Complement.
Type Conversion and Inquiry Functions—
 FLOAT(I) Real Integer I converted to real. IFIX(X) Integer X converted to integer by truncation. INT(X) Integer X converted to integer by truncation. NINT(X) Integer Nearest integer to X. INTEGER(X) Integer X converted to integer. LOGICAL(X) Logical X converted to logical. REAL(X) Real X converted to real. STRING(X) String X converted to string. TYPE(X) String The type of X (‘REAL’, ‘INTEGER’, ‘LOGICAL’, ‘STRING’, or ‘UNDEFINED’). UNDEFINED(X) Logical TRUE if X is undefined.
Miscellaneous Functions—
 DATE() String Current date. TIME() String Current time. GETNBS(S) Any Value of noticeboard item. GET_SYMBOL(S) String Value of DCL symbol. INKEY() Integer Key value of last key trapped (Screen mode only). KEYVALS(S) Integer Value of key with name S. OK(stat) Logical True if VMS Status OK. FILE_EXISTS(S) Logical True if file S exists. RANDOM(I) Real Random number between 0 and 1 from seed variable I. VARIABLE(proc,X) Any Returns value of variable X of procedure proc.

### 19.4 Exceptions

 Name Description ADAMERR An error has occurred in an ADAM task. An associated message will be output. ASSNOTVAR An assignment has been made to a procedure formal parameter which does not correspond to a variable in the procedure call. CLOSEERR Error closing text file. CONVERR Error converting RA or Dec to string or vice versa. CTRLC A Control-C has been entered on the terminal. DEVERR Error allocating or mounting device. EDITERR Attempt to use the LSE or TPU editors when they are not available. EOF End of file encountered on text file operation. FIGERR Error in a FIGARO program, or FIGARO not available. FLTDIV Floating point division by zero. FLTOVF Floating point overflow. IFERR The expression in an IF or ELSE IF statement does not evaluate to a logical value. INTOVF Integer overflow. INVARGMAT Invalid argument to a mathematical function. INVSET Invalid SET command. LOGZERNEG Logarithm of zero or negative number. NBSERR Error in GETNBS or PUTNBS. OPENERR Error opening text file. OPNOTLOG Operands of a logical operator (AND, OR etc.) are not logical values. OPNOTNUM Operands of a formatting operation (:) are not numeric. PROCERR Unrecognized procedure or command name. READERR Error reading from text file. RECCALL Attempt to make a recursive call of a procedure. SCREENERR Error in screen mode I/O. SQUROONEG Square root of negative number. STKOVFLOW ICL’s stack has overflowed. STKUNDFLOW ICL stack underflow — if this occurs it indicates an internal error in ICL. TOOFEWPARS Not enough parameters for a function or command. TOOMANYPARS Too many parameters for a procedure or command. UNDEFVAR Attempt to use an undefined variable — i.e. one that has not yet had a value assigned. UNDEXP Undefined Exponentiation. USERERR Error accessing a routine defined using DEFUSER, or error during such a routine. WHILEERR The expression in a WHILE statement does not evaluate to a logical value. WRITERR Error writing to text file.