Objects:

• HAT.Application
• HAT.Database
• HAT.Dimension

Examples:

• Open and Save
• Save copies with different password
• List currently open databases
• Modify Dimensions
• Call HAT Macros

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:

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

Available in HAT 5.1 and later.

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.

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

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.

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.

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.

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.

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

Password can be empty. If the file is password protected and no password is specified here, the user is asked to enter the password upon execution.

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.

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:

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.

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.

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.

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.

This method opens a HAT file.

Password can be empty. If the file is password protected and no password is specified here, the user is asked to enter the password upon execution.

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.

This method imports a HAT-file into the database.

Password can be empty. If the file is password protected and no password is specified here, the user is asked to enter the password upon execution.

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

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.

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.

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.

This method saves the database using its current name.

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

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.

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

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.

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.

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.

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.

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.

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:

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

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.

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.

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

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.

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.

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

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.

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.

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.

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

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

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