## Appendix BICL Commands

B.1 ALLOC
B.3 APPEND
B.5 CLEAR
B.6 CLOSE
B.7 CREATE
B.8 CREATEGLOBAL
B.9 (DCL)
B.10 DEALLOC
B.11 DEFAULT
B.12 DEFHELP
B.13 DEFINE
B.14 DEFPROC
B.15 DEFSHARE
B.16 DEFSTRING
B.18 DEFUSER
B.19 DELETE
B.20 DISMOUNT
B.22 EDIT
B.23 ENDOBEY
B.24 EXIT
B.25 GET
B.26 GETGLOBAL
B.27 GETNBS
B.28 GETPAR
B.29 HELP
B.30 INPUT
B.31 INPUTI
B.32 INPUTL
B.33 INPUTR
B.34 KEY
B.35 KEYTRAP
B.36 KEYUSER
B.37 KILL
B.38 KILLDCL
B.39 KILLW
B.40 LIST
B.44 MOUNT
B.45 NOREP
B.46 OBEYW
B.47 OPEN
B.48 PRINT
B.49 PROCS
B.50 PUTNBS
B.55 REPFILE
B.56 REPORT
B.57 SAVE
B.58 SAVEINPUT
B.59 SEND
B.60 SET
B.60.1 SET ATTRIBUTES

B.60.4 SET EDITOR
B.60.5 SET HELPFILE

B.60.7 SET PRECISION
B.60.8 SET PROMPT
B.60.9 SET SAVE, SET NOSAVE
B.60.10 SET SCREEN, SET NOSCREEN
B.60.11 SET TRACE, SET NOTRACE
B.61 SETGLOBAL
B.62 SETPAR
B.63 SIGNAL
B.64 SPAWN
B.65 STARTOBEY
B.67 VARS
B.68 WAIT
B.69 WRITE

### B.1 ALLOC

ALLOC   dev   [(actdev)]   [(status)]

Allocate a device:

dev
- The name of the device to be allocated This may be a generic name in which case the first available device will be allocated.
actdev
- (optional) A variable in which the name of the device actually allocated will be returned.
status
- (optional) A variable in which the status of the allocate request will be returned. The success of the request may be tested using the function OK(status).

### B.12 DEFHELP

DEFHELP   name   help_library   [topic...]

Allows the ICL HELP command to be able to access information in other help libraries.

name
- The Help name to be defined.
help_library
- The Help library to be used.
topic...
- An optional list of keywords specifying the path within help_library to the required information. If omitted, topic defaults to name.

After name has been defined in this way

ICL> HELP name

will return the topic information in help_library.

### B.13 DEFINE

command
- The command to be defined. An abbreviation may be specified in the form COM(MAND) where COM is the minimum acceptable abbreviation.
- The task which will execute the OBEYW.
action
- (optional) The action to be executed. If omitted it defaults to command.

Once a command has been defined then

ICL> command . . .

is equivalent to typing

ICL> OBEYW taskname action . . .

with any parameters of command being appended to the OBEYW as the VALUE string sent to the task.

### B.14 DEFPROC

DEFPROC   command   file   [procedure]

Define a command which runs a procedure from a source file.

command
- The command to be defined. An abbreviation may be specified in the form COM(MAND) where COM is the minimum acceptable abbreviation.
file
- The source file containing the procedure.
procedure
- (optional) The procedure to be executed. If omitted it defaults to command.

When command is issued, file.ICL is loaded and compiled (if it is not already loaded) and the procedure is called. Any parameters specified with the original command are passed to the procedure.

### B.15 DEFSHARE

DEFSHARE   command   image   [action]

Define a command which issues an OBEYW to an ADAM shareable image monolith

command
- The command to be defined. An abbreviation may be specified in the form COM(MAND) where COM is the minimum acceptable abbreviation.
image
- The logical name of the shareable image monolith which will execute the OBEYW.
action
- (optional) The action to be executed. If omitted it defaults to command.

Once a command has been defined with DEFSHARE then

ICL> command . . .

is equivalent to typing

ICL> OBEYW taskname action . . .

with any parameters of command being appended to the OBEYW as the VALUE string sent to the task. The task must be linked into a shareable image monolith rather than a normal executable task.

### B.16 DEFSTRING

