Subroutine Descriptions

• Introduction
• Initialization Functions
  • CFINIT - Initialize the Common File Library
• File Oriented Functions
  • CFSTFP - Set a File Parameter
  • CFGTFP - Get a File Parameter
  • CFRECL - Set Record Length to be Used Before Calling CFOPEN
  • CFOPEN - Open a Common File
  • CFCLOS - Close a Common File
• Node Oriented Functions
  • CFCNOD - Create a Node
  • CFCLNK - Create a Node Link
  • CFNDEL - Delete a Node
  • CFNMOV - Move a Node
  • CFNREN - Rename a Node
  • CFSNOD - Establish Access to a Node
  • CFRNOD - Read Node Header Information
  • CFWNOD - Write Node Header Information
  • CFNINF - Get Information About a Node
• Data Read and Write Functions
  • CFRVI - Read Integer Variable
  • CFRVR - Read Real Variable
  • CFRVD - Read Double Precision Variable
  • CFRVRX - Read Real Variable with Conversion
  • CFRVDX - Read Double Precision Variable with Conversion
  • CFRVC - Read Character Variable
  • CFWVI - Write Integer Variable
  • CFWVR - Write Real Variable
  • CFWVD - Write Double Precision Variable
  • CFWVC - Write Character Variable
  • CFVDEL - Delete a Variable
• Miscellaneous Functions
  • CFERMS - Retrieve Error Message Text for Specified Error Number
  • CFRREF - Read Reference and Scaling Data
  • CFWREF - Write Reference and Scaling Data
  • CFVINF - Get Information About a Variable
  • CFVLST - Get List of Variables
  • CFNLST - Get List of Subnodes
  • CFSLST - Get List of Reference and Scaling Data
  • CFUNIT - Common File Get Current/New UNITs
  • CFOREC - Common File Optimal RECord length calculation
  • CFVSIZ - Common File Variable SIZe information
  • CFGTRT - Get File Root State from Any File State
  • CFHOST - Common File get HOST type

Introduction

The following sections describe in detail the subroutine calls that define the common file library. All of the subroutine calls (with the exception of CFERMS and CFINIT) have the following format using the Fortran interface:

   CALL CFxxxx (STATUS, STATE, ...)

By default, all of the common file routines abort the program if an error is detected except CFINIT, CFERMS, CFVINF, and CFNINF. The program may prevent this action by calling CFSTFP to set the ABORT flag to zero. This will cause the library routines to return a non-zero status value if an error is detected.

The common file library now supports a C interface. The C interface has the same arguments, with the same meanings, as the Fortran interface, and the C routine names are the same as the Fortran routine names with the leading "CF" replaced by "CF_C". The type definitions and defines for the C interface are in the cfbind_c_2_f.h include file.

The following sections show the calling statement for each subroutine, with the Fortran version listed first, followed by the C version in italics. The arguments are then defined, and classified as Input, Output, or Temporary. In a few cases, an argument has two definitions, one for input and another for output. The argument names include the data type (i.e., integer, character, etc.), and again the Fortran name is listed first, followed by the C name in italics.

Initialization Functions

• CFINIT - Initialize the Common File Library

CFINIT initializes various internal tables used by the common file library routines. It must be called at least once in a program and must be called before any other common file library routine. Multiple calls to this subroutine will have no effect on the common file tables or operation.

File Oriented Functions

• CFSTFP - Set a File Parameter
• CFGTFP - Get a File Parameter
• CFRECL - Set Record Length to be Used Before Calling CFOPEN
• CFOPEN - Open a Common File
• CFCLOS - Close a Common File

CFSTFP is used to set the file parameters for use by a subsequent CFOPEN request. The following parameters can be set:

The values of RECORD_LENGTH, MAX_NODES, MAX_VARIABLES, MAX_INTEGERS, MAX_REALS, and MAX_CHARACTERS must be a multiple of two to allow for portability between machines and are subject to limitations described in the section "Default Library Values and Limits." For version 3 files the unit number is not used since the open is done in C.

If a file is opened and a specific parameter has not been set by CFSTFP then a default value will be assigned for the parameter. The default values are also defined in the section "Default Library Values and Limits."

Only the ABORT, FILE_CPU, and FILE_OS parameters may be set after the file is opened. For version 3 files the MAX_NODES and MAX_VARIABLES parameters may be changed after open to redefine the maximum that is allowed to be created in the file.

CFGTFP retrieves the value of a file parameter. If called prior to opening a file then the value returned will be either the default value for the parameter or the value set by CFSTFP. If called after the file is opened then the value will be that contained in the file header.

