ADF User's Guide - ADF Library Of Subroutines

(CGNS Documentation Home Page) (Steering Committee Charter) (Overview and Entry-Level Document) (A User's Guide to CGNS) (Mid-Level Library) (Standard Interface Data Structures) (SIDS File Mapping Manual) (CGIO Manual) (Parallel CGNS User's Guide) (ADF Implementation) (HDF5 Implementation) (Python Implementation) (CGNS Tools and Utilities)

(Introduction) (The ADF Software Library) (Glossary of Terms) (History of ADF Version Releases) (File System Architectures) (File Version Control Numbering) (Design Considerations) (Conventions and Implementations) (Error Messages) (Default Values and Limits) (Database-Level Routines) (Data Structure and Management Routines) (Data Query Routines) (Data I/O Routines) (Miscellaneous Routines) (Sample Fortran Program) (Sample C Program)

Database-Level Routines

ADF_Database_Open - Open a database
ADF_Database_Close - Close an opened database
ADF_Database_Delete - Delete an existing database
ADF_Database_Get_Format - Get the data format in an existing database
ADF_Database_Set_Format - Set the data format in an existing database

Open a Database

`ADF_Database_Open (filename,status,format,root_ID,error_return)`
Language	C	Fortran
Routine Name	`ADF_Database_Open`	`ADFDOPN`
Input	`const char filename` `const char status` `const char *format`	`character() filename` `character() status` `character() format`
Output	`double root_ID` `int error_return`	`real*8 root_ID` `integer error_return`

filename A legal file name that may include a relative or absolute path where it is directly usable by the C fopen() system routine (no environment expansion is done).

status

Similar to a Fortran OPEN() status. Input is required: there is no default. Allowable values are:

	`READ_ONLY`		File must exist; writing is not allowed.
	`OLD`		File must exist; reading and writing are allowed.
	`NEW`		File must not exist.
	`SCRATCH`		Temporary new file is created with a system name, and `filename` is ignored. The temporary file is deleted when the program exits or the file is closed.
	`UNKNOWN`		`OLD` if file exists or else `NEW` is used.

format

Specifies the numeric format for the file. This field is used only when a file is created and is ignored when status = OLD. Allowable values are:

	`NATIVE`		Use the native numeric format of the computer that creates the file. This is the default for a new file if the input string for format is null. Note that if the native numeric format is not one of the supported formats listed here, then the file cannot be read on machines using any other format.
	`IEEE_BIG`		Use the IEEE big endian format.
	`IEEE_LITTLE`		Use the IEEE little endian format.
	`CRAY`		Use the native CRAY format.

root_ID The root identity of the database.

error_return Error return code.

This routine, ADF_Database_Open, opens a new or existing database. If links to other ADF files exist in the current file, they will be opened only as required. Using this routine is similar to opening a file in Fortran with the corresponding clarifiers, such as whether it is READ_ONLY, OLD, NEW, or named as SCRATCH file.

The format of the file, which is ignored when the status of the file is OLD, is used when the file is first created. Big endian is a binary format in which the most significant byte or bit comes first, whereas in little endian, the most significant byte or bit comes last. To specify the format more explicitly, you can use the following formats:

   IEEE_BIG_32
   IEEE_BIG_64
   IEEE_LITTLE_32
   IEEE_LITTLE_64

for IEEE big or little endian formats.

Example

This example opens a new database using the native format of the host computer. Note that the default format is specified by using the empty string. In the C programming language, a null string could have been used.

   PROGRAM TEST
      CHARACTER*(80) MSG
      REAL*8 RID
      INTEGER IERR
      CALL ADFDOPN('db.adf','NEW',' ',RID,IERR)
      IF (IERR .GT. 0) THEN
         CALL ADFERR(IERR,MSG)
         PRINT *,MSG
         STOP
      ENDIF
      STOP
      END

Close a Database

