Differences

This shows you the differences between two versions of the page.

--- arev:arev_reference_manual:catalyst [2023/09/27 13:04] – created bshumsky
+++ arev:arev_reference_manual:catalyst [Unknown date] (current) – external edit (Unknown date) 127.0.0.1
@@ Line 1: / Line 1: @@
+====== CATALYST ======
+The subroutine CATALYST processes all Advanced Revelation code and command operations.
+**CATALYST (code,  comnand)**
+Using CATALYST
+Use of CATALYST requires knowledge of specific code and command operations. Each operation is different, but use of CATALYST itself is quite straightforward.
+For more information on codes and commands, see "Using Codes and Commands" in //Designing an Application// in the main system documentation.
+Code and command operations are a kind of shorthand: most simply call other Advanced Revelation tools. CATALYST provides a uniform interface to these tools. Use CATALYST in WBASIC programming to access such standard system-provided functions as window or popup processes.
+In addition to the CATALYST parameters //code// and //command,// there are also subcodes, which are modifications of the code operations. Subcodes can be either code-dependent or code-independent. For example, the code X has a subcode C (clear screen). This subcode applies only to code X. But the code-independent subcode R applies to all code and command operations.
+Code-dependent subcodes are documented below, directly under the relevant code description. Code-independent subcodes, which can apply to all codes, are documented following the section on code descriptions.
+Arguments for //command// supply whatever data is needed to execute the operation specified in //code//. Commands can range from null to complex, depending upon the code or operation involved.
+^Code and Command^Code Use^
+|I|Returns date, time, time & date, AREV serial #.|
+|@|Executes a captured keystroke set.|
+|{|Evaluates a symbolic field in the current dictionary.|
+|A|Returns to the last anchored menu.|
+|B|Uses a Btree index to look up the record key for known value.|
+|C|Compiles and executes R/BASIC source code.|
+|E|Executes a TCL command.|
+|F|Executes a function key.|
+|H|Executes one of several help-related processes.|
+|K|Executes a series of keystrokes.|
+|M|Displays a menu.|
+|O|Opens a data file within a window.|
+|P|Displays a popup.|
+|S|Calls a cataloged R/BASIC subroutine.|
+|V|Displays a popup of indexed field values.|
+|W|Displays a window.|
+|X|Performs a TCL command.|
+Use the ! code when you want to return the date, time, time and date, or the Advanced Revelation serial number.
+==== Codes and Commands ====
+=== "DATE", "TIMEDATE", "TIME", "SERIAL" ===
+<code>
+CATALYST("!","DATE")
+CATALYST("!","TTh1EDATE")
+CATALYST("!","TTh1E")
+CATALYST("!","SERIAL")
+</code>
+All return values are returned in @ANS (and therefore to the prompt, if called from within a window).
+=== @ ===
+Use the @ code when you want to execute a captured keystroke set.
+^Code^Command^Example^
+|@|capture_record|CATALYST("@","CAPTURE_RECORD")|
+An argument for //capture_record// is required and must be the name of the record in the CAPTURED file that is to be executed.
+=== { ===
+Use the { code to evaluate a field in the current dictionary. This code will run any R/BASIC code in the specified dictionary record and return the result in @ANS.
+^Code^Command^Example^
+|{|dict_record|CATALYST("{","INV_TOTAL")|
+The argument for //dict_record//// //must be a record in the current dictionary. The R/BASIC routine CALCULATE puts the result in @ANS.
+The dictionary must be opened to the system variable @DICT during this code and command procedure, and a file record must be in @RECORD.
+=== A ===
+Use the **A** code to return to the last anchored menu, skipping intermediate menus.
+^Code^Command^Example^
+|A|none|CATALYST("A","")|
+No command is processed for this code.
+=== B ===
+Use the **B** code to use a Btree index to look up the record key for a known data value. This function displays a Shared Index Information popup of the indexed field(s) specified in //command// and searches the Btree index, returning a single selection popup (configurable) of the record keys and display fields. Any user selections from the popup are returned in@ANS.
+^Code^Command^Example^
+|B|four_part|CATALYST("B","INV*DT*ID1,ID2,ID3*MULTI")|
+There must be a four-part argument for //command//, where parts are separated from the other by an asterisk. The structure of this parameter is:
+file*indexed_field*display_field*mode
+where //file// is the name of an indexed file, //indexed_field// is the name of one or more comma-delimited fields to be searched in the specified file, //display_field// (optional) is the name of one or more comma-delimited field names that will be displayed in the popup that results from the search, and //mode// is either a literal (KEY or MULTI) or null (single selection). KEY returns keys in a browse list, while MULTI returns keys that are @VM-delimited.
+The example above opens the INV file, asks the user for one or more dates, searches the index for those dates, and then displays the results of the search in a 3-column multiple selection popup in which each column displays data from its respective display field, and where DT data is not included in the display.
+=== C ===
+Use the **C** code to compile and execute the R'BASIC source code specified in //command//. Separate lines of source code with an "&" (ampersand). Total code may extend to 34K for DOS and 64K under OS/2.
+^Code^Command^Example^
+|C|source|CATALYST("C", "@ANS= SUM({AMOUNT})")|
+|CV|object|CATALYST("CV", object_record)|
+If you use the V subcode, the argument for //command// may be compiled object code. For example, the command SUM({AMOUNT}) will sum the multivalued field AMOUNT and return the total in @ANS.
+=== D ===
+The **D** code executes a RETURN.
+=== E ===
+Use the **E** code to execute the specified TCL command.
+^Code^Command^Example^
+|E|TCL_command|CATALYST("E","RENAMEFILE BP APP_BP")|
+The argument for //command// must be a valid TCL command. No active list ofrecords will be available to that command. CATALYST runs the RBASIC EXECUTE statement in //command//. See the **X**code below for more information.
+=== F ===
+Use the **F** code to execute a function key.
+^Code^Command^Example^
+|F|function_key|CATALYST("F", "F2")|
+Arguments for //function_key// are codes to stand for the various function keys. Examples: Fl is [Fl], SFl is [Shift-Fl], CFl is [Ctrl-Fl], and AFl is [Alt-Fl].
+=== H ===
+Use the series of H codes to display and process help. Each subcode modifies the basic help display process.
+The **H** codes and commands are intended to be run within window processes. Many cannot be run outside a window environment because required system variables are not available or have not been initialized.
+Arguments for //command// for the H series of codes depend upon the subcode. Without a subcode, the argument must be a number. That number is concatenated by CATALYST to the string "AW*template_name*" to make a valid record key for access to the SYS.HELP or HELP file. //Template_name// is derived from the current window (the AREY.COMMON variable TEMPLATE).
+**H** Use the H code to display help that is stored in the SYS.HELP or the HELP file. The value of //command// is a number that is placed at the end of the record key. A full record key has the format: //AW*template_name*number.//
+#    Append a "#" (pound sign) to any of the **H** codes to protect the help message from editing.
+**HC** Use the **C** subcode to display several help messages as one. The record keys to the help records are specified in //command// and are separated by "+". An optional title may be specified by including a comma, "," followed by the title. For example:
+record_keyl+record_key2,title
+The help message displayed is always protected.
+The records are read from HELP first, and, if not there, from SYS.HELP. If the record does not exist in either location the record key is included in the help message.
+The text of each help message is separated by a double horizontal line.
+**HD** Use a **D** to display help from the //description// field in a dictionary record. An argument for //command// is not necessary, in which case the current prompt name (field 2 of the AREY.COMMON variable SI) is used as the key to the diction ary record. In either case, it is field 14 of the dictionary record that is displayed.
+Prior to an **HD** CATALYST call, the dictionary file must have been opened to SRC.DICT.
+**HE** Use an **E** to explicitly allow editing of a help message. Other wise, this code is the same as **H**.
+**HF** Use an **F** to read the help message from the file and/or key and/or field specified in //command//. Contents of //command// is a string, with commas separating //filename// from //record_key// and //fromfield_number// within //record_key//. Unless you set protection (with a "#" subcode), a user can edit this message.
+Use the F subcode to read a record from HELP, SYS.HELP, or another file, or to read a single field (for example, field 14, the description field, from a dictionary record). There are three ways to specify the argument for //command//to reflect those options:
+  * filename, record key, field number filename, record-key
+  * record_key -
+The following command displays the contents of field 4 of the record SPECIAL_RECORD from the user-supplied help file SPECIAL_HELP:
+CATALYST("HF", "SPECIAL_HELP, SPECIAL_RECORD, 4")
+**HFT** Use an **FT** subcode to display a help message from the SYS.HELP file. When the [F2] key is pressed while reading that help message, the user sees a browse list ofrelated topics. The initial help message is a record key in SYS.HELP.
+The comma-delimited second part of the argument can also be a record in SYS.HELP, but one in which each field is the name of another record key in SYS.HELP. That record provides the list of keys that make up the browse list.
+As shown in the code example below, instead of passing the key of a list record as the comma-delimited second part of the HFT argument, you may simply pass the @FM-delimited record keys as the comma-delimited second part of the HFT argument.
+CATALYST("HFT","INV_HLP,ENT_HLP":@FM:"TAX_HLP"}
+This command displays the contents of a help record in the SYS.HELP file called INV_HLP, then makes available a browse list of related help records: ENT_HLP and TA.X_HLP.
+The message window is sized in accordance with the primary message specified in //command//. This means that the window will be no larger for additional messages from the browse list than for that primary message. Try to ensure that the primary message provides a reasonable window size.
+**HFW** Use an **FW** subcode to substitute the current window prompt literal (field 5 of the AREV.COMMON variable W(W.CNT)) for the default help window title. This forces the title of the help display to read "Detail Help for...[the current window prompt literal]".
+**HL** Use an **L** subcode to display the literal help message specified in //command//.
+**HM** Use an **M** subcode to display a help message and request a response. The response is returned in @ANS by this routine. //Command// is either literal text or a system message stored in MESSAGES or SYS.MESSAGES, referred to by record key. CATALYST first checks MESSAGES then SYS.MESSAGES for a record key corresponding to command. If no key is found, CATALYST will assume that you have passed literal text.
+The following command will display the "HELP_MESSAGE" record in either system message file.
+CATALYST("HM", "HELP_MESSAGE")
+**HMD** Use an **MD** subcode to display literal text or a message from the MESSAGES file until a key is pressed. See **HM **above.
+**HT** Use a **T** subcode to call MSG and display a message for a fixed duration. //Command// must contain the literal message. Append a"~" (tilde) and a number to the end of your literal string to specify display duration. Otherwise, the system default value (@ENVIRON.SET$) is used (2 seconds by default).
+^Code^Command^Example^
+|H HD HE HF HFT HFW HL HM HT|message_no dict_descrip message_no //"file,key,field"// module_key //"file,key,field"// literal key or literal timed HM|CATALYST("H","SQL_UPDATE")\\ CATALYST("HD","")\\ CATALYST("HE","SQL_UPDATE")\\ CATALYST("HF","ACCT_HELP,CHECKS,6")\\ CATALYST("HFT","F.KEY,F.KEY_LIST")\\ CATALYST("HFW","ACCT_HLP,CHECKS,6")\\ CATALYST("HL","Here is some help:")\\ CATALYST("HM","B213")\\ CATALYST("HT","Here's more help: ~10")|
+=== I ===
+The I code executes a RETURN.
+=== K ===
+Use the K code to execute the series of keystrokes specified in //command//. You can create those keystrokes as you type the contents of //command// simply by toggling the keystroke translator in the Advanced Revelation editor: [Ctrl-] (Ctrl-Hyphen). Instead of performing their defined operations, function and editing keys display literal values. For example, when you press the [F6] function key, the characters "{F6}" appear instead of [F6] taking immediate effect. The K code then translates the literal characters into the actual function of the specified key.
+^Code^Command^Example^
+|K|func_keys|CATALYST("K","{F5}{SPACE}Hey{SPACE}there!")|
+The argument for //func_keys// may be a string generated using the keystroke translator key or one typed directly, where function and editing key names are surrounded by braces ({}).
+=== L ===
+The **L** code is similar to the **S** code in running cataloged subroutines, but lacks access to window registers. Use the //S// code for all access to subroutines.
+=== M ===
+Use the **M** code to display a menu. //Command// contains the name of the menu.
+^Code^Command^Example^
+|M|menu_record|CATALYST("M", "CUST.SERVE")|
+The argument for //menu_record// must be the name of the menu to be displayed. CATALYST looks for the menu first in the MENUS file, then in the SYS.MENUS file.
+=== O ===
+Use the **O** code to open a data file within a window when that data file is other than the default.
+The AREY.COMMON file variable for the data file used within a window is SRC.FILE.
+=== P ===
+Use the **P** code to display a popup. There are several different ways to spend recordname is the record key of the desired popup.
+For example, CATALYST("P", "CUSTOM_POPUPS*TEST") runs the TEST popup from the CUSTOM_POPUPS file.
+**System variables and Popups:** @ID, @FILE and @VOLUME produce //single-selection// popups, while @IDS, @FILES, and @VOLUMES produce //multiple selection// popups.
+For @ID, @FILE, and @VOLUME, you can set the display size and location of the popup. Use a literal string "x:y:z" //after// the variable name, where x is the width of the popup display, y is the starting column, and z is the starting row.
+For example, CATALYST("P", "@FILE:15:20:5") would display a list of attached files in a popup 15 characters wide, starting at column 20 and row 5.
+@ID and @IDS require the AREY.COMMON variable SRC.FILE to contain a datafile file variable.
+**Window registers with Popups:** You can use the @REGISTERn option to dynamically provide data to a prompt by altering the data in an existing record or by replacing at will the file that provides the popup data.
+You must place the following information into one or more window registers:
+record_structure:char(247):mode_info:char(247):filename
+where record_structure is a valid popup record, mode_info is data for the fourth argument of POPUP and filename is the third argument of POPUP. This data is dependent on the mode that has been chosen for the popup (table, row, or field).
+Mode_info and filename must be delimited from the popup record by a CHAR(247).
+You may also use the @REGISTERn option to change the input filename and/or record keys for a system popup.
+=== S ===
+Use an S code to call a cataloged R/BASIC subroutine.
+^Code^Command^Example^
+|S|subroutine|CATALYST("S","USER_SUB,10")\\ CATALYST("S", "USER_SUB,<1>")|
+An argument for command must contain the name of a catalogued subroutine. In addition, if arguments are to be passed to the called subroutine, they must be separated from the subroutine name by a comma, but the entire argument must be passed as a literal. For example, the code
+CATALYST("S","USER_SUB,10")
+will invoke the system subroutine USER_SUB with an argument of 10.
+You can only pass one argument using this syntax, and that argument cannot contain a comma. If your routine presumes multiple parameters, use a different delimiter (such as an asterisk), and code your subroutine logic like this:
+<code>
+SUBROUTINE SAMPLE(in_value)
+CONVERT "*" TO @FM IN in_value
+argl = in_value<l>
+arg2 = in_value<2>
+arg3 = in_value<3>
+</code>
+See the discussion of the command for the B code for an example of when CATALYST uses this type of logic.
+The argument can be passed as a window register number, which is specified as <n>, where n is the window register number. From within a window environment, the following code will provide the argument to USER_SUB from a window register:
+CATALYST("S", "USER_SUB,<l>")
+=== V ===
+Use a V code to display a popup of the indexed field values specified in command. Any user selections will be returned in @ANS.
+^Code^Command^Example^
+|V|"file,field,sel"|CATALYST("V'',"SAMPLE_INVOICES,DATE,M")|
+The argument for command must be a string of comma-delimited values of the structure:
+filename, fieldname, select
+where filename is an indexed file, fieldname is an indexed field, and select is either
+"M" (=multiple selections) or "S" (=single selections).
+The previous example displays a multiple selection of data in the DATE field of the SAMPLE_INVOICES file, returning multiple selections.
+=== W ===
+Use a **W** code to display a window. If you do not include a value in //command//, the system will ask for the name of a window.
+^Code^Command^Example^
+|W|window_name|CATALYST ("W", "CUSTOMER TABLE.ON")|
+Any valid window command line option (such as TABLE.ON) may be included, separated by a space from the window name.
+Window names are looked up in the TEMPLATES file.
+=== X ===
+Use an X code to execute a TCL command. This code invokes the R/BASIC PERFORM command.
+The argument for command must contain a TCL command to be performed. CATALYST runs the R/BASIC PERFORM statement on command. See "PERFORM versus EXECUTE" under the R/BASIC PERFORM command for more details on the difference between the CATALYST E and X codes.
+**XC** Add the **C** subcode to the X code to clear the screen before running the TCL command.
+^Code^Command^Example^
+|X|R/BASIC_command|CATALYST("X","SELECT CUST BY ST")|
+|XC|R/BASIC_command|CATALYST("XC","LIST CUSTOMERS")|
+==== Subcodes ====
+The code parameter can accept several tokens other than the code arguments themselves.
+^Code & Subcode^Command example^
+|S;S;P|PROGRAM1;PROGRAM2;POPUPS*INSURANCE.CODES SIMULATE.INPUT@|
+|@SP|INVOICE.RPT,<1> AUDIT.UPDATE|
+|sSRx|
+Multiple code and command sets can be passed if separated by semicolons. If specifying three sets, for example, pass all three code arguments together, separated by semicolons. Then structure the command argument similarly, using semicolons to //hold// a position even if the code argument doer than the code arguments themselves.
+=== = ===
+Use the"=" subcode to load @DATA, the keyboard buffer, with the contents of@ANS, which can have been set by the !, {, B, HM, P, and V and codes. A CHAR(13) value (carriage return) is automatically added to the string in @ANS.
+=== : ===
+Use the ":" subcode to load @DATA with the contents of @ANS. Unlike the "=" subcode, a carriage return is not added.
+=== M ===
+Use the **M** subcode to keep new values from overwriting the data in @ANS. Instead, new values are merged (appended) to the current data in @ANS. This can be useful in a window environment.
+=== R ===
+Use the **R** subcode to save the screen image before the code and command procedure is executed. This option also restores the screen image after execution of the command.
+=== P ===
+Use the **P** subcode to suspend the playback of captured keystrokes before executing the specified code and command procedure. See "The Code and Command Options" in the "Using Codes and Commands" chapter of //Developing an Application// for informa tion on adding codes and commands to captured keystroke sets.
+=== X ===
+Use the **X** subcode to specify that a post-prompt code and command procedure will run only when data at the prompt changes. You might use the X suffix with the S code and command to run a post-prompt procedure that writes an entry to an audit file each time the value at a prompt changes.