home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / libraries / fileio_463 / fileio.lzh / BASIC / Basicusers < prev    next >
Text File  |  1991-02-08  |  6KB  |  150 lines
  1.                          FOR BASIC PROGRAMMERS
  2.  
  3.    This document is meant as a supplement for BASIC programmers to the FileIO
  4. programmer's doc. Please read that document as well.
  5.    The file requester operates on a structure which I've called a FileIO.
  6. A structure is one block of memory which contains various "fields". A field
  7. is simply a portion (some bytes) of that block of memory. The FileIO structure
  8. takes up 264 bytes of memory. These 264 bytes contain 29 fields. Some fields
  9. only take up 1 byte, others are 2 bytes wide (a WORD), or 4 bytes wide (a
  10. LONG). Certain other fields can be any number of bytes wide. These are STRINGS.
  11. Each field of a structure contains values (numbers). Sometimes these numbers
  12. form the address of some other structure. An address takes up 4 bytes (just
  13. like a LONG), but we'll call it APTR.
  14.   Unfortunately, AmigaBasic has no facility for manipulating structures as
  15. such. You cannot say, "Set the PenA field of my FileIO to the value 1." You
  16. must treat the FileIO as one block of memory, and its various fields as
  17. offsets from the beginning of that block of memory. The library routine
  18. GetFileIO() returns the start address of the FileIO memory block. This is
  19. what it looks like in memory.
  20.  
  21.   Field Name      Field Size       Offset from start
  22.  ------------    -------------    -------------------
  23.  
  24. The FileIO starts here:
  25.   Flags            1 WORD                 0
  26.   FileName        30 BYTES (STRING)       2
  27.   DrawerName     132 BYTES (STRING)      32
  28.   DiskName        30 BYTES (STRING)     164
  29.   DOS lock         4 BYTES (APTR)       194
  30.   NameCount        2 BYTES (WORD)       198
  31.   NameStart        2 BYTES (WORD)       200
  32.   CurrentPick      2 BYTES (WORD)       202
  33.   FileKey          4 BYTES (APTR)       204
  34.   FileIOText       4 BYTES (APTR)       208
  35.   FileIORoutine    4 BYTES (APTR)       212
  36.  the next 2 fields are for WB pattern match (i.e. Icon files displayed only)
  37.   DiskObjectType   2 BYTES (WORD)       216
  38.   ToolTypes        4 BYTES (LONG)       218
  39.  the next 2 fields are for extention match
  40.   ExtStringAddr    4 BYTES (APTR)       222
  41.   ExtStringLen     2 BYTES (WORD)       226
  42.   CustomHandler    4 BYTES (APTR)       228
  43.  the next 2 fields are the XY where the requester will open up in the window
  44.   ReqXposition     2 BYTES (WORD)       232
  45.   ReqYposition     2 BYTES (WORD)       234
  46.   FreeDiskSpace    4 BYTES (LONG)       236
  47.   FileSize         4 BYTES (LONG)       240
  48.   WindowTitle      4 BYTES (APTR)       244
  49.   BufferAddress    4 BYTES (APTR)       248
  50.   RawkeyCode       4 BYTES (APTR)       252
  51.   OriginalLock     4 BYTES (APTR)       256
  52.   Error number     1 BYTE               260
  53.   DrawMode         1 BYTE               261
  54.   PenA             1 BYTE               262
  55.   PenB             1 BYTE               263
  56.  
  57.   If you add up the sizes of all 29 fields, you should get 264 bytes.
  58.  
  59.   Now, let's say that we called GetFileIO() as demonstrated in the example
  60. program, BasicFileIO. We stored the returned address in a variable called
  61. FileIO.
  62.   There are two AmigaBASIC commands that are used with structures, PEEK and
  63. POKE. If you want to change a field of the FileIO, you must POKE a value to
  64. it. If you want to know what value is already stored in a FileIO field, then
  65. you PEEK that field. For example, if we want to know what the FileIO's PenA
  66. field is, we PEEK that field as follows.
  67.  
  68.   VALUE = PEEK(FileIO+262)
  69.  
  70.   I had to add 262 to FileIO because the PenA field's offset is 262 (see the
  71. above chart). Now VALUE is the number that was in the PenA field. If we want
  72. to change the number in the PenA field to 2, we must POKE the field like this:
  73.  
  74.   POKE  FileIO+262,2
  75.  
  76.   PEEK and POKE are used for fields that are only 1 BYTE in size (like the
  77. PenA, PenB, Flags, etc). For fields that are 2 BYTES (WORD) in size, you
  78. must use POKEW and PEEKW. For example, to change the ReqXposition to 50:
  79.  
  80.   POKEW FileIO+232,50
  81.  
  82.   Notice how I added the ReqXposition field's offset to FileIO.
  83.  
  84.   For LONG and APTR fields (4 BYTES in size), you must use PEEKL and POKEL.
  85. An APTR field is tricky because you can only put an address there. There are
  86. two BASIC commands for finding addresses of variables. If the variable is a
  87. string, use SADD. For all other types of variables, use VARPTR. For example,
  88. let's say we declared the following string.
  89.  
  90.   Title$ = "Hello"
  91.  
  92.   Now, let's set the FileIO's WindowTitle field to the address of our string.
  93. As you can see from the chart, the FileIO's WindowTitle field is APTR. In
  94. fact, this field holds the address of the title that is displayed in the
  95. window when the requester opens. Notice that this field's offset is 244.
  96.  
  97.   POKEL FileIO+244,SADD(Title$)
  98.  
  99.   For STRINGS (like the FileIO's Diskname), you must use PEEK or POKE to
  100. examine or alter EVERY SINGLE BYTE of the string. The Diskname is 30 BYTES
  101. and has an offset of 164 from the FileIO base. To copy the diskname to a
  102. a BASIC string, you must declare a string of 30 chars in length,
  103.  
  104.   DIM DiskName$(30)
  105.  
  106.   and PEEK all 30 bytes (starting at an offset of 164) to this BASIC string.
  107. See the example program for details.
  108.  
  109.   There is much more to be said about this topic. Please examine the commented
  110. code of the enclosed BASIC example. If the code seems completely alien to you,
  111. then you should buy a book on advanced AmigaBASIC programming. I can't recom-
  112. mend one as I didn't read any. Being an assembly programmer, I was able to
  113. ascertain how to use these BASIC commands by studying an example on the EXTRAS
  114. disk.
  115.  
  116.   There is one FileIO field that the example only briefly covers, the Flags
  117. field. Here are the values you should POKE to enable the following features.
  118. To enable several features simultaneously, just OR the hex ON MASK for all
  119. desired features.
  120.  
  121.                  BOOL MASK
  122. NO_CARE_REDRAW   = 1
  123. USE_DEVICE_NAMES = 2
  124. EXTENSION_MATCH  = 4
  125. DOUBLECLICK_OFF  = 8
  126. WBENCH_MATCH     = 16
  127. MATCH_OBJECTTYPE = 32
  128. MULTIPLE_FILES   = 64
  129. INFO_SUPPRESS    = 128
  130. NO_ALPHA         = 4096
  131. SHOW_DISK_NAMES  = 16384
  132. SPECIAL_REQ      = 32768
  133.  
  134.   For example, to enable EXTENTION_MATCH, DOUBLECLICK_OFF, and INFO_SUPPRESS:
  135.  
  136.   value = 4 OR 8 OR 128
  137.   POKEW   FileIO+0,value
  138.  
  139.   To disable a flag, NOT its BOOL MASK, then AND with the present value of
  140. the FileIO's flags. For example, to disable EXTENTION_MATCH:
  141.  
  142.   value = PEEKW(FileIO+0)
  143.   flag  = NOT 4
  144.   value = value AND flag
  145.   POKEW   FileIO+0,value  
  146.  
  147.   I hope that you find this file requester useful for your BASIC programs.
  148.  
  149.           Jeff Glatt
  150.