3rd Party Integration - ActiveX OCX
Definition of OCX:
OCX: Short for OLE Control Extension, an independent program module that can be accessed by other programs in a Windows environment. OCX controls end with a . ocx extension. OCX controls represent Microsoft's second generation of control architecture, the first being VBX controls written in Visual Basic.
Both VBX and OCX controls have now been superseded by ActiveX controls. However, ActiveX is backward compatible with OCX controls, which means that ActiveX containers can execute OCX components.
Omfax Systems Ltd. has developed an OCX custom control, which can be used in Windows based host applications. This control simplifies the interface between the host and Keyfax by encapsulating the majority of the complex code which would be required to communicate via XML with Keyfax directly.
The Keyfax OCX control can be used to integrate both Keyfax version 2.x and Keyfax version 3.x. There are NO differences in the code required in the host application. This gives the Keyfax customer the choice over which version of Keyfax they want to install.
This Keyfax OCX control can use either Early or Late Binding .
Early vs. Late Binding
There are two ways to use Automation (or OLE Automation) to programmatically control the Keyfax OCX.
Late binding uses CreateObject to create and instance of the Keyfax OCX object, which you can then manipulate. For example, to create a new instance of the Keyfax OCX using late binding:
Dim oKeyfax As Object
Set oKeyfax = CreateObject ( " KeyfaxEx.Keyfax ")
To use early binding , you first need to set a reference in your project to the control you want to manipulate. In VB, you do this by selecting Project + Components, and selecting the control you want from the list (e.g. "Keyfax XML exchange control").
The Keyfax OCX object will now be available in the control toolbox to drag and drop onto the required form. The control's can then be coded against; using it's properties and methods (the Keyfax OCX object also has a single event, notifying host of current Keyfax Status; this event however is only available with early bound usage).
To create a new instance of the Keyfax control using early binding:
Dim oKeyfax As KeyfaxEx.Keyfax
Set oKeyfax = New KeyfaxEx.Keyfax
In either case, incidentally, you can first try to get an existing instance of the Keyfax control, and if that returns an error, you can create a new instance in your error handler.
Advantages of Early Binding
- Your code will run considerably faster, because it can all be compiled up front. With late binding, the code relating to an application you declared as an object has to, in effect, be compiled as it runs.
- Because your code can all be compiled up front, debugging is far easier - select Debug + Compile, and the compiler will be able to spot syntax errors which would have been missed had you used late binding.
- You have full access in your project to intellisense (type a keyword and a dot to get a popup list of properties and methods supported by that keyword, select one to insert it; type a keyword and press F1 to launch the Help topic on that keyword).
- You have full access to the application's object model via the Object Browser and VBA Help.
- You have access to the application's built-in constants.
Advantages of Late Binding
- The main advantage is that code which uses late binding is more certain to be version-independent
- The more references your project contains, the larger the file size and the longer it takes to compile.
- Some programming environments don't allow you to create references to another application.
Using the Keyfax OCX to communicate with Keyfax 3
The launching and communication between a host application and Keyfax 3 can be broken down into the following distinct headings:
- Launching (loading Keyfax into memory).
- Requesting a Repair Diagnostic or Frontline enquiry (sending data to Keyfax).
- Waiting for Keyfax status notification (Keyfax alerting of completion).
- Reading results (reading results returned from Keyfax).
- Terminating (closing Keyfax when no longer required).
1. Launching
Keyfax should be launched prior to being required for the first time. Preferably during the host application launch (while a splash screen or similar is displayed). This allows the application to be preloaded ready for first use.
Note: The desktop version of Keyfax (2.x) will resume to an iconic state (minimised in task tray) between uses so that resuming for subsequent usage will be as rapid as possible. The browser version of Keyfax (3.x) simply unloads the browser form from the OCX, but for version compatible code integration, this difference should be ignored.
When launching the Keyfax OCX must be correctly initialised, together with some properties set to allow Keyfax to validate information in the start-up xml, and parameters used in the application launch command ( LaunchKeyfax ).
Sample launch code using OCX (version 3.x will ignore LaunchKeyfax )
With oKeyfax If Keyfax1.IsKeyfaxActive2 Then '=== Keyfax already loaded Else '=== Call Startup.xml initialisation method. '=== This is in case the Startup.xml file contains the 'EXIT' command. .InitStartup
'=== Load the basic properties to prevent load failure .Mode = "RD" '=== For Repair Diagnostics '.Mode = "FL" '=== For Frontline
'=== Pass company identifier (only available in OCX version 3.2.0.0 or greater) .Company = "HOSTCO01"
.Startup = "XML" '=== Only needs to be set if not XML .Export = "XML" '=== Only needs to be set if not XML .UserName = <host system user ID>
'=== This will override password validation if User ID is valid .Password = "Global"
'=== This will write properties to the Startup.xml file .SendStartup
'=== Set Export Status to -4 '=== This allows you to check status when launching after '=== possible closedown errors .SetExportLoadRequestFlag
'=== Launch Keyfax - This will Shell the Keyfax application. '=== Pass the required command line parameters. .LaunchKeyfax "/S:XML /E:XML /V:MIN /M:" & <host system user ID> & " /U:Global /P:" & txtPwd.Text
Do While .GetKeyfaxStatus <> -2 '=== Check for all status events here..... '=== You need to pay attention to the following! '=== -5 = Failed to load via KLaunch.exe module '=== -4 = SKIP - Only appears if using 'SetExportLoadRequestFlag' '=== -3 = SKIP - should receive this.... still loading '=== -2 = LOADED OK - Continue with Keyfax1 calls now! '=== -1 = General Error occurred, usually SQL Updates '=== 0 = Data failure '=== 1 = Script complete Flag '=== 2 = Script cancelled flag '=== 3 = Keyfax1 has exited '=== 4 = Follow up Script not completed '=== 5 = Follow up Script cancelled '=== 6 = Bookmarked script returned '=== 7 = Follow up Script bookmarked other scripts complete '=== 100 - 110 other errors DoEvents Loop End If End WithItems shown in arrow bracketing (<host variables>) indicate host application variables.
Once Keyfax has loaded successfully, the Keyfax Status is set at -2, Keyfax Launched OK.
2. Requesting a Repair Diagnostic or Frontline enquiry
When Keyfax is required from the host application for either a repair diagnostic or a Frontline enquiry, the Keyfax OCX properties should be set within the host application, followed by an OCX method call ( SetStartupFlag ) to notify Keyfax that information is to be read.
As the Keyfax application may have been inadvertently unloaded, it is prudent to always check if Keyfax is Active, by running the code indicated in section 1 before requesting a Repair Diagnostic or Frontline enquiry. This will, if required, re-launch the application, but will result in a slight delay with version 2.x.
At this point the host application should await the Keyfax OCX StatusX event (or poll for the Keyfax Status if late binding the Keyfax OCX control) to continues processing with the Keyfax results.
Sample Keyfax Request code, using OCX
With oKeyfax '=== Call Startup.xml initialisation method. '=== This is in case the Startup.xml file contains the 'EXIT' command. .InitStartup
'=== Load the basic properties to prevent load failure .Mode = "RD" '=== For Repair Diagnostics '.Mode = "FL" '=== For Frontline
'=== Pass company identifier (only available in OCX version 3.2.0.0 or greater) .Company = "HOSTCO01"
.Startup = "XML" '=== Only needs to be set if not XML .Export = "XML" '=== Only needs to be set if not XML .UserName = <host system user ID>
'=== This will override password validation if User ID is valid .Password = "Global"
.Tenant = <caller name> & ", " & <caller address> .TenantID = <caller ID or property ID>
Select Case JF_MODE Case "RD" '=== The Tenancy property is the Q&Aset to use .Tenancy = <caller tenancy type>
'=== Asset attributes XML document .AssetID = <property ID> '=== optional .Asset = <property attribute file> '=== optional
'=== Repair history document .History = <property repair history file> '=== optional Case "FL" '=== The Tenure_Code property is the Q&Aset to use .Tenure_Code = <caller tenancy type>
'=== The Scheme_Code & LA_Code are required if dataview is used .Scheme_Code = <caller housing scheme ID> .LA_Code = <property local authority code> End Select
'=== Create the XML file .SendStartup
'=== Set Export Status to -4 '=== This allows you to check status when launching after '=== possible closedown errors .SetExportLoadRequestFlag
'=== Alert Keyfax to read XML start-up .SetStartupFlag
'=== New call to ensure Keyfax1 pops up on top of desktop ZOrder '=== Note: not active for 3.x or greater as Keyfax always runs modally and it therefore at top of Z-order. .PutKeyfaxOnTop End WithItems shown in arrow bracketing (<host variables>) indicate host application variables.
3. Waiting for Keyfax status notification
Once Keyfax has been sent a request, then the host application should then wait until Keyfax has completed the Repair Diagnostic or Frontline enquiry. Keyfax will notify the host by either an event ( StatusX event) in the case of early bound embedded OCX usage, or the host application 'polling' the Keyfax OCX for the status (via the Status property).
The Keyfax OCX StatusX event
Private Sub oKeyfax_StatusX(ByVal Status As Long) '=== This event will fire every time Keyfax's Status changes Select Case Status Case 1 '=== Run code to read results here Case 2 '=== Keyfax was cancelled Case 3 '=== Keyfax has unloaded End Select End SubThe above code snippet indicates only the status codes which are of direct importance to this sample. However it is recommended that host code should include all the possible Keyfax status codes with error handling to allow for unexpected results.
For Keyfax integration where the Early Binding of the Keyfax OCX is not available, then the status should be retrieved from the OCX via the ' GetKeyfaxStatus ' property. This together with the ' GetKeyfaxStatusText ' property, both the numeric status and the textual equivalent can be obtained from the OCX for use in message boxes or similar.
In this situation, the host should enter a loop or a timer event to 'poll' for the status every ½ second (500 milliseconds) or so. As in the StatusX event, all the possible Keyfax status codes should be handled, with error handling to allow for unexpected results.
Important: As a matter of course there should also be a timeout or escape from any loop or timer routine, in case Keyfax or another process hangs, preventing the loop from exiting.
4. Reading results
Once the Keyfax status is set at 1, Keyfax Script Completed successfully (or 5, if multiple repair orders are being processed) then the StatusX event or timer/loop code should be exited and a call to a routine to extract the Keyfax resulting data should be made.
This is done once more by using the properties and methods of the Keyfax OCX control to fetch the required results from the returned XML packet.
Keyfax can be configured to repair multiple repairs or enquiries within a single XML packet, so the code should always check for multiples of data, and display messages in the event of too much data being returned, where it cannot be processed by the host.
Sample Keyfax Result reading code, using OCX
With oKeyfax '=== Set the Mode to 'RD' or 'FL' .Mode = "RD"
'=== Load result XML and Assign OCX properties .LoadExport
'=== Read the number of faults in diagnosed fCount = .ItemCount
'=== Loop through each fault For jLoop = 1 To fCount '=== Tell OCX which fault to read .Item = jLoop
'=== Read the fault description, <repair fault text> = .FaultText <repair notes> = .Additional_Info
'=== The fault may have multiple repairs logged. '=== Read the number of repairs to loop through. rCount = .RepairCount For iLoop = 1 To rCount '=== When reading sub items, pass the required item as an index <repair code (iLoop)> = .RepairCode(iLoop) <repair description (iLoop)> = .RepairCodeDesc(iLoop) <repair priority (iLoop)> = .Priority(iLoop) Next iLoop
'=== The fault may have multiple advice items. '=== Read the number of advices to loop through. aCount = .AdviceCount For aLoop = 1 To aCount <advice code (iLoop)> .AdviceCodeDesc(aLoop) Next aLoop Next jLoop
'=== Close the XML document .CloseExport End WithItems shown in arrow bracketing (<host variables>) indicate host application variables.
Note: There are many properties and methods in the Keyfax OCX control which are not included in these example code snippets. For a full list, please refer to the full list of OCX properties and methods .
At this point Keyfax is in an iconic state (minimised to the task tray) in the case of Keyfax 2.x or the browser window unloaded in the case of Keyfax 3.x. In either case can be resumed to run another Repair Diagnostic or Frontline enquiry by repeating step 3 onwards.
5. Terminating
Once the Keyfax application has been finished with, then Keyfax should also be closed. Although this is only actually required in version 2.x it is advisable to include the termination code in case the customer has chosen to use version 2.x.
Terminating Keyfax is a simple case of sending an XML packet with the 'Exit' command in the XML Startup packet :
When Keyfax is terminated using this method, the Status is set at 3, Keyfax exited. If Keyfax has been terminated, then the previous code, starting in section 1 would need to be repeated if the application was to be reused.Sample Keyfax Termination code, using OCX
With oKeyfax '=== Call Startup.xml initialisation method. '=== This is in case the Startup.xml file contains the 'EXIT' command. .InitStartup
'=== Load the basic properties to prevent load failure .Mode = "RD" '=== For Repair Diagnostics '.Mode = "FL" '=== For Frontline
'=== Pass company identifier (only available in OCX version 3.2.0.0 or greater) .Company = "HOSTCO01"
.Startup = "EXIT" '=== Use the Exit command .Export = "XML" '=== Only needs to be set if not XML .UserName = <host system user ID>
'=== This will overide password validation if User .Password = "Global" ID is valid
.SendStartup .SetStartupFlag End WithItems shown in arrow bracketing (<host variables>) indicate host application variables.