[Top] [Prev] [Next]

11.4 Writing Annotations

The DFAN interface supports writes to file labels, file descriptions, object labels, and object descriptions.

11.4.1 Assigning a File Label: DFANaddfid

To write a file label, the calling program must call DFANaddfid:

C:		status = DFANaddfid(file_id, label);
FORTRAN:	status = daafid(file_id, label)
DFANaddfid has two parameters: file_id and label. The file_id parameter contains the file identifier for the file to be annotated and the label parameter contains the annotation string. The label array must be null-terminated. In the FORTRAN-77 version, the length of the label should be the length of the label array as in FORTRAN-77 string lengths are assumed to be the declared length of the array that holds the string.

The parameters of DFANaddfid are further defined in Table 11C on page 348.

11.4.2 Assigning a File Description: DFANaddfds

To write a file description, the calling program must call DFANaddfds:

C:		status = DFANaddfds(file_id, description, desc_length);
FORTRAN:	status = daafds(file_id, description, desc_length)
DFANaddfds has three parameters: file_id, description, and desc_length. The file_id parameter contains the file identifier. The parameter description can contain any sequence of ASCII characters and is not limited to a single string (e.g., a carriage return may appear anywhere in the description). The desc_length parameter specifies the length of the description.

The parameters of DFANaddfds are defined in Table 11C.

TABLE 11C - DFANaddfid and DFANaddfds Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DFANaddfid

[intn]

(daafid)
file_id
int32
integer
File identifier

label
char *
character*(*)
File label string

DFANaddfds

[intn]

(daafds)
file_id
int32
integer
File identifier

description
char *
character*(*)
File description string

desc_length
int32
integer
Length of the description in bytes

EXAMPLE 1. Writing a File Label and a File Description

The following examples add a file label and description to the file named "Example1.hdf". Notice that after the file is opened, the file_id may be used to add any combination of file annotations before the file is closed.

C version

FORTRAN-77 version

11.4.3 Assigning an Object Label: DFANputlabel

To write a file label, the calling program must contain a call to DFANputlabel:

C:		status = DFANputlabel(filename, tag, ref, label);
FORTRAN:	status = daplab(filename, tag, ref, label)
DFANputlabel has four parameters: filename, tag, ref, and label. The label parameter contains a single null-terminated string that defines the annotation.

The parameters of DFANputlabel are further defined in Table 11D.

11.4.4 Assigning an Object Description: DFANputdesc

To write an object description, the calling program must contain a call to DFANputdesc:

C:		status = DFANputdesc(filename, tag, ref, description, desc_len);
FORTRAN:	status = dapdesc(filename, tag, ref, description, desc_len)
DFANputdesc has five parameters: filename, tag, ref, description, and desc_len. The filename parameter is the name of the HDF file containing the object to be annotated. The tag and ref parameters are the tag/reference number pair of the object to be annotated. The description parameter contains a buffer for the annotation text and the desc_len parameter specifies the length of the buffer.

The parameters of DFANputdesc are further defined in Table 11D.

TABLE 11D - DFANputlabel and DFANputdesc Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DFANputlabel

[intn]

(daplab)
filename
char *
character*(*)
Name of the file to be accessed

tag
uint16
integer
Tag of the object to be annotated

ref
uint16
integer
Reference number of the object to be annotated

label
char *
character*(*)
Object label string

DFANputdesc

[int]

(dapdesc)
filename
char *
character*(*)
Name of the file to be accessed

tag
uint16
integer
Tag of the object to be annotated

ref
uint16
integer
Reference number of the object to be annotated

description
char *
character*(*)
Object description string

desc_len
int32
integer
Length of the description in bytes

EXAMPLE 2. Writing an Object Label and Description to a Scientific Data Set

These examples illustrate the use of DFANputlabel and DFANputdesc to assign both an object label and an object description to a scientific data set immediately after it is written to file. The tag for scientific data sets is DFTAG_NDG.

C version

FORTRAN-77 version




[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.