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

8.4 Programming Model for the GR Interface

As with the SD interface, the GR interface relies on the calling program to initiate and terminate access to files and data sets to support multifile access. The GR programming model for accessing a general raster data set is as follows:

1. Open a file by obtaining a file id from a file name.
2. Initialize the GR interface and obtain a general raster interface id.
3. Open an existing general raster data set by obtaining a data set id from the interface id and data set index OR create a new general raster data set by obtaining a data set id from the data set name and data type.
4. Perform desired operations on the data set.
5. Dispose of the raster image id.
6. Terminate access to the GR interface by disposing of the interface id.
7. Close the file.
To access a single raster image data set in an HDF file, the calling program must contain the following calls:

C:		file_id = Hopen(filename, access_mode, number_of_desc);
		gr_id = GRstart(file_id);
		ri_id = GRselect(gr_id, gr_index);
		<Optional operations>
		status = GRendaccess(ri_id);
		status = GRend(gr_id);
		status = Hclose(file_id);

FORTRAN:	file_id = hopen(filename, access_mode, number_of_desc)
		gr_id = mgstart(file_id)
		ri_id = mgselct(gr_id, gr_index)
		<Optional operations>
		status = mgendac(ri_id)
		status = mgend(gr_id)
		status = hclose(file_id)

To access several files at the same time, a calling program must obtain a separate file id for each file to be opened. Similarly, to access more than one general raster data set a calling program must obtain a separate interface id for each data set. For example, to open two data sets stored in two files a program would execute the following series of function calls:

C:		file_id_1 = Hopen(filename_1, access_mode, number_of_desc);
		gr_id_1 = GRstart(file_id_1);
		ri_id_1 = GRselect(gr_id_1, gr_index_1);
		file_id_2 = Hopen(filename_2, access_mode, number_of_desc);
		gr_id_2 = GRstart(file_id_2);
		ri_id_2 = GRselect(gr_id_2, gr_index_2);
		<Optional operations>
		status = GRendaccess(ri_id_1);
		status = GRend(gr_id_1);
		status = Hclose(file_id_1);
		status = GRendaccess(ri_id_2);
		status = GRend(gr_id_2);
		status = Hclose(file_id_2);

FORTRAN:	file_id_1 = hopen(filename_1, access_mode, number_of_desc)
		gr_id_1 = mgstart(file_id_1)
		ri_id_1 = mgselct(gr_id_1, gr_index_1)
		file_id_2 = hopen(filename_2, access_mode, number_of_desc)
		gr_id_2 = mgstart(file_id_2)
		ri_id_2 = mgselct(gr_id_2, gr_index_2)
		<Optional operations>
		status = mgendac(ri_id_1)
		status = mgend(gr_id_1)
		status = hclose(file_id_1)
		status = mgendac(ri_id_2)
		status = mgend(gr_id_2)
		status = hclose(file_id_2)

Because every file and general raster data set is assigned its own identifier, the order in which files and data sets are accessed is very flexible as long as all file and general raster data set ids are individually discarded before the end of the calling program.

8.4.1 Accessing Files and Images: GRstart and GRselect

In the GR interface, Hopen is used to open files. This differs from the SD programming model where SDstart is used for this purpose. For information on the use of Hopen refer to Chapter 2, titled HDF Fundamentals and for information on SDstart refer to Chapter 3, titled Scientific Data Sets (SD API).

GRstart initializes the GR interface and must be called once after Hopen and before any other GR routines are called. It takes one argument; the file_id returned by Hopen and returns the interface id gr_id.

GRselect specifies the given image as the current image to be accessed. It takes two arguments: the gr_id returned by GRstart and gr_index and returns the raster image id ri_id. The argument gr_index is the position of the data set relative to the beginning of the file. The argument gr_index is zero-based, meaning that the index of first image in the file is 0.

The parameters for GRstart and GRselect are further defined below. (See Table 8B.)

8.4.2 Terminating Access to Files and Images: GRendaccess and GRend

GRendaccess disposes of the open raster image id ri_id and terminates access to the data set initiated by the corresponding call to GRselect. The calling program must make one GRendaccess call for every GRselect call made during its execution. Failing to call GRendaccess for each call to GRselect may result in a loss of data.

GRend disposes of the general raster data set id gr_id and terminates the access to the GR interface initiated by the corresponding call to GRstart. The calling program must make one GRend call for every GRstart call made during its execution and failing to call GRend for each GRstart may result in a loss of data. The parameters for GRendaccess and GRend are listed and defined in the following table.

TABLE 8B GRstart, GRselect, GRend and GRendaccess Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

GRstart

(mgstart)

file_id

int32

integer

File identifier.

GRselect

(mgselct)

gr_id

int32

integer

General raster data set identifier.

gr_index

int32

integer

Position of the general raster data set within the file.

GRend

(mgend)

gr_id

int32

integer

General raster data set identifier.

GRendaccess

(mgendac)

ri_id

int32

integer

Image array identifier.



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

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