DEFSTRING   command   equivalence_string

Associate a command with an equivalence string.

command
- The command to be defined. An abbreviation may be specified in the form COM(MAND) where COM is the minimum acceptable abbreviation.
equivalence_string
- The equivalence string for the command.

Issuing the command is equivalent to typing the equivalence string. Any parameters of the command are appended to the equivalence string.

command
- The command to be defined. An abbreviation may be specified in the form COM(MAND) where COM is the minimum acceptable abbreviation.
- (optional) The task which will receive the SEND. If omitted it defaults to command.

Once a command has been defined using DEFTASK then

ICL> command . . .

is equivalent to typing

ICL> SEND action . . .

the parameters of command must supply the CONTEXT (GET, SET, OBEY, CANCEL) and the parameter or action name to be sent to the task.

### B.18 DEFUSER

DEFUSER   command   image   [routine]

Define a command which calls a user written subroutine in a shareable image.

command
- The command to be defined. An abbreviation may be specified in the form COM(MAND) where COM is the minimum acceptable abbreviation.
image
- The name of the shareable image containing the routine. This must be a logical name if the image is not in SYS\$SHARE.
routine
- (optional) The name of the subroutine to be called. This must be a universal symbol of the shareable image. If omitted it defaults to command.

The subroutine should have a single character string parameter in which it will receive the ICL command line parameter string. The string is received as typed, except for the substitution of bracketed expressions.

Typing command causes the shareable image to be activated dynamically (if it is not already loaded), and the subroutine to be called. The subroutine can return an error message to ICL by signalling a VMS condition. This will result in the ICL exception USERERR. The exception text will contain the message associated with the VMS status returned.

### B.19 DELETE

DELETE   proc

Delete procedure proc from the procedure table.

### B.20 DISMOUNT

Dismount a tape previously mounted using the ICL MOUNT command. The NOUNLOAD parameter if specified means that the tape will be dismounted without unloading.

DISMOUNT may be abbreviated to DISMOU

This command causes the ADAM task of name taskname to output a stack dump on the terminal from which it was loaded. For this command to be effective, the task must include a call to DTASK_SETDUMP(STATUS).

### B.22 EDIT

EDIT   proc

Edit procedure ‘proc’ using the selected editor. If the name of the procedure is unchanged during the editing session the new version replaces the old one. If the name is changed a new procedure is created and the old version of ‘proc’ remains unchanged. By default the TPU editor is used. The editor may be changed to EDT or LSE using the SET EDITOR command.

To edit a file use the command:

DCL EDIT filename

### B.23 ENDOBEY

ENDOBEY   (path)   (messid)

path
- The path associated with the action.
messid
- The message identifier associated with the action.

### B.24 EXIT

EXIT

EXIT from ICL and return control to DCL. On exiting from ICL a copy of all the current procedures is saved in the file SAVE.ICL

### B.25 GET

Get a parameter of an ADAM I-task and put the value into an ICL variable.

- The name of the I-task.
parameter
- The name of the parameter to be got.
variable
- The ICL variable into which the value will be put.

### B.26 GETGLOBAL

GETGLOBAL   parameter   (variable)

Get the value of a ADAM global parameter

parameter
- The name of the global parameter to be got.
variable
- An ICL variable to receive the result.

### B.27 GETNBS

GETNBS   nbsname   (variable)

Get the value of a noticeboard item

nbsname
- The name of the noticeboard item to be got.
variable
- An ICL variable to receive the result.

The noticeboard name must correspond to a primitive item with one of the standard HDS types (e.g. _INTEGER). A dot notation is used to specify structure components (e.g. NOTICEBOARD.ITEM1.ITEM2). If the primitive item is an array only the first component is accessed.

### B.28 GETPAR

GETPAR   command   parameter   (variable)

Get the value of a parameter from the task’s parameter file. This will only be relevant for parameters which are not internal.

command
- A command name associated with an ADAM task by means of a DEFINE command. The task will usually be an A-task or monolith.
parameter
- The name of the parameter to be got.
variable
- An ICL variable to receive the result.

### B.29 HELP

HELP   [topic...]

Provide on line documentation on some aspect of ICL, or on some other topic which has been made available using the DEFHELP command.

