3 Getting started

 3.1 Running KAPPA
 3.2 Issuing Commands
 3.3 Obtaining Help
 3.4 Changing the Current Directory in ICL
 3.5 Exiting an Application

3.1 Running KAPPA

Kappa runs from the C-shell and variants, and also from the interactive command language—ICL. Both run monolithic programmes for efficiency. Both have their advantages and disadvantages. Of the latter, the shell forces you to escape certain characters, and ICL does not have a foreach to loop through a wildcarded list of NDFs. You may simply prefer the familiar shell to ICL, though UNIX commands, including editing, are accessible from ICL via a ! prefix. This is not the soapbox to expound the intrinsic merits of the two command languages, but where there are differences affecting Kappa, they’ll be indicated. The choice is yours.

To run Kappa from the shell just enter the following command.

       % kappa

This executes a procedure setting up aliases for Kappa’s command names and to make help information available. Then you’ll be able to mix Kappa commands with the familiar shell ones.

If the kappa command is not recognised, you probably haven’t enabled the Starlink software. In your .cshrc or .tcshrc file, you insert the line

       source /star/etc/cshrc

and in .login you include the equivalent line

       source /star/etc/login

At non-Starlink sites the /star path may be different.

To run Kappa from ICL you have to start up the command language if you are not already using it. This requires just one extra command, namely

       % icl

You will see any messages produced by system and user procedures, followed by the ICL> prompt. Again there is a procedure for making the commands known to the command language, and not unexpectedly, it too is

       ICL> kappa

Then you are ready to go. Not too painful, was it? In either case you’ll see message from Kappa telling you which version is ready for use.

So what do you get for your trouble? ?? lists in alphabetical order all the commands and their functions, and there is a classified list of the same commands. Many examples are given in subsequent sections.

3.2 Issuing Commands

To run an application you then can just give its name—you will be prompted for any required parameters. Alternatively, you may enter parameter values on the command line specified by position or by keyword. More on this in Parameters

Commands are interpreted in a case-independent way from ICL, but from the shell they must be given in lowercase. In ICL, commands may also be abbreviated provided they are unambiguous strings with at least four characters. Commands shorter than five characters, therefore, cannot be shortened. So

       ICL> CREF
       ICL> crefr
       ICL> CreFra

would all run CREFRAME. Whereas

       ICL> FITS
       ICL> FITSI

would be ambiguous, since there are several commands beginning FITS, and two starting FITSI, namely FITSIN and FITSIMP.

Note if other packages are active there is the small possibility of a command-name clash. Issuing such a command will run that command in the package last activated. You can ensure running the Kappa command by inserting a kap_ prefix before the command name. For example,

        % kap_rotate

will execute Kappa’s ROTATE application. There may also be a clash with UNIX commands and shell built-in functions, though there are now far fewer conflicts than in earlier versions of Kappa, with only look being ambiguous. There is also a glob in the C-shell which might confuse you should you forget that GLOBALS cannot be abbreviated from the shell.

Since the KAPPA commands are the same in both the shell and ICL, the % and ICL> prompts in the examples and description in subsequent pages are interchangeable unless noted otherwise.

3.3 Obtaining Help

3.3.1 Hypertext Help

A modified version of this document exists in hypertext form. One way to access it is to use the showme command

       % showme sun95

and a Web browser will appear, presenting the index to the hypertext form of this document. The hypertext permits easy location of referenced documents and applications. It also includes colour illustrations.

The findme command lets you search the Starlink documents by keywords. For instance,

       % findme masking

searches the document looking for the word ‘masking’ in them. The level of searching depends on whether a match is found. The search starts with the document title, the page (section) titles, and finally the document text. The deeper the search, the longer it will take. There are switches provided to limit the level of the search. The search string may include sed or grep regular expressions. See SUN/188 or enter

       % findme findme
       % findme showme

to learn more about the findme and showme commands.

