Writing data to an image array involves the following steps:
The calling program must contain the following sequence of calls:
C: file_id = Hopen(filename, access_mode, num_dds_block);
gr_id = GRstart(file_id);
ri_id = GRselect(gr_id, ri_index);
OR ri_id = GRcreate(gr_id, name, n_comps, number_type, interlace_mode, dim_sizes);
status = GRwriteimage(ri_id, start, stride, edges, data);
status = GRendaccess(gr_id);
status = GRend(ri_id);
status = Hclose(file_id);
FORTRAN: file_id = hopen(filename, access_mode, num_dds_block)
gr_id = mgstart(file_id)
ri_id = mgselct(gr_id, ri_index);
OR ri_id = mgcreat(gr_id, name, n_comps, number_type, interlace_mode, dim_sizes);
status = mgwrimg(ri_id, start, stride, edges, data)
OR status = mgwrcmg(ri_id, start, stride, edges, data)
status = mgendac(ri_id)
status = mgend(gr_id)
status = hclose(file_id)As with SD arrays, whole raster images, subsamples, and slabs can be written. The data to be written is defined by the values of the parameters
start, stride, and edges, which correspond to the coordinate location of the data origin, number of values to be skipped along each dimension during write operation, and number of elements to be written along each dimension.
The array start specifies the starting location of the data to be written. Valid values of each element in the array start are 0 to the size of the corresponding raster image dimension - 1. The first element of the array start specifies an offset from the beginning of the array data along the fastest-changing dimension, which is the second dimension in C and the first dimension in FORTRAN-77. The second element of the array start specifies an offset from the beginning of the array data along the second fastest-changing dimension, which is the first dimension in C and the second dimension in FORTRAN-77. For example, if the first value of the array start is 2 and the second value is 3, the starting location of the data to be written is at the fourth row and third column in C, and at the third row and fourth column in FORTRAN-77. Note that the correspondence between elements in the array start and the raster image dimensions in the GR interface is different from that in the SD interface. See Section 3.6 on page 55 on SDreaddata for an example of this.
Note that the FORTRAN-77 version of GRwriteimage has two routines; mgwrimg writes buffered numeric data and mgwcimg writes buffered character data.
GRwriteimage returns either SUCCEED (or 0) or FAIL (or -1). The parameters for GRwriteimage are described in Table 8C.
In this example, the program creates the HDF file called "General_RImages.hdf" and a raster image in the file. The image created is of size 5x10 and named "Image Array 1", and has data of the int16 data type, 2 components, and interlace mode MFGR_INTERLACE_PIXEL. Then the program writes the image data, terminates access to the image and the GR interface, and closes the file.
In this example, the program selects the only raster image in the file "General_RImages.hdf" created and written in Example 1, and modifies image data. The program also creates another raster image that is named "Image Array 2" and has 3 components with dimension size of 4x6, data type of DFNT_CHAR8, and interlace mode of MFGR_INTERLACE_PIXEL.
FORTRAN-77 version
C: status = GRsetcompress(ri_id, comp_type, c_info);
FORTRAN: status = mgscompress(ri_id, comp_type, comp_prm)The compression method is specified by the parameter
comp_type. Valid values of the parameter comp_type are: COMP_CODE_NONE (or 0) for no compression
COMP_CODE_RLE (or 1) for RLE run-length encoding
COMP_CODE_SKPHUFF (or 3) for Skipping Huffman compression
COMP_CODE_DEFLATE (or 4) for GZIP compression
COMP_CODE_JPEG (or 6) for JPEG compression
c_info in C and the parameter comp_prm in FORTRAN-77. The parameter c_info has type comp_info and contains algorithm-specific information for the library compression routines. The type comp_info is described in the header file "hcomp.h" and in the Reference Manual page for SDsetcompress. Compression parameters are only needed when Skipping Huffman or GZIP compression methods are applied.
The skipping size for the Skipping Huffman algorithm is specified in the field c_info.skphuff.skp_size in C and in the parameter comp_prm(1) in FORTRAN-77.
The deflate level for the GZIP algorithm is specified in the field c_info.deflate.level in C and in the parameter comp_prm(1) in FORTRAN-77.
GRsetcompress returns either SUCCEED (or 0) or FAIL (or -1). The GRsetcompress parameters are further described in Table 8D.
C: ri_id = GRcreate(gr_id, name, n_comps, data_type, interlace_mode, dim_sizes);
status = GRsetexternalfile(ri_id, filename, offset);
status = GRwriteimage(ri_id, start, stride, edges, image_data);
status = GRendaccess(ri_id);
FORTRAN: ri_id = mgcreat(gr_id, name, n_comps, data_type, interlace_mode, dim_sizes)
status = mgsxfil(ri_id, filename, offset)
status = mgwrimg(ri_id, start, stride, edges, image_data)
status = mgendac(ri_id)GRsetexternalfile marks the image identified by the parameter
ri_id as one whose data is to be written to an external file. The parameter filename is the name of the external file, and the parameter offset specifies the number of bytes from the beginning of the external file to the location where the first byte of data will be written.
GRsetexternalfile can only be called once per data set. If a file with the same name as filename exists in the current directory, HDF will use it as the external file. If the file does not exist, HDF will create one. Once the name of the external file is specified, it is impossible to change it without breaking the association between the raster image and its data.
Use caution when writing to existing files because the routine GRwriteimage begins its write at the specified offset without checking whether existing data is being overwritten. When different data sets have arrays being stored the same external file, the calling program is responsible for avoiding any overlap between them.
GRsetexternalfile returns either SUCCEED (or 0) or FAIL (or -1). The parameters of GRsetexternalfile are further defined in Table 8E.
The calling program must make the following calls:
C: ri_id = GRselect(gr_id, ri_index);
status = GRsetexternalfile(ri_id, filename, offset);
status = GRendaccess(ri_id);
FORTRAN: ri_id = mgselct(gr_id, ri_index);
status = mgsxfil(ri_id, filename, offset)
status = mgendac(ri_id);When GRsetexternalfile is used in conjunction with GRselect, it will immediately write the existing data to the external file; any data in the external file that occupies the space reserved for the external array will be overwritten as a result of this operation. A data set can only be moved to an external file once.
During the operation, the data is written to the external file as a contiguous stream regardless of how it is stored in the primary file. Because data is moved "as is," any unwritten locations in the data set are preserved in the external file. Subsequent read and write operations performed on the data set will access the external file.