topic...
- An optional list of keywords specifying the path within the help library to the required information. The first keyword may be the name specified in a DEFHELP command.

### B.30 INPUT

INPUT   [prompt]   (string)

Input a string from the terminal.

prompt
- (optional) A prompt string to be output on the terminal
string
- A variable into which the input string will be read.

### B.31 INPUTI

INPUTI   prompt   (i)   (j) ....

Input integers from the terminal

prompt
- A prompt string to be output on the terminal.
i,j etc
- The variables into which integers will be read.

### B.32 INPUTL

INPUTL   prompt   (l)   (m) ....

Input logical values from the terminal

prompt
- A prompt string to be output on the terminal.
l,m etc
- The variables into which logical values will be read.

The logical values may be input as YES, NO, TRUE, FALSE or any abbreviation of these, in either upper or lower case.

### B.33 INPUTR

INPUTR   prompt   (x)   (y) ....

Input real numbers from the terminal

prompt
- A prompt string to be output on the terminal.
x,y etc
- The variables into which the numbers will be read.

### B.34 KEY

KEY   keyname   equivalence_string

Define an equivalence string for a key

keyname
- The name of the key
equivalence_string
- The equivalence string for the key. A # character may be used to indicate a RETURN character terminating the string.

The KEY command may be used at any time but the definition is only effective when screen mode is in use (however, the first SET SCREEN call in a session clears all key definitions).

### B.35 KEYTRAP

KEYTRAP   keyname

Specify trapping of a key

keyname
- The name of the key

The KEYTRAP command may be used at any time but the definition is only effective when screen mode is in use (however, the first SET SCREEN call in a session clears all key definitions). The INKEY function is used to test for the pressing of a trapped key.

### B.36 KEYUSER

KEYUSER   keyname   image   routine

Associate key with a user written subroutine in a shareable image

keyname
- The name of the key
image
- logical name of the shareable image
routine
- name of the subroutine to be called. This must be a universal symbol of the shareable image.

The KEYUSER command may be used at any time but the definition is only effective when screen mode is in use (however, the first SET SCREEN call in a session clears all key definitions). KEYUSER causes the specified routine to be called at AST level immediately the key is pressed. If necessary the shareable image is activated dynamically

### B.37 KILL

- The name of the task to be killed.

### B.38 KILLDCL

KILLDCL

Kill the DCL subprocess

### B.39 KILLW

- The name of the task to be killed.

### B.40 LIST

LIST   proc

List procedure ‘proc’ on the terminal

Accept commands from ‘file.ICL’ rather than from the terminal.

‘file’ may specify a procedure previously saved using the SAVE command.

exename
- The name of the executable image file to be used for the task.
- (optional) The name of the task to be created. If omitted it defaults to the file name part of exename.
priority
- (optional) The priority for the created task.

exename
- The name of the executable image file to be used for the task.
- (optional) The name of the task to be created. If omitted it defaults to the file name part of exename.

### B.44 MOUNT

MOUNT   dev   [ (status) ]

Mount a tape - equivalent to the DCL MOUNT/FOREIGN command. The tape is mounted as a foreign tape at its initialized density.

The optional parameter status is a variable in which the status of the mount operation will be returned. The success of the operation may be tested using the function OK(status).

MOUNT may be abbreviated to MOU.

### B.45 NOREP

NOREP

Turn off reporting. Reporting is turned on by the REPORT command.

### B.46 OBEYW

OBEYW   taskname   action . . .

- The name of the task to which the obey message will be sent.
action
- The action name to be obeyed.
. . .
- Any parameters for the action.

### B.47 OPEN

OPEN   intname   [filename]

Open an existing text file for input.

intname
- The internal name by which the file will be known within ICL.
filename
- The VMS file name of the file. If omitted the file name will be intname.DAT.

### B.48 PRINT

PRINT   p1   p2 ....

The parameters of PRINT are concatenated and printed on the terminal.

### B.49 PROCS

PROCS

List the names of all current procedures.

### B.50 PUTNBS

PUTNBS   nbsname   value

Write the value of a noticeboard item

nbsname
- The name of the noticeboard item to be written.
value
- The new value for the item.

