Next: NDF_HSMOD - Set the history update mode for an NDF
Up: FORTRAN ROUTINE DESCRIPTIONS
Previous: NDF_HPURG - Delete a range of records from an NDF history component
- 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.
Next: NDF_HSMOD - Set the history update mode for an NDF
Up: FORTRAN ROUTINE DESCRIPTIONS
Previous: NDF_HPURG - Delete a range of records from an NDF history component
Starlink User Note 33
R.F. Warren-Smith
11th January 2000
E-mail:rfws@star.rl.ac.uk
Copyright © 2000 Council for the Central Laboratory of the Research Councils