Hamster-Skripte - Version 2

Bitte beachten:
Um die Hamster-Skripte, Version 2, einsetzen zu können, muß die erste Zeile eines Skripts so aussehen:
#!hs2
Diese Zeile bestimmt, womit das Skript ausgeführt wird; falls dieser Befehl fehlt, wird davon ausgegangen, daß es weiterhin ein Skript alten Typs ist.

Überblick über die Befehlssprache
Daten-Typen
Operanden
Variable

Einleitende Befehle
Ausdrücke
Funktionen (integriert)
Funktionen (selbst definiert)
Funktionen (Hamster)
Module

Überblick über die Befehlssprache

Kodierungszeilen

Die Hamster-Skriptsprache ist zeilenorientiert. Das bedeutet, dass jeder Ausdruck in eigener Zeile steht (woebei die Länge einer Zeile keiner Beschränkung unterliegt):

Sehr lange Zeilen können umgebrochen werden, indem ein Unterstrich "_" am Zeilenende die Verbindung aufrechthält. Bei der Ausführung des Skripts wird diese Markierung durch ein Leerzeichen ersetzt und der folgende Zeilenumbruch wird entfernt. So wird intern wieder die ursprüngliche Zeile hergestellt.

Kommentare

Kommentare werden mit dem "#" - Zeichen begonnen, der folgende Zeilentext wird ignoriert:

Es gibt jedoch eine zweite Sorte Kommentare, die innerhalb einer Befehlszeile untergebracht werden dürfen. Diese "eingebetteten" Anmerkungen stehen innerhalb von ( Klammern ):

Datentypen

Skalare
(Scalars)

Hamster verwendet einen variablen Datentypus, der zwei grundlegende Skalar-Arten enthalten kann: Zeichenketten (Strings) oder Ganzzahlige Ausdrücke (Integer).

Zeichenketten können beliebige Folgen von ASCII-Zeichen enthalten, sogar NUL (ASCII 0). Jede Kette kann so lang werden, wie RAM und Swapfile des PCs es zulassen. Konstanten in Zeichenform stehen innerhalb von Anführungszeichen ("...").

Ganzzahlige Ausdrücke existieren in 32-Bit-Form und können Zahlen von -2147483648 bis 2147483647 enthalten. Konstanten (in Hexadezimalform) enthalten ein führendes "0x" (die Zahl 0 - Null und den Kleinbuchstaben x, z.B. 0xFF).

Integer (Ganzzahlige Ausdrücke) dienen auch als Platzhalter Bool´scher Ausdrücke, wobei der Wert 0 FALSCH und jeder andere Wert WAHR bedeutet (alle eingebauten Funktionen, insbesondere "wahr" geben in diesem Fall "1" aus).

Beim Einsatz werden die Datentypen, falls erforderlich, automatisch konvertiert; wird ein Ganzzahliger Ausdruck in einer Zeichenkette verwendet, wird er in eine solche umgewandelt - und umgekehrt.

Arrays, Zufallszahlen (Hashes), Collections, Listen (Lists)

Innerhalb der Hamsterskripte tauchen diese Datentypen nicht auf, in vielen Fällen jedoch können sie durch Listenfunktionen ersetzt oder zumindest simuliert werden. Ist das so, werden sie intern gepflegt und der Zugriff auf sie erfolgt durch eine besondere Listenhandhabung. Zu Einzelheiten siehe "ListAlloc".

Überblick

Variable (Variables)

Alle Variablen beginnen mit einem einzelnen "Dollarzeichen" ("$"), gefolgt von einem Buchstaben ("A"..."Z", "a"..."z"). Weitere Zeichen können auch Zahlen ("0"..."9") oder Unterstriche ("_") enthalten.

Die Länge eines Variablen-Namens ist (tatsächlich) unbeschränkt und alle Zeichen sind von Bedeutung. Groß- und kleingeschriebene Zeichen werden identisch behandelt, also ist z.B. $ABC völlig identisch mit $abc.

Beispiele für gültige Variablen:

Beispiele für ungültige Variablen:

Hamster-Funktionen
(Functions (Hamster))

