The built-in macro language in HAT consist of text lines defining commands. Each line of text defines a single command with its options. Options are serapated by whitespace (space and tab characters). The number of whitespace characters between the options does not matter. Options including a space character must be enclosed in "double quotes". An empty option can be defined by "".

Command names are not sensitive to case. For example, ErrorFile and errorfile both are correct forms. Note however, that many options are case sensitive.

Currently defined commands:

How to write comments in macros.
Some syntax clarifications.
An example macro.

Aggregate

This command opens or activates the given template, calculates it, aggregates all data in that window and finally closes the window.

{template} can be:
- Base which means the complete database
- global subset name
- analysis template pathname (Cards and Lines only)

Following options are currently defined:

Beep

This command plays a simple beep signal on the system speaker.

Close

This command closes the given window. Changes made to that window are lost.

Close command without any parameters closes the current database. Database is closed after all other commands have completed their execution. Changes made to that database are lost.

DeleteCards

This command deletes cards inside given Card ID interval from the database. Card IDs can be partial and even totally omitted, in that case they are completed the same way as when entered in the Card ID fields in the analyses.

Date operators File, Year, Month, Day and Reference are available in HAT 5.4 and later.

DeleteComponent

This command deletes components in dimension {dim}. The dimension can be specified either by its number or its name. The component is specified by its HAT-code in {comp}. A group of components can be deleted by specifying their parent component. Components in use by cards and lines cannot be deleted.

To delete all components in a given dimension use option -all. In that case parameter {comp} can be empty. Note that if there are any components in use in this dimension this command does nothing and an error message is displayed.

To delete unused (inactive) components in a given dimension use option -unused. Parameter {comp} can be used to define a group of components or left empty which means all unused components in this dimension.

If you don't want any error messages to be displayed use the -silent option.

DeleteData

This command opens or activates the given template, calculates it, deletes all data in that window and finally closes the window.

{template} can be:
- Base which means all cards and lines in the database
- global subset name
- analysis template pathname (Cards and Lines templates only)

This command only deletes cards and lines. It does not delete dimension components or any other parts of the database. When Base option is used, the base window is not closed.

DeleteMacro

This command deletes macros.

Macros can be specified by name, group name or by using following options:

-all	all macros are deleted
-filter {string}	only macros whose name matches the key string

Multiple macros and options can be specified in a single command.

DeleteSavesetup

This command deletes save setups.

Save setups can be specified by name or by using following options:

-all	all save setups are deleted
-filter {string}	only save setups whose name matches the key string

Multiple save setups and options can be specified in a single command.

This command is available in HAT 5.1 and later.

DeleteSubset

This command deletes global subsets.

Subsets can be specified by name or by using following options:

-all	all subset are deleted
-filter {string}	only subsets matching the key string

Multiple subsets and options can be specified in a single command.

DeleteTemplate

This command deletes analysis templates.

Templates can be specified by name, group name or by using following options:

-all	all templates are deleted
-filter {string}	only templates whose name matches the key string

Multiple templates and options can be specified in a single command.

DimOptions

This command changes settings for a dimension.

The dimension can be specified either by its number or name in {dim}.

Options -singular and -plural can be used to set singular and plural forms of the dimension name. Using name default restores the default name.

Character case settings can be specified with -codecase, -textcase and -hostcase.
Currently defined alternatives are

   U  = Uppercase
   L  = Lowercase
   D  = Default format: first character uppercase
   W  = Words: first character of each word uppercase
   S  = Case Sensitive
   N  = Case Nonsensitive

Option -strings can be used to set the string format for dimension components in analyses.
Currently defined alternatives are

   C   = Code
   H   = Host
   T   = Text
   CT  = Code Text  (this is the default setting)
   HT  = Host Text
   CH  = Code Host
   CHT = Code Host Text

This command is available in HAT 5.3 and later.

DuplicateTemplate

This command duplicates an analysis template.

If the destination template name already exists this command does nothing.

This command is available in HAT 5.1 and later.

ErrorFile

This command defines a log file for error messages.

Normally error messages are displayed interactively on screen. This command causes subsequent error messages to be stored in a file. The previous error log file is closed. Logging to this file goes on until the last file is read in.

