Programming Commands

The syntax for the BASIC command (and its synonym COMPILE) is:

BASIC <filename> {<itemname> {<itemname> <itemname> … } *}

The BASIC command will compile the specified item or items, found in the specified file. Note that if the specified file is anything other than SYSPROCS, the stored procedure will actually be compiled with the name <filename>_<itemname>.

After compilation, an entry in the SYSLISTS table (if the filename is SYSPROCS), or in the DICT of the specified filename, will be created named "*"<itemname>. This item will contain a copy of the output from the BASIC command.

Also note that, although you may RUN your compiled Basic program from any application (through the use of q-pointers), you must compile your routines in the application where the Basic source file is located; an attempt to compile a routine in a different application will generate an error message.

If the filename is anything other than SYSPROCS, then you must use the RUN command to invoke this compiled procedure, or you must CATALOG the procedure if you wish to invoke it directly by its name. If the procedure has been cataloged, you do not need to re-catalog the procedure if you recompile it with the BASIC command again, unless it has been marked as a "GLOBAL" catalog pointer (see the CATALOG command for more information). Globally-cataloged routines require that you re-catalog the procedure if you re-compile it with the BASIC command; if you do not recatalog the routine, when you invoke it by its name only you will run the previously cataloged object code.

During compilation, the CTO compiler converts any “foreign” data/basic syntax into OpenInsight-compatible BASIC+. This often means that the source code that is actually compiled differs from the original users’ source code. The source code that is actually compiled is stored in the SYSLISTS table, with the item name (prefixed with the filename and underscore, unless the source table name is SYSPROCS) as the item id. You may refer to this “intermediate” source code item if you wish, to see how the CTO precompiler altered the code. Alternatively, if you do not wish the CTO compiler to record this intermediate source code, you may create an item named SAVE.CONVERTED in the MD file. Put an “X” in field 1, and a “0” in field 2, to override the CTO compiler’s default behavior. If any errors are encountered during the compilation process, the line number in the original source is displayed, and the line number in the “intermediate” source is displayed (in parenthesis) as well. Any errors that are encountered during the compilation process are both displayed on-screen and recorded in the “*<itemname>” record.

The CTO compiler may occasionally generate spurious errors, most likely due to uncertainty regarding the use of Pick-style format codes. While every attempt is made to determine the proper intent, the use of format variables (as opposed to explicit format codes) may be rejected by the precompiler. You can override this behaviour by editing the item FORMATVARS in the MD. This item should have an “X” in field 1, and then, separately on each line, the variable name that you use as a format variable in your source code. For example, if your source code had the following lines:

FMTVAR = “R#3”

PRINT OUTVAR FMTVAR

FMTVAR2 = “L#10”

PRINT OTHERVAR FMTVAR2

you could update the FORMATVARS entry in the MD so that it contained the following:

X

FMTVAR

FMTVAR2

The syntax for the CATALOG command is:

