Hamster-Scripts: Functions (Hamster)

HamVersion( <which> )

HamVersion

If used without parameter, it returns the version number of Hamster.

If <which> is given, it returns Hamster version (1), its maintainer (2), its download URL (3) or a comment with "stable" or "beta" (4). Currently unsupported values return an empty string.

Returns: String.

print( "Hamster Vr. " + HamVersion )

HamPath

Returns the base-path of Hamster, i.e. the path were "Hamster.exe" is located.

Returns: String with full qualified path-name and trailing backslash.

if( FileExists( HamPath + "Mails\Mail.Out\*.msg" ) )
   # send mails
endif

HamRequest( <request>, <request-list>, <reply-list> )

HamRequest( <request>, <request-list> )
HamRequest( <request> )

Sends the given request code <request> with the given parameters (<request-list>) to Hamster's internal "Live" server. The reply-code is returned as function's result, reply-data is returned in <reply-list>.

Both <request-list> and <reply-list> are lists, that were previously allocated by ListAlloc. They can also be given as -1, if no request parameters are needed or no result lines are expected/wanted.

For details on available requests, their parameters and replies see Live Mode of Remote Control Server. Please note, that parameters and results separated by "CRLF" have to be given or are returned as separate lines in the lists.

Returns: -1 on failure, otherwise Live reply code (e. g. 0x4000 on success).

#!load hamrequests.hsm

varset( $lReq, ListAlloc )
varset( $lRep, ListAlloc )
var( $Reply )

$Reply = HamRequest( $LMREQ_COUNTERS_LIST, $lReq, $lRep )
if( $Reply = $LMREP_OK )
   print( "All counters: ", ListGetText( $lRep ) )
   print( "Byte counter: ", ListGetKey( $lRep, "by" ) )
else
   print( "Request failed! Reply=", hex($Reply) )
endif

ListFree( $lReq )
ListFree( $lRep )

HamRequestStr( <request>, <request-string>, <reply-string-variable> )

HamRequestStr( <request>, <request-string> )
HamRequestStr( <request> )

Same as HamRequest above, but request parameters have to be given as a string (containing any CRLF characters) and reply data is returned as a string in the given variable.

Returns: -1 on failure, otherwise Live reply code (e. g. 0x4000 on success).

#!load hamrequests.hsm

var( $Reply, $ReplyData )

$Reply = HamRequestStr( $LMREQ_COUNTERS_LIST, "", $ReplyData )
if( $Reply = $LMREP_OK )
   print( "All counters: ", $ReplyData )
endif

HamMessage( <message>, <parameter> )

HamMessage( <message> )

Initiates some Hamster-functions, which are normally available and accessed by its menu-items:

<message>	<parameter> (default=0)	purpose
2	ignored	Reset counters and log
3	0=stop, 1=start, 2=restart	Start/Stop local NNTP server
4	0=stop, 1=start, 2=restart	Start/Stop local POP3 server
5	0=stop, 1=start, 2=restart	Start/Stop local SMTP server
8	ignored	Menu: Online/Stop all tasks
100	0=stop, 1=start, 2=restart	Start/Stop local RC server

Returns: 0=OK, 1=Failed, 2=Unknown message-number, 3=GPF

HamMessage( 2, 0 ) # reset counters

HamGetStatus( <type>, <item> )

HamGetStatus( <type> )

Returns current status information of given <type> for given <item> (default 0).

Supported <types>:

<type> = 1

Returns 1 if local server is active, 0 otherwise.
<items>: 1=NNTP, 
         2=POP3,
         3=SMTP,
         4=Remote Control

<type> = 2

Returns the number of currently connected clients.
<items>: 1=NNTP,
         2=POP3,
         3=SMTP,
         4=Remote Control

<type> = 3

Returns one of the internal counter values.
<items>: 1=new articles,
         2=loaded articles,
         3=not loaded (history),
         4=not loaded (score file),
         5=articles in outbox,
         6=new mails,
         7=mails in outbox,
         8=loaded mails,
         9=mails to news

Returns: >=0: Status, <0: Invalid <type> or <item>

print( HamGetStatus( 2, 1 ) )

HamThreadCount

Gives the number of currently active tasks.

