Validated as a Pure HTML 3.2
Information in this online help system is subject to change without notice and does not represent a commitment on the part of RITLABS S.R.L.. The software and/or files described in this online help system are furnished under a license agreement or nondisclosure agreement. The software and/or files may be used or copied only in accordance with the terms of the agreement. The purchaser may make one copy of the software for backup purposes. No part of this online help system may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information and retrieval systems, for any purpose other than the purchaser's personal use, without the written permission of RITLABS S.R.L..
RITLABS S.R.L. may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property rights except as expressly provided in any written license agreement from RITLABS S.R.L..
Copyright © 1997-2000 RITLABS S.R.L.. All rights reserved.
The Internet is a global computer network, covering the entire globe. The Internet evolves as if it is a core, ensuring the correct interrelationship of different information networks, belonging to various organisations around the world.
The first networks were used solely for the transmission of files and e-mail, but today it resolves the more complex problems of shared access to resources. Several years ago, programs were created to support the necessary functions of network search, and access to shared information resources, and electronic archives.
The Internet, was initially only used by research groups and educational establishments whose interests spread up to the access to supercomputers. These resources became all very popular in the business world, and in no time the Internet has grown phenomenally
Big companies were seduced by this quick and easy global connection, well suited to group-work, centralised programs, and a single database over the Internet networks. They considered a global network as an addendum to their own local networks. With the low service costs (often only a fixed monthly charge for lines used, or telephone charges) users are able to gain access to commercial and non-profit information services from across the USA, Canada, Australia and many European, and other countries. Using the Internet it is possible find information on practically any sphere of human activity, in the "free access" archives, from new scientific openings, to the weather forecast for tomorrow.
Besides all this, the Internet offers a unique possibility of cheap, reliable and confidential global communication with the whole world. This turns out to be extremely efficient for companies having various sites around the world, international corporations, and other organisations. Usually, using an Internet infrastructure for all international communications is vastly cheaper than direct computer communication through a satellite link or telephone lines.
E-mail is the most widespread service on the Internet. Sending e-mail messages over the Internet is vastly cheaper than more conventional means. Besides, messages sent on the Internet will arrive in several hours, while other messages (snail mail) can get to the addressee several days later, or even several weeks later.
The Bat! is an Internet e-mail program. Major objectives of The Bat! are:
- Providing an efficient way of processing large message flows;
- Easy-to-use user interface;
- Allowing users to work easily with several mail accounts with the possibility of exchanging messages between them;
- Maximum reduction of delays while working. The Bat! extensively uses Window's multitasking capabilities. This means that the user can send and receive e-mail while reading or writing other mail;
- Providing truly multi-lingual interface. The Bat! can communicate with the user using various languages - the interface's language can be chosen from the main program menu.
The Bat! also allows the user to process mail right on the mail server - without actually downloading messages to the local hard drive. Encrypted log-in to POP3 servers (APOP command - to avoid the transmission of account password 'open') and IMAP4 protocol is supported, and The Bat! has a comfortable editor with many useful functions, Address Book and provides extensive set of tools for processing mail.
The program has been developed mainly for business messaging, which is why we tried to provide as comfortable an interface as possible, without messing the workplace up with excessive interface elements used rarely or for entertainment purposes.
Major features of The Bat! are:
- Real-time automatic spellchecker. As you type, it underlines questionable spellings, and a single right click will let you choose the correct spelling.
- Full 32 bit multi-threading. You can check mail on all of your accounts, and write/read messages at the same time.
- Fast, browser-independent HTML Mail viewer.
- Quick Templates allow to save hours of typing and numerous keystrokes by inserting text blocks (even from files on your disks) and message-dependent information as well as attaching files and vCards without using menu commands.
- Threading messages by reference, subject, sender and recipient. This feature is especially handy for subscribers of discussion mailing lists.
- Mail Ticker™ is a feature seen nowhere else. It looks like a Wall Street stock ticker, but it shows you the header info from your new messages - From, To, Subject etc..
- Powerful Filtering System. Pass data to external programs, auto-responders, macro enhanced templates for auto-responders, kill filters etc..
- Filters and Macros are so powerful that allow you to turn the e-mail client into a mailing list server. For example, you can run mailing lists as well as full-fledged discussion lists like MajorDomo and Listserv. All you have to do is check the POP3 account, and it will filter, modify, correct the To:, From: and Reply To: headers, then mails it out to everyone on the list. One of lists running this way is called "The Bat! User's Discussion List" (see home page).
- Internal PGP implementation based on award-winning SSLeay library. Allows you to encrypt messages, sign them with digital signatures, etc. Handy manager of digital keys. Plus free plugins for PGP v5.5 & v6.0.2.
- Multiple accounts that can be changed on the fly. There's more, each folder you create to save messages in can have it's own identity (To, From, Reply-to), macro enhanced templates etc.. This is my most favourite aspect of The Bat! You can make it do just about anything.
- Automatic mail retrieval w/auto log-off
- It can import your messages with the built in import wizard from:
Microsoft Outlook Express v4.xx
Netscape Communicator v4.xx
Netscape Mail v2.xx/3.xx
Eudora Lite/Pro
Pegasus Mail v2.xx
- It can import address books from any client that can export to an:
.INI
Comma Separated File
Tab Separated File
- Support of ten different interface languages, with the capability to switch between them on the fly.
- An unique park function, where you can make a message stay where it is at. No accidental deletions or moving it to the wrong folder.
- An address book function that let's you choose e-mail addresses very similar to the way you run programs from the Windows Start button or choose favourites from the favourites dropdown menu. The address book also supports vCard files and LDAP directories as well as being able to place actual pictures of your contacts in the address book. Another feature is the ability to define macro enabled templates for *each* contact in your address book. That means you can personalise your messages for each individual person.
- A built in search engine displays your results in a logical, easy to use format.
- Mail Dispatcher allows you to manage your mail directly on the POP3 server.
- Provides an easy and cheap corporate mailing network server solution (multi-user capabilities), that allows to work without a local mail server.
- Submission Forms - a tool for creating queries that should be automatically processed. A great solution for business client-server based environment.
- Dial-up networking support, mail notification, message actions, live URLs, nested folders, smart drag & drop, and more!
The Bat! supports two ways of connecting to the Internet
Auto-disconnect after mail transmission - Use this option if you do not want to remain on-line when The Bat! finishes dealing with mail transmission. This feature is almost useful when you are using periodical mail retrieval (especially when you have to pay for call to your ISP).
Pause between dialling session - This value determines the minimal time interval between two consecutive dialling sessions. Using of this feature is essential in multi-user environment with only one dial-out machine - it prevents the dial-out machine to dial the ISP unnecessarily often. Note that manual requests of mail retrieval from dial-out machine will initiate dialling even in the pause time
If a machine is connecting to the Internet by either LAN or Dial-up networking and it is intended to retrieve and send mail for all accounts defined in The Bat!, the status of your machine is TCP/IP or Dial-out Server.
If a machine does not have TCP/IP protocol installed and it is a part of a network with TCP/IP or Dial-out Server, it must have status of Non-TCP/IP Workstation.
See also:
Working in Multi-User Environment
The Bat! Networking Course
POP (Post Office Protocol) - a post office protocol is used for retrieving mail from host by client.
Once you have an e-mail address, your ISP should give you a user name (which is usually the same as the part of your e-mail address before @ symbol) and a password to access your mailbox on the mail server, and the address of the POP server.
This information should be entered in the account properties, in the appropriate fields. The password may be left blank if you want to enter your POP password each time you check for new mail.
SMTP (Simple Mail Transfer Protocol) - a simple protocol for mail transmission which is widely used on the Internet. The SMTP server's function is to receive mail from other servers and clients, and to deliver mail to other hosts and to its clients mailboxes.
Usually, the address of an SMTP server is provided by your system administrator or Internet Service Provider. However, you may use other SMTP servers available on the Internet known to you, since SMTP does not require any special authorisation.
On the Internet, each user has a unique address (some people have more than one e-mail address) which identifies the mail server or zone address, and the name of the mailbox. The usual structure of an e-mail address is <user name>@<mail server/zone>, e.g., john.smith@ritlabs.com. E-mail addresses cannot be anything like John Smith or John Smith from Magic Island
Invoke Address Book command on the Tools menu in the main program window, or click the appropriate button on the main window toolbar.
Invoke New Address entry in the Edit menu in Address Book.
Edit user's data, especially his name and e-mail address - all other fields are optional.
The new entry may be added to the Pop-up menu of address entry fields, if the check box Add to Pop-up menu is checked.
Account settings are divided into the following sections:
General settings
Transport settings
Advanced Transport settings
Preferences
Files and directories
Message templates
Notification of new mail arrival (sound)
Sorting Office / Filters
Each e-mail account set-up in The Bat! has its own folder structure which is used for storing incoming, outgoing and sent messages. Other folders may have any name (depending on their use) but there always are four default folders, which cannot be deleted or renamed. These folders are:
| Inbox | the default incoming mail folder |
| Outbox | the outgoing mail folder |
| Sent | default folder for sent mail |
| Trash | folder for storing deleted messages before they are removed permanently |
This section is for setting up the title of an e-mail account, as it appears in The Bat!'s account list, and the data used for generating the sender's data in message headers.
Name - the name of the e-mail account. It may be any combination of characters. The only limitation is that the name must be unique within the program; in other words, there must not be another account with the same name
From name - the originator's name, which will be put in the header of each message created for the account
From address - originator's e-mail address
Organisation - organisation to which originator belongs (if any)
Reply name - the name of the person to which replies must be sent. Usually it is the same as the originator's name
Reply address - the e-mail address used for replies to the original e-mail. (return address, and the address to which confirmation must be sent)
Notes:
Avoid using characters disallowed in system file names (such as +,"/\><|) in accounts name. Otherwise, non-default directory names for disk storage must be used.
Try to use only ASCII characters in From and Reply names - this will help to avoid problems with some mail servers which don't allow of non-ASCII characters in message headers.
SMTP server - the address of your SMTP server to which all outgoing e-mail messages from the account must be sent. The address may be represented as a traditional URL (e.g.: mail.ritlabs.com) or as an IP numeric address (e.g. 193.219.214.38); if an IP address is used you should be aware that sometimes it may be changed. The advantage of using of IP addresses is that a DNS lookup is not used, thus it is slightly faster on connecting to the server. Generally speaking, if there are several mail accounts set in the program, it is possible to use just one SMTP server for sending messages from all accounts.
POP3 server - the address of your POP3 server where the accounts mailbox is located. All messages from the Internet are accumulated on POP3 servers and may be retrieved from there by the Get new mail command or by Message Dispatcher. The address may be represented as a traditional URL (e.g.: mail.ritlabs.com) or as an IP numeric address (e.g. 193.219.214.38); if an IP address is used you should be aware that sometimes it may be changed. The advantage of using of IP addresses is that a DNS lookup is not used, thus it is slightly faster on connecting to the server.
User - the POP3 user name for access to your mailbox on the server. Usually, it is the same as the part of the accounts e-mail address before @ symbol. For example, if the e-mail address is john.smith@ritlabs.com, the users name will be john.smith
Password - the password for logging on to the POP3 server. You may leave this field blank - in this case you will be prompted to enter the password each time you try to receive mail.
Encrypted logon - if set, APOP authentication method will be used instead of traditional authentication, which will make your password invisible when it is sent over the Internet. To use APOP you must ask your service provider or network administrator whether your POP3 server supports this type of authentication (it is not a complementary feature of POP3 servers)
8-bit characters are treated - this radio group allows you to set the method used to handle 8-bit (non-ASCII) characters. If you are using only the English alphabet, this feature is not very significant to you because all English characters are ASCII characters and will go through the net without any problems. However, if you are using accented characters or character sets other than English, you should choose the method carefully because there still are some mail servers which do not allow appearance of 8-bit characters in e-mail messages. If you are not sure that such servers are functioning in the way you write your messages, it is better to choose either Base64 or Quoted-printable encoding. The difference between these two encoding methods is that Base64 produces totally unreadable text. Quoted-printable encoding still can be read if your alphabet is almost Latin, only accented characters are encoded. If your recipient's are using The Bat! or another program which can recognise Base64 and quoted-printable encoding automatically, you may choose either of these two methods.
Delivery - the default delivery method. This is implemented almost for defining the function of "F2" and "Shift+F2" keystrokes in the message editor. If the delivery method is Immediate, pressing F2 within the editor will send the message immediately, whereas if Deferred is selected, the message will be queued in Outbox.
Combined delivery - if this check box is ticked, Get new mail command will also invoke sending of queued messages from Outbox and Send queued mail command will also invoke new mail retrieval.
Always ask for POP3 password - If this check box is ticked, you will always have to enter the POP3 password to retrieve new mail (this is equivalent to leaving POP3 password field blank).
Message management options and port numbers for servers are defined in this section
Leave messages on server - the opposite to the above method. This method is useful when you are accessing the server from several places and wish to be able to get a copy of any message from each of those places
Keep messages on server for n days - the maximum age of messages left on the server. When a message is older than the age stated, it will be automatically deleted from the server.
Delete message from server when it is removed from Trash - use this option if you are sure that you delete only messages not needed in the future.
Receive header only if message size if greater than n K bytes - use this option if you do not want to receive large messages from the account. This may be useful when you are away from your home and want to read only significant messages (messages of such kind are usually relatively short)
Invoke automatically at each mail check - if this check box is ticked, Mail Dispatcher will be invoked at each Get new mail command if there are new messages in the mailbox
Show all messages left on server - This option is available only if the previous option is set. If it is set, Mail Dispatcher will show all messages left on the server, otherwise only new messages will be shown
| SMTP | the port number used by SMTP protocol (default 25) |
| POP3 | the port number used by POP3 protocol (default 110) |
| IMAP4 | the port number used by IMAP4 protocol (default 143) |
This section is designed for setting some miscellaneous parameters for a mail account.
Check mailbox at startup - if ticked, Get new mail command is invoked automatically each time The Bat! Starts
Periodical checking each n minutes - The Bat! will automatically examine your mailbox for new mail periodically, if this check box is ticked.
Empty Trash folder on exit - trash folder of the account will be automatically emptied each time you exit The Bat!
Time of reading to mark a message as read - within this time interval, unread messages will retain their status. As soon as an unread message is marked as read, some actions may take place (Read Mail sorting rules, generation of Reading confirmation)
Maximum Log file size - the accounts activity Log file is stored in the accounts home directory and called ACCOUNT.LOG. To prevent this file from getting too big, you may limit its size with this parameter
Ignore Check All Accounts request - use this option only if your account is not password-protected. It must not be checked for all your other mailboxes (for example, when POP3 server only works within a specific time interval)
Home Directory - the path to the directory where all files related to the given account are stored. This directory is also used for creating default sub-directories (each mail folder keeps its messages in MESSAGES.MSB file in its mail-folder directory, which by default is placed in the home directory of the account it belongs to)
You may choose the storage method for received file attachments. They may be either kept in a separate directory (so you can copy them from there using explorer, or DOS. This method is the most preferable if you receive large files), or in message bodies. If you choose to store attached files in the <default> directory, files will be stored in the sub-directory named ATTACH in the accounts home directory.
Option Delete attached files when the message is deleted from Trash makes The Bat! keep your disk storage in order, so you dont keep file attachments to messages you no longer need.
Cookies are some funny phrases (aphorisms, quotations etc.) that could be inserted randomly in your messages if you are using %cookie macro in your message template. Use of cookies may entertain your correspondents. The more cookies you use - the more colourful your messages look.
Another way to use cookies is to use them for greetings or one-line signatures.
These are some examples of cookies:
Editing is a rewording activity
If you save the world too often, it begins to expect it
I like kids, but I don't think I could eat a whole one
The Bat! can notify you about new mail arrival with a custom sound (WAV files are used, so you need a sound card installed on your machine). Accounts sound settings are set to messages arriving to any accounts folder by default. It is possible to define additional sound for user defined mail folders so you may hear what folder new mail came in to.
Sometimes it is necessary to disable sound within a certain time interval (for example, if a PC is used at home usually you do not want to hear it reporting to you about new mail in the middle of the night). Allowance time interval is designed specially for such cases. Example: 9:00-20:00.
Sorting Office is implemented in The Bat! for auto-classification of incoming, outgoing, read and replied mail. Each of the above mentioned message flows can be sorted by folder, accordingly to its set of rules.
Each rule is determined by its name, the source folder (for incoming mail it is always Inbox, for outgoing - Outbox and this cannot be changed), the target folder, sets of signal strings and defined actions. To create a new rule, open Account | Sorting Office/Filters dialogue, select the desired rule set (depending on what type of messages you want to classify) in the tree, and press New button.
Related topics:
Signal strings
Filtering actions
Using special syntax in signal strings
Using The Bat! as a Mailing List Server
Regular Expressions
Each set of signal strings is a list of strings to be present or absent in a certain part of a message (it can be one of: sender, recipient, subject, whole message header (kludges), message text, or whole message (kludges and text together). A message which contains (or does not contain - depending on the presence flag for a particular string) ALL the strings included in the set, satisfies the condition defined by the set.
To define several signal string sets for one rule, use the Alternatives page of the Sorting Office dialogue box. If a message satisfies any of the signal string sets for signal strings, the message will be moved from the source folder to the destination folder and the actions defined by the rule will be executed
Example:
String: [John Smith], Location: [Sender], Presence: [Yes]
String: [beer], Location: [Text], Presence: [Yes]
String: [orange], Location: [Anywhere], Presence: [No]
This rule set will be satisfied by any message, which originates from John Smith AND beer must be mentioned somewhere in the message text AND orange must not be found anywhere in the message.
See also: Using special syntax in signal strings
Each filtering rule has its own set of actions, which will be executed whenever a message satisfying filtering condition appears in the source folder. A very widely used action is moving a message to another folder for filing purposes - that is why the target folder is set at the very first page of rule properties. However, it is an option, therefore, you can set the target folder to be the same as the source folder to leave message at its place and proceed other rule actions which can be defined at Actions page of Sorting Office configuration dialogue.
The actions currently available are:
Mark message as read - can be used for incoming messages because messages filtered by other rule sets are supposed to be marked as read already.
Delete message - this is similar to making the Trash folder as the target folder. To remove the message from the server as well as deleting it from your message base, use Kill Filters.
Add/delete the senders address to Address Book - this function allows you to maintain your address book and is especially useful for maintenance of your mailing lists.
Send auto-reply - automatically generate a reply message to the senders address using a template and the messages text as the text for quotation.
Create a message for - automatically generate a message to specified address(es) using a template and the messages text as the text for quotation.
Forward to - forward the message to a specific address(es). Options allow you to use the entire message including header for quotation, send the message as an attach and skip sending of attachments. Forwarding template of the target folder is used for generating of the forwarded message.
Redirect the message to - automatically send a copy of the message to another address(es).
Export message to a file - write the message to a plain text file. Options allow you to append the text to the file or override the existing file.
Run External Program - plug-in hook. Enter a command line for the external processor of the message. For example: C:\Util\MyLists.EXE -c %1. This means that MyLists.EXE will be started, the message will be stored in a temporary file and the file name will be passed as the second parameter. Create a detached process option allows to hide the started Win32 from the task bar.
Create a copy of message in another folder - duplicate the message in additional folder. This may be useful if you want another user to read messages of specific type.
Special syntax is used for signal strings:
Pipe character | means that signal string contains two alternatives. For example, string John|Jack means that search will be successful if John or Jack (or both) will be found in the specified location.
Square brackets [ ] mean that text embraced by them must be searched as a phrase. i.e. search for [Jack] will be successful for sentence Jack is a good man, but not for Jackson guitars are very good for beginners.
Text embraced in quotation marks is case-sensitive, i.e. Internet will be found in the sentence The Internet is growing very rapidly but not in InTeRnEt RuLeZ
The text containing special characters mentioned above, must be embraced in single quotes, like this:
["New" generation mailing list]
Message templates are used for composing messages. They include static textual information in the message body. It may have, for example, a salutation and a signature as well as defining the location of quoted text in replies. From our point of view, the use of templates is a more flexible way of message composition than the use of just signatures.
It is also possible to use macros in templates to include message-dependent information such as addressee name, subject, current time, etc. With macros, it is also possible to define additional addressees and a message subject.
Templates defined in the accounts properties are used by default for all messages created within the account, but it is also possible to create special templates for each mail folder - these templates will be used when the folder is selected in the main windows folder panel.
The current version of The Bat! supports four types of templates:
New message
Reply to a message
Forwarding of a message
Reading confirmation
It is possible to add Cookies to a message using template macros
%cursor
Bye now,
%fromfname mailto:%fromaddr
...%cookie
The initial look of new message addressed to Mike Brown <mike@domain.com> from John Smith <john@site.net> will be:
Hiya Mike,
| - the editor cursor will be placed here by default
Bye now,
John mailto:john@site.net
...Put knot yore trust inn spel chequers
See also:
Macros
Regular Expressions in Macros
New message template is used whenever you create a new message. Once the message editor window is opened and you have all the header information (From, To, Subject) fields filled in correctly, text will appear in the editor window, depending on the new message template. It is also possible to define some message options for new messages such as:
- Default character set
- Message priority
- Confirm Receipt Request.
- Reading Confirmation Request.
Note that these options will be used only for new messages. Replies and forwards will not use them. Also, macros related to "original message" will not function (they will be replaced by empty strings).
See also:
Macros
Regular Expressions in Macros
Reply template is used whenever you reply to a message you have received (Reply and Reply to all commands). In this case, you will see the initial text once Reply command is invoked. However you may change anything in the message header - in this case, the initial text will be adjusted accordingly to reflect the new information unless you have changed the message before editing the header. To include the original messages text in the initial text of a reply, use %QUOTES macros to put it in the mail as a quotation and %TEXT to put it in as normal text.
The style of the quotation prefix is determined by Sender information used for quotation option. Example (John A. Smith is used as the sender)
Information used:Prefix
None>
InitialsJAS>
NameJohn>
Last NameSmith>
First InitialJ>
Full NameJohn A. Smith>
See also:
Macros
Regular Expressions in Macros
There are two ways of forwarding messages: with a template, which places the original text into the message text, and using MIME to attach the file. When messages are forwarded using MIME, it is possible to send several messages enveloped in one (message digests), however not all mail clients can manage MIME digests.
In the case of a message forwarded by placing original text in the message text, the template could be:
From: %OFROMNAME <%OFROMADDR> To: %OTONAME <%OTOADDR> Subject: %OSUBJ
--------------- Original message text ----------------- Hello %TOFNAME, %CURSOR
Best regards,
|
Hello %TONAME,
%CURSOR
All the best,
%FROMNAME
See also:
Macros
Regular Expressions in Macros
Whenever you receive messages with Reading Confirmation Receipt Request, The Bat! will generate a receipt message using this template (unless it is configured to ignore these requests).
There are four options for processing Reading Confirmation Receipt Requests:
| Put in Outbox | generate the receipt and store it in Outbox. This allows you to make changes to the receipt or even delete it if you do not want it to be sent. |
| Send immediately | generate the receipt and send it immediately |
| Edit | the same as writing a reply, but receipt template is used instead of reply template |
| Ignore | one of simplest ways to finish your correspondence |
| Prompt before the Action | option is functional only if one of the first three methods above are chosen. In this case you will be prompted when the receipt is about to be created, if the action is not confirmed, the request is ignored |
Folders are the place where messages are kept. There are two types of folder in The Bat!: standard (or system) and user-defined (or custom). The general purpose of folders is classification of messaging so that you may easily find messages related to a particular topic.
Each account has its own folder hierarchy. Folders can be named depending on their use, but any account has four standard folders:
| Inbox | the default folder for incoming mail |
| Outbox | the folder for outgoing messages |
| Sent | the default folder for sent messages |
| Trash | Wastebasket - all deleted messages from other folders are stored here, when a message is deleted from the Trash folder, it will be erased permanently (unless you keep a copy on the server). |
With sorting rules (Account | Sorting Office/Filters), you can determine in which folder messages should be placed after they have been received, sent, read or replied to.
For example, if you have a contact from which you receive messages often, and wish to keep track of mails from him/her, you can create a folder with a relevant name, which gives you a clue that the folder keeps messages from this contact (his/her name, for instance). You can now create a sorting rule in the Incoming Mail group with the persons e-mail address or name as a signal string, located in sender information for the sorting rule. Once done, all incoming messages from this contact will go into the folder you have created.
User-defined folder may also have its own templates for new messages, replies to messages from this folder and for message forwards, as well as sounds for notification about new messages.
It is possible to move and copy messages from one folder to another by a simple drag-and-drop operation: if no keys are pressed, a Move operation is performed, if Ctrl key is held down while dragging, the message is copied.
A folder can have sub-folders.
To re-position a folder within the accounts hierarchy, press and hold Alt key and then use drag-and-drop to move the desired folder.
Name - the name of the folder as it appears in the folders hierarchy of the account. The name is also used as the default name for the folders message base sub-directory
Directory - the directory where folders message base file (MESSAGES.MSB) will be stored. If it is set to <default>, make sure that the folders name does not contain characters disallowed by the file system ("\", "/", "+", "|", "<", ">", ":"), otherwise you will be asked either to rename the folder or to change the folders directory
Maximum number of stored messages- the maximum amount of messages allowed to be kept in the message base. If the number of messages exceeds this value, earlier messages may be automatically deleted from message base by the Purge command
Keep messages in the base for n days - The maximum age of a message allowed in the message base. If a message is older than this, it may be automatically deleted from message base by Purge command
Compress the folder - compress the folders message base file (if there were some messages deleted or moved from the folder). This option helps you to use your disk storage more efficiently
See also:
Templates
New mail notification (Sound)
The Bat! provides an easy and fast way of editing messages. The text editor has number of commands and useful features. The main difference between it and most of other Windows-based e-mail message editor is that the text being edited is shown the same way as it will appear on recipients screen - no matter what system or e-mail client is running on the recipients computer.
The command set is described in sections below:
Block and formatting commands.
Insertion and deletion commands.
Miscellaneous editor commands.
Cursor movement commands.
Spell checking functions.
Regular Expressions
URL highlights.
Received messages can be read in message auto-view panel located of the bottom of the main program window, or in a separate window, which gives the capability to read subsequent messages from the folder. It is possible to list messages by pressing the space key. In this case you will read messages from page to page, and when you reach the bottom of the current message, the first page of the next message in the folder will be shown (this applies to both modes of reading).
When folder message list box is active, it is possible to view the message using Alt+Arrow keys to scroll the message text in the window. Use <Del> key to remove messages you do not want to keep in your message base. By pressing <Enter> the separate message viewer window will be opened with the current message shown. To sort messages within a folder, use the mouse to click on the appropriate header section.
It is possible to set the amount of reading time for a message, after which the message will be marked as read (note that this setting can vary from account to account) - this reduces the risk of missing an important message.
To mark a block of text, you can use the standard cursor keys, together with the <Shift> key. With the mouse you can select text by moving the mouse cursor while pressing the left mouse-button.
| Action | Key combination |
| Mark the beginning of a block | Ctrl+K B |
| Mark the end of a block | Ctrl+K K |
| Copy the block to Clipboard | Ctrl+Ins or Ctrl+C |
| Cut the block | Shift+Del or Ctrl+Xl |
| Paste the block from Clipboard | Shift+Ins or Ctrl+V |
| Paste the block from Clipboard as quotation | Alt+Ins |
| Read the block from file | Ctrl+K R |
| Write the block to a file | Ctrl+K W |
| Move the block left to right | Ctrl+K I |
| Move the block to the left | Ctrl+K U |
| Switch block type to stream (default) | Ctrl+O K |
| Switch block type to column | Ctrl+O C |
| Switch block type to linear | Ctrl+O L |
| Justify the block or paragraph | Alt+J |
| Align the block on left end | Alt+L |
| Align the block on right end | Alt+R |
| Command | Key combination |
| Toggle Insert/Overwrite Mode | Ins |
| Delete the current line | Ctrl+Y |
| Delete to the end of line | Ctrl+Q Y |
| Delete character at the left | Backspace |
| Delete character at the right | Del |
| Delete word after cursor | Ctrl+T |
| Delete word before cursor | Ctrl+Backspace |
| Command | Key combination |
| Save message and continue editing | Ctrl+S |
| Save message in queue and exit editing | Shift+F2 |
| Send message immediately | F2 or Ctrl+Enter |
| Undo | Alt+Backspace |
| Place a position marker in the text | Ctrl+K n (n=0..9) |
| Return to a marker | Ctrl+Q n (n=0..9) |
| Insert Current Date | Ctrl+Q D |
| Insert Current Time | Ctrl+Q T |
| Uppercase Current Word | Ctrl+[ |
| Lowercase Current Word | Ctrl+] |
| Capitalise Current Word | Ctrl+/ |
| Search for a string | Ctrl+Q F |
| Search and replace | Ctrl+Q A |
| Repeat the last search | Ctrl+L |
| Cancel operation | Esc |
Text blocks can be:
Stream - Standard - as they are in most Windows-based text processors
Linear - whole text rows are selected
Column - rectangular text areas are selected. This is based on the fact that plain text editors use only fixed pitch fonts. Column blocks are sensitive to the Insert mode of the editor. If Insert mode is on, column blocks are inserted in the text while shifting the original text the corresponding number of character positions to the right, otherwise the original text is replaced within the rectangular area of the inserted block
If Persistent blocks are used, text selection remains until you select another region, hide the selection or delete the selected text. Otherwise, selection will be automatically hidden when you move the cursor to another position, type some text in, or insert text from Clipboard.
Override blocks option works only if Persistent blocks are not used. If this option is selected, a text selection will be replaced with anything you type in, insert from the Clipboard, or press <Del> key, - selected text will be deleted.
| Left to one character | Left arrow |
| Right to one character | Right arrow |
| Word left | Ctrl + Left arrow |
| Word right | Ctrl + Right arrow |
| Up to one row | Up arrow |
| Down to one row | Down arrow |
| To the start of the row | Home |
| To the end of the row | End |
| Scroll up to one row | Alt + Up arrow |
| Scroll down to one row | Alt + Down arrow |
| Up to one screen height | PgUp |
| Down to one screen height | PgDn |
| To the start of the text | Ctrl+Home or Ctrl+PgUp |
| To the end of the text | Ctrl+End or Ctrl+PgDn |
| To the selection start | Ctrl+Q B |
| To the selection end | Ctrl+Q K |
When typing text, you may use the auto-formatting options of the editor. Note that text in the plain text editor is not re-formatted automatically when you modify the text you have typed in already - in this case you should use block formatting commands
Auto wrap mode-if the length of the row you are typing in exceeds the value set as Right margin, the text will be automatically wrapped to the next row
Auto indent mode- positions the cursor under the first nonblank character of the preceding nonblank line when you press Enter.
Backspace unindents - aligns the insertion point with the previous indentation level when you press Backspace, if the cursor is on the first nonblank character of a line.
Justify on wrap - when a text row is automatically wrapped while typing, the text in the row is justified accordingly with the Right margin value
The Bat! implements two most commonly used spell checking engines - Sentry Spelling-Checker Engine (SSCE) and Common Speller API (CSAPI) for Standard and Just-In-Time Spell Checking.
- Advanced User Dictionaries - add your own words to any of up to 30 user dictionaries. Words can be added to or removed from user dictionaries at run time. Words in user dictionaries may be offered as suggestions for misspelled words.
- Intelligent suggestions for misspelled words - SSCE can locate suggested replacements using either typographical (looks like) or phonetic (sounds like) matching. Suggestions are scored by the degree of closeness with the misspelled word, and the list of suggestions is returned in decreasing score order. The most commonly misspelled words are underlined by square-wave-line and can be corrected with mouse double-click on this word.
- Case sensitive - incorrect capitalisation (e.g., canada instead of Canada) can be reported as a misspelling. Case sensitivity can be disabled if necessary via a simple run-time option setting. Dictionaries included with SSCE contain correct capitalisation forms.
- Low resource consumption - SSCE typically uses a maximum of 450K of memory at run time and 400K of disk space. You will really appreciate this feature!
- Works with other applications' user dictionaries - SSCE can read and write user dictionaries created by other applications, including Microsoft Word and Microsoft Office (*.dic files).
Right-click on a highlighted word and a popup menu displays, letting you choose from the suggestions for the correct spelling of the word. Or, choose Ignore All to ignore the current and all subsequent occurrences of the word. Or, choose Add to add the word to the user dictionary. If it is no suggestions in its dictionary for the correct spelling of the misspelled word, suggestions are not listed in the popup menu.
It is also possible to check the text using Standard Spell Checking dialogue box (press “Check Entire Text” submenu of “Spell Checker” menu or simply F4). Below is the description of Spell Checking dialogue box buttons:
- Ignore: skips the current word (word displayed in “Not in Directory” field) without changing it and goes to the next misspelled word.
- Ignore All: skips all occurrences of the current word in the message without changing it and goes to the next misspelled word. This word would be treated as spelled correctly during the entire current The Bat! session.
- Change: replaces the current word with the correct word taken from “Change To” field.
- Change All: replaces all occurrences of the selected word in the message with the correct word taken from “Change To” field.
- Add: adds the current word to the current user directory. The name of the current user directory is displayed in “Add Words To:” drop-down list.
- Suggest: gets the list of similarly spelled words for the current word (word displayed in “Not in Directory” field).
- Undo: takes the selected word from Message Editor and places it to “Not in Directory” field.
- Options: invokes Spell Checking Engine specific options dialogue box.
- Dictionaries: invokes Spell Checking Engine specific user directories configuration dialogue box.
The main purpose of user dictionary is allowing user to add custom words in it. There are three ways of adding a word: from Standard Spell Checking dialogue box, from Edit dictionaries dialogue box and from pop-up menu (Right Mouse Button or Alt-F10) on misspelled word.
The Bat! checks the only text that you has entered plus your template text. If your template includes unknown words for spell checker, you can simply add them to the default user directory. Note that the user directories for different languages may vary. The quoted text and URL links are not checked.
Character Translation Tables are designed to manage countless national character encoding tables. For example, in there are three different encoding tables used in Russia (DOS Code Page 866, Windows 1251 and KOI-8), the same situation arises in many other countries where a non-Latin alphabet is used or a Latin alphabet with accented characters.
Translation tables determine what characters of a particular alphabet correspond to their equivalents in Windows national code page. To add a translation table to The Bat! from Options | XLAT tables dialogue, press Add button, select the file containing the translation table, then you will need to enter the name of the table being added as it appears in the program menus and the name of the character set determined by the table and as it appears in charset field of message header (for example, koi8-r for Russian KOI-8 character set).
The format of a file containing a Translation table is fairly simple. It is a stream of character pairs: <national character 1><Windows equivalent 1><national character 2><Windows equivalent 2>...<national character n><Windows equivalent n>
The Bat! is an international program, the language of its interface can be changed from Options | Language sub-menu. Language file TheBat.LNG must be placed in the same directory where the program executable is located. This file determines the contents of Options | Language sub-menu.
A new message can be created in four different ways:
1. By clicking on New message button or invoking New message command in the main program window menu. In this case you will have to enter the addressee manually or use the address pop-up menu.
2. By selecting the address needed from Address Book and invoking New message command from there.
3. When viewing a message if an e-mail address is highlighted, click the right mouse button and choose Write a message... command - the highlighted address will automatically be placed in the To: field.
4. By clicking Ctrl+N
You can assign a priority to outgoing messages and request a Confirm Receipt and Reading Confirmation.
You can assign a priority to outgoing messages. The priority is only for you and your recipients it does not affect the way mail transport systems handle the messages. New messages are created with a Normal priority. To change the priority of the current message, in Message Editor Window, use the Priority popup or Options menu. Unread received messages are displayed in the list with differently-coloured envelopes: high priority messages are red, normal priority messages are yellow and low priority messages are blue.
You can request that your recipients mail server notify you when your message has arrived to the users mailbox on the server. To do this, in Message Editor, click on the Confirm Receipt in the pop-up or Options menu. The Confirm Receipt options may or may not work as described, depending on your recipients SMTP server software.
You can also request that your recipient notify you when he have read your message. To do this, in Message Editor, click on the Reading Confirmation in the pop-up or Options menu. When your recipients open the message and have read it, a dialog is displayed asking them to create a confirmation message, depending on Reading Confirmation Options. The Reading Confirmation options may or may not work as described, depending on your recipients e-mail client software.
To send messages to their destination, you must establish a connection to the Internet. If you are in the message editor window and have just finished editing a message, use the Send now command. If there are any problems with sending your message to the SMTP server, the message editor window will re-appear on the screen, otherwise you may see what was wrong with the message in the log panel of the main program window. If you have queued mail in Outbox, use Send queued mail command, and if the messages are not sent (i.e. the messages are not moved from Outbox folder to Sent mail or whatever folder is determined by Sorting rules), again, examine the accounts log.
To send files attached to an e-mail message:
Open message editor and enter all the information you need (i.e. addressee information, subject, and message text)
From sub-menu Utilities | Attach a file choose the encoding type, or click the right mouse button on attachments panel and choose the encoding type from there, or click attach a file button on the editor window toolbar. In this case the encoding will be the one you set as default for the account you are writing from).
In the subsequent dialogue, select the file you would like to send, and press the Open button.
Files attached to a particular message are shown on the left of the message text as icons. You may use right mouse click to invoke the pop-up menu with possible actions for the file you have selected, or just double-click on the selected file to open it (note that the appropriate file associations must be defined in your system).
The Address Book provides you an easy way to maintain the list of contacts you have. It is possible to create groups dedicated to a particular classification or use as a mailing list. There are four possible ways to add a record to the Address Book:
1. When you see an e-mail address highlighted while viewing a message, click the right mouse button and then choose Add to Address Book command in the pop-up menu.
2. When you are filling in the To: field in the message editor, press the button with an arrow on it - e-mail addresses contained in To: field will be added to Address Book.
3. Using Add to address Book command of message list local pop-up menu.
4. Using New address entry menu command in Address Book.
It is possible to sort Address Book entries automatically using Edit | Sort sub-menu of Address book or manually using drag-and-drop operations.
The Bat! requires an address to be able to send your messages the same way as the postal service needs an address to be able to deliver a letter. The destination e-mail addresses must be entered in To:, CC: or BCC: fields. This is possible to do using either direct typing or Address Book aliases or Address Pop-Up menu (available by right mouse button click or clicking a button at the extreme right of the input field). Multiple addresses should be divided by a semicolon.
Message parking is designed to prevent occasional deletion. When a message is parked, it will not be moved to another folder, deleted or purged automatically. It is also impossible to delete a folder that contains one or more parked messages.
If you want to share the access to the Internet mail between several users, you may need to set access rights for particular accounts or account groups.
Users are classified by two categories:
Administrators - these users can see all accounts defined in the running copy of The Bat! and can change all account properties, program preferences and settings
Ordinary Users - these users cannot see all defined accounts. The properties they may change are determined by Administrators
If at least one ordinary user is defined, initial Log on dialogue is invoked at the programs start-up and a user has to enter his/her account name and the password (if any) to have access to his/her account. The password for a particular account can be set using Account | Set Access Password command from the main program window.
To allow an ordinary user to have several accounts and to see them simultaneously, the Administrator must define the account group for such a user.
Within a network, it is possible to give access to a particular account from a machine connected to the network. All the Administrator needs to do is to set as the accounts home directory a directory accessible within the network and to create a copy of the account on machine from where the account is intended to be accessed. Even if machine does not have TCP/IP protocol installed on it, it is still possible to use The Bat! - just define the machine as Non-TCP/IP Workstation and working directory of the copy of The Bat! running on the machine must be the same as on the machine which is running The Bat! with status of TCP/IP or Dial-out Server.
See also:
The Bat! Networking Course
In order to process E-Mail exchange within either Internet or corporate network, each E-mail client should have either permanent or on-demand connection with its mail (POP and SMTP) server. A mail server is a computer that processes distribution and storage of E-Mail messages until they rich the destination address. Generic E-mail client supports at least two most commonly used E-mail exchange protocols: POP and SMTP. POP (Post Office Protocol) is used for retrieving mail from host by client. Particularity of protocol - mail message exchange is initiated by the client's request. SMTP (Simple Mail Transfer Protocol) is simple protocol for mail transmission which is widely used on the Internet. The SMTP server's function is to receive mail from other servers and clients, and to deliver mail to other hosts and to its clients' mailboxes.
Local Area Network or manual connection. If this way is chosen, The Bat! uses the connection to the Internet already established either via your LAN or by dialling your Internet Service Provider. In other words, The Bat! itself does not need to do something extra to connect to the Internet. Some non-LAN systems may be configured so that ISP is dialled automatically whenever a program is trying to connect to an Internet server and this method can be used with The Bat! However, in some cases (combined delivery or multiple account operations) The Bat! has to establish two or more TCP/IP sessions simultaneously and this may cause problems such as trying to establish two dial-up connections at the same time. We recommend to use the second way if you have a Dial-up connection to your ISP
Dial-Up Networking Connection. You should specify this type of connection if your LAN is not connected to the Internet itself and you are using a Dial-up connection provided by your ISP. Whenever The Bat! needs to open TCP/IP connection, it checks whether the specified 'phone book entry is active (i.e. the established TCP/IP connection, if there is any, is made using this 'phone book entry). If the entry is active, TCP/IP sessions starts. Otherwise, The Bat! will automatically dial the 'phone book entry to establish TCP/IP connection. In this case, multiple requests such as checking mail for all accounts and combined delivery (which requires two TCP/IP connections to be open at once: one for mail retrieval and another one for sending mail) will be handled correctly.
The Bat! in the server mode can replace a mail server for such a network. This means that it allows you not to install a mail server inside of your local network and moreover, it gives users a possibility to process E-Mail exchange over the Internet without having their own Internet connection. A computer with The Bat! in the server mode is basically the same as in the stand-alone mode plus the use of its own Internet connection to provide E-Mail exchange of computers with The Bat! in the client mode over the network and/or the Internet.
When the user of a client machine wishes to send a message to an Internet address, it places the message into the Outbox which is physically located on the server machine and invokes the command that makes the server send the outgoing messages using the server's connection to the Internet.
When a client wishes to check its POP account, it invokes the command to the server to check the client's mailbox on the mail server. The server connects to the POP server using its own Internet connection, receives the messages, stores the messages to the client's message base and invokes the command to the client to re-read its message base contents. When the client receives this command, it notifies the user that the new mail has arrived. The new message arrival is indicated in the folder tree screen of the client, and on the MailTicker™, if the MailTicker™ is configured.
To turn on the MailTicker™ (there must be some unread messages though), use "Options | MailTicker™ | Show Always" or "Show Automatically" options of the main window menu.
2. Using "My Computer" desktop icon, choose the local drive or directory with The Bat! installed or where you are planning to install The Bat!. This location will be used to store message bases. Share this path to the network users that will run The Bat! in client mode on their computers. If you are already using a network drive, e.g. on a dedicated file server, you may skip this and the next step.
3. Map the resource you have shared to a network drive's letter. Other computers that will act as clients within your network using this network drive to exchange the information with the server.
4. If you do not have The Bat! installed yet, install it to the mapped network drive in order to machines with The Bat! in the client mode can access it. Run The Bat! from the network drive that you have mapped.
5. Click "Network & Administration" item of "Options" menu to make sure that this machine is in "TCP/IP or Dial-Out Server" (server) mode.
6. Create the accounts that will be used by client machines. Make sure that the home directories of these accounts are located on the network drive so the client users can access them.
7. Invoke "Network & Administration" dialogue box again and manage the privileges of accounts you have created.
2. At the installation of The Bat! on a client machine, select the program's working directory on the network drive letter that you just have mapped. The working directory must be the same as on the server.
3. If you have The Bat! already installed on this computer, please proceed the following steps, otherwise, if you just have installed The Bat! accordingly to the previous step, the setup is finished.
These sub-steps describe how to change the machine mode from stand-alone to client without reinstalling The Bat! If you are not familiar with RegEdit, it would be better for you to uninstall The Bat! and to go to the step "Installing The Bat! on a client computer"
a) Enter "Network & Administration" dialogue box and make sure that this machine is "Non-TCP/IP Workstation".
b) Exit The Bat!
c) Change the mail directory using RegEdit. HKEY_CURRENT_USER\Software\RIT\The Bat!, Value name: Working Directory, and the value data is the path to mail directory, which should be on a network drive, and it should be the same as on the server.
Local Delivery Technology is provided by The Bat! with the appropriate option turned on. To activate it, open "Network & Administration" dialogue box on server, and tick the "Allow Local Delivery" checkbox. This option allows several machines to work in a local network exchanging messages without using SMTP/POP server at all. This feature brings an efficient solution for building corporate mail-exchange networks without using Internet Mail Transfer Protocols. When "Allow Local Delivery" is on, the outgoing messages addressed to local users, are dispatched directly and put into appropriate message bases instead of sending them to SMTP server.
See also:
Working in Multi-User Environment
Account Groups
If a particular user wants to have access to several e-mail accounts, it is possible to define a group of accounts to be displayed whenever such a users logs on to The Bat!
To define an account group, use Options | Network and Administration command from the main program window.
To log into The Bat! using access to an account group, just enter the group name and password instead of an accounts logon data in the login screen.
See also:
Working in Multi-User Environment
The Bat! Networking Course
After you have installed The Bat!, the program starts automatically. If you are installing The Bat! for the first time, you will be prompted about working directory. The working directory is the most important directory for The Bat! functioning - all account home directories, account data and address books will be stored in there by default. You also will be prompted about adding The Bat! icon to your Desktop, Start Menu and Sent-To menu. If account list file is found in the directory you have specified, The Bat! will automatically add the listed accounts into your copy of The Bat!, otherwise the New Account Wizard will open.
Choose the name of the account you want create and specify the home directory of this account. If the home directory contains account configuration files (file names begin with ACCOUNT), the data from those files will be used as default for your newly created account. If you choose <default> as the home directory, The Bat! creates a sub-directory of the working directory with the same name as the account.
After you have the new account name and home directory chosen, click Next, the New Account Wizard begins walking you through the fields for which you need to enter setup information.
You will need to supply the following items in the panels of the New Account Wizard (click Next after filling out each page):
Your Name - Enter your name as you would like it to appear in the From field of all of your outgoing messages from this e-mail account, indicating to your recipients who the mail is from.
E-mail Address - Enter the e-mail address that has been assigned to you by your Internet Service Provider or your organisations e-mail administrator. This is the address that other people will use to send you e-mail. E-mail addresses are generally of the form username@domainname, and serg@ritlabs.com is an example.
Organisation - Organisation which you represent (if any). The information about your organisation name is placed in the header of all messages you write. Mythical Software, Inc is an example. If you do not want to identify your organisation, leave this field blank.
SMTP Server - To send messages in The Bat!, you must have access to a computer running an SMTP (Simple Mail Transfer Protocol) server. Your outgoing messages are sent to the SMTP server, which delivers them to your recipients. The address may be represented as a traditional Internet symbolic name (e.g.: mail.ritlabs.com) or as an IP numeric address (e.g. 193.219.214.38).
POP3 Server - All of your incoming e-mail messages are delivered to your incoming e-mail account, which resides on a computer that runs your incoming e-mail server. Once your messages arrive at your mail account, The Bat! picks them up and transfers them to your PC. Your incoming e-mail server must use one of the two Internet-mail communications protocols POP (Post Office Protocol) or IMAP (Internet Message Access Protocol). In the edit box, type the full name of the computer that runs your incoming e-mail server: mail.ritlabs.com is an example.
Username - Enter the name that you will use to log in to this e-mail account. This name is provided by your Internet Service Provider or your organisations e-mail administrator, and it usually consists of the text that appears before the at sign (@) in your return e-mail address. In the example serg@ritlabs.com, the login name is serg.
Password - Enter the password you use to access your mail server. You may leave this field blank - in this case you will be prompted to enter the password each time you try to receive mail
Use encrypted login method (APOP) - APOP is a secure login method, which prevents transmitting your password over the net in clear. This feature is not a complimentary for POP3 servers, however some systems do not allow other login methods but APOP. Please consult to your Internet Service Provider or Network Administrator whether you should use APOP.
Leave copy of messages on the server - You can use your account from different places. In this case, you may want to leave messages on the server to make it possible to retrieve them from other places where you use your mail account. If you do not want to leave copy of messages on the server, the messages will be deleted from the server mailbox after their successful retrieval.
Once you have completed setting up your account via the New Account Wizard, you are now ready to send and receive messages. However, you may need to take an additional step in order to send messages.
If the computer that runs your POP3 or IMAP server (incoming e-mail account) also runs an SMTP server, then no additional setup action is required. You are now ready to send and receive messages in The Bat!.
If you ever wish to change the settings of your e-mail account, you can do so from the Account Properties dialogue. It is available by Account | Properties menu command when the account is selected in the folder tree of the main window.
The Bat! is a "try-before-you-buy" program. If you intend to use The Bat! after the trial period of 30 days, you must register your copy of The Bat! or stop using it. When you register The Bat!, you are eligible to receive Technical support from The Bat! support team as well as features for registered users can be used from then.
Note: If you are part of a site license, you do not need to register. Contact your organisations e-mail administrator for support.
To get the latest licence prices and register your copy on-line using credit card, please visit The Bat! official WWW home page located at http://www.ritlabs.com/the_bat/ or contact The Bat! support team via e-mail info@thebat.net
Each time you open The Bat! (including the first time after install), the Bat! Tip of the Day dialogue is displayed, showing you the Tip of the Day. You can display next and previous tips by clicking the Next Tip and Previous Tip buttons. To prevent the Tip of the Day dialogue from being displayed on start-up, uncheck the checkbox. You can always display the Tip of the Day from the Help menu. Click the Close button to close the Tip of the Day dialogue.
You can add your own tips or your favourite quotations by editing the file named TheBat.tip located in the directory where The Bat! is installed. To change the order of tips, delete the file tips.ini located in the same directory.
If, after reviewing all of the available materials, you are still in need of assistance, contact your e-mail administrator (your Internet Service Provider or your companys The Bat! support coordinator) or The Bat! Support team. If you are eligible for technical support, select Feedback | Information request from the Help menu.
You must register your copy of The Bat! to receive technical support. See Registering Your Copy of The Bat! for details.
To quit The Bat!, select Exit from the Message menu, or press Alt+X. If you have any mail retrieving or sending sessions, you will hear the Windows exclamation sound which means that you cannot quit The Bat! right now.
The Trash folders of accounts are emptied if the Empty Trash on exit option is on in the Account Properties. Also, all folders will process their Exit actions (purge and/or compress) which can be set in Folder properties dialogue.
You can uninstall The Bat! by using the tools provided with your Windows 95 or Windows NT 4.0 (or later) operating system. Open the Control Panel, double-click on Add/Remove Programs, select The Bat!, and click Remove.
An outgoing message is a message you send to someone else. The simplest way to create an outgoing message is to select New from the Message menu or to press Ctrl+N. A new message window is displayed, called the message editor window).
You can assign a priority to outgoing messages and request a Confirm Receipt and Reading Confirmation.
The message editor window in invoked whenever you edit/reply/forward a new e-mail message. Message editor window consists of the menu bar, the Toolbar, the message header, the Status bar, the attachment window and the message body (text editor with Spell Checking)
-saving messages in various ways
-attaching files
-standard editing functions such as Copy/Paste/Cut operations as well as additional Pasting/Copying text from/to disk files, pasting as Quotation;
-special operations like block mode switching, inserting current date/time;
-spell checking functions;
-PGP functions and options;
-changing view options (switching on/off header fields, original message text when replying, toolbar and header fields visibility);
-changing message preferences such as priority, character encoding, confirmation receipt requests and the active account from which the message should be sent.
Addressee fields (To, CC and BCC) have quick buttons to invoke address selection dialogue. You can also use Shift+Enter keystroke for this. The other feature is quick address pop-up menu which can be invoked either by pressing Alt+Enter or by right mouse click - the menu contains the addresses from the address book with Add to pop-up menu option set. When you type an address, you can press Ctrl+Plus to let The Bat! find an addressee with the name or address beginning with whatever you have typed, pressing Ctrl+Plus again takes you to another addressee with matching name or address.
From and Reply-To fields contain senders identity and the address to which replies must be sent. These fields can be edited either directly or by choosing alternate addresses from their drop-down lists or by choosing Active account from the Options menu.
The Follow up contains the identifier of the message to which a reply is created (empty for a new message) - this field should not usually be edited.
The Subject is some brief text indicating the contents of the message. This field can be left blank, although it is considered a point of e-mail etiquette to include a Subject with each message.
Status bar
The status bar is the line below the message body. It shows current status of the editor and message preferences (left to right): Caret position, Modified flag, current Block mode, current Input mode, the message priority and receipt requests flags, the last is the messages character set). If you click with right mouse button on any section except two first ones, youll get a pop-up menu to change an option, which attached to a particular status panel.
See also: Text Editor
Sometimes it is convenient to save an outgoing message either as a safeguard when typing long messages, or so you can return to it later to make changes. You can use either Save or Save as draft or Autosave
To save the current message, select Save from the File menu. Saved messages are put in the Outbox and the saved message is shown with a Road works sign in the Status column. The Road works sign indicates that the message is not yet completed and thus cannot be sent from the outgoing queue.
You can continue making changes to the message or close it. If you try to close an outgoing message window without saving that version of the message, an alert is displayed asking if the message should be saved or the changes discarded. If you select Discard and the message has never been saved, the message is deleted.
If you want to send your messages immediately instead of putting them in a queue to send later, use F2 key while you are in the message editor (be sure the Immediate delivery option is chosen in the Account Properties, use Shift+F2 otherwise).
To send the current message, click on the Send button or select Send Now from the Message menu. A progress window is displayed to show the progress of the transmission.
See also: Queueing a Message to Send Later.
If you want to put your messages in the outgoing queue (in the Outbox) to send all together at a later time use Shift+F2 key (be sure the Immediate delivery option is chosen in the Account properties, use F2 otherwise).
To put the current message in the queue, click on the Queue button or select Queue in Outbox from the Message menu. The message window is closed, the message is saved in the Outbox without Road works sign which means that the message is ready to be sent.
To send all of your queued messages, select Send Queued Mail from the Account menu of the main window. A progress window is displayed momentarily at the top of the screen indicating the progress of the transmission.
See also: Sending a Message Immediately.
With The Bat!, you can lock your account with a password so nobody can read your mail without your permission. This can be often used when your computer is located in office where anybody can access your computer while you are away. Do not confuse the account access password with your mail server password - these are two different things so make sure that you use two different passwords for your privacy sake.
In multi-user environment, the account access password is also used for logging on.
To protect your account with a password, use Set Access Password command of Account menu or press Ctrl+F12. You will be prompted about the password you want to use to access your account. If you have a password set already for your account, you can enter empty string as your password - the account will be unprotected after doing this
Note that the accounts mail is encrypted if you set a password. Make sure that you wont occasionally forget your password, it is recommended that you write down your access password somewhere.
The Bat! uses Pretty Good Privacy (PGP) software to protect your messages from unauthorised reading and/or modification. For proper use of cryptography provided by PGP in Electronic Mail exchange, you need to know more about gaining message privacy - please visit PGP official Web site at http://www.pgp.com
To use PGP v2.6.3 with The Bat!, just install PGP completely, and make sure that PGP executables stay in your system's PATH Environment variable and you have PGPPATH is set accordingly to PGP documentation. Please read the documentation on PGP carefully before using it. Outside U.S., you may download PGP v2.6.3 International. U.S. version of PGP 2.6.3 is no longer available.
To use PGP v5.5.3 or higher with The Bat!, just install PGP completely and make sure that all PGP DLL's can be located using your system's PATH Environment variable. United States and Canada residents may download PGP 5.5.5 (U.S. Export Restricted) from its official Web site. Outside the U.S., you may download PGP 5.5.3 International and PGP 5.5.5 User's Manual from the International PGP WWW site - http://www.pgpi.com.
After you have your version of PGP installed accordingly the above instructions, you can start your secure messaging and PGP functions in the main windows Tools menu and the message editors PGP menu are available to use.
See also: Encrypting your message with PGP
Decrypting PGP signed messages
Signing your message with PGP
Verifying PGP signed messages
Adding PGP public keys from a message
To ensure your recipients that messages they receive are from your e-mail address, it is recommended to encrypt your messages with PGP. PGP signed messages contain their original text plus your key information so if somebody tries to modify a message signed by you, the message wont be verified successfully by its end-recipients. PGP signing can be used together with encryption.
With The Bat!, you can sign your messages from the message editor either manually using PGP | Sign block (Sign entire text, Sign and encrypt entire text) command or automatically using the on/off option Sign when completed of PGP menu.
Before sending signed messages, make sure that your recipient have your public PGP key, otherwise they wont be able to verify your signature validity. Please refer to PGP manual about the distribution of your public key.
See also: Encrypting your message with PGP
Decrypting PGP signed messages
Verifying PGP signed messages
Adding PGP public keys from a message
To send message securely over the Internet, it is recommended to encrypt your messages with PGP. A PGP encrypted message cannot be read by anybody but the persons whose public PGP keys are used to encrypt the message. PGP Encryption can be used together with signing.
With The Bat!, you can encrypt your messages from the message editor either manually using PGP | Encrypt block (Encrypt entire text, Sign and encrypt entire text) command or automatically using the on/off option Sign when completed of PGP menu.
To encrypt your message to a particular recipient, you must have the recipients public key. If you dont, please refer to PGP manual to learn how you can obtain public keys.
See also: Decrypting PGP signed messages
Signing your message with PGP
Verifying PGP signed messages
Adding PGP public keys from a message
Whenever you receive a PGP signed message, you can check whether the signature is valid so the information in the message has been sent by an authorised person and is not changed before it has arrived your mailbox. To do this, you should have PGP properly installed and the senders public key in your public key database.
To verify a signed e-mail message from The Bat!, use Check PGP signature command from the Tools menu. If the message is encrypted, it will be automatically decrypted (PGP may ask you for your passphrase).
See also: Encrypting your message with PGP
Decrypting PGP signed messages
Signing your message with PGP
Adding PGP public keys from a message
Whenever you receive a PGP encrypted message, you can decrypt it you have PGP properly installed and an appropriate private key in your key database. Please refer to PGP manual to get more information about PGP key pairs.
To decrypt an encrypted e-mail message from The Bat!, use Check PGP signature command from the Tools menu. If the message is signed, PGP automatically checks its signature validity. Note that the message is NOT stored so you need to decrypt it this way each time you read the message.
Another way is decryption as a message into your message base using Decrypt PGP... command of the Tools menu. Note that in this case your privacy might appear as defenceless because the message is stored in your message base in clear text so anybody else can read it.
See also: Encrypting your message with PGP
Signing your message with PGP
Verifying PGP signed messages
Adding PGP public keys from a message
PGP public keys can be distributed in plain ASCII text and therefore it is possible to embed public key blocks in an e-mail message. Below is an example of a message with public keys embedded.
Hello John,
This is my public key:
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.3i
mQBtAzPHTM0AAAEDAKCJ5/hM+qpxHaa4wFumqU2DEV4KfkKe5hkkfS6knTtn0rnD
Zm/90txo+29gOFARBL8ynIpGA7fUgmNG13mprN9q/9xrtH4gg6jV/cYJ3ZtnKN9B
sfw7QLKsW3r6eMYGsQAFEbQiU3RlZmFuIFRhbnVya292IDxzdGVmQHJpdGxhYnMu
Y29tPokAdQMFEDPHTM2sW3r6eMYGsQEBft0DAIi04Yya7Q5ZZAtz2K4bKHitMBFV
j1g0Vmr87Cr5qZYgGBzbNasyFwUuFqwqEuiwnLVNSpPiK8QsJTff6Ky9hqMUiZaL
ENOzJ5f9GKw0pmMio7rOlKRE8Szbl6RkpeCUQw==
=u13G
-----END PGP PUBLIC KEY BLOCK-----
All the best,
Stefan
To import PGP public keys from an e-mail message with The Bat! use Import PGP key command from Tools menu.
See also: Encrypting your message with PGP
Decrypting PGP signed messages
Signing your message with PGP
Verifying PGP signed messages
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.
See also: 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.
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.
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)
| 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. |
| 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: (.+)$". |
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. |
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.
| Keyword | Condition |
| URL | Is a valid URL |
| 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="®EX=^[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. |
-----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:
-----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 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."
-----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-----
I am going to define some variables so that the below how-to will be much clearer. Please substitute your actual information for that which I have provided.
IDL - The name of our list. It stands for Internet Discussion List
ldgregory@biogate.com - The list moderator's address (Your normal e-mail address)
list@idl.net - The e-mail address that subscribers send their posts and Un/Subscribe requests to.
www.idl.com - The IDL Web site.
IDL <list> - The address book group for normal IDL discussion list subscribers.
IDL Digest <list> - The address book group for digest version IDL list members.
How to "import" the IDL account into The Bat!
1. Go to where IDL.ZIP was saved when you downloaded it.
2. Double click the IDL.ZIP file.
3. Click the "Extract" button.
4. In the dialog box that comes up do these two things: The "Extract To" field should be the directory that your accounts are stored in under The Bat! In my case it is: C:\Program Files\The Bat!\MAIL. The second thing is to check the "Use Folder Names" checkbox if it isn't already checked.
5. If The Bat! isn't already running, start it.
6. Click "Account", select "New".
7. In the "Account Name" field, enter "IDL".
8. Click the "Next" button.
9. Put your name in the "Your Full Name" field.
10. In the "E-mail Address" field put the forwarding e-mail address you set up for your list. If you didn't set up a forwarding e-mail address (You really should use one of these), then put the POP3 e-mail address that you will be using for the list.
11. The "Organization" field can be left blank or put in the name of your discussion list.
12. Click the "Next" button.
13. In the "SMTP Server" field, put whatever SMTP server you will be using. I have mine set up for my regular ISP SMTP server address.
14. In the "POP3 server" field, put the same address as you used in step 10.
15. Click the "Next" button.
16. In the "Username" and "Password" fields, put whatever your username/login is for the POP3 account you are using in step 14.
17. The two checkboxes are up to you, but I have both unchecked. If the POP3 account you are using requires APOP, then you need to check this box. For the normal operation of the discussion list, you don't need to keep copies of messages on the server.
18. Click the "Next" button.
19. Check the "Do you want to check the account settings now" radio button and click the "Finish" button.
Ok, now that you have "imported" the IDL account, we need to finish setting it up for your discussion list.
How to set up the account for your discussion list.
1. Under the "General" sheet, verify that all the information is correct.
2. Under the "Transport" sheet, verify that all the information is correct.
3. For the first few weeks of your list's "life", you should check the "Deferred" option in the "Delivery" options on the "Transport" sheet. The reason for this, is that you want to make sure that everything is correct in the outgoing messages to be sent to your subscribers before they get sent.
4. Under the "Mail Management" sheet, you shouldn't have to change anything.
5. Under the "Options" sheet, set whatever options you prefer to use. You may want to leave the "Empty trash folder on exit" unchecked for the first few weeks of list "life" also. Sometimes you make a mistake in mail handling, and may accidentally delete a message.
6. Under the "Files and Directories" sheet, you may have to modify the "Home Directory" depending on whether you specified a different "Extract To" path in step 4 of the "How to "import" the IDL account into The Bat!".
7. Click the "+" in front of the "Templates" sheet.
8. Select "New Message". We are now going to set this template up. Hopefully you have given some thought as to what you would like your messages to look like when you post to your own discussion list. The merit to having the below boilerplate:-- ***************************************************Report problems to: <mailto:ldgregory@biogate.com>;Check the IDL FAQ: <http://www.idl.com/FAQ>;To unsubscribe, click here:<mailto:list@idl.net?subject=Unsubscribe_IDL>;***************************************************Is that your subscribers will be reminded each time you post a message to your own discussion list of how to report problems, unsubscribe, and where your discussion list web site or FAQ is. You can make this contain as much or as little information as you want, but I would suggest keeping it short. Take very careful notice of the two dashes right above the boilerplate. Please note that it is '-- ' (dash dash space). The trailing space is extremely important. What this is for, is that TB cuts off any text following the '-- ' when you reply to a message. How this works in your favor is like this.You send a message to the list, at the bottom of this message is your boilerplate. Now if you don't have the '-- ', then when someone replies to your message, the boilerplate is quoted. This basically helps you to keep the posts looking nice and clean.
This next block is your macros. Let me show them to you and then I'll explain what they are doing.%TO="IDL Members <list@idl.net>"%BCC="IDL <list>"%RETURNPATH=""%RETURNPATH="ldgregory@biogate.com"The Bat! requires that you have a valid e-mail address in the TO field. Putting the discussion lists e-mail address in here serves two purposes. The first is that it looks better than putting in your e-mail address. The second and most important, is that when the message is sent, you will receive it again. This sounds stupid, but it is necessary if you wish to verify that your message went out without actually subscribing yourself to your own list, and it allows you to keep the message in its final form just like all the other posts that come from your subscribers. This is useful if you want to create a digest version (which I'll get to later in this article), or if you want to place a searchable message archive on a Web site. The BCC field must contain your address book group that has all of your subscribers in it.. This is very important. If you put the address book group with all of your subscribers in the TO field, then everyone who is subscribed to your discussion list will see everyone else's e-mail address who is also subscribed to the discussion list. This is considered very bad netiquette.The RETURNPATH is very important in that it provides an e-mail address for bounced messages to come back to instead of your subscribers. Trust me, you have to have it in there, I learned the hard way with my list. Why are there two of them? Well, there's an undocumented feature in The Bat! that allows you to run a macro with a NULL input. What this does is to clear the field so that the second occurrence of the macro can fill it without worrying about what was stored in it previously. This will become much more easily understood when we get to the filtering section (filter four).
10. Select the "Reply" template. Again, you'll want include the boilerplate to remind the subscribers when you reply to a subscribers post. Here are the macros:%TO""%TO="%OFROMNAME <list@idl.net>"%BCC="IDL <list>"%RETURNPATH=""%RETURNPATH="ldgregory@biogate.com"Here's where the NULL value macro becomes a little easier to understand. Let's say "Billy Bob" <bbob@somewhere.com> sends a post. If I want to reply to his message before it gets sent to the list, and send my reply to the list, then I need to change his TO info so that it matches with what we are going to do in the filtering section to all of the messages posted. Namely change the TO, and REPLY-TO information. Again, just hang on a little while and I'll explain this fully in the filters section.
11. This pretty much concludes the account setup. You shouldn't have to use the forward template, and you can put whatever cookies in the cookies template that you want to use.
12. One last thing about the account settings. There are five folders (other than the default ones) included the IDL account. Here's what they are for. ***** Note: If you don't see the below folders, select the IDL account, then hold down the CTRL-ALT-SHFT-L keys simultaneously. This will force TB to search for any missing folders in that account.SPAM - This is the folder I move SPAM to. I'm pretty aggressive in tracking down spammers. If you are interested, I wrote an article for my weekly e-zine entitled "To Catch A Spammer". Moderated - I've already explained this one, but it is where the messages in their final form (as they were distributed to your subscribers) will reside after the "Move moderated incoming messages" filter processes it.Failures - This folder will be used to catch bounce messages. Believe me, you will get them. Remember the RETURN-PATH macro? This is what its main purpose is for. Please ensure that the e-mail address you use in RETURN-PATH is different than the one your subscribers use to post and Un/Subscribe to. This will keep the bounce messages from possibly being missed by the filters in your IDL account and getting sent out to your subscribers. IDL Subscribers - This is the folder that I move the Subscribe requests to, once I have verified that they have been added to the address book. This provides three functions. One is that at a glance, I can tell how many people are subscribed to the discussion list. Two, I have a record of subscribes. This way if someone later on says that I am spamming them, I can prove that they (or at least someone pretending to be them) did indeed subscribe, and three, if someone did not use the correct string to subscribe i.e. they sent a message with the words "Subscribe IDL " in the body of the message as opposed to the subject, you can just copy their e-mail address to the clipboard, right click on the "IDL Subscribers" folder, select "Create a new message" which will create a new message with the "Subscription receipt" in it. All you have to do is paste the subscribers e-mail address into the TO field and send it.*** NOTE: I have used text files for inclusion into the templates for both "IDL Subscribes" (both filter and folder), and "IDL Unsubscribes" (both filter and folder) that contain the actual text or the Un/Subscribe. This way, if you make changes, you can do it in one place and it updates both the filter and folder versions. If you specified a different "Extract To" path in step 4 of the "How to "import" the IDL account into The Bat!", then you will need to change the directory path in all the templates (both folder and filter) for IDL Un/Subscribes.IDL Unsubscribers - Serves the same function as the "IDL Subscribers", but is for unsubscribers. If a subscriber messes up the unsubscription process i.e. puts the words "Unsubscribe IDL" in the body as opposed to the subject, then you can cut and paste their address into the "Create a new message" option when you right click the "Unsubscribe IDL" folder.
This is the area that will make or break your mailing list. You will need at least four of the fiver filters that I will be explaining for the basic operation.
1. While the IDL account is highlighted, click "Account" and select "Sorting office/filters"
2. Click the "+" in front of "Incoming messages"
What we are actually doing with this filter is searching the kludges for the string [RETURN-PATH: ldgregory@biogate.com]. This is something we have modified in filter four to solve two problems: The first is bounce messages get sent to the designated address, and two we can use it as our search string, because it will only appear in messages we have already processed.
Of course you could just send these messages to the trashcan, but if you are going to participate in your own discussion list, it is easier to reply to this message than cutting and pasting all their info during the first time it comes through. Also, if you decide later on to build a searchable message-base on a Web site, you will have the message in its final, post filter-processed form.
To subscribe to the IDL mailing list, click here:<mailto:list@idl.com?subject=Subscribe_IDL>
If you click on this link, The Bat! will create a new message with the subject line filled in with "Subscribe_IDL", now all the prospective subscriber has to do it click send.
After you have highlighted the filter named "Susbcribe_IDL" do this:
1. Change the filter name in the "Name" field to whatever you wish to call it.
2. Change the filter string in the field "Strings" to whatever you will use as your subscribe filter string.
3. Click the "Alternatives" tab.What we are going to do here is to try and idiot proof your list a little. Believe me, no matter how hard you try, you will always have people trying to subscribe/unsubscribe from your list using everything but the correct keywords.The alternatives tab is for "ORing" your filter strings. For more information on this, check the TB help file under "Mail Filtering (Sorting Office)" "Signal Strings".On this sheet, you will want to change all the different variations of the subscribe signal string to match your list needs.
4.Click the "Actions" tab.
5. Check the "Send Auto-Reply" checkbox.
6. Click the "Template" button.Here's where you will tell the new subscriber about the list, what to expect, what e-mail address to use to post messages, some rules (concerning flaming, beating a dead horse etc), where to report problems etc. Take some time to think out what you want to put in here. You can use or modify the sample template to fit your needs.If you read the entire sample, you would have noticed at the bottom there was a macro. It was like this:%SUBJECT="IDL Discussion List Subscription Receipt."Because this is a new message created by the filter, you should specify a subject to be placed in the SUBJECT field. The TO field will have whatever e-mail address is specified in the subscribers REPLY-TO information. Here's something important to remember, this message will contain in the FROM and REPLY-TO fields whatever information you have specified in the account that calls this filter (In this case it's the IDL account settings). This is why you should set up a separate account in The Bat! when running a discussion list. You can specify that your FROM information say something like "IDL Discussion List Moderator <list@idl.net>" and your REPLY-TO info "Leif Gregory <list@idl.net>"
7. Also on the "Actions" sheet, you'll see that I have checked the "Add the sender's address to the address book" option. This option allows new subscribers to be automatically added to your address book group for the list. Make sure you change the name of the address book group listed to the one you are using for the list. ***** Note: If you check under the unsubscribe filter (filter three), you'll notice that the option to automatically remove an unsubscriber's address is not enabled. Unfortunately, TB does not currently check to see if the address really exists in the group before deleting it. What this means is if someone trys to unsubscribe from your list, but tries to do it under the wrong e-mail address, then TB will happily comply, but in reality does nothing other than to send them the unsubscription receipt saying they were successfully unsubscribe. Of course this person will probably send you some nasty e-mail when they continue receiving posts to the list. For now, it is better to do it manually. The way it is set up now, the unsubscribe receipt will still be automatically generated, but you can intervene before it is sent out if the address proved to be incorrect when you manually try to delete them from the address book group.
Under the "Rule" tab, your first filter string should be: [list@idl.net], select the "Recipient" location, and presence is "Yes". This is a SPAM measure. Most times when you receive SPAM, the recipient list has been suppressed, meaning your e-mail address is not displayed along with all the other unlucky recipients of the SPAM. So by specifying "list@idl.net" you will be eliminating a huge majority of SPAM from making it to your subscribers.
The second filter string should be: [Subscribe_IDL], select the "Subject" location, and presence is "No". This will ensure that Subscribe requests don't get sent to the rest of your subscribers.
The third filter string should be: [Unsubscribe_IDL], select the "Subject" location, and presence is "No". This will ensure that unsubscribe requests also don't get sent.
Under the "Actions" tab scroll down till you see "Create a message for", put your name and e-mail address here like this: "Leif Gregory"<list@idl.net> Now click the template button. Here is what the stuff in the template means:
The %TEXT is going to cut and paste the posters text into this message. You don't want to use the %QUOTE macro, because that's not what you want.
The three blank macros "TO, REPLYTO, and FROM" are an undocumented feature in The Bat! What happens when you don't specify any text between the quotes is that it blanks out the field (A NULL value.) Remember when you put your name and e-mail address in the field under the action "Create a message for"? Well, if you don't blank out this field, that info will appear here in addition to the info placed there by the second occurrence of "TO" in the above macro. This is a bad thing. The REPLYTO and FROM fields will contain the information you specified in the IDL account settings, so we want to blank these out.Ok, now on to the second occurrences of TO, REPLYTO and FROM. When a subscriber posts a message, and the other subscribers receive it, you want the TO, FROM and REPLYTO information to reflect the person who posted the message. i.e. say Billy Bob <bbob@user.com> posts a message to the list. When a subscriber receives the message, you want the TO field to say "IDL Discussion List <list@idl.net>" (unless they were replying to someone's message, then you would want it to have the repliees address here.), you want the REPLYTO field to say "Billy Bob <list@idl.net> (This is extremely important! The REPLYTO header is the address that is used when someone replies to a message. We want the replies to come back to the list, so that they will get sent to all the other subscribers too. If the replyer wants to send a private message to only Billy Bob, then they should cut and paste the address in the FROM field), which brings up what you want displayed in the FROM field. You want it to say "Billy Bob <bbob@user.com>" (You want the subscribers real e-mail address here.) With that out of the way, let's dissect the macros.
%TO="%OTONAME <list@idl.net>" Remember when I said that you wanted the TO field to display "IDL Discussion List" unless the post is a reply? Here's what happens in this macro. %OTONAME takes all the text except the actual e-mail address i.e. "IDL Discussion List", or in the case of a reply "Billy Bob" and puts it into the TO field. We are then specifying that the e-mail address be <list@idl.net>. So the new TO address will be "IDL Discussion List <list@idl.net>" or in the case of a reply "Billy Bob <list@idl.net>" .
%ReplyTo=%OFROMNAME <list@idl.net> When a subscriber replies to a message, this is the actual e-mail address it will use. We are taking the original posters name and changing the e-mail address so that the reply gets sent to the list instead of the original poster personally.
%From="%OFROMNAME <%OFROMADDR>" Here we are using all of the original posters real information. Their real name and real e-mail address.
%BCC="IDL <list>" This is your address book group entry. Of course we do not want to show everyone on the list who else is also subscribed to the list, so we put it in the Blind Carbon Copy (BCC) field. This also help to prevent spamming of your subscribers.
Right now, this is one area when The Bat! is kind of weak. I have asked RIT Labs to try and work on this area just a little more. I would have included this section in the filters section, but I didn't feel that it has the proper capability to really be used as a digest generator. There is an option on the "Actions" tab for "Export message to file". The problem is that you can either include all of the kludges (really messy looking), or none of the kludges (difficult to reply to people or to see who wrote the message and it's subject.) I asked RIT Labs if they could allow you to select which kludges to include in the exported message. I think that these kludges are necessary (DATE, FROM, REPLYTO, TO and SUBJECT,). If you wish to experiment around with the digest generator anyway, do this:
In the IDL filters, click the "+" in front of "Incoming messages".
Select "Move moderated incoming messages".
Select the "Actions" tab.
Scroll down till you see "Export message to file".
Put a checkmark in the box.
Click the "Browse" button to the right of the pathname field.
I have already selected the "TBDigest.TXT" file. I'd suggest keeping a copy of all the digests you create for future use (on a web site etc).
If you specified a different "Extract To" path in step 4 of the "How to "import" the IDL account into The Bat!", then you will need to change the directory path to reflect your directories.
Put a checkmark in the "Append to existing file" radio button.
Exit out of the filters dialog window.
To send a digest to someone (You'll have to do this manually, as there is no way currently to define to TB when to send these digests out.) right click on the "Digest" folder, select "Create a new message". You should be able to just click send from here.
Remember to empty out the "TBDigest.TXT" after sending it, because then you'll just append more messages to the end.
Also remember to set up an address book group called "IDL Digest" (Or change it to whatever.)
Ok, we're done. You have all of the stuff necessary to start your own discussion list. If you have any additional questions or find any faults in this how-to, please e-mail me at:
"Leif Gregory <ldgregory@pcwize.com>"
I will be glad to answer any questions you may have.
No matter how hard you try, there is always something that didn't get covered. Here are the answers to some common problems people using this how-to have come up against.
The RETURN-PATH doesn't seem to be working / posts that have already been processed and sent out to the list are being treated like new posts when they come back through the system.
Most likely the SMTP or POP server you are using is removing the RETURN-PATH statement from the header. Some are set up this way, and you might be able to get the administrator of that server to change that. If not, then you will most likely have to find a different SMTP or POP server.
To determine which is actually the culprit, create a new message from the IDL list, remove the addresses from the TO and BCC fields (you might have to enable the viewing of these fields first by clicking "View" in the message editor window and putting a check mark next to them.) Once you have cleared out these addresses, put my address <ldgregory@pcwize.com> in the TO field and send it to me. Of course, please type something in telling me why you are sending the message to me. I'll check the headers, and if it is missing, then the culprit is your SMTP server. I will then send you a reply that has a RETURN-PATH statement in it as well, you check the headers to see if it is there. If not, then your POP server is deleting them as well.
I've got a problem with a person who used to be subscribed, but I unsubscribed them because they either didn't follow the list rules or were causing problems. Even though they are unsubscribed, they can still post to the list.
Unfortunately, there is no way to have TB check to see if a post is coming from a person in the subscriber address book group. The only thing I can tell you is to put a filter in the incoming filter section to move their messages to the trash. Make sure you put that filter at the top of the list using the "move up" button. TB checks messages against filters in the order they are listed. Therefore, if you don't put it above at least filter four, then their messages will still get processed
Copyright © 1998-2000 Leif Gregory. All rights reserved.
After many discussions and tests, we have decided that the best way of interacting with other programs with The Bat! is the old good Command Line. The command line is a text string that is passed to the system whenever any program is executed; it contains the path to the program with the following set of parameters. In Windows, you can start a program via Start Menu “Run...” command or by clicking on a Shortcut on the Desktop or in Start menu. If you start a program by clicking a Shortcut, you can edit the command line for the program in Shortcut Properties “Target” input box.
For The Bat!, the Command Line in a Shortcut usually looks like this:
“C:\Program Files\The Bat!\TheBat.EXE”
You can add some start-up parameters to it to define a set of actions performed whenever you open the Shortcut. For example, if the Shortcut is located in the Windows Startup folder, you may want to switch The Bat! startup Logo off by adding /NOLOGO parameter, so the “Target” property of the shortcut becomes something like this:
“C:\Program Files\The Bat!\TheBat.EXE” /NOLOGO
We have implemented a set of Command Line parameters (we call them commands) helping to perform some actions within The Bat! without doing this manually, so it is possible to use The Bat! from batch files or other programs as an e-mail transport without knowing details of Internet mailing and for performing automatically scheduled tasks (for example, checking for new mail at particular time and then exiting so The Bat! would not use your systems resources for a long time).
Note that you can run only one copy of The Bat! at your PC at a time, but if you try to start another copy of The Bat!, all Command Line parameters will be seamlessly passed to the running copy of the program and executed.
For those who are familiar with programming we give a hint: The Bat! checks the file called TheBat.IPC which is located in the same directory where The Bat! executable (TheBat.exe) file is located. In this text file, each line represents one command that could be executed by the program, so you can write commands to this file directly and control The Bat! on your PC even over a local network. Note that TheBat.IPC is deleted as soon as all commands from it are executed, so if this file do not exist, you must create it.
To ensure that a copy of The Bat! is running on a computer, a program which wants to interact with The Bat! must check whether the mutex called “The Bat!” is owned by a process and if it is not, The Bat! must be started.
/CHECK can be used as a command line parameter for The Bat! whenever you want to check mail for one or several accounts.
/CHECKALL command is used for checking mail for all accounts and exiting from The Bat! if there were no new messages received. It is a shortcut for the combination of /CHECK* /SMARTEXIT
The syntax of /CHECK command is:
/CHECK<account mask1>[;account mask2[;account mask3[...]]]
Account mask is used for identification of a single or multiple accounts for performing the operation. It can be:
-the full name of a single account. Example: /CHECK”My account 1”;”My account 2”. This instructs The Bat! to check new mail for two accounts with names ”My account 1” and ”My account 2” (note that quotation marks are not included into accounts names they are used only because the names contain space characters)
-the beginning of a name ending with asterisk. Example: to check new mail for all accounts with names starting with word “My”, use /CHECKmy*
-asterisk with following ending of a name. Example: /CHECK*1 will check new mail for all accounts with names ending with “1”.
-a name fragment included in asterisks. Example: /CHECK*account*
-an asterisk which mean that all accounts will be checked
Notes:
1.To separate account masks, use semicolon (“;” character). Do not use spaces between account masks when use /CHECK command as a command line parameter because a space-separated mask will be treated as the next command line parameter and will not be processed.
2.If a mask contains space characters, put it into quotation marks as it shown in the first example. If a mask contains quotation marks, you should use upper commas (“ ” character).
/SEND can be used as a command line parameter for The Bat! whenever you want to send all queued mail from one or several accounts.
/SENDALL command is used for sending queued mail from all accounts and exiting from The Bat! if there were no new messages received. It is a shortcut for the combination of /SEND* /SMARTEXIT
The syntax of /SEND command is:
/SEND<account mask1>[;account mask2[;account mask3[...]]]
Account mask is used for identification of a single or multiple accounts for performing the operation. It can be:
-the full name of a single account. Example: /SEND”My account 1”;”My account 2”. This instructs The Bat! to send queued mail from two accounts with names ”My account 1” and ”My account 2” (note that quotation marks are not included into accounts names they are used only because the names contain space characters)
-the beginning of a name ending with asterisk. Example: to send queued mail from all accounts with names starting with word “My”, use /SENDmy*
-asterisk with following ending of a name. Example: /SEND*1 will send queued mail from all accounts with names ending with “1”.
-a name fragment included in asterisks. Example: /SEND*account*
-an asterisk which mean that queued mail will be sent from all accounts
Notes:
1.To separate account masks, use semicolon (“;” character). Do not use spaces between account masks when use /SEND command as a command line parameter because a space-separated mask will be treated as the next command line parameter and will not be processed.
2.If a mask contains space characters, put it into quotation marks as it shown in the first example. If a mask contains quotation marks, you should use upper commas (“ ” character).
/IMPORT command allows batch importing of e-mail messages into a specified folder from multiple RFC-822 message files or from UNIX mailbox files. The syntax of /IMPORT command is:
/IMPORT[parameter1[;parameter2[;parameter3[...]]]
Possible parameters are (parameter may be identified by two or more names):
USER=value or U=value- the value is the name of the destination account. If no FOLDER parameter is specified, the destination folder will be Inbox of the given account.
PASSWORD=value or P=value- the value is the password which will unlock the account if it is needed.
FOLDER=value or F=value- the value is the destination folders pathname. If the pathname does not include account name, The Bat! will search all accounts for a folder with such name; the first folder found will be used as the destination folder. If the specified folder is not found, Inbox folder of the destination account is used.
UNIX or X- this parameter tells The Bat! that input files are in UNIX mailbox format. By default, input files are treated as separate RFC-822 messages.
READ or R- when this parameter is used, all imported messages will be marked as read. By default, all imported messages are marked unread.
FILE=value or IN=value or
INFILE=value or I=value- the value is a file mask with a pathname of input files. /IMPORT command can have unlimited number of FILE parameters.
DELETE or DEL or W- if this parameter is specified, all processed files will be deleted after successful send of import operation.
/IMPORTF=”\\My account 1\Business\Unsorted”;UNIX;FILE=C:\InFiles\Unsorted\*.mbx;READ
Notes:
1.To separate parameters, use semicolon (“;” character). Do not use spaces between parameters when use /IMPORT command as a command line parameter because a space-separated mask will be treated as the next command line parameter and will not be processed.
2.If a parameter value contains space characters, put it into quotation marks. If a value contains quotation marks, you should use upper commas (“ ” character).
/EXPORT command allows batch exporting of e-mail messages from a specified folder to multiple RFC-822 message files or to UNIX mailbox files. This command also allows exporting of address book entries if the LDIF parameter is specified. The syntax of /EXPORT command is:
/EXPORT[parameter1[;parameter2[;parameter3[...]]]
Possible parameters are(parameter may be identified by two or more names):
USER=value or U=value- the value is the name of the source account. If no FOLDER parameter is specified, the source folder will be Inbox of the given account.
PASSWORD=value or P=value- the value is the password which will unlock the account if it is needed.
FOLDER=value or F=value- the value is the source folders pathname. If the pathname does not include account name, The Bat! will search all accounts for a folder with such name; the first folder found will be used as the source folder. If the specified folder is not found, Inbox folder of the source account is used.
DIR=value or D=value or
OUT=value or O=value- the value is the pathname of the output directory (for RFC-882 messages) or the output file (for UNIX mailbox). If RFC-822 format is chosen, the exported messages are stored in the output directory in files with names xxxxxxxx.MSG (each “x” character corresponds to a digit from 0 to 9). When export starts, The Bat! calculates the starting xxxxxxxx number by searching the output directory for the files with names in the same format and, in case when such files are found, the output file names will represent greater numbers than the greater found. For example, if file 00001234.MSG was in the output directory, the first exported message will be named as 00001235.MSG.
UNIX or X- this parameter tells The Bat! that output file must be in UNIX mailbox format. In this case, DIR parameter specifies the name of the output file. By default, output files are in RFC-822 message format.
READ or R- when this parameter is used, only read messages are to be exported. By default, all read and unread messages are to be exported.
UNREAD or N- when this parameter is used, only unread messages are to be exported.
REPLIED or RE- when this parameter is used, only replied messages are to be exported. By default, all replied and non-replied messages are to be exported.
UNREPLIED or NR- when this parameter is used, only non-replied messages are to be exported.
PARKED or PR- when this parameter is used, only parked messages are to be exported. By default, all parked and non-parked messages are to be exported.
UNPARKED or UP- when this parameter is used, only non-parked messages are to be exported.
MAXAGE=value or AGE=value or
A=value- the value specifies the maximum age (in days) of exported messages. If age of a message exceeds the specified maximum age, the message will not be exported. By default the maximum age is not limited.
START=value or S=value- the value specifies the number of the starting message in the source folder. All messages located before the starting messages will not be exported. If a negative value is given, the starting message number is calculated by subtracting the positive value from number of messages in folder, for example, if 5 is given, this means that export will start from fifth message from the end of message base.
END=value or E=value- the value specifies the number of the ending message in the source folder. All messages located after the ending messages will not be exported. If a negative value is given, the ending message number is calculated by subtracting the positive value from number of messages in folder, for example, if 2 is given, this means that export will end at second message from the end of message base.
OVERRIDE or V- (only when either UNIX or LDIF parameter is specified) if this parameter is specified, The Bat! will override the output file in case when it exists. By default, The Bat! adds new messages to the end of the mailbox file.
DELETE or DEL or W- if this parameter is specified, all processed messages will be deleted after successful end of export operation.
LDIF- if this parameter is specified, export of addresses will be performed. The OUTPUT parameter must specify the name of the output file that will receive exported data in LDIF format.
ADDRESSBOOK=value or AB=value or
BOOK=value- (only with the LDIF parameter) the value specifies name, filename or the full path of the address book which should be exported. If no address book specified, The Bat! will use the default address book.
GROUP=value or G=value- (only with the LDIF parameter) the value specifies the handle of the address group which should be exported. If no address book explicitly specified, The Bat! will search all address books for the first group with the specified handle.
/EXPORTF=”\\Account1\Business\Unsorted”;UNIX;O=C:\InFiles\Unsorted\Mail.mbx;UNREAD
/EXPORTLDIF;AB=”My Book”;Group=”My Group”;O=”C:\MyGroupFile.LDIF”
/EXPORTLDIF;Group=”My Test Group”;O=”C:\MyTestGroup.LDIF”
Notes:
1.To separate parameters, use semicolon (“;” character). Do not use spaces between parameters when use /EXPORT command as a command line parameter because a space-separated mask will be treated as the next command line parameter and will not be processed.
2.If a parameter value contains space characters, put it into quotation marks. If a value contains quotation marks, you should use upper commas (“ ” character).
/FOCUS command allows to automatically focus the specified folder in the main window. This command is especially useful at the programs startup. The syntax of /FOCUS command is:
/FOCUS[parameter1[;parameter2[;parameter3[...]]]
Possible parameters are(parameter may be identified by two or more names):
USER=value or U=value- the value is the name of the source account. If no FOLDER parameter is specified, the target folder will be Inbox of the given account.
PASSWORD=value or P=value- the value is the password which will unlock the account if it is needed.
FOLDER=value or F=value- the value is the target folders pathname. If the pathname does not include account name, The Bat! will search all accounts for a folder with such name; the first folder found will be used as the target folder. If the specified folder is not found, Inbox folder of the target account is used.
Notes:
1.To separate parameters, use semicolon (“;” character). Do not use spaces between parameters when use /FOCUS command as a command line parameter because a space-separated mask will be treated as the next command line parameter and will not be processed.
2.If a parameter value contains space characters, put it into quotation marks. If a value contains quotation marks, you should use upper commas (“ ” character).
/MAIL command is used for automated message creation from a template, text file and/or set of attached files for a specific address. This command is extremely useful for applications that require sending e-mail messages without making a lot of additional work connected to implementation of Internet standards. The syntax of /MAIL command is:
/MAIL[parameter1[;parameter2[;parameter3[...]]]
Possible parameters are(parameter may be identified by two or more names):
USER=value or U=value- the value is the name of the source account. If no FOLDER parameter is specified, the target folder will be Inbox of the given account.
PASSWORD=value or P=value- the value is the password which will unlock the account if it is needed.
FOLDER=value or F=value- the value is the target folders pathname. If the pathname does not include account name, The Bat! will search all accounts for a folder with such name; the first folder found will be used as the target folder. If the specified folder is not found, Inbox folder of the target account is used.
TEMPLATE=value or T=value- the value is the pathname of the file which contains the template which must be used for the message creation. By default, it is the template of the target folder or the target account.
TO=value- the value specifies the primary addressee of the message. You can add additional addressees by template macros %TO, %CC, %BCC.
SUBJECT=value or S=value- the value specifies the subject of the message. It is also possible to define message subject in the template using %SUBJECT macros.
TEXT=value or CONTENTS=value or
C=value- the value is the pathname of the plain text file which contains the text of the message. It is also possible to include a text file into a message using %PUT macro in the template.
ATTACH=value or FILE=value or
A=value- the value is the pathname of the file which must be attached to the message. It is also possible to use %ATTACHFILE macros in the template.
SEND- if this parameter is used, the created message will be immediately sent out once it is created.
QUEUE- if this parameter is used, the created message will be queued in the Outbox once it is created.
/MAILF=\\MyAccount\Test;TO=some@address.com
Notes:
1.To separate parameters, use semicolon (“;” character). Do not use spaces between parameters when use /EXPORT command as a command line parameter because a space-separated mask will be treated as the next command line parameter and will not be processed.
2.If a parameter value contains space characters, put it into quotation marks. If a value contains quotation marks, you should use upper commas (“ ” character).
mailto: command is used to force The Bat! to open a new editor window with some pre-set parameters. mailto: is a standard Internet URL for publishing e-mail addresses and is described in RFC 2368. This command line parameter is usually used by browsers which need to open an e-mail editor when user clicks on a link which contains mailto: URL.
If you need to execute a lot of commands many times, /BATCH command is the saver. This command allows executing multiple commands defined in a text file; each command is placed in one line. The syntax of /BATCH command is:
/BATCH:<filepath>
For example, if you have to check your account and send queued mail from it, you can create a batch file C:\The Bat!\CheckMail.BAT which will contain three lines:
/CHECKMyAccount
/SENDMyAccount
/SMARTEXIT
To execute this batch from a command line, you can run The Bat! with command line parameter /BATCH:C:\The Bat!\CheckMail.BAT
All of the commands below can be sent to The Bat! at the programs start-up or during its operation.
/EXIT command is used to force The Bat! to exit as soon as all mail transfer operations are finished.
/SMARTEXIT command is used to force The Bat! to exit as soon as all mail transfer operations are finished and if there were no new messages received.
/MINIMIZE command forces The Bat! to minimise.
/NOLOGO command can be used only at start-up of The Bat!. When it is used in the programs start-up command line, The Bat! Logo screen will not be displayed while program is loading its data. This feature can be used when The Bat! should run at your systems start-up automatically.
Quick Templates are designed for saving hours of typing similar blocks of text in your messages. This feature is extremely useful especially when you do any kind of support via e-mail and have to answer on similar questions. With Quick Templates, it is also possible to attach files, vCard and change other settings of a message without quitting typing a message and using menus. Note that all template macros are working in Quick Templates just like in other templates used within The Bat!
Each Quick Template has a unique handle, which should be easily remembered by you. When you want to insert a Quick Template in your message, just type its handle in the text and press Ctrl+Space the typed handle will be replaced with the text block accordingly to the used template. If you do not remember the handle, you still can use the “Utilities | Insert Quick Template” menu of the message editor.
Quick Templates are associated with an account, so you can edit them from Account Properties dialogue: at the Templates page, press the Edit Quick Templates” button. It is also possible to edit Quick Templates using the “Options | Quick templates” menu command from the main program window. If you want to share a Quick Template between other accounts, tick the appropriate check box in the template editor.
A Template Macro is a special command to the template processor that can generate text, set some message parameters etc. The macro when it is inserted into a template always starts with the “%” symbol followed by the name and an optional parameter in double quotes. Here is the complete list of possible names:
TONAME- insert the full name of the first TO addressee
TOFNAME- insert the first name of the first TO addressee
TOLNAME- insert the last name of the first TO addressee
FROMNAME- insert the full name of the sender
FROMFNAME- insert the first name of the sender
FROMLNAME- insert the last name of the sender
REPLYNAME- insert the full name of the reply recipient
REPLYFNAME- insert the first name of the reply recipient
REPLYLNAME- insert the last name of the reply recipient
OTONAME- (replies and forward) insert the full name of the first TO addressee of the original message
OTOFNAME- (replies and forward) insert the first name of the first TO addressee of the original message
OTOLNAME- (replies and forward) insert the last name of the first TO addressee of the original message
OFROMNAME- (replies and forward) insert the full name of the sender of the original message
OFROMFNAME- (replies and forward) insert the first name of the sender of the original message
OFROMLNAME- (replies and forward) insert the last name of the sender of the original message
OREPLYNAME- (replies and forward) insert the full name of the reply recipient of the original message
OREPLYFNAME- (replies and forward) insert the first name of the reply recipient of the original message
OREPLYLNAME- (replies and forward) insert the last name of the reply recipient of the original message
TOADDR- insert the first TO e-mail address
FROMADDR- insert the address of the sender
REPLYADDR- insert the address of the reply recipient
SUBJ- insert the subject of the message
OSUBJ- (replies and forward) insert the subject of the original message
OTOADDR- (replies and forward) insert the first TO address of the original message
OFROMADDR- (replies and forward) insert the address of the sender of the original message
OREPLYADDR- (replies and forward) insert the address of the reply recipient of the original message
ORGANIZATION,
ORGANISATION- insert the organisation name
OORGANIZATION,
OORGANISATION- (replies and forward) insert the organisation name from the original message
TOLIST- insert the full list of recipient in the TO address field
CCLIST- insert the full list of recipient in the CC address field
BCCLIST- insert the full list of recipient in the BCC address field
OTOLIST- (replies and forward) insert the full list of recipient in the TO address field of the original message
OCCLIST- (replies and forward) insert the full list of recipient in the CC address field of the original message
OBCCLIST- (replies and forward) insert the full list of recipient in the BCC address field of the original message
DOW- insert the current day of week
ODOW- (replies and forward) insert the day of week of the original message
CURSOR- place the caret the message editor in the position of this macro. This macro does nothing for automatically generated messages.
TEXT- insert the text of the original message
QUOTES- insert the quoted original message text
QUOTES="string"- insert quoted string
HEADERS- insert the RFC-822 headers of the original message
QHEADERS- insert the quoted RFC-822 headers of the original message
COOKIE- insert a random cookie from the current accounts cookies
COOKIE=”filepath”- insert a random cookie from the file defined by the filepath. This allows using virtually unlimited amount of cookies.
DATE- insert the current date in the long date format (defined by the systems country settings)
DATESHORT- insert the current date in the short date format (defined by the systems country settings)
ODATE- (replies and forward) insert the date of the original message in the long date format (defined by the systems country settings)
ODATESHORT- (replies and forward) insert the current date of the original message in the short date format (defined by the systems country settings)
TIME- insert the current time in the short time format (defined by the systems country settings)
TIMELONG- insert the current time in the long time format (defined by the systems country settings)
OTIME- insert the time of the original message in the short time format (defined by the systems country settings)
OTIMELONG- insert the time of the original message in the long time format (defined by the systems country settings)
DATEEN- insert the current date in “day-of-week, month day, year” format. The day-of-week and month are full words in English
ODATEEN- insert the date of the original message in “day-of-week, month day, year” format. The day-of-week and month are full words in English
TIMELONGEN- insert the current time in “hour:minutes:seconds AM/PM” format
OTIMELONGEN- insert the time of the original message in “hour:minutes:seconds AM/PM” format
REPLYCOUNTER,
RECOUNT- insert the numbered reply counter of the current message. This can be used in %SUBJECT macro: %SUBJECT=”%RECOUNT Why dont we change the subject?”
OREPLYCOUNTER,
ORECOUNT- insert the numbered reply counter of the original message.
TO=””- remove all recipients from the TO field
TO=”address(es)”- add address(es) to the TO field
CC=””- remove all recipients from the CC field
CC=”address(es)”- add address(es) to the CC field
BCC=””- remove all recipients from the BCC field
BCC=”address(es)”- add address(es) to the BCC field
FROM=”address”- redefine the default FROM field contents with the address data
REPLYTO=”address”- redefine the default REPLY-TO field contents with the address data
RETURNPATH=”address”- redefine the default RETURN-PATH field contents with the address data
SUBJECT=”subject”- set the new subject to the message
CHARSET=”Charset ID”- set the current message character set to the character set that corresponds to the Charset ID. All possible character sets with their IDs are defined in the “Options | XLAT Tables” dialogue.
ACCOUNT=”Account Name”- set the active account to the account with the name equal to Account Name.
READCONFIRM- set the Reading Confirmation Request flag for the current message.
RCPTCONFIRM- set the Receipt Request flag for the current message.
SIGNCOMPLETE- automatically ask to sign the current message when it is completed
ENCRYPTCOMPLETE- automatically encrypt the current message when it is completed
SINGLERE- disable reply counting.
CLEAR- when used in a Quick Template, clears all the previously entered/generated text.
ISSIGNATURE- when used in a Quick Template, tells the message editor that the Quick Template must be used as a signature. In other words, the text generated by the Quick Template replaces everything after the end-of-message line (“-- “, dash-dash-space); if the end-of-message line is not detected, it is added to the end of the message followed by the generated text.
BLANK- this macro is used to create a blank template.
WINDOWSMAJORVERSION- insert Windows major version number
WINDOWSMINORVERSION - insert Windows minor version number
WINDOWSBUILDNUMBER- insert Windows version build number
WINDOWSCSDVERSION- insert Windows additional version information
WINDOWSPLATFORMNAME- insert Windows platform name (e.g. Windows 95, Windows NT)
THEBATVERSION- insert The Bat! version number.
FOLDERFROMNAME- insert FROM name from the current folders Identity properties
FOLDERFROMADDR- insert FROM address from the current folders Identity properties
FOLDERREPLYNAME- insert REPLY-TO name from the current folders Identity properties
FOLDERREPLYADDR- insert REPLY-TO address from the current folders Identity properties
ACCOUNTNAME- insert the name of the active account
FOLDERNAME- insert the name of the current folder
FOLDERORGANISATION,
FOLDERORGANIZATION- insert the Organisation name from the current folders Identity properties
OTEXTSIZE- insert the byte size of the original message
PAGENUMBER- insert the number of the currently printed page
TOTALPAGES- insert the number of the currently printed page
ATTACHMENTS- insert the list of the files attached to the current message
OATTACHMENTS- insert the list of the files attached to the original message
REGEXPTEXT=”regexp”- insert the result of the search of the Regular Expression regexp with the text of the original message as the subject string.
REGEXPQUOTES=”regexp”- insert the result of the search of the Regular Expression regexp as quotation.
SETPATTREGEXP=”regexp”- set the Regular Expression pattern which will be evaluated with the following %REGEXPMATCH macro text parameter as the subject string.
REGEXPMATCH=”giventext ”- insert the result of the search in giventext of the Regular Expression previously set by SETPATTREGEXP=”regexp”.
REGEXPBLINDMATCH=”giventext ”- same as REGEXPMATCH except matching text is not inserted but may be exctracted by SUBPATT="n".
SUBPATT="n"- n is a number of captured substring to be inserted. Substrings are set by REGEXPMATCH or REGEXPBLINDMATCH macros. 0 means text matching entire regexp pattern, 1 - matching first subpattern, 2 - matching second subpattern,. etc...
INSERTPGPKEY=”address”- insert the PGP key from the public key ring. This feature works with the internal PGP implementation only.
INCLUDE=”filepath”- insert the text generated by the template located in the file determined by the filepath.
PUT=”filepath”- insert the text from the file determined by the filepath.
ATTACHVCARD- attach the personal vCard of the active account.
ATTACHFILE=”filepath”- attach a file determined by the filepath.
QINCLUDE=”Quick Template Handle”- insert the text generated by the Quick Template with
LANGUAGE=”Language ID”- set the default spell checker language to the language defined by Language ID. Possible Language IDs can be:
AM - American English
EA - Australian English
BR - British English
CT - Catalan
CZ - Czech
DA - Danish
FI - Finnish
FR - French
FC - French Canadian
GE - German
IT - Italian
NO - Norwegian (Bokmal)
NN - Norwegian (Nynorsk)
NL - Dutch
PB - Portuguese (Brazil)
PT - Portuguese (Iberian)
PL - Polish
SP - Spanish
SW - Swedish
RU - Russian
HU Hungarian
To use Common Speller API dictionaries, the Language ID must be prefixed by “CSAPI”. E.g. %LANGUAGE=”CSAPI RU”
Regular expression matching allows you to test whether a text fits into a specific syntactic shape. You can also search a text for a sub-string that fits a pattern.
A regular expression describes a set of strings. The simplest case is one that describes a particular string; for example, the string foo when regarded as a regular expression matches foo and nothing else. Nontrivial regular expressions use certain special constructs so that they can match more than one string. For example, the regular expression foo|bar matches either the string foo or the string bar; the regular expression c[ad]*r matches any of the strings cr, car, cdr, caar, cadddar and all other such strings with any number of a's and d's.
The Bat! allows using of regular expressions in:
Message Editor
Message Finder
Sorting Office / Filters
Templates
To learn about Regular Expressions, read the following topics:
Regular Expressions Syntax (Basic)
Regular Expressions Syntax (Advanced)
In the message editor/viewer, regular expressions are used for search of sub-strings matching a search pattern. To find a sub-string that matches a regular expression, invoke the search dialogue and type the regular expression, make sure that the checkbox “Regular Expressions” is checked and start search. Regular expressions can also be used for the Replace function in the Message Editor in the same way as they are used in the search dialogue.
If a match found, a text that matches given regular expression will be selected in a message editor/viewer. If the regular expression has subpatterns, the first captured substring will be selected, i.e for the regular expression Total amount: *(\S+) only the word following Total amount will be selected but not Total amount itself.
Default PCRE options for message editor/viewer are PCRE_CASELESS by default or none for "Case sensitive" search. String-by-string matching is done.
See also:
Regular Expressions Syntax (Basic).
Regular Expressions Syntax (Advanced).
Message Editor.
To make the Message Finder use regular expressions as the search pattern, enter the regular expression you want to use, click to the “Advanced” tab and tick the “Regular expressions” checkbox.
Default PCRE options for message finder are PCRE_CASELESS+PCRE_MULTILINE by default or PCRE_MULTILINE for "Case sensitive search". Whole message as one string matching is done. CF/LF characters (0D/0A) are replaced to LF (0A) before matching.
See also:
Regular Expressions Syntax (Basic)
Regular Expressions Syntax (Advanced)
It is possible to use Regular Expressions as signal strings in the message filters. In a filter definition in the Sorting Office dialogue, select the “Options” tab and tick the “Regular expressions” checkbox. Note that ALL signal strings of the filter will be treated as regular expressions so make sure that they all are compliant with the syntax of Regular Expressions.
Default PCRE options for message filters are PCRE_CASELESS+PCRE_MULTILINE. Whole message as one string matching is done. CF/LF characters (0D/0A) are replaced to LF (0A) before matching.
See also:
Regular Expressions Syntax (Basic).
Regular Expressions Syntax (Advanced).
Message Filters.
The Bat! allows to use the power of the regular expressions in the message templates. The general idea is to search a text for the first entry of a sub-string that matches the pattern defined by a regular expression and to insert the search result into the message text. For example, it is possible to parse incoming messages of a particular format and create new messages in other format with added or removed information.
To search the original message text for a sub-string, use %REGEXPTEXT=”regexp” macro where regexp defines the pattern. %REGEXPQUOTES=”regexp” macro do the same, but returns the result as quotation.
When it is needed to search any generic text for a particular sub-string, use %SETPATTREGEXP=”regexp” and %REGEXPMATCH=”string” macros combination. The regexp defines the search pattern for all subsequent occurrences of the %REGEXPMATCH macro until the next occurrence of the %SETPATTREGEXP. The string parameter is a template, so it is possible to use all possible macros to generate any text you need, e.g. %QUOTES="%SETREGEXP=""regexp""%REGEXPMATCH=""%TEXT""" is equivalent to %REGEXPQUOTES="regexp".
If a match found, a text that matches given regular expression will be returned. If the regular expression has subpatterns, the first captured substring will be returned, i.e for the regular expression Total amount: *(\S+) only the word following Total amount will be returned but not Total amount itself.
%REGEXPBLINDMATCH=”string” is like %REGEXPMATCH=”string” macro except matched string/substrings are not returned, they may be further extracted by %SUBPATT="n" macro where n is a number of captured substring; 0 means text matching entire regexp pattern, 1 - matching first subpattern, 2 - second subpattern,. etc.... Thus this %REGEXPBLINDMATCH=”string” macro allows more then one subpatterns e.g.
%QUOTES="%SETPATTREGEXP=""total_amount +(\S+).*flowers_type +(\S+)""%REGEXPBLINDMATCH=""%TEXT""pay %SUBPATT=""1"" for %SUBPATT=""2"""
Default PCRE options for templates are PCRE_CASELESS+PCRE_MULTILINE+ PCRE_DOTALL. Whole message as one string matching is done. CF/LF characters (0D/0A) are replaced to LF (0A) before matching.
See also:
Regular Expressions Syntax (Basic).
Regular Expressions Syntax (Advanced).
Templates.
A regular expression is a set of rules that describes a generalised string. If the characters that make up a particular string conform to the rules of a particular regular expression, the regular expression is said to match that string.
A few concrete examples usually help after an overblown definition like that one. The regular expression b. matches the strings bovine, above, Bobby, and Bob Jones, but not the strings Bell, b, or Bob. That's because the expression insists that the letter b (lowercase) must be in the string and must be followed immediately by another character.
The regular expression b+, on the other hand, requires the lowercase letter b at least once. This expression matches b and Bob in addition to the example matches for b. in the preceding paragraph. The regular expression b* requires zero or more bs, so it matches any string. That seems to be fairly useless, but it makes more sense as part of a larger regular expression. Bob*y, for example, matches all of Boy, Boby, and Bobby but not Boboby.
Assertions Several so-called assertions are used to anchor parts of the pattern to word or string boundaries. The ^ assertion matches the start of a string, so the regular expression ^fool matches fool and foolhardy but not tomfoolery or April fool. The following table lists the assertions.
Regular-Expression Assertions
| Assertion | Matches | Example | Matches | Doesn't Match |
| ^ | Start of string | ^fool | foolish | tomfoolery |
| $ | End of string | fool$ | April fool | foolish |
| \b | Word boundary | be\bside | be side | beside |
| \B | Nonword boundary | be\Bside | beside | be side |
Regular-Expression Atoms
| Atom | Matches | Example | Matches | Doesn't Match |
| Period (.) | Any character except new line | b.b | bob | bb |
| List of characters in brackets | Any one of those characters | ^[Bb] | Bob, bob | Rbob |
| Regular expression in parentheses | Anything that regular expression matches | ^a(b.b)c$ | abobc | abbc |
Quantifiers A quantifier is a modifier for an atom. It can be used to specify that a particular atom must appear at least once, as in b+. The atom quantifiers are listed in the following table.
Regular-Expression Atom Quantifiers
| Quantifier | Matches | Example | Matches | Doesn't Match |
| * | Zero or more instances of the atom | ab*c | ac, abc | abb |
| + | One or more instances of the atom | ab+c | abc | ac |
| ? | Zero or one instances of the atom | ab?c | ac, abc | abbc |
| {n} | n instances of the atom | ab{2}c | abbc | abbbc |
| {n,} | At least n instances of the atom | ab{2,}c | abbc, abbbc | abc |
| {n,m} | At least n, most m instances of the atom | ab{2,3}c | abbc | abbbbcat |
Regular-Expression Special Characters
| Symbol | Matches | Example | Matches | Doesn't Match |
| \d | Any digit | b\dd | b4d | bad |
| \D | Nondigit | b\Dd | bdd | b4d |
| \n | New line | |||
| \r | Carriage return | |||
| \t | Tab | |||
| \f | Form feed | |||
| \s | White-space character | |||
| \S | Non-white-space character | |||
| \w | Alphanumeric character | a\wb | a2b | a^b |
| \W | Nonalphanumeric character | a\Wb | aa^b | aabb |
| Single or double digit | matched quantities after a match. These matched quantities are called backreferences and are explained in a separate section. |
| Two-or three-digit octal number | the character with that number as character code, unless it's possible to interpret it as a backreference. |
| x, followed by two hexadecimal digits | the character with that number as its character code. \x3e, for example, is > |
| c, followed by a single character | the control character. \cG, for example, matches Ctrl+G.
|
| Any other character | the character itself. \&, for example, matches the & character |
Regular Expressions Syntax (Advanced)
The Bat! uses Perl-compatible regular expressions.(PCRE) library. The library is a set of functions that implement regular expression pattern matching using the same syntax and semantics as Perl 5, with just a few differences. The current implementation corresponds to Perl 5.005. The syntax and semantics of the regular expressions supported by PCRE are described in this chapter.
- Meta-Characters.
- Backslash.
- Circumflex and Dollar.
- Full Stop (Period, Dot).
- Square Brackets.
- Vertical Bar.
- Internal Option Setting.
- Subpatterns.
- Repetition.
- Back References.
- Assertions.
- Once-Only Subpatterns.
- Conditional Subpatterns.
- Comments.
- Performance.
- Limitiations.
- Differences From Perl.
PCRE Library and this chapter (Regular Expressions Syntax (Advanced)) are written by Philip Hazel <ph10@cam.ac.uk>, University of Cambridge Computing Service, Cambridge, England. Phone: +44 1223 334714. Copyright © 1997-2000 University of Cambridge
Regular expressions are also described in the Perl documentation and in a number of other books, some of which have copious examples. Jeffrey Friedl's "Mastering Regular Expressions", published by O'Reilly (ISBN 1-56592-257-3), covers them in great detail. The description here is intended as reference documentation.
A regular expression is a pattern that is matched against a subject string from left to right. Most characters stand for themselves in a pattern, and match the corresponding characters in the subject. As a trivial example, the pattern
The quick brown fox
matches a portion of a subject string that is identical to itself. The power of regular expressions comes from the ability to include alternatives and repetitions in the pattern. These are encoded in the pattern by the use of meta-characters, which do not stand for themselves but instead are interpreted in some special way.
There are two different sets of meta-characters: those that are recognised anywhere in the pattern except within square brackets, and those that are recognised in square brackets. Outside square brackets, the meta-characters are as follows:
| \ | general escape character with several uses |
| ^ | assert start of subject (or line, in multiline mode) |
| $ | assert end of subject (or line, in multiline mode) |
| . | match any character except newline (by default) |
| [ | start character class definition |
| | | start of alternative branch |
| ( | start subpattern |
| ) | end subpattern |
| ? | extends the meaning of ( also 0 or 1 quantifier also quantifier minimizer |
| * | 0 or more quantifier |
| + | 1 or more quantifier |
| { | start min/max quantifier |
| \ | general escape character |
| ^ | negate the class, but only if the first character |
| - | indicates character range |
| ] | terminates the character class |
The backslash character has several uses. Firstly, if it is followed by a non-alphameric character, it takes away any special meaning that character may have. This use of backslash as an escape character applies both inside and outside character classes.
For example, if you want to match a "*" character, you write "\*" in the pattern. This applies whether or not the following character would otherwise be interpreted as a meta-character, so it is always safe to precede a non-alphameric with "\" to specify that it stands for itself. In particular, if you want to match a backslash, you write "\\".
If a pattern is compiled with the PCRE_EXTENDED option, whitespace in the pattern (other than in a character class) and characters between a "#" outside a character class and the next newline character are ignored. An escaping backslash can be used to include a whitespace or "#" character as part of the pattern.
A second use of backslash provides a way of encoding non-printing characters in patterns in a visible manner. There is no restriction on the appearance of non-printing characters, apart from the binary zero that terminates a pattern, but when a pattern is being prepared by text editing, it is usually easier to use one of the following escape sequences than the binary character it represents:
| \a | alarm, that is, the BEL character (hex 07) |
| \cx | "control-x", where x is any character |
| \e | escape (hex 1B) |
| \f | formfeed (hex 0C) |
| \n | newline (hex 0A) |
| \r | carriage return (hex 0D) |
| \t | tab (hex 09) |
| \xhh | character with hex code hh |
| \ddd | character with octal code ddd, or backreference |
After "\x", up to two hexadecimal digits are read (letters can be in upper or lower case).
After "\0" up to two further octal digits are read. In both cases, if there are fewer than two digits, just those that are present are used. Thus the sequence "\0\x\07" specifies two binary zeros followed by a BEL character. Make sure you supply two digits after the initial zero if the character that follows is itself an octal digit.
The handling of a backslash followed by a digit other than 0 is complicated. Outside a character class, PCRE reads it and any following digits as a decimal number. If the number is less than 10, or if there have been at least that many previous capturing left parentheses in the expression, the entire sequence is taken as a back reference. A description of how this works is given later, following the discussion of parenthesized subpatterns.
Inside a character class, or if the decimal number is greater than 9 and there have not been that many capturing subpatterns, PCRE re-reads up to three octal digits following the backslash, and generates a single byte from the least significant 8 bits of the value. Any subsequent digits stand for themselves. For example:
| \040 | is another way of writing a space |
| \40 | is the same, provided there are fewer than 40 previous capturing subpatterns |
| \7 | is always a back reference |
| \11 | might be a back reference, or another way of writing a tab |
| \011 | is always a tab |
| \0113 | is a tab followed by the character "3" |
| \113 | is the character with octal code 113 (since there can be no more than 99 back references) |
| \377 | is a byte consisting entirely of 1 bits |
| \81 | is either a back reference, or a binary zero followed by the two characters "8" and "1" |
All the sequences that define a single byte value can be used both inside and outside character classes. In addition, inside a character class, the sequence "\b" is interpreted as the backspace character (hex 08). Outside a character class it has a different meaning (see below).
The third use of backslash is for specifying generic character types:
| \d | any decimal digit |
| \D | any character that is not a decimal digit |
| \s | any whitespace character |
| \S | any character that is not a whitespace character |
| \w | any "word" character |
| \W | any "non-word" character |
A "word" character is any letter or digit or the underscore character, that is, any character which can be part of a Perl "word". The definition of letters and digits is controlled by PCRE's character tables, and may vary if locale- specific matching is taking place (see "Locale support" above). For example, in the "fr" (French) locale, some character codes greater than 128 are used for accented letters, and these are matched by \w.
These character type sequences can appear both inside and outside character classes. They each match one character of the appropriate type. If the current matching point is at the end of the subject string, all of them fail, since there is no character to match.
The fourth use of backslash is for certain simple assertions. An assertion specifies a condition that has to be met at a particular point in a match, without consuming any characters from the subject string. The use of subpatterns for more complicated assertions is described below. The backslashed assertions are
| \b | word boundary |
| \B | not a word boundary |
| \A | start of subject (independent of multiline mode) |
| \Z | end of subject or newline at end (independent of multiline mode) |
| \z | end of subject (independent of multiline mode) |
A word boundary is a position in the subject string where the current character and the previous character do not both match \w or \W (i.e. one matches \w and the other matches \W), or the start or end of the string if the first or last character matches \w, respectively.
The \A, \Z, and \z assertions differ from the traditional circumflex and dollar (described below) in that they only ever match at the very start and end of the subject string, whatever options are set. They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options. The difference between \Z and \z is that \Z matches before a newline that is the last character of the string as well as at the end of the string, whereas \z matches only at the end.
Outside a character class, in the default matching mode, the circumflex character is an assertion which is true only if the current matching point is at the start of the subject string. Inside a character class, circumflex has an entirely different meaning (see below).
Circumflex need not be the first character of the pattern if a number of alternatives are involved, but it should be the first thing in each alternative in which it appears if the pattern is ever to match that branch. If all possible alternatives start with a circumflex, that is, if the pattern is constrained to match only at the start of the subject, it is said to be an "anchored" pattern. (There are also other constructs that can cause a pattern to be anchored.)
A dollar character is an assertion which is true only if the current matching point is at the end of the subject string, or immediately before a newline character that is the last character in the string (by default). Dollar need not be the last character of the pattern if a number of alternatives are involved, but it should be the last item in any branch in which it appears. Dollar has no special meaning in a character class.
The meaning of dollar can be changed so that it matches only at the very end of the string, by setting the PCRE_DOLLAR_ENDONLY option at compile or matching time. This does not affect the \Z assertion.
The meanings of the circumflex and dollar characters are changed if the PCRE_MULTILINE option is set. When this is the case, they match immediately after and immediately before an internal "\n" character, respectively, in addition to matching at the start and end of the subject string. For example, the pattern /^abc$/ matches the subject string "def
abc" in multiline mode, but not otherwise. Consequently, patterns that are anchored in single line mode because all branches start with "^" are not anchored in multiline mode. The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set.
Note that the sequences \A, \Z, and \z can be used to match the start and end of the subject in both modes, and if all branches of a pattern start with \A is it always anchored, whether PCRE_MULTILINE is set or not.
Outside a character class, a dot in the pattern matches any one character in the subject, including a non-printing character, but not (by default) newline. If the PCRE_DOTALL option is set, then dots match newlines as well. The handling of dot is entirely independent of the handling of circumflex and dollar, the only relationship being that they both involve newline characters. Dot has no special meaning in a character class.
An opening square bracket introduces a character class, terminated by a closing square bracket. A closing square bracket on its own is not special. If a closing square bracket is required as a member of the class, it should be the first data character in the class (after an initial circumflex, if present) or escaped with a backslash.
A character class matches a single character in the subject; the character must be in the set of characters defined by the class, unless the first character in the class is a circumflex, in which case the subject character must not be in the set defined by the class. If a circumflex is actually required as a member of the class, ensure it is not the first character, or escape it with a backslash.
For example, the character class [aeiou] matches any lower case vowel, while [^aeiou] matches any character that is not a lower case vowel. Note that a circumflex is just a convenient notation for specifying the characters which are in the class by enumerating those that are not. It is not an assertion: it still consumes a character from the subject string, and fails if the current pointer is at the end of the string.
When caseless matching is set, any letters in a class represent both their upper case and lower case versions, so for example, a caseless [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not match "A", whereas a caseful version would.
The newline character is never treated in any special way in character classes, whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE options is. A class such as [^a] will always match a newline.
The minus (hyphen) character can be used to specify a range of characters in a character class. For example, [d-m] matches any letter between d and m, inclusive. If a minus character is required in a class, it must be escaped with a backslash or appear in a position where it cannot be interpreted as indicating a range, typically as the first or last character in the class.
It is not possible to have the literal character "]" as the end character of a range. A pattern such as [W-]46] is interpreted as a class of two characters ("W" and "-") followed by a literal string "46]", so it would match "W46]" or "-46]". However, if the "]" is escaped with a backslash it is interpreted as the end of range, so [W-\]46] is interpreted as a single class containing a range followed by two separate characters. The octal or hexadecimal representation of "]" can also be used to end a range.
Ranges operate in ASCII collating sequence. They can also be used for characters specified numerically, for example [\000-\037]. If a range that includes letters is used when caseless matching is set, it matches the letters in either case. For example, [W-c] is equivalent to [][\^_`wxyzabc], matched caselessly, and if character tables for the "fr" locale are in use, [\xc8-\xcb] matches accented E characters in both cases.
The character types \d, \D, \s, \S, \w, and \W may also appear in a character class, and add the characters that they match to the class. For example, [\dABCDEF] matches any hexadecimal digit. A circumflex can conveniently be used with the upper case character types to specify a more restricted set of characters than the matching lower case type. For example, the class [^\W_] matches any letter or digit, but not underscore.
All non-alphameric characters other than \, -, ^ (at the start) and the terminating ] are non-special in character classes, but it does no harm if they are escaped.
Vertical bar characters are used to separate alternative patterns. For example, the pattern
gilbert|sullivan
matches either "gilbert" or "sullivan". Any number of alternatives may appear, and an empty alternative is permitted (matching the empty string). The matching process tries each alternative in turn, from left to right, and the first one that succeeds is used. If the alternatives are within a subpattern (defined below), "succeeds" means matching the rest of the main pattern as well as the alternative in the subpattern.
The settings of PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and PCRE_EXTENDED can be changed from within the pattern by a sequence of Perl option letters enclosed between "(?" and ")". The option letters are
| i | PCRE_CASELESS | Letters in the pattern match both upper and lower case letters. It is equivalent to Perl's /i option. |
| m | PCRE_MULTILINE | By default, PCRE treats the subject string as consisting of a single "line" of characters (even if it actually contains several newlines). The "start of line" metacharacter (^) matches only at the start of the string, while the "end of line" metacharacter ($) matches only at the end of the string, or before a terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as Perl.
When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the subject string, respectively, as well as at the very start and end. This is equivalent to Perl's /m option. If there are no "\n" characters in a subject string, or no occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect. |
| s | PCRE_DOTALL | If this bit is set, a dot metacharater in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option is equivalent to Perl's /s option. A negative class such as [^a] always matches a newline character, independent of the setting of this option. |
| x | PCRE_EXTENDED | If this bit is set, whitespace data characters in the pattern are totally ignored except when escaped or inside a character class, and characters between an unescaped # outside a character class and the next newline character, inclusive, are also ignored. This is equivalent to Perl's /x option, and makes it possible to include comments inside complicated patterns. Note, however, that this applies only to data characters. Whitespace characters may never appear within special character sequences in a pattern, for example within the sequence (?( which introduces a conditional subpattern. |
The scope of these option changes depends on where in the pattern the setting occurs. For settings that are outside any subpattern (defined below), the effect is the same as if the options were set or unset at the start of matching. The following patterns all behave in exactly the same way:
(?i)abc
a(?i)bc
ab(?i)c
abc(?i)
which in turn is the same as compiling the pattern abc with PCRE_CASELESS set. In other words, such "top level" settings apply to the whole pattern (unless there are other changes inside subpatterns). If there is more than one setting of the same option at top level, the rightmost setting is used.
If an option change occurs inside a subpattern, the effect is different. This is a change of behaviour in Perl 5.005. An option change inside a subpattern affects only that part of the subpattern that follows it, so
(a(?i)b)c
matches abc and aBc and no other strings (assuming PCRE_CASELESS is not used). By this means, options can be made to have different settings in different parts of the pattern. Any changes made in one alternative do carry on into subsequent branches within the same subpattern. For example,
(a(?i)b|c)
matches "ab", "aB", "c", and "C", even though when matching "C" the first branch is abandoned before the option setting. This is because the effects of option settings happen at compile time. There would be some very weird behaviour otherwise.
The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can be changed in the same way as the Perl-compatible options by using the characters U and X respectively. The (?X) flag setting is special in that it must always occur earlier in the pattern than any of the additional features it turns on, even when it is at top level. It is best put at the start.
Subpatterns are delimited by parentheses (round brackets), which can be nested.
Marking part of a pattern as a subpattern does two things:
1. It localizes a set of alternatives. For example, the pattern
cat(aract|erpillar|)
matches one of the words "cat", "cataract", or "caterpillar". Without the parentheses, it would match "cataract", "erpillar" or the empty string.
2. It sets up the subpattern as a capturing subpattern (as defined above). Opening parentheses are counted from left to right (starting from 1) to obtain the numbers of the capturing subpatterns.
For example, if the string "the red king" is matched against the pattern
the ((red|white) (king|queen))
the captured substrings are "red king", "red", and "king", and are numbered 1, 2, and 3.
The fact that plain parentheses fulfil two functions is not always helpful. There are often times when a grouping subpattern is required without a capturing requirement. If an opening parenthesis is followed by "?:", the subpattern does not do any capturing, and is not counted when computing the number of any subsequent capturing subpatterns. For example, if the string "the white queen" is matched against the pattern
the ((?:red|white) (king|queen))
the captured substrings are "white queen" and "queen", and are numbered 1 and 2. The maximum number of captured substrings is 99, and the maximum number of all subpatterns, both capturing and non-capturing, is 200.
As a convenient shorthand, if any option settings are required at the start of a non-capturing subpattern, the option letters may appear between the "?" and the ":". Thus the two patterns
(?i:saturday|sunday)
(?:(?i)saturday|sunday)
match exactly the same set of strings. Because alternative branches are tried from left to right, and options are not reset until the end of the subpattern is reached, an option setting in one branch does affect subsequent branches, so the above patterns match "SUNDAY" as well as "Saturday".
Repetition is specified by quantifiers, which can follow any of the following items:
a single character, possibly escaped
the . metacharacter
a character class
a back reference (see next section)
a parenthesized subpattern (unless it is an assertion - see below)
The general repetition quantifier specifies a minimum and maximum number of permitted matches, by giving the two numbers in curly brackets (braces), separated by a comma. The numbers must be less than 65536, and the first must be less than or equal to the second. For example:
z{2,4}
matches "zz", "zzz", or "zzzz". A closing brace on its own is not a special character. If the second number is omitted, but the comma is present, there is no upper limit; if the second number and the comma are both omitted, the quantifier specifies an exact number of required matches. Thus
[aeiou]{3,}
matches at least 3 successive vowels, but may match many more, while
\d{8}
matches exactly 8 digits. An opening curly bracket that appears in a position where a quantifier is not allowed, or one that does not match the syntax of a quantifier, is taken as a literal character. For example, {,6} is not a quantifier, but a literal string of four characters.
The quantifier {0} is permitted, causing the expression to behave as if the previous item and the quantifier were not present.
For convenience (and historical compatibility) the three most common quantifiers have single-character abbreviations:
| * | is equivalent to {0,} |
| + | is equivalent to {1,} |
| ? | is equivalent to {0,1} |
(a?)*
Earlier versions of Perl and PCRE used to give an error at compile time for such patterns. However, because there are cases where this can be useful, such patterns are now accepted, but if any repetition of the subpattern does in fact match no characters, the loop is forcibly broken.
By default, the quantifiers are "greedy", that is, they match as much as possible (up to the maximum number of permitted times), without causing the rest of the pattern to fail. The classic example of where this gives problems is in trying to match comments in C programs. These appear between the sequences /* and */ and within the sequence, individual * and / characters may appear. An attempt to match C comments by applying the pattern
/\*.*\*/
to the string
/* first command */ not comment /* second comment */
fails, because it matches the entire string due to the greediness of the .* item.
However, if a quantifier is followed by a question mark, then it ceases to be greedy, and instead matches the minimum number of times possible, so the pattern
/\*.*?\*/
does the right thing with the C comments. The meaning of the various quantifiers is not otherwise changed, just the preferred number of matches. Do not confuse this use of question mark with its use as a quantifier in its own right. Because it has two uses, it can sometimes appear doubled, as in
\d??\d
which matches one digit by preference, but can match two if that is the only way the rest of the pattern matches.
If the PCRE_UNGREEDY option is set (an option which is not available in Perl) then the quantifiers are not greedy by default, but individual ones can be made greedy by following them with a question mark. In other words, it inverts the default behaviour.
When a parenthesized subpattern is quantified with a minimum repeat count that is greater than 1 or with a limited maximum, more store is required for the compiled pattern, in proportion to the size of the minimum or maximum.
If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equivalent to Perl's /s) is set, thus allowing the . to match newlines, then the pattern is implicitly anchored, because whatever follows will be tried against every character position in the subject string, so there is no point in retrying the overall match at any position after the first. PCRE treats such a pattern as though it were preceded by \\A. In cases where it is known that the subject string contains no newlines, it is worth setting PCRE_DOTALL when the pattern begins with .* in order to obtain this optimization, or alternatively using ^ to indicate anchoring explicitly.
When a capturing subpattern is repeated, the value captured is the substring that matched the final iteration. For example, after
(tweedle[dume]{3}\\s*)+
has matched "tweedledum tweedledee" the value of the captured substring is "tweedledee". However, if there are nested capturing subpatterns, the corresponding captured values may have been set in previous iterations. For example, after
/(a|(b))+/
matches "aba" the value of the second captured substring is "b".
Outside a character class, a backslash followed by a digit greater than 0 (and possibly further digits) is a back reference to a capturing subpattern earlier (i.e. to its left) in the pattern, provided there have been that many previous capturing left parentheses.
However, if the decimal number following the backslash is less than 10, it is always taken as a back reference, and causes an error only if there are not that many capturing left parentheses in the entire pattern. In other words, the parentheses that are referenced need not be to the left of the reference for numbers less than 10. See the section entitled "Backslash" above for further details of the handling of digits following a backslash.
A back reference matches whatever actually matched the capturing subpattern in the current subject string, rather than anything matching the subpattern itself. So the pattern
(sens|respons)e and \1ibility
matches "sense and sensibility" and "response and responsibility", but not "sense and responsibility". If caseful matching is in force at the time of the back reference, then the case of letters is relevant. For example,
((?i)rah)\s+\1
matches "rah rah" and "RAH RAH", but not "RAH rah", even though the original capturing subpattern is matched caselessly.
There may be more than one back reference to the same subpattern. If a subpattern has not actually been used in a particular match, then any back references to it always fail. For example, the pattern
(a|(bc))\\2
always fails if it starts to match "a" rather than "bc". Because there may be up to 99 back references, all digits following the backslash are taken as part of a potential back reference number. If the pattern continues with a digit character, then some delimiter must be used to terminate the back reference. If the PCRE_EXTENDED option is set, this can be whitespace. Otherwise an empty comment can be used.
A back reference that occurs inside the parentheses to which it refers fails when the subpattern is first used, so, for example, (a\\1) never matches. However, such references can be useful inside repeated subpatterns. For example, the pattern
(a|b\\1)+
matches any number of "a"s and also "aba", "ababaa" etc. At each iteration of the subpattern, the back reference matches the character string corresponding to the previous iteration. In order for this to work, the pattern must be such that the first iteration does not need to match the back reference. This can be done using alternation, as in the example above, or by a quantifier with a minimum of zero.
An assertion is a test on the characters following or preceding the current matching point that does not actually consume any characters. The simple assertions coded as \b, \B, \A, \Z, \z, ^ and $ are described above. More complicated assertions are coded as subpatterns. There are two kinds: those that look ahead of the current position in the subject string, and those that look behind it.
An assertion subpattern is matched in the normal way, except that it does not cause the current matching position to be changed. Lookahead assertions start with (?= for positive assertions and (?! for negative assertions. For example,
\w+(?=;)
matches a word followed by a semicolon, but does not include the semicolon in the match, and
foo(?!bar)
matches any occurrence of "foo" that is not followed by "bar". Note that the apparently similar pattern
(?!foo)bar
does not find an occurrence of "bar" that is preceded by something other than "foo"; it finds any occurrence of "bar" whatsoever, because the assertion (?!foo) is always true when the next three characters are "bar". A lookbehind assertion is needed to achieve this effect.
Lookbehind assertions start with (?<= for positive assertions and (?<! for negative assertions. For example,
(?<!foo)bar
does find an occurrence of "bar" that is not preceded by "foo". The contents of a lookbehind assertion are restricted such that all the strings it matches must have a fixed length. However, if there are several alternatives, they do not all have to have the same fixed length. Thus
(?<=bullock|donkey)
is permitted, but
(?<!dogs?|cats?)
causes an error at compile time. Branches that match different length strings are permitted only at the top level of a lookbehind assertion. This is an extension compared with Perl 5.005, which requires all branches to match the same length of string. An assertion such as
(?<=ab(c|de))
is not permitted, because its single top-level branch can match two different lengths, but it is acceptable if rewritten to use two top-level branches:
(?<=abc|abde)
The implementation of lookbehind assertions is, for each alternative, to temporarily move the current position back by the fixed width and then try to match. If there are insufficient characters before the current position, the match is deemed to fail. Lookbehinds in conjunction with once-only subpatterns can be particularly useful for matching at the ends of strings; an example is given at the end of the section on once-only subpatterns.
Several assertions (of any sort) may occur in succession. For example,
(?<=\\d{3})(?<!999)foo
matches "foo" preceded by three digits that are not "999". Furthermore, assertions can be nested in any combination. For example,
(?<=(?<!foo)bar)baz
matches an occurrence of "baz" that is preceded by "bar" which in turn is not preceded by "foo".
Assertion subpatterns are not capturing subpatterns, and may not be repeated, because it makes no sense to assert the same thing several times. If an assertion contains capturing subpatterns within it, these are always counted for the purposes of numbering the capturing subpatterns in the whole pattern. Substring capturing is carried out for positive assertions, but it does not make sense for negative assertions.
Assertions count towards the maximum of 200 parenthesized subpatterns.
With both maximizing and minimizing repetition, failure of what follows normally causes the repeated item to be re-evaluated to see if a different number of repeats allows the rest of the pattern to match. Sometimes it is useful to prevent this, either to change the nature of the match, or to cause it fail earlier than it otherwise might, when the author of the pattern knows there is no point in carrying on.
Consider, for example, the pattern \\d+foo when applied to the subject line
123456bar
After matching all 6 digits and then failing to match "foo", the normal action of the matcher is to try again with only 5 digits matching the \d+ item, and then with 4, and so on, before ultimately failing. Once-only subpatterns provide the means for specifying that once a portion of the pattern has matched, it is not to be re-evaluated in this way, so the matcher would give up immediately on failing to match "foo" the first time. The notation is another kind of special parenthesis, starting with (?> as in this example:
(?>\\d+)bar
This kind of parenthesis "locks up" the part of the pattern it contains once it has matched, and a failure further into the pattern is prevented from backtracking into it. Backtracking past it to previous items, however, works as normal.
An alternative description is that a subpattern of this type matches the string of characters that an identical standalone pattern would match, if anchored at the current point in the subject string.
Once-only subpatterns are not capturing subpatterns. Simple cases such as the above example can be thought of as a maximizing repeat that must swallow everything it can. So, while both \\d+ and \\d+? are prepared to adjust the number of digits they match in order to make the rest of the pattern match, (?>\\d+) can only match an entire sequence of digits.
This construction can of course contain arbitrarily complicated subpatterns, and it can be nested.
Once-only subpatterns can be used in conjunction with lookbehind assertions to specify efficient matching at the end of the subject string. Consider a simple pattern such as
abcd$
when applied to a long string which does not match it. Because matching proceeds from left to right, PCRE will look for each "a" in the subject and then see if what follows matches the rest of the pattern. If the pattern is specified as
^.*abcd$
then the initial .* matches the entire string at first, but when this fails, it backtracks to match all but the last character, then all but the last two characters, and so on. Once again the search for "a" covers the entire string, from right to left, so we are no better off. However, if the pattern is written as
^(?>.*)(?<=abcd)
then there can be no backtracking for the .* item; it can match only the entire string. The subsequent lookbehind assertion does a single test on the last four characters. If it fails, the match fails immediately. For long strings, this approach makes a significant difference to the processing time.
It is possible to cause the matching process to obey a subpattern conditionally or to choose between two alternative subpatterns, depending on the result of an assertion, or whether a previous capturing subpattern matched or not. The two possible forms of conditional subpattern are
(?(condition)yes-pattern)
(?(condition)yes-pattern|no-pattern)
If the condition is satisfied, the yes-pattern is used; otherwise the no-pattern (if present) is used. If there are more than two alternatives in the subpattern, a compile-time error occurs.
There are two kinds of condition. If the text between the parentheses consists of a sequence of digits, then the condition is satisfied if the capturing subpattern of that number has previously matched. Consider the following pattern, which contains non-significant white space to make it more readable (assume the PCRE_EXTENDED option) and to divide it into three parts for ease of discussion:
( \( )? [^()]+ (?(1) \) )
The first part matches an optional opening parenthesis, and if that character is present, sets it as the first captured substring. The second part matches one or more characters that are not parentheses. The third part is a conditional subpattern that tests whether the first set of parentheses matched or not. If they did, that is, if subject started with an opening parenthesis, the condition is true, and so the yes-pattern is executed and a closing parenthesis is required. Otherwise, since no-pattern is not present, the subpattern matches nothing. In other words, this pattern matches a sequence of non-parentheses, optionally enclosed in parentheses.
If the condition is not a sequence of digits, it must be an assertion. This may be a positive or negative lookahead or lookbehind assertion. Consider this pattern, again containing non-significant white space, and with the two alternatives on the second line:
(?(?=[^a-z]*[a-z])
\d{2}[a-z]{3}-\d{2} | \d{2}-\d{2}-\d{2} )
The condition is a positive lookahead assertion that matches an optional sequence of non-letters followed by a letter. In other words, it tests for the presence of at least one letter in the subject. If a letter is found, the subject is matched against the first alternative; otherwise it is matched against the second. This pattern matches strings in one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are letters and dd are digits.
The sequence (?# marks the start of a comment which continues up to the next closing parenthesis. Nested parentheses are not permitted. The characters that make up a comment play no part in the pattern matching at all.
If the PCRE_EXTENDED option is set, an unescaped # character outside a character class introduces a comment that continues up to the next newline character in the pattern.
Certain items that may appear in patterns are more efficient than others. It is more efficient to use a character class like [aeiou] than a set of alternatives such as (a|e|i|o|u). In general, the simplest construction that provides the required behaviour is usually the most efficient. Jeffrey Friedl's book contains a lot of discussion about optimizing regular expressions for efficient performance.
When a pattern begins with .* and the PCRE_DOTALL option is set, the pattern is implicitly anchored by PCRE, since it can match only at the start of a subject string. However, if PCRE_DOTALL is not set, PCRE cannot make this optimization, because the . metacharacter does not then match a newline, and if the subject string contains newlines, the pattern may match from the character immediately following one of them instead of from the very start. For example, the pattern
(.*) second
matches the subject "first\nand second" (where \n stands for a newline character) with the first captured substring being "and". In order to do this, PCRE has to retry the match starting after every newline in the subject.
If you are using such a pattern with subject strings that do not contain newlines, the best performance is obtained by setting PCRE_DOTALL, or starting the pattern with ^.* to indicate explicit anchoring. That saves PCRE from having to scan along the subject looking for a newline to restart at.
There are some size limitations in PCRE but it is hoped that they will never in practice be relevant. The maximum length of a compiled pattern is 65539 (sic) bytes. All values in repeating quantifiers must be less than 65536. The maximum number of capturing subpatterns is 99. The maximum number of all parenthesized subpatterns, including capturing subpatterns, assertions, and other types of subpattern, is 200.
The maximum length of a subject string is the largest positive number that an integer variable can hold. However, PCRE uses recursion to handle subpatterns and indefinite repetition. This means that the available stack space may limit the size of a subject string that can be processed by certain patterns.
Validated as a Pure HTML 3.2