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

10.6 Reading Annotations

The DFAN interface provides two functions for reading file annotations, which are described below.

10.6.1 Reading a File Label: DFANgetfidlen and DFANgetfid

The DFAN programming model for reading a file label is as follows:

1. Get the length of the label.
2. Read the file label.
To read the first file label in a file, the calling program must contain the following function calls:

C:		isfirst = 1;
		label_length = DFANgetfidlen(file_id, isfirst);
		label_buffer = HDgetspace(label_length);
		fid_len = DFANgetfid(file_id, label_buffer, label_length, 
isfirst);

FORTRAN:	isfirst = 1
		label_length = dagfidl(file_id, isfirst)
		fid_len = dagfid(file_id, label_buffer, label_length, isfirst)

DFANgetfidlen has two parameters: file_id and isfirst. The isfirst parameter specifies whether the first or subsequent file annotations are to be read. To read the first file label length isfirst should be set to the value 1, to sequentially step through all the remaining file labels assigned to a file isfirst should be set to 0.

When DFANgetfidlen is first called for a given file, it returns the length of the first file label. To get the lengths of subsequent file labels, you must call DFANgetfid between calls to DFANgetfidlen. Otherwise, additional calls to DFANgetfidlen will return the length of the same file label.

DFANgetfid has four parameters: file_id, label_buffer, label_length, and isfirst. The label_buffer parameter is a pointer to a buffer for the label text. The label_length parameter is the length of the buffer in memory which can be shorter than the full length of the label in the file. If the label_length is not large enough, the label is truncated to label_length-1 characters in the buffer label_buffer. The isfirst parameter is used to read the first or subsequent file annotations. To read the first file label isfirst should be set to 1, to sequentially step through all the remaining file labels assigned to a file isfirst should be set to 0.

HDgetspace is described in Chapter 2, titled HDF Fundamentals.

The parameters of DFANgetfidlen and DFANgetfid are described below. (See Table 10E on page 256.)

10.6.2 Reading a File Description: DFANgetfdslen and DFANgetfds

The DFAN programming model for reading a file description is as follows:

1. Get the length of the description.
2. Read the file description.
To read the first file description in a file, the calling program must contain the following calls:

C:		isfirst = 1;
		desc_length = DFANgetfdslen(file_id, isfirst);
		desc_buffer = HDgetspace(desc_length);
		fds_len = DFANgetfds(file_id, desc_buf, desc_length, isfirst);

FORTRAN:	isfirst = 1
		desc_length = dagfdsl(file_id, isfirst)
		fds_len = dagfds(file_id, desc_buf, desc_length, isfirst)

DFANgetfdslen has two parameters: file_id and isfirst. The isfirst parameter specifies whether the first or subsequent file annotations are to be read. To read the first file description length isfirst should be set to the value 1, to sequentially step through all the remaining file descriptions assigned to a file isfirst should be set to 0.

When DFANgetfdslen is first called for a given file, it returns the length of the first file description. To get the lengths of successive file descriptions, you must call DFANgetfds between calls to DFANgetfdslen as with DFANfidgetlen.

DFANgetfds has four parameters: file_id, desc_buf, desc_length, and isfirst. The desc_buffer parameter is a pointer to a buffer for the description text. The desc_length parameter is the length of the buffer in memory which can be shorter than the full length of the description in the file. If the desc_length is not large enough, the description is truncated to desc_length characters in the buffer desc_buf. The isfirst parameter specifies whether the first or subsequent file annotations are to be read. To read the first file description isfirst should be set to the value 1, to sequentially step through all the remaining file descriptions assigned to a file isfirst should be set to 0.

The parameters of these routines are described further in the following table.

TABLE 10E DFANgetfidlen, DFANgetfid, DFANgetfdslen and DFANgetfds Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFANgetfidlen

(dagfidl)

file_id

int32

integer

File identifier.

isfirst

intn

integer

Location of the next annotation.

DFANgetfid

(dagfid)

file_id

int32

integer

File identifier.

desc_buf

char *

character* (*)

File label buffer.

buf_length

int32

integer

Label buffer length.

isfirst

intn

integer

Location of the next annotation

DFANgetfdslen

(dagfdsl)

file_id

int32

integer

File identifier.

isfirst

intn

integer

Location of the next annotation.

DFANgetfds

(dagfds)

file_id

int32

integer

File identifier.

description

char *

character* (*)

File description buffer.

desc_length

int32

integer

Description buffer length.

isfirst

intn

integer

Location of the next annotation.

EXAMPLE 5. Reading a File Label and a File Description

The following examples read a file label from the HDF file named "Example1.hdf". The DFANgetfidlen routine is used to verify the length of the label before the read operation is performed. The argument "1" in both routines indicate the first description in the HDF file is the target. DFANgetfdslen and DFANgetfds can be directly substituted for DFANgetfidlen and DFANgetfid in order to read a file description instead of a file label.

C:

#include "hdf.h"

main( )
{
	int32 file_id, file_label_len;
	char *file_label;
	intn status;

	/* Open the HDF file containing the annotation. */
	file_id = Hopen("Example1.hdf", DFACC_READ, 0);
      
	/* Determine the length of the file label. */
	file_label_len = DFANgetfidlen(file_id, 1);
    
	/* Allocated memory for the file label buffer. */
	file_label = HDgetspace(file_label_len);

	/* Read the file label. */
	file_label_len = DFANgetfid(file_id, file_label, file_label_len, 1);

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

}


 FORTRAN:	

PROGRAM GET ANNOTATION integer status, file_id, label_length integer hopen, hclose, dagfidl, dagfid character file_label(50) integer*4 DFACC_READ parameter(DFACC_READ = 1) C Open the HDF file containing the file label. file_id = hopen("Example1.hdf", DFACC_READ, 0) C Determine the length of the file label. label_length = dagfidl(file_id, 1) C Read the file label. status = dagfid(file_id, file_label, label_length, 1) C Close the HDF file. status = hclose(file_id) end

