RevDotNet API

Before communicating with .NET, you must first create a RevDotNet object in OpenInsight. The RevDotNet object can be created by putting a RevDotNet OCX control on a form, or it can be created “dynamically”. If the .NET objects you wish to create are visible controls (for example, a calendar control), then you must use the OCX version of the RevDotNet object. If, however, you are going to be manipulating data that does not require a visible interface, then you can use either the OCX control or a dynamically-created RevDotNet object. In either case, be sure to include the REVDOTNETEQUATES insert item in your stored procedure. This insert item declares all the API functions for RevDotNet, as well as equated variables referenced in RevDotNet.

If you wish to put an actual RevDotNet control on a form, select an “OLE control” from the Form Designer toolbox, name it whatever you wish, and specify “Revelation4_10.Invoker” as the OCX information. If you intend to communicate with a .NET 2.0 control, specify “Revelation_10.Invoker” as the OCX information instead.

In either the form-based or “dynamic” RevDotNet scenario, you must “initialize” the RevDotNet environment by calling StartDotNet before using any of the RevDotNet APIs:

myHandle  = StartDotNet(dotNetCtl)

or

myHandle  = StartDotNet(dotNetCtl, “2.0”)

when using a .NET 2.0 control.

StartDotNet returns a “handle” that will be used to communicate with the RevDotNet object. If you are using a form-based RevDotNet, then the passed-in parameter is the control ID of the RevDotNet OCX control. If you are dynamically creating a RevDotNet object, then the parameter to StartDotNet is not specified:

myHandle = StartDotNet()

or

myHandle = StartDotNet(“”, “2.0”)

when using a .NET 2.0 control.

RevDotNet also allows you to keep all the RevDotNet objects you create in a separate common (so that they can be more easily “cleaned up” without interfering with any other RevDotNet processes). To instruct RevDotNet to use a separate common, you must pass in a third parameter to StartDotNet; this will hold the name of the special common that StartDotNet will create for you:

myRevDotNetCommon = “”
myHandle = StartDotNet(“”, “”, myRevDotNetCommon)

or

myHandle = StartDotNet(dotNetCtl, “”, myRevDotNetCommon)

or

myHandle = StartDotNet(“”, “2.0”, myRevDotNetCommon)

or

myHandle = StartDotNet(dotNetCtl, “2.0”, myRevDotNetCommon)

Note that you must assign this variable a null value before passing it into StartDotNet, and – once specified in the StartDotNet call – you must use this variable in all subsequent RevDotNet calls.

After creating the RevDotNet object, the AssemblyName property must be set to specify the path or paths where the .NET classes you wish to create can be found. This is done with the set_property.net function:

rslt = set_property.net(myHandle, "AssemblyName", paths)

or

rslt = set_property.net(myHandle, “AssemblyName”, paths, myRevDotNetCommon)

If desired, multiple paths may be specified, @fm delimited.

To create a specific .NET object, we can call the create_class.net function. This function requires the handle to the previously-created RevDotNet object, the name of the class you wish to create, and whether this object should be visible when created, and returns a handle to the .NET object:

hndlClass = create_class.net(myHandle, ClassName, 0)

or

hndlClass = create_class.net(myHandle, ClassName, 0, “”, “”, myRevDotNetCommon)

If the .NET object you wish to create requires additional parameters, you may specify the parameters and their .NET types after the “Visible?” flag:

pointHndl = create_class.net(myHandle, "System.Drawing.Point", 0, "10":@FM:"10", "System.Int16":@FM:"System.Int16")

or

pointHndl = create_class.net(myHandle, "System.Drawing.Point", 0, "10":@FM:"10", "System.Int16":@FM:"System.Int16", myRevDotNetCommon)

Multiple parameters can be specified, @fm delimited. Parameters and their types should be ‘associated’ (there should be the same number of types as there are values specified).

If desired (or if required in more complicated scenarios), the parameters can be “bundled together” into a single entity using create_params.net. Invoke create_params.net with a dimensioned array of parameters, a dynamic array of the parameter types, and the number of parameters:

DIM Params(3)
Params(1) = “Hello World”
Params(2) = “10”
Params(3)= pointHndl
pTypes = “System.String”
pTypes<2> = “System.Int16”
pTypes<3> = “RevDotNet” ;* used to represent an internal RevDotNet object
paramObject = create_params.net(3, mat Params, pTypes)

or

paramObject = create_params.net(3, mat Params, pTypes, myRevDotNetCommon)

You can determine a variety of information about the .NET class using the get_info.net function. The get_info.net function can return details about the properties, methods, events, fields, and interfaces of any .NET class:

mthds = get_info.net(hndlClass, REVDOTNET_INFO_METHODS)
evts = get_info.net(hndlClass, REVDOTNET_INFO_EVENTS)

or

mthds = get_info.net(hndlClass, REVDOTNET_INFO_METHODS, “”, myRevDotNetCommon)
evts = get_info.net(hndlClass, REVDOTNET_INFO_EVENTS, “”, myRevDotNetCommon)

If you wish to capture any events that the .NET object raises, you must call the events.net API:

Call events.net(hndlClass, “OnForeColorChanged”)

or

Call events.net(hndlClass, “OnForeColorChanged”, myRevDotNetCommon)

In addition, you must specify in your form that the RevDotNet control should respond to the OLE event, and you must handle the OLE event in your commuter module:

Case event _eqc "OLE" And P1 _eqc "DotNetEvent"
caller = P2<1,1>
event = P2<1,2>
Call Msg(@window, "Event ":event:" has happened!":@FM:"BOK")

