To read the first file label in a file, the calling program must contain the following function calls:
C: isfirst = 1;
label_length = DFANgetfidlen(file_id, isfirst);
label_buffer = HDgetspace(label_length);
fid_len = DFANgetfid(file_id, label_buffer, label_length, isfirst);
FORTRAN: isfirst = 1
label_length = dagfidl(file_id, isfirst)
fid_len = dagfid(file_id, label_buffer, label_length, isfirst)
DFANgetfidlen has two parameters: file_id and isfirst. The isfirst parameter specifies whether the first or subsequent file annotations are to be read. To read the first file label length, isfirst should be set to the value 1; to sequentially step through all the remaining file labels assigned to a file isfirst should be set to 0.file_id, label_buffer, label_length, and isfirst. The label_buffer parameter is a pointer to a buffer for the label text. The label_length parameter is the length of the buffer in memory, which can be shorter than the full length of the label in the file. If the label_length is not large enough, the label is truncated to label_length - 1 characters in the buffer label_buffer. The isfirst parameter is used to determine whether to read the first or subsequent file annotations. To read the first file label, isfirst should be set to 1; to sequentially step through all the remaining file labels assigned to a file, isfirst should be set to 0.
The parameters of DFANgetfidlen and DFANgetfid are described in Table 11E.
11.5.2 Reading a File Description: DFANgetfdslen and DFANgetfds
The DFAN programming model for reading a file description is as follows:
To read the first file description in a file, the calling program must contain the following calls:
C: isfirst = 1;
desc_length = DFANgetfdslen(file_id, isfirst);
desc_buffer = HDgetspace(desc_length);
fds_len = DFANgetfds(file_id, desc_buf, desc_length, isfirst);
FORTRAN: isfirst = 1
desc_length = dagfdsl(file_id, isfirst)
fds_len = dagfds(file_id, desc_buf, desc_length, isfirst)
DFANgetfdslen has two parameters: file_id and isfirst. The isfirst parameter specifies whether the first or subsequent file annotations are to be read. To read the first file description length, isfirst should be set to the value 1; to sequentially step through all the remaining file descriptions assigned to a file, isfirst should be set to 0.file_id, desc_buf, desc_length, and isfirst. The desc_buffer parameter is a pointer to a buffer for the description text. The desc_length parameter is the length of the buffer in memory, which can be shorter than the full length of the description in the file. If desc_length is not large enough, the description is truncated to desc_length characters in the buffer desc_buf. The isfirst parameter specifies whether the first or subsequent file annotations are to be read. To read the first file description, isfirst should be set to the value 1; to sequentially step through all the remaining file descriptions assigned to a file, isfirst should be set to 0. TABLE 11E - DFANgetfidlen, DFANgetfid, DFANgetfdslen, and DFANgetfds Parameter List
C version
11.5.3 Reading an Object Label: DFANgetlablen and DFANgetlabel
The DFAN programming model for reading a data object label is as follows:
To read the first object label in a file, the calling program must contain the following routines:
C: label_length = DFANgetlablen(filename, tag, ref);
label_buf = HDgetspace(label_length);
status = DFANgetlabel(filename, tag, ref, label_buf, label_length);
FORTRAN: label_length = daglabl(filename, tag, ref)
status = daglab(filename, tag, ref, label_buf, label_length)
DFANgetlablen returns the length of the label assigned to the object identified by the given tag/reference number pair. DFANgetlabel must be called between calls to DFANgetlablen. DFANgetlabel is the routine that actually returns the label and prepares the API to read the next label.filename, tag, ref, label_buf, and label_length. The label_buf parameter is a pointer to a buffer that stores the label text. The label_length parameter is the length of the buffer in memory. label_length can be shorter than the full length of the label in the file, but if so, the label is truncated to label_length characters in the buffer label_buf. The length of label_buf must be at least one greater than the anticipated length of the label to account for the null termination appended to the label text. 11.5.4 Reading an Object Description: DFANgetdesclen and DFANgetdesc
The DFAN programming model for reading a data object description is as follows:
To read the first object description in a file, the calling program must contain the following routines:
C: desc_length = DFANgetdesclen(filename, tag, ref);
desc_buf = HDgetspace(desc_length);
status = DFANgetdesc(filename, tag, ref, desc_buf, desc_length);
FORTRAN: label_length = dagdlen(filename, tag, ref)
status = dagdesc(filename, tag, ref, desc_buf, desc_length)
DFANgetdesclen returns the length of the description assigned to the object identified by the specified tag/reference number pair. DFANgetdesc must be called between calls to DFANgetdesclen to reset the current object description to the next in the file.filename, tag, ref, desc_buf, and desc_length. The desc_buf parameter is a pointer to the buffer that stores the description text. The desc_length parameter is the length of the buffer in memory, which can be shorter than the full length of the description in the file. If the desc_length is not large enough, the description is truncated to desc_length characters in the buffer desc_buf.TABLE 11F - DFANgetlablen, DFANgetlabel, DFANgetdesc and DFANgetdesclen Parameter List
C version
No FORTRAN-77 version for this example