Form template

Form templates are stored as text files with a TBC-extension. The file content is signed with a digital signature. Form templates are usually created on the server, signed and then sent to clients before starting any transactions. Upon receipt of a template file and verification of the digital signature, the client adds it to the list of template forms (Options/Submission Forms).

A template describes the properties of a screen form window (which is filled in by the client), e-mail message attributes (in which the query will be sent) and the requested variables. Each string of a form template can contain one keyword with one or more parameters. Lines that start with a semicolon (;) are treated as comments.

Window and Message Properties

The MSG keyword is used to define the properties of a screen form window and message attributes, other keywords are used to fill in the form. MSG keyword can have the following parameters:

Parameter	Description	Value
FORMTITLE	title of the screen form window	string value
FORMWIDTH	width of the window	numeric value
FORMHEIGHT	height of the window	numeric value
AREAWIDTH	width of the area inside a window, this area will be scrollable if it exceeds the window	numeric value
AREAHEIGHT	height of the area inside a window	numeric value
TO	e-mail address of destination server	string value
SUBJ	Subject filed of the message	string value
PRIORITY	priority type of the message	string value
ENCRYPT	whether the message should be encrypted	ON/OFF
SIGN	whether the message should be signed	ON/OFF
BATCH	whether this query is to be followed by more queries as part of a group submission
QUEUEOUT	do not send the message immediately, put it in the outbox
TPL	the query content is plain text
NFO	info added as plaintext before the encrypted data
FILEDLGTITLE	title for the file open dialog window for a VFILERE command
FILEDEFNAME	used by VFILERE to specify the file name that appears in the file open window when the window opens
FILEFILTER	used by VFILERE to determine which file masks will be available in the file open window
FILEDEFEXT	used by VFILERE, if you want a file extension automatically appended to the filename typed in the file open window

Query Content

Query content is the data that a user has entered while filling in the on-screen form. When the user clicks the OK button in a form, The Bat! creates an e-mail message with the query content. If stated in the form template, the message content will be signed and/or encrypted. The message will then be sent via e-mail to the server. The e-mail address of the server is also stated in the form template.

If the TPL parameter of a MSG keyword is not specified, the message body appears with an unlimited-length line and contains the form variables, which are separated by an ampersand ("&") character. The names of the variables are defined in the form template. The values of the variables are taken from the fields of the on-screen form, which the user has filled in before clicking OK. In the query string that is transmitted to server in the message body, the name and the value of a variable are separated by an equals sign ("=" character). E.g., if the query contains two variables, named servicetype and accountnumber, the first variable has the value "getaccountlog" and the second variable has the value "849780094"; in which case the message body will look like this:

servicetype=getaccountlog&accountnumber=849780094

This generation method for a query string conforms to RFC1866 (paragraph 8.2.1, application/x-www-form-urlencoded content-type).

The names and values of variables can contain any characters, but some characters should be "escaped" according to the following rules: the space character must be replaced by a plus sign character. Non-alphanumeric characters must be replaced by "%HH", a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks, as in multi-line text field values, are represented as CR LF pairs, i.e. "%0D%0A".

If the TPL parameter of a MSG keyword is specified, the query will be sent in human-readable plain text conforming to a given template. You can specify a multiline template where each additional TPL parameter adds a line to the template. Names of variables must be enclosed in $-characters, and will be replaced by the related values of the form data entries.

Overview of Form Elements

A screen form can contain such elements as input lines, lists, check-boxes, labels and buttons. All these elements are defined in a form template by means of keywords.

Keyword	Description
EDIT	single-line input field
MEMO	multi-line input field
CHECKBOX	standard list
LISTBOX	standard list
COMBOBOX	drop-down list

All of these elements define variables, one variable per element.

Beside them an invisible element - HIDDEN - is defined, which the user cannot change. Furthermore the visible element LABEL exists, which doesn't define a variable but gives the label (or name) for any visible element.

Two further elements are used to control the screen form: SUBMIT (the button that causes the query to be sent to server) and CANCEL (button that cancels and closes the form).

Overview of Element Parameters

Screen form elements have the following parameters:

Parameter	Description
X, Y	coordinates of the topmost left corner within a window
WIDTH, HEIGHT	the width and height of an element, most of the elements use default parameter values or they are calculated from the font height, so these parameters are optional)
NAME
VALUE
DEFTPL
VBODYRE	defines the name and value of variable, applies to all elements except LABEL, CHECKLISTBOX, SUBMIT and CANCEL