The parameter name may be any one of the following names:

   UNIT
   OPEN
   HOST_CPU
   HOST_OS
   ABORT
   FILE_CPU
   FILE_OS
   RECORD_LENGTH
   MAX_NODES
   MAX_VARIABLES
   MAX_INTEGERS
   MAX_REALS
   MAX_CHARACTERS
   LAST_RECORD
   VERSION

CFRECL sets the record length to be used when creating a common file with a subsequent CFOPEN request. The routine uses MAXPTS and PRECSN to calculate a record length acceptable to the operating system. This works fine for simple one size variable files but not very well for files containing variables of many different sizes. Thus the CFOREC routine should be used to calculate record lengths for an arbitrary sized file. For version 3 files there is no record length although the record length parameter stored in the file is still used to determine the size of the conversion buffers used in the CFRVxx subroutines.

For example, assume you are going to be writing single precision records dimensioned IDIM × JDIM × KDIM. The following call will set the record length:

   RSTATE = 0
   CALL CFRECL (STATUS, RSTATE, IDIM*JDIM*KDIM, 1)

CFOPEN allocates internal tables for the common file library and opens the file for processing.

A CFOPEN call must be preceded, at minimum, by a call to CFSTFP to set the unit number. For version 3 files the unit number is not used, thus the CFSTFP call is unnecessary in the following example of a minimal opening sequence for a common file:

   INTEGER STATE, STATUS
   STATE = 0
   CALL CFINIT ()
   CALL CFSTFP (STATUS, STATE, 'UNIT', 11)
   CALL CFOPEN (STATUS, STATE, 'TEST.CGD', 'NEW')

When CFOPEN is called with a mode of NEW or SCRATCH, the attributes of the file are set from either default values or from the values set by calls to CFSTFP. The default values are listed in the section "Default Library Values and Limits."

When CFOPEN is called with a mode of OLD, the default values or the values specified by CFSTFP are used to verify that the calling program can accomodate the file being opened and are subsequently overwritten by the actual values from the file. Thus if the program let everything default and tried to open a file with MAX_INTEGERS set to 128, the request to open the file would be rejected.

The only routines that can be called prior to CFOPEN for a given file are CFSTFP, CFRECL, CFOREC, CFUNIT, and CFERMS.

CFCLOS closes a common file. Any internal table space within the common file library is released and made available for use for other files.

Node Oriented Functions

• CFCNOD - Create a Node
• CFCLNK - Create a Node Link
• CFNDEL - Delete a Node
• CFNMOV - Move a Node
• CFNREN - Rename a Node
• CFSNOD - Establish Access to a Node
• CFRNOD - Read Node Header Information
• CFWNOD - Write Node Header Information
• CFNINF - Get Information About a Node

CFCNOD is used to create a subnode under another node. The following code fragment creates a subnode under the root node using the name stored in ZNAME (RSTATE is the root state returned by CFOPEN):

   CHARACTER*32 ZNAME
   INTEGER ZONE,ZSTATE,RSTATE
   ZNAME = subnode_name
   CALL CFCNOD (STATUS, RSTATE, ZNAME, ZSTATE)

Once the request has been successfully completed, the program may read and write the node header information and variables of the subnode by using the the new state (ZSTATE) as the state for subsequent calls to CFR/WNOD and CFR/WVxNOD.

The integer and real elements in the node header will be initialized to zero and the character elements will be initialized to blank.

CFCLNK is used to create a subnode which points to another node. The node may be in the current file or another file. The FILNAM can contain a path, but it is not recommended since the user does not know what the path is, and so does not know where the file should be located so the library can open it. The following code fragment creates a link under the root node called ZNAME which points to node "Zone   1" in file ZONE1.cgd (RSTATE is the root state returned by CFOPEN):

   CHARACTER*32 ZNAME,LNKNAM,FILNAM
   INTEGER ZONE,ZSTATE,RSTATE
   ZNAME = 'Node 1'
   FILNAM = 'ZONE1.cgd'
   LNKNAM = '/ZONE   1'
   CALL CFCLNK (STATUS, RSTATE, ZNAME, FILNAM, LNKNAM, ZSTATE)

CFNDEL is used to delete a subnode under another node. The following code fragment deletes a subnode under the root node using the name stored in ZNAME (RSTATE is the root state returned by CFOPEN):

   CHARACTER*32 ZNAME
   INTEGER ZONE,RSTATE
   ZNAME = subnode_name
   CALL CFNDEL (STATUS, RSTATE, ZNAME)

Once the request has been successfully completed, all data for the node and all subnodes under that node will be inaccessible. For version 1 and 2 files the data is not removed and the space becomes dead space in the file. For version 3 files the ADF core puts the space into a free chunk table to be reallocated to a new node or variable. The actual size of the file does not change.

CFNMOV is used to move a subnode from one node to another in the same file. All subnodes of the moved node move with it. No data in the file is actually moved; only the node pointers are moved.

