Chapter 2
Getting Started

 2.1 Preliminaries
 2.2 Quotas
 2.3 Starting up ADAM
 2.4 Choice of command language
 2.5 Trying out the command languages
  2.5.1 ICL
  2.5.2 DCL

This chapter gets you started with ADAM. If possible, you should try out the examples on your terminal so you can verify that what is claimed to happen does happen, and you can get a feel for the ADAM system. Any terminal will do — you don’t need image displays or graphics devices.

If you are totally unfamiliar with computers you should read the introductory guide to your local computer system (for example, Introduction to VMS ), or better still get the Starlink site manager or a local user to show you. In the rest of this manual you are assumed to be familiar with basic VMS terms and concepts.

2.1 Preliminaries

Before you switch on your terminal, let us explain how to interpret the examples. The basic principle we use is to show lines as they actually appear on your terminal screen. When the computer wants you to type something it normally displays a prompt. For example, the VAX VMS operating system displays the prompt:


(We indent lines which appear on your terminal screen.) You respond to this prompt by typing something that VMS will understand. For example:

    $ DIR

will cause the contents of your default directory to be displayed on the screen. What you actually type are the characters ‘DIR’, followed by the ‘carriage return’ key1. We will use the word ‘enter’ to mean ‘type and then press carriage return’. A displayed line will consist partly of characters output by the computer, and partly of characters typed in by you. We do not attempt to differentiate between the two by typographical conventions; you will find it obvious which is which when you try out the examples. Sometimes the only key you need to press is the ‘carriage return’ key. Usually, this means that you want to accept a default value offered by the parameter system. For example, you might come across a line like:

    XDIM - x dimension of output array /64/ >

This is output by the computer, and the last character ‘ >’ is an invitation for you to type something. If the line appears like that without any further comment, it means that you respond by pressing ‘carriage return’. Finally, you will find that in most cases you can type input characters in upper or lower case — it doesn’t matter which; they are interpreted as being the same.

Sometimes you need to press a key while holding down the ‘CTRL’ key. This is the way you send ‘control codes’ to the computer. This is indicated typographically by the convention ‘ctrl/x’, where ‘x’ is the other key you press. For example, ‘ctrl/Z’ means ‘press the Z key while holding down the CTRL key’.

2.2 Quotas

You must have sufficient VMS process quotas for running ADAM. Typical quotas required are as follows:

CPU limit: Infinite Direct I/O limit: 18
Buffered I/O byte count quota: 65400 Buffered I/O limit: 18
Timer queue entry quota: 10 Open file quota: 74
Paging file quota: 49000 Subprocess quota: 10
Default page fault cluster: 64 AST quota: 23
Enqueue quota: 100 Shared file limit: 0
Max detached processes: 0 Max active jobs: 0

The paging file quota given here is large enough to allow three large applications to be loaded simultaneously. You can find out what your quotas are by:


You may run out of paging file quota when using big programs or data sets. This is usually indicated by the system failing to do what you asked it to do and displaying some (probably incomprehensible) message on the screen. Consult your Site Manager if you need to get your quotas increased.

2.3 Starting up ADAM

If you have not already executed the Starlink command procedure SSC:LOGIN.COM (which defines symbols like ADAMSTART and ICL), do that first:

    $ @SSC:LOGIN

Since you need to do this before using any Starlink software, it is worth putting it in your personal LOGIN.COM file.

The first thing to do when you want to use ADAM is to type in the following command:

    * ADAM Version 2.0-1 has been installed *  
    *  Type ADAM_CHANGES for information    *  
      ADAM version 2.0-1 available  

(If this command causes problems, then ADAM hasn’t been installed properly at your site — see your Site Manager. You may, of course, find that you are using a different version of ADAM, so you may get a slightly different response when you try it.) This command sets up various logical names and commands needed to use ADAM. Also, if you haven’t executed this command before, it will create a subdirectory called ADAM in your login directory and give it the logical name ADAM_USER2. You can see what’s in it by typing:


Notice that it contains a file called GLOBAL.SDF; this will hold global parameter values. (In general, the behaviour of programs and the files they read and write can be modified by specifying parameters, of which much more will be said later. Global parameters are parameters which are not specific to any one application.) The file type qualifier ‘.SDF’ is characteristic of ADAM data files. They are written by a component of ADAM called HDS, which stands for ‘Hierarchical Data System’. ADAM_USER is used by the system to hold files which it creates automatically. It should be cleared occasionally by using the VMS PURGE and DELETE commands in the usual way. Provided that no parameter values need retaining between sessions, everything can be deleted at the end of a session, but ADAMSTART must be re-run to initialize things again before ICL is used.

