PocoScript Help

General

Scripting in Poco is implemented through PocoScript, an interpreted language created for Poco that focuses on mail processing and handling. Even though it has a narrow focus, PocoScript can act as a conduit between Poco and other applications to implement more sophisticated mail processing, such as mail encryption. This document outlines the commands available with PocoScript, the language syntax and other information useful in creating scripts. A tutorial is also available, it walks you through the creation of a couple of the scripts provided with Poco.

PocoScript is interpreted, high-level language, run directly by Poco itself. Language syntax is simple, specifically focused at handling e-mail messages. Since the interpreter is part of the main application, to run any scripts you need to have Poco running.

Scripts can be run:

• Against messages after they have been sent.
• Against messages before they are downloaded from the server. Scripts in this category do not have access to the message body, they can only act on the message headers. Such scripts are useful for deciding which messages should be downloaded, left on the server or deleted from the server.
• Against selected messages
• On Incoming messages (after the message has been read but before it is placed into the "In" box).
• On Outgoing messages (before the message has actually been sent).
• Stand alone
• When starting Poco (see command line parameters).

For more help with scripting check out the PocoScript Tutorial, the PocoScript Primer, the PocoScript EZBoard forum, or the PocoScript Command Search Utility (http://www.pocomail.com/help/pocoscriptcommandsearch.html). Another great way to learn scripting is to download and examine the scripts from the registered users area on the Poco website.

Examples

Many of the commands listed below are illustrated using examples from the scripts supplied with Poco. To view these scripts follow the instructions for editing a script. In other cases a typical use of the command is demonstrated within this document. When this is done the script lines will be in italics with each command on a separate line and indented from the left margin.

Back to Poco Help : PocoScript Index : Top

Variables

PocoScript is not a strongly typed language, but it offers four basic variable types. Variables can have any alphanumeric name, prefixed with the type identifier, listed below:

$ - String variable

# - Numeric variable

% - Mail message variable

& - Boolean variable

String types can be assigned out of their type, but the assignment will be successful only if the values are interchangeable. This means that you can assign an integer variable to a string variable at any time, but the reverse will work only when the string contains a true integer. In the absence of error checking a badly typed assignment will result in an error message being issued and the script halting. This avoids the unlikely but possible situation where a message might be lost when an assignment fails.

When assigning values to string variables, place them in double-quotes to ensure they are fully assigned. If you are assigning a single word, without spaces or separators, you don't need to use quotes.

Boolean variables (&var) can be used in several forms, all of which resolve to logical true or false. Value "True", "Yes", "On" or digit "1" all resolve to true, while "False", "No", "Off" or digit "0" resolve to false. Any other assignments to a boolean variable will resolve to true, such as number "42" or string "Friday". Boolean variables are not strongly typed, so you can assign an integer or a string to them. You can apply boolean operators to boolean variables, see Operators section. PocoScript also has several boolean commands. Boolean variables resolved by the interpreter will always resolve as "1" for true and "0" for false, and as such can be assigned to integer or string variables.

Message variables (%var) consist of message header fields and message body. You can use a set of message commands to operate on message variables. They will allow you to operate on messages as a whole, as well as access individual headers, or save them to a file / mailbox.

PocoScript provides several system variables at run time with already assigned values, you can use in your programs:

$mailpath = Full path to mailboxes root folder

$scriptpath = Full path to scripts folder

$apppath = Full path to application root folder

$attachpath = Full path to attachments folder

$addresspath = Full path to address books folder

$sigpath = Full path to signatures folder

$temppath = Full path to Windows temporary folder

%message = Contains the message passed to the script to be processed. It is either a selected message that script is run on, or a currently incoming or outgoing message. The %message variable can be modified at run-time, but changes are only passed back to Poco when run on incoming or outgoing mail. When %message is modified while script is running on selected messages, the changes will not affect the original message in the mailbox.

#PocoVersion = Contains the Poco build number. This variable would be used by script developers who use new PocoScript commands. The script would check for a minimum Poco version and issue a message if the user was using a prior version.

$PocoVersion = Contains the version info for Poco (the same as is displayed in the X-Mailer header).

#PocoScriptMode = Mode script is running in: 0 (unknown), 1 (incoming), 2(outgoing), 3 (pre-download), 4 (post-send), 5 (manually on selected), 6 (startup via command line parameter), 7 (dry run).

$CurrentMailbox = Contains the currently opened mailbox.

Back to Poco Help : PocoScript Index : Top

Operators

Most of the operations on the variables are done through built-in commands, including basic addition and subtraction. Exception is the boolean operators. They take form of

value/variable OPERATOR value/variable

These expressions are used mainly in assignment commands, like SET, and in boolean commands, like IF. Following operators can be used:

> Greater than, works for integers and strings. String are compared alphabetically; (thus "b" > "a" is true).

< Less than, usage same as >;

= Equals, evaluates true only for equal integers and EXACTLY identical strings; thus "A" = "a" is false, as is "A " = "A" (the first "A " has a trailing space).

! Does not equal, usage same as =;

^ Contained within, works practically only on strings. Evaluates true if the first string is contained within the second string. For example "ven" ^ "Slaven" is true. This operator can be used to determine if a variable consists solely of alphabetic characters:

     Set &isalpha $test ^ "abcdefghijklmnopqrstuvwxyz"

When applied to strings, all boolean operators are case sensitive. To ignore the case of the compared strings, apply Lowercase or Uppercase commands to the values before the comparison.

Files

PocoScript is fairly adept at handling text files. PocoScript does not support binary files. When opening and saving files, the default directory used is the root directory of your mail folder, or as described above $mailpath. To save outside the default directory, simply use fully qualified file names.

When saving files, the default settings will overwrite any existing files. To change this behaviour set AppendToFile to true at the beginning of the script or prior to saving the file. For instance, if you want to save three messages to a new mailbox call "Stuff", simply run:

     AppendToFile true
     SaveMessage %m1 Stuff.mbx
     SaveMessage %m2 Stuff.mbx
     SaveMessage %m3 Stuff.mbx

And that is it. This will create a valid mailbox that you can later open with Poco.

Error Handling

If PocoScript encounters a runtime error while parsing the script, it will do its best to continue running the script without halting. If you want to control what happens when an error is encountered, you can use the following variables:

$OnErrorMessage: if you define this variable with a non-empty value, Poco will present that message whenever error occurs, with the correct error description below and the line that caused the error. In the absence of an $OnErrorGoTo statement execution will continue with the next line in the script.

$OnErrorGoTo: if this variable is defined, when Poco encounters an error the script execution will continue on the label defined by this variable.

For example, to display a message "Sorry, error occurred", and continue script execution on script section with label ":ErrorHandler", define the following at the point in the script you wish to activate error handling (usually the beginning of the script):

     Set $OnErrorMessage "Sorry, error occurred"
     Set $OnErrorGoTo "ErrorHandler"

In addition to these variables, Poco will set the following variables to the corresponding values AFTER the error occurs:

#ErrorResult: Numerical value of the error (see below)
$ErrorResult: Text description of the error message
#ErrorLine: Line number where the error occurred
$ErrorLine: Line itself that the error occurred on

Following are currently recognized and handled runtime errors and the corresponding codes used for #ErrorResult:

FILE I/O ERRORS
1010 Error saving message to file
1012 Error saving text
1014 Error saving text to new file
1020 Error reading file
1025 Error reading file - file not found

MATH OPS ERRORS
1110 Integer operation on string
1112 Float operation on string
1120 Divide by zero

RUNTIME ERRORS
1210 Non-integer parameter in integer variable
1220 Invalid date parameter
1230 Invalid time parameter

ONLINE ERRORS
1310 Sending message failed

Back to Poco Help : PocoScript Index : Top

Commands

Creates a blank message. This command is used in situations where you want to generate a message from the script, for example to send a confirmation to a customer when an order is received from your website. The "Vacation Message" script provides a good example of this command.

Loads a message saved to a file in RFC822 (Poco mailbox) format.

Saves message to a Poco mailbox (RFC822 format). This command would be used when you want to save the message being processed by the script or one that was instanced by the script to one of your mailboxes. If you are saving the message to an existing mailbox remember to issue the "AppendToFile" command prior to using this command. For examples of this command refer to the "DeleteHeader" or "FileExists" commands or see either the "Archive Old Mail" or "Display Raw Message" scripts supplied with Poco.

Deletes the message passed to the script. Practically used only on the %message variable; when used on messages instanced by the script, it will only add "D" to the Status header. This command will be used whenever you need to delete a message. An example would be if a script is designed to run against selected messages and format a reply to the message(s) marking the messages as replied. In order to accomplish this the script has to save a copy of the message and, to avoid confusion, delete the original message. This technique is demonstrated in the example under the "DeleteHeader" command. An additional example of this command can be found in the "Archive Old Mail" script supplied with Poco.

Checks for new mail for a specific account

SendMessage %m

Sends the prepared message %m via SMTP server setup in the accounts or settings. This command sends immediately, if you want to queue message to be sent later, simply use:

     AppendToFile True
     SaveMessage %m Out.mbx

Alternatively you may want to display the message in the compose window for editing, this would be done using the EditMessage command as described below.

Message %m is opened in Poco to be edited in the Poco compose window. The message can be sent or queued using the "Send" or "Queue" options in the compose window. EditMessage will not interpret styled text if itÆs in the message, and will extract plain text without formatting tags (styling will be lost if the message is sent or queued from the compose window). The script will continue to run while the compose window is displayed (execution will not be suspended). For an example of this command see the "Reply with Template" script supplied with Poco.

Prints the message %m to the current printer. Message is formatted for printing with the current printing template. For example, the following command will print the current message:

     PrintMessage %message

Marks the message %m to be encrypted, which happens whenever the message is saved to disk. You would use this command when you need to save messages in a secure form safe from prying eyes. When run on Incoming or Outgoing messages the command will read the encryption password from the Accounts Setup for that particular account. When the filter is run on Selected Messages it will use the currently set encryption password (see SetEncryptionPassword command).

Sets the current encryption password to the passed value. This command would be used in conjunction with the "EncryptMessage" command when the a script that is running against selected messages needs to save those messages in a secure form. For security reasons it is best to ask the user for the password with an InputBox command, rather than saving it in the script, scripts exist as plain text files and the password could be read by anyone with access to your computer. There is no ReadEncryptionPassword command to return the current password, also for security reasons!

Adds a "header" to message %m with value of $a. Works only on single-line headers. DonÆt use these commands to add message recipients û better support for that is provided by commands AddTo, AddCC and AddBCC. SetHeader and AddHeader behave the same way, SetHeader is still supported for backward compatibility while AddHeader is semantically correct. For a sample refer to the example under the "DeleteHeader" command or see the "Vacation Message" script supplied with Poco.

Deletes the passed header from the message %m. This command is also used prior to the "AddHeader" command when you want to replace an existing header. For example, to mark a message as "Replied" you must set the "Status" header to "W". The following commands would accomplish this:

     DeleteHeader "Status:" %message
     AddHeader %message "Status:" "W"

If the script is running against selected messages then you will also have to delete the original message and save the message with the modified header:

     AppendToFile True
     SaveMessage %message $mailbox
     DeleteMessage %message

Reads "header" value of message %m into variable $a. Works only on single-line headers. For example, to read the "Subject" header of the current message you would use:

     ReadHeader $subject "Subject:" %message

Additional examples of this command can be found in the "Vacation Message" script supplied with Poco.

Places all of the message %m headers into a multiline variable $a, just as they would appear in an RFC 822 message, complete with header names. The obsolescent "AnnotateMessage" script available from the registered users area of the Poco website provides an example of this command.

Adds one or more primary recipients to message %m. It is typically used to indicate the primary recipients of messages instanced by a script via the CreateMessage command. The address can be a constant string, a simple variable or a multi-line variable. When adding multiple addresses they can be passed either one per line in a multi-line variable or separated by commas in a simple variable. See the "Reply with Template" script for an example of this command.

Adds carbon copy recipient(s) to message %m. See the AddTo command above for information on passing address(es) to this command.

Adds anonymous recipient(s) to message %m. See the AddTo command above for information on passing address(es) to this command.

Clears all primary recipients from message %m. This command is typically used to clear the "To" field in a message instanced by the script that is being sent to a number of different primary recipients when you do not want to reveal the names of the recipients to each other or where you need to send the messages in batches due to restrictions imposed by your service provider.

Clears all carbon copy recipients from message %m. See the ClearTo command for more information.

Clears all anonymous recipients from message %m. See the ClearTo command for more information.

Places all the primary recipients into multi-line variable $a. Each recipient is placed on a separate line. This command might be used to send a reply to all recipients of a message you received. The following commands will display the number of primary recipients of a message:

ReadCC $a %m

Similar to the ReadTo command, this command places all the carbon copy recipients into multi-line variable $a.

ReadBCC $a %m

Places all the anonymous recipients into multi-line variable $a. Since BCC headers are not sent with messages this command will have no effect on Incoming mail. The following commands will display the anonymous recipients of a message:

     ReadBCC $bcc %message
     InsertLine $bcc 0 "You sent this message anonymously to the following recipients:"
     MessageBox $bcc

Opens text file and places it in variable $a. The file may contain line breaks. This command would be used whenever you need to read plain text files from a script. The "Vacation Message" script provides an example of how this command is used.

Saves variable $a to a text file. This command would be used whenever you need to write a plain text file from a script. One example might be saving a count of the number of messages sent from a mass mailing script. The "Display Raw Message" script, provided with Poco, provides an example of this command.

Deletes the message body for message %m.

Appends two strings with a line separator. Primary used on multiline string variables, like the message body or a string that is being constructed to use as a message body. This command is demonstrated in the "About PocoScript" script.

Appends signature of the current account to the message %m. Signature is parsed at this point for any inserted user tags (see Signatures). Use this command to "sign" a message instanced by the script. To change the current account see SetAccount.

Assigns variable $a as a body of message %m. Typically variable $a would be a multi-line variable. Use of this command is illustrated by the "Vacation Message" script supplied with Poco.

Assigns styled multi-line variable $a to message %m. Message styling is achieved via HTML formatting. This command also sets the content-type header to "text/html". ReadBody $a %m

Assigns body of message %m to variable $a. If message %m is of content type text/html, ReadBody will extract the plain text version of the body into $a, to preserve formatting see the "ReadRawBody" command. The actual message %m will not be changed in either case. This command is demonstrated in the "Vacation Message" script.

Assigns body of message %m as raw text to variable $a, regardless of message %m content type. This command will preserve any message styling codes (html formatting) for styled messages (those with a content type of text/html).

It will "quote" or insert quotestring as the beginning of each line of variable $a. The quotestring is optional and if omitted the "greater than" sign (>) is used. This command is typically used to quote an incoming message when the script is creating an automated reply to that message. Use of this command is demonstrated in the "Vacation Message" script.

Removes leading quotestring from each line of $a. Reverses QuoteBody. If quotestring is not specified, "greater than" symbol (>) is assumed. This command would be used when it is necessary to remove the reply message quoting from a message body prior to processing.

Marks the passed message with a message marking code. #a must be between 0 (clear mark) and 8, if it is less than 0 it will be interpreted as 0, if it is greater than 8 it will be interpreted as 8. This command is most useful for processing incoming messages and is be used to set the message marking for the message. For example, the following commands will mark any message containing the string "RSVP" with the standard "Follow up" message mark:

     ReadBody $body %message
     LowerCase $body
     StringPos #ix $body "rsvp"
     If #ix = 0 Then Done
     MarkMessage %message 2
     :Done

Tags the passed message. This command, in conjunction with the "UntagMessage" command allow scripts to manipulate the tagging of messages. Message tagging, used in conjunction with the ShowOnly Bar provide a powerful facility for selecting and sorting messages.

UntagMessage %m

Removes the tag from the passed message. ExtractName $a

Extract person's name from properly formatted e-mail address entry, like "Jane Doe <jdoe@provider.com>". Result overwrites the original value in $a.

Just like the ExtractName, but instead extracts the e-mail address.

Reads CSV formatted data in $b, and parses each record as a separate line in $a.

Reads a multiline variable $b and formats each line as a single record. Places the CSV formatted records as a single line into $a.

Reads the list of attached files in the message %m, and places their filenames with full path into $a. Each file is placed onto a separate line in $a. This command works by scanning the end of the message for string
Attachment Converted: "filename"
which Poco places at the end of the message when an attachment is received with a message. The following commands will examine all incoming messages for "winmail.dat" attachments (from MicroSoft OutLook):

     ReadAttached $AttachedFiles %message
     If "winmail" ^ $AttachedFiles Then WinMailPrefix
     Exit
     :WinMailPrefix
     If ".dat" ^ $AttachedFiles Then WinMail
     Exit
     :WinMail
     MessageBox "This message may contain a WinMail.dat attachment."

Places the name of the current account in $a.

Returns the email address associated with the current account. An example of this command can be found in the "Vacation Message" script.

All of these commands read the respective values for the current account and place them in the variable $a.

Sets which account to use as the current account. This command will affect all of the account reading or setting commands described.

All of these commands will permanently set the respective value for the current account.

Adds the RFC formatted address (form: Name <address>) in $a to the indicated address book, parsing out and adding the name as well.

Adds the pre-formatted address in multi-line variable $a to the indicated address book.

Finds and places the entry for email address $b from address book $bookname into multi-line variable $a. If $bookname is omitted or is "*" then all address books are checked.

Determines if address $a is present in address book $bookname. If $bookname is omitted or is "*" then all address books are checked.

Removes e-mail address $a from address book $bookname (if found). If $bookname is "*" then all address books are checked.

Set &a bool-expression

All variants of the Set command assign either a constant value (eg: "John") or variable (eg: $date) to the variable on the left. When used to set a boolean variable the right hand side can be a boolean expression (eg: i < 5). You can assign out of type, just be careful when you use those values later on.

The Set command is used primarily to establish initial value for a variable or to preserve the contents of a variable prior to performing operations on that variable.

Examples:

Set $name Slaven	Assigns the value "Slaven" to the $name variable
Set $name "Slaven Radic"	Assigns the value "Slaven Radic" to the $name variable. Note the use of quotes.
Set #i 0	Sets the value of the #i variable to zero
Set &switch False	Sets the &switch variable to false.
Set &sw #i > 5	If #i is greater than 5 then the &sw variable is set to true, otherwise it is set to false.
Set $name $someone	Copies the value from the $someone variable to the $name variable

All External commands work similar to Set, they assign value to a variable, except they cannot assign a variable to a variable, and the External declarations will show up on the Setup tab of the Scripts. You can only use $userdata1 through $userdata4 and $userfile1 through $userfile4 for variable names if you want Poco to display them to the user. For each $userdata Poco will display an edit field with the description "desc" in the Setup pane of the Filters and Scripts window. Each $userfile will map a button on the same pane to the filename in "value". When user clicks on that button, Poco will launch Notepad with that file loaded. Please take a look at the sample scripts provided for demonstration, the "Vacation Message" script provides an example of the userfile syntax while the "Archive Old Mail" script provides examples of the userdata syntax.

Use InputBox when you want to prompt the user for a value. A window will pop up with question in "desc", and with a default value filled out as "value". User can edit the value, as well as cancel the script at this point. Do not use InputBox in time sensitive operations, as it stops the script execution until user tells it to proceed. The value will be placed in $a.

InputBox also features a drop-down edit box which you can use to pre-fill selections for the user. You can use standard tags for the setup window in the description to populate the drop-box, for example with the list of headers. These tags are: %mailboxes%, %bool%, %accounts%, %headers% and %addressbooks%. You can also use the %var% user definable tag. These tags have to appear in the description text in order for Poco to use them. The %var% tag works by parsing the default value for pipe or "|" sign. A simple example:

     InputBox $a "Test box...%var%" "First choice|2nd|3rd"

For a more complex example see the sample script provided to demonstrate the "DirList" command.

Embed command allows you to embed multiline values within the script itself. Anything following the Embed command is considered as value to be placed in $a. Use the $b to mark when the input will finish; for instance command:

     Embed $months "@@@"
     January
     February
     March
     April
     May
     June
     July
     August
     September
     October
     November
     December
     @@@

Adds all the strings together and places the result in $a. Integers are added as strings. The following sequence of commands, taken from the "Vacation Message" script, demonstrates how to read the subject from an incoming message and add a "Re:" prefix and assign it as the subject line in a new message that has already been started:

     ReadHeader $Subject "Subject:" %message
     Set $NewSubject "Re: "
     AddStrings $NewSubject $Subject
     SetHeader %Out "Subject:" $NewSubject

Adds integers and places the result in #a. Non-integers are interpreted as zero. For an example of this command see the example under the "DirList" command.

Multiplies the two and places the result in #a. Non-integers are interpreted as one.

Division. Non-integers are interpreted as one. Division by zero returns zero.

Subtraction. Non-integers are interpreted as zero. For example, to subtract 6 from variable #i you would use:

     SubIntegers #i 6

It will delete substring $b from $a. Be careful to include leading or trailing spaces if operand $b if necessary. For example, the following commands:

     Set $a "This is a sentence."
     SubStrings $a "is"
     MessageBox $a

Random #a #n

Places a random number into variable #a, in a range from 0 to #n (0 <= x < #n). For example, to generate a random number between 1 and 10 you would use:

     Random #random 9
     Inc #random

These commands are the standard trigonometry operations sine, cosine and tangent and are performed in radians. Each command takes the argument in $b and returns the value in $a variable. They use string variables, since they operate on floating point values. If the functions fail (for example if an invalid number is passed) they will return an empty string. The result will be accurate to 8 decimal places.

Increase the value of #a by 1. An example of this command is provided at the start of the section on Branching.

Decrease the value of #a by 1. This command is frequently used when coding loops through multi-line variables, for example, to iterate backwards through multi-line variable $x you could use the following commands:

     LineCount #n $x
     {  Line numbers are zero based!
     Dec #n
     :Loop
     GetLine $line #n $x
     {  Commands to process variable $line go here
     Dec #n
     If #n > -1 Then Loop

Converts the supplied string variable to lowercase or uppercase. For an example of this command see the "MarkMessage" command.

Trims all leading left and trailing right spaces from string $a. For example, the following command would remove all spaces from the start and end of variable $name:

     Trim $name

Inserts string $b into variable $a at the position #n in characters. If #n is larger than the size of $a, the string is appended to the back of $a. Character positions are one-based, meaning the first character has a position of 1.

Returns in #n the position in characters of string $b inside string $a. Character numbers are 1-based!

Returns in #n the number of characters in $a. Character numbers are 1-based! An example of this command can be found in the "DirList" command sample.

Deletes a portion of string $a, starting from position #n, and deleting the next #c characters. Character numbers are 1-based! For an example of this command see the sample provided for the "DirList" command.

Returns in $a the single character at the position #n in $b. Character numbers are 1-based! For example, to copy the first character of variable $name into variable $initial use:

     Char $initial 1 $name

Returns true if variable #b/$b/&b contains a number that can be further processed. Otherwise returns false. Due to relaxed variable typing of PocoScript, you can assign a non-integer variable to a number variable like #b. Use this function in those cases.

Similar to IsNumber, but checks for boolean values in the second parameter. Boolean values are 1, 0, true, false, on, off, yes, no. They are not case sensitive. If a value is not boolean, it will still evaluate to true when tested.

Or &a &b
Sets &a to true if either &a or &b are true.

Xor &a &b Sets &a to true if either, but not both, &a or &b are true. Not &a Changes &a to it's opposite value, ie: if &a was true then Not &a will change &a to false.

Multi-Line Variable Operations

Deletes #c lines starting at line #n from multi-line variable $a. #c is optional, if omitted a single line will be deleted. The following command would be used to delete the 3rd and 4th lines of multi-line variable $x:

     DeleteLine $x 3 2

Places line number #n of multiline variable $b into $a. Line numbers are zero-based! See the sample provided for the "DirList" command for an example of this command.

Inserts new line $b at position &n in multi-line variable $a. Line positions are zero-based, meaning the first line has a position of 0. For an example of this command see the sample provided for the "ReadBCC" command.

Returns in #n the number of lines in $a. Line numbers are zero-based! For examples of this command see the "DirList" and "ReadTo" command examples.

Returns in #n the line number of multiline variable $b, where $a appears. Line numbers are zero-based! The line must match exactly, partial matches will not be found, use the "LocateLine" command when partial matching is required.

Finds the first occurrence of string $a within multiline variable $b and returns the line number in variable #n. Line numbers are zero based! The &casesensitive operand is optional and will default to true if omitted.

Trims leading left and trailing right spaces from every line in multiline variable $a. An example of this command can be found in the sample provided for the "DirList" command.

GetTime $a

Places current date or time in $a. The "Archive Old Mail" script provides an example of the GetDate command.

Calculates the difference in days between dates in $b and $c and puts the result in #a. Order of $b and $c is irrelevant - the result is always positive, except when an invalid date is in either $b or $c; the result is then -1. For an example of this command see the "Archive Old Mail" script.

Comments are statements describing the purpose of the script or portions thereof. Comments can greatly assist understanding what the script or a portion of it are doing when you come back to look at it in the future. To insert a comment into the script place a { at the start of the line. Poco will ignore comments when processing the script.

External Commands

Use AppendToFile to modify saving to file. When set to true, if file already exists, saved information is appended to the file. When set to false, if file exists it is overwritten with saved information. This variable defaults to false when the script is started. Illustrations of this command can be found in the "DeleteMessage", "FileExists", "SaveMessage" and "SendMessage" commands.

Starts an external application specified in "file". The application name has to be either fully qualified or in the windows search path. If you want to pass any parameters to the application, use the optional "params" parameter. Executable name and parameters need to be separated for parameters to be passed correctly. You can also pass non-executable filename - as long as it is registered with Windows correctly, Poco will launch the viewer application on that file. Yes, you can also launch fully qualified URLs, such as http or even mailto. Use of this command is demonstrated in the "Calculator" and "Display Raw Message" scripts.

Works identical to Execute, but unlike Execute, ExecuteAndWait will stop PocoÆs operation and script until the external process is finished. Obviously, caution needs to be exercised when using this command, but it is invaluable when running external message processors, such as message encryption.

PlaySound will play a WAV file specified by "file". If you pass the literal "user", PlaySound will instead play the sound defined by the user, in Program Settings. Passing the literal "system" will play the built-in New Mail sound. For example, to play the "MessageForYouSir" wave file from your Poco directory you would use the following commands:

     Set $wav $apppath
     AddStrings $wav "messageforyousir.wav"
     PlaySound $wav

Shows the informational dialog box with an OK button. Text in $a is used for the message. The message box will be displayed with an "Ok" button, to obtain input from the user it is necessary to use the InputBox command. Examples of this command can be found in the samples provided for the "ReadTo", "ReadBCC" and "ReadAttached" commands.

Sounds the Windows system beep, as defined by the user. An alternate means of getting the user's attention is to use the "PlaySound" command to play a sound file.

Pauses execution of the script for #n seconds. An example of this command can be found in the "Display Raw Message" script.

Compresses the indicated mailbox. To compress all mailboxes use the string "*" for the mailbox name. Mailbox compression is required when custom tags are used in the mailbox indexes and to reclaim space in the mailbox.

Affects the main application window, it will refresh the mailboxes currently showing in Mailboxes window. Use it when you have just created or deleted a mailbox, to keep the application in-sync. If not used, Poco will pick up the new mailboxes on restart, when the user right-clicks and chooses Refresh or when they select "Refresh List of Mailboxes" from the "Mailbox" menu.

Deletes a file if it exists. This command is illustrated in the "Display Raw Message" script.

If the file exists, &a is set to true, otherwise it is set to false. This command is useful in conjunction with the "AppendToFile" command when you need to either create or append information to a file. The following commands check to see if a file exists, if it does then the script appends variable $msg to the file, otherwise it writes it to a new file.

     FileExists &sw "C:\Temp\pocotest.txt"
     AppendToFile &sw
     SaveBody $msg "C:\Temp\pocotest.txt"

Places the size of file in bytes into a variable #a. If the file doesn't exist #a will be set to 0. For example, the following commands would be used to determine the size of this help file:

     Set $p $apppath
     AddStrings $p "help\pocoscript.html"
     FileSize #size $p
     MessageBox #size

Attaches the file to the message %m. If the file doesn't exist the message is unchanged. Realistically only used on outgoing messages. The following command would attach this help file to an outgoing message:

     Set $p $apppath
     AddStrings $p "help\pocoscript.html"
     AttachFile %message $p

Lists the contents of the directory dir and places it into multiline variable $a. There are two optional parameters: $pattern is a string that will be used to filter matching files. If omitted "*.*" is assumed. #mode denotes the type of files to list, it defaults to 47 if omitted. Mode can be one of the following values:

1: Read-only files
2: Hidden files
4: System files
8: Volume ID files
16: Directory files
32: Archive files
63: Everything

The following example demonstrates the use of the DirList command. It will display a list of the upper level directories of the "C" drive.

     DirList $l "C:" "*." 16
     TrimLines $l
     Set $list "C:"

     :Loop
        GetLine $line 0 $l
        AddStrings $list "|" $line

        LineCount #l $l
        If #l = 0 Then EndLoop

        CharCount #l $line
        AddIntegers #l 2
        CharCount #size $l
        If #l > #size Then EndLoop

        ChopString $l 1 #l
        GoTo Loop

     :EndLoop
;     InputBox $dir "Select directory %var%" $list

CopyToClipboard $a

Copies to clipboard value contained in variable $a or the value directly.

Pastes the contents of the clipboard (text only) into variable $a.

Conditionally branches to the specified "label" if expression evaluates to true. See the section on operators for a description of the boolean conditions that can be used in this statement. For an example of this command see the "DirList" example.

Forces execution to jump to "label". This command is demonstrated in the example for the "DirList" command or the "Archive Old Mail" script.

Provides rudimentary subroutine support. Execution will be transferred to the indicated label. All commands from the label to the first Return command will be executed.

Returns control to the statement following the Call command that invoked the subroutine.

Marks the line for branching instructions. Note that the actual label name is preceded with a colon.

Terminates the execution of a script. The execution is terminated for the current message only. If the script is being run against selected messages or if multiple messages are being downloaded or sent then the script will be executed against the remaining messages (provided any filtering conditions used to trigger the script are met). A script can also be terminated by pressing the escape (Esc) key while the script is running.

Back to Poco Help : PocoScript Index : Top

Creating and Editing Scripts

The first step in creating or editing a script is to open the "Scripts" window:

1. Press F9 or select "Scripts..." from the "Tools" menu.
2. Press the "Edit Script" tab.

To create a script type the commands in the window, one per line. It is recommended that you add a comment describing the script's purpose as the first line in the script.

To edit a script select the script name from the drop down box beside the Script name: label.

Note: Scripts are stored as plain text files in the scripts directory. Any plain text editor can be used to create or edit them.

Configuring and Setting Up Scripts

Configuring a Script for Automatic Execution

The process of configuring a script for automatic execution is the series of steps used to indicate when the script is to be run (eg: Against all incoming messages) and the order in which the script is to be executed with respect to other filters and scripts. This process is done using the "Filters" window.

1. Open the "Filters" window by pressing F4 or by selecting "Filters..." from the "Tools" menu.
2. Select the environment in which you want the script to run by pressing one of the tabs at the top of the "Filters" window.
3. Press the "Add Script" command button near the bottom of the window.
4. Select the script name and, if required, the account name.
5. Press the "Ok" button.
6. The entry will be created at the bottom of the list of filters. To change the order simply drag the entry to the appropriate position in the filter list.

Setting up a script

The process of setting up a script is used to establish initial values for the script to use. These values replace the ones predefined by the script author and are designed as a means for you to alter the behaviour of the script without having to modify the script yourself.

To setup a script:

1. Press F9 or select "Scripts..." from the "Tools" menu.
2. Press the "Setup Script" tab.
3. Select the script name from the drop down box beside the Script name: label.
4. Change the values supplied as appropriate. The comments at the beginning of the script may provide insight as to the values that can be used for the setup variables. Sometimes scripts will allow setting up of files for use within the script (the "Vacation Message" script is an example). When this is done the setup pane will contain a command button for each file that will be used within the script. Pressing one of these buttons will open the file for editing in NotePad.