[Top] [Prev] [Next] [Bottom]

10.5 Writing Annotations

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

10.5.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 is further defined below. (See Table 10F on page 259.)

10.5.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 and the description parameter contains the label string. The parameter description can contain any sequence of ASCII characters and is not limited to a single string. The desc_length parameter specifies the length of the annotation.

The parameters of DFANaddfds are defined in the following table.

TABLE 10C DFANaddfid and DFANaddfds Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFANaddfid

(daafid)

file_id

int32

integer

File identifier.

label

char *

character* (*)

File label string.

DFANaddfds

(daafds)

file_id

int32

integer

File identifier.

description

char *

character* (*)

File description string.

desc_length

int32

integer

Length of the description in bytes.

EXAMPLE 3. 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:

#include "hdf.h"

main( )
{

	int32 file_id;
	intn status;
	static char file_label[] = "This is a file label.";
	static char file_desc[] = "This is a file description.";

	/* Open the HDF file to write the annotations. */
	file_id = Hopen("Example1.hdf", DFACC_CREATE, 0);

	/* Write the label to the file. */
	status = DFANaddfid(file_id, file_label);

	/* Write the description to the file. */
	status = DFANaddfds(file_id, file_desc, strlen(file_desc));

	/* Close the file. */
	status = Hclose(file_id);

}


 FORTRAN:	

PROGRAM CREATE ANNOTATION character*50 file_label, file_desc integer daafid, daafds, status, file_id, hopen, hclose integer*4 DFACC_CREATE parameter (DFACC_CREATE = 4) file_label = "This is a file label." file_desc = "This is a file description." C Open the HDF file to write the annotations. file_id = hopen('Example1.hdf', DFACC_CREATE, 0) C Write the label to the file. status = daafid(file_id, file_label) C Write the description to the file. status = daafds(file_id, file_desc, 26) C Close the file. status = hclose(file_id) end

10.5.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 10F below.

10.5.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 the following table.

TABLE 10D DFANputlabel and DFANputdesc Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFANputlabel

(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

(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.

label

char *

character* (*)

Object description string.

desc_len

int32

integer

Length of the description in bytes.

EXAMPLE 4. 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:

#include "hdf.h"

#define X_LENGTH 3
#define Y_LENGTH 2
#define Z_LENGTH 5

main( )
{

	/* Create the data array. */
	static float32 sds_data[X_LENGTH][Y_LENGTH][Z_LENGTH] =
	{  1,  2,  3,  4,  5,
	   6,  7,  8,  9, 10,
	  11, 12, 13, 14, 15,
	  16, 17, 18, 19, 20,
	  21, 22, 23, 24, 25,
	  26, 27, 28, 29, 30 };

	/* 
	* Create the array that will hold the dimensions of 
	* the data array.
	*/
	int32 dims[3] = {X_LENGTH, Y_LENGTH, Z_LENGTH};
	intn refnum, status;
	static char object_desc[] = "This is an object description.";
	static char object_label[] = "This is an object label.";

	/* Write the data to the HDF file. */
	status = DFSDadddata("Example1.hdf", 3, dims, (VOIDP)sds_data);

	/* Get the reference number for the newly written data set. */
	refnum = DFSDlastref( );

	/* Assign the object label to the scientific data set. */
	status = DFANputlabel("Example1.hdf", DFTAG_NDG, refnum, \
					object_label); 

	/* Assign the object description to the scientific data set. */
	status = DFANputdesc("Example1.hdf", DFTAG_NDG, refnum, \
					object_desc, strlen(object_desc));

}


 FORTRAN:	

PROGRAM ANNOTATE OBJECT integer dsadata, dims(3), status, refnum integer daplab, dapdesc, dslref integer*4 DFTAG_NDG, X_LENGTH, Y_LENGTH, Z_LENGTH parameter(DFTAG_NDG = 720, + X_LENGTH = 5, + Y_LENGTH = 2, + Z_LENGTH = 3) C Create the data array. real*4 sds_data(X_LENGTH, Y_LENGTH, Z_LENGTH) data sds_data / + 1, 2, 3, 4, 5, + 6, 7, 8, 9, 10, + 11, 12, 13, 14, 15, + 16, 17, 18, 19, 20, + 21, 22, 23, 24, 25, + 26, 27, 28, 29, 30 / C Create the array the will hold the dimensions of the data array. data dims /X_LENGTH, Y_LENGTH, Z_LENGTH/ C Write the data to the HDF file. ref = dsadata('Example1.hdf', 3, dims, sds_data) C Get the reference number for the newly written data set. refnum = dslref( ) C Assign the object label to the scientific data set. status = daplab('Example1.hdf', DFTAG_NDG, refnum, + 'This is an object label.') C Assign an object description to the scientific data set. status = dapdesc('Example1.hdf', DFTAG_NDG, refnum, + 'This is an object description.', 30) end



[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.