Reference: File HscActions.hst

Purpose

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

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.

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.

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.

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.

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.

Wait=<wait for end 0/1>

If set to 1 (default), Hamster waits until the script has terminated before it continues.

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 (default), all other actions have to wait until the current one was either started (Wait=0) or has finished executing (Wait=1).

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.

[Hamster Ys Documentation]