HamVersion
Übermittelt die Versionsnr. von Hamster
Ausgabe: Zeichenkette mit der Versionsnr. (bspw. "1.3.17.0").
print( "Hamster Vr. " + HamVersion )

HamPath
Übermittelt den Verzeichnispfad von Hamster, bspw. das Verzeichnis, wo sich die Datei "Hamster.exe" befindet.
Ausgabe:Zeichenkette mit dem vollständigen Pfadnamen und folgendem Backslash.
if( FileExists( HamPath + "Mails\Mail.Out\*.msg" ) )
        # send mails
endif

HamMessage( <message>, <parameter> )
HamMessage( <message> )
Aufruf einiger Funktionen von Hamster, die i.d.R. über Menüs ausgewählt und genutzt werden können:

Nachricht (Message)	Parameter (Standard=0)	Zweck (purpose)
1	wird ignoriert	Hamster beenden
2	wird ignoriert	Counters + Log zurücksetzen
3	0=stop, 1=start	Start / Stop lokaler NNTP-Server
4	0=stop, 1=start	Start / Stop lokaler POP3-Server
5	0=stop, 1=start	Start / Stop lokaler SMTP-Server
6	0=verbergen, 1=anzeigen	Verbergen / Anzeigen Hauptfenster
7	0=verbergen, 1=anzeigen	Verbergen / Anzeigen Icon im Systray
8	wird ignoriert	Abbruch aller laufenden Prozesse

Ausgabe: 0=OK, 1=Failed (Fehlgeschlagen), 2=Unknown message-number (Unbekannte Nachrichtennr.), 3=GPF (Schutzverletzung)
HamMessage( 2, 0 ) # reset counters (Counters zurücksetzen)

HamThreadCount
Zeigt die Anzahl der geraden aktiven Tasks an.
Anmerkung: Verbindungen von (Mail-/News-)Clients zum lokalen Server zählen nicht als  aktive Tasks .
Ausgabe: Integer (Ganzzahlig)
print( HamThreadCount )

HamIsIdle
Gibt TRUE (Wahr) (1) aus, falls momentan keine aktiven Prozesse wie Purgen, Newsabruf, Mailversand etc. laufen.
Anmerkung: Verbindungen von (Mail-/News-)Clients zum lokalen Server zählen nicht als  aktive Tasks 
Ausgabe: Integer
if( HamIsIdle )
        # ...
endif

HamWaitIdle( <timeout> )
HamWaitIdle
Wartet entsprechend der eingetragenen Dauer (in Millisekunden) bis alle aktiven Tasks beendet worden sind. Ist kein "timeout" (*** also eine Wartezeit) definiert, wird die Funktion solange ausgeführt, bis Hamster wieder einen (anderen) Prozess startet.
Anmerkung: Verbindungen von (Mail-/News-)Clients zum lokalen Server zählen nicht als  aktive Tasks 
Ausgabe: 0=OK, 1=Timeout, 2=Interrupted (unterbrochen)
HamWaitIdle

HamPurge( <option> )
HamPurge
Beginnt den Prozeß des "Purging" (*** das Löschen alten Datenbestandes). Der bit-orientierte Parameter beschreibt, welche Art Daten gelöscht werden sollen (1=articles / Artikel, 2=news-history, 4=killfile-log, 8=mail-history). Wird der Parameter nicht angegeben, werden alle Datentypen gelöscht.
Ausgabe: 0=OK/Started (gestartet), < oder >0=Not started (Prozeß wurde nicht begonnen)
HamWaitIdle
HamPurge( 4 )
HamWaitIdle

HamRebuildGlobalLists
Damit wird ein Prozeß angestoßen, der einige von Hamster benötigte Listen neu erstellt, insbes. die für die Newsgroup-Auswahl / -Abonnierung benötigten Listen (*** group.txt und grpdesc.txt).
Ausgabe: 0=OK/Started (gestartet), < oder >0=Not started (Prozeß wurde nicht begonnen)
HamWaitIdle
HamRebuildGlobalLists
HamWaitIdle

