2 Running CONVERT

 2.1 Starting CONVERT from the UNIX shell
 2.2 Starting CONVERT from ICL
 2.3 Issuing CONVERT Commands
 2.4 Obtaining Help
 2.5 Hypertext Help

2.1 Starting CONVERT from the UNIX shell

The command convert defines Convert commands from the UNIX shell.

        % convert

Note that the % is the UNIX shell’s prompt which you do not type.

A message similar to:

  
     CONVERT commands are now available -- (Version 1.0, 1997 August)
  
     Defaults for automatic NDF conversion are set.
  
     Type conhelp for help on CONVERT commands.
     Type "showme sun55" to browse the hypertext documentation.
  

will be displayed. You will then be able to mix Convert and UNIX commands.

The convert command is defined by the Starlink startup procedures to ‘source’ file convert.csh in the Convert executables directory. Non-Starlink sites must make their own arrangements.

2.2 Starting CONVERT from ICL

To start ICL, type:

       % icl

You will see any messages produced by system and user procedures, followed by the ICL> prompt, something like the following.

  ICL (UNIX) Version 3.1-5 20/05/97
  
  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>

Then, to make the Convert commands known to the command language, type:

  ICL> CONVERT

This will produce a Convert startup message similar to:

  CONVERT commands are now available -- (Version 1.0, 1997 August)
  
  Defaults for automatic NDF conversion are set.
  
  Type CONHELP or HELP CONVERT for help on CONVERT commands.
  Type "showme sun55" to browse the hypertext documentation.

The ICL command CONVERT is defined by the standard Starlink ICL login files to LOAD file convert.icl in the Convert executables directory. Non-Starlink sites must make their own arrangements.

2.3 Issuing CONVERT Commands

Having initialised Convert you are now ready to issue a Convert command. To run an application you can just give its name (or its name preceded by con_2)—you will be prompted for any required parameters. Alternatively, you may enter parameter values on the command line specified by position or by keyword. If you want to override any defaulted parameters, then you specify the parameter’s value on the command line. Note that from UNIX the commands are in lowercase, whereas from ICL the case does not matter.

Most Convert applications can be run as simply as:

       <application> <in> <out>

where <application > is the application’s name, <in > is the input file, and <out > is the output file following the conversion. For instance, from the UNIX shell,

       % dst2ndf old new

or, from ICL,

       ICL> DST2NDF old new

both instruct the application DST2NDF to convert the DST file called old.dst to the NDF called new.sdf. Note that for UNIX, the case of the filename is significant.

The following example has the same effect as those immediately above, only this time you are prompted for the filenames needed by DST2NDF.

       ICL> DST2NDF
       IN - Name of Figaro (.DST) file to be converted /’ ’/ > old
       OUT - Name of output NDF /@f1/ > new

The value between the / / delimiters is a suggested default. You can choose to accept the suggestion by pressing carriage return.

The simple usage, (<application> <in> <out>), will usually produce a result but many applications have additional parameters which you can set to give finer control over the conversion. See the application specifications in Appendix A for details of the options available.

You can find details of how to use parameters for controlling Starlink program options in Section 4 of SUN/95 or in Chapter 8 of SG/4. However, you should be able to get along using intuition alone, or, perhaps by consulting the application specifications in Appendix A, which include usage, parameters, examples and details of the conversion process.

In most cases, one invocation of a Convert application is required for each file conversion but in some cases, inputs may be defined as ‘GROUPS’ of names, including wildcards (see the application specifications for details).

2.4 Obtaining Help

You can get the top-level help information for Convert by typing:

       % conhelp

from the UNIX shell, or:

       ICL> CONHELP

from ICL. (You can also access Convert help from ICL by using the ICL command, HELP.)

The help topics are mostly detailed descriptions of the applications but also include global information on matters such as using parameters. e.g. the following command gives help on the application UNF2NDF.

       % conhelp unf2ndf

If you have commenced running an application you can still access the help library whenever you are prompted for a parameter; you enter ?. Here is an example.

       NOPEREC - Number of data values per output record /512/ > ?
  
       NDF2UNF
  
         Parameters
  
           NOPEREC = _INTEGER (Read)
              The number of data values per record of the output file.  It
              should be in the range 1 to 8191, unless the array is double
              precision, when the upper limit is 4095.  The suggested
              default is the current value. [The first dimension of the NDF]
  
       NOPEREC - Number of data values per output record /512/ >

2.5 Hypertext Help

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

       % showme sun55

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.

2The con_<name> form is defined for use where there may be confusion between commands of the same name from different packages.