[Top] [Prev] [Next]

11.5 Reading Annotations

The DFAN interface provides several functions for reading file and data object annotations, which are described below.

11.5.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 determine whether 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, HDF Fundamentals.

The parameters of DFANgetfidlen and DFANgetfid are described in Table 11E.

11.5.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. As with DFANgetfidlen, you must call DFANgetfds between calls to DFANgetfdslen to get the lengths of successive file descriptions.

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 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 11E - DFANgetfidlen, DFANgetfid, DFANgetfdslen, and DFANgetfds Parameter List

Routine Name

[Return Type]

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

[int32]

(dagfidl)
file_id
int32
integer
File identifier

isfirst
intn
integer
Location of the next annotation

DFANgetfid

[int32]

(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

[int32]

(dagfdsl)
file_id
int32
integer
File identifier

isfirst
intn
integer
Location of the next annotation

DFANgetfds

[int32]

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

FORTRAN-77 version

11.5.3 Reading an Object Label: DFANgetlablen and DFANgetlabel

The DFAN programming model for reading a data 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. DFANgetlabel 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. label_length can be shorter than the full length of the label in the file, but if so, 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.

11.5.4 Reading an Object Description: DFANgetdesclen and DFANgetdesc

The DFAN programming model for reading a data 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 11F - DFANgetlablen, DFANgetlabel, DFANgetdesc and DFANgetdesclen Parameter List

Routine Name

[Return Type]

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

[int32]

(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

[intn]

(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

[int32]

(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

[intn]

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

No FORTRAN-77 version for this example

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]

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