home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / fortran / library / library / libry5.doc < prev    next >
Text File  |  1989-11-10  |  14KB  |  349 lines
  1. .pa
  2.                             FILE HANDLING ROUTINES
  3.  
  4. FORTRAN is rather ill suited to file I/O. It is painfully slow compared to the
  5. actual  speed  of  memory-to-disk  transfers.  I have developed  this  set  of
  6. procedures to allow fast file access from FORTRAN. On the HP-1000F and HP-A900
  7. these  routines  provide a speed increase factor of about 20.  On the  PC  the
  8. speed  increase is more like 30 for FORTRAN/V3.31 and 3 for FORTRAN/V4   It
  9. may  seem  a  little circuitous at first to always read  and  write  character
  10. strings  instead  of  numbers and to call some subroutine rather  than  simply
  11. using "WRITE" and "READ" statements; but once you get used to it,  it isn't so
  12. bad; and the speed is worth a little extra trouble.
  13.  
  14. As far as numbers go, you can use DEC0DE to decode  them  from  the  character
  15. strings and "WRITE(CBUF,1000)" to encode them.
  16.  
  17. I  have  allowed for only four sequential access files and one  random  access
  18. file. It's not obvious in FORTRAN, but you can't just open an unlimited number
  19. of  files.  If you need more you can always access the binary file  procedures
  20. directly  (e.g.   BOPEN).  You can open as many files with BOPEN as there  are
  21. FILES=?? allocated in your CONFIG.SYS file.
  22.  
  23. A  word  of  warning about reading files created by word  processors  and  the
  24. like... these procedures ignore control characters on either read or write and
  25. chop-off trailing blanks on write.  Also, files must end with the standard EOF
  26. character (zero record length for HPs or ctrl-Z for PCs). This is done for you
  27. automatically  by  the end-file functions and most editors (at least  WED  and
  28. IBM's  Professional  Editor).   If you create a file using FORTRAN on  the  PC
  29. WITHOUT these procedures and then attempt to read it WITH these procedures you
  30. will  get  trash  at the end unless you put a CHAR(26)  on the last  line  (A1
  31. format) before you close the file.
  32.  
  33. Another  word  of caution.  Do not mix Microsoft's FORTRAN file I/O and  these
  34. routines.   The  only thing that I know it messes up is the  directory  search
  35. functions (DIRSET and DIRNXT);  however,  one can't be sure.  You see there is
  36. this  special area at the top of your program called a program segment  prefix
  37. (PSP) which contains an important data transfer area (DTA). FORTRAN moves this
  38. area off into the twilight zone; whereas, these routines leave it alone.  They
  39. just aren't compatible.
  40. .pa
  41.                    QUICK LIST OF FILE HANDLING SUBROUTINES
  42.  
  43. BCLOSE... binary file close
  44. BCREAT... binary file open (status='unknown')
  45. BMFP..... move binary file pointer
  46. BOPEN.... binary file open (status='old')
  47. BPURGE... binary file purge/delete
  48. BREAD.... binary file read
  49. BWRITE... binary file write
  50. DIRNXT... get next entry in directory
  51. DIRSET... set up for directory search
  52. ECLOS.... close random access file
  53. EOPEN.... open random access file
  54. EREAD.... read random access file
  55. EWRIT.... write random access file
  56. FBKSP1... backspace first sequential access file
  57. FCLOS1... close first sequential access file
  58. FENDF1... end (affix EOF marker to) first sequential access file
  59. FEXIST... logical check for file exist
  60. FOPEN1... open first sequential access file
  61. FREAD1... read first sequential access file
  62. FRWND1... rewind first sequential access file
  63. FWRIT1... write first sequential access file
  64. GETPSP... get the program segment prefix (PC only - on HP use GETST)
  65. RRPAR.... get file name from runtime string
  66.  
  67. also available are:
  68.  
  69.      FWRIT2, FBKSP2, FCLOS2, FENDF2, FOPEN2, FREAD2, and FRWND2.
  70.      FWRIT3, FBKSP3, FCLOS3, FENDF3, FOPEN3, FREAD3, and FRWND3.
  71.      FWRIT4, FBKSP4, FCLOS4, FENDF4, FOPEN4, FREAD4, and FRWND4.
  72.  
  73. A note about binary file routines:
  74.  
  75.      These are not available on the HP. They are absolute file I/O. There
  76.      is  no  consideration of record separators,   line-feeds,   carriage
  77.      return, or end of file markers. This applies to reading and writing.
  78. .pa
  79. NAME:     BCLOSE
  80. PURPOSE:  close a binary file
  81. TYPE:     subroutine (far external)
  82. SYNTAX:   CALL BCLOSE(IHAND)
  83. INPUT:    IHAND (INTEGER*2) file handle (see BOPEN)
  84. OUTPUT:   none
  85.  
  86.  
  87. NAME:     BCREAT
  88. PURPOSE:  open a binary file and create if not already exist
  89. TYPE:     subroutine (far external)
  90. SYNTAX:   CALL BCREAT(NAME,ICODE,IHAND,IERR)
  91. INPUT:    NAME (CHARACTER*(*)) ASCIIZ string (the last character MUST be a
  92.           CHAR(0)! or else disaster may result)
  93.           ICODE (INTEGER*2) open code (see BOPEN)
  94. OUTPUT:   IHAND (INTEGER*2) file handle (see BOPEN)
  95.           IERR (INTEGER*2) error indicator (see BOPEN)
  96.  
  97.  
  98. NAME:     BMFP
  99. PURPOSE:  move binary file pointer
  100. TYPE:     subroutine (far external)
  101. SYNTAX:   CALL BMFP(IHAND,NBYTES,IERR)
  102. INPUT:    IHAND (INTEGER*2) file handle (see BOPEN)
  103.           NBYTES (INTEGER*4 note unsigned long integer!) number of bytes from
  104.           the beginning of the file where you want the pointer to be
  105.           positioned (e.g. NBYTES=INT4(0) is a rewind)
  106. OUTPUT:   IERR (INTEGER*2) error indicator (IERR=1 indicated invalid handle)
  107.  
  108.  
  109. NAME:     BOPEN
  110. PURPOSE:  open an existing binary file
  111. TYPE:     subroutine (far external)
  112. SYNTAX:   CALL BOPEN(NAME,ICODE,IHAND,IERR)
  113. INPUT:    NAME (CHARACTER*(*)) ASCIIZ string (the last character MUST be a
  114.           CHAR(0)! or else disaster may result)
  115.           ICODE (INTEGER*2) open code (see chart below)
  116.                  bit 7 6 5 4 3 2 1 0
  117.                      . . . . . . . 1  read only
  118.                      . . . . . . 1 .  hidden
  119.                      . . . . . 1 . .  system
  120.                      . . . . 1 . . .  volume label
  121.                      . . . 1 . . . .  subdirectory
  122.                      . . 1 . . . . .  archive
  123.                      . 1 . . . . . .  unused
  124.                      1 . . . . . . .  unused
  125. OUTPUT:   IHAND (INTEGER*2) file handle (you must keep track of this and use
  126.           it every time you refer to the file)
  127.           IERR (INTEGER*2) error indicator
  128.                IERR= 2  file not found or invalid file name
  129.                IERR= 3  path not found or invalid path name
  130.                IERR= 4  no handles available (too many files already open)
  131.                IERR= 5  access denied (protected file)
  132.                IERR=12  invalid access code
  133.  
  134.  
  135. NAME:     BPURGE
  136. PURPOSE:  purge/delete an existing file
  137. TYPE:     subroutine (far external)
  138. SYNTAX:   CALL BPURGE(NAME)
  139. INPUT:    NAME (CHARACTER*(*)) ASCIIZ string (the last character MUST be a
  140.           CHAR(0)! or else disaster may result)
  141. OUTPUT:   none
  142.  
  143.  
  144. NAME:     BREAD
  145. PURPOSE:  read from a binary file (what's in there is what you get-literally!)
  146. TYPE:     subroutine (far external)
  147. SYNTAX:   CALL BREAD(IHAND,LREC,CBUF,LBUF,IERR)
  148. INPUT:    IHAND (INTEGER*2) file handle (see BOPEN)
  149.           LREC (INTEGER*2) size of buffer to be read in bytes (unsigned
  150.           integer - can go up to 65535)
  151. OUTPUT:   CBUF (CHARACTER*(*)) buffer
  152.           LBUF (INTEGER*2) actual number of bytes read (you must check for
  153.           end of file, LBUF can be zero)
  154.           IERR (INTEGER*2) error indicator
  155.                IERR=5  access denied (protected file)
  156.                IERR=6  invalid handle
  157.  
  158.  
  159. NAME:     BWRITE
  160. PURPOSE:  write to a binary file (what you put in there is what will be in
  161.           there, literally!)
  162. TYPE:     subroutine (far external)
  163. SYNTAX:   CALL BWRITE(IHAND,LREC,CBUF,IERR)
  164. INPUT:    IHAND (INTEGER*2) file handle (see BOPEN)
  165.           LREC (INTEGER*2) size of buffer to be written in bytes (unsigned
  166.           integer - can go up to 65535)
  167.           CBUF (CHARACTER*(*)) buffer
  168. OUTPUT:   IERR (INTEGER*2) error indicator
  169.                IERR=5  access denied (protected file)
  170.                IERR=6  invalid handle
  171.                IERR=7  write error or insufficient space
  172.  
  173.  
  174. NAME:     DIRNXT
  175. PURPOSE:  get next entry in directory (see DIRSET)
  176. TYPE:     subroutine (far external)
  177. SYNTAX:   CALL DIRNXT(NAME)
  178. INPUT:    none
  179. OUTPUT:   NAME (CHARACTER*12) next matching name (blank indicates no more
  180.           matches)
  181.  
  182.  
  183. NAME:     DIRSET
  184. PURPOSE:  set up for directory search
  185. TYPE:     subroutine (far external)
  186. SYNTAX:   CALL DIRNXT(NAME)
  187. INPUT:    NAME (CHARACTER*12) file mask (e.g. '*.*') DO NOT use a constant
  188.           character string as it will be written over on return.
  189. OUTPUT:   NAME (CHARACTER*12) first matching name (blank indicates no matches)
  190. NOTE:     You must call this before DIRNXT. See example program at the end
  191.           of this section.
  192.  
  193.  
  194. NAME:     ECLOS
  195. PURPOSE:  close random access file
  196. TYPE:     subroutine (far external)
  197. SYNTAX:   CALL ECLOS
  198. INPUT:    none
  199. OUTPUT:   none
  200.  
  201.  
  202. NAME:     EOPEN
  203. PURPOSE:  open random access file
  204. TYPE:     subroutine (far external)
  205. SYNTAX:   CALL EOPEN(NAME,NEW,LREC,IERR)
  206. INPUT:    NAME (CHARACTER*? up to 64 including drive and path)
  207.           NEW (INTEGER*2) NEW<0 means 'old', NEW=0 means 'unknown'
  208.           NEW>0 means 'new' (note that Microsoft hasn't yet learned what
  209.           'new', 'old', and 'unknown' mean.  'New' means make one and if
  210.           it already exists return an error.  'Old' means open it and if
  211.           it doesn't already exist return an error. 'Unknown' means open
  212.           it and create it if necessary.)
  213.           LREC (INTEGER*2) record length in bytes
  214. OUTPUT:   IERR (INTEGER*2) error indicator (IER=0 is normal)
  215.  
  216.  
  217. NAME:     EREAD
  218. PURPOSE:  read random access file
  219. TYPE:     subroutine (far external)
  220. SYNTAX:   CALL EREAD(CBUF,NREC,IERR)
  221. INPUT:    NREC (INTEGER*2) desired record number
  222. OUTPUT:   CBUF (CHARACTER*LREC see EOPEN) buffer
  223.           IERR (INTEGER*2) error indicator (IER=0 is normal)
  224.  
  225.  
  226. NAME:     EWRIT
  227. PURPOSE:  write random access file
  228. TYPE:     subroutine (far external)
  229. SYNTAX:   CALL EWRIT(CBUF,NREC,IERR)
  230. INPUT:    CBUF (CHARACTER*LREC see EOPEN) buffer
  231.           NREC (INTEGER*2) desired record number
  232. OUTPUT:   IERR (INTEGER*2) error indicator (IER=0 is normal)
  233.  
  234.  
  235. NAME:     FBKSP1
  236. PURPOSE:  backspace first sequential access file
  237. TYPE:     subroutine (far external)
  238. SYNTAX:   CALL FBKSP1(NREC)
  239. INPUT:    NREC (INTEGER*2) number of records to backspace (if NREC is
  240.           larger than the number of records read so far this will be
  241.           the same as a rewind)
  242. OUTPUT:   none
  243.  
  244.  
  245. NAME:     FCLOS1
  246. PURPOSE:  close first sequential access file
  247. TYPE:     subroutine (far external)
  248. SYNTAX:   CALL FCLOS1
  249. INPUT:    none
  250. OUTPUT:   none
  251.  
  252.  
  253. NAME:     FENDF1
  254. PURPOSE:  end (affix EOF marker to) first sequential access file
  255. TYPE:     subroutine (far external)
  256. SYNTAX:   CALL FENFD1
  257. INPUT:    none
  258. OUTPUT:   none
  259.  
  260.  
  261. NAME:     FEXIST
  262. PURPOSE:  logical test for file exist
  263. TYPE:     LOGICAL*2 function (far external)
  264. SYNTAX:   IF(.NOT.FEXIST('THISFILE.EXT')) GO TO 100
  265. INPUT:    CHARACTER*(*) file name
  266. OUTPUT:   none
  267.  
  268.  
  269. NAME:     FOPEN1
  270. PURPOSE:  open first sequential access file
  271. TYPE:     subroutine (far external)
  272. SYNTAX:   CALL FOPEN1(NAME,NEW,IERR)
  273. INPUT:    NAME (CHARACTER*? up to 64 including drive and path)
  274.           NEW (INTEGER*2) NEW<0 means 'old', NEW=0 means 'unknown'
  275.           NEW>0 means 'new' (note that Microsoft hasn't yet learned what
  276.           'new', 'old', and 'unknown' mean.  'New' means make one and if
  277.           it already exists return an error.  'Old' means open it and if
  278.           it doesn't already exist return an error. 'Unknown' means open
  279.           it and create it if necessary.)
  280. OUTPUT:   IERR (INTEGER*2) error indicator (IER=0 is normal)
  281. NOTE:     See example program at the end of this section.
  282.  
  283.  
  284. NAME:     FREAD1
  285. PURPOSE:  read first sequential access file
  286. TYPE:     subroutine (far external)
  287. SYNTAX:   CALL FREAD1(CBUF,NBUF,LREC,IERR,IEND)
  288. INPUT:    NBUF (INTEGER*2) number of bytes in CBUF
  289. OUTPUT:   CBUF (CHARACTER*?) buffer
  290.           LREC (INTEGER*2) nominal record length
  291.           IERR (INTEGER*2) error indicator (IERR=0 is normal)
  292.           IEND (INTEGER*2) EOF indicator (IEND=0 is normal)
  293.  
  294.  
  295. NAME:     FWRIT1
  296. PURPOSE:  write first sequential access file
  297. TYPE:     subroutine (far external)
  298. SYNTAX:   CALL FWRIT1(CBUF,NBUF,IERR)
  299. INPUT:    CBUF (CHARACTER*?) buffer
  300.           NBUF (INTEGER*2) number of bytes in CBUF
  301. OUTPUT:   IERR (INTEGER*2) error indicator (IERR=0 is normal)
  302.  
  303.  
  304. NAME:     FRWND1
  305. PURPOSE:  rewind first sequential access file
  306. TYPE:     subroutine (far external)
  307. SYNTAX:   CALL FRWND1
  308. INPUT:    none
  309. OUTPUT:   none
  310.  
  311.  
  312. NAME:     GETPSP
  313. PURPOSE:  get the program segment prefix (PC only - on HP use GETST)
  314. TYPE:     subroutine (far external)
  315. SYNTAX:   CALL GETPSP(PSP)
  316. INPUT:    none
  317. OUTPUT:   PSP (CHARACTER*1 PSP(128))
  318. NOTE:     This seems like a logical thing to want; but to actually find
  319.           the PSP after DOS gets through with it on the PC is no easy
  320.           task when working from inside an EXE file.
  321.  
  322.  
  323. NAME:     RRPAR
  324. PURPOSE:  get file name from runtime string
  325. TYPE:     subroutine (far external)
  326. SYNTAX:   CALL RRPAR(N,NAME)
  327. INPUT:    N (INTEGER*2) number of entry see example below
  328. OUTPUT:   NAME (CHARACTER*12)
  329. NOTE:     the purpose of this is to fetch and parse the string that you
  330.           type in after the name of your program as below
  331.  
  332.                MYPROG this.dat that.for other.bin wednesday
  333.  
  334.           fetch the names with the following
  335.  
  336.                CHARACTER NAME1*12,NAME2*12,NAME3*12,COMMENT*12
  337.                CALL RRPAR(1,NAME1)
  338.                CALL RRPAR(2,NAME2)
  339.                CALL RRPAR(3,NAME3)
  340.                CALL RRPAR(4,COMMENT)
  341.  
  342.           you will get the following
  343.  
  344.                NAME1='this.dat'
  345.                NAME2='that.for'
  346.                NAME3='other.bin'
  347.                COMMENT='wednesday'
  348. .ad LIBRY5A.DOC
  349.