ERROR_POST

Prints error messages that are generated by IMSL routines using EPACK.

Required Argument

EPACK — (Input [/Output])
Derived type array of size p containing the array of message numbers and associated data for the messages. The definition of this derived type is packaged within the modules used as interfaces for each suite of routines. The declaration is:

        type ?_error
        integer idummy; real(kind(?_)) rdummy
        end type 
                                                

The choice of “?_” is either “s_” or “d_” depending on the accuracy of the data. This array gets additional messages and data from each routine that uses the “epack=” optional argument, provided p is large enough to hold data for a new message. The value p = 8 is sufficient to hold the longest single terminal, fatal, or warning message that an IMSL Fortran Library routine generates.

The location at entry epack (1)%idummy contains the number of data items for all messages. When the error_post routine exits, this value is set to zero. Locations in array positions (2:) %idummy contain groups of integers consisting of a message number, the error severity level, then the required integer data for the message. Floating-point data, if required in the message, is passed in locations(:)%rdummy matched with the starting point for integer data. The extent of the data for each message is determined by the requirements of the larger of each group of integer or floating-point values.

Optional Arguments

new_unit = nunit (Input)
Unit number, of type integer, associated for reading the direct-access file of error messages for the IMSL Fortran 90 routines.
Default: nunit = 4

new_path = path (Input)
Pathname in the local file space, of type character*64, needed for reading the direct-access file of error messages. Default string for path is defined during the installation procedure for certain IMSL Fortran Library routines.

FORTRAN 90 Interface

Generic: CALL ERROR_POST (EPACK [, …])

Specific: The specific interface names are S_ERROR_POST and D_ERROR_POST.

Description

A default direct-access error message file (.daf file) is supplied with this product. This file is read by error_post using the contents of the derived type argument epack, containing the message number, error severity level, and associated data. The message is converted into character strings accepted by the error processor and then printed. The number of pending messages that print depends on the settings of the parameters PRINT and STOP in the Reference Material. These values are initialized to defaults such that any Level 5 or Level 4 message causes a STOP within the error processor after a print of the text. To change these defaults so that more than one error message prints, use the routine ERSET documented and illustrated with examples in the Reference Material. The method of using a message file to store the messages is required to support “shared-memory parallelism.”

Managing the Message File

For most applications of this product, there will be no need to manage this file. However, there are a few situations which may require changing or adding messages:

New system-wide messages have been developed for applications using this Library.
All or some of the existing messages need to be translated to another language
A subset of users need to add a specific message file for their applications using this Library.

Following is information on changing the contents of the message file, and information on how to create and access a message file for a private application.

Changing Messages

In order to change messages, two files are required:

An editable message glossary, messages.gls, supplied with this product.
A source program, prepmess.f, used to generate an executable which builds messages.daf from messages.gls.

To change messages, first make a backup copy of messages.gls. Use a text editor to edit messages.gls. The format of this file is a series of pairs of statements:

message_number=<nnnn>
message='message string'

(Note that neither of these lines should begin with a tab.)

The variable <nnnn> is an integer message number (see below for ranges and reserved message numbers).

The 'message string' is any valid message string not to exceed 255 characters. If a message line is too long for a screen, the standard Fortran 90 concatenation operator // with the line continuation character & may be used to wrap the text.

Most strings have substitution parameters embedded within them. These may be in the following forms:

%(i<n>) for an integer substitution, where n is the nth integer output in this message.
%(r<n>) for single precision real number substitution, where n is the nth real number output in this message.
%(d<n>) for double precision real number substitution, where n is the nth double precision number output in this message.

New messages added to the system-wide error message file should be placed at the end of the file. Message numbers 5000 through 10000 have been reserved for user-added messages. Currently, messages 1 through 1400 are used by IMSL. Gaps in message number ranges are permitted; however, the message numbers must be in ascending order within the file. The message numbers used for each IMSL Fortran Library subroutine are documented in this manual and in online help.

If existing messages are being edited or translated, make sure not to alter the message_number lines. (This prevents conflicts with any new messages.gls file supplied with future versions of this Library.)

Building a New Direct-access Message File

The prepmess executable must be available to complete the message changing process. For information on building the prepmess executable from prepmess.f , consult the installation guide for this product.

Once new messages have been placed in the messages.gls file, make a backup copy of the messages.daf file. Then remove messages.daf from the current directory. Now enter the following command:

prepmess > prepmess_output

A new messages.daf file is created. Edit the prepmess_output file and look near the end of the file for the new error messages. The prepmess program processes each message through the error message system as a validity check. There should be no FATAL error announcement within the prepmess_output file.

Private Message Files

Users can create a private message file within their own messages. This file would generally be used by an application that calls this Library. Follow the steps outlined above to create a private messages.gls file. The user should then be given a copy of the prepmess executable. In the application code, call the error_post subprogram with the new_unit/new_path optional arguments. The new path should point to the directory in which the private messages.daf file resides.