Chapter 9
Using ADAM for Data Reduction

 9.1 A-tasks
 9.2 Monoliths
 9.3 Running KAPPA
 9.4 ADAM Parameter Format
 9.5 KAPPA from Procedures
 9.6 Error Reports

9.1 A-tasks

When ADAM is used for data reduction, ICL is used to communicate with one or more A-tasks or application tasks which contain the data reduction programs. Each of these tasks can be associated with an ICL command by means of the DEFINE command. When the associated ICL command is issued the A-task will be loaded and executed. If the same ICL command is issued a second time the task will not normally need to be reloaded so that execution will be faster. However, if too many tasks are loaded one of these tasks may have to be killed before another can be loaded. The maximum number of tasks allowed to be loaded at one time has a default value of three, but may be adjusted, on a system basis, by the system logical name ADAM_CACHLIMIT. The least recently used task is always selected for killing when the limit is exceeded. This process is known as task caching and such tasks are referred to as cached tasks.

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:

      $ 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

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

      ICL> ADD
      Loading KAPPA_DIR:KAPPA into 0591KAPPA
      IN1 - First input NDF> IM1
      IN2 - Second input NDF> IM2
      OUT - Output NDF> SUM

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.

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

      ICL> ADD IM1 IM2 SUM

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.

9.4 ADAM Parameter Format

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

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:


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’’’
           ADD  SUM  (SNAME(’RUN’,I))  SUM  TITLE=(TITLE)
         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:

      ICL> ADD
      Loading KAPPA_DIR:KAPPA into 0591KAPPA
      IN1 - First input NDF > !
      !! Null NDF structure specified for the IN1 parameter
      !  ADD: Error adding two NDF data structures
      ADAMERR   %PAR, Null parameter value

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 @.