The built-in XML-command interface can be used to retrieve data from HAT's database for external use. This interface is designed for web-servers but can be utilised for other purposes as well.

Note! The XML-command interface requires HAT-Server license.

Currently the interface is available in the Windows version only. The interface consists of one OLE function which is accessible from Visual Basic and C/C++.

Using the Visual Basic interface is straightforward. HAT.exe file contains VB-library information for the function. In VB editor open the HAT.exe as a reference.

Using C/C++ interface to HAT requires "iface.h" header file and "guids.c" file. These are available here separately for HAT 5.0 and HAT 5.1 and later.

There is a simple window in HAT that can be used for testing XML-functions ("XML Command Tester" command in "Database" menu). This window is implemented in Macintosh versions of HAT as well.

XML Input

XML input may but is not required to begin with a processing instruction:

<?xml version="1.0"?>

XML standard requires that a file only has one root level tag. HAT does not require that, but to conform to the standard, in HAT 5.6 and later, command input may use this root tag:

<HAT-xml-input>

XML input may include comments:

<!-- this text is skipped, including any <tags> -->
<!-- note: these comments cannot be nested -->

XML input may contain any combination of the currently defined input tags. HAT generates an output stream containing an ouput tag with subtags for each input tag. Error messages are also embedded in the output XML stream.

Currently defined input tags:

HAT Version

A version string for HAT is returned in XML output when using <version> tag. For beta versions a beta number is also returned.

<version/>

Available in HAT 5.1 and later.

date- and code -attributes are generated in HAT 5.4 and later

Dimension list

A list of dimensions is returned in XML output when using <dimensions> tag. A complete list of all dimensions is returned when specifying

<dimensions/>

Dimension list can be altered by specifying following attributes:

• num="2", only dimension number 2.
• name="Accounts", only dimension with the name "Accounts".
• filter="foo", only dimensions containing "foo" in their names.
  Advanced text search can be specified by starting with a backslash '\'.
• usage="on", include component usage values

Available in HAT 5.1 and later.

Component list

A list of components is returned in XML output when using <components> tag. A complete list of all components in all dimensions is returned when specifying

<components/>

Component list can be altered by specifying following attributes:

• dim="2", only dimension number 2, dimension names can also be used.
• code="KLM", only component with HAT-code "KLM" and its subcomponents.
• text="Costs", only components whose text is "Costs".
• host="0102", only components whose host code is "0102".
• filter="foo", only components containing "foo" in HAT-code, text or host code.
  Advanced text search can be specified by starting with a backslash '\'.
• levels="2", only components two levels deep.
  If levels is 2 or more each component is returned with a level number attribute.

Available in HAT 5.1 and later.

Template list

A list of installed templates is returned in XML output when using <templates> tag. A complete list of all installed templates is returned when specifying

<templates/>

Template list can be limited by specifying following attributes:

• name="Costs", template subtree
• type="Lines", only templates of this type
• filter="foo", only templates containing "foo" in their name.
  Advanced text search can be specified by starting with a backslash '\'.

Available in HAT 5.1 and later.

Temporary templates

Temporary templates are used to create on-the-fly queries to the HAT database. A complete definition of the query is supplied and HAT responds by exporting the analysis data to the XML output.

Following is a simple template definition:

<template type="lines">
  <selection>
    <from> 920101 </from>
    <dim num="1"> U </dim>
    <dim num="2"> KAL </dim>
    <dim num="3"> 2 </dim>
  </selection>
</template>

Currently defined temporary template types:

• Cards template
• Lines template
• Components template

Available in HAT 5.0 and later.

Installed templates

Installed templates in HAT database can be exported using XML commands. An installed template is invoked by specifying its name:

<template name="Costs: Costs by product"/>

All the analysis templates (Cards, Lines, Components, Time Functions and Component Functions) are available this way.

Available in HAT 5.1 and later.

<template type="cards">