The noticeboard name must correspond to a primitive item with one of the standard HDS types (e.g. _INTEGER). A dot notation is used to specify structure components (e.g. NOTICEBOARD.ITEM1.ITEM2). If the primitive item is an array, only the first component is accessed.

Read a line from a text file.

intname
- The internal name of the text file. The file must have been opened with the OPEN command.
string
- A variable into which the input string will be read.

Read a line of integers from a text file.

intname
- The internal name of the text file. The file must have been opened with the OPEN command.
i,j etc
- The variables into which integers will be read.

Read a line of logical values from a text file.

intname
- The internal name of the text file. The file must have been opened with the OPEN command.
l,m etc
- The variables into which logical values will be read.

The logical values may be input as YES, NO, TRUE, FALSE or any abbreviation of these, in either upper or lower case.

Read a line of real numbers from a text file

intname
- The internal name of the text file. The file must have been opened with the OPEN command.
x,y etc
- The variables into which the numbers will be read.

### B.55 REPFILE

REPFILE   [logfile]   [DTNS]

Examine a logfile

logfile
- Name of the logfile to be examined - defaults to ADAM_LOGFILE
DTNS
- Four character string specifying which items in each log record are displayed. D = Date, T = Time, N = Name, S = String. Replace the item letter by anything else to stop the display of that item. DTNS is case independent.

### B.56 REPORT

REPORT   [logfile]

Turn on reporting. After reporting has been turned on, a log of input/output and ADAM message system traffic is written to the file specified by logfile. If the parameter is omitted the logical name ADAM_LOGFILE is used. If the file already exists, the log is appended to it.

The logfile may be examined using the REPFILE command or by the ADAM task, LISTLOG. LISTLOG is found along the ADAM_EXE search path and provides a means of obtaining readable hardcopy of the log. A DCL symbol LISTLOG is defined by ADAMSTART to run this task from DCL.

The command NOREP turns off reporting.

### B.57 SAVE

SAVE   proc

Save procedure ‘proc’ in the file ‘proc.ICL’.

SAVE ALL

Save all procedures in file ‘SAVE.ICL’.

### B.58 SAVEINPUT

SAVEINPUT   lines   filename

Save previous input lines in a text file. ‘lines’ specifies the number of lines to be saved, and ‘filename’ is the file in which they are saved. If ‘filename’ is omitted it defaults to SAVEINPUT.ICL in the default directory. If ‘lines’ is omitted the entire input buffer is saved.

### B.59 SEND

SEND   taskname   context   . . .

- The name of the task to which the message will be sent. It must correspond with taskname in the ALOAD, LOADW or DEFINE command and include any directory specification given there.
context
- The context (GET, SET, OBEY or CANCEL).
. . .
- The remainder of the message. This will depend upon context.
SET
parameter value
parameter
- The name of the parameter whose value is to be set.
value
- The value to be set. Type conversion will be done where necessary.
GET
parameter
parameter
- The name of the parameter. Its value will be displayed.
OBEY
action parameters
action
- The name of the action to be obeyed.
parameters
- the parameter string for action.
CANCEL
action parameters
action
- The name of the action to be cancelled.
parameters
- the parameter string for action.

OBEY, SET and GET contexts may be used with A-task monoliths. In that case, action is replaced by atask and parameter by atask:parameter where atask is the name of the individual A-task within the monolith.

### B.60 SET

The SET command is used to control various features of the state of ICL.

#### B.60.1 SET ATTRIBUTES

SET ATTRIBUTES   attributes

Sets the attributes for text written with the LOCATE command. attributes is a string containing any combination of the letters D (double size), B (bold), R (Reverse video), U (underlined) and F (flashing).

#### B.60.3 SET CHECKPARS, SET NOCHECKPARS

SET CHECKPARS

SET NOCHECKPARS

Switches on/off the checking of parameters supplied to ICL procedures. ICL’s default is CHECKPARS – in that case a procedure will not be executed unless the correct number of parameters is supplied. NOCHECKPARS allows the procedure to use the UNDEFINED function to test if the parameter was supplied and prompt if not. Note that only trailing parameters may be omitted.

#### B.60.4 SET EDITOR

SET EDITOR   name

Sets the editor to be used for editing of ICL procedures. name must be one of TPU, EDT or LSE. (LSE may not be available on all systems). The default editor is TPU.