HamRebuildHistory
Ein Prozessablauf wird begonnen, der die aktuelle Datei news-history (*** Hist40*.dat) löscht und sie anhand aller von Hamster gespeicherten Message-IDs (*** bzw. Artikel) wieder erstellt.
Anmerkung: Möglicherweise dauert das - etwa mit Tausenden Artikeln - länger, deshalb sollte diese Funktion nur bei Bedarf eingesetzt werden. Erst nach Beendigung darf Hamster weitere Befehle ausführen!
Ausgabe: 0=OK/Started, < oder >0=Not started (Prozeß wurde nicht begonnen)
HamWaitIdle
HamRebuildHistory
HamWaitIdle

HamSetLogin( <identifier>, <username>, <password> )
Damit werden vorübergehend <username> (Benutzername) und <password> (Passwort) für einen vorhandenen <Identifier> gesetzt. Der <Identifier< kann entweder eine DFÜ-Verbindung oder der Name eines News-/Mailservers sein. "Vorübergehend" bedeutet nicht das Speichern in einer Datei, sondern den Verbleib im Speicher, bis Hamster beendet wurde.
Werden für "username" und / oder "password" ein einzelnes Fragezeichen ("?") gesetzt, wird der Wert von Hamster erfragt.
Außerdem kann eines der gespeicherten "allgemeinen" Passwörter hier ausgewählt werden, um eine Angabe im Skript in Klartextform zu verhindern.
Ausgabe: 0=OK, "<" oder ">"0=Error
HamSetLogin( "MyProvider", "MyUsername", "MyPassword" )
HamSetLogin( "MyProvider", "MyUsername", "?" )
HamSetLogin( "MyProvider", "$42", "" )

HamNewsPull( <server-list> )
HamNewsPull
Damit wird der Abruf neuer Artikel vom Newsserver begonnen
Wird die "server-list" übergangen oder bleibt sie leer (""), werden alle NNTP-servers, die in Hamster definiert sind, verwendet. Andernfalls ist der Transfer auf die eingetragenen Server beschränkt.
Falls eingesetzt, besteht die "server-list" aus durch Semikolon getrennte (";") Serverbezeichnungen. Die Servernamen haben das gleiche Format wie in den Hamster-Settings (*** Menü File / Configuration / Settings) dargestellt (d.h., Servername + "," + Port), z.B.:
"news.aaa.com,nntp;news.bbb.com,nntp"
Ausgabe: 0=OK/Started, "<" oder ">"0=Not started (Prozeß wurde nicht begonnen)
HamNewsPull
HamNewsPull( "one.newsserv.er,nntp;two.newsserv.er,nntp" )

HamNewsPost( <server-list> )
Beginnt den Prozeß, um neue Artikel (falls vorhanden) zu posten.
Wird die <server-list> übergangen oder bleibt sie leer (""), werden alle NNTP-servers, die in Hamster definiert sind, verwendet. Andernfalls ist der Transfer auf die eingetragenen Server beschränkt.
Falls eingesetzt, besteht die <server-list> aus durch Semikolon getrennte (";") Serverbezeichnungen. Die Servernamen haben das gleiche Format wie in den Hamster-Settings (*** Menü File / Configuration / Settings) dargestellt (d.h., Servername + "," + Port), z.B.:
"news.aaa.com,nntp;news.bbb.com,nntp"
Ausgabe: 0=OK/Started, < oder > 0=Not started (Prozeß wurde nicht begonnen)
HamNewsPost
HamNewsPost( "one.newsserv.er,nntp;two.newsserv.er,nntp" )

HamNewsJobsClear
Löscht die Liste von auszuführenden Aufgaben im Zusammenhang mit News.
Ausgabe: 0
HamNewsJobsClear

HamNewsJobsPullDef( <server-list> )
HamNewsJobsPullDef
Definiert die Aufgabenliste - Newsabruf - (d.h., ein separater Vorgang für jede von einem Newsserver abzurufende Newsgroup).
Falls die <server-list> übergangen wird oder leer ist (""), werden alle Gruppen aller NNTP-Server, die in Hamster definiert wurden, verwendet. Sonst werden nur die Gruppen der explizit ausgewählten Server berücksichtigt.
Falls verwendet, <server-list> enthält eine Aufzählung von Server, getrennt durch Semikolon ";"). Die Serverbezeichnungen müssen das gleiche Format wie in den Hamster-Einstellungen haben (d.h., Servername + "," + Port-Nr.), z.B.: "news.aaa.com,nntp;news.bbb.com,nntp".
Ausgabe: <0: Error (Fehler), >=0: Zahl laufender Aufgaben (Newsabruf)
HamNewsJobsPullDef
HamNewsJobsPullDef( "one.newsserv.er,nntp;two.newsserv.er,nntp" )

