## HAT 5 OLE Reference

### Registering OLE Server

To start using the OLE services of HAT, you need to register the OLE server. This can be done in the "Preferences" dialog in the "File" menu of HAT. Click the button "Register OLE-Server".

Only one HAT.exe can be registered as an OLE server at a time. Registering another HAT.exe as the server disables the previous server.

Click the button "Unregister OLE-Server" in the "Preferences" dialog when you want to disable OLE services of HAT.

### Using Visual Basic with HAT

Objects and methods can be shown in Visual Basic's object browser if you open HAT.exe as a reference from within the Visual Basic editor. Take "References" command in the "Tools" menu, click the "Browse.." button and select HAT.exe.

Note: OLE interfaces for HAT 5.0 and 5.1 are not binary compatible. If you compile your VB program, you need to compile it separately for each interface.

### Using C/C++ with HAT

The OLE interface of HAT is also available to C and C++ programs.
The required "iface.h" header file and "guids.c" file are available here separately for HAT 5.0 and HAT 5.1 and later.

Note: OLE interfaces for HAT 5.0 and 5.1 are not binary compatible. You need to compile your C/C++ program separately for each interface.

### HAT.Application object:

 • property Version HAT version number HAT 5.1 and later • property Visible Visibility of HAT application window • property WindowState State of HAT application window • property ExitOnRelease Exit HAT when application object is released • property Indicators Visibility of progress indicators HAT 5.1 and later • property Signature Current signature in HAT • property BaseCount Number of open databases HAT 5.1 and later • method OpenFile Open a HAT-file and return a database object • method Quit Quit HAT when application object is released

 string version = app.Version

This property can be used to get the current version of the HAT application.

Available in HAT 5.1 and later.

 boolean vis = app.Visible app.Visible = vis boolean

This property can be used to set or get the visibility of the HAT application window.

The default visibility of HAT application window depends on how the HAT application instance was started. If the HAT instance was started by OLE using CreateObject("Hat.Application") then it is not visible by default.

When this property is set to True, the application window becomes visible, and a HAT icon is shown in the Taskbar.

Note that this property does not control the visibility of the progress indicators. Another property Indicators is used to do that.

 integer ws = app.WindowState app.WindowState = ws boolean

This property can be used to set or get the state of HAT application window.

The constants in WindowState which can be used with this property are:

  wsNormal   = 0
wsMaximize = 1
wsMinimize = 2


 boolean exit = app.ExitOnRelease app.ExitOnRelease = exit boolean

This property can be used to set or get the flag that controls wether the HAT application process will be terminated or not when the OLE session ends.

By default, the HAT application process is terminated when the OLE session ends. It is possible to speed up repeated sessions by leaving the HAT process unterminated. The next session will pick up this process.

Note: remember to terminate the HAT application process when all your OLE sessions are completed. There is no indication to the user that HAT application is still running - its application window is not visible and there is no HAT icon in Taskbar. Only the Task Manager will show it under "Processes" but not under "Applications". A typical HAT process can take a considerable amount of memory so it is not recommended to leave it unterminated.

This property can be set to True also with the Application.Quit method.

 boolean vis = app.Indicators app.Indicators = vis boolean

This property can be used to set or get the visibility of the progress indicators during file operations.

By default, the progress indicators are visible. When this property is set to False, the progress indicators are not shown.

Available in HAT 5.1 and later.

 string sign = app.Signature app.Signature = sign string

This property can be used to set or get the user signature.

The signature is used to stamp changes made to the cards in a database. Transforming a set of cards is one example when the signature must be defined. To avoid the signature dialog to pop up during execution, the signature can be defined using this property.

 integer count = app.BaseCount

This property can be used to get the number of open databases currently in HAT.

To get access to the open databases, create a HAT.database object and use GetBase method with index value from 1 to the number returnded by this property.

Available in HAT 5.1 and later.

 err = app.OpenFile (filename string, password string, out database object)

This method opens a HAT-file and returns a database object.

The CloseOnRelease property is set to True. This causes the database to be closed in HAT when the database object is released.

This method is not available in VBScript because it returns an object reference. Use Database.OpenFile method instead.

In case of an error, a non-zero error code is returned.

 app.Quit

This method is used to set the ExitOnRelease property to True.

Normally you do not need to call this method to terminate HAT.
It is enough to set app = nothing.