#### B.60.5 SET HELPFILE

SET HELPFILE library

Specifies a help library to be used by the ICL HELP system for topics other than those specified by a DEFHELP command. The library specification library should include a directory specification.

The default help library is ICLDIR:ICLHELP.

SET MESSAGES

SET NOMESSAGES

#### B.60.7 SET PRECISION

SET PRECISION   digits

Set the number of decimal digits precision for unformatted conversions of real values to strings. The default value is 6 and may be set to any value between 1 and 16.

#### B.60.8 SET PROMPT

SET PROMPT   string

This command can be used to specify a prompt string to replace the default ICL$>$ prompt.

#### B.60.9 SET SAVE, SET NOSAVE

SET SAVE

SET NOSAVE

This command controls whether ICL procedures are saved in a SAVE.ICL file when ICL exits. By default a SAVE.ICL file is created if there are any procedures to save.

#### B.60.10 SET SCREEN, SET NOSCREEN

SET SCREEN n

SET NOSCREEN

These commands select screen I/O mode or normal I/O mode. On the SET SCREEN mode the parameter n specifies the number of lines in the scrolling region. If n is omitted eight lines of scrolling region are allocated.

#### B.60.11 SET TRACE, SET NOTRACE

SET TRACE

SET NOTRACE

These commands turn on and off the tracing of procedure execution. By default tracing is off. When tracing is on, each line of the procedure is output on the terminal before execution.

### B.61 SETGLOBAL

SETGLOBAL   parameter   value

Set the value of a ADAM global parameter

parameter
- The name of the global parameter to be set.
value
- The value for the parameter. It should not be enclosed in quotes unless the quotes are required as part of the global parameter value.

If the global parameter does not exist, one of type _CHAR*132 is created. This is usually OK but could give problems with _LOGICAL parameters. The CREATEGLOBAL command can be used to create global parameter storage of a specific type.

### B.62 SETPAR

SETPAR   command   parameter   value

Set the value of a parameter into the task’s parameter file. This will only be relevant for parameters which are not internal.

command
- A command name associated with an ADAM task by means of a DEFINE command. The task will usually be an A-task or monolith.
parameter
- The name of the parameter to be set.
value
- The value for the parameter.

If the parameter value is an HDS object name or device name it must be prefixed by @. SETPAR sets the current value of the parameter. Thus the VPATH or PPATH must include CURRENT for SETPAR to have any effect on subsequent execution of the command. Note that if the task is loaded, it will probably have its parameter file open and locked against ICL writing into it.

### B.63 SIGNAL

SIGNAL   name   [text]

Signal an ICL exception

name
- The exception name — any valid ICL identifier.
text
- A message text associated with the exception.

Following SIGNAL an exception handler will be executed if one exists for the exception. Otherwise a message will be output, and control will return to direct mode.

### B.64 SPAWN

SPAWN   [ dcl_command ]

SPAWN with parameters concatenates the parameters to form a DCL command. creates a subprocess, and executes the DCL command in the subprocess.

SPAWN with no parameters creates a subprocess in which a series of DCL commands may be executed. Use LOGOUT to return to ICL.

In most cases DCL is a faster alternative to SPAWN as the subprocess does not have to be created for each new command. However SPAWN will do a few things which are not possible under DCL. SPAWNed commands will prompt for their parameters, for example, whereas commands issued using DCL will not.

### B.65 STARTOBEY

STARTOBEY   (path)   (messid)   task   action   value

Send an OBEY message to an ADAM task and return the path and message-id. Used in conjunction with ENDOBEY to set up multiple concurrent actions in a I-task.

path
- An ICL variable to receive the path associated with the action.
messid
- An ICL variable to receive the message identifier associated with the action.
- The task to which the OBEY message will be sent.
action
- The action to be executed.
value
- Any parameters associated with the action.

### B.67 VARS

VARS   [ proc ]

Lists the variables of procedure ‘proc’ with their current types and values. VARS with no parameters lists the variables at direct mode.

### B.68 WAIT

WAIT interval

Wait for a specified interval expressed in seconds.

### B.69 WRITE

WRITE intname   p2   p3 ....

The parameters of WRITE are concatenated and written to the text file of name intname. This file must have been previously opened with an APPEND or CREATE command.