HamNewsJobsPostDef( <server-list> )
HamNewsJobsPostDef
Definiert die Aufgabenliste - Versand von Postings - an die vorhandenen Newsserver (d.h., ein separater Vorgang für jedes versandfertige Posting.
Falls die <server-list> übergangen wird oder leer ist (""), können alle in Hamster definierten NNTP-Server für den Postingversand verwendet werden. Andernfalls wird der Transfer auf die bestimmten Server begrenzt.
Falls verwendet, <server-list> enthält eine Aufzählung von Server, getrennt durch Semikolon ";"). Die Serverbezeichnungen müssen das gleiche Format wie in den Hamster-Einstellungen haben (d.h., Servername + "," + Port-Nr.), z.B.: "news.aaa.com,nntp;news.bbb.com,nntp".
Ausgabe: <0: Error (Fehler), >=0: Zahl laufender Aufgaben (Versand von Postings)
HamNewsJobsPostDef
HamNewsJobsPostDef( "one.newsserv.er,nntp;two.newsserv.er,nntp" )

HamNewsJobsPull( <server>, <group-select> )
HamNewsJobsPull( <server> )
Füllt die Aufgabenliste bei News mit der Abrufliste der eingetragenen Newsserver <server>. Falls <group-select> vorhanden ist, werden nur die Gruppen berücksichtigt, die dem Regulären Ausdruck entsprechen.
Ausgabe: <0: Error (Fehler), >=0: Number of pull-jobs added (Anzahl der zu bearbeitenden Abrufe)
HamNewsJobsPull( "one.newsserv.er" )
HamNewsJobsPull( "two.newsserv.er", "^alt\." )

HamNewsJobsPost( <server>, <group-select>, <header-select> )
HamNewsJobsPost( <server>, <group-select> )
HamNewsJobsPost( <server> )
Füllt die Liste der News-bezogenen Arbeitsvorgänge mit Aufträgen zum Postingversand für die vorhandenen Newsserver <server>.
Falls <group-select> vorhanden und nicht leer ist, werden nur Artikel für Newsgroups, die zu einem Regulären Ausdruck passen, berücksichtigt.
Falls <header-select> angegeben ist, werden nur Artikel mit Kopfzeilen, die zu einem Regulären Ausdruck passen, berücksichtigt.
Anmerkung: Hamster unterstützt nicht "multiple injection" (die mehrmalige Einlieferung von Artikeln). Wurde ein Artikel einmal zur Liste hinzugefügt, so wird er bei späteren Vorgängen ignoriert.
Hinweis: Hamster postet nur an Server, von dem / denen neue Artikel für die Gruppe(n) abgerufen werden. Losgelöst von der oben getroffenen Auswahl muss die festgelegte Kombination Server / Gruppe auch in der Abrufliste in Hamster aufgeführt sein.
Ausgabe: <0: Error (Fehler), >=0: Number of post-jobs added (Anzahl hinzugekommener Post-Aufgaben)
HamNewsJobsPost( "one.newsserv.er", ".*", "^X-Post-To: one.newsserv.er" )
HamNewsJobsPost( "two.newsserv.er", "^alt\." )
HamNewsJobsPost( "one.newsserv.er" )

HamNewsJobsStart( <server-list> )
HamNewsJobsStart
Beginnt Transferprozesse für eingetragene Server, die unbearbeitete News-Aufträge haben.
Falls <server-list> übergangen wird oder leer ist (""), werden alle Newsserverver mit unbearbeiteten Jobs angesprochen. Andernfalls werden nur die explizit ausgewählten Server berücksichtigt.
Falls verwendet, muss die <server-list> aus einer durch Semikolon (";") getrennte Aufzählung von Servernamen bestehen. Die Serverbezeichnungen müssen genauso wie in den Hamster-Einstellungen angegeben werden (d.h., Servername + "," + Portnr.), z.B.:
"news.aaa.com,nntp;news.bbb.com,nntp"
Ausgabe: <0: Error (Fehler), >=0: Number of threads started (Anzahl der gestarteten Newsjobs)
# Bei HamNewsPost und HamNewsPull sind zu ersetzen:
HamNewsJobsClear
HamNewsJobsPostDef
HamNewsJobsPullDef
HamNewsJobsStart