`ADF_Database_Close (root_ID,error_return)`
Language	C	Fortran
Routine Name	`ADF_Database_Close`	`ADFDCLO`
Input	`const double *root_ID`	`real*8 root_ID`
Output	`int *error_return`	`integer error_return`

	`root_ID`		The root identification of the database. This can be a valid node ID for this database.

	`error_return`		Error return code.

This routine, ADF_Database_Close, closes an existing database, as well as the other ADF files that may be attached through links. For example, if there is another ADF file that is opened and linked to this database, only the file stream associated with this database will be closed. This routine is similar to the close of a file in Fortran.

Example

This example closes a database. Note that while the root ID is used in the call to ADFDCLO, any valid node ID for this file will work. Also, in general, it is not necessary to close open ADF files when the program exits normally. The standard shutdown procedures will flush all buffers and bring files up to date. The primary use of ADFDCLO is to clean up file tables or to release unused files.

   PROGRAM TEST
      CHARACTER*(80) MSG
      REAL*8 RID
      INTEGER IERR
      CALL ADFDOPN('db.adf','NEW',' ',RID,IERR)
      IF (IERR .GT. 0) THEN
         CALL ADFERR(IERR,MSG)
         PRINT *,MSG
         STOP
      ENDIF
      .
      ...do useful stuff (hopefully)
      .
      CALL ADFDCLO(RID,IERR)
      STOP
      END

Delete a File

`ADF_Database_Delete (filename,error_return)`
Language	C	Fortran
Routine Name	`ADF_Database_Delete`	`ADFDDEL`
Input	`const char *filename`	`character() filename`
Output	`int *error_return`	`integer error_return`

	`filename`		A legal file name of an existing ADF database. The filename may include a relative or absolute path where it is directly usable by the C `fopen()` system routine (no environment expansion is done).

	`error_return`		Error return code.

This routine, ADF_Database_Delete, deletes an existing database file. It does not delete links referenced in the database. This routine is similar to the deletion of a file in Fortran.

Note: This routine will be implemented in a future release.

Get the Data Format

`ADF_Database_Get_Format (root_ID,format,error_return)`
Language	C	Fortran
Routine Name	`ADF_Database_Get_Format`	`ADFDGF`
Input	`const double *root_ID`	`real*8 root_ID`
Output	`char format` `int error_return`	`character() format` `integer error_return`

	`root_ID`		Any valid node ID for the given ADF file.

	`format`		The format for the file.

	`error_return`		Error return code.

This routine, ADF_Database_Get_Format, gets the data format for an existing database.

Example

This example opens an existing ADF database, creates a new node, and then uses the node ID for the new node to ask what the file type is. Note that the file format is ignored because the database already exists.

   PROGRAM TEST
      CHARACTER*(80) MSG
      CHARACTER*(32) FORM
      REAL*8 RID,CID
      INTEGER IERR
      CALL ADFDOPN('db.adf','OLD',' ',RID,IERR)
      IF (IERR .GT. 0) THEN
         CALL ADFERR(IERR,MSG)
         PRINT *,MSG
         STOP
      ENDIF
      CALL ADFCRE(RID,'junk_node',CID,IERR)
      CALL ADFDGF(CID,FORM,IERR)
      PRINT *,'FILE FORMAT = ',FORM
      STOP
      END

Set the Data Format

`ADF_Database_Set_Format (root_ID,format,error_return)`
Language	C	Fortran
Routine Name	`ADF_Database_Set_Format`	`ADFDSF`
Input	`const double *root_ID`	`real*8 root_ID`
Output	`const char format` `int error_return`	`character() format` `integer error_return`

	`root_ID`		The root identity of the database.

	`format`		The numeric format for the file.

	`error_return`		Error return code.

This routine, ADF_Database_Set_Format, sets the data format in an existing database.

Note: Use with extreme caution. This routine is needed only for the data conversion utilities and not intended for the general user.