Note: Client-connections to local servers and running scripts do not count as "active tasks" here.

Returns: Integer

print( HamThreadCount )

HamIsIdle

Returns TRUE (1) if there are currently no active tasks like purging, pulling news, sending mails etc.

Note: Client-connections to local servers and running scripts do not count as "active tasks" here.

Returns: Integer

if( HamIsIdle )
   # ...
endif

HamWaitIdle( <timeout> )

HamWaitIdle

Waits up to the given amount of milliseconds until all active tasks are finished. If no <timeout> is given, the function does not return until Hamster is idle again.

Note: Client-connections to local servers and running scripts do not count as "active tasks" here.

Returns: 0=OK, 1=Timeout, 2=Interrupted

HamWaitIdle

HamFlush

Writes unsaved data to disk. Suggested after last article imported with HamArtImport.

Returns: 0

HamFlush

HamPurge( <option>, <group> )

HamPurge( <option> )
HamPurge

Starts a purge-thread (i.e. the deletion of old data). The bit-oriented parameter <option> describes, which old data should be deleted (1=articles, 2=news-history, 4=killfile-log, 8=mail-history). If it's omitted, all type of data are purged.

If <group> is given and 1=articles is selected, only the given group is purged.

Returns: 0=OK/Started, <>0=Not started

HamWaitIdle
HamPurge( 1 + 2 + 4 )
HamWaitIdle

HamRebuildGlobalLists

Starts a thread, which rebuilds some lists needed by Hamster, especially the list of newsgroups used for selecting new news-pulls.

Returns: 0=OK/Started, <>0=Not started

HamWaitIdle
HamRebuildGlobalLists
HamWaitIdle

HamRebuildHistory

Starts a thread, which deletes the current news-history and rebuilds it by adding the Message-IDs of all articles stored in Hamster.

Note: This may take some time with thousands of articles, so it should only be used, if it's really necessary! Be sure to wait until Hamster is idle again after calling this function!

Returns: 0=OK/Started, <>0=Not started

HamWaitIdle
HamRebuildHistory
HamWaitIdle

HamSetLogin( <identifier>, <username>, <password> )

Temporarily sets <username> and <password> for the given <identifier>, which can be either the name of a RAS-connection or the name of a news-/mail-server. "Temporarily" means, that this setting is not saved to a file but is kept in memory until Hamster is closed again.

If username and/or password is set to a single question-mark ("?"), Hamster will ask for the value.

Furthermore, one of the stored "general-purpose"-passwords can be selected here to avoid noting it in clear-text in the script.

Returns: 0=OK, <>0=Error

HamSetLogin( "MyProvider", "MyUsername", "MyPassword" )
HamSetLogin( "MyProvider", "MyUsername", "?" )
HamSetLogin( "MyProvider", "$42", "" )

HamNewsPull( <server-list> )

HamNewsPull

Starts the threads, which pull new articles from newsservers.

If <server-list> is omitted or set to an empty string (""), all NNTP-servers defined in Hamster will be used. Otherwise, transfer is restricted to the given servers.

If used, <server-list> has to consist of a semicolon-separated (";") list of servernames. The servernames have to be in the same format as displayed in the Hamster-settings (i.e. servername + "," + port), e.g.: "news.aaa.com,nntp;news.bbb.com,nntp"

Note: Starting with Hamster Vr. 1.3.19, this function was replaced with the NewsJobs*-functions described below and is only simulated internally with these new functions. See the example at "HamNewsJobsStart" for a replacement of this obsolete function.

Returns: 0=OK/Started, <>0=Not started

HamNewsPull
HamNewsPull( "one.newsserv.er,nntp;two.newsserv.er,nntp" )

HamNewsPost( <server-list> )

HamNewsPost

Starts the thread, which posts new articles (if any).

If <server-list> is omitted or set to an empty string (""), all NNTP-servers defined in Hamster may be used. Otherwise, transfer is restricted to the given servers.

Returns: 0=OK/Started, <>0=Not started

HamNewsPost
HamNewsPost( "one.newsserv.er,nntp;two.newsserv.er,nntp" )

HamNewsJobsClear

Clears the list of news-related jobs.

Returns: 0

HamNewsJobsClear