<template type="cards">
  <!-- type attribute is required -->

  <selection>
    <dim num="1"> U </dim>
    <dim name="konto"> KAL|KAT </dim>
    <dim name="res enhet"> m/s katja </dim>
    <!-- dimensions can be referred by number or name -->

    <value> &lt;10000 </value>
    <value num="2"> 1000 </value>
    <value name="fim"> 1100 </value>
    <!-- value fields can be referred by number or name -->
    <!-- relational operators < and > need to be expressed as &lt; and &gt; -->

    <!-- other search tags that can be used in selection:
      <from>
      <to>
      <cardtitle>
      <linetext>
      <subset>
    -->

  </selection>

  <columns dim3="on" linetext="off" accum="off"/>
    <!-- attributes (on/off) for columns:
      card-id           (default "on")
      cardtitle         (default "on")
      linetext          (default "on")
      dim1 .. dim32     (default "on")
      value             (default "on", same as "value1")
      value1..value24   (default "on")
      notes             (default "off", HAT 5.3 and later)
      signatures        (default "off", HAT 5.3 and later)
    -->

  <contents lines="all"/>
    <!-- attributes (all/selected/none) for contents:
      groups     (default "selected")
      lines      (default "selected")
    -->

  <values decimals="3"/>
    <!-- decimal digits for values: from 0 to 6 -->

  <export-options wintitle="on"/>
    <!-- attributes for export-options:
      format    = "text" "html" "xml"  (default "xml")
      wintitle  = "on" "off"           (default "off")
      coltitles = "on" "off"           (default "off")
      notes     = "on" "off"           (default "off")
      headers   = "on" "off"           (default "on")
      datarows  = "on" "off"           (default "on")
      decsep    = ","  "."             (default from system)
      thousep   = " "  "."  ","  ""    (default from system)
    -->

</template>

<template type="lines">

<template type="lines">
  <!-- type attribute is required -->

  <selection>
    <dim num="1"> U </dim>
    <dim name="konto"> KAL|KAT </dim>
    <dim name="res enhet"> m/s katja </dim>
    <!-- dimensions can be referred by number or name -->

    <value> &lt;10000 </value>
    <value num="2"> 1000 </value>
    <value name="fim"> 1100 </value>
    <!-- value fields can be referred by number or name -->
    <!-- relational operators < and > need to be expressed as &lt; and &gt; -->

    <!-- other search tags that can be used in selection:
      <from>
      <to>
      <cardtitle>
      <linetext>
      <subset>
    -->

  </selection>

  <columns dim3="on" linetext="off" accum="off"/>
    <!-- attributes (on/off) for columns:
      card-id         (default "on")
      cardtitle       (default "on")
      linetext        (default "on")
      dim1 .. dim32   (default "off", except dim2 "on")
      value           (default "on")
      value2..value24 (default "off")
      accum           (default "on")
    -->

  <headers period="on" linecount="on" cardcount="off"/>
    <!-- attributes (on/off, default off) for headers:
      before
      positive
      negative
      period
      after
      linecount
      cardcount
      average
      median
      max
      min
      turnovertime
      turnoverrate
      variance              (HAT 5.1 and later)
      stddeviation          (HAT 5.1 and later)
    -->

  <values decimals="3"/>
    <!-- decimal digits for values: from 0 to 6 -->

  <export-options wintitle="on"/>
    <!-- attributes for export-options:
      format    = "text" "html" "xml"  (default "xml")
      wintitle  = "on" "off"           (default "off")
      coltitles = "on" "off"           (default "off")
      notes     = "on" "off"           (default "off")
      headers   = "on" "off"           (default "on")
      datarows  = "on" "off"           (default "on")
      decsep    = ","  "."             (default from system)
      thousep   = " "  "."  ","  ""    (default from system)
    -->

</template>

<template type="components">