CATALOG <filename> {<itemname> {<itemname> <itemname> … } *} {(G}

The CATALOG command will record a copy of the compiled code for the specified item<s>. Unlike the BASIC command, the compiled code will be named <itemname> (not <filename>_<itemname>), therefore allowing for the direct invocation of the procedure by its name alone.

The "G" option indicates that this is a GLOBALLY cataloged entry. If this is global catalog entry, you MUST reissue the CATALOG command after you change the source to the basic+ routine; it is not sufficient to just reissue the BASIC command. Invoking the procedure by name will invoke the last CATALOGED version of the routine.

If you do not specify the "G" option, the system will create a LOCAL catalog entry. Local catalog entries do not need to be recataloged when you recompile the source code; the changes to the source code are automatically reflected when you run the procedure by its name alone.

Note also that you MUST catalog any procedures that are used as subroutines in other procedures.

The syntax for the DECATALOG command is:

DECATALOG <filename> {<itemname> {<itemname> <itemname> … } *}

The DECATALOG command will remove the compiled code for the specified item<s>. After the DECATALOG command has been issued, you cannot invoke the specified procedure, either directly or through the RUN command. You must reissue the BASIC command to recompile the procedure if you wish to be able to invoke it through the RUN command.

The syntax for the RUN command is:

RUN <filename> <procedurename>

The RUN command will invoke the specified procedure, as found in the specified file.

The ED line editor allows you to edit or create one or more items in a file. It is invoked with the following syntax:

ED {DICT} <filename> {<itemid> {<itemid> <itemid> …} *} {({T}{N}}

Alternatively, if there is an active "select list" when ED is invoked, the list of items to operate on will be drawn from the select list.

The "T" option instructs the editor to convert any tabs in the item to a space. The "N" option forces the editor to display dictionary items in OpenInsight format, even if they were originally entered in "traditional" format.

If a specified item does not already exist, the "New Item" message will be displayed. In both the "new item" and existing item cases, you will then be placed at the "top" of the item (before field 1), and the editor prompt "." will be displayed.

From the editor prompt, you may move through the item in a variety of ways. The editor tracks your current location; editing and inserting operations (for example, changing some characters in a field) occur on the current line. You may change your location in the item with the following commands:

T - return to the Top (field 1);

B - move to the bottom (the last field of the record);

{G}<n> - move to field number <n>;

U{<n>} - move up <n> lines (<n> defaults to 1 if not specified);

+<n> - move down <n> lines;

-<n> - move up <n> lines;

<cr> - move down one line;

L{<n>} - display and move down <n> lines (<n> defaults to 21 if not specified);

P - display and move down 21 lines;

You may also change your location in the item by searching through the item. The search commands include:

L:<text> - Move to the line that begins with <text>;

F<space><text> - Move to the line that begins with <text>;

L{<n>}<delim><text> - Move to the line that contains <text>. If <n> is specified, search through the next <n> lines for the specified <text>, and display the occurrences (current location moves to the end of the search region);

A - Repeat last search again

The following commands allow you to modify the item starting at the current line:

D{E}{<n>} - Delete the current line, or the current and next <n> lines;

R{U}{<n>}<delim>{<oldtext>}<delim>{<newtext>}{<delim>} - Replace the first occurrence, or all occurrences (if U specified), on the current line or the current and next <n> lines, of the specified <oldtext> with <newtext>. The <delim> character may be any character (other than "U" or a number) that does not occur in the <oldtext> or <newtext>. Leaving out <oldtext> will insert <newtext> at the beginning of the line or lines. Leaving out <newtext> will delete <oldtext> in the line or lines;

R<space><text> - Replaces the current line with the specified <text>;

R - Prompts for the entry of the text to replace the current line;

I<space><text> - Insert the specified <text> after the current line;

I - Prompts for the entry of the text to insert after the current line. The editor remains in "insert" mode until a <cr> is entered on a line by itself;

Please note that if you enter just a single space as the text for a line when in “insert” mode, the editor will convert this into an empty line. This is the only way to generate an empty line in insert mode; if you just press <cr>, you will exit insert mode. If you actually wish to create a line with a single space, you can either use the Replace function after you have finished with Insert mode, or you can enter the space using the control code syntax (^032) discussed below.

Whenever you are modifying, searching or inserting text in a record, you may specify "control characters" using the special syntax "^xxx", where xxx is the 3 digit decimal representation of the character. For example, "^254" would represent a field mark, "^253" would represent a value mark, etc. You may use this special representation when searching, inserting, or eplacing text.

By default, searching and replacing operates in a "case sensitive" mode. You may toggle this behavior by entering the "C" command. When in "case insensitive" mode, searches and replaces will match the specified text regardless of its case.

You may also modify the item using "block" commands. The block commands allow you to specify a region of the item that you wish to effect. You define the block by moving to the first line of the block and entering "<". You then move to the last line of the block and enter ">". If the block only contains one line (the first and last line of the block are the same), you may enter "<>". The following commands operate on these blocks:

DROP - delete the lines within the block;

MOVE - copy the lines from within the block to the current location, and then delete the original block;

COPY - copy the lines from within the block to the current location. The original block is unchanged;

It is sometimes necessary or desirable to combine text from another item with the current item. The following command allows you to extract text from another item and insert it at the current location:

ME{<n>}<delim>{<location>}<delim>{<startingline>} - Merges 1 line, or <n> lines, from the item specified by <location>. <Location> may be just an item name (for an item in the current file), or the filename and itemname, separated by a space. If <location> is omitted, the text is merged from the current item. The text is extracted starting from line <startingline>, or 1 if <startingline> is omitted;

At any time, you may choose to "undo" the last change. You may enter the command "OOPS" or “X” to return the item to the state it was in before your most recent change. You may issue the "OOPS" or “X” command repeatedly to undo successively earlier changes.

It is sometimes convenient, when in the editor, to execute a command (for example, to perform a copy, or edit up an unrelated item, etc.). You may execute any CTO command from within the editor by using the “>” or “$” when at the editor prompt. For example, you may type in “$TIME” or “>TIME” from within the editor to see the current date and time.

When you have finished modifying your item, you may choose to save your changes, save your changes and exit, or discard your changes. The following commands allow you to either save or discard your changes:

FI - Save the changes and exit this item. If there were other items specified when ED was invoked, the next item in the list will be presented for editing;

FIB - Save the changes, exit this item, and compile it. If there were other items specified when ED was invoked, the next item in the list will be presented for editing;

FIBC - Save the changes, exit this item, compile and catalog it. If there were other items specified when ED was invoked, the next item in the list will be presented for editing;

FIC – Save the changes, exit this item, and convert it to an OpenInsight-format dictionary item. Note that this is only applicable if you are editing a new item in the dictionary of a file;

EX - Exit without saving changes. If you have made any changes to the record, you will be prompted to confirm this action. If there were other items specified when ED was invoked, the next item in the list will be presented for editing;

FD{Y} - Delete the record. If Y is not specified in the command, you will be prompted to confirm this action. If there were other items specified when ED was invoked, the next item in the list will be presented for editing;

If you wish to save or discard your changes, and exit the editor, discarding any further items specified when ED was invoked, you may add a "K" to the end of the command (i.e., FIK, EXK, and FDK).

If you wish to save the item you are currently working on, but do not wish to exit the item at this time, you may use the following commands:

FS{O}{<itemname> (<filename><space><itemname>} - Saves the current item without exiting. If <itemname>, or <filename> and <itemname>, is specified, then the current item is written out to the specified new location. If an item with the new name already exists, the save fails unless the "O" option is also specified;

SAVE {{DICT} <filename>} <itemname> - Saves the current item to the specified itemname, in the current file (or in the file <filename> if specified), without exiting. Note that this command always overwrites any existing item with the same name;

Normally, as you proceed through the item, the field number associated with each line is displayed. You may enter "S" at the editor prompt to "toggle" the line number display on and off. Similarly, you may wish to toggle on and off the display of control characters (these are characters that are not normally printable). By default, control characters will not be displayed in a special, person-readable format; however, the "^" command will toggle the control character display mode.

If you wish to display information about the current record, you may enter either of the following commands:

? - displays the current file name, item name, and line number. If this item is part of an active list of items, this also displays the current item count and the total number of items;

S? - displays the size of the current item

Finally, the editor has the ability to save and reissue a sequence of commands. These sequences of commands are saved as a "prestore", and are defined with the following syntax:

P<#><space><cmd>{]<cmd>]<cmd>…}

where <#> is the prestore number you wish to save this as, and <cmd> is the editor command you wish to invoke when this prestore is recalled. Multiple editor commands may be specified in a single prestore by separating them with the ESC character (represented by ] above). To invoke a prestore, enter the following command:

P<#>

where <#> is the prestore number previously used. To delete a previously defined prestore, issue the command:

P<#><space>

FUNCTION RTI_SET_DEBUGGER(MODE {, REPLACEMENT_ROUTINE_NAME})

Call RTI_SET_DEBUGGER to dynamically change the debug mode, and optionally change the name of the debugger replacement routine that is called in “intercept” mode. Set mode to “0” to disable the debugger, “2” to enable the alternate debugger, or “1” (or anything else) to reset to the normal OI debugger. When mode is “2”, you may optionally specify the name of a stored procedure to use as the debugger replacement routine. If no routine is specified, then the debugger replacement routine is unchanged; if the debugger replacement routine is invalid, then the default routine DEBUGGER_REPLACEMENT will be used. Changes to the debug mode will last until the next RTI_SET_DEBUGGER call, or until the user logs out and logs back in.

The return value of the function is the previous debug mode, and the previous debugger replacement routine’s name is returned in the replacement_routine_name parameter.

Example:

Declare Function RTI_SET_DEBUGGER

routineName = “MY_DEBUGGER_CODE”

oldMode = RTI_SET_DEBUGGER(“2”, routineName) ;* oldMode retains the previous debug mode, and routineName is changed to the prior debugger replacement routine name

* … perform actions that require debug mode 2 …

Dummy = RTI_SET_DEBUGGER(oldMode, routineName) ;* reset to prior values to clean up

When using CTO or AREV32, it is now possible to debug your processes using the graphical OpenInsight debugger (as opposed to the character-based alternate debugger that is used by default in CTO and AREV32). You must be using an EngineServer connection (as opposed to the “direct”, local connection specified with “.” in the CTO configuration record (found in SYSENV or the MD table of the application)).

Make sure you’re running the EngineServer on your desktop, in a DOS command box using the java command, and not as a service.

Edit your CTO configuration record (named CTO*<username> in the MD table of the application you’re running in, or just CTO in the MD table, or CTO in the SYSENV table), verifying that field 1 contains your local machine ID (either “127.0.0.1”, or “localhost”, or the actual IP address or name of the local machine), and field 2 contains the port that the EngineServer will be “listening” on (8088 by default) in its first value. The third and fourth values contain the startup and shutdown flags, respectively; set them both to “1”, and save your configuration record.

Your CTO record should now look like this:

Once you have saved your modified CTO record, you can start up CTO or AREV32. You should see a visible OpenEngine (OEngine) start on your desktop.

By default, when CTO or AREV32 starts up, the alternate debugger is automatically enabled. OpenInsight 9.2.1 and above allow you to change this dynamically with the RTI_SET_DEBUGGER command. From TCL in CTO or AREV32, issue the command:

RTI_SET_DEBUGGER “1”

Or from within a stored procedure add the following line:

CALL RTI_SET_DEBUGGER(“1”)

This will re-enable the normal OpenInsight graphical debugger. Now, when you encounter a run-time error, or a DEBUG statement, the OEngine on your desktop will launch the graphical debugger, allowing you to step through your CTO or AREV32 routine.

The following routines are supplied with the CTO to provide compatibility with "traditional" multivalue systems. Developers will not necessarily need to be familiar with these routines, as the BASIC compiler will normally convert traditional multivalue BASIC to OpenInsight's BASIC+; however, they are documented here should developers wish to work on post-converted code.

SUBROUTINE CURSOR_SELECTVAR_SWAP(<cursornumber>,<selectvar>,<direction>)

- Transfers the contents of the select list stored in the specified cursor into the specified select variable (if <direction> is null or 0), or transfers the contents from the select variable into the specified cursor (if <direction> is 1), or swaps the information in the cursor and select variable (if <direction> is 2)

FUNCTION DO_AT(<xparam>{,<yparam>})

- generate "escape sequences" for cursor positioning and screen control. You may specify a negative value for the <xparam> to generate the following actions:

SUBROUTINE DO_CRT(<output>{,<holdatend>)

- Displays specified <output> at the current cursor position on the CTO screen. Optionally suppresses line feed/carriage return at end of output (<holdatend> set to "1")

SUBROUTINE DO_DATA(<param>)

- Puts <param> into "data stack"; this data will be retrieved by the next call to DO_INPUT or - if the invoking program terminates - the value of the <param> will be taken to be the name of the next program to invoke.

SUBROUTINE DO_ECHO(<state>)

- Turns echoing of characters when typing on (<state> set to "1") or off (<state> set to "0")

SUBROUTINE DO_EXECUTE(<cmd>{<capture?>,<capturevar>{,<return?>,<returnvar>}})

- Invokes the specified <cmd>, either by CALL (if this is a BASIC+ routine), or by using the PROC or PAragraph interpreter, or by using RList (if this is a LIST or SELECT statement). If <capture?> is set to "1", then output from the

command is stored in the <capturevar> variable, rather than displayed on-screen. If <return?> is set to "1", then any return values generated by the command will be stored in the <returnvar> variable.

SUBROUTINE DO_FOOTING(<text>{,<doforce>)

- Sets or resets the "footing" text for all output. You may specify the footing string using the same special characters that are used in a LIST statement's HEADING and FOOTING specification. To disable footing, call DO_FOOTING with <text> set to null. Calling DO_FOOTING with <doforce> set to "1" forces the use of a footing even if <text> is null.

FUNCTION DO_FORMAT(<inparam>,<formatstring>)

- Returns the text in the parameter <inparam> after formatting it according to the specified <formatstring>. DO_FORMAT supports OpenInsight, U2, and "traditional" multivalue format codes.

SUBROUTINE DO_HEADING(<text>{,<doforce>})

- Sets or resets the "footing" text for all output. You may specify the footing string using the same special characters that are used in a LIST statement's HEADING and FOOTING specification. To disable footing, call DO_FOOTING with <text> set to null. Calling DO_FOOTING with <doforce> set to "1" forces the use of a footing even if <text> is null.

SUBROUTINE DO_HEADING(<text>{,<doforce>})

- Sets or resets the "footing" text for all output. You may specify the footing string using the same special characters that are used in a LIST statement's HEADING and FOOTING specification. To disable footing, call DO_FOOTING with <text> set to null. Calling DO_FOOTING with <doforce> set to "1" forces the use of a footing even if <text> is null.

SUBROUTINE DO_HUSH

- Toggles the "output suppress" flag. When in "output suppress" mode, all output from the CTO is discarded rather than displayed.

FUNCTION DO_INPUT({<holdatend>{,<maxlen>{,<posn>{,<origvalue>{,<delay>{,<beepatmax>{,<doraw>}}}}}}})

- Returns input as entered by the user in the CTO, or as extracted from the "data stack" (if present). If <holdatend> is set to "1", then the final cr/lf typed by the user will be suppressed. If <maxlen> is specified, then no more than <maxlen> characters may be entered; if <beepatmax> is set to "1", then the CTO will beep if more than <maxlen> characters are typed. If <posn> is specified, the cursor will first be moved to the specified screen position (NOTE: <posn> should be the result of a DO_AT() call). If <origvalue> is specified, then the text in the <origvalue> parameter will be displayed at the specified <posn>. If <delay> is specified, the CTO will wait no more than <delay> seconds for a response. If <doraw> is set to "1", only a single character will be input; its ASCII code value will be returned to the calling routine.

SUBROUTINE DO_INPUTERR(<outstr>)

- Displays the specified <outstr> at the bottom of the screen. This message remains displayed until another INPUT @ is executed.

SUBROUTINE DO_PAGE({<pgno>})

- This routine ejects the current page, and – if <pgno> is specified – sets the current page to the desired <pgno>.

SUBROUTINE INPUTCLEAR

- Clears the typeahead buffer.

FUNCTION DO_OPEN(<dictname>,<dataname>,<filevar>{,<current_filename>,{real_tablename}}))

- Returns "0" if unable to open the file specified in <dictname>,<dataname>; otherwise, returns "1" and puts the "file handle" to the opened file into <filevar>. Note that DO_OPEN respects any Q-Pointers that may exist in the MD. If the specified file is a Q-pointer, its local filename may be returned in <current_filename>, and the filename in the application where it actually resides may be returned in <real_tablename>.

SUBROUTINE DO_PRINT(<output>{,<holdatend>)

- Displays specified <output> at the current cursor position on the CTO screen or to the currently selected print output device (depending on whether DO_PRINTER_ON has been invoked). Optionally suppresses line feed/carriage return at end of output (<holdatend> set to "1")

SUBROUTINE DO_PRINTER_CLOSE

- Closes any currently-generating print jobs

SUBROUTINE DO_PRINTER_OFF

- Temporarily suspends output to the currently selected print output device. Subsequent DO_PRINT statements will generate output to the CTO screen until DO_PRINTER_ON has been invoked again.

SUBROUTINE DO_PRINTER_ON

- Indicates that subsequent output from DO_PRINT should be directed to the currently selected print output device.

SUBROUTINE DO_PROMPT(<promptchar>{,<rememberflag>})

- Sets the prompt character for the DO_INPUT command to <promptchar>. If <rememberflag> is set to “0”, or not specified, then the specified prompt character is also “saved” for later recall; if <rememberflag> is set to “1”, then the prompt character is actually set to the “saved” value.

FUNCTION DO_READNEXT(<resultvar>{,<svalresult>,<dosval>}{,<selectvar>}})

- Returns 0 if there are no more item IDs in the current select list; otherwise, returns 1, and sets <resultvar> to the next item ID. If <dosval> is set to 1, and the select list is "by-exploding", the <svalresult> will be set to the value number. If <selectvar> is specified, the item ID is read from the specified select variable instead of cursor #0.

SUBROUTINE DO_SELECT(<filevar>, <selectvar>)

- Creates a non-sorted select list from the specified file variable, and stores the select list information in the specified select variable.

SUBROUTINE DO_SHELL(<state>)

- Enables (<state> set to "1") or disables (<state> set to "0") the availability of command-line "shell" commands for the current CTO session.

FUNCTION DO_SYSTEM(<code>)

- Returns the state of the system variables associated with the specified <code> value. Valid options for <code> are:

FUNCTION UCASE(<text>)

- Returns the characters contained in <text> converted to upper-case

FUNCTION LCASE(<text>)

- Returns the characters contained in <text> converted to lower-case

FUNCTION READ_LOCK(<filevar>,<itemid>{,<att#>{,<noitemflag>{,<waitforlock>}}})

- Attempts to read and lock the item specified in <itemid> from the file <filevar>. If <att#> is not specified, the entire record is returned; otherwise, only the specified field is returned. If the desired record is already locked, the function will return (if <waitforlock> is set to "0") or retry the lock each second, beeping to indicate it is currently locked (if <waitforlock> is set to "1", the default). If the desired record is not on file, the function will return a null string and keep the lock set (if <noitemflag> is set to "0", the default) or release the lock (if <noitemflag> is set to "1").

SUBROUTINE RELEASE_LOCK(<filevar>, <itemid>)

- Releases the lock held on item <itemid> in file <filevar>

SUBROUTINE WRITE_LOCK(<filevar>, <itemid>, <itemtext> {, <att#> {, <keeplock> }})

- This routine updates the item named <itemid> in file <filevar> with the text specified in <itemtext>. If <att#> is 0 or not specified, the entire item is written; if <att#> is non-zero, then only the specified attribute in the item is written. If <keeplock> is set to "0" (the default), any locks on this item are released; if <keeplock> is set to "1", the item lock remains in effect.

FUNCTION SET.OPTIONS(<option>,<optionvalue>{,<nodisplay>})

- This function allows a BASIC+ routine to examine or modify current account options. For information on the <option> (either the option name or option number) and <optionvalue> parameters, please see the section SET.OPTIONS in the main manual. As described in that section, use “?” as the <optionvalue> parameter to examine the current state of the specified option. The <nodisplay> parameter would normally be set to “1” to suppress any printed output of the option information; any values are instead returned only as the function result.