home *** CD-ROM | disk | FTP | other *** search
-
- =============== QuickFile ARexx Command interface ================
-
- QuickFile v3.17.2 5 April 1996 Copyright Alan Wigginton
-
- QuickFile accepts ARexx commands from macros (ARexx scripts invoked from
- within QuickFile) and from external scripts which may be run from another
- application or from the shell or workbench.
-
- QuickFile's ARexx port is named QUICKFILE.01 for the first copy of
- QuickFile running, QUICKFILE.02 for the next and so on. QuickFile can
- open multiple windows so this should not be a problem.
-
- Not all QuickFile functions can be executed via an ARexx command. If you
- would like to see some other commands added, let me know and I will see
- what I can do.
-
- QuickFile expects commands to consist of a command name followed by a
- series of parameters separated by spaces. Parameters that contain spaces
- must be enclosed in quotes, therefore two sets of quotes are required in
- ARexx code as ARexx will remove the first set when it parses the command.
-
- For example, to pass the following command to QuickFile
-
- ReqMsg 'This is a demo message'
-
- the ARexx code required is
-
- "ReqMsg 'This is a demo message'"
-
- Both ARexx and QuickFile will accept either double or single quotes.
-
- You should also include quotes around values included from variables if
- the variable value could contain spaces. For example:
-
- pull filename
- address quickfile.01 "openfile '"filename"'"
-
- If filename was entered as "My file" this would result in the following
- being (correctly) passed to quickfile:
-
- openfile 'My file'
-
- If the single quotes had been omitted this would have caused an error. The
- easiest way to check the string being passed is to display it using say.
- This will usually make things clear.
-
- QuickFile will process commands regardless of case and any ARex variables
- it creates will be upper case. Case is preserved in field values.
-
- Confusion with case is a common problem with ARexx. ARexx always
- converts any tokens to upper case unless they are in quotes. A common
- trap is that the PULL and ARG statements translate to upper case as they
- are equivalent to PARSE UPPER PULL and PARSE UPPER ARG. To preserve case
- use PARSE PULL and PARSE ARG instead.
-
- Return codes
-
- The return codes from QuickFile have the following general meanings. See
- the command descriptions for details
-
- 5 Warning or object not found.
- 10 Command failed
- 12 Unknown command
- 15 System error - usually out of memory
- 20 Syntax error
-
- Command notation convention
-
- Command names use Initial Capitals eg GetRec
- Values in square brackets [ ] are optional
- You must include one of the values in braces {A | D}
- Repeated values are indicated by ellipsis ...
- Keywords are shown in UPPER CASE
- Lower case words represent values you provide
-
- ============ List of Commands ===================
-
- AddSearch OpenWin
- CloseWin PutField
- ClrRec Query
- CycleToString Refresh
- DelRec Report
- DoSearch ReqChoice
- FreeIndex ReqMsg
- FreeView ReqString
- GetField SaveFile
- GetRec SetFile
- GoTo SetIndex
- InsRec SetView
- LoadView Sort
- NewSearch StringToCycle
- Next UpdRec
- NumRecs WintoFront
- OpenFile
-
-
- ============= AddSearch =============
-
- AddSearch {AND | OR} fieldname operator value1 [value2]
-
- Adds a new search criteria to the existing criteria. Use the NewSearch
- command to replace any existing criteria and use DoSearch to start the
- search.
-
- AND | OR Determines how multiple criteria are to be handled. See
- QuickFile docs for full details.
-
- See the NewSearch command for details of the remaining parameters.
-
- Results
- None
-
- Return codes
- 10 Unknown field or operator
- 20 Insufficient parameters or first parameter is not AND or OR
-
- Example
- /* select records where surname is brown or smith */
- "newsearch surname equal brown"
- "addsearch or surname equal smith"
- "dosearch"
-
- ============= CloseWin ===============
-
- CloseWin
-
- Closes the current window and file. You cannot close the last window with
- an ARexx command. The first window in QuickFiles internal list becomes the
- current window,
-
- Results
- None
-
- Return codes
- 5 You tried to close the last window.
-
- Example
- "closewin"
-
- ============== ClrRec ====================
-
- ClrRec
-
- Clears all fields in the current record. Use this to clear all fields
- before setting up the values for a new record
-
- Results
- None
-
- Return codes
- None
-
- Example
- "ClrRec"
- "putfield surname Brown"
- "putfield firstname John"
- "putfield address '23 George Street'"
- "insrec"
-
- ============== CycleToString ================
-
- CycleToString field string
-
- Finds the string corresponding to a string number for a cycle field. The
- cycle field value is not changed.
-
- Results
- String from the cycle field.
-
- Return codes
- 5 String number out of range for cycle field
- 10 Unknown field name or not a cycle field
- 20 Parameter missing
-
- Example
- given a cycle field called Status with "Active,Pending,Cancelled"
-
- "stringtocycle Status 2"
- say result /* ==> Cancelled */
-
- ============== DelRec ================
-
- DelRec
-
- Deletes the current record. The next record becomes the new current
- record.
-
- Results
- None
-
- Return codes
- 5 There are no records in the file.
-
- Example
- "getfield expirydate"
- if result < today then
- "delrec"
-
- ============== DoSearch ============
-
- DoSearch
-
- Searches through the data base and selects records matching the search
- criteria. The criteria are established using the NewSearch and AddSearch
- commands.
-
- It places the matching records in an index named SELECTED. It does not
- change the current index.
-
- Results
- RESULT contains the number of matching
-
- Return codes
- None
-
- Example
- "newsearch surname equal brown"
- "addsearch or surname equal smith"
- "dosearch"
- "setindex selected"
-
- ================ FreeIndex ==============
-
- FreeIndex
-
- Discards the current index and frees the storage used. Only temporary
- indexes, ie those named SORTED and SELECTED, can be freed.
-
- Results
- None
-
- Return codes
- 10 Not a temporary index
-
- Example
- "setindex selected"
- "freeindex"
-
- ================ FreeView =================
-
- FreeView
-
- Discards the current view from memory and frees associated storage. The
- first view in the loaded list becomes the current view. The display is
- redrawn. You must keep at least one view. It does not affect the disk
- file containing the view.
-
- Result
- None
-
- Return codes
- 5 You tried to free the last view
-
- Example
- "setview mylist.view"
- "freeview"
-
- ================ GetField =================
-
- GetField field
-
- Returns value of field from the current record
-
- Result
- Field value is placed in RESULT.
-
- Return Codes
- 10 Field requested does not exist
- 20 Field name omitted
-
- Example
- "goto Smith"
- "getfield surname"
- say "Found name" result * Displays==> Found name Smith */
-
- ============= GetRec =============
-
- GetRrec stem
-
- Returns values for all fields from the current record in compound
- variables in the form of stem.fieldname where fieldname is the field name
- from the file definition (not always the title in the view).
-
- You cannot use this if your field names contain spaces; use GETFIELD
- instead.
-
- Results
- stem.fieldname variables updated.
-
- Return codes
- 20 Syntax error. stem not provided.
-
- Example
- "next"
- "getrec val"
- say val.firstname val.surname
-
- =========== GoTo ===========
-
- GoTo value1 [value2...]
-
- Sets the current position to the first record with the current key
- matching the specified values. Value1 is the value for index field 1 and
- Value2 is the value for index field 2 etc.
-
- QuickFile does not tell you if the requested record was not found. It will
- happily position on the next record. You must compare the record with the
- requested key values to check if they were found.
-
- Result
- None
-
- Return Codes
- 5 End of file encountered. Requested key higher than any record.
- 10 More values specified than index fields
-
- Example
- "goto Brown John"
- "getrec val"
- if val.surname ~= "Brown" | val.firstname ~= "John" then
- say "Record not found"
-
- ============ InsRec ================
-
- InsRrec
-
- Adds a new record to the file. You use PUTFIELD to set the field values
- before issuing INSREC. Any fields not updated with PUTFIELD will retain
- the values from the previous record. Use CLRREC to clear all values
- before setting up your new record.
-
- Results
- None
-
- Return codes
- 10 Error occurred. Probably duplicate key.
-
- Examaple
- "ClrRec" /* omit this to use values from previous record */
- "putfield surname Brown"
- "putfield firstname John"
- "putfield address '23 George Street'"
- "insrec"
-
- =================== LoadView ==============
-
- LoadView path
-
- Loads the named view. The full name including extension must be specified.
- This does not change the display. Use the SetView command to change the
- current view.
-
- Result
- None
-
- Return codes
- 10 File not found
- 10 path name not specified
-
- Example
- "loadview df0:QuickFile/Example1/Product.view"
-
- =================== NewSearch =============
-
- NewSearch fieldname operator value1 [value2]
-
- Replaces any existing search criteria with a new one. Use the AddSearch
- command to add additional criteria, if required, and use the DoSearch
- command to start the actual search.
-
- operator The search operator. One of the following:
- like
- equal
- between
- notlike
- notequal
- sounds
-
- value1 The value to be used in the search
-
- value2 The second value required for the between operator. Can also
- be used for others. See QuickFile docs for more details.
-
- Results
- None
-
- Return codes
- 10 Unknown field or operator
- 20 Insufficient parameters
-
- Example
- /* find all current memberships that expire in March */
- "newsearch status equal current"
- "addsearch and 'expiry date' between 01-mar-95 31-mar-95"
- "dosearch"
-
- ================== Next ================
-
- Next [n]
-
- Moves n records forward or backward through the file. If n is omitted 1 is
- assumed. If the resulting position is outside the range of the file, the
- position will be the first or last record. n can be positive or negative.
-
- Result
- None.
-
- Return codes
- 5 No more records. Positioned at first or last record
-
- Example
- "Next -9999" /* move to start of file */
- "Next" /* move to second record */
-
- ============ NumRecs ===============
-
- NumRecs
-
- Returns number of records in the current index. If 'Selected' is the
- current index, this will be the number of selected records.
-
- Result
- Number of records in RESULT
-
- Return codes
- 10 No file open
-
- Example
- "SetIndex name"
- say result /* ==> 253 */
- "SetIndex selected"
- "NumRecs"
- say result /* ==> 16 */
-
- ============ OpenFile ===============
-
- OpenFile pathname
-
- Opens a new file in the current window. Closes the existing file, if any.
- To open an additional file, issue the OPENWINDOW command first to obtain a
- new window.
-
- Result
- None
-
- Return codes
- 10 The file could not be opened. NB Any previous file will have been
- closed.
- 20 pathname not specified
-
- Example
- "openfile 'ram disk:Membership'" /* care with spaces in path names */
-
- ================== OpenWin ===============
-
- OpenWin
-
- Opens a new window which becomes the current window. It will have no open
- file. Until a file is opened, the only commands that can be issued are
- OpenFile, CloseWin.
-
- Result
- None
-
- Return Codes
- 10 The window could not be opened
-
- Example
- pull filename
- "openwin"
- "openfile '"filename"'" /* quotes in case filename contains spaces */
-
- =========== PutField ==============
-
- PutField field value
-
- Sets the contents of field for the current record to value. The change
- will not take effect until you issue the UPDREC command. value must be
- consistent with the field's type.
-
- Result
- None
-
- Return codes
- 5 The value is inconsistent with the field type. The field is not
- updated
- 10 The field does not exist
- 20 Either field or value were omitted
-
- Example
- "next"
- newdate = "31-Mar-1996"
- "putfield 'expiry date'" newdate
- "updrec"
-
- =============== Query =================
-
- Query {FIELD | INDEX} stem [name]
-
- Obtains details about the current file.
-
- stem A stem variable to receive the details
-
- name An optional name of an object to be queried. If omitted, a summary
- of all objects of the requested type are returned.
-
- Results
-
- FIELD without name
- Returns the number of fields in stem.0 and the field names in
- stem.1 to stem.n where n is the number of fields.
-
- FIELD with name
- Returns field type in stem.type and the maximum length in
- stem.length. Name is a field name
-
- INDEX without name
- Returns the number of indexes in stem.0 and the index names
- in stem.1 to stem.n
-
- INDEX with name
- Returns the number of index fields in stem.0 in the field names in
- stem.1 to stem.n. Name is an index name.
-
- Return codes
- 10 Requested name does not exist
- 15 Syntax error. Either a required field was omitted or type was not
- FIELD or INDEX.
-
- Example
- "query field fld"
- do i = 1 to fld.0 /* displays all field names */
- say fld.i
- end
-
- ============== Refresh =============
-
- Refresh
-
- Redraws the screen display. This should not be required in a macro, but
- will be required if you want to update the display to reflect changes
- made from an external script.
-
- Result
- None
-
- Return codes
- None
-
- Example
- "refresh"
-
- ============== Report ===============
-
- Report count [target [title]]
-
- Produces the report defined for the current view. Writes 'count' records
- starting at the current record. The parameters are positional so 'title'
- cannot be specified without 'target'.
-
- count Number of records to process. Specify -1 for all.
-
- target Specify 'printer' to write report to the printer, otherwise the
- report is written to the screen.
-
- title Up to 50 characters to be used instead of the title defined for
- the report. Don't forget the extra quotes.
-
- Note that the report definition is not changed.
-
- Result
- None
-
- Return codes
- 10 No report has been defined for the current view.
- 15 Could not allocate memory.
-
- Example
- "report -1 printer 'Report Title over-ride'" /* note quotes */
-
- "report 10 screen"
-
- ============== ReqChoice ============
-
- ReqChoice line1 [line2]
-
- Displays a requester that displays two lines of text with OK and CANCEL
- buttons. Don't forget the extra set of quotes.
-
- Result
- None
-
- Return codes
- 0 User chose OK.
- 5 User chose CANCEL.
- 20 No message text specified
-
- Example
- "reqchoice 'Delete requested' 'Are you sure'"
- if rc = 0 then
- "delrec"
- else
- say "Delete cancelled"
-
- ============== ReqMsg =============
-
- ReqMsg message
-
- Displays the message in a requester. The message must be enclosed in
- quotes if it is more than one word.
-
- Result
- None
-
- Return codes
- 20 No message specified
-
- Example
- "ReqMsg 'This message from ARexx script'"
-
- ============== ReqString ============
-
- ReqString default [title]
-
- Displays a requester with a string gadget to obtain input from the
- keyboard.
-
- default The default value to be placed in the string gadget. Specify
- '' if no default
-
- title The title to be displayed in the requester window.
-
- Result
- RESULT will contain the users input string
-
- Return codes
- 0 User pressed OK
- 5 User pressed CANCEL
- 20 No message specified
-
- Example
- "reqstring '' 'Please enter your name'"
- if rc = 0 then
- name = result
-
- ============== SaveFile ==============
-
- SaveFile
-
- Writes any updates to disk, if any changes have been made.
-
- Result
- None
-
- Return codes
- None
-
- Example
- "savefile"
-
- ============== SetFile ===============
-
- SetFile [filename]
-
- Selects window containing filename as the current window or returns
- current file name if 'filename' is not specified.
-
- The file must have been opened previously. 'Filename' is the file name
- part only, not including disk and directory names.
-
- Results
- Current file name if issued without filename, otherwise none.
-
- Return code
- 5 Unknown file name
-
- Example
- "setfile"
- say result
-
- "setfile Images"
-
- ============= SetIndex =====================
-
- SetIndex [indexname]
-
- Makes indexname the current index. Specify a name as SORTED to use the
- last sort sequence and SELECTED to use the last selection.
-
- Returns name of the current index if issued without 'indexname'.
-
- Results
- Name of current index if issued without name, otherwise none.
-
- Return codes
- 5 Could not find index
-
- Example
- "setindex sorted"
-
- ==================== SetView =================
-
- SetView [viewname]
-
- Makes the named view the current view and redraws the display using the
- new view. The viewname must include the extension, if any.
-
- If 'viewname' is not specified, returns the name of the current view.
-
- Warning: If used from a macro, this may cause the window to be redrawn
- several times in quick succession after the macro completes. This happens
- because QuickFile does not respond to Intuition's newsize messages while
- the macro is running and several may be queued up when the macro
- completes. This does not happen if it is used from the shell or another
- program.
-
- Result
- Name of the current view if issued without 'viewname', otherwise none.
-
- Return codes
- 5 Could not find view
-
- Example
- "setview namelist.view"
-
- ==================== Sort ===================
-
- Sort field {A | D} [field {A | D} ] ...
-
- Creates a new index named SORTED in the specified sequence and makes
- 'sorted the current index.
-
- field The field name to sort over
-
- order A for ascending, D for descending
-
- Both field and order must be specified for each sort field. You can switch
- between indexes, including SORTED and SELECTED using SETINDEX.
-
- Result
- None
-
- Return codes
- 10 One of the sort fields was not known.
- 20 Either no parameters specified or there was not an even number
- of parameters
-
- Example
- "sort country a surname a firstname a"
-
- =========== StringToCycle ==============
-
- StringToCycle field string
-
- Converts a string to a cycle field string number. The numbering starts
- at zero. The cycle field value is not changed.
-
- Results
- Cycle field string number.
-
- Return codes
- 5 String not found in cycle field
- 10 Unknown field name or not a cycle field
- 20 Parameter missing
-
- Example
- given a cycle field called Status with "Active,Pending,Cancelled"
-
- "stringtocycle Status 'cancelled'"
- say result /* ==> 2 */
-
- =========== UpdRec ==============
-
- UpdRec
-
- Commits an updated record to the file. The update is not necessarily
- written back to disk at this point.
-
- Results
- None
-
- Return codes
- 10 Internal error occurred. Possibly a duplicate key occurred
-
- Example
- "putfield ExpiryDate 31-Mar-95"
- "updrec"
-
- ========= WinToFront ============
-
- WinToFront
-
- Moves the current window to the front of the display.
-
- Results
- None
-
- Return codes
- None
-
- Example
- "wintofront"
-
-