BINARY_FILE_UTILITY.F90 Subprograms

Last modified: Fri Feb 11 14:23:42 2005.


List of Subprograms


Subprogram Descriptions

OPEN_BINARY_FILE

[List of Subprograms]
 NAME:
       Open_Binary_File

 PURPOSE:
       Function to open the unformatted, sequential access Binary files

 CALLING SEQUENCE:
       Error_Status = Open_Binary_File( Filename,                 &  ! Input
                                        FileID,                   &  ! Output
                                        For_Output = For_Output,  &  ! Optional input
                                        No_Check   = No_Check,    &  ! Optional input
                                        Message_Log = Message_Log )  ! Error messaging

 INPUT ARGUMENTS:
       Filename:         Name of the Binary file to open.
                         UNITS:      N/A
                         TYPE:       CHARACTER(*)
                         DIMENSION:  Scalar
                         ATTRIBUTES: INTENT( IN )

 OPTIONAL INPUT ARGUMENTS:
       For_Output:       Set this optional argument to open a new file for
                         writing. Default action is to open an existing file
                         for read access. Note, if the file already exists and
                         it is opened with this keyword set, the file is
                         overwritten.
                         If == 0, existing file is opened for READ access (DEFAULT)
                                  ACTION='READ', STATUS='OLD'
                            == 1, new file is opened for WRITE access.
                                  ACTION='WRITE', STATUS='REPLACE'
                         UNITS:      N/A
                         TYPE:       INTEGER
                         DIMENSION:  Scalar
                         ATTRIBUTES: INTENT( IN ), OPTIONAL

       No_Check:         Set this optional argument to suppress the byte-order
                         check made on an existing file by NOT reading the file
                         header magic number.  Default action is to check the
                         file. This argument is ignored if the FOR_OUTPUT 
                         optional argument is set.
                         If == 0, existing file magic number is read and the
                                  byte order is checked (DEFAULT)
                            == 1, magic number is *NOT* read from file and
                                  checked for validity.
                         UNITS:      N/A
                         TYPE:       INTEGER
                         DIMENSION:  Scalar
                         ATTRIBUTES: INTENT( IN ), OPTIONAL

       Message_Log:      Character string specifying a filename in which any
                         Messages will be logged. If not specified, or if an
                         error occurs opening the log file, the default action
                         is to output Messages to the screen.
                         UNITS:      N/A
                         TYPE:       CHARACTER(*)
                         DIMENSION:  Scalar
                         ATTRIBUTES: INTENT( IN ), OPTIONAL

 OUTPUT ARGUMENTS:
       FileID:           File unit number.
                         UNITS:      N/A
                         TYPE:       INTEGER
                         DIMENSION:  Scalar
                         ATTRIBUTES: INTENT( OUT )

 OPTIONAL OUTPUT ARGUMENTS:
       None.

 FUNCTION RESULT:
       Error_Status:     The return value is an integer defining the
                         error status. The error codes are defined in
                         the ERROR_HANDLER module. Values returned by
                         this function are:
                           SUCCESS == file open was successful
                           FAILURE == - error occurred during file open,
                                      - error occurred during file check.
                         UNITS:      N/A
                         TYPE:       INTEGER
                         DIMENSION:  Scalar

 CALLS:
      Check_Binary_File:       Function to determine if the unformatted
                               Binary file is in the correct byte order.

      File_Exists:             Function to determine if a named file exists.
                               SOURCE: File_Utility module

      Get_Lun:                 Function to return a free logical unit number
                               for file access.
                               SOURCE: File_Utility module

      Display_Message:         Subroutine to output Messages
                               SOURCE: Error_Handler module


 SIDE EFFECTS:
       None.

 RESTRICTIONS:
       File open ACCESS and FORM specifiers are set to 'SEQUENTIAL' and
       'UNFORMATTED' respectively.

 CREATION HISTORY:
       Written by:     Paul van Delst, CIMSS/SSEC 12-July-2000
                       paul.vandelst@ssec.wisc.edu

(See Binary_File_Utility.f90)