HamNewsJobsPullDef( <server-list> )

HamNewsJobsPullDef

Fills the list of news-related jobs with the pull-list of the given newsservers (i.e. one job for each group to pull from a server).

If <server-list> is omitted or set to an empty string (""), all groups of all NNTP-servers defined in Hamster will be added. Otherwise, only the groups for the given servers will be added.

Returns: <0: Error, >=0: Number of pull-jobs added

HamNewsJobsPullDef
HamNewsJobsPullDef( "one.newsserv.er,nntp;two.newsserv.er,nntp" )

HamNewsJobsPostDef( <server-list> )

HamNewsJobsPostDef

Fills the list of news-related jobs with post-jobs for the given newsservers (i.e. one job for each article waiting to be posted).

If <server-list> is omitted or set to an empty string (""), all NNTP-servers defined in Hamster may be used to post the article. Otherwise, transfer is restricted to one of the given servers.

Returns: <0: Error, >=0: Number of post-jobs added

HamNewsJobsPostDef
HamNewsJobsPostDef( "one.newsserv.er,nntp;two.newsserv.er,nntp" )

HamNewsJobsPull( <server>, <group-select> )

HamNewsJobsPull( <server> )

Fills the list of news-related jobs with the pull-list of the given newsserver <server>.

If <group-select> is given, only the groups matching this regular expression are added.

Returns: <0: Error, >=0: Number of pull-jobs added

HamNewsJobsPull( "one.newsserv.er" )
HamNewsJobsPull( "two.newsserv.er", "^alt\." )

HamNewsJobsPost( <server>, <group-select>, <header-select> )

HamNewsJobsPost( <server>, <group-select> )
HamNewsJobsPost( <server> )

Fills the list of news-related jobs with post-jobs for the given newsserver <server>.

If <group-select> is given and not empty, only articles with a newsgroup matching this regular expression are added.

If <header-select> is given, only articles with a header-line matching this regular expression are added.

Note: Hamster does not support "multiple injection", so once an article is added to the list, it is ignored in further assignments.

Note: Hamster only posts to servers from which a group is also pulled. So, regardless which selections you choose, the resulting server/group-combination has to be in Hamster's pull-list, too.

Returns: <0: Error, >=0: Number of post-jobs added

HamNewsJobsPost( "one.newsserv.er", ".*", "^X-Post-To: one.newsserv.er" )
HamNewsJobsPost( "two.newsserv.er", "^alt\." )
HamNewsJobsPost( "one.newsserv.er" )

HamNewsJobsFeed( <server>, <group-select> )

HamNewsJobsFeed( <server> )

Fills the list of news-related jobs with feed-jobs for the given newsserver <server>.

If <group-select> is given and not empty, only articles with a newsgroup matching this regular expression are added.

Note: Hamster feeds the remote server using the IHAVE command. CHECK and TAKETHIS are not available.

Returns: <0: Error, >=0: Number of feed-jobs added

HamNewsJobsFeed( "two.newsserv.er", "^comp\." )
HamNewsJobsFeed( "one.newsserv.er" )

HamNewsJobsStart( <server-list> )

HamNewsJobsStart

Starts transfer-threads for the given servers that have pending news-jobs.

If <server-list> is omitted or set to an empty string (""), threads for all newsservers with pending news-jobs are started. Otherwise, only threads for the given servers are started.

Returns: <0: Error, >=0: Number of threads started

# replacement for HamNewsPost and HamNewsPull:
HamNewsJobsClear
HamNewsJobsPostDef
HamNewsJobsPullDef
HamNewsJobsStart

HamMailExchange( <server-list> )

HamMailExchange

Not supported any more, use "HamFetchMail" and "HamSendMail" instead.

HamFetchMail( <server>, <port>, <user>, <pass>, <destuser>, <filter>, <leave> )

...
HamFetchMail( <server> )

Starts a thread, which fetches mails from the given POP3-server (<server>, <port>).

