The ActiveX Control 'OXACTIVE'

The ActiveX control oxactive.dll offers methods and objects that allow reading and editing data of the handoff file and the configuration file.

During the installation of enaio®, the control will be installed and registered automatically.

The control can be directly used in the VBScript editor through the VBScript add-on. In other environments, the ActiveX control oxactive.dll is integrated as follows:

CoxHelp

Interface to support VBScript programming Object creation in VBScript: Dim x Set x = CreateObject('oxactive.CoxHelp')

Methods

GetProfString()

HRESULT GetProfString(BSTR bstrSec, BSTR bstrKey, BSTR bstrDefault, VARIANT* pvarReturn, BSTR bstrFile)

This function provides the functionality of the Windows API function GetPrivateProfileString.

Input:	BSTR bstrSec	the section name in the handoff file
	BSTR bstrKey	the key name in this section
	BSTR bstrDefault	default return value if no value can be determined
	BSTR bstrFile	file name of the handoff file
Output:	VARIANT* pVarReturn	determines key value as string

Example:

oxhelp.GetProfString "PAGE00","#OSEXP#",-1,rvalue,osfile

If the value cannot be determined, the value of the '#OSEXP#' key in the 'Page00' section is written to the 'rvalue' variable; otherwise '-1'.

WriteProfString()

HRESULT WriteProfString(BSTR bstrSection, BSTR bstrKey, BSTR bstrValue, BSTR bstrFile)

This function provides the functionality of the Windows API function WritePrivateProfileString.

Input:	BSTR bstrSection	the section name in the handoff file
	BSTR bstrKey	the key name in the handoff file
	BSTR bstrValue	the key value
	BSTR bstrFile	path and file name of the handoff file
Output:	-

The WriteToFile() method must be called prior to the oxhelp.WriteProfString() method can be used.

ExtractString()

HRESULT ExtractString(BSTR strVal, VARIANT* pFieldName, VARIANT* pFieldValue)

This function helps split the string into two parts. As a separator, either the character '\021' or ASCII code '17' must be used.

Input:	BSTR strVal	the string that is meant to be separated into two parts
Output:	VARIANT* pFieldName	left part of the string until the separator
	VARIANT* pFieldValue	right part of the string from the separator

WinExec()

HRESULT WinExec(BSTR strFile, BSTR strParams)

This function allows you start the application and pass the parameter.

Input:	BSTR strFile	file name of the application
	BSTR strParams	command line parameter
Output:	-

Objects

The ActiveX control oxactive.dll offers the following objects:

• ASFile Object: allows access to the add-on or the event's handoff file

• RequestPages object: comprises all registers of an index data form (collection of RequestPage objects)

• RequestPage Object: a single data sheet

• ActivePage object: is a RequestPage object, that is, a reference to the active data sheet

• ASFields Object: comprises all fields of an index data form (collection of all ASField objects)

• ASField Object: a single field of a form

These objects are used to read and edit the data of the handoff file.

Example:

The value of the 'Year' field can be read with one of the two following variants:

Method a) will read the field through the ActivePage object; method b) through the RequestPages collection.

ASFile Object

The ASFile object allows for access to the add-on or the event's handoff file. This handoff file contains information on the index data form.

Properties:

L – read-only

S – write access only

L/S – read and write access

ActivePage	Returns a RequestPage object of the currently active (top) data sheet	L
AddonFields	For add-ons only Returns a collection of ASField objects of the fields that are connected to the add-on. The first element is exactly the field to which the add-on button is assigned. The other elements of the collection allow access to all fields that are connected with the add-on.	L
ErrorMessage	In connection with the 'ASField.IsErrorField' property, an error text for both events 'BeforeValidate' and 'OnItemClick' can be specified, which will then be shown in an info window. A prerequisite is that the ResultCode is not 0 (see Example 4).	L/S
EventAction	Only for events. Available values are: NEW – a new object will be created UPDATE – an existing object will be modified REQUEST – a search will be performed READONLY – an existing object is open in read-only mode.	L
EventCode	Returns the numerical EventCode (see 'Client-side Events').	L
Filename	Name of the file that is meant to be used including the full path, usually the file name of the corresponding handoff file.	L/S
FOLDERID	Returns the ID of the folder in which the object is located	L
FOLDERTYPE	Returns the numeric folder type.	L
Handle	Sizing handle of the index data form	L
IsErrorField	Specifies whether or not this field is selected as corrupt on the index data form	L/S
REGISTERID	Returns the ID of the register in which the object is located	L
REGISTERTYPE	Returns the numeric register type	L
RequestPages	Collection of RequestPage objects of all data sheets on the current index data form	L
ResultCode	Only for events. All changes will apply if the value is set to '1'. Default value: '0'	L/S
TARGETMAINTYPE	Reads and writes the main document type.	L/S

