Chapter 9Using ADAM for Data Reduction

9.2 Monoliths

9.2 Monoliths

To avoid frequent loading and killing of tasks, large data reduction packages are normally organized as Monoliths or M-tasks. A monolith is a single task which contains a large number of independent programs which would otherwise be separate A-tasks. Thus a monolith will have many commands associated with it, whereas an A-task only has a single command. The monolith will be loaded when the first command is issued and then any of the other monolith commands may be issued without requiring the task to be reloaded.

9.3 Running KAPPA

An example of an ADAM monolith is the Starlink Kernel Applications Package (KAPPA). KAPPA is described in more detail in the Starlink document SUN/95. To run KAPPA type:

$ADAM KAPPA This is actually a convenient way of combining the commands1:$ ADAMSTART
\$ ICL
ICL> KAPPA

To run any ADAM task from ICL it is necessary to have obeyed the command ADAMSTART in DCL before running ICL. If you use ADAM tasks frequently, you may include this command in your LOGIN.COM file. The ADAM procedure will not obey ADAMSTART again if it has already been obeyed, although it wouldn’t matter if it did.

When the command KAPPA is obeyed in ICL, you will see

Help key KAPPA redefined

--    Initialized for KAPPA   --
--   Version 0.8, 1991 August --

Type HELP KAPPA or KAPHELP for KAPPA help
ICL>

The KAPPA command causes all the individual commands of the KAPPA monolith to be defined and then outputs its initialization message. It does not cause the KAPPA monolith itself to be loaded. This occurs when the first KAPPA command is issued.

The simplest way of using KAPPA is to type just the command names. You will then be prompted for all the required parameters. For example, to use the ADD command which adds two images just type ADD and the following dialogue will result

IN1 - First input NDF> IM1
IN2 - Second input NDF> IM2
OUT - Output NDF> SUM
ICL>

The above command causes the images contained in HDS data files IM1.SDF and IM2.SDF to be added and the result placed in a new file called SUM.SDF.

Since this is the first KAPPA command the monolith needs to be loaded, and a loading message2 is output which tells us the name of the task being created, in this case 0591KAPPA3.

Each parameter prompt consists of three parts, the name of the parameter (e.g. IN1), a brief description (First input NDF4), and in some cases a suggested value enclosed between / characters.

When responding to a parameter prompt the user has several options.

• Just hit the return key. The suggested value will be used.
• Type in a new value.
• Hit the TAB key. This causes the suggested value to be placed in the input buffer. It can then be edited by the normal command line editing keys.
• Enter ! — the NULL value. The effect of doing this will depend upon the application but frequently causes termination.
• Enter !! — by convention, this causes the program to be aborted.
• Enter ? or ?? — this causes the help system to be entered, giving further information on the parameter and/or the application (assuming that such text has been provided by the application implementor5).

If the parameters of a command are known they can be placed on the command line itself. Thus the above example would become:

In this example it is important to get the parameters in the right order. If we are not sure about the order of the parameters, but know their names we can specify the parameters by name on the command line.

ICL> ADD OUT=SUM IN1=IM1 IN2=IM2 TITLE=’Sum of 2 Images’

TITLE is an example of a parameter which can only be specified using the ‘name=’ syntax as it has not been allocated a position in the order of parameters. If TITLE is not specified, a default value will be used.

ADAM task parameters can be of a number of different types as follows:

• Numbers — These can be Integer, Real or Double Precision and are entered in the usual format (e.g. as in FORTRAN)
• Strings — These are represented in the usual ICL formats. Quotation marks may be omitted where there is no ambiguity. In the above example they were necessary on ‘Sum of 2 images’ when used on the command line as the spaces would otherwise make it appear to be four different parameters. However, they would not be needed for the same string in response to a single parameter prompt.
• Logical values — These can be represented by the words TRUE, FALSE, YES, NO, T, F, Y or N, regardless of case.
• Arrays — arrays of any of the above items may be represented by a list of values enclosed in square brackets, e.g. [1, 2, 3]. Two dimensional arrays may be represented as [ [1, 2], [3, 4] ] etc. The outer brackets may be omitted when responding to a prompt.
• Names — These are the names of HDS (hierarchical data system) objects or files, or the names of devices (graphics devices, tape drives etc.). Normally these names can be typed directly as MTA0, ARGS etc, but there are a few cases of ambiguity. These cases can be resolved by prefixing the name with an @ character. For example, if it is required to specify an HDS container file with a name different from that of the object it contains, or with a specific generation number, the file specification can be enclosed in quotes (e.g. "data.sdf;3"). However, this would be interpreted as a character string unless prefixed with @. Suggested values in prompts are always displayed prefixed with @.

9.5 KAPPA from Procedures

ICL becomes particularly useful when a series of KAPPA operations are to be performed on a sequence of files. We can then use an ICL procedure for this purpose. In such cases we will probably want to use an ICL variable or expression to specify at least one of the parameter names. This is perfectly acceptable provided the expression is placed in parentheses so that it will be evaluated and not treated as a string. A frequent occurrence is that we want to process a sequence of files which have names such as RUN1, RUN2, RUN3 etc. ICL therefore provides a function SNAME to generate such sequential names 6. It has the form:

SNAME(string,n,m)

and produces a name which is the concatenation of the string with the integer n. An optional third parameter m specifies a minimum number of digits for the numeric part of the name, leading zeros are inserted if necessary to produce at least m digits.

SNAME(’@RUN’,3)      has the value   ’@RUN3’
SNAME(’@IPCS’,17,3)  has the value   ’@IPCS017’

The latter example being the format of name produced directly by the IPCS observing software at the AAT. Using this way of specifying the name it is easy to write an ICL procedure to add a whole series of images together using the KAPPA ADD command.

{   Add images RUN1 to RUN20 to form SUM  }

ADD RUN1 RUN2 SUM TITLE=’Sum of 2 images’
LOOP FOR I=3 TO 20
TITLE = ’’’Sum of ’ & I:2 & ’ images’’’
END LOOP

END PROC

9.6 Error Reports

In the event of an error occurring in the task, error reports will be displayed. For example:

IN1 - First input NDF > !
!! Null NDF structure specified for the IN1 parameter

The first two messages are issued by the task. Such messages will usually indicate which ADAM subsystem or routine generated them by a prefix (ADD: in the example).

The message starting ‘ADAMERR’ is issued by ICL on receiving a termination message containing a ‘bad’ status. ADAMERR is the name of an ICL exception – the %PAR following ADAMERR tells us that the PAR subsystem within ADAM generated the bad status value.

1In fact, any ICL command may be specified in place of KAPPA in the ADAM command.

2These loading messages can be turned off by the SET NOMESSAGES command, if desired

3The name is prefixed with a number (e.g. 0591) to make a unique process name, so that there is no conflict between your version of KAPPA, and another version run at the same time by another user

4‘NDF’ stands for Extensible N-Dimensional Data Format. For more information see Section 10.7.

5For a detailed description of the parameter help system, see SUN/115.

6Note that for reasons explained in Section 10.5, strings defining names to be used as ADAM task parameters are generally prefixed with @.