### HAT.Database object:

 • property Name Database name • property Password Database password • property CloseOnRelease Close HAT database when object is released HAT 5.1 and later • method GetDim Return dimension object • method GetBase Connect to an open HAT database HAT 5.1 and later • method OpenFile Open a HAT file HAT 5.1 and later • method Import Import a HAT file • method ImportWithSetup Import transaction file with import setup • method ImportText Import text in HAT-text syntax • method ImportTrans Import text with import setup • method Save Save database in its file • method SaveAs Save database in a specified file with options • method XML_Command Execute XML commands • method MacroCall Execute a HAT macro • method MacroCommand Execute macro commands directly • method TemplateList Return a list of installed templates HAT 5.1 and later • method Export Export a template HAT 5.1 and later • method ErrorFile Specify a file for error messages HAT 5.1 and later • method Close Close HAT database

 string name = base.Name

This property returns the database name.
Database name is the leaf part of its filename.

This property can be used to set or get the password of the database.

See Save copies with different password for an example of how it can be used.

 boolean close = base.CloseOnRelease base.closeOnRelease = close boolean

This property can be used to set or get the flag that controls wether the database in HAT application will be closed or not when the OLE database object is released.

This property is set to True by the Application.OpenFile and Database.OpenFile methods. Typically databases created during the OLE session are closed when the session ends.

This property is set to False by the Database.GetBase method. Typically databases created before the OLE session started are not closed when the session ends.

Available in HAT 5.1 and later.

 dm = base.GetDim (num integer)

This method returns a dimension object.

See Modify Dimensions for an example of how it can be used.

This method is not available in VBScript because it returns an object reference.

 err = base.GetBase (index integer)

This method connects to an open HAT database. The database is identified by index: set index to 1 for the first database, 2 for the second and so on. An error code is returned when index is larger than the number of open databses.

If there was an existing database connected to this database object, it is first released. If the CloseOnRelease property was set then that HAT database is also closed.

To get the number of open databases currently in HAT, you can use the BaseCount property.

The CloseOnRelease property is set to False. This causes the database to be left open in HAT when the database object is released or connected to another HAT database.

In case of an error, a non-zero error code is returned.

Available in HAT 5.1 and later.

 err = base.OpenFile (filename string, password string)

This method opens a HAT file.

See Open and Save for an example of how this method can be used.

If there was an existing database connected to this database object, it is first released. If the CloseOnRelease property was set then that HAT database is also closed.

The CloseOnRelease property is set to True. This causes the database to be closed in HAT when the database object is released.

In case of an error, a non-zero error code is returned.

Available in HAT 5.1 and later.

 err = base.Import (filename string, password string)

This method imports a HAT-file into the database.

In case of an error, a non-zero error code is returned.

 err = base.ImportWithSetup (filename string, importsetup string)

This method imports a text file containing transactions into the database, using an import setup. The import setup must be predefined and stored in the database.

In case of an error, a non-zero error code is returned.

 err = base.ImportText (text string)

This method imports a string variable into the database. The string must be formatted as a HAT-textfile with proper headers and syntax.

In case of an error, a non-zero error code is returned.

 err = base.ImportTrans (data string, importsetup string)

This method imports a string of transactions into the database, using an import setup. The import setup must be predefined and stored in the database.

In case of an error, a non-zero error code is returned.

 err = base.Save

This method saves the database using its current name.

In case of an error, a non-zero error code is returned.

 err = base.SaveAs (filename string, options string)

This method saves the database using the given filename.

The filename can be a full or a partial pathname. If a partial pathname is used, the database's current pathname is used as starting point in the file system. For example, if only a leaf name is given, like "copy.hat", the file will be found in the same directory as the original database file.

A lot of options can be specified in the options string. All the options that apply to the macro command Save are also available here.

In case of an error, a non-zero error code is returned.

 string xmlout = base.XML_Command (xmlin string)

This method executes XML commands.
See XML Command Reference for details how to use XML in HAT.

 err = base.MacroCall (name string)

This method executes a HAT macro. The macro is specified by its name.

See Call HAT Macros for an example how to use this method.

In case of an error, a non-zero error code is returned.

 err = base.MacroCommand (commands string)

This method executes HAT macro commands directly.

See Macro Reference for a complete list of available macro commands.
See Call HAT Macros for an example how to use this method.

In case of an error, a non-zero error code is returned.

 string list = base.TemplateList (rootname string, filter string)

This method returns a list of installed templates. The list has two columns separated by a tab character. First column contains the analysis template type and the second analysis template name.
The rootname parameter is used to limit the list to a template subtree.

The filter parameter is used select templates that have the specified text somewhere in their name. Advanced text search can be specified by starting with a backslash.