HamMailExchange( server-list )
HamMailExchange
Damit werden zuerst neue Mails vom Mailserver abgerufen und danach Mails (falls vorhanden) versendet.
Wird die "server-list" übergangen oder leer gelassen (""), werden alle in Hamster definierten POP3- and SMTP-servers verwendet. Andernfalls ist der Transfer auf die eingetragenen Server eingeschränkt.
Bei Verwendung muß die <server-list> aus einer durch Semikolon getrennte (";") Liste von Servernamen bestehen. Die Servernamen haben das gleiche Format wie in den Hamster-Settings (Menü File / Configuration / Settings), , d.h. Servername + "," + port.
Anmerkung: Sinnvoller ist stattdessen die Verwendung von "HamFetchMail" und "HamSendMail", da mit diesen Befehlen auch die Mailaccounts und Mailfilter von Hamster einbezogen werden können. "HamMailExchange" beherrscht das nicht.
Ausgabe: 0=OK/Started, < oder > 0=Not started (Prozeß wurde nicht begonnen)

HamFetchMail( <server>, <port>, <user>, <pass>, <destuser>, <filter> )
...
HamFetchMail( <server> )
Damit wird eine Befehlsfolge begonnen, die zuerst Mails von einem definierten POP3-Server (<server>, <port>) abruft. Falls <user> / (username / Benutzerbezeichnung) und <pass> (password / Passwort) eingetragen sind, werden sie zur Serveranmeldung verwendet; sind beide leer, wird das für einen Server festgelegte Passwort verwendet.
Außerdem kann auch eines der gespeicherten "allgemeingültigen" Passwörter eingesetzt werden, um eine Klartextangabe im Skript zu vermeiden (<user>="$(number / Nummer), <pass>="")".
Ist ein bestimmter User <destuser> eingetragen, werden abgerufene Mails in dessen Mailbox abgelegt, andernfalls landen sie in der "Admin"-Mailbox.
Wurde die Variable "Filter" ( <filter> ) definiert, so bestimmt sie, auf welchen Teil der Mailfilter (Datei "MailFilt.hst") beim Mailabruf mit dem Befehl "HamFetchMail" zurückgegriffen wird. Standard ist "Nur global gültige Filter", d.h., die "[*]"-Sektion in MailFilt.hst.
Ausgabe: 0=OK/Started (Gestartet), "<" ">"0=Not started (kleiner / grösser 0 bedeutet: Nicht gestartet).
HamFetchMail( "pop3.serv.er", "pop3", "", "", "", "" )
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> )
...
HamSendMail( <server> )
Es wird ein Prozess begonnen, mit dem Mails an einen definierten SMTP-Server versendet werden (<server>, <port>). Falls das <from-select> (*** zur Auswahl einzelner Mails) bestimmt wurde, werden alle versandbereiten Mails übertragen. Falls eine Auswahl getroffen wurde (mittels "Regular expression"), so werden nur die mit einem passenden "Envelope-From" an diesen Server versendet.
Ausgabe: 0=OK/Started (gestartet), < oder >0=Not started (größer oder kleiner 0=nicht gestartet)
HamSendMail( "smtp1.serv.er", "smtp", "john\.doe@serv\.er" )
HamSendMail( "smtp2.serv.er" )

