## HAT 5 Macro Language Reference

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:

 Aggregate Beep Close DeleteCards DeleteComponent DeleteData DeleteMacro DeleteSavesetup HAT 5.1 and later DeleteSubset DeleteTemplate DimOptions HAT 5.3 and later DuplicateTemplate HAT 5.1 and later ErrorFile Execute Export Import Message Modify NewComponent HAT 5.3 and later OpenFile HAT 5.4 and later OpenTemplate OpenURL HAT 5.4 and later Password Print Quit Save Signature SortComponents HAT 5.3 and later Transform WebHATServer HAT 5.4 and later Write HAT 5.7 and later

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

### Aggregate

 Syntax: Aggregate {template} {option} {option} ... Examples: Aggregate MyCards -days Aggregate Base -years -title "Saldo of the year" Aggregate Base -monts -dim account 3 -dim 4 none

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:

 -onecard {date} Aggregate to a single card. The date for the new card can be given in {date} using YYMMDD format or date operators and offsets. -years Aggregate to a resolution of one year. -halfyears Aggregate to a resolution of half year. -tertials Aggregate to a resolution of four months. -quarters Aggregate to a resolution of three months. -2months Aggregate to a resolution of two months. -months Aggregate to a resolution of one month. -halfmonths Aggregate to a resolution of half month. -4weeks Aggregate to a resolution of four weeks. -3weeks Aggregate to a resolution of three weeks. -2weeks Aggregate to a resolution of two weeks. -weeks Aggregate to a resolution of weeks. -days Aggregate to a resolution of days. -cards Aggregate to a resolution of cards (default setting). -timescale {name} Aggregate to a resolution of a time scale. The time scale name is given in {name}. -title {text} Defines the text to be used for the aggregated cards. Text can be given in {text}. -periodnames A specification of each aggregation period is appended to the card title (default setting). -noperiodnames No specification of each aggregation period is appended to the card title. -duplicate The original lines are not deleted after creating the aggregated data. -keepzerolines Do not remove the aggregated lines with zero values. -skipzerolines Remove the aggregated lines with zero values (default setting). Available in HAT 5.1.1 and later. -keeplinetexts Do not remove line texts when aggregating. Available in HAT 5.1.1 and later. -skiplinetexts Remove line texts when aggregating (default setting). Available in HAT 5.1.1 and later. -dim {dim} {level} Aggregate a dimension. The dimension can be specified either by its number or its name. The {level} parameter indicates how many levels deep the dimension is preserved, removing the sublevels beneath. Specifying none as the level removes all dimension references. Available in HAT 5.3 and later.

### Beep

 Syntax: Beep Example: Beep

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

### Close

 Syntax: Close [{window}] Examples: Close Projects:Results:Totals 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

 Syntax: DeleteCards {fromCardID} {toCardID} Examples: DeleteCards 960301-001 961231-999 DeleteCards 960101 DeleteCards "" 961231

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

 Syntax: DeleteComponent {dim} {comp}   [-all]   [-unused]   [-silent] Examples: DeleteComponent Account KKM DeleteComponent 3 -all DeleteComponent 3 -unused DeleteComponent 4 TT -unused DeleteComponent 4 TTH -silent

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

 Syntax: DeleteData {template} Examples: DeleteData Cards:Outdated DeleteData Base

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

 Syntax: DeleteMacro {macro} {macro} ... Examples: DeleteMacro Update:Cards DeleteMacro -all

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

 Syntax: DeleteSavesetup {setup} {setup} ... Examples: DeleteSavesetup "stp01" DeleteSavesetup -all

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

 Syntax: DeleteSubset {subset} {subset} ... Examples: DeleteSubset "Outdated Cards" DeleteSubset -all

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

 Syntax: DeleteTemplate {template} {template} ...   [-all]   [-filter {string}] Examples: DeleteTemplate Cards:Outdated DeleteTemplate -all

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

 Syntax: DimOptions {dim}   [-singular {name}]   [-plural {name}]   [-codecase {strcase}]   [-textcase {strcase}]   [-hostcase {strcase}]   [-strings {stringformat}]   [-compulsory]   [-optional] Examples: DimOptions 2 -singular "Account" -plural "Accounts" DimOptions 2 -hostcase U DimOptions 6 -strings H DimOptions Accounts -compulsory

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
Alternatives D and W cannot be used with -codecase.

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

 Syntax: DuplicateTemplate {template} {newtemplate} Examples: DuplicateTemplate "Cards:Outdated" "To be checked"

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

 Syntax: ErrorFile {filename}   [-append]   [-nofile]   [-language {lang}]   [-verbose]   [-persistent] Examples: ErrorFile errors.txt -append ErrorFile errors.txt -language SWE ErrorFile "C:\Program Files\HAT\errors.txt" ErrorFile -nofile

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

 Syntax: Execute {macroname} Example: Execute "Update Cards"

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

 Syntax: Export {template} [{filename}]   [-file {filename}]   [-dir {directory}]   [-filter {templatefilter}]   [-skipEmpty]   [-append] Examples: Export MyLinesTemplate C:\hat\out\lines.txt Export Results -dir C:\hat\out -filter A201 Export NewProjects:Total -dir C:\hat\out -append

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

 Syntax: Import {filename}   [-s {importsetup}]   [-pw {password}]   [-dim {dim}] Examples: Import C:\hat\data.hat -pw sesam Import C:\hat\data*.txt -s ImportSetupForData Import C:\hat\accounts.txt -dim 2

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}.

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

 Syntax: Message {text}   [-title {title}]   [-seconds {secs}] Example: Message "The database has been updated." Message "OK" -title "Update" -seconds 30

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

 Syntax: Modify {template} {selector} ... Example: Modify MyLinesTemplate BD2 KKM

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

 Syntax: NewComponent {dim} {code} [{text} [{host}]]   [-silent] Examples: NewComponent Accounts KKMA NewComponent 2 KFR "Reserve parts" NewComponent 3 CCB "" 001010 -silent

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

 Syntax: OpenFile {filename} Example: OpenFile C:\hat\errors.txt

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

 Syntax: OpenTemplate {template}   [-current]   [-reopen]   [-skipEmpty]   [-filter {templatefilter}]   [-templates]   [-subsets] Example: OpenTemplate Projets:Results -reopen OpenTemplate -filter costs -skipEmpty

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

 Syntax: OpenURL {url} Example: OpenURL www.macrosoft.fi/hat/index.html

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.

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.

### Print

 Syntax: Print {template} Example: Print Projects:Totals:Results

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

 Syntax: Quit Example: Quit

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

### Save

 Syntax: Save {filename} {option} {option} ... Example: Save C:\data\ready.hat FN P- M- D2A

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

 Syntax: Signature {sign} Example: Signature JFK

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

 Syntax: SortComponents {dim} {comp}   [-sublevels]   [-reverse]   [-text]   [-host] Examples: SortComponents Account KKM SortComponents 3 -sublevels SortComponents 3 -text SortComponents 3 KK -sublevels -host -reverse

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

 Syntax: Transform {template} {option} {option} ... Examples: Transform MyLinesTemplate D3=\ VA=Value*2 Transform Base D4=\

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

 Syntax: WebHATServer [-start] [-stop] [-port {port}] Examples: WebHATServer -start -port 7412 WebHATServer -stop

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

 Syntax: Write {file} [{message}] [-time] [-clear] Examples: Write docs/exported.txt "Export started at" -time Write docs/exported.txt "Export completed" Write docs/exported.txt "Writing two\rlines" Write docs/exported.txt -clear

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.

There are two ways to write comments in macros:

 // 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-