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.
- Investigate the functionality in NAG in a particular area as currently used by applications.
Consult the NAG documentation for this.
- 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.
- 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
- 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.
- 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.
- Go through the single-file source code and change the routine names. Whenever possible
the old names should just be preceded by ‘PDA_’.
- Split the full source into Fortran modules with ‘fsplit’.
- 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
- 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.
- 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
- Register the new source files in the ‘makefile’. Also register any test programs. Test programs
have capitalised names, library routines have lower-case names.
- 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
- 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
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).