HamRasDial( <name>, <user>, <pass> )
...
HamRasDial( <name> )
Funktion, die die mit <name> bezeichnete DFÜ-Verbindung für die Einwahl verwendet und die Anmeldung am Server mit Usernamen (Benutzernamen) <user> und Passwort <pass> versucht (falls vorhanden).
Falls <user> (Benutzer) und / oder <pass> (Passwort) übergangen werden oder sind sie leer (""), so werden die Einträge in "HamSetLogin" (falls vorhanden) oder die in Hamster gespeicherten Werte zum Aufbau der Verbindung benutzt. Auch diese Funktion kann auf eines der "allgemeingültigen" Passwörter zurückgreifen, um eine Klartextangabe im Skript zu vermeiden (<user>"="$(number), <pass>="").
HINWEIS: Wenn "HamRasDial" verwendet wird, sollte die Verbindung mit "HamRasHangup" beendet werden.
Ausgabe: 0=OK/connected (verbunden); >0=error-code (Ausgabe eines Fehlercodes); -1=RAS not installed (keine DFÜ-Verbindung vorhanden).
$try = 1
while( HamRasDial( "MeineProviderVerbindung","$42" ) != 0 )
    if( $try >= 3 )
        error( "Dialing failed!" ) (Fehler ("Anwahl fehlgeschlagen!")
    endif
    inc( $try )
    sleep( 10000 )
endwhile

HamRasHangup
Beendet eine vorhandene DFÜ-Verbindung.
Ausgabe: 0: OK; <0: error-code (Ausgabe Fehlerhinweis); -1: RAS not installed (keine DFÜ-Verbindung)
HamRasHangup

HamGroupCount
Ruft die Anzahl der von Hamster erhältlichen Newsgroups ab.
Ausgabe: >=0: OK/number of groups (Gruppenanzahl); "<"0: error (Fehler)
# siehe Beispiel bei "HamGroupName"

HamGroupName( <index> )
Besorgt den Namen einer vorhandenen Newsgroup. <index> can be 0 to (HamGroupCount-1).
Ausgabe: String (Zeichenkette)
var( $grpidx )
$grpidx = 0
while( $grpidx < HamGroupCount > )
    print( HamGroupName( $grpidx ) )
    inc( $grpidx )
endwhile

HamGroupIndex( <grpname> )
Besorgt den Indexwert eines vorhandenen Gruppennamens.
Ausgabe: >=0: OK/index-number (Indexzahl); -1: unknown group (unbekannte Gruppe)
print( HamGroupIndex( "hamster.misc" ) )
HamGroupOpen( <grpname> )
Öffnet eine vorhandene Gruppe (*** greift darauf zu) und gibt Daten zurück, die zum Abruf weiterer Informationen in den unten folgenden Funktionen bnötigt werden (diese Daten werden dort als <grphdl> bezeichnet).
Schlägt die Funktion fehl, so ist der ausgegebene Wert negativ ("<0>").
Ausgabe: >=0: OK/group-handle; "<0": error (Fehler)
$grphdl = HamGroupOpen( "hamster.misc" )

HamGroupClose( <grphdl> )
Schließt eine vorher (*** mit HamGroupOpen geöffnete) Gruppe wieder.
Ausgabe: 0
HamGroupClose( $grphdl )

HamArtCount( <grphdl> )
Ruft die Anzahl verfügbarer Artikel in einer Newsgroup ab.
Ausgabe: >=0: OK/count, "<0": error (Fehler)
# siehe Beispiel bei HamArtText

HamArtNoMin( <grphdl> )
Ruft die kleinste verfügbare Artikelnr. ab.
Ausgabe: >=0: OK/count (zähle), "<0": error (Fehler)
# siehe Beispiel bei HamArtText

HamArtNoMax( <grphdl> )
Ruft die größte verfügbare Artikelnr. ab.
Ausgabe: >=0: OK/count (zähle), "<0": error (Fehler)
# siehe Beispiel bei HamArtText

HamArtText( <grphdl>, <artno> )
Ruft den Text ab, der einer vorhandenen Artikelnr. zugeordnet ist. Eine leere Zeichenkette zeigt an, dass der Artikel nicht (mehr) vorhanden ist.
Ausgabe: String (Zeichenkette) (Artikeltext oder "")

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

$grpnam = "hamster.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

HamArtTextExport( <grphdl>, <artno> )
Genau wie "HamArtText", der Text wird zusätzlich in ein Datenformat konvertiert, das exportiert werden kann.
Ausgabe: String (Zeichenkette) (Artikeltext oder "")
$arttxt = HamArtTextExport( $grphdl, $artno )

HamArtImport( <article>, <goverride>, <ignorehist>, <marknoarch> )
...
HamArtImport( <article> )
Importiert einen vorhanden <article> in die Datenbank von Hamster und gibt TRUE (Wahr) aus, falls der Artikel importiert wurde, andernfalls FALSE (Unwahr). <article> enthält den zu importierenden Artikel, inkl. aller Kopfzeilen, den Trennzeichen zwischen Kopf- und Textzeilen und den Artikeltext. Alle Zeilen müssen durch CR+LF (0x0d, 0x0a) getrennt werden (Zeilenumbruch, Sprung zum Zeilenanfang der neuen Zeile).
Falls <goverride> leer ist (Standardeinstellung), wird der Artikel in der / den Newsgroup(s) abgelegt, die in der zugehörigen Kopfzeile "Newsgroup" des Artikels angegeben ist. Sonst wird er in der Gruppe gespeichert, die in <goverride> definiert ist.
Sind keine gültigen lokale Gruppen vorhanden, wird der Artikel in hamster.misc gespeichert.
Hat die Funktion <ignorehist> den Wert TRUE (wahr) ("< > 0"), so erfolgt kein Abgleich der Message-ID des importierten Artikels; er wird importiert, selbst wenn er bereits vorhanden ist. Die Standardvorgabe ist FALSE (unwahr).
Ist <marknoarch> TRUE (wahr) ("< > 0"), wird der importierte Artikel mit "NoArchive=1" in der Kopfzeile "X-Hamster-Info:" angegeben. Dieses Kennzeichen kann dazu verwendet werden, den importierten Artikel als "temporär" darzustellen. Damit kann dieser z.B. von einer geeigneten Archivsoftware übergangen werden. Standardvorgabe ist FALSE (unwahr).
Ausgabe: true/1: OK (wahr/1: OK), false/0: error (unwahr/0: Fehler)
HamArtImport( $article_text, "hamster.misc" )

HamArtDeleteMid( <message-id> )
Findet den durch eine vorhandene <message-id> identifizierten Artikel und löscht ihn in der Artikeldatenbank von Hamster. Die Funktion gibt 0 aus, falls der Artikel gefunden und gelöscht wurde, ansonsten einen von 0 abweichenden Wert.
Ausgabe: =0: Deleted (gelöscht), < >: Message-ID not found/deletion failed (MID nicht gefunden/Löschen misslungen)
HamArtDeleteMid( "<12345.67890@abd.def.ghi>" )

HamArtLocateMid( <message-id>,<grpname>, <artno> )
HamArtLocateMid( <message-id> )
Gibt 0 aus, falls eine vorhandene Message-ID (noch immer) in der Datei "History" gespeichert ist. In diesem Fall werden die Variablen <grpname> und <artno> gesetzt (*** mit einem bestimmten Wert versehen), um auf den Artikel zu verweisen. Ansonsten gibt die Funktion einen Wert abweichend von 0 aus und <grpname> und <artno> bleiben unverändert.
Ausgabe: =0: OK/found (OK / gefunden), < > 0: Message-ID not found (MID nicht auffindbar)
if( HamArtLocateMid( "<12345.67890@abd.def.ghi>", $groupname, $artno ) )
    # ... endif

HamScoreList( <grpname> )
Greift auf eine Liste mit allen Score-Einträgen zu, die beim Abruf von Postings einer bestimmten vorhandenen Gruppe <grpname> Anwendung finden.
Ausgabe: String
ListSetText( $ScoreList, HamScoreList( "group.name" ) )

HamScoreTest( <grpname>, <article>, <matchlog> )
HamScoreTest( <grpname>, <article> )
Gibt den Score-Wert eines bestimmten Artikels <article> aus. Der Test wird unter der Annahme ausgeführt, dass der Artikel von einer bestimmten (vorhandenen) Newsgroup <grpname> abgerufen wurde. Eine Liste aller zutreffenden Score-Zeilen, durch CR/LF getrennt (Zeilenumbruch, Sprung zum nächsten Zeilenanfang) wird als Wert der Variable <matchlog> ausgegeben.
Ausgabe: Integer (score-value)
$ScoreValue = HamScoreTest( "group.name", $Article, $MatchLog )