The EDIT element can have a MASK parameter that pre-defines the format of input and a PASSWORD parameter that causes it to display an asterisk character in place of any entered text; LISTBOX, COMBOBOX and CHECKLISTBOX elements can have an ITEM parameter that adds an item to the list; LABEL, CHECKBOX, SUBMIT and CANCEL elements can have a CAPTION parameter.

The LABEL element also has some other parameters: FOCUSNAME, which links the label to another element - if the value of the CAPTION argument of a label includes an accelerator key (an "&" prefix to the accelerator character) and SHOWACCEL is ON, the element named in the value of the FOCUSNAME parameter gains the focus when the user presses the accelerator key. The LABEL keyword can also have a JUSTIFY parameter, which specifies how text is aligned within the label. The value of JUSTIFY can be one of: LEFT (align text to the left side of the label), CENTER (center text horizontally in the label), RIGHT (align text to the right side of the label), WORDWRAP (allows the label to display multiple lines of text)

List of Form Elements

EDIT	Single-line input field. Use the EDIT element to put a standard Windows edit box control on the screen form. Edit boxes are used to retrieve information, which the client can type into an edit box. The client can be forced to enter only valid characters using a MASK parameter. The MASK can be also used to format the display of data. Mandatory parameters: X, Y, NAME; optional parameters: WIDTH, HEIGHT, VALUE, DEFTPL, VBODYRE, MASK, PASSWORD.
MEMO	Multi-line input field, which displays text to the client and permits the client to enter text into the application much like the EDIT component. The difference is that the MEMO element permits multiple lines to be entered or displayed, but doesn't permit masked input, unlike EDIT. Mandatory parameters: X, Y, NAME; optional parameters: WIDTH, HEIGHT, VALUE, DEFTPL, VBODYRE.
CHECKBOX	Switch. This element is used to present On/Off (Yes/No, True/False) options to the client, particularly where more than one choice is available at a time from a group of choices. The string value of the checkbox can be either "on" or "off". When the form is submitted with a value of "on", it will be sent as "name=on". Mandatory parameters: X, Y, NAME; optional parameters: WIDTH, HEIGHT, VALUE.
LISTBOX	Standard list. This element defines a Windows list box. A list box displays a list from which users can select one item. Mandatory parameters: X, Y, NAME; optional parameters: ITEM, WIDTH, HEIGHT, VALUE, COLUMNS.
COMBOBOX	Drop-down list. This element defines a list that has much in common with LISTBOX, but it drops down to allow one item to be selected. Mandatory parameters: X, Y, NAME; optional parameters: ITEM , WIDTH, HEIGHT, VALUE.
CHECKLISTBOX	Multiple-checkboxes list. This element is similar to a list box, except that each item has a check box next to it. Users can check or uncheck items in the list. Mandatory parameters: X, Y; optional parameters: ITEM , WIDTH, HEIGHT, COLUMNS.
HIDDEN	Hidden element. Allows embedded information within the form, which cannot be changed by the client. The NAME and VALUE parameters of this element will be sent to the server without modifications. Mandatory parameters: NAME, VALUE.
LABEL	Label. It displays text on a window. Usually this text labels some other element. Mandatory parameters: X, Y, CAPTION, optional parameters: WIDTH, HEIGHT, FOCUSNAME, JUSTIFY, SHOWACCEL, WORDWRAP.
SUBMIT	Submit button. When pressed, sends the contents of the form to the server. Mandatory parameters: X, Y, optional parameters: WIDTH, HEIGHT, CAPTION.
CANCEL	Cancel button. When pressed, closes the form and cancels client input. Mandatory parameters: X, Y, optional parameters: WIDTH, HEIGHT, CAPTION.

List of Element Parameters

