home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / fortran77_210 / library / docs / binaryio < prev    next >
Encoding:
Text File  |  1992-01-17  |  16.1 KB  |  370 lines
  1.  
  2.       **************************************************************
  3.       *   Fast Fortran 77 Callable Binary File Handling Routines   *
  4.       *                                                            *
  5.       *                for RISC OS and RISC iX                     *
  6.       **************************************************************
  7.       *  Version 1.0 copyright Interactive Software Services 1992  *
  8.       **************************************************************
  9.  
  10. 1. Introduction
  11.    ------------
  12.  
  13. This file documents a set of Fortran callable binary file handling routines
  14. for users of Acorn's RISC OS and RISC iX operating systems on ARM-based
  15. computers. The routines are significantly faster than conventional Fortran
  16. i/o (roughly 15 times faster under RISC OS and about 4 times faster under
  17. Unix). The RISC iX version is also compatible with f77 on Sun workstations.
  18.  
  19. The file handling subroutines described here are based on code written
  20. originally as internal routines for INTERACTER, a portable Fortran 77
  21. user-interface and graphics library from Interactive Software Services Ltd.,
  22. which runs on RISC OS, Unix, DOS, VMS and PRIMOS. These binary file handling
  23. routines are being placed in the public domain to help encourage the use of
  24. Fortran on Acorn hardware. But first, some boring but important legalities.
  25.  
  26.    THE CODE WHICH IS DESCRIBED IN THIS FILE IS HEREBY PLACED IN THE
  27.    PUBLIC DOMAIN SUBJECT TO THE FOLLOWING TERMS AND CONDITIONS :
  28.  
  29.    (1) IN NO CIRCUMSTANCES WILL INTERACTIVE SOFTWARE SERVICES LTD. BE
  30.        LIABLE FOR ANY DAMAGE OR LOSS OF PROFITS OR FOR ANY INDIRECT
  31.        OR CONSEQUENTIAL LOSS ARISING FROM THE USE OF THIS CODE
  32.    (2) DOCUMENTATION FOR ANY PROGRAM WHICH INCORPORATES THESE ROUTINES
  33.        SHOULD INCLUDE DUE ACKNOWLEDGEMENT TO INTERACTIVE SOFTWARE SERVICES
  34.        LTD. AS THE ORIGINAL AUTHORS OF THE CODE CONTAINED HEREIN
  35.    (3) THIS DOCUMENTATION FILE AND THE ASSOCIATED SOURCE CODE MAY BE
  36.        FREELY REDISTRIBUTED ON A NON-PROFIT MAKING BASIS I.E. ONLY
  37.        REASONABLE MEDIA AND HANDLING CHARGES MAY BE MADE
  38.    (4) ONLY UNALTERED VERSIONS OF THIS SOURCE CODE AND THE ASSOCIATED
  39.        DOCUMENTATION FILE MAY BE REDISTRIBUTED
  40.  
  41. 2. Files
  42.    -----
  43. Two source files are provided containing the binary file handling
  44. routines, one for RISC OS and the other for Unix (RISC iX). Where the
  45. code is distributed on a RISC OS disk the following files are supplied
  46.  
  47.    asm.binaryio   : ARM assembler source for RISC OS version
  48.                     of binary file handling routines
  49.  
  50.    c.binaryio     : C source for RISC iX version
  51.                     (can also be used on Sun workstations)
  52.  
  53.    doc.binaryio   : This file !
  54.  
  55.    aof.binaryio   : Object code for RISC OS version
  56.  
  57.  (On the PD_F77 disc, only the last two are usually supplied, in
  58. Library.Docs.Binaryio and an alf formatted version of the aof in 
  59. Library.lib.Binaryio)
  60.  
  61. 3. Overview
  62.    --------
  63. The binary file handling routines allow both character and numeric data
  64. to be randomly written to and read from binary data files. No structure
  65. is imposed on files accessed by these routines, giving the programmer
  66. complete byte-level file access. The routines bypass the standard Fortran
  67. i/o system completely giving very significant i/o performance improvements
  68. especially under RISC OS. Tests have shown a 15-fold speed increase over
  69. standard Fortran i/o under RISC OS. The improvements of 4 to 5 times under
  70. RISC iX seem modest in comparison but are still very significant. The exact
  71. speed improvements which you can expect to achieve in any particular
  72. application depend to some extent on what type of Fortran i/o they are used
  73. to replace. 
  74.  
  75. Seven routines are provided to perform open, close, read, write and seek
  76. operations :
  77.  
  78.              BFOPEN   : Opens a file for fast binary i/o
  79.              BFCLOSE  : Closes a file opened by BFOPEN
  80.              BFREAD   : Reads non-CHARACTER data from a file
  81.              BFREADC  : Reads CHARACTER data from a file
  82.              BFWRITE  : Writes non-CHARACTER data to a file
  83.              BFWRITEC : Writes CHARACTER data to a file
  84.              BFSEEK   : Moves the file pointer
  85.  
  86. The i/o model adopted is similar to that used by Unix and MeSs DOS.
  87. BFOPEN is called to open a file in read, write or read/write mode and
  88. obtain a file handle. BFWRITE/BFWRITEC and/or BFREAD/BFREADC can then
  89. be used to write/read data to/from the file at the current file pointer
  90. position. The position of the file pointer can be updated using BFSEEK,
  91. allowing completely random access to any byte address in a file.
  92.  
  93. Separate versions of the write routines and the read routines are provided
  94. for CHARACTER and non-CHARACTER data due to the differences in the argument
  95. passing mechanism for these data types. Use BFREADC/BFWRITEC to read/write
  96. CHARACTER data of any sort and BFREAD/BFWRITE to read/write all other data
  97. types (i.e. INTEGER, LOGICAL, REAL, DOUBLE PRECISION, etc.)
  98.  
  99. 4. Error Handling
  100.    --------------
  101. To simplify portability, error handling is implemented via an IERROR
  102. parameter which is always the last argument to each of the seven binary
  103. file handling routines. In all cases, a zero return code means there was
  104. no error. A non-zero error return specifies a system dependent error code.
  105. Different codes are returned under RISC OS and RISC iX.
  106.  
  107. 5. Subroutine Descriptions
  108.    -----------------------
  109. In the following documentation each subroutine argument is preceded by an
  110. (I) or (O) to signify whether it is an Input or Output argument.
  111.  
  112. ----------------------------------------------------------------------------
  113.  SUBROUTINE BFOPEN(FILNAM,MODE,IHANDL,IERROR)
  114.  
  115.   Open a file for fast binary i/o
  116.  
  117.   (I) FILNAM = Filename (must be null terminated)
  118.   (I) MODE   = Mode to open file in
  119.                 0 = read / 1 = write / 2 = read/write
  120.   (O) IHANDL = File handle
  121.   (O) IERROR = Error flag (non-zero if an error occurred)
  122.  
  123.   CHARACTER*(*) FILNAM
  124.   INTEGER       MODE,IHANDL,IERROR
  125.  
  126. BFOPEN opens a file for binary i/o and returns a file handle (channel
  127. number). This handle will be used in all subsequent file accesses via
  128. the other 'BF' routines until BFCLOSE is called. Several files can be
  129. open simultaneously, in which case the operating system will return
  130. different handles for each opened file. Do not confuse IHANDL with a
  131. Fortran Logical File Number. Whilst IHANDL serves a similar purpose
  132. to a LFN, its value is allocated by the operating system, not the
  133. user program and it cannot be used in Fortran i/o (read/write/etc.)
  134. statements.
  135.  
  136. The filename FILNAM must be null-terminated under both RISC OS and RISC iX.
  137. i.e. a CHAR(0) must be concatenated onto the end of the filename passed
  138. to BFOPEN.
  139.  
  140. The MODE argument controls how the file will be opened. Values of 0 or 2
  141. leave the current file contents intact. A value of 1 (write mode) creates
  142. an empty file if it did not already exist or sets the file length to zero
  143. otherwise. It is an error to open a non-existent file for read access.
  144.  
  145. The file handle IHANDL should be preserved since this is the only means
  146. of identifying the file to be accessed in subsequent read/write/seek
  147. operations
  148.  
  149. e.g.     PARAMETER (IR = 0, IW = 1 , IRW = 2)
  150.          CALL BFOPEN('datafile'//CHAR(0),IW,IHANDL,IERROR)
  151.          IF (IERROR.NE.0) THEN
  152.              WRITE(*,*)'Failed to open datafile'
  153.              STOP
  154.          ENDIF
  155.          CALL BFWRITE(IHANDL,IVALUE,4,NWRITN,IERROR)
  156.  
  157. ----------------------------------------------------------------------------
  158.   SUBROUTINE BFCLOSE(IHANDL,IERROR)
  159.  
  160.   close a binary file
  161.  
  162.   (I) IHANDL = File handle (obtained by previous call to BFOPEN)
  163.   (O) IERROR = Error flag (non-zero if an error occurred)
  164.  
  165.   INTEGER IHANDL,IERROR
  166.  
  167. Call BFCLOSE when you have finished processing a file.
  168.  
  169. e.g.     PARAMETER (IR = 0, IW = 1 , IRW = 2)
  170.          CALL BFOPEN('datafile'//CHAR(0),IW,IHANDL,IERROR)
  171.               :
  172.          CALL BFCLOSE(IHANDL,IERROR)
  173.          IF (IERROR.NE.0) WRITE(*,*)'Failed to close datafile'
  174.  
  175. ----------------------------------------------------------------------------
  176.   SUBROUTINE BFWRITEC(IHANDL,BUFFER,NBYTES,NWRITN,IERROR)
  177.  
  178.   Write a specified number of bytes from a CHARACTER
  179.   buffer to a binary file
  180.  
  181.   (I) IHANDL = File handle
  182.   (I) BUFFER = Character buffer holding data to write
  183.   (I) NBYTES = Number of bytes to write
  184.   (O) NWRITN = Number of bytes actually written
  185.   (O) IERROR = Error flag (non-zero if an error occurred)
  186.  
  187.   INTEGER       IHANDL,NBYTES,NWRITN
  188.   CHARACTER*(*) BUFFER
  189.  
  190. BFWRITEC writes the specified number of bytes from a data buffer which has
  191. been declared to be of type CHARACTER in the calling program. It does not
  192. matter whether the data buffer is an array, variable or literal string,
  193. so long as it is of type CHARACTER. NBYTES will then be written from that
  194. address regardless of the declared size of BUFFER in the calling program.
  195.  
  196. Two pieces of information are returned : NWRITN is the number of bytes
  197. actually written (usually the same as NBYTES) and IERROR is the error flag.
  198. IERROR can be set for various reasons (e.g. bad file handle, disk full, etc)
  199.  
  200. BFWRITEC writes data at the current file pointer position, which is
  201. set initially by BFOPEN to zero (the start of the file). On successful
  202. completion the file pointer is updated by NBYTES bytes, so that a
  203. subsequent call to BFWRITEC/BFWRITE will write to the position immediately
  204. following the last data to be written.
  205.  
  206. e.g.     PARAMETER (IR = 0, IW = 1 , IRW = 2)
  207.          CHARACTER*1  BUFF1(100)
  208.          CHARACTER*20 BUFF2
  209.          CALL BFOPEN('datafile'//CHAR(0),IW,IHANDL,IERROR)
  210.          CALL BFWRITEC(IHANDL,BUFF1,100,NWRITN,IERROR)
  211.          CALL BFWRITEC(IHANDL,BUFF2,LEN(BUFF2),NWRITN,IERROR)
  212.          CALL BFWRITEC(IHANDL,'I hate C',8,NWRITN,IERROR)
  213.  
  214. ----------------------------------------------------------------------------
  215.   SUBROUTINE BFWRITE(IHANDL,BUFFER,NBYTES,NWRITN,IERROR)
  216.  
  217.   Write a specified number of bytes from a non-CHARACTER
  218.   buffer to a binary file
  219.  
  220.   (I) IHANDL = File handle
  221.   (I) BUFFER = Non-character buffer holding data to write
  222.   (I) NBYTES = Number of bytes to write
  223.   (O) NWRITN = Number of bytes actually written
  224.   (O) IERROR = Error flag (non-zero if an error occurred)
  225.  
  226.   INTEGER           IHANDL,NBYTES,NWRITN,IERROR
  227.   INTEGER/REAL/etc. BUFFER
  228.  
  229. BFWRITE is exactly equivalent to BFWRITEC except that it should be used
  230. to write non-CHARACTER data, e.g. INTEGER, REAL, LOGICAL, etc. BFWRITE
  231. does not know or care what type of data is being written (so long as it
  232. is not CHARACTER) since BUFFER simply specifies an address of an area
  233. of memory to be written to disk. Thus a mixture of data (such as the
  234. data in a COMMON block) can easily be written in a single call simply
  235. by specifying the variable which lies at the start of the memory area
  236. to be written. Remember though, that NBYTES specifies the number of BYTES
  237. of data to be written so you must be careful to calculate the total buffer
  238. size accordingly
  239.  
  240. e.g.     COMMON/MIX/ IVALUE,RVALUE,LVALUE,DVALUE
  241.          INTEGER          IVALUE
  242.          REAL             RVALUE
  243.          LOGICAL          LVALUE
  244.          DOUBLE PRECISION DVALUE
  245.          PARAMETER (IR = 0, IW = 1 , IRW = 2)
  246.          CALL BFOPEN('datafile'//CHAR(0),IW,IHANDL,IERROR)
  247.    C NBYTES = sizeof(INTEGER) + sizeof(REAL)
  248.    C        + sizeof(LOGICAL) + sizeof(DOUBLE PRECISION)
  249.          NBYTES = 4 + 4 + 4 + 8
  250.          CALL BFWRITE(IHANDL,IVALUE,NBYTES,NWRITN,IERROR)
  251.  
  252. ----------------------------------------------------------------------------
  253.   SUBROUTINE BFREADC(IHANDL,BUFFER,NBYTES,NREAD,IERROR)
  254.  
  255.   Read a specified number of bytes from a binary file
  256.   into a CHARACTER buffer
  257.  
  258.   (I) IHANDL = File handle
  259.   (I) BUFFER = Character buffer to receive data
  260.   (I) NBYTES = Number of bytes to read
  261.   (O) NREAD  = Number of bytes actually read
  262.   (O) IERROR = Error flag (non-zero if an error occurred)
  263.  
  264.   INTEGER       IHANDL,NBYTES,NREAD,IERROR
  265.   CHARACTER*(*) BUFFER
  266.  
  267. BFREADC writes the specified number of bytes from a file into a data buffer
  268. which has been declared to be of type CHARACTER in the calling program.
  269. It does not matter whether the data buffer is an array or a variable (but
  270. not a literal string) so long as it is of type CHARACTER. Up to NBYTES will
  271. then be read from the file to that address regardless of the declared size
  272. of BUFFER in the calling program.
  273.  
  274. Two pieces of information are returned : NREAD is the number of bytes
  275. actually read. This need not necessarily be the same as NBYTES since there
  276. may not be that many ytes left in the file. Asusual, IERROR is the error
  277. flag which is most likely to be set if a bad file handle is specified,
  278.  
  279. BFREADC reads data from the current file pointer position, which is
  280. set initially by BFOPEN to zero (the start of the file) and can be updated
  281. by calling BFSEEK. On successful completion the file pointer is updated by
  282. NREAD bytes, so that a subsequent call to BFREADC/BFREAD will read from the
  283. position immediately following the last data to be read.
  284.  
  285. e.g.     PARAMETER (IR = 0, IW = 1 , IRW = 2)
  286.          CHARACTER*1  BUFF1(100)
  287.          CHARACTER*20 BUFF2
  288.          CALL BFOPEN('datafile'//CHAR(0),IR,IHANDL,IERROR)
  289.          CALL BFREADC(IHANDL,BUFF1,100,NREAD,IERROR)
  290.          IF (NREAD.EQ.100)
  291.         1    CALL BFREADC(IHANDL,BUFF2,LEN(BUFF2),NREAD,IERROR)
  292.  
  293. ----------------------------------------------------------------------------
  294.   SUBROUTINE BFREAD(IHANDL,BUFFER,NBYTES,NREAD,IERROR)
  295.  
  296.   Read a specified number of bytes from a binary file
  297.   into a non-CHARACTER buffer
  298.  
  299.   (I) IHANDL = File handle
  300.   (I) BUFFER = Non-character buffer to receive data
  301.   (I) NBYTES = Number of bytes to read
  302.   (O) NREAD  = Number of bytes actually read
  303.   (O) IERROR = Error flag (non-zero if an error occurred)
  304.  
  305.   INTEGER           IHANDL,NBYTES,NREAD,IERROR
  306.   INTEGER/REAL/etc. BUFFER
  307.  
  308. BFREAD is exactly equivalent to BFREADC except that it should be used
  309. to read data into non-CHARACTER variables, e.g. INTEGER, REAL, LOGICAL, etc.
  310. BFREAD does not know or care what type of data is being written (so long as
  311. it is not being read into a CHARACTER variable) since BUFFER simply
  312. specifies an address of an area of memory to which disk data is to be read.
  313. Thus a mixture of data (such as the data in a COMMON block) can easily be
  314. restored in a single call simply by specifying the variable which lies at
  315. the start of the memory area to be updated. Remember though, that NBYTES
  316. specifies the number of BYTES of data to be read so you must be careful to
  317. calculate the total buffer size accordingly
  318.  
  319. e.g.     COMMON/MIX/ IVALUE,RVALUE,LVALUE,DVALUE
  320.          INTEGER          IVALUE
  321.          REAL             RVALUE
  322.          LOGICAL          LVALUE
  323.          DOUBLE PRECISION DVALUE
  324.          PARAMETER (IR = 0, IW = 1 , IRW = 2)
  325.          CALL BFOPEN('datafile'//CHAR(0),IR,IHANDL,IERROR)
  326.    C NBYTES = sizeof(INTEGER) + sizeof(REAL)
  327.    C        + sizeof(LOGICAL) + sizeof(DOUBLE PRECISION)
  328.          NBYTES = 4 + 4 + 4 + 8
  329.          CALL BFREAD(IHANDL,IVALUE,NBYTES,NREAD,IERROR)
  330.  
  331. ----------------------------------------------------------------------------
  332.   SUBROUTINE BFSEEK(IHANDL,IFPOS,IERROR)
  333.  
  334.   Move binary file pointer
  335.  
  336.   (I) IHANDL = File handle (obtained by previous call to BFOPEN)
  337.   (I) IFPOS  = File pointer position (0 = start of file)
  338.   (O) IERROR = Error flag (non-zero if an error occurred)
  339.  
  340.   INTEGER IHANDL,IFPOS,IERROR
  341.  
  342. BFSEEK moves the file pointer within the file specified by BFSEEK. To rewind
  343. a file to the beginning specify an IFPOS value of zero. To move the file
  344. pointer to the end of the file, specify a huge IFPOS value larger than the
  345. file can possibly be. (n.b. this behaviour is different from the default
  346. RISC OS file handling routines which would attempt to extend a file to the
  347. new length if a file pointer is specified beyond the current extent).
  348.  
  349. As usual IERROR flags errors. The most likely error is that IHANDL is
  350. invalid.
  351.  
  352. e.g.     PARAMETER (IR = 0, IW = 1 , IRW = 2)
  353.          CHARACTER*10 START
  354.          CALL BFOPEN('datafile'//CHAR(0),IRW,IHANDL,IERROR)
  355.          IHUGE = 9999999
  356.          CALL BFSEEK(IHANDL,IHUGE,IERROR)
  357.          CALL BFWRITEC(IHANDL,'End of file',11,NWRITN,IERROR)
  358.          CALL BFSEEK(IHANDL,0,IERROR)
  359.    C Read first 10 bytes from start of file
  360.          CALL BFREADC(IHANDL,START,10,NREAD,IERROR)
  361.  
  362. ----------------------------------------------------------------------------
  363.  
  364. 6. Feedback
  365.    --------
  366. Any comments or bug reports to Lawson Wakefield of I.S.S. Ltd. on :
  367.  
  368.                        Tel. (+44) 0785 715588
  369.                        Fax  (+44) 0785 714913
  370.