[Top] [Prev] [Next]

8.9 GR Data Set Attributes

The GR interface provides tools that attach attributes to particular images. This capability is similar to, though more limited than, attribute function capabilities of the SD interface. The concepts of user-defined and predefined attributes are explained in Chapter 3, Scientific Data Sets (SD API). The GR implementation of attributes is similar to the SD implementation. Attributes are not written out to a file until access to the object the attribute is attached to is terminated.

8.9.1 Predefined GR Attributes

The GR API library has only one predefined attribute: FILL_ATTR. This attribute defines a fill pixel, which is analogous to a fill value in the SD interface. It represents the default value that is written to each element of an image array not explicitly written to by the calling program, i.e., when only a portion of the entire image array is filled with data. This value must of the same data type as the rest of the initialized image data. The routine used to set the fill value, GRsetattr, is explained in the next section.

8.9.2 Setting User-defined Attributes: GRsetattr

GRsetattr creates or modifies an attribute for either a file or a raster image. If the attribute with the specified name does not exist, GRsetattr creates a new one. If the named attribute already exists, GRsetattr resets all the values that are different from those provided in its argument list. The syntax of GRsetattr is as follows:

C:		status = GRsetattr(obj_id, attr_name, data_type, n_values, attr_value);
FORTRAN:	status = mgsnatt(obj_id, attr_name, data_type, n_values, attr_value)
	OR	status = mgscatt(obj_id, attr_name, data_type, n_values, attr_value)
The first argument, obj_id, can either be the GR interface identifier or raster image identifier. The argument attr_name contains the name of the attribute and can be no more than MAX_GR_NAME (or 256) characters in length. Passing the name of an existing attribute will overwrite the value portion of that attribute.

The arguments data_type, n_values, and attr_value describe the right side of the label=value equation. The attr_value argument contains one or more values of the same data type. The data_type argument describes the data type for all values in the attribute and n_values contains the total number of values in the attribute.

Note that the FORTRAN-77 version of GRsetattr has two routines; mgsnatt writes numeric attribute data and mgscatt writes character attribute data.

GRsetattr returns either SUCCEED (or 0) or FAIL (or -1). The parameters for GRsetattr are further described in Table 8I on page 278.

EXAMPLE 5. Operations on File and Raster Image Attributes.

This example illustrates the use of the routines GRsetattr/mgsnatt/mgscatt to assign attributes to an HDF file and to an image.

In this example, the program sets two attributes to the existing file "General_RImages.hdf" and two attributes to the image named "Image Array 2". The file is created by the program in Example 1 and the image is created by the program in Example 2. The values of the second attribute of the image are of type int16 and the values of the other three attributes are of type char8.

C version

FORTRAN-77 version

8.9.3 Querying User-Defined Attributes: GRfindattr and GRattrinfo

Each attribute associated with an object has a unique attribute index, a value ranging from 0 to the total number of attributes attached to the object - 1. Given a GR interface or raster image identifier and an attribute name, GRfindattr will return a valid attribute index of the file or raster image attribute if the attribute exists. The attribute index can then be used to retrieve information about the attribute or its values. Given a GR interface or raster image identifier and a valid attribute index, GRattrinfo returns the name, data type, and number of values for the file or raster image attribute if the attribute exists.

The syntax for GRfindattr and GRattrinfo is as follows:

C:		attr_index = GRfindattr(obj_id, attr_name);
		status = GRattrinfo(obj_id, attr_index, attr_name, &data_type, &n_values);
FORTRAN:	attr_index = mgfndat(obj_id, attr_name)
		status = mgatinf(obj_id, attr_index, attr_name, data_type, n_values)
The parameter obj_id is either a GR interface identifier or a raster image identifier. The parameter attr_name specifies the name of the attribute. The parameter attr_index specifies the index of the attribute to be read. The attribute index is a zero-based integer and must be less than the total number of attributes assigned to the specified object. The parameter data_type specifies the data type of the attribute. And the parameter n_values specifies the number of attribute values.

GRfindattr returns the attribute index if successful and FAIL (or -1) otherwise. GRattrinfo returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The parameters for GRfindattr and GRattrinfo are further described in Table 8I.

8.9.4 Reading User-defined Attributes: GRgetattr

GRgetattr reads the values of an attribute assigned to the object identified by the parameter obj_id. The syntax for GRgetattr is as follows:

C:		status = GRgetattr(obj_id, attr_index, values);
FORTRAN:	status = mggnatt(obj_id, attr_index, values)
	OR	status = mggcatt(obj_id, attr_index, values)
The parameter obj_id is either a GR interface identifier or a raster image identifier. The parameter attr_index specifies the index of the attribute to be read. The attribute index is a zero-based integer and must be less than the total number of attributes assigned to the specified object.

It is assumed that the buffer values, allocated to hold the attribute values, is large enough to hold the data; if not, the data read will be truncated to the size of the buffer. The size of the buffer should be at least n_values*sizeof(data_type) bytes long. If an attribute contains multiple values, GRgetattr will return all of them. It is not possible to read a subset of values.

Note that the FORTRAN-77 version of GRgetattr has two routines; mggnatt reads numeric attribute data and mggcatt reads character attribute data.

GRgetattr returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise. The parameters for GRgetattr are further described in Table 8I.

TABLE 8I - GRsetattr, GRfindattr, GRattrinfo, and GRgetattr Parameter Lists

Routine Name

[Return Type]

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

[intn]

(mgsnatt/mgscatt)
obj_id
int32
integer
GR interface or raster image identifier

attr_name
char *
character*(*)
Name assigned to the attribute

data_type
int32
integer
Data type of the attribute

n_values
int32
integer
Number of values in the attribute

values
VOIDP
<valid numeric data type>(*)/character*(*)
Buffer with the attribute values

GRfindattr

[int32]

(mgfndat)
obj_id
int32
integer
GR interface or raster image identifier

attr_name
char *
character*(*)
Name of the attribute

GRattrinfo

[intn]

(mgatinf)
obj_id
int32
integer
GR interface or raster image identifier

attr_index
int32
integer
Index for the attribute to be read

attr_name
char *
character*(*)
Name of the attribute

data_type
int32 *
integer
Data type of the attribute values

n_values
int32 *
integer
Total number of values in the attribute

GRgetattr
[intn]
(mggnatt/
mggcatt)
obj_id
int32
integer
GR interface or raster image identifier

attr_index
int32
integer
Index for the attribute to be read

values
VOIDP
<valid numeric data type>(*)/character*(*)
Buffer for the attribute values

EXAMPLE 6. Obtaining File and Image Attribute.

This example illustrates the use of the routines GRattrinfo/mgatinf, GRfindattr/mgfndat, and GRgetattr/mggnatt/mggcatt to extract information and values of file and image attributes that were set by the program in Example 5.

In this example, the program gets the information about each file attribute, then extracts its values. The program then selects the second image in the file, finds the attribute named "Image Attribute 2", obtains the data type and the number of values in the attribute, and extracts its stored values.

C version

FORTRAN-77 version



[Top] [Prev] [Next]

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