X	Horizontal coordinate of the left edge of an element within a form. This is a mandatory parameter for all visible elements: EDIT, MEMO, CHECKBOX, LISTBOX, COMBOBOX, LABEL, SUBMIT, CANCEL, e.g. all except HIDDEN. Numeric value.
Y	Vertical coordinate of the top edge of an element within a form. Coordinates run from top to bottom. This is a mandatory parameter for all visible elements: EDIT, MEMO, CHECKBOX, LISTBOX, COMBOBOX, LABEL, SUBMIT, CANCEL, e.g. all except HIDDEN. Numeric value.
WIDTH	Width of an element. The width of all visible elements is set by default. This is an optional parameter for all visible elements: EDIT, MEMO, CHECKBOX, LISTBOX, COMBOBOX, LABEL, SUBMIT, CANCEL, e.g. all except HIDDEN. Numeric value.
HEIGHT	Height of an element. The height of all visible elements is set to a default value determined by the font height. This is an optional parameter for all visible elements: EDIT, MEMO, CHECKBOX, LISTBOX, COMBOBOX, LABEL, SUBMIT, CANCEL, e.g. all except HIDDEN. Numeric value.
NAME	Variable name. This is a mandatory parameter for EDIT, MEMO, CHECKBOX, LISTBOX and COMBOBOX. Numeric value.
VALUE	Default value. This is a mandatory parameter for HIDDEN and optional for EDIT, MEMO and CHECKBOX. String value.
CAPTION	Caption. This is a mandatory parameter for LABEL and CHECKBOX and optional for SUBMIT and CANCEL. String value.
FOCUSNAME	Name of the element to be focused by a label. It defines the element which links the label to another element - if the value of the CAPTION argument of a label includes an accelerator key ("&" character), the element named as the value of this parameter gains the focused when the user presses the accelerator key. This is an optional parameter for LABEL. String value.
JUSTIFY	Justifies label text. This parameter specifies how text is aligned within a label. This is an optional parameter for a LABEL. The value of JUSTIFY can be one of: LEFT (align text to the left side of the label), CENTER (center text horizontally in the label), RIGHT (align text to the right side of the label).
SHOWACCEL	Control the accelerator character. This parameter determines how an ampersand in the caption of a label appears. Boolean value. If value is ON, an ampersand appears as an underline under the character to its right in the caption indicating that the underlined character is an accelerator character. If value is OFF, the ampersand character appears as an ampersand.
ITEM	Defines an item of a list element: LISTBOX, COMBOBOX or CHECKLISTBOX. Use two comma-separated string values for LISTBOX, COMBOBOX and three for CHECKLISTBOX. The first value defines the item name, second - the item caption and the third argument (which applies only to CHECKLISTBOX) defines whether an item is checked (value is empty) or unchecked (value is not empty).
WORDWRAP	Multiple lines. Boolean value. Set WordWrap to ON to allow the label to display multiple line of text. When WordWrap is ON, text that is too wide for the label control wraps at the right margin and continues on additional lines. Set WordWrap to OFF to limit the label to a single line. When WordWrap is OFF, text that is too wide for the label appears truncated.
PASSWORD	Password input. If the value is ON, the EDIT control displays a special character (asterisk) in place of any entered text.
COLUMNS	Number of columns in a list element. This is an optional parameter for LISTBOX and CHECKLISTBOX elements. Numeric value. Use COLUMNS to specify the number of columns that are visible in a multi-column list box without having to use the horizontal scrollbar. Multi-column list boxes have a horizontal scrollbar that allows users to view multiple columns as they wrap. The default value for COLUMNS is 0, meaning that the list box is not multi-column. That is, users can only scroll vertically and the list of items will not wrap. For COLUMNS values greater than 0, multiple columns accommodate the items as they wrap beyond the bottom of the list box. The COLUMNS parameter specifies the number of columns that are visible without having to horizontally scroll the list box. The width of each column depends upon both the WIDTH parameter and the number of columns.
DEFTPL	Default value template. The VALUE parameter of the element will be set using macros. The difference from standard template macros is that the '#' character is used here as a prefix instead of '%'. E.g. DEFTPL="#FOLDERFROMNAME" as an argument of an EDIT element sets the VALUE of the element to the "FROM" name of the current folder's Identity properties. For use in EDIT, MEMO and HIDDEN elements.
VBODYRE	Default value: use a regular expression on message body. Similar to DEFTPL except that the value is not a template with macros but a regular expression. The match is performed on the text of the currently selected message, e.g. VBODYRE="^UserFullName: (.+)$".
VFILERE	Default value: regular expression on a particular text file. Similar to VBODYRE except that the value is extracted from a text file, not the message body. The user will be given a standard windows file open dialog to select a file.

MASK Parameter: Character-by-Character Validation

Use the MASK parameter to restrict the characters a user can enter into an EDIT element to valid characters and formats. If the user attempts to enter an invalid character, the edit control does not accept the character. Validation is performed on a character-by-character basis. Ensure that the contents of the MASK parameter don't start with an ampersand (&) character when using character-by-character validation. If the contents of a MASK parameter starts with an ampersand character, it is treated as advanced mask.

A mask consists of three fields separated by semicolons. The first part of the mask is the mask itself. The second part is the character that determines whether the literal characters of a mask are saved as part of the data. The third part of the mask is the character used to represent editable character positions in the mask.