Methods:

WriteToFile()

Returns all objects and properties to the handoff file. The file name is provided by the Filename property. Return values: '10' – file does not exist '11' – no file name specified

RequestPages Object

This object allows for access to a collection of RequestPage objects.

Properties:

L – read-only

S – write access only

L/S – read and write access

Count

Number of elements in this collection

L

Methods:

Item(VARIANT Item)

Returns an element of this collection Parameters: Item – either the index or the name of the intended element can be specified here.

RequestPage Object

This object allows you to access a single data sheet of the index data form.

Properties:

L – read-only

S – write access only

L/S – read and write access

Active	'1' if this page is on top; otherwise '0'	L
ASFields	ASField collection of all fields on this page	L
FileCount	Number of files that belong to a document	L
ID	ID of the object	L
Name	Name of the data sheet	L
ObjectType	Object type of this page	L

ASFields Object

This object represents a collection of ASField objects.

Properties:

L – read-only

S – write access only

L/S – read and write access

Count

Number of elements in this collection

L

Methods:

Item(VARIANT Item)

Returns an element of this collection Parameters: Item – either the index or the name of the intended element can be specified here.

ASField Object

This object allows you to access a single field of a search form.

Properties:

L – read-only

S – write access only

L/S – read and write access

CtrlPages	Collection of all registers of a page control	L
DBName	Name of the field in the database	L
Enabled	If set to FALSE, the respective field on the form is read-only.	L/S
Required	If set to 'TRUE', the respective field is a mandatory field. A mandatory field property from enaio® editor cannot be disabled.	L/S
GUID	Returns the GUID of the respective field on the form.	L
InternalName	The internal name of the respective field on the form.	L
IsErrorField	Specifies whether this field of the form is labeled as corrupt (yellow) on the index data form ('TRUE') or not ('FALSE’). (see Example 4)	L/S
Length	Maximum length of the field	L
Name	Name of the field	L
Type	Data type of the field (see below)	L
Value	Value of the field	L/S
Visible	If set to FALSE, the respective field on the form is hidden	L/S
TextColor	Text color, for example: RGB(33,255,59)	L/S

Available data types:

Type	Description	Database
#	Decimal numbers	DECIMAL
0	Checkboxes	SHORT
1	Radio button	SHORT
9	Numbers	INTEGER
A	All characters without numbers	CHAR
C	Page control	CHAR
D	Date	DATE
G	Uppercase letters	CHAR
I	Full-text index	INTEGER
L	All characters	CHAR
M	All characters	CHAR
P	Patient type	CHAR
Q	Yes/no	CHAR
S	male/female/other	CHAR
T	Left/right	CHAR
W	Table element	CHAR
X	All characters	CHAR
Z	Numbers only	CHAR

Examples of Use in VBScript

If, in enaio® client, the aforementioned objects are used through an event or the VBScript add-on, neither the ASFile object nor the CoxHelp object need to be created explicitly. Furthermore, the 'Filename' property of the ASFile object will be set automatically.

Example 1

Output the names of all data sheets:

Example 2

Output all field names of the currently active data sheet as well as change the content of a field for an event:

Example 3

Output the name of the add-on field as well as its content in the data sheet and then change the content of the add-on field:

Example 4

Highlight a data sheet's field on a page control in color and activate the respective page and output an error message in the form of a tooltip for the 'OnClickItem' or 'BeforeValidate' event:

Example 5

Distinguish whether a query has been performed in expert mode or not by reading the #OSEXP# key of the handoff file: