binary_streams(n) 1.0 "flibs"

NAME

binary_streams - Implement binary streams

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    DATA TYPES AND ROUTINES
    IMPLEMENTATION NOTES
    COPYRIGHT

SYNOPSIS

use binary_streams

type(BINARY_STREAM)

call binstream_open( stream, lun, filename, error )

call binstream_close( stream )

call binstream_seek( stream, start, offset )

pos = binstream_tell( stream )

call binstream_read( stream, var, error )

call binstream_write( stream, var, error )

DESCRIPTION

The binary_streams module defines a set of subroutines and functions that allows you to read a file as if it were a "stream" of bytes, rather than, as is more usual a set of records.

The module uses direct-access file I/O but hides the fact that you read from individual records. By providing two routines to query and set the position of the next read/write action and by automatically positioning a "file pointer" otherwise, the module offers the benefits of both direct-access files and sequential files.

Note: In Fortran 2003, the notion of "streams" is formalised. This module will be superfluous with compilers supporting Fortran 2003. Also there are a number of issues that may or may not come into play on a particular system - see the section on IMPLEMENTATION NOTES.

DATA TYPES AND ROUTINES

The module defines a single data type, BINARY_STREAM, and several functions and subroutines:

use binary_streams

The name of the module

type(BINARY_STREAM)

Files are opened and the necessary data are kept in variables of this type.

call binstream_open( stream, lun, filename, error )

Open the file "filename" using the LU-number "lun". If some error occurs, the argument "error" is set to true.

type(binary_stream) stream: The variable by which to reference the file
integer, intent(in) lun: The LU-number to connect the file to
character(len=*), intent(in) filename: The name of the file to open
logical, intent(out) error: Argument indicating whether opening the file was successful or not. Note that the file is opened with read/write access (though not explicitly) and that it is opened in such a way that the record length is 4 bytes. If this is not possible (for any number of reasons), an error is returned.

call binstream_close( stream )

Close the file that was opened as a stream.

type(binary_stream) stream: The variable by which to reference the file

call binstream_seek( stream, start, offset )

Set the position in the file (either from the start or from the current position).

type(binary_stream) stream: The variable by which to reference the file
logical, intent(in) start: If true, the offset is from the start of the file. Otherwise it is an offset from the current position.
integer, intent(in) offset: The number of bytes to skip from the given position. Zero means either the start of the file or the same position.

pos = binstream_tell( stream )

Return the current position in the file (in bytes, the first byte is taken as 0).

type(binary_stream) stream: The variable by which to reference the file

call binstream_read( stream, var, error )

Read a variable "var" from the current position in the file.

type(binary_stream) stream: The variable by which to reference the file
(...), intent(out) var: The variable to be read. It can be either a character string, a (default) integer, a (default) real, a (default) logical or a double-precision real. Also one- and two-dimensional arrays of these types are supported.

call binstream_write( stream, var, error )

Write a variable "var" at the current position in the file.

type(binary_stream) stream: The variable by which to reference the file
(...), intent(in) var: The variable to be written. It can be either a character string, a (default) integer, a (default) real, a (default) logical or a double-precision real. Also one- and two-dimensional arrays of these types are supported.

IMPLEMENTATION NOTES

The module makes a number of assumptions:

Any file can be opened as a direct-acess file with any record length
To avoid complicated code the files are opened with records of 4 bytes long (ordinary the record length is 4 or 1 - the length unit is system-dependent!). This means that systems where the unit is not 1 or 4 bytes are not supported - this could include 64-bits systems.
The end of a file may not be accurately detected. This is due to the behaviour of direct-access files: the last record may not be complete, if the file size is a multiple of 4 bytes.
A default integer is assumed to be 4 bytes, as is a default real and a default logical. A double precision real is assumed to be 8 bytes long. There is NO provision for situations where this is not true.