This section provides a summary of the design considerations that were used in the construction of the ADF software library.
Every ADF file has a header section that contains information about the file itself. The following information from this header is available to the user:
To optimize the performance of ADF, the following techniques have been incorporated into the ADF software to enhance performance of the file:
Allow data space to grow by linking data chunks. It is possible to increase the last dimension; doing so will extend the data. However, internal dimensional changes will corrupt the existing data.
The pointer table for child nodes will also contain the child node names.
To address code portability and future needs, the following design decisions were made:
Error checking has been implemented for the ADF file and is summarized here. Each item in the ADF file will have item-specific boundary tags surrounding it to provide file-based corruption checking. For variable-sized items, the associated boundary tags will include file-based size information. Information will be written to the disk in a sequence that will not allow corrupt files. For example, when adding a new child node, the complete child information will be written before the parent's child-table is updated. An ADF-core subroutine for downloading data to disk will be provided.
The ADF library of source code will incorporate the use of UNIX "what" strings for the ADF version number and also RCS versioning information in the source code and in the object code. The source code is written in portable ANSI C, using POSIX-defined system calls.
The following information is contained in an ADF node header:
|if num_data_chunks||= 1,||then a file pointer to data|
|> 1,||then a file pointer to a table of num_data_chunks file pointers and associated data sizes.|
Fortran character arrays are different from any other array type because they inherently include declared length information. Abstractly, they are a compound type: an array and an integer. The ANSI standards do not specify the implementation mechanism for handling this data type and so it is left to the vendor. As one might expect, vendors have devised different policies. This is particularly evident in how argument lists are created and used. The matter is further complicated when writing functions in other languages that are to be called from Fortran.
To keep the interfaces simple and to keep the Fortran and C data I/O calls similar (as opposed to having separate data I/O functions for character data), ADF suggests abiding by the following rules (these are required for Cray T90-mode users):
Note to Cray T90-mode users: The above rules must be followed. In addition, the given node must be available and have its data type correctly defined. Error handling is not possible otherwise, and ADF will abort or fail regardless of how the error state flag is set.
For portability reasons, it is suggested that the use of the I8 data type be restricted to a 64-bit environment.
For the transportability reasons discussed below, use of compound data types is not recommended.
When using compound data types (e.g., with structures in C), it is important to be aware of data alignment issues. If one is not careful, the actual size of the structure in memory may be larger than the sum of the individual members. The total size depends on the order and word boundary alignment requirements of the specific data types. This is platform and compiler dependent and not handled by ADF. In order to provide the greatest portability (at least up to 64-bit environments), it is recommended that
So a 4-byte data type (e.g., I4) needs "padding" (e.g., I4) if it is to be followed by an 8-byte data type. And assuming a word size of 4 bytes, all C1-data-type elements need dimension values of multiples of 4 bytes (e.g., C1, C1, etc.). To be even more careful, size everything in multiples of 8 bytes, for example, "C1, I4, C1, R4, R8, I8".
For a given architecture and compiler, and taking into consideration the restrictions given above, compound data types should work. It is more portable and highly recommended that users write out the individual components of a structure into separate nodes. It would probably be best to copy the individual components of a list of structures into an appropriate array type and write the temporary array out using the write-all or write-strided routines.