NDF_HINFO - Obtain information about an NDF's history component

Description:

The routine returns character information about an NDF's history component or about one of the history records it contains.

Invocation:

CALL NDF_HINFO( INDF, ITEM, IREC, VALUE, STATUS )

Arguments:

INDF = INTEGER (Given)

NDF identifier.

ITEM = CHARACTER $*$ ( $*$ ) (Given)

Name of the information item required: 'APPLICATION', 'CREATED', 'DATE', 'DEFAULT', 'HOST', 'MODE', 'NLINES', 'NRECORDS', 'REFERENCE', 'USER', 'WIDTH' or 'WRITTEN' (see the "General Items" and "Specific Items" sections for details). This value may be abbreviated, to no less than three characters.

IREC = INTEGER (Given)

History record number for which information is required. This argument is ignored if information is requested about the history component as a whole. See the "Specific Items" section for details of which items require this argument.

VALUE = CHARACTER $*$ ( $*$ ) (Returned)

The history information requested (see the "Returned String Lengths" section for details of the length of character variable required to receive this value).

STATUS = INTEGER (Given and Returned)

The global status.

General Items

The following ITEM values request general information about the history component and do not use the IREC argument:

• 'CREATED': return a string giving the date and time of creation of the history component as a whole in the format 'YYYY-MMM-DD HH:MM:SS.SSS' (e.g. '1993-JUN-16 11:30:58.001').

• 'DEFAULT': return a logical value indicating whether default history information has yet to be written for the current application. A value of 'F' is returned if it has already been written or has been suppressed by a previous call to NDF_HPUT, otherwise the value 'T' is returned.

• 'MODE': return the current update mode of the history component (one of the strings 'DISABLED', 'QUIET', 'NORMAL' or 'VERBOSE').

• 'NRECORDS': return the number of history records present (an integer formatted as a character string). Note that for convenience this value may also be obtained directly as an integer via the routine NDF_HNREC.

• 'WRITTEN': return a logical value indicating whether the current application has written a new history record to the NDF's history component. A value of 'T' is returned if a new record has been written, otherwise 'F' is returned.

Specific Items

The following ITEM values request information about specific history records and should be accompanied by a valid value for the IREC argument specifying the record for which information is required:

• 'APPLICATION': return the name of the application which created the history record.

• 'DATE': return a string giving the date and time of creation of the specified history record in the format 'YYYY-MMM-DD HH:MM:SS.SSS' (e.g. '1993-JUN-16 11:36:09.021').

• 'HOST': return the name of the machine on which the application which wrote the history record was running (if this has not been recorded, then a blank value is returned).

• 'NLINES': return the number of lines of text contained in the history record (an integer formatted as a character string).

• 'REFERENCE': return a name identifying the NDF dataset in which the history component resided at the time the record was written (if this has not been recorded, then a blank value is returned). This value is primarily of use in identifying the ancestors of a given dataset when history information has been repeatedly propagated through a sequence of processing steps.

• 'USER': return the user name for the process which wrote the history record (if this has not been recorded, then a blank value is returned).

• 'WIDTH': return the width in characters of the text contained in the history record (an integer formatted as a character string).

Returned String Lengths

• If ITEM is set to 'CREATED', 'DATE', 'MODE', 'NLINES', 'NRECORDS' or 'WIDTH', then an error will result if the length of the VALUE argument is too short to accommodate the returned result without losing significant (non-blank) trailing characters.

• If ITEM is set to 'APPLICATION', 'HOST', 'REFERENCE' or 'USER', then the returned value will be truncated with an ellipsis '...' if the length of the VALUE argument is too short to accommodate the returned result without losing significant (non-blank) trailing characters. No error will result.

• When declaring the length of character variables to hold the returned result, the constant NDF__SZHDT may be used for the length of returned date/time strings for the 'CREATED' and 'DATE' items, the constant NDF__SZHUM may be used for the length of returned update mode strings for the 'MODE' item, and the constant VAL__SZI may be used for the length of returned integer values formatted as character strings.

• Use of the constant NDF__SZAPP is recommended when declaring the length of a character variable to hold the returned application name for the 'APPLICATION' item. Similarly, use of the constant NDF__SZHST is recommended when requesting the 'HOST' item, NDF__SZREF when requesting the 'REFERENCE' item and NDF__SZUSR when requesting the 'USER' item. Truncation of the returned values may still occur, however, if longer strings were specified when the history record was created.

• The NDF__SZAPP, NDF__SZHDT, NDF__SZHST, NDF__SZHUM, NDF__SZREF and NDF__SZUSR constants are defined in the include file NDF_PAR. The VAL__SZI constant is defined in the include file PRM_PAR (see SUN/39).