To access a single SDS in an HDF file, the calling program must contain the following calls:
C: sd_id = SDstart(filename, access_mode);
sds_id = SDcreate(sd_id, sds_name, data_type, rank, dim_sizes);
OR sds_id = SDselect(sd_id, sds_index);
<Optional operations>
status = SDendaccess(sds_id);
status = SDend(sd_id);
FORTRAN: sd_id = sfstart(filename, access_mode)
sds_id = sfcreate(sd_id, sds_name, data_type, rank, dim_sizes)
OR sds_id = sfselect(sd_id, sds_index)
<Optional operations>
status = sfendacc(sds_id)
status = sfend(sd_id)
To access several files at the same time, a program must obtain a separate SD file identifier (sd_id) for each file to be opened. Likewise, to access more than one SDS, a calling program must obtain a separate SDS identifier (sds_id) for each SDS. For example, to open two SDSs stored in two files a program would execute the following series of function calls.C: sd_id_1 = SDstart(filename_1, access_mode);
sds_id_1 = SDselect(sd_id_1, sds_index_1);
sd_id_2 = SDstart(filename_2, access_mode);
sds_id_2 = SDselect(sd_id_2, sds_index_2);
<Optional operations>
status = SDendaccess(sds_id_1);
status = SDend(sd_id_1);
status = SDendaccess(sds_id_2);
status = SDend(sd_id_2);
FORTRAN: sd_id_1 = sfstart(filename_1, access_mode)
sds_id_1 = sfselect(sd_id_1, sds_index_1)
sd_id_2 = sfstart(filename_2, access_mode)
sds_id_2 = sfselect(sd_id_2, sds_index_2)
<Optional operations>
status = sfendacc(sds_id_1)
status = sfend(sd_id_1)
status = sfendacc(sds_id_2)
status = sfend(sd_id_2)
3.4.1 Establishing Access to Files and Data Sets: SDstart, SDcreate, and SDselect
In the SD interface, SDstart is used to open files rather than Hopen. SDstart takes two arguments, filename and access_mode, and returns the SD interface identifier, sd_id. Note that the SD interface identifier, sd_id, is not interchangeable with the file identifier, file_id, created by Hopen and used in other HDF APIs.filename is the name of an HDF or netCDF file.access_mode specifies the type of access required for operations on the file. All the valid values for access_mode are listed in Table 3B. If the file does not exist, specifying DFACC_READ or DFACC_WRITE will cause SDstart to return a FAIL (or -1) . Specifying DFACC_CREATE creates a new file with read and write access. If DFACC_CREATE is specified and the file already exists, the contents of this file will be replaced.
TABLE 3B - File Access Code Flags
|
|
|
|
|---|---|---|
|
Read only access
| |
|
Read and write access
| |
|
Create with read and write access
|
Although it is possible to open a file more than once, it is recommended that the appropriate access mode be specified and SDstart called only once per file. Repeatedly calling SDstart on the same file and with different access modes may cause unexpected results.
SDstart returns an SD identifier or a value of
FAIL (or -1). The parameters of SDstart are defined in Table 3C on page 27.
SDcreate defines a new SDS using the arguments
sd_id, sds_name, data_type, rank, and dim_sizes and returns the data set identifier, sds_id.sds_name is a character string containing the name to be assigned to the SDS. The SD interface will generate a default name, "Data Set", for the SDS, if one is not provided, i.e., when the parameter sds_name is set to NULL in C, or an empty string in FORTRAN-77. The maximum length of an SDS name is 64 characters and, if sds_name contains more than 64 characters, the name will be truncated before being assigned.data_type is a defined name, prefaced by DFNT, and specifies the type of the data to be stored in the data set. The header file "hntdefs.h" contains the definitions of all valid data types, which are described in Chapter 2, HDF Fundamentals, and listed in Table 2F on page 14.
The parameter
rank is a positive integer specifying the number of dimensions of the SDS array. The maximum rank of an SDS array is defined by MAX_VAR_DIMS (or 32), which is defined in the header file "netcdf.h".dim_sizes specifies the length of the corresponding dimension of the SDS array. The size of dim_sizes must be the value of the parameter rank. To create a data set with an unlimited dimension, assign the value of SD_UNLIMITED (or 0) to dim_sizes[0] in C, and to dim_sizes(rank) in FORTRAN-77.sd_id and sds_index and returns the SDS identifier sds_id. The argument sd_id is the SD interface identifier returned by SDstart, and sds_index is the position of the data set in the file. The argument sds_index is zero-based, meaning that the index of first SDS in the file is 0.FAIL (or -1). The parameters of SDstart, SDcreate, and SDselect are further described in Table 3C.
3.4.2 Terminating Access to Files and Data Sets: SDendaccess and SDend
SDendaccess terminates access to the data set and disposes of the data set identifier sds_id. The calling program must make one SDendaccess call for every SDselect or SDcreate call made during its execution. Failing to call SDendaccess for each call to SDselect or SDcreate may result in a loss of data. sd_id. The calling program must make one SDend call for every SDstart call made during its execution. Failing to call SDend for each SDstart may result in a loss of data. SUCCEED (or 0) or FAIL (or -1). The parameters of SDendaccess and SDend are further described in Table 3C.
TABLE 3C - SDstart, SDcreate, SDselect, SDendaccess, and SDend Parameter Lists
Note that the Fortran program uses a transformed array to reflect the difference between C and Fortran internal data storages. When the actual data is written to the data set, SDS.hdf will contain the same data regardless of the language being used.
C version