3.3.2 Entering the Help System

To access the Kappa help use KAPHELP.

       ICL> kaphelp

The system responds by introducing Kappa’s help library, followed by a long list of topics for which help is available, followed by the prompt Topic?. These topics are mostly the commands for running applications, but they also include global information on matters such as parameters, data structures and selecting a graphics device.

From ICL you can issue other commands for obtaining help about Kappa.

       ICL> help kappa
       ICL> help packages

The former is nearly equivalent to entering kaphelp. However, it is less easy to use as it lacks many of the navigational aids of KAPHELP. The latter gives a summary of Starlink packages available from ICL. If you select the KAPPA subtopic, you’ll get a precis of the package’s facilities. (This is part of an index of Starlink packages.)

If you have commenced running an application you can still access the help library whenever you are prompted for a parameter. See Entering the Help System for details.

3.3.3 Navigating Help Hierarchies

The help information is arranged hierarchically. The help system enables you to navigate the library by prompting when it has either presented a screen’s worth of text or has completed displaying the previously requested help. The information displayed by the help system on a particular topic includes a description of the topic and a list of subtopics that further describe the topic.

You can select a new topic by entering its name or an unambiguous abbreviation. If you press the carriage-return key (<CR>) you will either continue reading a topic where there is further text to show, or move up one level in the hierarchy. Entering a CTRL/D (pressing D whilst holding the CTRL key) terminates the help session. See the description of KAPHELP for a full list of the options available at prompts inside the help system, and the rules for wildcarding and abbreviating topics.

3.3.4 Help on KAPPA commands

Help on an individual Kappa application is simply achieved by entering kaphelp followed by the command name, for example

       % kaphelp centroid

will give the description and usage of the CENTROID command. There are subtopics which contain details of the parameters, including defaults, and valid ranges; examples; notes expanding on the description; implementation status; and occasionally timing. For example,

       ICL> kaphelp hist param ndf

gives details of Parameter NDF in all applications prefixed by HIST.

(From ICL you can also invoke its help system, thus

       ICL> help centroid

is similar to kaphelp centroid, though the ICL system has drawbacks, and you are recommended to run KAPHELP.)

The instruction

       ICL> kaphelp classified

displays a list of subject areas as subtopics. Each subtopic lists and gives the function of each Kappa application in that classification. There is also an alphabetic list which can be obtained directly via the command

       ICL> kaphelp summary

3.4 Changing the Current Directory in ICL

You should change default directories in ICL using its DEFAULT command, and not cd. Thus

       ICL> default /home/scratch/dro

makes /home/scratch/dro the default directory for the ICL session, and for existing and future subprocesses, including application packages.

3.5 Exiting an Application

In normal circumstances when you’ve finished using Kappanothing need be done from the shell, but to end an ICL session, enter the EXIT command to return to the shell.

What if you’ve done something wrong, like entering the wrong value for a parameter? If there are further prompts you can enter the abort code !! to exit the application. This is recommended even from the shell because certain files like your NDFs may become corrupted if you use a crude CTRL/C. If, however, processing of the data has begun in the application, it is probably best to let the task complete, unless it is a long job like image deconvolution. If you really must abort, CTRL/C should be hit. From ICL this ought to return you to a prompt, but the processing will continue. Then you can stop the running process by ‘killing’ it. First find the task name

       ICL> tasks
                             TASKNAME  Process Id
                     ndfpack_mon16528  15186

and then kill it.

       ICL> kill ndfpack_mon16528

This removes a the NDFPACK monolith. NDFPACK will be loaded again once you enter one its commands. If pressing CTRL/C several times fails to return you to an ICL prompt then it’s time for the heavy artillery—you may have to kill your window. Once back to the shell enter icl to return to ICL, and then kill the process as described above.

If you have interrupted a task, it may be necessary to delete the parameter file (Section 4.2) and the graphics database (Section 11.4).