home *** CD-ROM | disk | FTP | other *** search
/ Amiga Computing 59 / ac059.adf / SupportFiles / files.doc / files.doc
Text File  |  1993-02-05  |  8KB  |  132 lines
  1.                       FILING SYSTEM
  2. No less than three demonstration programs are on the support disc this time!
  3. The first two explain to new Assembler and 'C' programmers how to read
  4. and write files from a disc. The third demo program contains some more 
  5. advanced features that might interest regular readers of this page.
  6.                     COMMAND OF THE LANGUAGE
  7. The last two programming pages introduced the Amiga Library, with routines
  8. that can be used in 'C' and Assembler programs. C programmers passed the input
  9. parameters to the routine (as to any other function), and any result was
  10. returned. Assembler programmers put the inputs in the appropriate registers, 
  11. and called the routine as if it was a subroutine. Any return values came back 
  12. in register D0. The short demo programs opened the Dos library, for the 
  13. Output() and Write() commands to write a message to the screen.
  14. The current demo programs use Dos library routines to read data from an ASCII
  15. file in the current directory, and write data to a similar file. Two Exec 
  16. library routines are needed to allocate a block of memory to store this data, 
  17. and to free the memory afterwards for general use.     
  18.  
  19. AllocMem(bytesize,requirements) (D0,D1) 'puts by' an area of memory  
  20. 'bytesize' is the number of bytes wanted
  21. 'requirements' is the type of memory wanted 
  22. If the command is successful, a pointer to a block of memory is returned.
  23. The memory block will be available for you, and not overwritten by another
  24. program when multitasking.
  25.  
  26. FreeMem(memorypointer,bytesize) (A1,D0) frees the block of memory
  27. 'memorypointer' is a pointer to a block of allocated memory
  28. 'bytesize' is the number of bytes to be freed
  29.  
  30. Open(name,mode) (D1,d2) opens the chosen file
  31. 'name' is the name of the file
  32. 'mode' is the access mode
  33. A pointer to a 'filehandle' or block of information for the file, is returned 
  34. (the system uses the block of information, when processing the file).  
  35.  
  36. Read(filehandle,buffer,length) (D1,D2,D3) will read from a file
  37. 'filehandle' is its filehandle pointer 
  38. 'buffer' is a pointer to the memory area to hold the data
  39. 'length' is the number of bytes to be read
  40. The number of bytes successfully read, is returned. 
  41.  
  42. Close(filehandle) (D1) closes the file
  43. 'filehandle' is its filehandle pointer
  44.  
  45.                        INCLUSION POLICY
  46. The main compiler (or assembler) header directory contains a subdirectory of 
  47. 'header files' for each library. These files contain useful macros and 
  48. definitions for some of the library functions. A header file can be 'included'
  49. with any source code. 
  50.   The file 'exec/memory.h' (C) or 'exec/memory.i' (Assembler) is included 
  51. with the source code as it contains the memory requirement definitions for 
  52. use with the AllocMem() command. The program asks for memory that is 
  53. 'public', 'clear' but not necessarily 'chip'.
  54.   The file 'libraries/dos.h' or 'libraries/dos.i' is used for the access mode
  55. definitions when opening a file.  The file to be read (limerick) is opened
  56. using MODE_OLDFILE, which opens an existing file for reading or writing.
  57. The file to be written (limerick2) is opened using MODE_NEWFILE which will 
  58. overwrite a file if it already exists, and open a new one otherwise.
  59. *****************************************************************************
  60.                     THE ASSEMBLER DEMO PROGRAM
  61. The complete program source code listing (afiles.a) is available on the          
  62. support disc. The files "exec/types.i" has been included as it contains
  63. definitions used by "libraries/dos.i" and "exec/memory.i". Instead of having 
  64. all the code in the main program, groups of commands have been built into
  65. separate subroutines. The main program checks the value returned from each
  66. subroutine to see whether the subroutine is successful. If all is well the 
  67. program can continue, otherwise it tidies up and exits gracefully.  The 
  68. cleanup routine closes any open files or libraries, and frees any allocated 
  69. memory. It also calls a 'message' subroutine, entering the routine with the
  70. a pointer to the message data in register D2, and the length of the message
  71. in register D3. The message subroutine only has to put the filehandle of the 
  72. console in register D1, the address of the Dos library in A6, and call the
  73. Amiga library Write() routine to display the data on the screen.
  74.   When the object program (afiles) is run, the program opens the 
  75. DOS library. If the library opens successfully, the program asks the Amiga
  76. to allocate a memory buffer for 152 bytes of data. If the memory is 
  77. forthcoming, the program can open a short ASCII text file ('limerick') in
  78. the current directory, and read the text into the memory buffer. 
  79. If the data has been read successfully, the program opens a new file, 
  80. ('limerick2'), writes the text 'This is a new file' into it, and then apends 
  81. the text from the memory buffer. The program writes the text from the
  82. buffer to the screen, and waits for a few seconds. The program can then 
  83. display a message of success on the screen, tidy up, and exit.
  84. ******************************************************************************
  85.                         THE C PROGRAM
  86. The support disc contains the program source code listing (files.c) and the
  87. object code (files). The source code includes "libraries/dos.h" and 
  88. "exec/memory.h" for some of its definitions. Some of the commands have been
  89. grouped into functions which are called from the main program. The functions 
  90. are listed separately after the main program but their 'prototypes' are 
  91. declared earlier. The main program is then aware of the name of each function
  92. and the datatype of its return value. 
  93.   The 'cleanup' function has a parameter passed to it, a pointer to a string 
  94. of text. The function displays the text on the screen, tidies up the files, 
  95. libraries, and allocated memory. The main program can call this function with
  96. a suitable message for all occaisions. 
  97.   When the object program (files) is run, the program opens the library, and 
  98. allocates a memory buffer. The short text file is read into the buffer, and
  99. the contents displayed on the screen. After a short delay a text message and 
  100. the buffer contents are written to the 'limerick2' file, and the program 
  101. tidies itself up and exits. 
  102. *****************************************************************************
  103.                        ADVANCED FEATURES
  104. When a file is opened for reading, information about the file is put into
  105. a parameter block in memory, called a 'filehandle', and a pointer to a
  106. FileHandle structure is returned. When the file is first opened, the 
  107. read/write position, or file pointer, will be at the beginning of the file.
  108. When a number of bytes of information are read or written, the file pointer
  109. will move a corresponding number of bytes. If you do not want any other
  110. process to interfere with the file, you can open the file with access mode
  111. MODE_READWRITE. This access mode opens an existing file for reading or writing,
  112. but locks the file so that as long as it is open, no other process on the 
  113. multitasking Amiga can access it. 
  114.   It is also possible to lock files, without opening them for reading
  115. or writing. This can be especially useful for a file requester program,
  116. it can obtain a lock on all the available files and directories, and ensure 
  117. that they remain undisturbed.
  118.                            LOCK UP YOUR FILES
  119. The source code (advfiles.c) and the object code (advfiles) are both available
  120. on the support disc. When the program is run it opens the Dos library,
  121. and opens the text file 'limerick' in MODE_READWRITE. 
  122.   To demonstrate this, 'advfiles' calls the 'files' program (Process 1) which 
  123. is unable to open the 'limerick' text file for reading. After 'advfiles' 
  124. closes the file, it calls the 'files' program again (Process 2) which can 
  125. successfully read the 'limerick' file and write the 'limerick2' file.
  126. 'Advfiles' obtains a lock for the second file, 'limerick2'. The 'files'
  127. program is called (Process 3) and there will be a message to the effect that 
  128. the 'limerick2' file cannot be written.  When the file is unlocked and the 
  129. 'files' program called again (Process 4) the files can be read and written
  130. successfully.
  131. ******************************************************************************
  132.