B Adding further routines

This section describes how a new routine or set of routines might be added to the existing library. The development of the library is coordinated by David Berry.

(1)

Investigate the functionality in NAG in a particular area as currently used by applications. Consult the NAG documentation for this.

(2)

Consider what functionality is actually necessary. This is often an abstraction from what NAG provides: Say, NAG may have a choice of routines or algorithms, or a set of NAG routines may be closely related.

(3)

Look at what is available in the Public Domain. Use the GAMS decision tree on the World Wide Web and give preference to SLATEC routines. Also give preference to double precision routines.

(4)

Make up your mind as to which routines from the Public Domain will be necessary and how they will cover completely and consistently a particular area of functionality. You will now have a list of one or a few user-callable routines that you want to incorporate into the library.

(5)

Down-load the code for each user-callable routine you picked. Make sure you get all code needed, including subsidiary routines. Use the ‘fullsource’ anchor in GAMS. Check that the transfer was successful, Mosaic will not warn you if the final five per cent are missing.

(6)

Go through the single-file source code and change the routine names. Whenever possible the old names should just be preceded by ‘PDA_’.

(7)

Split the full source into Fortran modules with ‘fsplit’.

(8)

If the routine PDA_XERMSG is part of the full source, SLATEC error handling is involved. If PDA_XERROR is present the old SLATEC error handling is involved. Remove PDA_XERMSG or PDA_XERROR and their subsidiaries PDA_FDUMP, PDA_J4SAVE, PDA_XERABT, PDA_XERCNT, PDA_XERCTL, PDA_XERHTL, PDA_XERPRN, PDA_XERPRT, PDA_XERRWV, PDA_XERSAV, PDA_XERSVE, PDA_XGETUA. Also remove PDA_I1MACH.

(9)

Check if there are routine name conflicts with the existing library. Check if modules of the same name are compatible or identical. Remove the redundant routines.

(10)

Modify the error handling and message output.

• If PDA_XERMSG is used to report and handle errors, an inherited status must be introduced to the routines in question. The calls to PDA_XERMSG must be given an extra integer argument. This status must be passed down and up all the way from the user application to PDA_XERMSG. The user application is assumed to give a value of zero indicating OK. When PDA_XERMSG is called it changes the status to one indicating an error.  
  You must also check that the new routines you want to introduce into the library obey the status. When a routine A calls a routine B which has the status as argument, then the status may have to be checked by A. If the status is bad, A must return gracefully to its caller. In the original SLATEC library XERMSG may be called with error severity levels that cause XERMSG to stop the program. This does not and must not happen in this library. The code you down-loaded may rely on the abortion to have occurred, but the code that goes into this library must not rely on this.
• If PDA_XERROR is called, these calls should be re-directed to PDA_XERMSG, or avoided altogether. If using PDA_XERMSG, review the routines accordingly.
• The routines in this library are not allowed to execute STOP statements or to write messages to the ‘terminal’. They must instead return a status code indicating what went wrong or what message the caller may or may not want to pass on to the user.
• You can introduce new calls to PDA_XERMSG to issue error reports, but this is not encouraged.

(11)

Register the new source files in the ‘makefile’. Also register any test programs. Test programs have capitalised names, library routines have lower-case names.

(12)

Modify pda_test.f to make a trivial call to the user-callable routines that you introduced. pda_test.f can be compiled and linked to see if all modules necessary are present, it cannot be executed.

(13)

Update the source of this document.

• Did you tap into a Public Domain package so far unused in the library?
• Were there problems with routine names?
• Do the new routines use include files?
• Provide migration hints, if possible.
• Add the user-callable routines to the list of routines and provide the routine documentation.

If you write new code for the library:

• Try not to use include files.
• Try not to use common blocks.
• Do not execute STOP statements.
• Do not write to the ‘terminal’.
• Do not call routines outside this library, do not call EMS_REP, ERR_REP, MSG_OUT, etc.
• Handle errors by returning a status to the caller that indicates what went wrong or what message might have to be delivered to the user. Do not deliver messages from code for this library. If you have to, use PDA_XERMSG.
• Adhere to the Starlink Application Programming Standard (SGP/16).