CFNREN is used to rename a subnode of a node. The new name must be unique under the parent node.

CFSNOD is used access a subnode under another node. The following code fragment accesses a subnode under the root node using the name stored in ZNAME (RSTATE is the root state returned by CFOPEN):

   CHARACTER*32 ZNAME
   INTEGER ZONE,ZSTATE,RSTATE
   ZNAME = subnode_name
   CALL CFSNOD (STATUS, RSTATE, ZNAME, ZSTATE)

Once the request has been successfully completed, the program may read and write the node header information and variables of the subnode by using the the new state (ZSTATE) as the state for subsequent calls to CFR/WNOD and CFR/WVxNOD.

CFRNOD reads the application dependent node header information for the specified node.

CFWNOD writes the application dependent node header information for the specified node.

CFNINF returns information about a node. Note that if the requested node is not present, CFNINF will not abort even if the ABORT flag is set.

Data Read and Write Functions

• CFRVI - Read Integer Variable
• CFRVR - Read Real Variable
• CFRVD - Read Double Precision Variable
• CFRVRX - Read Real Variable with Conversion
• CFRVDX - Read Double Precision Variable with Conversion
• CFRVC - Read Character Variable
• CFWVI - Write Integer Variable
• CFWVR - Write Real Variable
• CFWVD - Write Double Precision Variable
• CFWVC - Write Character Variable
• CFVDEL - Delete a Variable

CFRVI reads an integer variable located under the specified node.

CFRVR reads a real variable located under the specified node.

CFRVD reads a double precision precision variable located under the specified node.

CFRVRX reads either a real or double precision value located under the specified node into a single precision array. If the requested variable is a single precision variable then the call is equivalent to a call to CFRVR. If the requested variable is double precision then the data is read in and converted to single precision in the output array.

CFRVDX reads either a real or double precision value located under the specified node into a double precision array. If the requested variable is a double precision variable then the call is equivalent to a call to CFRVD. If the requested variable is single precision then the data is read in and converted to double precision in the output array.

CFRVC reads a character variable located under the specified node. This function is only available in version 3 or greater.

CFWVI writes an integer variable under the specified node. The variable will be created if it does not already exist. If the variable already exists, the new contents will replace the old contents. The old length and the new length do not have to be equal.

CFWVR writes a real variable under the specified node. The variable will be created if it does not already exist. If the variable already exists, the new contents will replace the old contents. The old length and new length do not have to be equal.

If the variable already exists and is double precision, the data will be written as double precision. The input data will be unaffected.

CFWVD writes a double precision variable under the specified node. The variable will be created if it does not already exist. If the variable already exists, the new contents will replace the old contents. The old length and new length do not have to be equal.

If the variable exists and is single precision, the data will be written as single precision. The input data will be unaffected.

CFWVC writes a character variable located under the specified node. This function is only available in version 3 or greater.

CFVDEL is used to delete a variable under a node. Once the request has been successfully completed, all data for the variable will be inaccessible. For version 1 and 2 files the data is not removed and the space becomes dead space in the file. For version 3 files the ADF core puts the space into a free chunk table to be reallocated to a new node or variable. The actual size of the file does not change.

Miscellaneous Functions

• CFERMS - Retrieve Error Message Text for Specified Error Number
• CFRREF - Read Reference and Scaling Data
• CFWREF - Write Reference and Scaling Data
• CFVINF - Get Information About a Variable
• CFVLST - Get List of Variables
• CFNLST - Get List of Subnodes
• CFSLST - Get List of Reference and Scaling Data
• CFUNIT - Common File Get Current/New UNITs
• CFOREC - Common File Optimal RECord length calculation
• CFVSIZ - Common File Variable SIZe information
• CFGTRT - Get File Root State from Any File State
• CFHOST - Common File get HOST type

CFERMS returns a textual error message corresponding to an error number returned by a call to a common file library routine. See the section "Status Codes" for the error numbers and their associated text. For version 3 files the ADF core errors are returned as a negative number to distinguish them from the common file error numbers. The ADF error message routine is automatically called to return the proper error string.

CFRREF reads the reference and scaling data for the specified variable. If no reference and scaling data has been written for the specified variable then the following values are returned:

   UCOFST = 0.0
   UCSCAL = 1.0
   NDOFST = 0.0
   NDSCAL = 1.0

CFWREF writes the reference and scaling data for the specified variable.

Note: To obtain conversion numbers, use the CFUNIT subroutine, or see the section "Conversion Factors."

CFVINF returns the type and length of the specified variable. Note that if the requested variable is not present, CFVINF will not abort even if the ABORT flag is set. For character variables the length returned will be the element length times the character size.

CFVLST returns the list of variables associated with the specified node.

CFNLST returns a list of subnodes of the specified node.

CFSLST returns a list of variables that have reference and scaling data.

