NDF_HPUT - Write history information to an NDF

Description:

The routine writes textual information to the history component of an NDF, creating a new history record if necessary. A variety of formatting options are available and values may be substituted for message tokens embedded within the text. The text supplied may either augment or replace the history information normally written by default.

Invocation:

CALL NDF_HPUT( HMODE, APPN, REPL, NLINES, TEXT, TRANS, WRAP, RJUST, INDF,
STATUS )

Arguments:

HMODE = CHARACTER $*$ ( $*$ ) (Given)

The priority for the text being written: 'VERBOSE', 'NORMAL' or 'QUIET', where 'VERBOSE' signifies the lowest priority and 'QUIET' signifies the highest. The value given may be abbreviated, to no less then three characters. A blank value is accepted as a synonym for 'NORMAL'.

APPN = CHARACTER $*$ ( $*$ ) (Given)

Name of the current application. This will only be used if a new history record is created by this routine, otherwise it is ignored. If a blank value is given, then a system-supplied default will be used instead.

REPL = LOGICAL (Given)

Whether the text supplied is intended to replace the history information which is supplied by default. If a .TRUE. value is given and no default history information has yet been written to the NDF, then subsequent writing of this information will be suppressed. If a .FALSE. value is given, then default history information is not suppressed and will later be appended to the text supplied (unless suppressed by another call to NDF_HPUT).

NLINES = INTEGER (Given)

Number of lines of history text supplied.

TEXT( NLINES ) = CHARACTER $*$ ( $*$ ) (Given)

The lines of history text to be written. The length of the elements of this array (as returned by the Fortran LEN function) should not exceed the value NDF__SZHMX. The recommended length of TEXT elements is given by the constant NDF__SZHIS. (Both of these constants are defined in the include file NDF_PAR.)

TRANS = LOGICAL (Given)

If a .TRUE. value is supplied, then any message tokens embedded in the supplied text will be expanded before it is written to the history record (see SUN/104 for a description of how to use message tokens). If a .FALSE. value is given, then the supplied text is taken literally; no special characters will be recognised and no message token expansion will occur.

WRAP = LOGICAL (Given)

If a .TRUE. value is given, then paragraph wrapping will be performed on the supplied text (after message token expansion if appropriate) so as to make as much text fit on to each line of a history record as possible. Blank input lines may be used to delimit paragraphs. If a .FALSE. value is given, then input lines which exceed the history record's text width will simply be broken (at a space if possible) and continued on a new line.

RJUST = LOGICAL (Given)

If a .TRUE. value is given, then lines of history text will be padded out with blanks (after message token expansion and paragraph wrapping if appropriate) so as to give a justified right margin. If a .FALSE. value is given, then the right margin will remain ragged.

INDF = INTEGER (Given)

NDF identifier.

STATUS = INTEGER (Given and Returned)

The global status.

Notes:

• This routine will return without action if (a) there is no history component present in the NDF, (b) the priority specified via HMODE is lower than the NDF's current history update mode setting, or (c) the NDF's history update mode is currently set to 'DISABLED'.

• It is expected that the APPN argument will usually be left blank. A non-blank value should normally only be given for this argument if a more complete identification of the current application can be given than is supplied by default.

• If no previous history information has been written to the NDF by the current application, then this routine will create a new history record whose text width will be determined by the length of the lines of the TEXT array (as returned by the Fortran LEN function). If history information has already been written, then this routine will append to the existing history record. In this case, the text width will already have been defined, so the supplied text will be re-formatted if necessary (by line breaking or paragraph wrapping) to fit into the available width.

• Paragraph wrapping is recommended, when appropriate, as a means of saving space while retaining a neat appearance in the resulting history record. It is particularly useful when message tokens are used within normal text, since these make it hard to predict the precise length of history lines in advance. The right justification flag may be used to improve the cosmetic appearance of history text, but it has no effect on the amount of space used.

• On exit from this routine, all message tokens in the current message context are left in an undefined state.