HAT 4.1 Macro Language Reference

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:

• Beep
• Close
• DeleteCards
• DeleteComponent
• DeleteData
• DeleteSubset
• DeleteTemplate
• ErrorFile
• Execute
• Export
• Import
• Modify
• OpenTemplate
• Password
• Print
• Quit
• Save
• Signature
• Transform

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

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.

DeleteComponent

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

Currently defined options:

-silent

do not generate error messages

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 the complete database
- global subset name
- anlysis template pathname (Cards and Lines only)

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.

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.

Parameter {filename} is a pathname for a file where the errors are stored.

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 opens or activates the given template, calculates it, exports it to the given file and finally closes the window.

Filename is optional; default filename is the template pathname

- on Macintosh:	the name separator : is converted to /
- on Windows:	the name separator : is converted to ;

Import

This command imports the given file into the database.

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.

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.

OpenTemplate

This command opens and calculates the given template.

This command is used similarly as "Open Directly" checkbox when installing a template. Using a command section inhibits the normal "Open Directly" feature.

It is not necessary to open a template using this command before using other template commands, e.g. Transform, DeleteData, Print or Export.

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

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 i 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 = Analyser
FB	file format = Browser
FZ+	file compression on
FZ-	file compression off
Fs	set database name and type
P+	include protection section
P-	exclude protection section
B+	include database settings section
B-	exclude database settings 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..12
D{dim}-	exclude this dimension section, {dim} = 1..12
D{dim}A	include only active components in this dimension, {dim} = 1..12
D{dim}U	include only components in use in this dimension, {dim} = 1..12
C+	include cards section
C-	exclude cards section
C{dim}C	use HAT-codes for this dimension in cards, {dim} = 1..12
C{dim}H	use host codes for this dimension in cards, {dim} = 1..12
C{dim}T	use component texts for this dimension in cards, {dim} = 1..12
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.

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
- anlysis 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={expr}	Value expression. Letter A refers to the current value, e.g. V=A*2
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

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

{template} = A full template pathname.
             Parts are separated by a colon (:).

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

    in macintosh:
      - Folders separated by a colon (:).
      - Partial pathnames begin with a colon which in most cases can be omitted.
      - Double colon (::) refers to the parent folder.
      - Full pathname uses format volume:folder:file, where the folder
        part (:folder) may occur zero or more times.
      - Filenames in macintosh are case insensitive.

    in windows:
      - Directories separated by a backslash (\).
      - Double point (..) refers to the parent directory.
      - Full pathname uses format drive:\dir\file, where the directory
        part (dir\) may occur zero or more times.
      - Filenames in windows 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-