next up previous 530
Next: Getting started
Up: Tutorials
Previous: From the C-shell

From ICL

ICL is a command language designed for use with Starlink applications, such as KAPPA. It is now of some antiquity but is still in use. The main advantages for the KAPPA user are that shell metacharacters like []() $ \backslash$ " need not be escaped; command names may be abbreviated; far fewer executables need be loaded, and therefore it is slightly faster than using the shell when you want to invoke more than a few commands on a busy system; there is a wide selection of intrinsic functions and floating-point arithmetic; and results may be passed between applications via ICL variables. However, in these two demonstrations the command languages are interchangeable apart from the accept backslash.

Let's start the second example.

     % icl

This starts ICL. System, local and user-defined ICL login files are invoked. Here there is only a system login procedure which sets up help on Starlink packages, and commands for setting up definitions for those packages. One of those commands is kappa; it is analogous to the kappa command from the shell. We enter it after receiving the ICL prompt.

You should see something like the following.

    ICL (UNIX) Version 3.1-9 14/02/2000

    Loading installed package definitions...

       - Type HELP package_name for help on specific Starlink packages
       -   or HELP PACKAGES for a list of all Starlink packages
       - Type HELP [command] for help on ICL and its commands

     ICL> kappa

        KAPPA commands are now available (Version 1.0).

        Type `help kappa' or `kaphelp' for help on KAPPA commands.

Now we run an application, ADD, that adds the pixels in $KAPPA_DIR/comwest.sdf to those in $KAPPA_DIR/ccdframec.sdf. Although these images have different dimensions, the intersection is made.

     ICL> add $KAPPA_DIR/comwest $KAPPA_DIR/ccdframec

After the first KAPPA command is issued you'll see an arcane message like this.

     Loading /star/bin/kappa/kappa_mon into kappa_mon11601 (attached)

It just tells you that the KAPPA monolith is being loaded. You'll see similar messages for each of the three monoliths when they are first wanted.

Since we did not give the name of the destination NDF that will hold the co-added NDFs, ADD prompts for it. Notice that literal parameters are case insensitive.

     OUT - Output NDF / / > demo1

     ICL> ndftrace \

        NDF structure /home/soft2/mjc/alpha_OSF1/kappa/package/demo1:
           Title:  Comet West, low resolution

            No. of dimensions:  2
            Dimension size(s):  256 x 256
            Pixel bounds     :  1:256, 1:256
            Total pixels     :  65536

        Data Component:
            Type        :  _REAL
            Storage form:  PRIMITIVE
            Bad pixels may be present

This shows that the demo1 NDF has the same dimensions as the smaller of the two NDFs.

We were going to display the image on the current graphics device, but then changed our minds. A !! in response to a prompt aborts a task.

     ICL> display demo1
     MODE - Method to define the scaling limits /'PERCENTILES'/ > !!
     !! SUBPAR: Abort (!!) response to prompt for Parameter MODE
     OBEYW unexpected status returned from task "kapview_mon11601", action
     - "DISPLAY"
     ADAMERR  %PAR, Parameter request aborted

KAPPA uses the graphics database, which records the positions and extents of graphs and images, collectively called pictures.

     ICL> picgrid 2 1

This instruction divides the display surface into two equally sized pictures, side by side. They are labelled 1 and 2 in the database. Picture 1 is the current picture, in which future pictures are drawn, unless we select a new current picture.

Thus in Picture 1 we display an image of Comet West around which we draw annotated axes. The backslash causes the current scaling method to be used.

     ICL> display comwest axes \
     !! Error accessing file '/home/scratch/mjc/comwest.sdf' -
     !     No such file or directory
     !  HDS_OPEN: Error opening an HDS container file.
     !  NDF_ASSOC: Unable to associate an NDF structure with the '%IN' parameter.

DISPLAY could not find the a comwest.sdf in the current directory. So there is an error message and we are prompted. This time we remember to add the environment variable.

     IN - NDF to be displayed /@comwest_bas/ > $KAPPA_DIR/comwest
     Data will be scaled from 67.46276 to 226.5568.

An image of Comet West should be visible to the left of the screen.

SHADOW creates an image that appears like a bas-relief. We've called the resulting NDF comwest_bas. The backslash causes the current NDF to be the input NDF for SHADOW.

     ICL> shadow out=comwest_bas \

We select the right-hand picture created earlier.

     ICL> picsel 2

As above we display the current NDF, the bas-relief image, with annotated axes on the right of the raw comet image (we do not need to request the axes explicitly this time, since the axes parameter retains the value used in the previous invocation until changed).

     ICL> display border \
     Data will be scaled from -4.721756 to 5.697861.

The relief looks best with a grey-scale colour table. Note that this does not affect the colour of the border. LUTGREY is a procedure which calls a more-general application. Since it is the first procedure we've invoked there is a short pause while all the KAPPA procedures are compiled and loaded.

     ICL> lutgrey
     Loading procedure file $KAPPA_DIR/kappa_proc.icl

Next we decide to make a hard copy of the bas-relief image. DISPLAY does this and can add a key of grey levels and their corresponding values. The chosen device is ps_l; this overrides the xwindows device for the duration of DISPLAY. If this name isn't recognised at your site, issue the GDNAMES command for a list of your local device names. Select the landscape PostScript device. We scale between wider limits to reduce the glare.

     ICL> display key=yes device="/PS"
     IN - NDF to be displayed /@comwest_bas/ >
     MODE - Method to define the scaling limits /'SCALE'/ >
     LOW - Low value for display /187.5625/ > 11
     HIGH - High value for display /-183.453125/ > -8.33

DISPLAY does not send your plot to the printer, since this is hardware and node dependent. Therefore, you must issue a shell command from ICL to perform this action. That's not difficult--just insert a ! before the UNIX command, and in most cases just issue the command as if you were in the shell, like we do below.

     ICL> !lpr -P1

Shell aliases may also be used, so if ri equates to rm -i, we could remove any unwanted HDS  files. If you don't have this symbol, as is likely, then you will receive the appropriate error message from ICL.

     ICL> ri *.sdf

That's the end of the second demonstration. Of course, these introductions have only scratched the surface of what KAPPA can do for you. You should look at the classified lists to search for the desired function, and then find more details in the specifications.

If you get stuck or something untoward happens, there is a Hints help topic.

next up previous 530
Next: Getting started
Up: Tutorials
Previous: From the C-shell

KAPPA --- Kernel Application Package
Starlink User Note 95
Malcolm J. Currie & David S. Berry
2013 February 14

Copyright © 2013 Science and Technology Facilities Council