Interactions between OpenInsight and CTO

To aid in debugging your CTO routines, you may invoke them from the OpenInsight environment. Using the System Monitor (from the Tolls / Advanced OpenInsight menu), type in RUN DO_CTO “<command to run>”. All output will be displayed in the System Monitor window; any requests for input will cause a Message Box to appear.

You may “embed” a CTO screen in an OpenInsight GUI form. OpenInsight currently ships with two forms which have this functionality – CTO_STANDALONE_FORM and CTO_CHILD_FORM. The CTO_STANDALONE form is designed to allow you to launch a CTO session from the main GUI application screen; CTO_CHILD_FORM is designed to allow you to write OpenInsight “MDI” frames that include green screen functionality.

Please note: You must create a record named CTO in the SYSENV table before using the CTO_STANDALONE_FORM. At a minimum, this record must contain the IP address of the OpenInsight system (the system where the OEngineServer is running) in field 1. Failure to create this record may cause unpredictable behaviour.

If you either the CTO_STANDALONE_FORM or the CTO_CHILD_FORM, you may also take advantage of some additional CTO/OpenInsight connectivity routines. These currently include:

FUNCTION CTO_MSG(<PARAMS>)

- This routine opens up a MSG window on your OpenInsight form. The <PARAMS> parameter is identical to the <msgstructure> parameter in the OpenInsight MSG fuction. This function returns the same values as the MSG function.

FUNCTION CTO_POPUP(<DEFN>,<POPUPNAME>)

- This routine opens up a PopUp window on your OpenInsight form. The <DEFN> parameter is identical to the <typeoverride> parameter in the OpenInsight POPUP function. This function returns the same values as the POPUP function.

FUNCTION CTO_RUNWIN(<CMD>,<MODE>)

- This routine executes the specified <CMD> in the underlying Operating System environment. Both <CMD> and <MODE> are passed to the UTILITY function, with the RUNWIN argument. Please see RUNWIN in the OpenInsight help for more details on the <MODE> parameter. This function currently returns 0.

FUNCTION CTO_SET_PRINTER(<CTYPE>,<PARAM1>,<PARAM2>,…<PARAM8>)

- This routine calls OpenInsight’s SET_PRINTER function, passing it any parameters that are specified. This function returns the same values as the SET_PRINTER routine.

FUNCTION CTO_GUI_FUNCTION(<FNAME>,<PARAM1>,<PARAM2>,…<PARAM20>)

- This routine calls any OpenInsight function that requires an “event context”. Specify the name of the function as the <FNAME> parameter, and any required or desired parameters as <PARAM1>, <PARAM2>, etc. This function will return the return value of the specified <FNAME> function.

FUNCTION CTO_SET_PROPERTY(OBJNAME,PROPNAME,PROPVAL)

- This routine can be used to set a property in the GUI environment. Specify the name of the object in the OBJNAME parameter, the name of the property in the PROPNAME parameter, and the value you wish to set in the PROPVAL parameter. Please note that the CTO routines, run in the character context, do NOT have access to the @window variable, and therefore you cannot specify @window (or anything derived from @window) explicily as the object name. However, if you ise the literal “@” character, CTO_SET_PROPERTY will substitute the current @window value for the “@” literal when it invokes the actual SET_PROPERTY function in the GUI context.

FUNCTION CTO_GET_PROPERTY(OBJNAME,PROPNAME)

- This routine can be used to get a property in the GUI environment. Specify the name of the object in the OBJNAME parameter, and the name of the property to retrieve in the PROPNAME parameter. Please note that the CTO routines, run in the character context, do NOT have access to the @window variable, and therefore you cannot specify @window (or anything derived from @window) explicitly as the object name. However, if you use the literal “@” character, CTO_GET_PROPERTY will substitute the current @window value for the “@” literal when it invokes the actual GET_PROPERTY function in the GUI context.

SUBROUTINE SET_OIPI_PROPERTIES(FileName, Title, PageInfo, PageSetup, PrintSetup)

- This routine allows you to customize the OIPI output generated through the CTO print routines. The parameters correspond to the first five parameters of the INIT Set_Printer message. Please refer to your OpenInsight help for the INIT Set_Printer Message for details.

SUBROUTINE CTO_GUI_SUBROUTINE(<SNAME>,<PARAM1>,<PARAM2>,…<PARAM20>)

- This routine calls any OpenInsight subroutine that requires an “event context”. Specify the name of the subroutine as the <SNAME> parameter, and any required or desired parameters as <PARAM1>, <PARAM2>, etc. This subroutine calls SET_STATUS to set the status code with the status of the <SNAME> subroutine.

As an alternative to using CTO_CHILD_FORM, you may include in your form the following call:

FUNCTION RUN_CHARACTER(<ctlname>,<cmd>)

The RUN_CHARACTER function will set the properties on the specified control to allow for a connection to the sample application as the GUI form is currently running in, and will invoke the specified command. If <cmd> is not specified, the user will be placed at TCL; if <cmd> is specified, the CTO session will terminate when the command terminates.

You should also be sure to have the “Close” property of your window programmatically send the “disconnect” message to the OLE control to avoid having “orphaned” CTO sessions.