Note that the details provided by each event will vary by the type of event, but in general, the 2nd parameter passed into your code will contain the caller that’s raised the event (as a string) in the first value; the name of the event (as a string) in the second value; a list of all the properties in the event object (subvalue delimited) in value three; an associated list of all the properties’ values in the event object (subvalue delimited) in value 4; the caller that raised the event, as an object reference, in value 5; and the event that has been raised, as an object reference, in value 6.

If you wish to use RevDotNet to communicate with the object references returned in the event, you must first convert them into RevDotNet objects by using CreateInternalObject.Net:

               hndlObject = P2<1,5>
               hndlEvent = P2<1,6>
               objEvent = CreateInternalObject.Net(myHandle, hndlEvent, “1”, “”)
               locObject = get_property.net(objEvent, “Location”, 1)

or

               hndlObject = P2<1,5>
               hndlEvent = P2<1,6>
               objEvent = CreateInternalObject.Net(myHandle, hndlEvent, “1”, myRevDotNetCommon)
               locObject = get_property.net(objEvent, “Location”, 1, myRevDotNetCommon)

You can now proceed to set properties of the class with set_property.net:

rslt = set_property.net(hndlClass, "TitleForeColor", "Red")

or

rslt = set_property.net(hndlClass, "TitleForeColor", "Red", myRevDotNetCommon)

You can also get properties with get_property.net:

currColor = get_property.net(hndlClass, "ForeColor")

or

currColor = get_property.net(hndlClass, "ForeColor", “”, myRevDotNetCommon)

In some cases, the get_property.net call may need to return additional .NET objects. If this is the case, specify an additional parameter to indicate that the returned value should be treated as an object (instead of as just a “normal” string return value):

hndlNewClass = get_property.net(hndlClass, “GetSubObject”, 1)

or

hndlNewClass = get_property.net(hndlClass, “GetSubObject”, 1, myRevDotNetCommon)

If you wish to return a particular value in an indexed field, you may specify the index or indices in square brackets after the property name:

thisSpecificValue = get_property.net(hndlClass, “ArrayValue[0]”)

or

thisSpecificValue = get_property.net(hndlClass, “ArrayValue[0]”, “”, myRevDotNetCommon)

If arrays need to be passed into, or extracted out of, .NET, use the array_utility.net API. You can create an array by specifying “CREATE”, either with a list of initial values:

oIntArray = array_utility.net(hndlClass, "Create", "System.Int32", "", "1":@FM:"3":@FM:"5":@FM:"7":@FM:"9":@FM:"11") ;* create a 6 element array

or

oIntArray = array_utility.net(hndlClass, "Create", "System.Int32", "", "1":@FM:"3":@FM:"5":@FM:"7":@FM:"9":@FM:"11", “”, myRevDotNetCommon) ;* create a 6 element array

or an “empty” array by specifying the size of the array:

oCharArray = array_utility.net(hndlClass, "Create", "System.Char", "1", "*")

or

oCharArray = array_utility.net(hndlClass, "Create", "System.Char", "1", "*", “”, myRevDotNetCommon)

Extract an array element with the “Get” command:

thirdPiece = array_utility.net(oIntArray, "Get", 2) ;* note: 0-based counting in arrays

or

thirdPiece = array_utility.net(oIntArray, "Get", 2, “”, “”, “”, myRevDotNetCommon) ;* note: 0-based counting in arrays

Set an array element with the “Set” command:

dummy = array_utility.net(oIntArray, "Set", 3, "99") ;* note: 0-based array, so this is setting the 4th element

or

dummy = array_utility.net(oIntArray, "Set", 3, "99", “”, “”, myRevDotNetCommon) ;* note: 0-based array, so this is setting the 4th element

To invoke “methods” on the .NET object, you can use send_message.net:

rslt = send_message.net(hndlClass, "UpdateBoldedDates")

or

rslt = send_message.net(hndlClass, "UpdateBoldedDates", “”, “”, “”, myRevDotNetCommon)

If you have parameters to specify in the send_message.net call, you must specify the parameter (and optionally the .NET type of the parameter) after the name of the method:

Rslt   = send_message.net(hndlClass, “AddBoldedDate”, “04/01/17”, “System.DateTime”)

Or

Rslt   = send_message.net(hndlClass, “AddBoldedDate”, “04/01/17”, “System.DateTime”, “”, myRevDotNetCommon)

Multiple parameters can be specified, @fm delimited; the parameter types should be “associated” with the parameter values (ie, if there are 10 values that you are passing, there should be 10 types specified as well). If you do not specify a type for a parameter value, RevDotNet will attempt to determine the appropriate type. You may also pass in a “parameter structure” created with create_params.net.

If the method you are invoking will return a new .NET object, then you must pass an additional flag at the end of the send_message.net call to indicate that you wish the return value of the function to be treated as a RevDotNet object:

Rslt = send_message.net(hndlClass, “MakeNewObject”, “”, “’, 1)

Or

Rslt = send_message.net(hndlClass, “MakeNewObject”, “”, “’, 1, myRevDotNetCommon)

When you no longer need one of the created .NET objects, you should call the free_class.net API to remove it from memory:

Free_class.net(hndlClass)

Or

Free_class.net(hndlClass, myRevDotNetCommon)

If free_class.net is called with an empty parameter, then all .NET objects will be freed in either the default common area:

Free_class.net()

Or in the special common area you created for your controls:

Free_class.net(“”, myRevDotNetCommon)