Available in HAT 5.1 and later.

 string text = base.Export (templatename string)

This method exports the given template and returns that text as a string. The template is specified by its pathname.

Contents of the exported text is determined in the "Export" definition page in the template.

Available in HAT 5.1 and later.

 base.ErrorFile (filename string)

This method redirects subsequent error messages into a file.
The file contents are cleared if no errors occur.

The redirection is in effect until another ErrorFile is executed.
By default the errors are logged into "Errors.txt" file.

Note: This method has no effect if a database is not open. CreateObject(HAT.Database) creates a database object only, it does not open a database in HAT. A database is opened with Database.OpenFile method.

Note: An empty filename can be specified to cause all error messages be lost. This is available in HAT 5.3 and later.

Note: In HAT 5.2.3 and earlier the error file is handled a bit differently. The file contents are not cleared if no errors occur.

Available in HAT 5.1 and later.

 base.Close

This method closes the HAT database immediately.

You do not need to call this method if CloseOnRelease property is set to true. Opening a database with Application.OpenFile or Database.OpenFile methods set this property. In that case it is enough to Set base = Nothing to close the database.

Changes made to the database are not automatically saved. You need to explicitly call the Save or SaveAs methods to save changes before closing the database.

### HAT.Dimension object:

 • property Number Dimension number • property Singular Dimension singular name • property Plural Dimension plural name • property DimString Component presentation in analyses • property ComponentsInUse Number of components directly in use • property ActiveComponents Number of active components • property TotalComponents Total number of components • method Import Import a file with components • method ImportText Import components as text • method Export Export all components into a file • method ExportText Export all components into a variable • method ExportComponents Export selected components into a variable HAT 5.1 and later

 integer num = dimension.Number

This property returns the dimension number (1 to 32) of the dimension.

 string tx = dimension.Singular dimension.Singular = tx string

This property can be used to set or get the singular form of the dimension name.

See Modify Dimensions for an example of how this method can be used.

 string tx = dimension.Plural dimension.Plural = tx string

This property can be used to set or get the plural form of the dimension name.

See Modify Dimensions for an example of how this method can be used.

 integer dc = dimension.DimString dimension.DimString = dc integer

This property can be used to set or get the way how dimension components are represented in analyses.

The constants in DimStringCase which can be used with this property are:

  dcCode         = 0
dcHost         = 1
dcText         = 2
dcCodeText     = 3
dcHostText     = 4
dcCodeHost     = 5
dcCodeHostText = 6


 integer num = dimension.ComponentsInUse

This property returns the number of components that are directly in use. This number does not contain components that are indirectly in use, through the dimension hierarchy.

Note: By "a component in use" is meant that there is at least one card line in the database that refers directly to the component.

 integer num = dimension.ActiveComponents

This property returns the number of active components. The number includes also components that are indirectly in use, through the dimension hierarchy.

Note: By "an active component" is meant that there is at least one card line in the database that refers directly to the component or one of its subcomponents.

 integer num = dimension.TotalComponents

This property returns the total number of components in the dimension.

 err = dimension.Import (filename string)

This method imports the given file into the dimension.

If there is an import setup defined for this dimension, it is used when importing the file.

If there is no import setup defined, the default format is used (i.e. assuming a tab-separated text file with HAT-code in the first, text in the second and host code in the third column).

See Modify Dimensions for an example of how this method can be used.

 err = dimension.ImportText (text string)

This method imports the given text string into the dimension. The text string must consist of dimension components.

If there is an import setup defined for this dimension, it is used when importing the string.

If there is no import setup defined, the default format is used (i.e. assuming a tab-separated text with HAT-code in the first, text in the second and host code in the third column).

See Modify Dimensions for an example of how this method can be used.

 err = dimension.Export (filename string)

This method exports all the dimension components to the given file.

The filename can be a full or a partial pathname. If a partial pathname is used, the database's current pathname is used as starting point in the file system. For example, if only a leaf name is given, like "Products.txt", the file will be found in the same directory as the database file.

See Modify Dimensions for an example of how this method can be used.

 string text = dimension.ExportText

This method returns all the dimension components in a string variable.

See Modify Dimensions for an example of how this method can be used.

 string text = dimension.ExportComponents (root string, filter string, levels integer)

This method returns the specified dimension components in a string variable.

The root parameter can be used to select a subtree. Pass a HAT-code of the root component to this parameter. An empty string denotes all components.

