Previous chapter is Chapter 1, "About this Manual".
Next chapter is Chapter 3, "Using TOI".
TOI is an interactive tool that helps programmers by
TOI can be used to incrementally develop and run OmniMark code. TOI executes each command as the command is entered. Previously entered commands have already completed their execution. If the current command has a syntax error, the command can be re-entered. If a number of commands are known to be correct, those commands can be stored in a file, and the file can be read with an include command, prior to entering additional commands.
This makes it easy to repeat a test on an external function after modifying and recompiling an external function library. TOI has a set of commands for declaring global shelves, setting the value of shelf items, declaring external functions, calling external functions, inspecting the return values of the called functions, and inspecting the passed shelf arguments. You can interactively inspect the values of shelf items immediately before and after entering any command (like calling an external function) and check for correct results.
The entire TOI source code is supplied for use with a debugger. You can place breakpoints at strategic locations, like the points in the TOI DLL manager dllmgr.c where external functions are loaded and called. Using your debugger and the TOI source code, you can trace or step through source code as you test external function libraries. To take full advantage of your debugger, both TOI and the external function library must be compiled with debugging information. For details, you will need to consult the documentation supplied with your compiler, linker, and debugger. There are also some debugging tips in the comments of the source code file dllmgr.c.
The TOI source code, and supporting files are installed in several subdirectories of your TOI directory (which also contains the TOI executable):
In the TOI main directory, there is a subdirectory (support) that contains files to support easier access to the API, and to support a tracing facility.
The subdirectory also contains the header file omxfapi.h which defines the OmniMark External Function API for your C compiler. Since this file is subject to change, it should not be used as a guide to the API. Instead, you should refer to the "OmniMark External Function Programmer's Guide" for detailed documentation of the API.
The external function API provides functions at a low level for maximum flexibility but, in some circumstances, it may be preferable to combine two or three of the API functions into a single function. The omxfhelp files provide a set of helper functions that combine two or more API calls into single functions. TOI assumes that these helper functions are to be used when you use TOI to generate C code for a function library.
The helper files are:
Documentation for the helper functions. This document assumes that you already know the External Function API, as described in the "OmniMark External Function Programmer's Guide"
This file contains the C source code for the OmniMark External Function Helper API. The Helper API consists of a set of functions that uses the OmniMark External Function API to provide and abstract functionality which is needed or convenient to have when writing C external function libraries. All helper APIs have "HLP_" as a prefix to distinguish them from the OmniMark External Function APIs which have the "OMXF_" prefix. Refer to "omxfhelp.txt" for
Prototypes and definitions for the Helper Functions This file must be included in any C source code that is generated by TOI's PROJECT or TEMPLATE commands.
In some cases you may prefer to use the External Function API directly, instead of using the simplified method. In such cases, you can still use C source code generated by TOI, if you look at the source code of the helper functions as a guide to replacing any helper function by the corresponding direct calls to the API.
Instead of using a debugger, you may simply want to insert temporary calls to functions that provide a trace. For this purpose, a set of trace functions is provided in several files:
Trace functions that report information about the external function. Information include the name of the external function, return type, number of arguments, the type, name, and class of each argument, etc.
Prototypes for the public functions in tracer.c.
Documentation for the OmniMark External Function Tracer API.
TOI can be used to generate C code and supporting files for an external function library, directly from the external function declarations, as illustrated in Section 3.4, "Using TOI to Write External Functions".
You can create the generic part of the C code for external functions by using either the TEMPLATE command (which generates only C code) or the PROJECT command (which also generates supporting files). Both command extract information from your external function declarations to:
The PROJECT command generates source code and supporting files for use in a Visual C++ project. If you are working in another environment, like UNIX, you can edit some of these files for use as supporting files in the other environment.
The PROJECT command extracts information from your external function declarations to generate C source code and supporting files. The command
PROJECT "prjname"
will generate a complete set of files for a Visual C++ project:
The make file contains comments outlining how to modify the file for use with other compilers and platforms. The export definition file is likely to require extensive editing for other compilers and platforms, but some compilers will not require this file.
See the PROJECT (Section 4.20, "PROJECT") and TEMPLATE (Section 4.20, "PROJECT") commands for additional information about generating code.
When you run programs from OmniMark, no results are visible unless your program contains actions (such as an OUTPUT action) to make those results available. For example, you cannot see the value of a string that was in a stream item, if that stream item was only used as temporary storage by the program. TOI, in contrast, permits you to examine the value of any counter, stream, or switch at any time. If you want to know the value of a data item between the execution of two commands, you simply display that value after entering the first command.
OmniMark compiles an entire program before running the program. A syntax error in any rule or action will prevent the program from running. In contrast, TOI executes each command when the command is entered. A syntax error in that command will prevent the execution of that command, but the previous commands will have been completely executed before the erroneous command was entered.
If a TOI command fails because of a syntax error, your working state will be the same as if the command was never entered. All of your previously entered declarations and external function definitions will remain as they were, and all of the existing data will be unchanged.
If a TOI command fails because of an operational error (such as an exception signalled by an external function), then your data may have changed because of operations that were successfully completed prior to the point of failure. However, your declarations and external function definitions will remain unchanged.
The interactive nature of TOI can produce odd results when commands are entered from a file, instead of at the command line. If a file contains three commands, and the second command contains a syntax error. The first and third commands will execute, but the second will not. The third command will produce unexpected results if it requires data that the second command should have produced.
TOI and OmniMark use different methods for managing data, and TOI does not support the full range of OmniMark data structures, nor does TOI have any concept of domains. Consequently, all TOI streams must be attached to buffers before external functions can operate on them. If the streams are not attached to buffers, external functions attempting to operate on those streams will fail when running in TOI.
TOI does not require you to declare shelves before their first use. A shelf can be explicitly declared with a GLOBAL command, or it can be implicitly declared by its first use in a SET, NEW or CLEAR command. The advantage of this, in the interactive TOI environment, is that you can define shelves as needed, on the fly. However, the ability to implicitly declare shelves in SET, NEW and CLEAR commands also requires that shelf names be heralded by their types in every command:
SET COUNTER c1 to 9
You cannot enter a command like
SET c1 to 9
A disadvantage of implicit declarations is that you can create new shelves by misspelling the names of the shelves that you actually want.
TOI supports only a limited range of OmniMark commands, and also supports commands that do not have any counterpart in OmniMark. The OmniMark commands that are supported work in essentially the same way in OmniMark and TOI. The additional TOI commands are used for operations that are not required in OmniMark, such as controlling TOI operation, and generating C source code.
TOI supports a smaller range of expressions than OmniMark. Consequently, the TOI versions of the SET, RESET, OPEN, and REOPEN are more limited than the OmniMark versions.
You can SET or RESET a counter to
You can SET an opaque item to
You can SET a stream item or an external output to
You can OPEN or REOPEN a stream as
You can set a switch item to
TOI and OmniMark use the same external function API, and expect the same failure codes. Consequently, external functions require the same header file (omxfapi.h) and are compiled the same way for use from either TOI or OmniMark. The only difference is that TOI limits stream access to those streams that are attached to buffers.
Next chapter is Chapter 3, "Using TOI".
Copyright © OmniMark Technologies Corporation 1988-1999. All rights reserved.
EUM33, release 3, 1997/10/07.