2.4 Choice of command language

As an ADAM user you have a choice of at least three ways of running ADAM programs:

ICL is recommended for most purposes because it gives flexibility and good performance when you are using many commands. It also offers you an easy, yet efficient, way of writing simple procedures, and a comprehensive scientific calculator (with the ability to feed the results directly into programs). It also allows you to run multiple applications at the same time. Most of this Guide will assume that ICL is being used.

DCL gives fewer facilities — particularly in terms of command line specification — but in some circumstances it can be quicker. Naturally, it also gives immediate access to all DCL facilities. For this reason it is often quickest to test a new program under DCL; the normal switching between editor, compiler and program execution could mean frequent overheads in either stopping and starting ICL or having to execute DCL commands from ICL.

SMS (‘Simple Menu System’) is primarily used for data-acquisition, though there is no reason why it should not be used for data-analysis. Its main advantage is that it requires little typing, and gives maximum efficiency when a few programs are being run which have lots of parameters but only a few change for each run. Its main drawbacks are that it is quite difficult to set up the description of what is to appear in the various menus and how they are to look, and that this has not been done for the normal Starlink application packages.

SMS is not considered further in this guide. If you wish to investigate it, read chapter 11 of the ICL User’s Guide (SG/5).

2.5 Trying out the command languages

The program TRACE, used below, looks at the contents of a data file of the type handled by the Hierarchical Data System (HDS).

2.5.1 ICL

You start up the ICL command language by typing:

   $ ICL

This loads the ICL program which will interpret the commands you type. After it has warmed up (a few seconds), it displays some introductory information:

   Interactive Command Language   ---   Version 1.5-7  
      - 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  

You may find that the system responds differently when you try it because it may have been updated since we wrote this. Anyway, it’s all self-explanatory. The last line is the prompt that ICL gives when it wants you to enter something. Like the ‘$’ prompt, the ‘ICL>’ prompt is output by the computer; you do not type it in yourself.

You can find out what packages are available at your site by entering:

        The following ADAM applications packages are available from Starlink:  
        Standard Packages:  
         CONVERT   -  Data format conversion.  
         FIGARO    -  General data-reduction.  
         KAPPA     -  Image processing.  
         SPECDRE   -  Spectroscopy Data Reduction  
         SST       -  Simple Software Tools  
         TSP       -  Time series and polarimetry data analysis.  
        Option Packages:  
         ASTERIX   -  X-ray data analysis.  
         CCDPACK   -  CCD data reduction  
         DAOPHOT   -  Stellar photometry.  
         PHOTOM    -  Aperture photometry.  
         PISA      -  Position, Intensity and Shape Analysis  
         SCAR      -  Catalogue access and reporting.  
        Additional information available:  
        MISCELLANEOUS        PHOTOM     PISA       SCAR       SPECDRE   SST  
    PACKAGES Subtopic?

Now you can enter the name of one of the packages to get information on it. Use it exactly like the VMS HELP system. Keep pressing ‘carriage return’ to get back to the ‘ICL >’ prompt.

One of the things you can do with ICL is get answers to calculations; for example, if you input:

    ICL> X=SQRT(2)  
    ICL> PRINT Result=(X)

ICL will print the answer:

    Result= 1.414214  

You can exit from ICL at any time by entering the command:

    ICL> EXIT  

The ‘$’ prompt indicates that you are now talking to DCL. To use ICL again you will have to type:

    $ ICL

again, and this will generate the same introductory lines as before.

When you have an ICL > prompt, simply type:


followed by <CR > when you get the prompt:

   OBJECT --- Object to be examined /@ADAM_USER:GLOBAL/ >

This will show you the structure and contents of the ADAM_USER:GLOBAL.SDF file.

Once again, to leave ICL and return to DCL simply type:

   ICL> EXIT  

The above sequence of operations is encapsulated in the single command ADAM. Therefore, the easiest way of running TRACE is to type:


which leaves you in ICL and in a position to try out any of the other ICL commands.

2.5.2 DCL

When using DCL, the normal way to run program TRACE is simply to type:

   $ TRACE

and then press <CR > when you receive the prompt:

   OBJECT --- Object to be examined /@ADAM_USER:GLOBAL/ >

Once again, the contents and structure of the file will be displayed, only this time you will be left in DCL with a ‘$’ prompt.

1Sorry, but there are still people around who complain that you never told them this.

2ADAMSTART will only create the [.ADAM] directory and define the job logical name ADAM_USER if ADAM_USER is not already defined as a job logical name. If ADAM_USER is so defined, the assigned directory is assumed to exist.