home *** CD-ROM | disk | FTP | other *** search
/ Vectronix 2 / VECTRONIX2.iso / FILES_08 / NEO4REL5.LZH / NEO4REL5.MSA / JARXXX / JARXXX.DOC < prev    next >
Text File  |  1993-03-05  |  10KB  |  204 lines
  1.                         JARxxx:  Cookie Jar Manager
  2.                                 by Dan Wilga
  3.                       Copyright 1992, Gribnif Software
  4.                       
  5. This program may be freely distributed, even with commercial products, so
  6. long as this documentation file is included, and both it and the program
  7. are unmodified.
  8.  
  9.  
  10. What is the Cookie Jar, anyway?
  11. ------------------------------
  12.  
  13. When Atari created TOS 1.60, they added a feature to the operating system
  14. which had been needed for some time. It allows programs to store
  15. information in a place where any other program can look for it. This Cookie
  16. Jar is very useful for things like an AUTO folder program which wants to be
  17. able to leave some information around for a companion desk accessory to
  18. look at. Also, newer versions of the operating system use cookies to tell
  19. programs what types of hardware the computer has. Atari even provided a
  20. documented method for programs to create a Cookie Jar for older versions of
  21. TOS.
  22.  
  23.  
  24. Fine, so why do I need this program?
  25. -----------------------------------
  26.  
  27. When Atari documented how to use the Cookie Jar, it outlined how
  28. programmers should create new cookies and how to see what value a
  29. particular cookie has. Unfortunately, the procedure for doing this is not
  30. all that simple. The result was that some programs either go about it
  31. half-heartedly, or do not work correctly in all cases.
  32.  
  33. What JARxxx does is take the "dirty work" away and simplify the whole
  34. process of using the Cookie Jar. It provides a standard way for programs to
  35. look for cookies and create new ones. It also establishes a new jar, as
  36. large as you want it to be, for all future programs to use.
  37.  
  38. If you received this program as part of another package, you will probably
  39. need it in order for the other program to run properly. NeoDesk, for
  40. instance, requires JARxxx, so that it can create a cookie to use later on.
  41. Even if you do not have a program which takes advantage of the code in
  42. JARxxx to look for and create new cookies, you can still benefit from its
  43. ability to enlarge the Cookie Jar, since some programs which create cookies
  44. will give an error message when the Cookie Jar is full, rather than making
  45. it larger.
  46.  
  47.  
  48. Installation
  49. ------------
  50.  
  51. JARxxx is very easy to install. All you have to do is copy JARXXX.PRG into
  52. the AUTO folder of the disk you normally boot from. Then, rename the
  53. program so that the "XXX' is a number. This number, which is the quantity
  54. of new cookies to make space for in the jar, can be anywhere from 0 to 999.
  55.  
  56. Usually, a program will only create one cookie for itself, if it creates
  57. any at all. A value of 10 extra cookies will probably be more than enough
  58. for most people. They take up very little memory (8 bytes each), so don't
  59. worry about making the number too large.
  60.  
  61. If you make this number too small, a program may quit with a message like
  62. "Not enough room in cookie jar". If this happens, you can either run
  63. JARxxx.PRG again from the desktop (to double the number of entries), or
  64. increase the number by changing the name of the file in the AUTO folder.
  65.  
  66. Probably the most common type of program to use the Cookie Jar is one which
  67. runs in the AUTO folder. Since it is not easy to tell which programs use
  68. the Jar, it is safest to just make sure that JARxxx runs before all other
  69. AUTO folder programs. If you use a boot configuration program like XBoot,
  70. however, you can probably leave the configuration program as first, and
  71. make JARxxx second. To accomplish this, there is a program called AUTOFRST
  72. which is also included with JARxxx.
  73.  
  74. AUTOFRST will take whatever program you tell it to and reposition it so
  75. that it will be the first program the operating system loads from the AUTO
  76. folder.  You tell AUTOFRST which program to make first by giving it the full
  77. path of that file on the TTP commandline. For instance, if you tell it
  78. "c:\auto\jar16.prg", then JAR16.PRG will be moved to the first position.
  79.  
  80. AUTOFRST can actually be used to reorder the files in any directory, not
  81. just the AUTO folder. It can also be given a list of filenames, like this:
  82.  
  83.   c:\auto\jar16.prg xboot.prg neoload.prg templmon.prg
  84.  
  85.  
  86. Technical Stuff
  87. ---------------
  88.  
  89. The Cookie Jar is pointed to by a variable called _p_cookies, which is
  90. located at $5A0. If there is no jar installed, this memory location
  91. contains a null pointer. Each cookie in the jar is two longwords in size:
  92.  
  93.                      longword 1  longword 2
  94.                    -------------------------
  95.         Cookie #1  | ID Number |   Value   |
  96.                    -------------------------
  97.         Cookie #2  | ID Number |   Value   |
  98.                    -------------------------
  99.         ...
  100.                    -------------------------
  101.         Cookie #n  | ID Number |   Value   |
  102.                    -------------------------
  103.     Length Cookie  | 0 (long)  | Jar Size  |
  104.                    -------------------------
  105.         
  106. The first longword in a cookie is an ID number. This should somehow
  107. describe what program installed the cookie. A common practice is to use a
  108. longword whose ASCII value is an abbreviation for the program.  For
  109. example, JARxxx installs a cookie whose ID is "CJar" ($434A6172).  Atari
  110. has reserved all ID's beginning with "_" for use by the operating system.
  111. You should not use ID's beginning with this character.
  112.  
  113. The "Value" field of a cookie can contain any information at all, but since
  114. there are only four bytes of space, the most common thing to do is to use
  115. this to store a pointer to a larger structure which can hold more
  116. information.
  117.  
  118. The last cookie in the jar has an ID of zero (long). This indicates the end
  119. of the cookie jar. The "value" of this cookie is actually a longword
  120. indicating how many entries the entire jar can hold. This number does NOT
  121. include the length cookie, itself. Therefore, a jar large enough for 10 new
  122. cookies must actually be 11 entries (or 22 longwords) in size.
  123.  
  124.  
  125. Programming Using JARxxx
  126. ------------------------
  127.  
  128. JARxxx works by first copying the old Cookie Jar to a new location, if
  129. necessary. This depends on the number of entries requested. If the number
  130. of requested entries is less than the current number of empty entries, the
  131. jar is not changed. This means that if you just want to install the jar
  132. management code without increasing the jar, you simply need to request 0
  133. entries. JARxxx also intercepts trap #14 (XBIOS) and the reset vector (to
  134. clean up the Cookie Jar for older versions of the operating system.)
  135.  
  136. If you want to use JARxxx's routines in your own program, here is all you
  137. need to do. There is a new XBIOS routine ($434A) which is installed by
  138. JARxxx to handle requests by a program. A C language binding:
  139.  
  140.         int CJar( int mode, long cookie, long *value )
  141.  
  142. Mode 0 will retrieve the "cookie" and store its value in the longword
  143. pointed to by the long pointer.  If the long pointer is null (zero), then
  144. the value is not stored anywhere.  The value $6172 is returned if the
  145. search was successful; 0 is returned if the cookie was not found. Any other
  146. value greater than zero can be assumed to mean that JARxxx is not
  147. installed.  Values less than zero are currently reserved.
  148.  
  149. This mode can, and should be, used to determine if JARxxx is installed
  150. before actually creating a new cookie.  If the "cookie" parameter is
  151. $434A6172 ("CJar") and the number $6172 is returned, then JARxxx is
  152. installed.  In this situation, any other return value means JARxxx is not
  153. installed.  If the "value" pointer is not null (zero), then the longword
  154. pointed to by it is modified to contain the following information:
  155.  
  156.         high word, high byte:   Version number, starting at $01.
  157.  
  158.         high word, low byte:    An unsigned byte indicating the number of
  159.                                 cookie jar entries specified by the user. A
  160.                                 value of zero means 256 or more.
  161.  
  162.         low word, high byte:    An unsigned byte indicating the number of
  163.                                 cookie jar entries actually allocated.
  164.                                 This includes any cookie jar entries which
  165.                                 already existed when JARxxx first ran.  A
  166.                                 value of zero means 256 or more.
  167.  
  168.         low word, low byte:     An unsigned byte indicating the number of
  169.                                 cookie jar entries currently being used.  A
  170.                                 value of zero means 256 or more.
  171.  
  172. Mode 1 creates a new cookie.  In this case, "value" points to a longword
  173. whose *contents* are copied into the cookie jar.  If "value" is null
  174. (zero), then a value of zero is entered into the cookie jar.  This is
  175. useful for situations where the mere presence of the new cookie in the jar
  176. is sufficient.  If the cookie already exists, the old value is overwritten.
  177. This mode returns $6172 if the addition was successful or -1 if the
  178. addition failed due to lack of room in the cookie jar.  All other return
  179. values are currently reserved.
  180.  
  181. All other modes are reserved.
  182.  
  183. For an example of how to use this call in a C program, please refer to the
  184. file JARTEST.C, which is included with this document.
  185.  
  186.  
  187. Contact
  188. -------
  189.  
  190. If you have any questions or comments about this program, please feel free
  191. to get in touch with me. I want to make sure as many people use this
  192. program as possible.
  193.  
  194.         Dan Wilga
  195.         Gribnif Software
  196.         P.O. Box 779
  197.         Northampton, MA  01061
  198.         
  199.         GEnie:    GRIBNIF
  200.         Internet: wilga@titan.ucs.umass.edu
  201.         
  202.         Voice: (413) 247-5620
  203.         Fax:   (413) 247-5622
  204.