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. 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. 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.int16 and the values of the other three attributes are of type char8.
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.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.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.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. 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
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