If <user> (username) and <pass> (password) are given, they will be used to login to the server, if they are both empty, the password-setting for the given server is used. Furthermore, one of the stored "general-purpose"-passwords can be used here to avoid noting it in clear-text in the script (<user>="$(number), <pass>="").

If <destuser> is given, fetched mails will be stored in the mailbox of this user, "admin"-mailbox is used otherwise.

If <filter> is given, it determines the filter-section to use for the mails fetched with this commands (default is global filters only, i.e. "[*]"-section in MailfFilt.hst).

If <leave> is given, it overrides any default settings regarding "leave mails on server". A value of "1" always leaves mail on server, a value of "0" deletes them after loading.

Returns: 0=OK/Started, <>0=Not started

HamFetchMail( "pop3.serv.er", "pop3", "", "", "", "", "1" )
HamFetchMail( "pop3.serv.er", "", "john.doe", "secret", "john", "" )
HamFetchMail( "pop3.serv.er", "10110", "$7", "", "jane", "" )
HamFetchMail( "pop3.serv.er", "", "$42", "", "admin", "myfilters" )

HamSendMail( <server>, <port>, <from-select>, <to-select> )

...
HamSendMail( <server> )

Starts a thread, which sends mails to the given SMTP-server (<server>, <port>).

If no <from-select> and no <to-select> is given, all mails waiting for delivery are sent. If selections are given (regular expressions), only mails with a matching Envelope-From/-To are sent to this server.

Returns: 0=OK/Started, <>0=Not started

HamSendMail( "smtp1.serv.er", "smtp", "john\.doe@serv\.er" )
HamSendMail( "smtp2.serv.er" )

HamSendMailAuth( <server>, <port>, <user>, <pass>, <from-select>, <to-select> )

...
HamSendMailAuth( <server> )

Like "HamSendMail" above, but additionally allows to provide username and password used for authentication.

Note: Username and password are ignored, if SMTP authentication is not enabled for the given server.

Returns: 0=OK/Started, <>0=Not started

HamSendMailAuth( "smtp3.serv.er", "smtp", "$42", "", "@smtp3\.serv\.er" )

HamSendMailMX

Starts a thread, which sends mails in MX mode, i. e. Hamster tries to detect the mail exchange (MX) servers of mail recipients and then sends the mails directly to these servers.
See "Reference: File SmtpRouter.hst" for additional info on this MX mode.

Returns: 0=OK/Started, <>0=Not started

# Try to send mails in MX mode
HamSendMailMX
HamWaitIdle
# Send remaining mails to provider's server
HamSendMail( "mail.provid.er" )
HamWaitIdle

HamNewMail( <EnvelopeFrom>, <EnvelopeTo>, <Mailtext> )

Send a new mail as if it had been sent to Hamster's SMTP server.

<EnvelopeFrom> is the sender of the mail, <EnvelopeTo> are the recipients separated by ";". Both envelope values may contain the name of local users like "admin".

<Mailtext> is the mail to send. It contains header lines, an empty line as header/body separator and finally the text of the message. If required "Date:" or "From:" headers are missing, they will be added automatically.

Returns: 0=OK, <>0=Failed

varset( $EnvFrom, "admin" )
varset( $EnvTo, "admin;john.doe@remote.address;jane.doe@remote.address" )
varset( $MailText, ListAlloc )
ListAdd( $MailText, "From: admin" )
ListAdd( $MailText, "To: (various recipients)" )
ListAdd( $MailText, "Subject: Mail by Script!" )
ListAdd( $MailText, "" ) # header/body separator
ListAdd( $MailText, "This mail was sent by script!" )
HamNewMail( $EnvFrom, $EnvTo, ListGetText($MailText) )
ListFree( $MailText )

HamRasDial( <name>, <user>, <pass> )

...
HamRasDial( <name> )

Dials the RAS-connection named "<name>" and tries to authenticate with username <user> and password <pass> (if given).

If <user> and/or <pass> is omitted or set to empty strings (""), the settings of "HamSetLogin" (if any) or the values stored in Hamster are used to establish the connection. This function also supports one of the stored "general-purpose"-passwords to avoid noting it in clear-text in the script (<user>="$(number), <pass>="").

NOTE: If this function is used, "HamRasHangup" should be used to terminate the connection again.

Returns: 0=OK/connected; >0=error-code; -1=RAS not installed

$try = 1
while( HamRasDial( "MyProvider","$42" ) != 0 )
   if( $try >= 3 )
      error( "Dialing failed!" )
   endif
   inc( $try )
   sleep( 10000 )
endwhile

HamRasHangup

Terminates an existing RAS-connection.

Returns: 0: OK; >0: error-code; -1: RAS not installed

HamRasHangup

HamGroupCount

Retrieves number of newsgroups available from Hamster.

Returns: >=0: OK/number of groups; <0: error

# see example at HamGroupName

HamGroupName( <index> )

Retrieves the name of the given newsgroup. <index> can be 0 to (HamGroupCount-1).

Returns: String

var( $grpidx )
$grpidx = 0
while( $grpidx < HamGroupCount )
   print( HamGroupName( $grpidx ) )
   inc( $grpidx )
endwhile

HamGroupIndex( <grpname> )

Retrieves the index-number of the given groupname.

Returns: >=0: OK/index-number; -1: unknown group

print( HamGroupIndex( "internal.misc" ) )

HamGroupOpen( <grpname> )

Opens the given group and returns a handle, which is needed to retrieve additional infos in the functions below (the handle is referenced as <grphdl> there).
If the function fails, the return-value is negative (<0).

Returns: >=0: OK/group-handle; <0: error

$grphdl = HamGroupOpen( "internal.misc" )

HamGroupClose( <grphdl> )

Closes a previously opened group.

Returns: 0

HamGroupClose( $grphdl )

HamArtCount( <grphdl> )

Retrieves the number of available articles in the group.

Returns: >=0: OK/count, <0: error

# see example at HamArtText

HamArtNoMin( <grphdl> )

Retrieve the lowest available article-number.

Returns: >=0: OK/count, <0: error

# see example at HamArtText

HamArtNoMax( <grphdl> )

Retrieve the highest available article-number.

Returns: >=0: OK/count, <0: error

# see example at HamArtText

HamArtText( <grphdl>, <artno> )

Retrieves the text for the given article-number. An empty string indicates, that an article with the given number is not available (any more).

Returns: String (article-text or "")

var( $grpnam, $grphdl, $artmin, $artmax, $artno, $arttxt )

$grpnam = "internal.misc"
$grphdl = HamGroupOpen( $grpnam )

if( $grphdl >= 0 )
   print( "Group ", $grpnam, ": ", HamArtCount($grphdl), " articles" )
   $artmin = HamArtNoMin( $grphdl )
   $artmax = HamArtNoMax( $grphdl )

   $artno = $artmin
   while( $artno <= $artmax )
      $arttxt = HamArtText( $grphdl, $artno )
      if( $arttxt <> "" )
         print( "Article ", $artno, ": ", len($arttxt), " byte" )
      endif
      inc( $artno )
   endwhile

   HamGroupClose( $grphdl )
endif

HamArtTextByMid( <mid> )

Retrieves the text for the given Message-ID. An empty string indicates, that an article with the given Message-ID is not available (any more).
Please note, that only Message-IDs of articles work here, that are within the "Days to keep data: History" range. Older articles cannot be accessed by this function.

Returns: String (article-text or "")

$arttxt = HamArtTextByMid( "<aaa.bbb@ccc.ddd>" )

HamArtTextExport( <grphdl>, <artno> )

Same as "HamArtText", but the text is additionally converted to export-format.

Returns: String (article-text or "")

$arttxt = HamArtTextExport( $grphdl, $artno )

HamArtImport( <article>, <goverride>, <ignorehist>, <marknoarch> )

...
HamArtImport( <article> )

Imports the given <article> into Hamster's database and returns TRUE, if the article was imported, FALSE otherwise.
<article> contains the article to import, including all headers, header/body-separator and the article-body. The lines have to be separated by CR+LF (0x0d, 0x0a).
If <goverride> is empty (default), the article is stored in the groups determined by the "Newsgroups:"-header of the article. Otherwise it is stored in the group given by <goverride>. If no valid local groups are given, the article is stored in internal.misc.
If <ignorehist> is TRUE (<>0), no history-lookup is made for the Message-ID of the imported article, so it will be imported even if it's already known. Default is FALSE.
If <marknoarch> is TRUE (<>0), the imported article is marked with "NoArchive=1" in the "X-Hamster-Info:"-header. This flag might be used to mark the imported article as "temporary", so it can, for example, be ignored by appropriate archiving-software. Default is FALSE.

Returns: true/1: OK, false/0: error

HamArtImport( $article_text, "internal.misc" )

HamArtImportFile( <filename>, <goverride>, <ignorehist>, <testonly> )

...
HamArtImportFile( <filename> )

Imports a file with given <filename>, that contains articles in "mbox" format.
If <goverride> is empty (default), the article is stored in the groups noted in the "Newsgroups:"-header of imported articles. Otherwise it is stored in the group given by <goverride>. If no valid local groups are given, the article is stored in internal.misc.
If <ignorehist> is TRUE (<>0), no history-lookup is made for the Message-ID of the imported article, so it will be imported even if it's already known. Default is FALSE, i. e. don't import already known articles.
If <testonly> is given and TRUE (<>0), the articles are not really imported but just tested, if they can be imported. Default is FALSE, i. e. import the articles.

Returns: >=0: Number of imported articles, -1: File not found; -2: Unknown file format; -9: Error

HamArtImportFile( "articles.mbox" )

HamArtExportFile( <filename>, <groupname>, <artnomin>, <artnomax> )

...
HamArtExportFile( <filename>, <groupname> )

Exports articles of group <groupname> to file <filename> in "mbox" format.
The range of article numbers to export can be selected by <artnomin> and <artnomax>. If these values are missing or are given as -1, the lowest/highest available numbers are used.

Returns: >=0: Number of exported articles, -1: Unknown group; -9: Error

HamArtExportFile( "articles.mbox", "internal.misc" )

HamArtDeleteMid( <message-id> )

Locates the article identified by the given <message-id> and deletes it in Hamster's database-files. The function returns 0, if article could be located and deleted; a value other than 0 otherwise.

Returns: =0: Deleted, <>0: Message-ID not found/deletion failed

HamArtDeleteMid( "<12345.67890@abd.def.ghi>" )

HamArtLocateMid( <message-id>, <grpname>, <artno> )

HamArtLocateMid( <message-id> )

Returns 0, if the given Message-ID is (still) saved in the history-file. In this case, the variables <grpname> and <artno> will be set to point to this article. Otherwise the function returns a value other than 0 and <grpname> and <artno> remain unchanged.

Returns: =0: OK/found, <>0: Message-ID not found

if( HamArtLocateMid( "<12345.67890@abd.def.ghi>", $groupname, $artno ) )
   # ...
endif

HamScoreList( <grpname> )

Retrieves a list containing all score-entries, which will be used when pulling news for the given groupname <grpname>.

Returns: String

ListSetText( $ScoreList, HamScoreList( "group.name" ) )

HamScoreTest( <grpname>, <article>, <matchlog>, <scoretype> )

HamScoreTest( <grpname>, <article>, <matchlog>  )
HamScoreTest( <grpname>, <article> )

Returns the score-value for the given article <article>.

The test is done with the assumption, that the article was pulled from the given newsgroup <grpname>.

A CR/LF-separated list of all matching score-lines is returned in the variable <matchlog>.

If <scoretype> is missing or 0, the sum of "Score-Before-Load" and "Score-After-Load" is returned. A value of 1 returns "Score-Before-Load" and a value of 2 returns "Score-After-Load" value.

Returns: Integer (score value)

$ScoreValue = HamScoreTest( "group.name", $Article, $MatchLog )

HamFinger( <address> )

Execute a finger query on port 79 to the server named in <address>. This sends the Hamster server IP to the remote server for incoming feeds on the special anonymous nntpdefault account in stream mode.

Returns: The complete query from the server.

$QueryResult = HamFinger( "login@finger.server" )

HamSound( <filename.wav>, <wait>, <system> )

HamSound( <filename.wav>, <wait> )HamSound( <filename.wav> )

Plays <filename.wav>. If <wait> is missing or 0 the script does not wait for the end of the sound playing to continue. If <system> is missing or 0 the sound full path must be specified, if 1 Hamster assumes the path is the system sounds path (windows\media).

Returns: True if okay, otherwise False.

$OK = HamSound( "ding.wav", 0, 1 )

[Hamster Ys Documentation]