10.6.3 Reading an Object Label: DFANgetlablen and DFANgetlabel

The DFAN programming model for reading a object label is as follows:

1. Get the length of the label.
2. Read the file label.
To read the first object label in a file, the calling program must contain the following routines:

C:		label_length = DFANgetlablen(filename, tag, ref);
		label_buf = HDgetspace(label_length);
		status = DFANgetlabel(filename, tag, ref, label_buf, 
label_length);

FORTRAN:	label_length = daglabl(filename, tag, ref)
		status = daglab(filename, tag, ref, label_buf, label_length)	

DFANgetlablen returns the length of the label assigned to the object identified by the given tag/reference number pair. DFANgetlabel must be called between calls to DFANgetlablen - it is the routine that actually returns the label and prepares the API to read the next label.

DFANgetlabel has five parameters: filename, tag, ref, label_buf, and label_length. The label_buf parameter is a pointer to a buffer that stores the label text. The label_length parameter is the length of the buffer in memory - this can be shorter than the full length of the label in the file. If the label_length is not large enough, the label is truncated to label_length characters in the buffer label_buf. The length of label_buf must be at least one greater than the anticipated length of the label, to account for the null termination appended to the label text.

The parameters of DFANgetlablen and DFANgetlabel are defined below.

10.6.4 Reading an Object Description: DFANgetdesclen and DFANgetdesc

The DFAN programming model for reading a object description is as follows:

1. Get the length of the description.
2. Read the file description.
To read the first object description in a file, the calling program must contain the following routines:

C:		desc_length = DFANgetdesclen(filename, tag, ref);
		desc_buf = HDgetspace(desc_length);
		status = DFANgetdesc(filename, tag, ref, desc_buf, desc_length);

FORTRAN:	label_length = dagdlen(filename, tag, ref)
		status = dagdesc(filename, tag, ref, desc_buf, desc_length)	

DFANgetdesclen returns the length of the description assigned to the object identified by the specified tag/reference number pair. DFANgetdesc must be called between calls to DFANgetdesclen to reset the current object description to the next in the file.

DFANgetdesc takes five parameters: filename, tag, ref, desc_buf, and desc_length. The desc_buf parameter is a pointer to the buffer that stores the description text. The desc_length parameter is the length of the buffer in memory which can be shorter than the full length of the description in the file. If the desc_length is not large enough, the description is truncated to desc_length characters in the buffer desc_buf.

The parameters of DFANgetdesclen and DFANgetdesc are defined in the following table.

TABLE 10F DFANgetlablen, DFANgetlabel, DFANgetdesc and DFANgetdesclen Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFANgetlablen

(dagllen)

filename

char *

character* (*)

Name of the file to be accessed.

tag

uint16

integer

Tag assigned to the annotated object.

ref

uint16

integer

Reference number for the annotated object.

DFANgetlabel

(daglab)

filename

char *

character* (*)

Name of the file to be accessed.

tag

uint16

integer

Tag assigned to the annotated object.

ref

uint16

integer

Reference number assigned to the annotated object.

label_buf

char *

character* (*)

Buffer for the returned annotation.

label_length

int32

integer

Size of the buffer allocated to hold the annotation.

DFANgetdesclen

(dagdlen)

filename

char *

character* (*)

Name of the file to be accessed.

tag

uint16

integer

Tag assigned to the annotated object.

ref

uint16

integer

Reference number for the annotated object.

DFANgetdesc

(dagdesc)

filename

char *

character* (*)

Name of the file to be accessed.

tag

uint16

integer

Tag assigned to the annotated object.

ref

uint16

integer

Reference number assigned to the annotated object.

desc_buf

char *

character* (*)

Buffer for the returned annotation.

desc_length

int32

integer

Size of the buffer allocated to hold the annotation.

EXAMPLE 6. Reading an Object Label and Description

The following examples demonstrate the use of DFANgetdesclen and DFANgetdesc to read an object description assigned to a scientific data set. These examples assume that, in addition to other data objects, the "Example1.hdf" HDF file also contains multiple scientific data sets, some of which may not be annotated. Hfind is used to determine the reference number for the first annotated scientific data object in the file.

C:

#include "hdf.h"

main( )
{
	intn desc_length = -1, status;
	char desc[50];
	int32 file_id;
	uint16 tag = 0, ref = 0;
	uint32 find_offset, find_length;

	/* Open the file and initialize the searching parameters to 0. */
	file_id = Hopen("Example1.hdf", DFACC_READ, 0);

	/*
	* Start a sequential forward search for the first reference
	* number assigned to a scientific data set.
	*/
	while (Hfind(file_id, DFTAG_NDG, DFREF_WILDCARD, &tag, &ref, \
		&find_offset, &find_length, DF_FORWARD) != FAIL) {

	/*
	* After discovering a valid reference number, check for an
	* object description by returning the length of the description.
	* If the inquiry fails, continue searching for the next valid
	* reference number assigned to a scientific data set.
	*/
	if ((desc_length = DFANgetdesclen("Example1.hdf", tag, ref)) \
		== FAIL)
		break;

	/* 
	* If a description exists and it will fit in the description buffer,
	* print it.
	*/
	if (desc_length != FAIL && desc_length <= 50) {
		status = DFANgetdesc("Example1.hdf", tag, ref, desc, desc_length);
		printf("Description: %s\n", desc);
	}
	}

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

}


 FORTRAN:				

There is no Fortran-77 version of the Example 4 C code for this version of the documentation as there is no Fortran-77 equivalent of Hfind.



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

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