CFUNIT returns the current system of units and the units for any CFD variable when the mode is CURRENT. When then mode is NEW, CFUNIT returns conversion data from CUNITS to DUNITS where the input CUNITS and DUNITS can be a system of units or the actual units. If actual units are used they must conform to the format used in the section "Conversion Factors." Valid systems of units are MKS = SI = METRIC, CGS, ENGLISH = BRITISH = FSS (Foot-Slug-Second), and FPP (Foot-Pound-Second). VARNAM may be any CFD variable name or a unit type. Valid unit types are LENGTH, MASS, TIME, FORCE, DENSITY, TEMPERATURE, ENERGY, ENTROPY, VELOCITY, PRESSURE, GAS CONSTANT and VISCOSITY. If VARNAM is a CFD variable and either CUNITS is blank or mode is CURRENT then the current units will be derived from the reference and scaling data. If no reference and scaling data have been stored for the variable the default will be the MKS system. For readability the following aliases have been set up for use in the CUNITS and DUNITS variables.

   m = meter = meters
   cm = centimeter = centimeters
   mm = millimeter = millimeters
   ft = feet
   in = inch = inches
   kg = kilogram = kilograms
   g = gram = grams
   slug = slugs
   lbf = lb = pounds
   K = KELVIN
   C = CENTIGRADE = CELSIUS
   R = RANKINE
   F = FAHRENHEIT
   J = N-m
   erg = dyn-cm

For consistency this subroutine should be used in all CFD applications. The following examples illustrate the use of this subroutine.

Example 1

When the variable is old and is being read into an application, the application wants the variable to be in certain units. The following reads the variable 'x' and places it in the units of inches. This example uses the fact that MSCALE and MOFF factors are stored to convert 'x' to the MKS system of units.

   CALL CFRVR  (STATUS, STATE, 'x', VARLEN, 1, X)
   CALL CFRREF (STATUS, STATE, 'x', MOFF, MSCALE, DOFF, DSCALE)
   CALL CFUNIT (STATUS, STATE, 'x', 'NEW', 'MKS', 'in', CNVOFF, CNVSCL)
   DO I = 1,VARLEN
      X(I) = ((X(I)*DSCALE + DOFF)*MSCLE + MOFF)*CNVSCL + CNVOFF
   END DO

When the variable is old and is being read into an application the units that the variable is stored in may need to be known (e.g. for display). The following writes the variable 'p' to a file and includes the units as part of the output.

       CALL CFRVR  (STATUS, STATE, 'p', VARLEN, 1, P)
       CALL CFRREF (STATUS, STATE, 'p', MOFF, MSCALE, DOFF, DSCALE)
       CALL CFUNIT (STATUS, STATE, 'p', 'CURRENT', CUNITS, DUNITS, CNVOFF, CNVSCL)
       CALL UTSLEN (DUNITS, LEN)
       WRITE (6, 210) 'I', 'J', 'K', 'PRESSURE'
       DO K = 1,KMAX
          DO J = 1,JMAX
             DO I = 1,IMAX
                P(I,J,K) = P(I,J,K)*DSCALE + DOFF 
                WRITE (6,200) I, J , K, P(I,J,K), DUNITS(1:LEN) 
             END DO
          END DO
       END DO
   200 FORMAT (3I5, F12.5, A)
   210 FORMAT (A, 5X, A, 5X, A, 7X, A)

When the variable is first being stored, four factors must be saved for the variable using the subroutine CFWREF. The dimensional factors and units are known, CFUNIT is used to get the factors to convert those units to the MKS system of units. In the following the pressure is known to be in the 'FSS' system of units.

   CALL CFUNIT (STATUS, STATE, 'p', 'NEW', 'FSS', 'MKS', MOFF,  MSCALE)
   CALL CFWREF (STATUS, STATE, 'p', MOFF, MSCALE, DOFF, DSCALE)
   CALL CFWVR  (STATUS, STATE, 'p', VARLEN, 1, P)

CFOREC calculates the optimal record length for a common file. There are five modes 'FULL', 'CGD', 'CFL', 'CGF', or 'ZDF'. Mode 'FULL' works on existing common files and uses the actual variable sizes stored in the file to calulate the optimal record length. The other modes make a guess at the optimal record length based on the zone dimensions input. The 'CGD' mode is similar to the 'CFL' mode except that it takes into account the variable sizes of boundary conditions. If you are not storing boundary conditions then the 'CFL' mode should be used. For version 3 files there is no record length although the record length parameter stored in the file is still used to determine the size of the conversion buffers used in the CFRVxx subroutines.

CFVSIZ searches the entire file and locates the largest variable of the given type. This is useful for check and/or allocating memory for reading file variables.

CFGTRT returns the root state of a common file, given any state in the file.