home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d594 / analyrimsrc.lha / AnalyRimSrc / AnaRimSrcDoc.Zoo / riminterface.doc < prev    next >
Text File  |  1991-09-30  |  9KB  |  212 lines
  1. The AnalytiCalc RIM interface is a command interface to AnalytiCalc which
  2. allows the AnalytiCalc user to operate on predefined RIM database
  3. schemas. In the following let us assume the following RIM schema
  4. definition is in effect:
  5.   DEFINE FOO
  6.   OWNER GCE
  7.   ATTRIBUTES
  8.     LABEL INT KEY
  9.     VAL DOUB
  10.     FRM TEXT VAR
  11.   RELATIONS
  12.     SS WITH LABEL VAL FRM
  13.   END
  14.  
  15.  
  16. This defines a database containing one relation; each row of the relation
  17. contains an index, a value, and a formula and the relation SS relates
  18. these; each row contains one of each. The AnalytiCalc interface does not
  19. understand all possible RIM datatypes due to the difficulty of presenting
  20. some of them in a spreadsheet context. It does understand the following
  21. types:
  22.    1. Integer (4 bytes)
  23.    2. Real (4 bytes)
  24.    3. Double (8 bytes) (NOTE: this is only partly functional!)
  25.    4. Text, variable length.
  26.  
  27.    The AnalytiCalc commands that operate on RIM data all begin with CMD
  28. and must be done in certain combinations. To allow the spreadsheet to
  29. know the types of different RIM attributes, it is necessary to keep
  30. a "title row" on the sheet. This contains the attribute names in a
  31. format usable for titles, plus encoded type information.
  32.   The interface commands are as follows:
  33.  
  34. CMDOPEN dbname
  35.    Opens the RIM database named "dbname". (RIM code assumes the
  36. database files are in the current default directory.)
  37.  
  38. CMDUSER password
  39.    Sets the current password (or "user") to "password". This is used
  40. to match against owner, read, or modify passwords that may be set
  41. on RIM relations.
  42.  
  43. CMDCLOSE
  44.     Closes the currently active database.
  45.  
  46. CMDGETATT relname,startcell:endcell
  47.     This command loads the "title row" from the relation "relname"
  48. (which would be SS in the given example) into the spreadsheet starting
  49. at startcell and working right from there. The endcell is used to
  50. determine how many of the attributes to set (at most; if there are
  51. fewer attributes in the relation, only those that exist are stored)
  52. and does NOT determine direction. Rather the title row is ALWAYS a row.
  53.  
  54. CMDFIND relname
  55.     This command establishes a set of rows which can be pulled
  56. into AnalytiCalc (via CMDGET) or loaded into (via CMDLOAD or CMDPUT)
  57. storing them internally. The set and order of rows to be retrieved
  58. may be altered AFTER a CMDFIND call by a CMDWHERE call or a
  59. CMDSORT call. However, before any data can be accessed, a CMDGETATT
  60. must have been done to store properties and CMDFIND, optionally
  61. followed by CMDWHERE and/or CMDSORT, must be given.
  62.  
  63. CMDWHERE
  64.     CMDWHERE gives a single WHERE clause to qualify the rows
  65. selected. The command format is
  66.     CMDWHERE attcell:valuecell,oper
  67. so that the attribute name must be stored in attcell's formula
  68. and the value must be in the value of the cell valuecell if
  69. the attribute is numeric, or in the formula if it is text.
  70.    For example, the command
  71.     CMDWHERE C2:G5,GT
  72.    might express the qualifier
  73.         WHERE VAL GT 5.0
  74. if cell G5 contained value 5.0 and cell C2 were the title cell for
  75. attribute VAL in the example relation SS. Title cells may be used
  76. or the cell may be any whose formula contains the attribute name
  77. (space padded to 8 characters).
  78.  
  79.     Unlike the situation in full interactive RIM, and owing
  80. to the complexities of decoding, only a single qualifier is supported
  81. in WHERE statements at this point.
  82.  
  83. CMDSORT
  84.     CMDSORT allows sorting of selected rows on one or more
  85. keys prior to retrieval. The command format is:
  86.     CMDSORT attcell:typcell
  87. The attcell formula must contain attribute names, space padded
  88. And 8 characters apart (though if a title cell is used for a single
  89. attribute, that is OK) to be sorted on. The formula of typcell contains
  90. up to 6 characters, A or D, corresponding to up to 6 attribute names
  91. (column names) in typcell. If an A is found in typcell, the attribute
  92. is sorted in Ascending order. If a D is found, it is sorted in Descending
  93. order. Up to 6 columns may be sorted on with one call.
  94.  
  95. CMDGET
  96.     CMDGET loads rows into a spreadsheet area that have been
  97. readied by CMDFIND and possible CMDWHERE and CMDSORT commands.
  98. The command format is:
  99.     CMDGET titlecell,ulcell:rlcell
  100. where titlecell is the upper left end of the "title cell row"
  101. loaded with CMDGETATT earlier for the relation. ulcell:lrcell
  102. is an area on the spreadsheet in upper-left:lower-right format
  103. to be filled in. The number of rows in this area controls the
  104. number of rows that CMDGET will try to retrieve from the RIM
  105. database, and the number of columns controls the number of
  106. attributes of each relation to be stored in the spreadsheet. These
  107. always start from the first attribute of each row of the relation;
  108. there is no provision for skipping any.
  109.  
  110. CMDDEL
  111.     CMDDEL deletes rows from a RIM relation. It presumes you
  112. have used CMDFIND, CMDWHERE, CMDSORT, and CMDGET to "position"
  113. yourself in the RIM relation where you want to be, and then deletes
  114. the N rows you tell it.
  115.     The command format is:
  116.     CMDDEL var
  117.     where var is a cell whose value is the number of rows of
  118. the relation to delete.
  119.  
  120. CMDPUT
  121. CMDLOD
  122.     CMDPUT and CMDLOD enter rows in a RIM relation. The command
  123. format is
  124.     CMDPUT titlecell,valuerowcello:valuerowcellhi
  125.     or
  126.     CMDLOD titlecell,valuerowcello:valuerowcellhi
  127.  
  128.     If using CMDPUT, you need to use CMDFIND etc. and CMDGET
  129. to "position" yourself in the RIM relation where you want. CMDPUT
  130. will then overwrite the relation at the last gotten cell with
  131. data from the spreadsheet. By specifying an area, multiple
  132. relation rows can be replaced with one call. One would use such 
  133. a thing by using CMDFIND et. al.  and CMDGET to get data out
  134. of a RIM relation, modify it on the sheet, then use CMDFIND
  135. et. al. and possibly a shorter CMDGET (if the first several
  136. relations were not to be changed) followed by CMDPUT to
  137. replace some of the data.
  138.  
  139.     The CMDLOD command just adds rows to the relation at the
  140. end, so it does not require "positioning" oneself.
  141.  
  142.  
  143.  
  144. CMDRIM
  145.     CMDRIM
  146.     The CMDRIM command simply places you into RIM command mode,
  147. from which point any RIM command is legal. This permits one to
  148. access any and all RIM functions from AnalytiCalc. Should
  149. AnalytiCalc input be coming from a command file, the RIM input
  150. will do so also. An additional RIM keyword RETURN is added
  151. and causes RIM to return to AnalytiCalc without closing its
  152. data bases. The reason for this is to permit the other commands
  153. to be used to find data and allow RIM WHERE clauses to be entered
  154. in full generality prior to using CMDGET or CMDPUT. This avoids
  155. the limitation of the rest of the AnalytiCalc RIM frontend
  156. which permits only a single WHERE clause. Should automation
  157. be desired, a command file driving both AnalytiCalc and RIM
  158. components can be used.
  159.  
  160. CMDIRIM
  161.     CMDIRIM Rim-command
  162.  
  163.     CMDIRIM will pass any RIM command to the RIM database component
  164. of AnalyRim as a single line command. Then it will pass a RETURN
  165. command to RIM so that the effect is to execute one line of command
  166. followed by a return to the spreadsheet control sequence. This can
  167. be used as a more convenient means to pass commands, via the
  168. *U XQTCMD function from within cells or via interactive commands,
  169. to the database. Where a single WHERE or SORT qualifier is desired,
  170. this makes it simpler to use the normal RIM SQL-like syntax.
  171.  
  172. CMDSAV
  173.     CMDSAV locell:hicell
  174.  
  175.     CMDSAV presets AnalytiCalc to capture RIM output (during
  176. CMDRIM or CMDIRIM mode) into the given rectangular range of
  177. cells. These cells will be filled in with the text of RIM
  178. output verbatim (up to 109 characters each), one line of
  179. output per cell. RIM output beyond 109 characters is not
  180. saved (except in the -arg input array, for the last typed
  181. command only). A CMDSAV command without the cell range arguments
  182. turns off this output saving. Cells in the range that are filled
  183. in become text cells (resettable as usual with DF commands if
  184. such is needed.)
  185.  
  186. CMDKLON and CMDKLOF
  187.     RIM does not really store double precision data correctly,
  188. so it is not fully functional. What RIM normally does is store a
  189. single precision real in 8 bytes. AnalytiCalc stores true 8
  190. bit double precision, on the other hand. When RIM is passed
  191. this 8 bit data, it stores and retrieves it OK. At least on
  192. the Sun architecture, however, it may compute incorrectly with
  193. it. If such data is stored/retrieved by AnalytiCalc using CMDGET
  194. and CMDLOD/CMDPUT and friends (but not via CMDRIM/CMDIRIM),
  195. it will be handled consistently. Attempts to use the data across
  196. the two interfaces will however not work well. 
  197.     To allow the CMDGET routine to at least load RIM-stored
  198. DOUB data (loaded via the CMDRIM interface), give the CMDKLON
  199. command, which allows such data to be recognized and loaded by
  200. converting to true real*8. To return to the totally consistent
  201. model, give the CMDKLOF command (kludge on and off). The conversion
  202. will only be done if the second half of the purported real*8
  203. number is exactly zero, but this can happen legally for many
  204. cases, making yet another command necessary.
  205.     The best course is to avoid using the DOUB type where
  206. feasible, but this allows it to be used where it makes sense
  207. to do so, provided one is willing to use the AnalytiCalc
  208. command interface for all data accesses and examinations.
  209.     Note that the use of the RIM interface for adding
  210. WHERE or SORT clauses should be harmless, but beware of selection
  211. on DOUB data entered from AnalytiCalc.
  212.