C: gr_id = GRstart(filename, access_mode); status = GRsetattr(gr_id|ri_id, attr_name, data_type, count, attr_value); status = GRend(gr_id); FORTRAN: gr_id = mgstart(filename, access_mode) status = mgsnatt(gr_id|ri_id, attr_name, data_type, count, attr_value) status = mgend(gr_id)
In GRsetattr the first argument can either be the id of a file, palette or raster image. The attribute will be assigned to the object referred to by this identifier. The argument attr_name contains the name of the attribute and can be no more than MAX_GR_NAME characters in length. Passing the name of an existing attribute will overwrite the value portion of that attribute.
EXAMPLE 9. Setting File and Image Attribute Values
The following code segment calls GRsetattr to assign file and image attributes to a general raster data set.
#include "hdf.h" main( ) { int32 gr_id, ri_id, file_id, dim_index, status; int32 num_values[2]; /* Open the file. */ file_id = Hopen("Example5.hdf", DFACC_RDWR, 0); /* Initialize the GR interface. */ gr_id = GRstart(file_id); /* Set an attribute that describes the file contents. */ status = GRsetattr(gr_id, "File contents", DFNT_CHAR8, 16, \ (VOIDP)"RGB image data"); /* Get the identifier for the first data set. */ ri_id = GRselect(gr_id, 0); /* Set an attribute the specifies a valid range of values. */ num_values[0] = 2; num_values[1] = 10; status = GRsetattr(ri_id, "Value range", DFNT_INT32, 2, \ (VOIDP)num_values); /* Terminate access to the image. */ status = GRendaccess(ri_id); /* Terminate access to the GR interface. */ status = GRend(gr_id); /* Close the file. */ status = Hclose(file_id); }
PROGRAM SET IMAGE ATTRIBS integer*4 gr_id, ri_id, file_id, status integer num_values(2) integer mgstart, mgsnatt, mgselct integer mgendac, mgend, hopen, hclose integer DFACC_RDWR, DFNT_CHAR8, DFNT_INT32 parameter (DFACC_RDWR = 3, DFNT_CHAR8 = 4, DFNT_INT32 = 24) C Open the file. file_id = hopen(`Example5.hdf', DFACC_RDWR, 0) C Initialize the GR interface. gr_id = mgstart(file_id) C Set an attribute that describes the file contents. status = mgsnatt(gr_id, `File contents', DFNT_CHAR8, 16, + `RGB image data') C Get the identifier for the first data set. ri_id = mgselct(gr_id, 0) C Set an attribute the specifies a valid range of values. num_values(1) = 2 num_values(2) = 10 status = mgsnatt(ri_id, `Value range', DFNT_INT32, 2, num_values) C Terminate access to the image. status = mgendac(ri_id) C Terminate access to the GR interface. status = mgend(gr_id) C Close the file. status = hclose(file_id) end
8.8.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 in the object. Given a file, array or dimension id and an attribute name, GRfindattr will return a valid attribute index if the attribute exists. The attribute index can then be used to retrieve information about an attribute or its values. Given a file or array and a valid attribute index GRattrinfo returns the name, data type and count for the attribute if it exists.
C: status = GRfindattr(ri_id|gr_id, attr_name); status = GRattrinfo(ri_id|gr_id, attr_index, attr_name, &data_type, &count); FORTRAN: status = mgfndat(ri_id|gr_id, attr_name) status = mgatinf(ri_id|gr_id, attr_index, attr_name, data_type, count);
The parameters for GRfindattr and GRattrinfo are further described below. (See Table 8K.)
8.8.4 Reading User-Defined Attributes: GRgetattr
GRgetattr reads an attribute's values. The syntax for GRgetattr is as follows:
C: status = GRgetattr(ri_id|gr_id, attr_index, data); FORTRAN: status = mggnatt(ri_id|gr_id, attr_index, data)
GRgetattr takes a file, array, or dimension identifier and an attribute index specified in the attr_index parameter as input parameters and returns the attribute's values in the buffer data.
TABLE 8K GRsetattr, GRfindattr, GRattrinfo and GRgetattr Parameter List
C:
#include "hdf.h" main( ) { int32 gr_id, ri_id, file_id, status; int32 attr_index, data_type, count; char attr_name[MAX_GR_NAME]; int8 *buffer; /* Open the file. */ file_id = Hopen("Example5.hdf", DFACC_RDONLY, 0); /* Initialize the GR interface. */ gr_id = GRstart(file_id); /* Find the file attribute named "File contents". */ attr_index = GRfindattr(gr_id, "File contents"); /* Get information about the file attribute. */ status = GRattrinfo(gr_id, attr_index, attr_name, &data_type, &count); /* Allocate a buffer to hold the attribute data. */ buffer = HDmalloc(count * DFKNTsize(data_type)); /* Read the attribute data. */ status = GRgetattr(gr_id, attr_index, buffer); /* Free the buffer memory. */ HDfree(buffer); /* Get the identifier for the first image. */ ri_id = GRselect(gr_id, 0); /* Find the data set attribute named "Value range". */ attr_index = GRfindattr(ri_id, "Value range"); /* Get information about the image attribute. */ status = GRattrinfo(ri_id, attr_index, attr_name, &data_type, &count); /* Allocate a buffer to hold the attribute data. */ buffer = HDmalloc(count * DFKNTsize(data_type)); /* Read the attribute data. */ status = GRgetattr(ri_id, attr_index, buffer); /* Terminate access to the array */ status = GRendaccess(ri_id); /* Terminate access to the GR interface. */ status = GRend(gr_id); /* Close the file */ status = Hclose(file_id); }
PROGRAM IMAGE ATTRIB INFO integer*4 gr_id, ri_id, file_id integer attr_index, data_type, count, status character attr_name *13 character buffer *20 integer mgstart, mgfndat, mgatinf, mggnatt, mgselct integer mgendac, mgend, hopen, hclose C DFACC_RDONLY is defined in hdf.h. integer DFACC_RDONLY parameter (DFACC_RDONLY = 1) C Open the file. file_id = hopen(`Example5.hdf', DFACC_RDONLY, 0) C Open the file. gr_id = mgstart(file_id) C Find the file attribute named `File contents'. attr_index = mgfndat(gr_id, `File contents') C Get information about the file attribute. status = mgatinf(gr_id, attr_index, attr_name, data_type, count) C Read the attribute data. status = mggnatt(gr_id, attr_index, buffer) C Get the identifier for the first image. ri_id = mgselct(gr_id, 0) C Find the data set attribute named "Value range". attr_index = mgfndat(ri_id, `Value range') C Get information about the image attribute. status = mgatinf(ri_id, attr_index, attr_name, data_type, count) C Read the attribute data. status = mggnatt(ri_id, attr_index, buffer) C Terminate access to the array. status = mgendac(ri_id) C Terminate access to the GR interface. status = mgend(gr_id) C Close the file. status = hclose(file_id) end