Parameter {filename} is a pathname for a file where the errors are stored. It may be a full pathname or a partial pathname and must follow the rules of the host operating system. Partial pathnames start from the directory where the database file is located.

Note: if the filename contains space characters it must be enclosed in double quotes (").

Currently defined options:

-append	New messages are appended to the end of the previous file
-nofile	Discard error messages, no file is created
-language {lang}	Use language {lang} currently defined languages: US English DAN Danish FIN Finnish GER German NOR Norwegian FRA French SWE Swedish Otherwise the user's current language is used.	HAT 5.3 and later
-verbose	Generate a verbose, more detailed log. Verbose log is always in English.	HAT 5.3 and later
-persistent	Keep logging after the file has been read	HAT 5.3 and later

Execute

This command executes the macro given in parameter {macroname}. If the macro name contains space characters, the name must be enclosed in double quote marks.

Note: recursive (circular) calls are not supported.

Export

This command exports analysis data contents to a file.

The {template} reference can be either a single template pathname or a template group. If a template group is specified, all the templates inside this group are exported. {templatefilter} can be used to limit the template selection inside this group. The {template} parameter can be omitted, in which case all templates are exported. However, executing a single command "Export" with no options exports nothing.

The -file {filename} option can be used to specify where the exported data should be stored. The {filename} option has a default value that is same as the template name. If the {directory} parameter is specified then the default filename is only the leaf part of the template name. Otherwise a complete template pathname is used.

Characters that are not allowed in current filesystem are converted:

- on windows:	the name separator : is converted to ;
- on mac OS X:	the name separator : is converted to \
- on mac classic:	the name separator : is converted to /

More details on filenames in different platforms can be found here.

The -dir {directory} option can be used to specify the directory where the exported data files should be stored. It is especially usefull when exporting many templates in a single export command (template group).

The -filter {templatefilter} option can be used to limit which templates in a template group are exported. It works like any other filter string in HAT: both simple form and a more advanced form can be used. The simple form searches the specified string in the pathname and accepts it if the string is found somewhere. See User's Manual for documentation on Advanced text searching.

The -skipEmpty option can be used disable export of empty templates, ie templates with no data rows. This option is available in HAT 5.7 and later.

The -append option can be used to specify that the exported lines should be appended to the previous file contents. It only works with textfiles (numeric presentation).

Note: This command is available in HAT 5.1.1 and later.

HAT 5.1 and earlier supported a more limited version of Export command

Syntax:

Export {template} [{filename}]

Note that none of the options were supported and only a single template could be exported in one command. However, the current form is fully backwards compatible with the old form.

Import

This command imports files into the database.

Multiple files can be specified by using wildcard characters * and ?. Wildcard characters can only be used in the last part of the name (leafname).
? matches any single character.
* matches any sequense of characters, including none.
Note: Wildcard characters are available in HAT 5.3 and later.

Partial pathnames can also be used. Database file location is used as a starting point for partial pathnames. More details how to write file references are under clarifications.

An import setup can optionally be specified in {importsetup}.

Opening password can optionally be specified in {passowrd}. If imported file is password protected and no password is given here, the password is asked from the user.
Note for security that password is given here in plain text.

Option -dim can be used to import dimension components. Dimension number (1..32) or dimension name is specified in {dim}. If there is an import setup defined for the specified dimension, the file will be imported using it.

Message

This command displays a message window on the screen. The message text is given in the parameter {text}. Embedded carriage returns can be written as //.

The optional title is given in the parameter {title}. If no title is specified, the macro name is displayed on the title bar.

An optional timeout can be given with the {secs} parameter. The message dialog is automatically dismissed after the specified number of seconds have elapsed.

Modify

This command modifies a subset or template specified by the {template} parameter. The syntax used for {selector} depends on the template type and is the same as in the template sections, but fields are separated by whitespace.

As a side effect this command closes the subset or analysis window if it was open.

NewComponent

This command creates a new component in a dimension.

The dimension can be specified either by its number or name in {dim}.
The HAT-code for the new component is given in {code}.
The component text (optional) is given in {text}.
The host code (optional) is given in {host}.

If you don't want any error messages to be displayed use the -silent option.

If you want to create thousands of components, it is more efficient to store them in a file and import them using a single Import command.

This command is available in HAT 5.3 and later.

OpenFile

This command opens a file or folder.

Partial pathname can also be used. Database file location is used as a starting point for partial pathname. More details how to write file references are under clarifications.

The operating system chooses its default application according to the file type. If no default application is defined for a given file, the system will ask which application to use to open the file.

This command is available in HAT 5.4 and later.

OpenTemplate

This command opens and calculates the given template.

{template} can be:
- analysis template pathname
- analysis template group pathname
- global subset name

Currently defined options:

-current	activate curretly open window
-reopen	close the current window and open a new
-skipEmpty	do not open a template that contains no data
-filter	only open templates that match a criteria	HAT 5.4 and later
-templates	open all templates	HAT 5.4 and later
-subsets	open all global subsets	HAT 5.4 and later

The -current and -reopen options can be used to avoid dialog when opening a template that is already open. -current option preserves current settings which may differ from the installed settings in the template. -reopen option closes the previous window and opens a fresh window with exactly the same settings as in the installed template.

The -skipEmpty option can be used to automatically close a template that does not contain any data. In Components analysis there must be at least one component with nonzero line count. In Time and Component Functions there must be at least one nonzero value.

The -filter {templatefilter} option can be used to limit which templates in a template group are opened. It works like any other filter string in HAT: both simple form and a more advanced form can be used. The simple form searches the specified string in the pathname and accepts it if the string is found somewhere. See User's Manual for documentation on Advanced text searching.

This command is used similarly as "Open Directly" checkbox when installing a template.

It is not necessary to explicitly open a template before using other commands that operate on template data, e.g. Print, Export, Transform, Aggregate or DeleteData.

OpenURL

This command opens a web location.

The operating system chooses which application is used to view the web location.

This command is available in HAT 5.4 and later.

Password

This command defines a password for the current database. The password is used to protect a database file. Passwords are not sensitive to case, e.g. "sesam" and "SESAM" are equal.

{password} is the new password.

Print

This command opens or activates the given template, calculates it, prints it to the current printer and finally closes the window.

A group of templates can be specified as well. In that case all the templates in the specified group are printed.

Quit

This command terminates the application after all other commands have completed their execution. Changes made to any open database are lost.

Save

This command saves a copy of the current database in a file using the given name and options.

Note that options for this command are case sensitive.

Following options are currently defined:

FT	file format = Text
FN	file format = Normal
FB	file format = Browser
FZ+	file compression on
FZ-	file compression off
Fs	set database name and type
X+	include all sections (HAT 5.6.4 and later)
X-	exclude all sections (HAT 5.6.4 and later)
P+	include protection section
P-	exclude protection section
c+	include characters section (HAT 5.6.4 and later)
c-	exclude characters section (HAT 5.6.4 and later)
B+	include database settings section
B-	exclude database settings section
W+	include web users section
W-	exclude web users section
s+	include save setup sections
s-	exclude save setup sections
s={name}	use save setup named {name}
I+	include import setup sections
I-	exclude import setup sections
S+	include time scale sections
S-	exclude time scale sections
M+	include macro sections
M-	exclude macro sections
D+	include dimension sections
D-	exclude all dimension sections
D{dim}+	include this dimension section, {dim} = 1..32
D{dim}-	exclude this dimension section, {dim} = 1..32
D{dim}A	include only active components in this dimension, {dim} = 1..32
D{dim}U	include only components in use in this dimension, {dim} = 1..32
C+	include cards section
C-	exclude cards section
C{dim}C	use HAT-codes for this dimension in cards, {dim} = 1..32
C{dim}H	use host codes for this dimension in cards, {dim} = 1..32
C{dim}T	use component texts for this dimension in cards, {dim} = 1..32
CT	include cards/lines referred in templates only
U+	include global subsets
U-	exclude global subsets
T+	include template section
T-	exclude template section
TO	include open templates only
T={filter}	template filter string
F+	include analysis defaults section
F-	exclude analysis defaults section

Signature

This command defines a signature to be used in data operations. Defining the signature this way avoids a dialog when the signature is first needed. Signature is needed when the cards are modified.

{sign} is the signature, max 3 characters.

SortComponents

This command sorts dimension components.

The dimension can be specified in {dim} by either its number or name.

The component is specified in {comp} by its HAT-code. This command will sort the subcomponents of that component. Highest level of components can be sorted by leaving the component empty.

By default this command sorts only one hierarchy level. The option -sublevels can be used to sort all underlying levels in a recursive manner.

The option -reverse can be used to sort in falling order.

By default the HAT-codes are used to define sort order. The option -text can be used to sort according to the component texts and -host to sort according to the component host codes.

This command is available in HAT 5.3 and later.

Transform

This command opens or activates the given template, calculates it, transforms all data in that window and finally closes the window.

{template} can be:
- Base which means the complete database
- global subset name
- analysis template pathname (Cards and Lines only)

Following options are currently defined:

A	Add a transformed duplicate
D{dim}={expr}	Dimension expression, e.g. D3=\ clears dimension 3.
V{val}={expr}	Value expression. {val} is from A to X and refers to the value fields on each line. Value field titles are used to refer to the current values. Characters from A to X can also be used.
CB={expr}	Card-ID source "Start" expression
CE={expr}	Card-ID source "End" expression
CF={expr}	Card-ID destination "Start" expression
CT={expr}	Card-ID destination "End" expression
TF={expr}	Card title "From" expression
TT={expr}	Card title "To" expression
LF={expr}	Line text "From" expression
LT={expr}	Line text "To" expression
NF={expr}	Notes "From" expression
NT={expr}	Notes "To" expression
XR	Clear Created and Modified signatures (HAT 5.7 and later)
XE	Clear Examined signatures (HAT 5.7 and later)
XA	Clear Approved signatures (HAT 5.7 and later)
XN	Clear Notes signatures (HAT 5.7 and later)

WebHATServer

This command controls the Web-HAT server component in HAT.

The server can be started and stopped using options -start and -stop.

The -port option can be used to set tcp port for hat.cgi gateway. Port numbers greater than 80 are accepted.

By using this command it is possible to start many instanses of HAT that serve different tcp ports thus allowing many Web-HAT servers to run on a single computer.

This command is available in HAT 5.4 and later.

Write

This command writes a text message to a file.
The message is appended to the end of the file's current contents.

A line break can be embedded using \r notation.
A tab character can be embedded using \t notation.

The -time option can be used to write current date and time.

The -clear option can be used to clear the previous file contents.

This command is available in HAT 5.7 and later.

Comments

//	Comment line: the text to the right of this operator on the same line is ignored
/*	Start of a comment block which can span over many lines. The block is ignored.
*/	End of a comment block

Some clarifications for syntax used above:

{dim}      = dimension number in range 1 to 32.
               note: maximum number of dimensions
               HAT 5.0    16
               HAT 5.1    24
               HAT 5.2    32

{template} = a full template pathname
             hierarchy levels are separated by a colon (:)

{filename} = a valid file pathname, either full or partial pathname.
             Partial pathnames start at the directory where the database
             file is located.

    in Windows:
      - directories are separated by backslashes (\)
      - double point (..) refers to parent directory
      - there are two syntaxes for full pathnames:
          DOS:  drive:\dir\file
          UNC:  \\computer\dir\file
        where the directory part (dir\) may occur zero or more times
      - characters that must not be used in names .:/\
      - filenames in Windows are case insensitive

    in Macintosh OS X:
      - folders are separated by slashes (/)
      - double point (..) refers to parent directory
      - full pathnames begin with a slash
      - disks and network volumes can be accessed using full pathname syntax:
          /Volumes/disk/folder/file
      - current user's home folder is denoted by tilde (~)
          ~/desktop/data.hat
      - filenames beginning with a dot (.) are invisible (not shown in Finder)
      - most filenames in OS X are case insensitive
          UFS partitions are case sensitive

    in Macintosh classic (System 8 and 9):
      - folders are separated by colons (:)
      - partial pathnames begin with a colon which in most cases can be omitted
      - double colon (::) refers to parent folder
      - full pathname syntax is volume:folder:file, where the folder
        part (folder:) may occur zero or more times
      - filenames in Macintosh are case insensitive

An example of a macro:

// global definitions
Signature  AG
ErrorFile -nofile

// remove outdated cards and lines
DeleteCards  950101  951231
DeleteData   Filters:Subsets:Badcards

// import the new fresh data in
Import  "C:\data\new\update.hat"  -pw bingo

// save the result file
Save  "C:\data\ready.hat"  FN   P-  M-