Submission Forms

(click HERE to get the same page in Russian)

Submission forms are a tool for creating queries that should be automatically processed. A query is actually a message with strictly defined fields and string variables.

The queries come from a user equipped with The Bat! software with form templates (files with a TBC-extension). Such a user is called the client. Before submitting a query, The Bat! asks the user to fill out a form, that looks very much like forms that you have probably filled out on the Web. The program that processes user requests is called a server. The Bat! transforms data filled in by the user to an e-mail message, encrypts and signs the message digitally. This message is sent to the server via e-mail. The address of the server is defined in a form template. The system of interacting of client and server by means of queries and replies is called The Bat! Client-Server.

This system is intended for remote access to data and managing data in off-line mode securely. The purpose of this system is to control bank accounts, make ticket and hotel reservations, etc. In order to provide secure transactions, encryption and digital signing is used (RSA/IDEA/MD5 algorithms), defined in RFC-1991. Server software is specific and depends on its tasks: Internet-shops, Banks or Ticket Reservation Agencies may use different types of server software, but the client, using The Bat!, can seamlessly use all of their services.

In order to provide a proper transaction, format of query fields must be equal on both client and server parts. As the server usually works with more then one client, the form templates (TBC-files) are usually being created on the server, signed and sent to clients before starting any transactions between the client and the server. While making transactions, the server can start new kinds of services for its users; in this case, the server would send any new versions of form templates in order for the client to be able to use those new services. Upon reception of a template file and verification of the digital signature, the client adds it to the list of template forms.

The presence of a digital signature is mandatory. It does not only ensure that the formats are equal on both client and server, but protects the system from intrusion of unauthorised templates. This unauthorised intrusion can come as a templates renewal and can cause all or a part of clients to have unauthorised templates instead of authorised ones. This can cause “freezing” of networks or information drain. The changing of a servers e-mail address in a form template can cause such a drain.

The Format of a Submission Form Template

Form templates are stored in a text file with a TBC-extension. The file content is signed by a digital signature. Form templates (TBC-files) are usually being created on the server, signed and sent to clients before starting any transactions. Upon reception of a template file and verifying the digital signature, the client adds it to the list of template forms (Options/Submission Forms). See introduction to learn more about 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 variables of request. Each string of a form template can contain one keyword with one or more parameters. Lines that start with “;” character are treated as comments.

Window and Message Properties

Keyword MSG 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: FORMTITLE (title of screen form window, string value), FORMWIDTH (width of the window, numeric value), FORMHEIGHT (height of the window, numeric value), AREAWIDTH (width of area inside a window, this are 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 the same similar query needed to be submitted after submitting the query), QUEUEOUT (do not send the message immediately; queue in outbox), TPL (query content is a plain human-readable text), NFO (info put as a plaintext before encrypted data)

Query Content

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

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

servicetype=getaccountlog&accountnumber=849780094

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

Names and values of variables can contain any characters, but some characters should be escaped according to the following rules: the space character should be replaced by a plus sign character. Non-alphanumeric characters are 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 TPL parameter of MSG keyword is specified, the query will be sent in a human-readable text according to a given template. You can specify multiline template, each additional TPL parameter adds a line to a template. Names of variables must be enclosed in $-characters, and will be replaced to respective values.

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: EDIT (single-line input field), MEMO (multi-line input field), CHECKBOX, LISTBOX (standard list), COMBOBOX (drop-down list) all of these elements define variables, one variable per element. Besides that, there is a special invisible element, HIDDEN the user cannot affect the value set by this element, and visible LABEL element that doesnt define a variable and is used as a label for any other visible element. Two elements are used to control the screen form: SUBMIT (button, that causes the query to be sent to server) and CANCEL (button, that cancels the form).

Overview of Element Parameters

Screen form elements can have the following parameters: X, Y (coordinates of topmost left corner within a window), WIDTH, HEIGHT (width and height of an element, most of the elements are defaulted or calculated from font height, so these parameters are optional), NAME, VALUE, DEFTPL, VBODYRE (defines name and value of variable, applies to all elements except LABEL, CHECKLISTBOX, SUBMIT and CANCEL). The EDIT element can have a MASK parameter that defines formatted input and PASSWORD parameter that allows 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.

Besides that, the LABEL element can have some extra parameters: FOCUSNAME, which links the label to another element - if the value of the CAPTION argument of a label includes an accelerator key (“&” character) and SHOWACCEL is ON, the element named as the value of the FOCUSNAME parameter becomes focused when the user presses the accelerator key. LABEL keyword can also have a JUSTIFY parameter, which specifies how text is aligned within the label. The value of JUSTIFY can be on 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 line of text)

List of Form Elements

