[Top] [Prev]

11.7 Determining Reference Numbers

It is advisable to check the reference number before attempting to assign an object annotation, as the overwriting of reference numbers is not prevented by the HDF library routines.

There are three ways to check a reference number for an object:

11.7.1 Determining a Reference Number for the Last Object Accessed: DF*lastref and DF*writeref

There are two methods of obtaining a reference number through the use of a DF*lastref call. The first approach is to obtain and store the reference number of an object immediately after the object is created:

  1. Create the data object.
  2. Call DF*lastref to determine its reference number.
  3. Read or write an object annotation.

The second approach is to determine the reference number at some time after the data object is created. This approach requires repeated DF*read calls until the appropriate object is accessed, followed by a call to DF*lastref:

  1. Read the appropriate data object.
  2. Call DF*lastref to determine its reference number.
  3. Read or write and object annotation.

Most HDF interfaces provide one routine that assigns a specified reference number to a data object and another routine that returns the reference number for the last data object accessed. (See Table 11H.) However, the SD interface doesn't. Also, the DFAN annotation doesn't include a DF*lastref routine.

Although DF*writeref calls are designed to assign specific reference numbers, they are not recommended for general use because there is no protection against reassigning an existing reference number and overwriting data. In general, it is better to determine a reference number for a data object by calling DF*lastref immediately after reading or writing a data object.

The DF*lastref routines have no parameters. The DF*writeref routines have two: filename, which is the name of the file that contains the data object, and ref, which is the reference number for the next data object read operation.

The DF*lastref and DF*writeref routines are further described in the following table.

TABLE 11H - List and Descriptions of the DF*writeref and DF*lastref Routines

HDF Data Object
Routine Name
(FORTRAN-77)
Description
8-bit Raster Image
DFR8writeref (d8wref) Assigns the specified number as the reference number for the next 8-bit raster write operation and updates the write counter to the reflect highest reference number

DFR8lastref (d8lref) Returns the reference number for the last 8-bit raster image set accessed

24-bit Raster Image
DF24writeref (d2wref) Assigns the specified number as the reference number for the next 24-bit raster write operation and updates the write counter to reflect the highest reference number

DF24lastref (d2lref) Returns the reference number for the last 24-bit raster image set accessed

Palette
DFPwriteref (dpwref) Assigns the specified number as the reference number for the next palette write operation and updates the write counter to reflect the highest reference number

DFPlastref (dplref) Returns the reference number for the last palette accessed

DFSD Scientific Data
DFSDwriteref (dswref) Assigns the specified number as the reference number for the next SDS write operation and updates the write counter to reflect the highest reference number

DFSDlastref (dslref) Returns the reference number for the last scientific data set accessed

Annotation
DFANlastref (dalref) Returns the reference number for the last annotation accessed

11.7.2 Querying a List of Reference Numbers for a Given Tag: DFANlablist

Given a tag and two buffers, DFANlablist will fill one buffer with all reference numbers for the given tag and the other with all labels assigned to the given tag. The programming model for determining a list of reference numbers is as follows:

  1. Determine the number of reference numbers that exist for a given tag.
  2. Allocate a buffer to store the reference numbers.
  3. Specify the maximum label length.
  4. Allocate a buffer to store the labels.
  5. Store the list of reference numbers and their labels.

To create a list of reference numbers and their labels for a given tag, the following routines should be called:

C:		num_refs = Hnumber(file_id, tag);
		ref_buf = HDmalloc(sizeof(uint16*)*num_refs);
		max_lab_len = 16;
		label_buf = HDmalloc(max_lab_len * num_refs);
		start_pos = 0;
		num_of_refs = DFANlablist(filename, tag, ref_buf, label_buf,
		num_refs, max_lab_len, 
		start_pos);
FORTRAN:	num_refs = hnumber(file_id, tag)
		max_lab_len = 16
		start_pos = 0
		num_of_refs = dallist(filename, tag, ref_buf, label_buf,
		num_refs, max_lab_len, start_pos)

Hnumber determines how many objects with the specified tag are in a file. It is described in Chapter 2, HDF Fundamentals.

DFANlablist has seven parameters: filename, tag, ref_list, label_buf, num_refs, max_lab_len, and start_pos. The filename parameter specifies the name of the file to search and tag specifies the search tag to use when creating the reference and label list. The ref_buf and label_buf parameters are buffers used to store the reference numbers and labels associated with tag. The num_ref parameter specifies the length of the reference number list and the max_lab_len parameter specifies the maximum length of a label. The start_pos parameter specifies the first label to read. For instance, if start_pos has a value of 1 all labels will be read; if it has a value of 4, all but the first three labels will be read.

Taken together, the contents of ref_list and label_list constitute a directory of all objects and their labels for a given tag. The contents of label_list can be displayed to show all of the labels for a given tag or it can be searched to find the reference number of a data object with a certain label. Once the reference number for a given label is found, the corresponding data object can be accessed by invoking other HDF routines. Therefore, this routine provides a mechanism for direct access to data objects in HDF files.

TABLE 11I - DFANlablist Parameter List

Routine Name

[Return Type]

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

[int]

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

tag
uint16
integer
Tag assigned to the annotated object.

ref_list
uint16 []
integer (*)
Reference number for the annotated object.

label_list
char *
character*(*)
Buffer for the labels.

list_len
int
integer
Size of the reference number and label lists.

label_len
intn
integer
Maximum label length.

start_pos
intn
integer
First entry in the reference number and label lists to be returned.

EXAMPLE 5. Getting a List of Labels for All Scientific Data Sets

These examples illustrate the method used to get a list of all labels used in scientific data sets in an HDF file using DFANlablist. The DFS_MAXLEN definition is located in the "hlimits.h" include file.

C version

FORTRAN-77 version

11.7.3 Locate an Object by Its Tag and Reference Number: Hfind

Instead of using DFANlablist to create a list of reference numbers to search, HDF provides a general search routine called Hfind. Hfind is described in Chapter 2, HDF Fundamentals.



[Top] [Prev]

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