The filter parameter can be used to select components that have the specified string somewhere in their HAT-code, text or host code. Advanced text search can be specified by starting the string with a backslash '\'.

The levels parameter can be used to limit subcomponents to a certain level. A value of 1 denotes one level down from the root.

See Modify Dimensions for an example of how this method can be used.

Available in HAT 5.1 and later.

### Example: Open and Save

This example opens a HAT-file and saves it using a different name.
This code works in HAT 5.1 and later.

 Dim base As HAT.Database Dim err As Long ' create a database object and open a HAT database Set base = CreateObject("HAT.Database") err = base.OpenFile("c:\hat\example.hat", "") If err Then MsgBox "Unable to open a HAT-file" End If ' save using another name err = base.SaveAs("duplicate.hat", "") If err Then MsgBox "Unable to save a file" End If ' release the database object Set base = Nothing 

In HAT 5.0 a bit more complex code must be used because the database object does not support OpenFile method.

 Dim app As HAT.Application Dim base As HAT.Database Dim err As Long ' create an app instance and open a HAT database Set app = CreateObject("HAT.Application") err = app.OpenFile("c:\hat\example.hat", "", base) If err Then MsgBox "Unable to open a HAT-file" End If ' save using another name err = base.SaveAs("duplicate.hat", "") If err Then MsgBox "Unable to save a file" End If ' release the objects Set base = Nothing Set app = Nothing 

### Example: Save copies with different password

This example opens a HAT-file and saves it using different names and passwords.
This code works in HAT 5.1 and later.

Note that error handling code is omitted, for clarity in this example.

 Dim base As HAT.Database Dim err As Long ' create a database object and open a HAT database Set base = CreateObject("HAT.Database") err = base.OpenFile("c:\hat\example.hat", "") ' set password and save base.Password = "k23zx6" err = base.SaveAs("copy1.hat", "") base.Password = "foo" err = base.SaveAs("copy2.hat", "") ' release the database object Set base = Nothing 

### Example: List currently open databases

This example loops through all open HAT databases and prints their name.
This code works in HAT 5.1 and later.

 Dim app As HAT.Application Dim base As HAT.Database Dim err As Long Dim index As Integer ' create an app instance Set app = CreateObject("HAT.Application") ' tell how many bases are currently open MsgBox CStr(app.BaseCount) + " databases currently open" ' create a database object and loop through HAT databases Set base = CreateObject("HAT.Database") index = 1 err = 0 do while err = 0 err = base.GetBase(index) If err = 0 Then MsgBox "Database name: " + base.Name End If index = index + 1 Loop ' release the objects Set base = Nothing Set app = Nothing 

### Example: Modify Dimensions

This example demonstrates how to change dimension properties and how to import and export dimension components.
This code works in HAT 5.1 and later.

Note that error handling code is omitted, for clarity in this example.

 Dim base As HAT.Database Dim dm As HAT.Dimension Dim err As Long Dim tx As String ' create a database object and open a HAT database Set base = CreateObject("HAT.Database") err = base.OpenFile("c:\hat\example.hat", "") ' set some dimension properties Set dm = base.GetDim(2) dm.Singular = "Account" dm.Plural = "Accounts" ' import dimension components from a file err = dm.Import ("c:\hat\accounts.txt") ' create new dimension components using a string tx = "K" + Chr(9) + "Product Group K" + Chr(13) _ + "KA" + Chr(9) + "Product KA" + Chr(13) _ + "KB" + Chr(9) + "Product KB" + Chr(13) err = dm.ImportText (tx) ' copy all components from dimension 2 to dimension 6 base.GetDim(6).ImportText dm.ExportText ' copy component subtree from dimension 3 to dimension 7 base.GetDim(7).ImportText base.GetDim(3).ExportComponents("KM","","") ' save using another name err = base.SaveAs("result.hat", "") Set dm = Nothing Set base = Nothing 

### Example: Call HAT Macros

This example demonstrates how to use HAT macros from VB.
This code works in HAT 5.1 and later.

Note that error handling code is omitted, for clarity in this example.

 Dim base As HAT.Database Dim err As Long ' create a database object and open a HAT database Set base = CreateObject("HAT.Database") err = base.OpenFile("c:\hat\example.hat", "") ' call a predefined macro err = base.MacroCall "PrintMyReports" ' execute a macro commands directly err = base.MacroCommand "print Projects:Totals:Results" err = base.MacroCommand "signature zz" + Chr(13) _ + "print Projects:Totals:Results" + Chr(13) _ + "message 'Results printed OK' -seconds 15" Set base = Nothing