Previous chapter is Chapter 3, "Using TOI".
This section describes the TOI and OmniMark commands in alphabetical order.
ACTIVATE <name> [KEY <string> | ITEM <number>]
<name> ::= An OmniMark Switch Shelf name
<string> ::= A quoted string giving the key associated with
the desired item
<number> ::= A positive integer specifying the number of
desired shelf item
The ACTIVATE command turns ON the indicated SWITCH shelf item. If no index (KEY or ITEM) is specified, the shelf's default item is used.
ACTIVATE Text-Found ACTIVATE Chapter-has-Illustration Item 2 ACTIVATE Table-header KEY "Chapter-9"
CLEAR <type> <name> <name> ::= An OmniMark Shelf name <type> ::= SWITCH | COUNTER | STREAM | Opaque sub-type
The CLEAR command removes all items from a shelf. The number of items on a cleared shelf is zero. The CLEAR command is not allowed on shelves that have been declared with a fixed size.
If the named shelf has not already been created with a GLOBAL command, the shelf will be created immediately. For additional information, see the GLOBAL command.
The shelf name in a CLEAR command must always be heralded by a type, because the type information will be needed if the shelf did not already exist.
CLEAR COUNTER X CLEAR float_type f
DEACTIVATE <name> [KEY <string> | ITEM <number>]
<name> ::= An OmniMark Switch Shelf name
<string> ::= A quoted string giving the key associated with
the desired item
<number> ::= A positive integer specifying the number of
desired shelf item
The DEACTIVATE command turns OFF the indicated SWITCH shelf item. If no index (KEY or ITEM) is specified, the shelf's default item is used.
DEACTIVATE Text-Found DEACTIVATE Chapter-has-Illustration Item 2 DEACTIVATE Table-header KEY "Chapter-9"
DECLARE FUNCTION-LIBRARY <Library> OR DECLARE OPAQUE <Sub-type> CREATED BY <Creator > <Library> ::= A system-specific library name. <Sub-type>::= An Opaque sub-type name <Creator> ::= A system-specific opaque creator sub-function name.
The DECLARE command Declares a new OPAQUE sub-type or a default dynamic link library. This command behaves exactly is in OmniMark. Refer to the "OmniMark Programmer's Guide" for information on declaring OPAQUE types and declaring default dynamic link library name for external functions that do not explicitly specify one.
DECLARE FUNCTION-LIBRARY "Math.dll" DECLARE FUNCTION-LIBRARY "C:\Lib\Math\bignum.dll" DECLARE FUNCTION-LIBRARY "~lab/lib/gui/dlglib.so" DECLARE OPAQUE Float_type CREATED BY "FloatConstructor"
DEFINE EXTERNAL [<fun-type>] <fun-name>
([<class> <type> <arg-name>]*)
AS <sys-name> [IN FUNCTION-LIBRARY <lib-name>]
<fun-type> ::= SWITCH | COUNTER | STREAM |
SOURCE | OUTPUT | Opaque sub-type
<type> ::= SWITCH | COUNTER | STREAM | Opaque sub-type
<fun-name> ::= An OmniMark function name
< class > ::= VALUE | READ-ONLY | MODIFIABLE
<sys-name> ::= The name of system-specific function that
implements the OmniMark function
<lib-name> ::= The name of system-specific library that
contains the external function
<arg-name> ::= A formal argument name
The DEFINE command allows you to declare external functions and optionally specify in what dynamic link library they are located. You should refer to the "OmniMark Programmer's Guide" for detailed information on how to declare external functions using the DEFINE command. TOI's DEFINE command is practically similar to OmniMark's DEFINE command. TOI supports both the "parenthesized" and "heralded" format.
The DEFINE command declares an OmniMark external function name, describes the function parameters and how they are passed, and specifies the C (system specific name) of the external function and the dynamic library that implements the OmniMark function.
DEFINE EXTERNAL COUNTER Function AcceptConnection (Read-Only COUNTER skListen) As "GW_AcceptConnection" IN FUNCTION-LIBRARY "~omni/libs/socket.so" DEFINE EXTERNAL SWITCH Function MakeConnection ON value COUNTER skClient HOST Modifiable STREAM HostName AT Read-Only COUNTER PortNumber As "GW_MakeConnection" IN FUNCTION-LIBRARY "C:\DLLs\socket.dll" DECLARE FUNCTION-LIBRARY "C:\DLLs\socket.dll" DEFINE EXTERNAL Source Function ReceivePacket Value COUNTER skClient As "GW_ReceivePacket" DECLARE OPAQUE float_type CREATED BY "FloatConstructor" DEFINE EXTERNAL float_type Cosine (Value float_type f) AS "FloatCosine"
DETAIL <number>?
<number> ::= A value from 1 to 9 inclusive that specifies
the level of details
The DETAIL command specifies the level of details in the source code that is generated by the TEMPLATE and PROJECT commands. The default detail value is set to 5 when TOI starts. The detail value remains in effect until the next DETAIL command changes it. The following shows what is produced by the TEMPLATE command and at what details level:
DETAIL ; Displays the current details level DETAIL 1 ; Minimum details DETAIL 2 DETAIL 9 ; Maximum details
DISPLAY <type> [<name>] [KEY <string> | ITEM <number>]
OR
DISPLAY FUNCTION [<name>]
<type> ::= SWITCH | COUNTER | STREAM
<name> ::= An OmniMark Shelf name or an OmniMark
(external) Function name
<string> ::= A quoted string giving the key associated
with the desired item
<number> ::= A positive integer specifying the number of
desired shelf items
The DISPLAY command allows you to display the current values of shelf items and the OmniMark declaration of external functions. The DISPLAY command must always specify the type of the object to be displayed (counter, switch, stream, opaque sub-type, or function). If no index (KEY or ITEM) is specified, then all items of the specified shelf name are displayed. If no shelf name or a function name is specified, then all shelves of the specified type or functions are displayed. The output of the DISPLAY command is controlled by the DETAIL command which specifies how much detail is displayed.
; displays all counter shelves DISPLAY COUNTER ; displays all items of counter shelf Y DISPLAY COUNTER Y ; displays the 2nd item of counter shelf Y DISPLAY COUNTER Y ITEM 2 ; displays the counter item of shelf D whose key is "hello" DISPLAY STREAM D KEY "hello" ; displays the OmniMark declaration of all external functions DISPLAY FUNCTION ; displays the OmniMark declaration of function Beep DISPLAY FUNCTION Beep
DUMP <name> [KEY <string> | ITEM <number>]
<name> ::= An OmniMark Shelf name
<string> ::= A quoted string giving the key associated
with the desired item
<number> ::= A positive integer specifying the number of
desired shelf items
The DUMP command displays the value of a stream shelf item in HEX and ASCII. This command is useful for printing stream items that contain binary data. If no index (KEY or ITEM) is specified, all items on the shelf are printed.
SET STREAM b TO "hello world!" DUMP b 0000: 6865 6c6c 6f20 776f 726c 6421 hello world! DUMP TCP.STREAM DUMP Send_buffer ITEM 2 DUMP EncryptedDailyNotes KEY "Monday"
EXTERNAL FUNCTION <function-name> <function-name> ::= An OmniMark External Function name
EXTERNAL FUNCTION is a shelf that holds the names of external libraries. The name may not exist, because it is possible to declare the function and to assign the external name later. EXTERNAL FUNCTION can be read or modified by the SET command.
DEFINE EXTERNAL FUNCTION OmniF () AS "*" IN FUNCTION-LIBRARY "*" SET STREAM s5 TO EXTERNAL FUNCTION OmniF EXTERNAL FUNCTION OmniF SET EXTERNAL FUNCTION OmniF TO "C_F"
FUNCTION-LIBRARY <function-name> <function-name> ::= An OmniMark External Function name
FUNCTION-LIBRARY is a shelf that holds the names of external libraries. The name may not exist, because it is possible to declare the function and to assign the library later. FUNCTION-LIBRARY can be read or modified by the SET command.
DEFINE EXTERNAL FUNCTION OmniF () AS "*" IN FUNCTION-LIBRARY "*" SET STREAM s6 TO FUNCTION-LIBRARY OF EXTERNAL FUNCTION OmniF SET FUNCTION-LIBRARY OF EXTERNAL FUNCTION OmniF TO "sample.dll"
GLOBAL <type> <name>
GLOBAL <type> <name> VARIABLE
GLOBAL <type> <name> SIZE <number>
<type> ::= SWITCH | COUNTER | STREAM | Opaque sub-type
<name> ::= An OmniMark Shelf name
<number> ::= An integer specifying the size of
the shelf
The GLOBAL command creates a shelf object that is accessible throughout the program. If the keyword VARIABLE is not specified, then the shelf is fixed with a size, given by SIZE <number>. If the SIZE is not explicitly specified, the shelf size is one (i.e. the shelf contains one item) by default.
The interactive TOI environment allows you to define a shelf on the fly, as needed, without using the GLOBAL command. If a SET, RESET, NEW, or CLEAR command operates on a shelf that has not yet been declared by a GLOBAL command, then the shelf will be created immediately as a shelf with variable size. The CLEAR command will create a variable shelf with zero items, the other commands will create a variable shelf with one item.
You may still want to use a GLOBAL command, in order to get a shelf of fixed SIZE.
GLOBAL COUNTER X ;X is a counter shelf with a fixed size of 1 GLOBAL SWITCH Y VARIABLE ;Y is a variable switch shelf with an initial size of 1 GLOBAL STREAM Z FIXED 10 ; Z is a fixed stream shelf with a size of 10 items
HELP
The HELP command displays a summary of TOI's commands.
INCLUDE <file> <file> a system-specific file name.
The INCLUDE command allows batch processing by including a file that has TOI commands. This file is called a TOI script or TOI program. It is a convention to name such a file with ".tin", ".xin" or ".toi" extension, i.e. "myfile.toi", but this is not required. When a TOI script file is included by the INCLUDE command, TOI executes the commands one-by-one as if you have typed them yourself at the keyboard. In particular, the output produced by these commands is displayed on the screen and logged into a log file if scripting is active. This command can be a time-saver if you find your self typing the same commands over and over again. This command is similar in many ways to OmniMark's INCLUDE action.
INCLUDE "GUI.xin" ; quotes are optional here. INCLUDE "C:\OmniMark\EFAPI\UIMS.xin" INCLUDE "~/omni/efapi/ODBC/core.xin"
INDENT <number>?
<number> ::= A positive integer specifying the
level of indentation
The INDENT command specifies the level of indentation in the source code that is generated by the TEMPLATE and PROJECT commands. The default indentation value is set to 3 when TOI starts. The Indentation value remains in effect until the next INDENT command changes it.
INDENT ; displays the current indentation value. INDENT 4 ; sets the indentation value to 4 from this point on.
LENGTH OF <StringExpr> <StringExpr> A literal string or a stream item.
The LENGTH OF operator returns the length of its argument.
SET COUNTER x TO LENGTH OF "hello world" SET STREAM s TO "I Love OmniMark" SET COUNTER y TO LENGTH OF s - 4 DisplayString (s, LENGTH OF s)
LIST <file> <file> a system-specific file name.
The LIST command lists the contents of the specified ASCII file.
LIST "Script.log" ; quotes are optional here. LIST "C:\OmniMark\XOM\test.xom" LIST "/usr/smith/Omni/dlglib.api"
NEW <type> <name> [KEY <string>]
<type> ::= COUNTER | STREAM | SWITCH | Opaque sub-type
<name> ::= An OmniMark Shelf name
<string> ::= An optional quoted string giving the key
associated with the newly-created item.
The NEW command adds a new item to the right side of a shelf. The new value is initialized according to its type: Counters are set to 1, switches are in inactive state, streams are attached to a buffer of zero length, and opaque items are initialized by calling their respective creator sub-function. This command cannot be used on a shelf declared with a fixed size.
If the named shelf has not already been created with a GLOBAL command, the shelf will be created immediately. For additional information, see the GLOBAL command.
The shelf name in a NEW command must always be heralded by a type, because the type information will be needed if the shelf did not already exist.
NEW COUNTER Page-List NEW STREAM TOC KEY "Chapter 1" NEW float_type f
NUMBER OF <type> <name> <type> ::= SWITCH | COUNTER | STREAM | Opaque sub-type <name> ::= An OmniMark Shelf name
The NUMBER OF operator returns the number of items on the indicated shelf.
GLOBAL COUNTER X SIZE 11 SET COUNTER y TO NUMBER OF X NEW STREAM s NEW STREAM s CheckShelfSize (NUMBER OF STREAM s) GLOBAL float_type f size 9 SET COUNTER nFloats TO NUMBER OF f
OUTPUT <FormatString> < FormatString > ::= A format string.
SET COUNTER page to 9 SET STREAM s to "Hello World!" OUTPUT "page = %d(page)%ts = %g(s)%n" SET COUNTER APR to 7 OUTPUT "Annual Percent Return = %%%d(APR)%n"
PROJECT <ProjectName>
<ProjectName> ::= A project name of up to 8 characters
with no extension.
Given a set of OmniMark external function declarations and a project name such as "prj", the "PROJECT" command generates the following set of files:
This file contains the skeleton for a library that contains the external functions. The code for obtaining data from the function arguments is present, along with code to return a function value (if a value is to be returned). The file will compile and run, but it will not do anything useful until you add your own code in the places indicated by the comments.
This file is a makefile for Visual C++, but will serve as an example for use on other systems. Comments in the file tell how to modify the file for use in a typical UNIX system. Different modifications would be required on other systems, and you will probably want to make additional modifications as you develop your onw code.
This file contains a list of all the external function names. It is needed for use with Visual C++, which requires any function to be in an export list before that function can be reached from outside the module that contains the function. Some other compilers and operating systems require a file with the same information, although the format of the file may be considerably different.
This file contains a list of OmniMark external function declarations for all the external functions in the C source file. You can use this file in an OmniMark program to define the functions. You can also use the INCLUDE command in TOI to avoid reentering all the declarations manually when you want to test the external functions in TOI (See Section 4.13, "INCLUDE").
This file contains an example of a TOI script that calls each external function and displays its return value. You can use this file with the INCLUDE command to do a test run on the external function library (See Section 4.13, "INCLUDE"). You can also use the file as a starting point for the code that will use the external function library from OmniMark.
PROJECT "myproj" PROJECT hello2
PROMPT <prompt string> <prompt string> ::= A non-empty quoted string.
The PROMPT command sets TOI's prompt to the specified string.
; change TOI's main prompt to "$" PROMPT "$" ; change TOI's main prompt to "toi>" PROMPT "toi>"
PURGE
The PURGE command re-initializes TOI's data structure to ensure that no results from a partial program execution will appear in a subsequent execution. This command deletes from TOI's memory all shelf and external function declarations. The PURGE command can not be undone.
QUIT
The QUIT command terminates TOI. The word EXIT is an alias to the QUIT command and can be used to terminate TOI as well. If scripting is active (see SCRIPT command), it will be turned off and the log file is closed before TOI terminates.
REMOVE <type> <name> [KEY <string> | ITEM <number>]
<type> ::= SWITCH | COUNTER | STREAM | Opaque sub-type
<name> ::= An OmniMark Shelf name
<string> ::= A quoted string giving the key associated with
the desired item
<number> ::= A positive integer specifying the number of
desired shelf items
The REMOVE command removes one item from the indicated shelf. Removing an item from a shelf which only has one item is the same thing as applying the CLEAR command to it. The REMOVE command is not allowed on shelves that have been declared with a fixed size.
If no index (KEY or ITEM) is specified, the shelf's default item is used.
REMOVE COUNTER X REMOVE COUNTER Y.c ITEM 7 REMOVE STREAM Day KEY "5/24/96" REMOVE float_type f ITEM 2
RESET <name> [KEY <string> | ITEM <number>] TO <value>
<name> ::= An OmniMark Counter Shelf name
<string> ::= A quoted string giving the key associated with
the desired item
<number> ::= A positive integer specifying the number of
desired shelf item
<value> ::= Number | Counter Item |
Counter returning Function
The RESET command sets the value of the indicated COUNTER shelf item to the given value. Counters must be set to integer values. If no index (KEY or ITEM) is specified, the shelf's default item is used.
If the named shelf has not already been created with a GLOBAL command, the shelf will be created immediately. For additional information, see the GLOBAL command.
The shelf name in a RESET command is never heralded by a type, because because only a counter can receive a value from a RESET command.
RESET X TO 123 RESET Y.c ITEM 2 to -1400 RESET Number-of-hours-worked KEY "Monday" to 8 RESET A-1 TO X + 4 * Y.c RESET A-2 ITEM 2 to COUNTER W Key "OmniMark" RESET A-3 to AnyCounterReturningFunction RESET len TO LENGTH OF "I Love OmniMark" RESET items TO NUMBER OF X
SCRIPT <file name> SCRIPT OFF <file name>::= A system-specific file name.
The SCRIPT command allows you to log all interactions with TOI in a log file for later examination or reuse. You start the scripting session by typing the SCRIPT command and providing a name for the script file. From that point onward, all of your keyboard input and TOI's output and error messages are displayed on the screen as well as logged into the script file that you have specified. The scripting will end when you quit TOI or when you type "SCRIPT OFF" at the "TOI>" prompt. This command is especially useful when used in conjunction with TEMPLATE command. The TEMPLATE command generates source code which can be captured in a log file by the SCRIPT command.
Only one script file can be active at one time. Use the keyword OFF in place of a file name to turn off scripting and close the script file. Use the LIST command to examine the script file from within TOI.
SCRIPT "test.log" ; quotes are optional here.
SCRIPT OFF ; turn scripting off and close
; the current script file
SCRIPT "C:\OmniMark\logs\run1.log"
SCRIPT "~/omni/debug/gui_test_1.scr"
LIST test.log
SET <type> <name> [KEY <string> | ITEM <number>] TO <value>
OR
SET EXTERNAL FUNCTION <name> TO <value>
OR
SET FUNCTION-LIBRARY OF EXTERNAL FUNCTION <name> TO <value>
<type> ::= COUNTER | STREAM | SWITCH | Opaque sub-type
<external output function>
<name> ::= An OmniMark Shelf or function name
<string> ::= A quoted string giving the key associated with
the desired item
<number> ::= A positive integer specifying the number of
desired shelf items
<value> ::= A value appropriate to the type being set
The SET command is used to assign a specified value to a shelf item. The value can be a call to an external function with the appropriate type, a literal, or can be obtained from a shelf item of a matching type. In essence, the SET command is overloaded. It declares shelves, calls typed functions, and assigns values to shelf items.
A counter must be set to an integer value, a numeric expression, a counter shelf item, or a counter- returning function. A Stream can only be set to a string literal, a stream shelf item, a stream-returning function, or to a source-returning function. A switch can be set to TRUE, FALSE, a switch shelf item, or to a switch-returning function. An External output function can be "set" to a string literal, a stream shelf item, a stream-returning function, or to a source-returning function.
If the named shelf has not already been created with a GLOBAL command, the shelf will be created immediately. For additional information, see the GLOBAL command.
The shelf name in a SET command must always be heralded by a type, because the type information will be needed if the shelf did not already exist.
SET SWITCH w1 TO FALSE SET SWITCH w1 TO TRUE SET SWITCH w2 TO w1 SET SWITCH w2 TO SomeSwitchReturningFunction () SET COUNTER c1 TO 23 SET COUNTER c1 ITEM 7 TO (-400 * 7) + (23 / 9) SET COUNTER c2 TO c1 - 8 SET COUNTER c3 TO SomeCounterReturningFunction () + 5 SET COUNTER c4 TO LENGTH OF "hello world" SET COUNTER c5 TO NUMBER OF COUNTER c1 SET STREAM s1 KEY "5/24/96" TO "Referent-Stream" SET STREAM s2 TO s1 SET STREAM s3 TO SomeStreamReturningFunction () SET STREAM s4 TO SomeSourceReturningFunction () DECLARE OPAQUE float_type CREATED BY "FloatConstructor" SET float_type f1 SomeFloatTypeReturningFunction () SET float_type f2 TO f1 SET SomeExternalOutputFunction() TO "Monday" SET SomeExternalOutputFunction() TO s1 item 3 SET SomeExternalOutputFunction() TO AStreamReturningFunction() SET SomeExternalOutputFunction() TO ASourceReturningFunction() DEFINE EXTERNAL FUNCTION OmniF () AS "*" IN FUNCTION-LIBRARY "*" SET STREAM s5 TO EXTERNAL FUNCTION OmniF SET STREAM s6 TO FUNCTION-LIBRARY OF EXTERNAL FUNCTION OmniF SET EXTERNAL FUNCTION OmniF TO "C_F" SET FUNCTION-LIBRARY OF EXTERNAL FUNCTION OmniF TO "sample.dll"
SYSTEM <System Command> <System Command> ::= A system command within double quotes.
Executes the specified system command on your target system.
SYSTEM "dir" SYSTEM "date" SYSTEM "mkdir ~oe/newdir" SYSTEM "del *.* /p" SYSTEM "copy c:\work\*.c d:\backup"
TEMPLATE [<name>] <name> ::= An OmniMark (external) Function name
The TEMPLATE command generates a C source code function template from an OmniMark external function declaration. The template C source code uses the OmniMark external function API (omxfapi.h) and a set of convenience (helper) functions (omxfhelp.h) to automate chores commonly found in most external functions. This template C code serves as a starting base that you can build upon by adding your useful code in the appropriate places and in the places indicated by the comments that are embedded within the generated code. It is best to use the TEMPLATE command in conjunction with SCRIPT command to log the generated source code into a file. Alternatively, use the more powerful PROJECT command which writes directly to the files implied by the project name and thus requires no scripting.
If no function name is specified, code is generated for all functions. The output of the TEMPLATE command is controlled by the DETAIL command which specifies how much details are generated, and by the INDENT command which specifies the level of indentation. Please refer to the INDENT and the DETAIL commands for details.
To compile the template code that is generated by the TEMPLATE or PROJECT commands, you must include the "C" header file "omxfapi.h" and the header file "omxfhelp.h" using the C "#INCLUDE" preprocessor directive. You also need to compile the helper library which is found in the file "omxfhelp.c" and link it with the file that contains the template source code.
The PROJECT command is more powerful than the TEMPLATE command and it produces a set of project files that are ready to compile into a dynamic link library with minimum modification.
DEFINE EXTERNAL SWITCH Function MakeConnection ( modifiable COUNTER skClient, value STREAM HostName, value COUNTER PortNumber ) As "GW_MakeConnection" IN FUNCTION-LIBRARY "C:\DLLs\socket.dll" ; Generate template code for function MakeConnection TEMPLATE MakeConnection ; Generate template code for all external functions TEMPLATE
VERSION
The VERSION command displays TOI's version and the OmniMark External Function API version number that TOI was build with.
Copyright © OmniMark Technologies Corporation 1988-1999. All rights reserved.
EUM33, release 3, 1997/10/07.