Reference: File HscActions.hst

How to ... start a script on startup?

Purpose

With the "Script Actions" defined in file HscActions.hst, scripts and "User Tasks" can be started automatically whenever one of the predefined event happens.

See also: Setup Action Tasks

Action Events

Each action event is identified by a unique name and can have different parameters.

Supported events are:

Startup

Happens once when Hamster is started (informational only).

ParamStr(1): Startup

Shutdown

Happens once when Hamster is stopped (informational only).

ParamStr(1): Shutdown

NewsOut

Happens right before an article to be posted is placed in News.Out directory.
Action script can modify the message (by 3rd parameter), it can even replace it with an empty text to prevent it from being saved.

ParamStr(1): NewsOut
ParamStr(2): Path and filename where message is about to be stored.
ParamStr(3): MsgAlloc number of message.

NewsInLocal

Happens right after an article was posted to the local NNTP server and is about to be processed now. If the article is to be sent out, this event happens before above NewsOut.
Action script can modify the message (by 3rd parameter), it can even replace it with an empty text to prevent it from being accepted and processed further.

ParamStr(1): NewsInLocal
ParamStr(2): Destination of message (1=will be mailed to moderator of group, 2=will be mailed to gateway, 3=will only be sent out i. e. placed in Mail.Out, 4=will only be stored in local newsgroup, 5=will both be sent out and stored locally, 6=feeded with IHAVE/TAKETHIS and will only be stored in local newsgroups).
ParamStr(3): MsgAlloc number of message.

NewsIn

Happens right after an article was loaded from a remote server and before it is saved in a local newsgroup file.
Action script can modify the message (by 3rd parameter), it can even replace it with an empty text to prevent it from being saved.

Warning: Special care must be taken when using such a NewsIn action, as this action will be called very often and multiple times concurrently for each transfer thread. It is strongly suggested to only use it with default options Wait=1 and Lock=1 to avoid any concurrency issues. Also be prepared, that it may slow down news transfer drastically, as each message will have to go through your action script then.

ParamStr(1): NewsIn
ParamStr(2): Name of the newsgroup where the message is about to be stored.
ParamStr(3): MsgAlloc number of message.

MailToNews

Happens right before a mail loaded from a remote server is redirected, i. e. stored in a newsgroup. Action script can modify the message (by 3rd parameter), it can even replace it with an empty text to prevent it from being saved.

ParamStr(1): MailToNews
ParamStr(2): Name of the newsgroup where the message is about to be stored.
ParamStr(3): MsgAlloc number of message.

MailOut

Happens right before a mail to be sent is placed in Mail.Out directory.
Action script can modify the message (by 3rd parameter), it can even replace it with an empty text to prevent it from being saved.

ParamStr(1): MailOut
ParamStr(2): Path and filename where message is about to be stored.
ParamStr(3): MsgAlloc number of message.
ParamStr(4): Authenticated account name of sender (empty if configuration does not require SMTP-AUTH).

MailOutFile

Happens right after MailOut but still before the mail is actually saved as "ready to be send".

Action script can both modify and delete the given message file.

ParamStr(1): MailOutFile
ParamStr(2): Path and filename of temporary message file.
ParamStr(3): Authenticated account name of sender (empty if configuration does not require SMTP-AUTH).

MailIn

Happens right before a mail fetched from a remote server or sent locally is placed in receiver's mailbox.

Action script can modify the message (by 3rd parameter), it can even replace it with an empty text to prevent it from being saved.

ParamStr(1): MailIn
ParamStr(2): Path and filename where message is about to be stored.
ParamStr(3): MsgAlloc number of message.
ParamStr(4): Name of user account to receive the message.
ParamStr(5): Origin of incoming mail (0=SMTP, 1=ESMTP, 2=Script, 3=POP3, 4=Internal, 5=NewsToMail).

MailInFile

Happens right after MailIn but still before a mail fetched from a remote server or sent locally is placed in receiver's mailbox.

Action script can both modify and delete the given message file.

ParamStr(1): MailInFile
ParamStr(2): Path and filename of temporary message file.
ParamStr(3): Name of user account to receive the message.
ParamStr(4): Origin of incoming mail (0=SMTP, 1=ESMTP, 2=Script, 3=POP3, 4=Internal, 5=NewsToMail).

MailInHeader

Happens right after the headers of a new mail fetched from a remote POP3 server or sent to the local SMTP server are available.

