ISAP Programmer's Guide

Guidelines

• The specifications given for incomplete routines are an outline of what the tool should be capable of, not a final specification. However, AAR or YAAAR data structures for I/O should always be used, and these guidelines should be followed when possible.
• New IDL routines are written in pure IDL when possible.
• Routines should be able to handle non-uniformly spaced data.
• Ideally ISAP will run on any platform supported by IDL with minimum porting. (Exception: The version of ISAP used by the LIDT will also read/write MCFITS files, which are designed for efficiency on VAX/VMS systems.).
• Common blocks should be avoided where possible.
• When a routine is passed an AAR structure, it will check that the tag names that it is expecting to be in the data are present, and will issue an error message if not. Initially a printed message will suffice.
• An AAR structure passed into a routine will be processed in its entirety. That is, it is up to the user/GUI to construct AARs which contain correct data, the routine itself will make no assumptions about the data it is being passed.
• Any procedures that are written which use widgets should be modal, to avoid confusion within the GUI. The exception is for compound widgets, used as part of a larger widget (which should itself be modal). Functions/Procedures should be in a file with the same name as the routine, so that IDL can load and compile the routine when it is first called.
• If keywords are used, these should have a `NONE' value, since the GUI will have to include the keyword values on the calling line, and therefore needs to be able to specify that certain keywords are invalid. (e.g, sap_keyword_set)
• If Handles/Unrealised Base Widgets are used as pointers, they will be destroyed when no longer needed, either explicitly, or as part of a Group allocation.
• Logical names/aliases will be set up for the CAL files etc.
• The GUI is designed so that the addition/removal of routines/functions is simple.
• The flavour of FITS is TBD
• Do we require double precision or not?? maximum number of scans combined retain a precision of TBD?
• Hardware constraints: X-terminal minimum size 17inches TBC, colour TBC.

General Rules for ISAP Programs

1. All keyword checks like

    if keyword_set(key) then ...

   or

    if n_elements(key) ne 0 then ...

   have to be replaced with sap_keyword_set(key). The difference between IDL's keyword_set and sap_keyword_set is that the latter accepts zero as a value and that the value 'NONE' can be used to un-set a keyword explicitly.

   A statement

    if n_elements(keyword) eq 1

   has to be replaced with

    if sap_keyword_set(keyword) and n_elements(keyword) eq 1.

   Subroutines that are borrowed from other packages (e.g. IA3) must only be modified if their keywords shall be directly passed from the GUI. See also item 7.
2. The error handling has to be performed using sap_error (same syntax as in IA3 error routine error).
3. All checks for AAR/SPD/LLI structure have to be done with is_struct.
4. All (shell) routines have to call the history handling routine update_history at the end (i.e. just before return).
5. All routines should check the syntax of the programm call at the beginning.
6. If two or more structures are involved they have to be checked for same structure (-> warning if not), same units using chk_unit (and get_unit) and, if necessary, same length (using n_elements).
7. If subroutines that are borrowed from other packages (e.g. IA3), and they have to be modified, this has to be discussed first with the people who are responsible for the package. In general changes of such borrowed subroutines have to be avoided whenever possible. The current policy is to avoid borrowed routines at all!
8. All routines should have a keyword DEPENDENCIES in the help header which declares all subroutines beeing called from this routine and all routines that call this routine as a subroutine.

Error Handling

The error handling approach for the interactive ISAP mode (sap_error) is similar to the SWS IA error handling. In particular: programmes return to the main level (RETALL) after occurance of a fatal error. For the GUI this was not sufficient, because there is no way for it to check if an error occured or not. Therefore the IPAC routines have been modified to return to the calling routine (return, not retall) and to provide an error status in a variable (usually called STATUS) in the GUI mode (i.e. if !SAP_GUI is set to 1).

For instance:

      status = tippex(aar_in,aar_out,tip_list)

The GUI will then examine the status and continue accordingly.

BUT: I see two problems:

1. SAP_ERROR does the return only in the GUI mode, in interactive mode it still retalls to the main level. In this case the status, i.e. the value of the function in the example above, would be undefined. It is not satisfying to have a routine which returns an error status which is undefined when an error actually occurs.
2. To make sure that this approach works porperly, you have to make sure, that each subroutine that is called by a routine returns an error status as well. In the above example tippex calls kwd_notset. This subroutine calls sap_error, but doesn't return an error status (please correct me if I am wrong - this is only an example).

1. Drop the distinction between GUI and interactive mode for sap_error: sap_error should always return to the calling routine (no retall).
2. Every routine which calls sap_error (i.e. almost all routines) should return an error status (0 if ok, 1 if fatal error).
3. Every routine that calls a subroutine should analyze the error status before continuing and set its own error status according to the error status of its subroutines.

After a call from the main level to a routine which calls a subroutine which calls a subroutine where an error occurs you'll still end up at the main level (and get an error message). But in addition you'll have an error code which can be analyzed by the GUI or other programmes.

I have now modified the arithm and dered routines according to this principle but I will wait with the update of the other MPE routines till we agreed on the above suggestions or alternative schemes. Please let me know what you think.

IA3/CoCo Compatibility Requirements for ISAP Routines

1. Header:

    - First line:   ;#> filename.dcx
           
      The blank between ">" and "filename" is mandatory! 
      x stands for 1 (user level) or 2 (programmer level)
   
    - Second line:  ; Identifier        filename
                    ......
   
    -               ; Category:         ISAP
    
    - Last line:    ;#<
   

2. No ISAP routine can have the same name as an existing IA3 routine.
3. AAR structure:
   • Data points (table rows) must be sorted by increasing wavelength.
   • Data tags, or fields (table columns) must be in a predetermined order.
   • Follow the AAR structure definition (defined where?).

Inserting a New Module Into IA3 via CoCo

1. Create a CoCo install file.
   new_module.install:

      # 
      # NEW_MODULE 
      #
      FILES: NEW_MODULE.install
      FIELS: NEW_MODULE.pro
    
      INSTALL: ARITHM.pro UTL_SRC
   

2. Create a dc file, new_module.dcx (x = 1 or 2), containing a copy of the header part of the routine. See above for header requirements.
3. The *.dc file and the *.install file have to be in the same directory as the *.pro file. Type the following:
   

      coco create-module new_module UTL "ISAP: comment"  (-w 30 ...)
   

   The comment should be a short description of the routine, usually taken from the PURPOSE keyword in the header. You may use other CoCO options such as '-w 30' (wait 30 minutes before communication time out.)

   The .dc file goes into a subdirectory DOC.
   The .install file will be in INSTALL.
   

4. To modify an existing routine, type the following:
   

      coco reserve-module filename comment
   

   After modifying it, type:

      coco insert-module filename comment