`EDIT`	Single-line input field. Use EDIT element to put a standard Windows edit box control on the screen form. Edit boxes are used to retrieve information from client, because the client can type data into an edit box. The client can be forced to enter only valid characters using a MASK parameter. 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`	Muili-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 doesnt 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 at a time is available 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 and the only one item can be selected. Mandatory parameters: X, Y, NAME; optional parameters: ITEM , WIDTH, HEIGHT, VALUE.
`CHECKLISTBOX`	Multiple-checkboxes list. This element is 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. NAME and VALUE 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 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 top edge of an element within a form. Coordinates are incremented 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`	Width of an element. The width of all visible elements is set by default or by 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, COMBOBOX. Numeric value.
`VALUE`	Default value. This is a mandatory parameter for HIDDEN and optional for EDIT, MEMO è CHECKBOX. String value.
`CAPTION`	Caption. This is a mandatory parameter for LABEL and CHECKBOX and optional for SUBMIT è CANCEL. String value.
`FOCUSNAME`	Name of element to be focused by a label. It defines the element which links the label to another element - if the value of CAPTION argument of a label includes an accelerator key (“&” character), the element named as the value of this parameter becomes focused when the user presses the accelerator key. This is an optional parameter for LABEL. String value.
`JUSTIFY`	Justifies label text. This parameters specifies how text is aligned within the label. This is an optional parameter for LABEL. The value of JUSTIFY can be on 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 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 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. Have two coma-separated string values for LISTBOX, COMBOBOX and three for CHECKLISTBOX. First value defines item name, second - item caption and third argument (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 in 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 value is ON, 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, in a multi-column list box, that are visible 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 scroll only 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. Parameter COLUMNS 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. VALUE parameter of the element will be set using macros. Exceptions from standard macros is that # character is used here as a prefix instead of %. E.g. `DEFTPL="#FOLDERFROMNAME"` as an argument of EDIT element sets VALUE of the element to "FROM" name from the current folders Identity properties. To be used in EDIT, MEMO and HIDDEN elements.
`VBODYRE`	Default value: regular expression on message body. Similar to DEFTPL except value is not a template with nacros but a regular expression. The matching is done upon text of a currently selected message, e.g. `VBODYRE="^UserFullName: (.+)$"`.

MASK Parameter: Character-By-Character Validation

Use MASK parameter to restrict the characters a user can enter into 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. Be sure contents of MASK parameter doesn't start with ampersand (&) character when using character-by-character validation. If contents of MASK parameters starts with ampersand character, it is treated as advanced mask.

A mask consists of three fields with semicolons separating the fields. 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 unentered characters in the mask.

These are the special characters used in the first field of 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 use any of the mask special characters as a literal in the data.

L The L character requires an alphabetic character only in this position. For the US, this is A-Z, a-z.

l The l character permits only an alphabetic character in this position, but doesn't require it.

A The A character requires an alphanumeric character only in this position. For the US, this is A-Z, a-z, 0-9.

a The a character permits an alphanumeric character in this position, but doesn't require it.

C The C character requires an arbitrary character in this position.

c The c character permits an arbitrary character in this position, but doesn't require it.

0 The 0 character requires a numeric character only in this position.

9 The 9 character permits a numeric character in this position, but doesn't require it.

# The # character permits a numeric character or a plus or minus sign in this position, but doesn't require it.

: The : character is used to separate hours, minutes, and seconds in times. 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 dates. 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 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 must be matched 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 contents of MASK parameter starts with ampersand character, it is treated as advanced mask, so no character-by-character validation is done, and the contents are parsed different way: characters following ampersand up to equal sign (or end of parameter) are treated as a keyword. According to a keyword, contents of a EDIT element is checked upon one of the following conditions

Keyword Condition

URL Is a valid URL

EMAIL Is a valid e-mail

DATA Data is the same as of given control. Useful for validating whether a password is properly confirmed. E.g. MASK="&DATA=UserPasswordAgain=Password is not properly confirmed" compares the string entered by user in a EDIT named UserPasswordAgain and, if the two strings are not bitwise equal, displays 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 empty value, an error box is displayed.

Example

Below is content of a sample TBC-file that can be used to receive currency trend for a stated period. The screen form contains a drop-down list (COMBOBOX) for selecting 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

As values of ENCRYPT and SIGN parameters of 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 like this:

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 TBC-file had following strings...

MSG TPL=" Service : $service$" MSG TPL="Currency : $iso$" MSG TPL=" Start : $date1$" MSG TPL=" End : $date2$"

...query had been sent in a human-readable format, and decrypted message body had been looked like:

Service : getcurrencytrend Currency : MDL Start : 01.01.1996 End : 01.01.1999

If TBC-file had 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 had been 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."

`!`	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 use any of the mask special characters as a literal in the data.
`L`	The L character requires an alphabetic character only in this position. For the US, this is A-Z, a-z.
`l`	The l character permits only an alphabetic character in this position, but doesn't require it.
`A`	The A character requires an alphanumeric character only in this position. For the US, this is A-Z, a-z, 0-9.
`a`	The a character permits an alphanumeric character in this position, but doesn't require it.
`C`	The C character requires an arbitrary character in this position.
`c`	The c character permits an arbitrary character in this position, but doesn't require it.
`0`	The 0 character requires a numeric character only in this position.
`9`	The 9 character permits a numeric character in this position, but doesn't require it.
`#`	The # character permits a numeric character or a plus or minus sign in this position, but doesn't require it.
`:`	The : character is used to separate hours, minutes, and seconds in times. 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 dates. 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 spaces into the text. When the user enters characters in the field, the cursor skips the _ character.

Keyword	Condition
`URL`	Is a valid URL
`EMAIL`	Is a valid e-mail
`DATA`	Data is the same as of given control. Useful for validating whether a password is properly confirmed. E.g. `MASK="&DATA=UserPasswordAgain=Password is not properly confirmed"` compares the string entered by user in a EDIT named `UserPasswordAgain` and, if the two strings are not bitwise equal, displays `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 empty value, an error box is displayed.