!	If a '!' character appears in the mask, optional characters are represented as leading blanks. If a '!' character is not present, optional characters are represented as trailing blanks.
>	If a '>' character appears in the mask, all characters that follow are in uppercase until the end of the mask or until a '<' character is encountered.
<	If a '<' character appears in the mask, all characters that follow are in lowercase until the end of the mask or until a '>' character is encountered.
<>	If these two characters appear together in a mask, no case checking is done and the data is formatted with the case the user uses to enter the data.
\	The character that follows a '\' character is a literal character. Use this character to include any of the mask special characters as literal characters in the data.
L	The 'L' character forces a mandatory alphabetic character in this position. For the US, this is A-Z, a-z.
l	The 'l' character allows an optional alphabetic character in this position.
A	The 'A' character forces a mandatory alphanumeric character in this position. For the US, this is A-Z, a-z, 0-9.
a	The 'a' character allows an optional alphanumeric character in this position.
C	The 'C' character forces a mandatory arbitrary character in this position.
c	The 'c' character allows an optional arbitrary character in this position.
0	The '0' (zero) character forces a mandatory numeric character only in this position.
9	The '9' character allows an optional numeric character in this position.
#	The '#' character allows an optional numeric character or a plus or minus sign in this position.
:	The ':' character is used to separate hours, minutes, and seconds within time value strings. If the character that separates hours, minutes, and seconds is different in the regional settings of the Control Panel utility on your computer system, that character is used instead.
/	The '/' character is used to separate months, days, and years in date value strings. If the character that separates months, days, and years is different in the regional settings of the Control Panel utility on your computer system, that character is used instead.
;	The ';' character is used to separate the three fields of the mask.
_	The '_' character automatically inserts forced spaces into the text. When the user enters characters in the field, the cursor skips the _ character.

Any character that does not appear in the preceding table can appear in the first part of the mask as a literal character. Literal characters are copied exactly in the edit control. They are inserted automatically, and the cursor skips over them during editing. The special mask characters can also appear as literal characters if preceded by a backslash character (\).

The second field of the mask is a single character that indicates whether literal characters from the mask should be included as part of the text.

MASK Parameter: Advanced Use

If the contents of a MASK parameter starts with an ampersand character, it is treated as an advanced mask, so no character-by-character validation is done, and the contents are parsed in a different way. Characters following an ampersand up to an equal sign (or the end of the parameter) are treated as a keyword. Depending upon a keyword, the contents of an EDIT element can be checked for one of the following conditions

Keyword	Condition
URL	It is a valid URL
e-mail	It is a valid e-mail address
DATA	The data is the same as that of a given control. Useful for validating whether a password has been properly confirmed. E.g. MASK="&DATA=UserPasswordAgain=Password is not properly confirmed" compares the string entered by the user in an EDIT field named "UserPasswordAgain" and, if the two strings are not byte-for-byte equal, displays a "Password is not properly confirmed" error box.
REGEX	Matches given regular expression. E.g. MASK="&REGEX=^[a-fA-F0-9]{8}$" matches a string of exactly eight alphanumeric characters.
MANDATORY	Value cannot be empty. If a user leaves the field empty, an error box is displayed.

Example

Below is content of a sample TBC-file that can be used to receive a currency trend for a stated period. The screen form contains a drop-down list (COMBOBOX) for selecting the currency type and fields for date input (EDIT).

-----BEGIN PGP SIGNED MESSAGE-----

MSG FORMTITLE="Currency Rate Request"

MSG TO="Client-Bank <client-bank@bank.com>"

MSG SUBJ="Client-Bank"

MSG PRIORITY="High"

MSG FORMWIDTH=260

MSG FORMHEIGHT=190

MSG ENCRYPT=ON

MSG SIGN=ON

HIDDEN NAME="service" VALUE="getcurrencytrend"

LABEL CAPTION="&Currency" X=16 Y=8 FOCUSNAME="iso"

COMBOBOX NAME="iso" X=16 Y=24 WIDTH=120

COMBOBOX NAME="iso" ITEM="MDL","Moldavian Leu"

COMBOBOX NAME="iso" ITEM="USD","US Dollar"

COMBOBOX NAME="iso" ITEM="RUR","Russian Rouble"

COMBOBOX NAME="iso" ITEM="UAH","Ukrainean Hr."

COMBOBOX NAME="iso" ITEM="FIM","Finnish Mark"

COMBOBOX NAME="iso" ITEM="DEM","Deutche Mark"

COMBOBOX NAME="iso" ITEM="GBP","GB Pound"

LABEL CAPTION="&Starting Date" X=154 Y=8 FOCUSNAME="date1"