<template type="components">
  <!-- type attribute is required -->

  <selection>
    <dim num="1"> U </dim>
    <dim name="konto"> KAL|KAT </dim>
    <dim name="res enhet"> m/s katja </dim>
    <!-- dimensions can be referred by number or name -->

    <value> &lt;10000 </value>
    <value num="2"> 1000 </value>
    <value name="fim"> 1100 </value>
    <!-- value fields can be referred by number or name -->
    <!-- relational operators < and > need to be expressed as &lt; and &gt; -->

    <!-- other search tags that can be used in selection:
      <from>
      <to>
      <cardtitle>
      <linetext>
      <subset>
    -->

  </selection>

  <valuefield name="fim"/>
    <!-- value field can be specified either by name or number -->

  <columns count="on"/>
    <!-- attributes (on/off) for columns:
      before        (default "off")
      negative      (default "off")
      positive      (default "off")
      period        (default "on")
      percentage    (default "off", HAT 5.1 and later)
      count         (default "off")
      atend         (default "off")
      after         (default "off")
      total         (default "off")
    -->

  <viewdim num="2" expand="all" structure="flat" filter="inuse"/>
    <!-- attributes for viewdim:
      num="2"            (number of the viewed dimension, default "2")
      name="account"     (name of the viewed dimension)
      expand="all"       (expand all sublevels)
      structure="flat"   (flatten the component hierarchy)
      filter="inuse"     (exclude unused components)
    -->

  <sort order="asc" column="count"/>
    <!-- attributes for sort:
      order="none"       (sort order, default "none")
            "desc"
            "combdesc"
            "absdesc"
            "absasc"
            "combasc"
            "asc"
      column="before"    (column to be used in sorting, default "period")
             "negative"
             "positive"
             "period"
             "percentage"      (HAT 5.1 and later)
             "count"
             "atend"
             "after"
             "total"
    -->

  <values decimals="3" sublevels="include"/>
    <!-- attributes for values:
      decimals="2"          (decimal digits for values form 0 to 6, default "2")
      sublevels="exclude"   (sublevel value inclusion, default "exclude")
                "include"
    -->

  <export-options wintitle="on"/>
    <!-- attributes for export-options:
      format    = "text" "html" "xml"  (default "xml")
      wintitle  = "on" "off"           (default "off")
      coltitles = "on" "off"           (default "off")
      notes     = "on" "off"           (default "off")
      headers   = "on" "off"           (default "on")
      datarows  = "on" "off"           (default "on")
      decsep    = ","  "."             (default from system)
      thousep   = " "  "."  ","  ""    (default from system)
    -->

</template>

XML_Command

This function passes a question to HAT and returns the result, both using xml syntax.

This function is defined in HAT's Database COM-object. To access it you need to first create a database object instance.

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 "Can't open file"
End If

' form a question in XML

Dim xmlin As String
Dim xmlout As String

xmlin = "<template type=" + Chr(34) + "lines" + Chr(34) + ">" _
      + "<selection>" _
      + "<dim num=" + Chr(34) + "2" + Chr(34) + ">KAL</dim>" _
      + "</selection>" _
      + "</template>"

xmlout = base.XML_Command(xmlin)

' process the xml result the way you want

MsgBox xmlout

' release the objects

Set base = Nothing

#include <stdio.h>
#include "iface.h"

void main ()
{
  CoInitialize (0);
  IDatabase *base = 0;
  IDimension *dim = 0;

  // create database object instance

  HRESULT hr = CoCreateInstance (CLSID_Database, 0,
    CLSCTX_LOCAL_SERVER, IID_IDatabase, (void**) &base);
  if (!SUCCEEDED(hr)) return;

  // declare variables and set up them

  BSTR fname = SysAllocString (L"c:\\hat\\example.hat");
  BSTR xmlin = SysAllocString (
         L"<template type=\"lines\">"
         L"<selection>"
         L"<dim num=\"2\">KAL</dim>"
         L"</selection>"
         L"</template>");
  BSTR xmlout = 0;
  long err = 0;

  if (base)   // open a HAT file
    {
      base->OpenFile (fname, 0, &err);
      if (err != errNone)
        printf ("Error opening file = %i\n", err);

      base->XML_Command (xmlin, &xmlout);

      // process the xml result the way you want 

      base->Release ();
    }

  // close and clean up

  SysFreeString (fname);
  SysFreeString (xmlin);
  SysFreeString (xmlout);
}