Chapter 7
Extending ICL

 7.1 Login files
 7.2 The DEFSTRING Command
 7.3 Hidden Procedures
 7.4 The DEFPROC Command
 7.5 Defining Additional Help Topics
 7.6 Other Ways of Defining Commands

If you use ICL frequently you will find it convenient to define your own commands. We have already met one way of defining new commands. This is to write an ICL procedure as described in Chapter 3. There are several other ways of defining new commands which are described in this chapter. If you have many commands which you want to use frequently it is convenient to put these into a login file which will be automatically loaded each time ICL is started up.

7.1 Login files

An ICL login file works in exactly the same way as your DCL LOGIN.COM file. ICL uses the logical name ICL_LOGIN to locate your login file so if you create a file called LOGIN.ICL in your top level directory you can use use the following DCL DEFINE command (which you should put in your DCL LOGIN.COM file).

     $ DEFINE ICL_LOGIN DISK$USER:[ABC]LOGIN.ICL

where DISK$USER:[ABC] needs to be replaced by the actual directory used.

This file will then be loaded automatically whenever you start up ICL and can include procedures, definitions of commands, or indeed, any valid ICL commands. Below is an example of a login file which illustrates some of the facilities which may be used.

  
      {  ICL  Login File  }
  
      {  Define TYPE command  }
  
      DEFSTRING  T(YPE)  $ TYPE
  
      {  Define EDIT command  }
  
      HIDDEN PROC EDIT name
         IF INDEX(name,’.’) = 0
            #EDIT (name)
         ELSE
            DCL EDIT (name)
         ENDIF
      END PROC
  
      {  Login Message  }
  
      PRINT
      PRINT   Starting ICL at (TIME()) on (DATE())
      PRINT
  

7.2 The DEFSTRING Command

The first entry in the file defines the DCL TYPE command so that it is accessible directly from ICL without having to do enter DCL TYPE. This is done using the DEFSTRING command which defines an equivalence string for a command. In this case the command is TYPE and the equivalence string is DCL TYPE. The notation T(YPE) specifies possible abbreviations for the TYPE command, indicating that we could actually use T, TY or TYP instead of TYPE in full.

7.3 Hidden Procedures

The definition of the EDIT command is done in a different way. Since EDIT is used within ICL to edit procedures, if we just used DEFSTRING to define EDIT as $ EDIT we would lose the ability to edit ICL procedures. The EDIT command would always edit VMS files.

The procedure used to redefine EDIT gets round this by testing for the existence of a dot in the name to be edited using the INDEX function. If a dot is present it assumes that a VMS file is being edited and issues the command $ EDIT (name). If no dot is present it is assumed that an ICL procedure is being edited, and the command #EDIT (name) is issued. The # character forces the internal definition of EDIT to be used, rather than the definition currently being defined.

The procedure is written as a hidden procedure, indicated by the word HIDDEN preceding PROC. A hidden procedure works in exactly the same way as a normal procedure, but it does not appear in the listing of procedures produced by a PROCS statement, nor can it be edited, deleted or saved. It is convenient to make all procedures in your login file hidden procedures so that they do not clutter your directory of procedures, and cannot be accidentally deleted.

7.4 The DEFPROC Command

If you have many procedures of this type you may not wish to include them in full in your login file, because this will require them all to be compiled when ICL starts up and may therefore slow down the start up process. The DEFPROC command allows you to define commands which run ICL procedures, but with the procedures only being compiled when they are required. For example if the EDIT procedure described above was put in the source file EDIT.ICL we could put the following DEFPROC command in the login file.

      DEFPROC ED(IT) EDIT.ICL

This command specifies that the command EDIT (with minimum abbreviation ED) is to run the procedure EDIT in source file EDIT.ICL.

The procedure will not be loaded and compiled until the first time the EDIT command is issued.

7.5 Defining Additional Help Topics

ICL includes a HELP command which provides on line documentation on ICL itself. Using the DEFHELP command it is possible to extend the facility to access information on the commands you have added. In order to do this you need to create a help library in the normal format used by the VMS help system. This is described in the VAX/VMS documentation for the librarian utility. You can then specify topics from this library which will be available using the ICL HELP command using a command of the form

      DEFHELP  EDIT  LIBRARY.HLB

This will cause a

      HELP EDIT

command to return the information on EDIT in help library LIBRARY.HLB rather than in the standard ICL library.

7.6 Other Ways of Defining Commands

The DEFUSER command allows an ICL command to be defined to call a FORTRAN subroutine. In order to make this work you have to link the subroutine into a shareable image (The VAX/VMS linker manual explains how to do this). The subroutine should have a single character string parameter in which it will receive the command line parameters of the original ICL command (after substitution of any bracketed expressions).

An easier way of achieving a similar result is to write your FORTRAN subroutine as an ADAM A-task, and use the DEFINE command as described in the next section.