home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #3 / amigamamagazinepolishissue1998.iso / bazy / quickfile3 / docs / qf_arexx.doc next >
Text File  |  1996-06-10  |  19KB  |  805 lines
  1.  
  2. =============== QuickFile ARexx Command interface ================
  3.  
  4. QuickFile v3.17.2 5 April 1996     Copyright Alan Wigginton
  5.  
  6. QuickFile accepts ARexx commands from macros (ARexx scripts invoked from
  7. within QuickFile) and from external scripts which may be run from another
  8. application or from the shell or workbench.
  9.  
  10. QuickFile's ARexx port is named QUICKFILE.01 for the first copy of
  11. QuickFile running, QUICKFILE.02 for the next and so on. QuickFile can
  12. open multiple windows so this should not be a problem.
  13.  
  14. Not all QuickFile functions can be executed via an ARexx command. If you
  15. would like to see some other commands added, let me know and I will see
  16. what I can do.
  17.  
  18. QuickFile expects commands to consist of a command name followed by a
  19. series of parameters separated by spaces. Parameters that contain spaces
  20. must be enclosed in quotes, therefore two sets of quotes are required in
  21. ARexx code as ARexx will remove the first set when it parses the command.
  22.  
  23. For example, to pass the following command to QuickFile
  24.  
  25.       ReqMsg 'This is a demo message'
  26.  
  27.   the ARexx code required is
  28.  
  29.       "ReqMsg 'This is a demo message'"
  30.  
  31. Both ARexx and QuickFile will accept either double or single quotes.
  32.  
  33. You should also include quotes around values included from variables if
  34. the variable value could contain spaces. For example:
  35.  
  36.     pull filename
  37.     address quickfile.01 "openfile '"filename"'"
  38.  
  39. If filename was entered as "My file" this would result in the following
  40. being (correctly) passed to quickfile:
  41.  
  42.     openfile 'My file'
  43.  
  44. If the single quotes had been omitted this would have caused an error. The
  45. easiest way to check the string being passed is to display it using say.
  46. This will usually make things clear.
  47.  
  48. QuickFile will process commands regardless of case and any ARex variables
  49. it creates will be upper case. Case is preserved in field values.
  50.  
  51. Confusion with case is a common problem with ARexx. ARexx always
  52. converts any tokens to upper case unless they are in quotes. A common
  53. trap is that the PULL and ARG statements translate to upper case as they
  54. are equivalent to PARSE UPPER PULL and PARSE UPPER ARG. To preserve case
  55. use PARSE PULL and PARSE ARG instead.
  56.  
  57. Return codes
  58.  
  59. The return codes from QuickFile have the following general meanings. See
  60. the command descriptions for details
  61.  
  62.     5    Warning or object not found.
  63.    10    Command failed
  64.    12    Unknown command
  65.    15    System error - usually out of memory
  66.    20    Syntax error
  67.  
  68. Command notation convention
  69.  
  70.     Command names use Initial Capitals eg GetRec
  71.     Values in square brackets [ ] are optional
  72.     You must include one of the values in braces {A | D}
  73.     Repeated values are indicated by ellipsis ...
  74.     Keywords are shown in UPPER CASE
  75.     Lower case words represent values you provide
  76.  
  77. ============ List of Commands ===================
  78.  
  79.     AddSearch         OpenWin
  80.     CloseWin         PutField
  81.     ClrRec             Query
  82.     CycleToString         Refresh
  83.     DelRec             Report
  84.     DoSearch         ReqChoice
  85.     FreeIndex         ReqMsg
  86.     FreeView         ReqString
  87.     GetField         SaveFile
  88.     GetRec             SetFile
  89.     GoTo             SetIndex
  90.     InsRec             SetView
  91.     LoadView         Sort
  92.     NewSearch         StringToCycle
  93.     Next             UpdRec
  94.     NumRecs          WintoFront
  95.     OpenFile
  96.  
  97.  
  98. ============= AddSearch =============
  99.  
  100. AddSearch {AND | OR} fieldname operator value1 [value2]
  101.  
  102. Adds a new search criteria to the existing criteria. Use the NewSearch
  103. command to replace any existing criteria and use DoSearch to start the
  104. search.
  105.  
  106. AND | OR    Determines how multiple criteria are to be handled. See
  107.         QuickFile docs for full details.
  108.  
  109. See the NewSearch command for details of the remaining parameters.
  110.  
  111. Results
  112.     None
  113.  
  114. Return codes
  115.     10    Unknown field or operator
  116.     20    Insufficient parameters or first parameter is not AND or OR
  117.  
  118. Example
  119.     /* select records where surname is brown or smith */
  120.     "newsearch surname equal brown"
  121.     "addsearch or surname equal smith"
  122.     "dosearch"
  123.  
  124. ============= CloseWin ===============
  125.  
  126. CloseWin
  127.  
  128. Closes the current window and file. You cannot close the last window with
  129. an ARexx command. The first window in QuickFiles internal list becomes the
  130. current window,
  131.  
  132. Results
  133.     None
  134.  
  135. Return codes
  136.     5    You tried to close the last window.
  137.  
  138. Example
  139.     "closewin"
  140.  
  141. ============== ClrRec ====================
  142.  
  143. ClrRec
  144.  
  145. Clears all fields in the current record. Use this to clear all fields
  146. before setting up the values for a new record
  147.  
  148. Results
  149.     None
  150.  
  151. Return codes
  152.     None
  153.  
  154. Example
  155.     "ClrRec"
  156.     "putfield surname Brown"
  157.     "putfield firstname John"
  158.     "putfield address '23 George Street'"
  159.     "insrec"
  160.  
  161. ============== CycleToString ================
  162.  
  163. CycleToString field string
  164.  
  165. Finds the string corresponding to a string number for a cycle field. The
  166. cycle field value is not changed.
  167.  
  168. Results
  169.     String from the cycle field.
  170.  
  171. Return codes
  172.     5    String number out of range for cycle field
  173.     10    Unknown field name or not a cycle field
  174.     20    Parameter missing
  175.  
  176. Example
  177.    given a cycle field called Status with "Active,Pending,Cancelled"
  178.  
  179.     "stringtocycle Status 2"
  180.     say result            /* ==> Cancelled */
  181.  
  182. ============== DelRec ================
  183.  
  184. DelRec
  185.  
  186. Deletes the current record. The next record becomes the new current
  187. record.
  188.  
  189. Results
  190.     None
  191.  
  192. Return codes
  193.     5    There are no records in the file.
  194.  
  195. Example
  196.     "getfield expirydate"
  197.     if result < today then
  198.     "delrec"
  199.  
  200. ============== DoSearch ============
  201.  
  202. DoSearch
  203.  
  204. Searches through the data base and selects records matching the search
  205. criteria. The criteria are established using the NewSearch and AddSearch
  206. commands.
  207.  
  208. It places the matching records in an index named SELECTED. It does not
  209. change the current index.
  210.  
  211. Results
  212.     RESULT contains the number of matching
  213.  
  214. Return codes
  215.     None
  216.  
  217. Example
  218.     "newsearch surname equal brown"
  219.     "addsearch or surname equal smith"
  220.     "dosearch"
  221.     "setindex selected"
  222.  
  223. ================ FreeIndex ==============
  224.  
  225. FreeIndex
  226.  
  227. Discards the current index and frees the storage used. Only temporary
  228. indexes, ie those named SORTED and SELECTED, can be freed.
  229.  
  230. Results
  231.     None
  232.  
  233. Return codes
  234.     10    Not a temporary index
  235.  
  236. Example
  237.     "setindex selected"
  238.     "freeindex"
  239.  
  240. ================ FreeView =================
  241.  
  242. FreeView
  243.  
  244. Discards the current view from memory and frees associated storage. The
  245. first view in the loaded list becomes the current view. The display is
  246. redrawn. You must keep at least one view. It does not affect the disk
  247. file containing the view.
  248.  
  249. Result
  250.     None
  251.  
  252. Return codes
  253.     5    You tried to free the last view
  254.  
  255. Example
  256.     "setview mylist.view"
  257.     "freeview"
  258.  
  259. ================ GetField =================
  260.  
  261. GetField field
  262.  
  263. Returns value of field from the current record
  264.  
  265. Result
  266.     Field value is placed in RESULT.
  267.  
  268. Return Codes
  269.     10    Field requested does not exist
  270.     20    Field name omitted
  271.  
  272. Example
  273.     "goto Smith"
  274.     "getfield surname"
  275.     say "Found name" result   * Displays==> Found name Smith */
  276.  
  277. ============= GetRec =============
  278.  
  279. GetRrec stem
  280.  
  281. Returns values for all fields from the current record in compound
  282. variables in the form of stem.fieldname where fieldname is the field name
  283. from the file definition (not always the title in the view).
  284.  
  285. You cannot use this if your field names contain spaces; use GETFIELD
  286. instead.
  287.  
  288. Results
  289.     stem.fieldname variables updated.
  290.  
  291. Return codes
  292.     20    Syntax error. stem not provided.
  293.  
  294. Example
  295.     "next"
  296.     "getrec val"
  297.     say val.firstname val.surname
  298.  
  299. =========== GoTo ===========
  300.  
  301. GoTo value1 [value2...]
  302.  
  303. Sets the current position to the first record with the current key
  304. matching the specified values. Value1 is the value for index field 1 and
  305. Value2 is the value for index field 2 etc.
  306.  
  307. QuickFile does not tell you if the requested record was not found. It will
  308. happily position on the next record. You must compare the record with the
  309. requested key values to check if they were found.
  310.  
  311. Result
  312.     None
  313.  
  314. Return Codes
  315.     5    End of file encountered. Requested key higher than any record.
  316.    10    More values specified than index fields
  317.  
  318. Example
  319.     "goto Brown John"
  320.     "getrec val"
  321.     if val.surname ~= "Brown" | val.firstname ~= "John" then
  322.     say "Record not found"
  323.  
  324. ============ InsRec ================
  325.  
  326. InsRrec
  327.  
  328. Adds a new record to the file. You use PUTFIELD to set the field values
  329. before issuing INSREC. Any fields not updated with PUTFIELD will retain
  330. the values from the previous record. Use CLRREC to clear all values
  331. before setting up your new record.
  332.  
  333. Results
  334.     None
  335.  
  336. Return codes
  337.     10    Error occurred. Probably duplicate key.
  338.  
  339. Examaple
  340.     "ClrRec"        /* omit this to use values from previous record */
  341.     "putfield surname Brown"
  342.     "putfield firstname John"
  343.     "putfield address '23 George Street'"
  344.     "insrec"
  345.  
  346. =================== LoadView ==============
  347.  
  348. LoadView path
  349.  
  350. Loads the named view. The full name including extension must be specified.
  351. This does not change the display. Use the SetView command to change the
  352. current view.
  353.  
  354. Result
  355.     None
  356.  
  357. Return codes
  358.     10    File not found
  359.     10    path name not specified
  360.  
  361. Example
  362.     "loadview df0:QuickFile/Example1/Product.view"
  363.  
  364. =================== NewSearch =============
  365.  
  366. NewSearch fieldname operator value1 [value2]
  367.  
  368. Replaces any existing search criteria with a new one. Use the AddSearch
  369. command to add additional criteria, if required, and use  the DoSearch
  370. command to start the actual search.
  371.  
  372. operator    The search operator. One of the following:
  373.         like
  374.         equal
  375.         between
  376.         notlike
  377.         notequal
  378.         sounds
  379.  
  380. value1        The value to be used in the search
  381.  
  382. value2        The second value required for the between operator. Can also
  383.         be used for others. See QuickFile docs for more details.
  384.  
  385. Results
  386.     None
  387.  
  388. Return codes
  389.     10    Unknown field or operator
  390.     20    Insufficient parameters
  391.  
  392. Example
  393.  /* find all current memberships that expire in March */
  394.     "newsearch status equal current"
  395.     "addsearch and 'expiry date' between 01-mar-95 31-mar-95"
  396.     "dosearch"
  397.  
  398. ================== Next ================
  399.  
  400. Next [n]
  401.  
  402. Moves n records forward or backward through the file. If n is omitted 1 is
  403. assumed. If the resulting position is outside the range of the file, the
  404. position will be the first or last record. n can be positive or negative.
  405.  
  406. Result
  407.     None.
  408.  
  409. Return codes
  410.     5    No more records. Positioned at first or last record
  411.  
  412. Example
  413.     "Next -9999"    /* move to start of file */
  414.     "Next"          /* move to second record */
  415.  
  416. ============ NumRecs ===============
  417.  
  418. NumRecs
  419.  
  420. Returns number of records in the current index. If 'Selected' is the
  421. current index, this will be the number of selected records.
  422.  
  423. Result
  424.     Number of records in RESULT
  425.  
  426. Return codes
  427.     10    No file open
  428.  
  429. Example
  430.     "SetIndex name"
  431.     say result            /* ==> 253    */
  432.     "SetIndex selected"
  433.     "NumRecs"
  434.     say result            /* ==> 16 */
  435.  
  436. ============ OpenFile ===============
  437.  
  438. OpenFile pathname
  439.  
  440. Opens a new file in the current window. Closes the existing file, if any.
  441. To open an additional file, issue the OPENWINDOW command first to obtain a
  442. new window.
  443.  
  444. Result
  445.     None
  446.  
  447. Return codes
  448.     10    The file could not be opened. NB Any previous file will have been
  449.     closed.
  450.     20    pathname not specified
  451.  
  452. Example
  453.     "openfile 'ram disk:Membership'"  /* care with spaces in path names */
  454.  
  455. ================== OpenWin ===============
  456.  
  457. OpenWin
  458.  
  459. Opens a new window which becomes the current window. It will have no open
  460. file. Until a file is opened, the only commands that can be issued are
  461. OpenFile, CloseWin.
  462.  
  463. Result
  464.     None
  465.  
  466. Return Codes
  467.     10    The window could not be opened
  468.  
  469. Example
  470.     pull filename
  471.     "openwin"
  472.     "openfile '"filename"'"  /* quotes in case filename contains spaces */
  473.  
  474. =========== PutField ==============
  475.  
  476. PutField field value
  477.  
  478. Sets the contents of field for the current record to value. The change
  479. will not take effect until you issue the UPDREC command. value must be
  480. consistent with the field's type.
  481.  
  482. Result
  483.     None
  484.  
  485. Return codes
  486.     5    The value is inconsistent with the field type. The field is not
  487.     updated
  488.    10    The field does not exist
  489.    20    Either field or value were omitted
  490.  
  491. Example
  492.     "next"
  493.     newdate = "31-Mar-1996"
  494.     "putfield 'expiry date'" newdate
  495.     "updrec"
  496.  
  497. =============== Query =================
  498.  
  499. Query {FIELD | INDEX} stem [name]
  500.  
  501. Obtains details about the current file.
  502.  
  503. stem    A stem variable to receive the details
  504.  
  505. name    An optional name of an object to be queried. If omitted, a summary
  506.     of all objects of the requested type are returned.
  507.  
  508. Results
  509.  
  510.   FIELD without name
  511.     Returns the number of fields in stem.0 and the field names in
  512.     stem.1 to stem.n where n is the number of fields.
  513.  
  514.   FIELD with name
  515.     Returns field type in stem.type and the maximum length in
  516.     stem.length. Name is a field name
  517.  
  518.   INDEX without name
  519.     Returns the number of indexes in stem.0 and the index names
  520.     in stem.1 to stem.n
  521.  
  522.   INDEX with name
  523.     Returns the number of index fields in stem.0 in the field names in
  524.     stem.1 to stem.n. Name is an index name.
  525.  
  526. Return codes
  527.     10    Requested name does not exist
  528.     15    Syntax error. Either a required field was omitted or type was not
  529.     FIELD or INDEX.
  530.  
  531. Example
  532.     "query field fld"
  533.     do i = 1 to fld.0    /* displays all field names */
  534.     say fld.i
  535.     end
  536.  
  537. ============== Refresh =============
  538.  
  539. Refresh
  540.  
  541. Redraws the screen display. This should not be required in a macro, but
  542. will be required if you want to update the display to reflect changes
  543. made from an external script.
  544.  
  545. Result
  546.     None
  547.  
  548. Return codes
  549.     None
  550.  
  551. Example
  552.     "refresh"
  553.  
  554. ============== Report ===============
  555.  
  556. Report count [target [title]]
  557.  
  558. Produces the report defined for the current view. Writes 'count' records
  559. starting at the current record. The parameters are positional so 'title'
  560. cannot be specified without 'target'.
  561.  
  562. count    Number of records to process. Specify -1 for all.
  563.  
  564. target    Specify 'printer' to write report to the printer, otherwise the
  565.     report is written to the screen.
  566.  
  567. title    Up to 50 characters to be used instead of the title defined for
  568.     the report. Don't forget the extra quotes.
  569.  
  570. Note that the report definition is not changed.
  571.  
  572. Result
  573.     None
  574.  
  575. Return codes
  576.     10    No report has been defined for the current view.
  577.     15    Could not allocate memory.
  578.  
  579. Example
  580.     "report -1 printer 'Report Title over-ride'"  /* note quotes */
  581.  
  582.     "report 10 screen"
  583.  
  584. ============== ReqChoice ============
  585.  
  586. ReqChoice line1 [line2]
  587.  
  588. Displays a requester that displays two lines of text with OK and CANCEL
  589. buttons. Don't forget the extra set of quotes.
  590.  
  591. Result
  592.     None
  593.  
  594. Return codes
  595.     0    User chose OK.
  596.     5    User chose CANCEL.
  597.    20    No message text specified
  598.  
  599. Example
  600.     "reqchoice 'Delete requested' 'Are you sure'"
  601.     if rc = 0 then
  602.     "delrec"
  603.     else
  604.     say "Delete cancelled"
  605.  
  606. ============== ReqMsg =============
  607.  
  608. ReqMsg message
  609.  
  610. Displays the message in a requester. The message must be enclosed in
  611. quotes if it is more than one word.
  612.  
  613. Result
  614.     None
  615.  
  616. Return codes
  617.     20        No message specified
  618.  
  619. Example
  620.     "ReqMsg 'This message from ARexx script'"
  621.  
  622. ============== ReqString ============
  623.  
  624. ReqString default [title]
  625.  
  626. Displays a requester with a string gadget to obtain input from the
  627. keyboard.
  628.  
  629. default     The default value to be placed in the string gadget. Specify
  630.         '' if no default
  631.  
  632. title        The title to be displayed in the requester window.
  633.  
  634. Result
  635.     RESULT will contain the users input string
  636.  
  637. Return codes
  638.      0    User pressed OK
  639.      5    User pressed CANCEL
  640.     20    No message specified
  641.  
  642. Example
  643.     "reqstring '' 'Please enter your name'"
  644.     if rc = 0 then
  645.     name =    result
  646.  
  647. ============== SaveFile ==============
  648.  
  649. SaveFile
  650.  
  651. Writes any updates to disk, if any changes have been made.
  652.  
  653. Result
  654.     None
  655.  
  656. Return codes
  657.     None
  658.  
  659. Example
  660.     "savefile"
  661.  
  662. ============== SetFile ===============
  663.  
  664. SetFile [filename]
  665.  
  666. Selects window containing filename as the current window or returns
  667. current file name if 'filename' is not specified.
  668.  
  669. The file must have been opened previously. 'Filename' is the file name
  670. part only, not including disk and directory names.
  671.  
  672. Results
  673.     Current file name if issued without filename, otherwise none.
  674.  
  675. Return code
  676.     5  Unknown file name
  677.  
  678. Example
  679.     "setfile"
  680.     say result
  681.  
  682.     "setfile Images"
  683.  
  684. ============= SetIndex =====================
  685.  
  686. SetIndex [indexname]
  687.  
  688. Makes indexname the current index. Specify a name as SORTED to use the
  689. last sort sequence and SELECTED to use the last selection.
  690.  
  691. Returns name of the current index if issued without 'indexname'.
  692.  
  693. Results
  694.     Name of current index if issued without name, otherwise none.
  695.  
  696. Return codes
  697.     5  Could not find index
  698.  
  699. Example
  700.     "setindex sorted"
  701.  
  702. ==================== SetView =================
  703.  
  704. SetView [viewname]
  705.  
  706. Makes the named view the current view and redraws the display using the
  707. new view. The viewname must include the extension, if any.
  708.  
  709. If 'viewname' is not specified, returns the name of the current view.
  710.  
  711. Warning: If used from a macro, this may cause the window to be redrawn
  712. several times in quick succession after the macro completes. This happens
  713. because QuickFile does not respond to Intuition's newsize messages while
  714. the macro is running and several may be queued up when the macro
  715. completes. This does not happen if it is used from the shell or another
  716. program.
  717.  
  718. Result
  719.     Name of the current view if issued without 'viewname', otherwise none.
  720.  
  721. Return codes
  722.     5  Could not find view
  723.  
  724. Example
  725.     "setview namelist.view"
  726.  
  727. ==================== Sort ===================
  728.  
  729. Sort field {A | D} [field {A | D} ] ...
  730.  
  731. Creates a new index named SORTED in the specified sequence and makes
  732. 'sorted the current index.
  733.  
  734. field    The field name to sort over
  735.  
  736. order    A for ascending, D for descending
  737.  
  738. Both field and order must be specified for each sort field. You can switch
  739. between indexes, including SORTED and SELECTED using SETINDEX.
  740.  
  741. Result
  742.     None
  743.  
  744. Return codes
  745.     10    One of the sort fields was not known.
  746.     20    Either no parameters specified or there was not an even number
  747.     of parameters
  748.  
  749. Example
  750.     "sort country a surname a firstname a"
  751.  
  752. =========== StringToCycle ==============
  753.  
  754. StringToCycle field string
  755.  
  756. Converts a string to a cycle field string number. The numbering starts
  757. at zero. The cycle field value is not changed.
  758.  
  759. Results
  760.     Cycle field string number.
  761.  
  762. Return codes
  763.     5    String not found in cycle field
  764.     10    Unknown field name or not a cycle field
  765.     20    Parameter missing
  766.  
  767. Example
  768.    given a cycle field called Status with "Active,Pending,Cancelled"
  769.  
  770.     "stringtocycle Status 'cancelled'"
  771.     say result        /* ==> 2 */
  772.  
  773. =========== UpdRec ==============
  774.  
  775. UpdRec
  776.  
  777. Commits an updated record to the file. The update is not necessarily
  778. written back to disk at this point.
  779.  
  780. Results
  781.     None
  782.  
  783. Return codes
  784.     10    Internal error occurred. Possibly a duplicate key occurred
  785.  
  786. Example
  787.     "putfield ExpiryDate 31-Mar-95"
  788.     "updrec"
  789.  
  790. ========= WinToFront ============
  791.  
  792. WinToFront
  793.  
  794. Moves the current window to the front of the display.
  795.  
  796. Results
  797.     None
  798.  
  799. Return codes
  800.     None
  801.  
  802. Example
  803.     "wintofront"
  804.  
  805.