Action script can modify the headers (by 3rd parameter), it can even replace it with an empty text to prevent it from being handled further.

ParamStr(1): MailInHeader
ParamStr(2): [*] Path and filename in "admin" mailbox.
ParamStr(3): MsgAlloc number of message.
ParamStr(4): [*] Always "admin".
ParamStr(5): [*] Origin of incoming mail (0=SMTP, 1=ESMTP, 3=POP3).
[*] Only added for compatibility with MailIn, real values are not available yet or are not supported in this case.

MailInHeaderFile

Happens right after MailInHeader and provides all headers in a file.

Action script can both modify and delete the given header file.

ParamStr(1): MailInHeaderFile
ParamStr(2): Path and filename of temporary file.
ParamStr(3): [*] Name of user account to receive the message.
ParamStr(4): [*] Origin of incoming mail (0=SMTP, 1=ESMTP, 3=POP3).
[*] Only added for compatibility with MailInHeader, real values are not available yet or are not supported in this case.

NewsWaiting

Happens right after a news message was placed in News.Out directory, i. e. there is a new news message waiting to be sent out (informational only).

ParamStr(1): NewsWaiting
ParamStr(2): Path and filename where message was stored.
ParamStr(3): MsgAlloc number of message.

MailWaiting

Happens right after a mail message was placed in Mail.Out directory, i. e. there is a new mail message waiting to be sent out (informational only).

ParamStr(1): MailWaiting
ParamStr(2): Path and filename where message was stored.
ParamStr(3): MsgAlloc number of message.

MsgWaiting

Happens right after a mail or news message was placed in the appropriate .Out directory, i. e. there is a new message waiting to be sent out (informational only).
MsgWaiting happens after MailWaiting/NewsWaiting.

ParamStr(1): MailWaiting
ParamStr(2): Path and filename where message was stored.
ParamStr(3): MsgAlloc number of message.

ReportsCreated

Happens right after new reports were created..

ParamStr(1): ReportsCreated

File Format

The file is a standard Windows .ini file, in which each action event has its own section, e. g. the "[Startup]" section contains the definitions for the event named Startup.

The keys in each section are as follows:

Script=<script's filename>

Name of the script file to start whenever the event happens.
Starting with version 1.12, a User Task can also be started by giving the name of its definition file (*.hut) here.

Wait=<wait for end 0/1>

If set to 1, Hamster waits until the action script has terminated before it continues. Default is 0, i. e. continue immediately.

Warning: Never use Wait=0 if you want to access a message provided by a MsgAlloc parameter, as Hamster might already have freed this message even before the first line of your script is executed!

Lock=<locked execution 0/1>

If set to 1, all other actions have to wait until the current one was either started (Wait=0) or has finished executing (Wait=1). Default is 0, i. e. multiple action scripts may run concurrently.

Silent=<silent execution 0/1>

If set to 1, the usual log file lines when starting a script are omitted. Default is 0, i. e. create the log entries.

Example:

[Startup]
Script=Startup.hsc
Wait=0
Lock=0
Silent=0

[Shutdown]
Script=Shutdown.hsc

Action Scripts

Each script is started with at least one parameter, the name of the action. This parameter is always the first one (i. e. accessible by ParamStr(1) script function) and allows the handling of different actions within a single script:

if( ParamStr(1) = "Startup" )
   print( "Hello!" )
endif

if( ParamStr(1) = "Shutdown" )
   print( "Bye!" )
endif

Other parameters depend on the specific action and were noted in event description above.

Please note:

Action scripts should not be used to start processes, which will take longer than a few seconds, as Hamster might "hang" in the meanwhile and might not be able to handle your process!

Either use the Wait=0 option for the action in this case or just use the action as a trigger for the long running process, e. g. start this process by an appropriate RunScript command.

Messages in Action Scripts

Some actions provide a "MsgAlloc number" parameter, which allows accessing and modifying a message. To access the message text, you first have to convert this parameter to a number. This number can then be used with any Msg-functions as if it had been returned by MsgAlloc:

var( $Msg )
$Msg = int( ParamStr(3) )
print( MsgGetText($Msg) )

Please note:

Do not use MsgFree with such a message number! If an action allows to clear the message, use MsgSetText( $Msg, "" ) instead, i. e. just setting its content to an empty string.

[www.elbiah.de Hamster Playground Documentation]