Previous chapter is Chapter 2, "Overview of TOI".
Next chapter is Chapter 4, "Command Reference".
The installation script that installs OmniMark on your system also installs TOI in a sub-directory in the directory where OmniMark is installed. If that directory is on your PATH, you can simply type toi at the command line to start TOI. After TOI displays some copyright, version, and build information, it will display the TOI prompt "TOI>" as shown below:
TOI> _
TOI commands are case-insensitive, free format, and can span multiple lines. An unquoted semicolon begins a comment, which extends to the end of a line. Blank lines are ignored, lines may be of any length, and any number of spaces can separate the tokens of a command.
TOI handles continuation lines differently, depending on whether the commands are given at the prompt or come from a file. When reading commands from a file, the end of a command is indicated by the beginning of the next command, and commands will be processed in the same way as in OmniMark. When accepting commands from a prompt, TOI may execute the leading part of a command before you can enter a continuation line. To prevent this, you must break the command at points that call for additional input.
TOI will execute a command if you hit Enter at a point where a continuation line is optional, but not required. If you will be continuing a command to a new line, you must hit Enter at a point that clearly calls for a continuation of the command. This can be illustrated by a simple example:
DEFINE EXTERNAL COUNTER Function AcceptConnection
(Read-Only COUNTER skListen) As "GW_AcceptConnection"
IN FUNCTION-LIBRARY "~omni/libs/socket.so"
TOI will treat all three lines as a single command when reading from a file, but will treat the first two lines as a command when you enter the three lines at a prompt, because the third line is an optional part of the command syntax. Consequently, the function definition will be incorrect, if entered from a prompt, because the command is executed before the third line can be entered:
TOI> DEFINE EXTERNAL COUNTER Function AcceptConnection + (Read-Only COUNTER skListen) As "GW_AcceptConnection" ERROR: No default function library is declared, cannot omit library name
If you move the token IN from the third line to the second. TOI will recognize the need for a continuation of the command, and will prompt with a + for a continuation line:
TOI> DEFINE EXTERNAL COUNTER Function AcceptConnection + (Read-Only COUNTER skListen) As "GW_AcceptConnection" IN + FUNCTION-LIBRARY "~omni/libs/socket.so" TOI>
You can exit from TOI, by typing "EXIT" or "QUIT" at the "TOI>" prompt.
The commands in TOI fall into two groups. There is a group of commands that correspond to OmniMark commands, and a second group of commands that control the operation of TOI, or cause TOI to carry our some desired actions.
TOI commands have no counterpart in OmniMark. Instead of doing something that you might want to do in OmniMark, they control the action of TOI, or cause TOI to carry out some operation that is not available from OmniMark. The TOI commands are:
OmniMark commands and operators in TOI work in essentially the same way as the corresponding commands operators in OmniMark. TOI supports the following OmniMark commands and operators:
The following TOI session shows how to declare an external function, set the shelf arguments, call the external function, display the return value of the function, and inspect the passed shelf arguments.
Start TOI: change to the directory where TOI is installed, or add the full path name of the TOI directory to your path variable (see your system documentation for details). In either case, type "toi" at the command line to start TOI.
TOI> _
Use the SCRIPT command to produce a log for this TOI session. The name of the log file is "a.log". The quotation marks are optional in the cases where you do not specify the full path name for the log file. Otherwise, they are required as in "C:\work\logs\a.log".
TOI> script a.log Script session to a.log started: Monday December 02 1996 - 09:22am TOI> _
Declare an external function. The OmniMark name of this external function is "ConnectTo", the name of the C function that is invoked when "ConnectTo" is called by OmniMark is "TCP_IP_ConnectTo" which is found in the dynamic link library "C:\socklib.dll". Notice that TOI changes the prompt to "+" to indicate that it needs more input to complete the command before it can execute it.
TOI> declare function-library "C:\socklib.dll" TOI>_ TOI> DEFINE EXTERNAL SWITCH function ConnectTo + Host value STREAM HostName + At value counter PortNum Using modifiable counter SocketFd + as "TCP_IP_ConnectTo" TOI> _
The display function command is used here to confirm the definition for function " ConnectTo". If no specific function name is given, then all functions that are declared during this TOI session are displayed. Notice that the display here is detailed because the default value for details is 5. For a brief display, use the DETAIL command to set the detail level to 1 by typing "DETAIL 1". This detail level remains in effect for the duration of the entire session unless it is changed later on.
TOI> display function ConnectTo
DEFINE EXTERNAL SWITCH FUNCTION ConnectTo
Host VALUE STREAM HostName
At VALUE COUNTER PortNum
Using MODIFIABLE COUNTER SocketFd
AS "TCP_IP_ConnectTo"
TOI> _
The following TOI command shows how to call the OmniMark external function defined above using the SET command. The return value is stored in the specified switch and can be displayed after the function is called. Note how the passed arguments match in order and type with the arguments listed int he function declaration. Note also that if the function fails or if the function is not defined, the switch shelf "status" is not created (declared).
TOI> SET SWITCH status TO ConnectTo Host "ulna" At 1039 Using sk TOI> OUTPUT "Connection established using socket: %d(sk)%n" TOI> OUTPUT "Connection status is:" TOI> DISPLAY SWITCH status ITEM 1 TOI> _
Finally we exit TOI. Note that the scripting to the file "a.log" automatically stops upon exit from TOI. If you were not exiting, you could still turn the scripting off by typing "SCRIPT OFF" at the "TOI> prompt.
TOI> exit Script session ended: Monday December 02 1996 - 09:27am
TOI can create C code for the External Function API directly from external function declarations or Opaque data declarations.
The generated code is designed to be used with a set of functions (in files omxfhelp.c and omxfhelp.h) that are supplied with TOI to simplify use of the API by combining more than one API call into a single helper function. If you prefer to use the API directly, you can use code in the files omxfhelp.c and omxfhelp.h as a guide to replacing the helper functions by direct API calls.
The following example contains three commands to create an external counter function from a single OmniMark declaration:
TOI> define external counter function + sum(value counter first, value counter second) + as "AddThem" in function-library "countxfn" TOI> project countxfn Generating export definition file "countxfn.def"... Generating DLL Source code file "countxfn.c"... Generating TOI/OmniMark include file "countxfn.xin"... Generating a sample project make file "countxfn.mki"... Generating a sample TOI Script (tester) file "countxfn.toi"... TOI> quit
The project command produces five files:
The content of each file is listed below.
/*
* countxfn.c - DLL Source code file
*/
#include <stdlib.h>
#include <stdio.h>
#include "omxfapi.h"
#include "omxfhelp.h"
#ifdef dll_export_fun
#undef dll_export_fun
#endif
#define dll_export_fun
/*
* DEFINE EXTERNAL COUNTER FUNCTION sum
* (
* VALUE COUNTER first,
* VALUE COUNTER second
* )
* AS "AddThem"
* IN FUNCTION-LIBRARY "countxfn"
*/
dll_export_fun void
AddThem (OMXF_Environment_type *p_Env)
{
/* Shelf Argument Declarations */
OMXF_CounterShelf_type *p_first;
OMXF_CounterShelf_type *p_second;
/* Shelf-Item Declarations */
OMXF_int first;
OMXF_int second;
/* Failure Indicator Declaration */
OMXF_int fi;
/* Shelf Argument Extraction */
if (! (p_first = OMXF_GetCounterArgumentByPosition (p_Env, 1)))
{
OMXF_SignalExternalFunctionException (p_Env,
"Counter shelf argument first at position 1 is NULL");
return;
}
if (! (p_second = OMXF_GetCounterArgumentByPosition (p_Env, 2)))
{
OMXF_SignalExternalFunctionException (p_Env,
"Counter shelf argument second at position 2 is NULL");
return;
}
/* Extraction of Default Shelf Items */
first = OMXF_GetCounterItemValue (p_first, OMXF_GetDefaultItem (p_first));
if ((fi = OMXF_GetFailureIndicator (p_first)) != OMXF_fi_Success)
{
OMXF_SignalExternalFunctionException (p_Env, HLP_GetFailureMessage (fi));
return;
}
second = OMXF_GetCounterItemValue (p_second,
OMXF_GetDefaultItem (p_second));
if ((fi = OMXF_GetFailureIndicator (p_second)) != OMXF_fi_Success)
{
OMXF_SignalExternalFunctionException (p_Env, HLP_GetFailureMessage (fi));
return;
}
/*
* TODO: add your code here
*/
/* TODO: Return an appropriate Counter value to OM */
OMXF_SetCounterReturnValue (p_Env, (OMXF_int) 1);
if ((fi = OMXF_GetFailureIndicator (p_Env)) != OMXF_fi_Success)
{
OMXF_SignalExternalFunctionException (p_Env, HLP_GetFailureMessage (fi));
return;
}
}
; ; countxfn.def - Export file ; ; ; This export definition file may not be required by your compiler. ; If required, modify this file according to your compiler format. EXPORTS AddThem
# # countxfn.mki - Sample project make file # # WARNING: # Modify this make file according to your compiler/loader options. # Modify the following path names to point to the location of # TOI Support files (omxfapi.h, omxfhelp.c, omxfhelp.h). SUPP_DIR = ../support OMXFAPI_H = $(SUPP_DIR)/omxfapi.h OMXFHELP_H = $(SUPP_DIR)/omxfhelp.h OMXFHELP_C = $(SUPP_DIR)/omxfhelp.c # The following are example options for the SUN OS 4.5 compiler. # Modify these options according to your compiler/loader. CC = cc LINK = cc -o OBJ_SFX = .o DLL_SFX = .so LOAD_LIBS = -ldl LOAD_OPTS = -G CC_OPTS = -g -c -Xc -DDEBUG -I$(SUPP_DIR) OBJ_FILES = countxfn$(OBJ_SFX) omxfhelp$(OBJ_SFX) countxfn$(DLL_SFX): $(OBJ_FILES) $(LINK) countxfn$(DLL_SFX) $(LOAD_OPTS) $(OBJ_FILES) $(LOAD_LIBS) countxfn$(OBJ_SFX): countxfn.c $(OMXFAPI_H) $(OMXFHELP_H) $(CC) $(CC_OPTS) countxfn.c omxfhelp$(OBJ_SFX): $(OMXFHELP_C) $(OMXFAPI_H) $(OMXFHELP_H) $(CC) $(CC_OPTS) $(OMXFHELP_C)
; ; countxfn.toi - Sample TOI Script (tester) file ; INCLUDE "countxfn.xin" OUTPUT "Calling COUNTER function sum...%n" SET COUNTER RetValue.c TO sum ( 1, 1) OUTPUT "RetValue.c = %d(RetValue.c)%n"
;
; countxfn.xin - TOI/OmniMark include file
;
DEFINE EXTERNAL COUNTER FUNCTION sum
(
VALUE COUNTER first,
VALUE COUNTER second
)
AS "AddThem"
IN FUNCTION-LIBRARY "countxfn"
Next chapter is Chapter 4, "Command Reference".
Copyright © OmniMark Technologies Corporation 1988-1999. All rights reserved.
EUM33, release 3, 1997/10/07.