EDIT NAME="date1" X=154 Y=24

EDIT NAME="date1" MASK="00/00/0000" VALUE="01011996"

LABEL CAPTION="&Ending Date" X=154 Y=52 FOCUSNAME="date2"

EDIT NAME="date2" X=154 Y=68

EDIT NAME="date2" MASK="00/00/0000" VALUE="01011999"

SUBMIT CAPTION="OK" X=60 Y=112

CANCEL CAPTION="Cancel" X=154 Y=112

-----BEGIN PGP SIGNATURE-----

iQDVAwUANfjoiRQeqwtQAYtzAQHkIQX+JhO61HCBfVw5VF3KqQhpApmOPhk2gEKz

C7qkNwpx7lexjbZvTVNGNfxTk7cTx5AxSFiUV32JH9WPm9fuJ5/bXIfWojDnaYbi

OM/BqS2KykFyoiuy+KULji10oRTt1jdC0Yqyv+OMgo2RuMwI0QhUozpHlVvkEHkk

r3acZ3NVIjBZHdW0I4YCjA3FKxBQmoFsQg9/ndjeE2lHZTCtLK2Kue036PeSCJq1

JWwVgWwT0JfhfFMXjj5tZm7pspNaGLst

=FBRX

-----END PGP SIGNATURE-----

When the client clicks the OK button, The Bat! generates the following request line:

service=getcurrencytrend&iso=USD&date1=01011996&date2=01011999

Since the values of the ENCRYPT and SIGN parameters of the MSG keyword are set to ON, this string will be signed and encrypted before being sent to the server via e-mail (to client-bank@bank.com). The e-mail message body will look something like this:

-----BEGIN PGP MESSAGE-----

hMwDFB6rC1ABi3MBBgBuPwdXPA/obgJJ/fcjDSqO7oh820EHlKpA5mzbYSwg/qWg

wYvNO/iJq4mofSfUnwozK3S5dD4zSeNcEqzQzw3ZZpE5D8aLOlNRAKlRh2ZIfN4W

6pmLJrhcX/GvsH667YUfL97r8LCWbaBtYI8D85ZluPSNGzt8AIgjIEZLKaAcq6yD

eYpO5GpxvvDvT8Vb80QnUZW5kTX9MGFg+gtUGqcb3f3dibyewWZfjndhkjj4Br4I

QLQ5v0mjx76lqxhbi5qmAAABM3PfOx1lpLE7VkHCTuQSPsm09a69rjQqgKimOPxj

hcH8wKXAi2FYDQ8wY8iszRZ9IeDHJtqOsdr0vUltT0Mj0jGvWi1Jb/jFOZ0jW/2J

k1uFMo5Dy/gaGQjjCIZvRT2dWy7CQ67vnegTi2zsvMAPM6/Bz7qTA6lsMMY88E9p

4qDlcN6OZIlY8DGaExcIDpoZwPChgIQfA55VQyNfN5YKzfBxCmtqSWbbLFh7WnkR

8FBLi9E8rPGg2jmzfAn1CczYnlfXinHtuAKmxmt3m3bOyNv5SGmMz+9WWhWIBH8Q

XIBXrfH2yDDldKwkyj0tsjeXs6LFS7D/kMCdBNM1FClWw1EftTBbdwL0ykDX9Z6f

NS6fQxYJxGrfAMp7hSaGydrenSKEviAy5o6HyjBxoCqQLGKdsWQ=

=wflO

-----END PGP MESSAGE-----

Upon reception of the message, the server decrypts it, verifies the digital signature, extracts the request line, parses it and sends the currency trend back to the user.

If the TBC-file contained the following strings...

MSG TPL=" Service : $service$"

MSG TPL="Currency : $iso$"

MSG TPL=" Start : $date1$"

MSG TPL=" End : $date2$"

...then the query has been sent in a human-readable format, and the decrypted message body would have looked like:

Service : getcurrencytrend

Currency : MDL

Start : 01.01.1996

End : 01.01.1999

If the TBC-file had contained the following strings...

MSG NFO="This message contains your currency rates request"

MSG NFO="that will be sent to the bank. It is PGP-encrypted"

MSG NFO="to protect sensitive information. When you are online"

MSG NFO="press <Shift+F2> (Send Queued Mail item of Account menu)"

MSG NFO="to send the message."

... the message sent to the server would have looked like:

This message contains your currency rates request

that will be sent to the bank. It is PGP-encrypted

to protect sensitive information. When you are online

press <Shift+F2> (Send Queued Mail item of Account menu)

to send the message."