Um Hamster automatisiert zu nutzen (OLE), wird ein Automatisierungs-Objekt (Rangbezeichnung " Hamster.App") benötigt.

Beispiele:

Verschiedene Funktionen (.misc-functions):

ControlGetInfo: Zeichenkette
Ruft eine Textzeile ab, in der die Hamsterversion und der -pfad stehen (als Begrüßungstext, z.B. "Hello World")

ControlGetPath: Zeichenkette
Ruft den Verzeichnispfad des momentan registrierten und verwendeten Automations-Servers ab (z.B. Pfad zur zuletzt benutzten Datei "Hamster.exe").

ControlGetVersion: Zeichenkette
Ruft die Hamster-Versionsnr. als Zeichenkette ab (z.B. "1.3.0.16")

ControlSetLogin(Identifier, Benutzername, Paßwort): Zeichenkette
Legt vorübergehend den Benutzernamen und das Passwort für einen vorhandenen "Bezeichner" fest.
Der "Bezeichner" kann eine DFÜ-Verbindung oder ein News-/Mailserver sein.
Vorübergehend heißt hier, dass diese Einstellungen nicht in eine Datei geschrieben werden. Aber sie bleiben im Speicher erhalten, bis Hamster beendet wird.
Wird für den Benutzernamen und/oder das Passwort ein einzelnes Fragezeichen ("?") gesetzt, wird der Hamster diesen Wert abfragen, wenn er benötigt wird. Außerdem kann eines der in "File / Configuration / Password" definierbaren "allgemeingültigen" Passwörter verwendet werden, um eine Angabe im Klartext im Skript zu umgehen, z.B. ControlSetLogin("serv.er", "$1" "").

ControlMessage(Msg, Param: Ganzzahlig): Ganzzahlig
HAM_MSG_HAMSTER_EXIT         = 1
HAM_MSG_RESET_COUNTERS    = 2
HAM_MSG_LOCALNNTP_ONOFF = 3
HAM_MSG_LOCALPOP3_ONOFF = 4
HAM_MSG_LOCALSMTP_ONOFF = 5

Leitet einige Hamster-Funktionen ein, die normalerweise über dessen Menüfelder verfügbar und nutzbar sind.

Rückmelde-Werte:

0    OK; Befehl ausgeführt (command executed).
1    Error; Befehl fehlgeschlagen (command failed).
2    Unbekannte Befehlnr. (Unknown Msg-number).
3    Schwere Schutzverletzung, bitte Neustart (GPF, please reboot) ... ;-)

Funktionen für ausführende Befehle (Task-functions):

ControlIsIdle: Bool´scher Ausdruck
Wird mit TRUE beantwortet, falls momentan keine laufenden Aufgaben wie Purging, Newsabruf, Mailversand etc. vorhanden sind.
Anmerkung: Verbindungen zwischen News-/Mailreader und lokalem Server sind davon nicht berührt (werden nicht als "aktiver Prozeß" angesehen).

ControlWaitIdle(WaitTimeout: Ganzzahlig): Bool´scher Ausdruck
Const HAM_WAITIDLE_INFINITE = 0
Wie "ControlIsIdle" - s.o. - mit dem Unterschied, daß diese Funktion zusätzlich den vorgegebenen Zeitraum von Millisekunden abwartet, falls aktive Prozesse laufen. Falls der Aufruf mit "WaitTimeout=0" erfolgt, erfolgt keine Rückmeldung nach Beendigung der laufenden Prozesse.

Anmerkung: Siehe Erläuterungen zu "Events: evtHamster.IsIdleAgain" um die Vorgaben für die Warteschleife vor weiteren Hamster-Prozessen zu optimieren.
Anmerkung: Verbindungen zwischen Programm(en) und dem lokalen Server zählen nicht als "laufende Prozesse".

ControlThreadCount: Ganzzahlig
Übermittelt die Zahl momentan laufender Prozesse.
Anmerkung: Verbindungen zwischen Programm(en) und dem lokalen Server zählen nicht als "laufende Prozesse".

ControlRunPurge(PurgeOptions: Ganzzahlig): Ganzzahlig

Const HAM_PURGEOPT_DOALL	0xFF
Const HAM_PURGEOPT_DONEWS	0x01
Const HAM_PURGEOPT_DOHISTORY	0x02
Const HAM_PURGEOPT_DOKILLS	0x04
Const HAM_PURGEOPT_DOMHISTORY	0x08

Beginnt einen Purge-Prozess (d.h., das Löschen alter Daten). Der Bit-orientierte Parameter PurgeOptions beschreibt, welches alten Datenmaterial gelöscht werden soll (bit0=1=Artikel, bit1=2=Einträge in der Datei History, Bit2=4=Killfile-Log, Bit3=8=Einträge in der Datei Mail-History).

ControlRunRebuildHistory: Ganzzahlig
Beginnt einen Teilprozeß, der die aktuelle History-Datei löscht (".\Groups\History.dat") und sie wiederherstellt, indem die Message-IDs aller in Hamster gespeicherten Artikel verwendet werden.

Anmerkung: Bei zahlreichen Artikeln kann das einige Zeit in Anspruch nehmen, entsprechend sollte diese Möglichkeit nur genutzt werden, wenn sie wirklich nötig ist! Es empfiehlt sich abzuwarten, bis Hamster wieder den Ruhezustand erreicht hat (z.b. mit ControlWaitIdle), nachdem diese Funktion aufgerufen wurde.

ControlRunMail(ServerList: Zeichenkette): Ganzzahlig
Beginnt einen Teilprozess, der zuerst neue Mails von Mailservern abruft und dann (falls vorhanden) neue Mails verschickt.
Falls "ServerList" leer ist (""), können alle in Hamster eingetragenen POP3- und SMTP-Server verwendet werden. Andernfalls erfolgt eine Beschränkung auf bestimmte Server.

Das Format der "ServerList" ist eine durch Semikolon (";") getrennte Liste von Servernamen. Sie müssen im gleichen Format wie in den Hamster-Einstellungen angegeben werden (also "Servername" + "," + "Portnr."
Beispiel: "mail.aaa.com,pop3;mail.bbb.com,pop3;mail.aaa.com,smtp"

ControlRunFetchMail(Server, Port, User, Pass, DestUser: Zeichenkette): Ganzzahlig
Beginnt einen Teilprozess, der Mails von einem vorhandenen POP3-Server (Server, Port) abruft.

Sind Benutzer und Paßwort gegeben, werden sie zur Anmeldung am Server verwendet; sind die Einträge leer, werden die Passworteinstellungen für den eingetragenen Server benutzt.
Außerdem kann eines der gespeicherten "allgemeingültigen" Passwörter (User="$(number - Nummer)", Pass="") verwendet werden.
Ist ein bestimmter Benutzer ("DestUser") vorhanden, werden abgeholte Mails in dessen Mailbox hinterlegt; ansonsten landen sie in der "Admin"-Mailbox.

ControlRunSendMail(Server, Port, FromSelection: Zeichenkette): Ganzzahlig
Beginnt einen Teilprozess, der Mails an einen bestimmten SMTP-Server (Server, Port) verschickt. Wurde keine Auswahl des Absenders getroffen ("FromSelection"), werden alle versandfertigen Mails verschickt. Andernfalls - Festlegung über einen Regulären Ausdruck - werden nur die mit einem dazu passenden Absender an den Server gesendet.

ControlRunNewsPost(ServerList: Zeichenkette): Gannzahlig
Startet einen Teilprozess, der neue Artikel postet (wenn vorhanden). Ist die Serverliste leer ("") oder nicht angegeben, werden alle NNTP-Server, die in Hamster definiert wurden, abgearbeitet. Ansonsten wird der Transfer von News auf die angegebenen Server beschränkt (vergl. oben - Befehl "ControlRunMail" - für die Details des Serverlisten-Formates).
Hinweis: Ab Hamster Vr. 1.3.19, wurde diese Funktion durch die weiter unten beschriebenen NewsJobs*-Funktionen ersetzt. Sie wird nur noch intern mit den neuen Funktionen simuliert. Um diese inzwischen überflüssige Funktion zu ersetzen, siehe das Beispiel bei "NewsJobStart"

ControlRunNewsPull(ServerList: Zeichenkette): Ganzzahlig
Startet einen Teilprozess, der neue Artikel von Newsservern lädt. Ist die Serverliste leer ("") (oder nicht angegeben), werden alle NNTP-Server, die in Hamster definiert wurden, abgearbeitet. Ansonsten wird der Transfer von News auf die angegebenen Server beschränkt (vergleiche oben - Befehl "ControlRunMail" - für die Details des Serverlisten-Formates).
Hinweis: Ab Hamster Vr. 1.3.19, wurde diese Funktion durch die weiter unten beschriebenen NewsJobs*-Funktionen ersetzt. Sie wird nur noch intern mit den neuen Funktionen simuliert. Um diese inzwischen überflüssige Funktion zu ersetzen, siehe das Beispiel bei "NewsJobStart".

NewsJobsClear: Ganzzahlig
NewsJobsPullDef(ServerList: Zeichenkette): Ganzzahlig
NewsJobsPostDef(ServerList: Zeichenkette): Ganzzahlig
NewsJobsPull(Servername, reGrpSelect: Zeichenkette): Integer
NewsJobsPost(Servername, reGrpSelect, reMsgSelect: Zeichenkette): Ganzzahlig
NewsJobsStart(ServerList: Zeichenkette): Ganzzahlig
Diese Funktionen sind mit denen der Hamsterskriptsprache V. 2 identisch.
Eine weitergehende Beschreibung ist zu finden unter:
HamNewsJobsClear, HamNewsJobsPullDef, HamNewsJobsPostDef, HamNewsJobsPull, HamNewsJobsPost, HamNewsJobsStart.

DFÜ-Funktionen (RAS-functions):

RasDial(ConnectionID, Username, Password): Bool´scher Ausdruck
Hiermit wird eine DFÜ-Verbindung namens "ConnectionID" hergestellt. Benutzernamen und/oder Passwort können weggelassen werden (""). In diesem Fall werden die Einträge bei "ControlSetLogin" (falls vorhanden) oder die in Hamster gespeicherten Werte verwendet, um die Verbindung herzustellen. War die Einwahl erfolgreich (d.h., die Verbindung steht), wird die Rückmeldung TRUE, ansonsten FALSE gesendet. Zu Hinweisen für den Grund der Fehlverbindung: Vgl. unten - Befehl "RasLastError" -.

RasHangup:
Beendet die mit RasDial aufgebaute Verbindung.

RasIsConnected: Bool´scher Ausdruck
Es erfolgt eine Rückmeldung mit TRUE, falls mit RasDial eine Einwahl zustandegekommen ist.

RasLastError: Ganzzahlig
Übermittelt den letzten DFÜ-Fehlercode (insbesondere wenn RasDial FALSE als Rückmeldung sendet).

News-Funktionen (News-functions):

NewsGrpCount: Ganzzahlig
Ruft die Zahl aller in Hamster verfügbaren Newsgroups ab.

NewsGrpName(GrpIdx: Ganzzahlig): Zeichenkette
Ruft den Namen einer vorhandenen Newsgroup ab. GrpIdx kann einen Wert zwischen "0" und (NewsGrpCount-1) sein.

NewsGrpIndex(GrpName: Zeichenkette): Ganzzahlig
Ruft die Index-Nr. eines vorhandenen Gruppennamens auf (-1 bei unbekannten / nicht vorhandenen Gruppen).

NewsGrpOpen(GrpName: Zeichenkette): Ganzzahlig
Öffnet eine vorhandene Gruppe und sendet einen Wert (> 0) zurück, der für den Abruf weiterer Informationen in den unten folgenden Funktionen benötigt wird (er wird dort als "GrpHdl" bezeichnet). Wird die Funktion fehlerhaft ausgeführt, ist der zurückkommende Wert negativ ("<0").

NewsGrpClose(GrpHdl: Ganzzahlig)
Schließt eine vorher geöffnete Gruppe wieder.

NewsArtCount(GrpHdl: Ganzzahlig): Ganzzahlig
Ruft die Zahl der für eine Gruppe vorhandene Artikel ab.

NewsArtNoMax(GrpHdl: Ganzzahlig): Ganzzahlig
Ruft die kleinste verfügbare Artikelnr. ab.

NewsArtNoMin(GrpHdl: Ganzzahlig): Ganzzahlig
Ruft die größte verfügbare Artikelnr. ab.

NewsArtText(GrpHdl, ArtNo: Ganzzahlig): Zeichenkette
Ruft den Text zu einer vorhandenen Artikelnr. ab. Eine leere Zeichenkette zeigt an, daß der Artikel nicht mehr verfügbar ist.

NewsArtTextExport(GrpHdl, ArtNo: Ganzzahlig): Zeichenkette
Genau wie bei "NewsArtText" der Text wurde jedoch in ein exportierbares Datenformat umgewandelt.

NewsScoreListFor(GrpName: Zeichenkette): Zeichenkette
Ruft eine Liste aller Scoring-Einträge ab, die beim Abholen von Postings für die jeweilige Gruppe verwendet werden.

NewsScoreTest(GrpName, ArtText: Zeichenkette; var MatchLog: Zeichenkette): Ganzzahlig
Übermittelt den Scorewert für einen vorhandenen Artikel ("ArtText"). Der Scoringtest erfolgt unter der Annahme, daß der Artikel von der vorhandenen Newsgroup bezogen wurde (GrpName). Eine durch CR/LF (Aufbau wie eine Textdatei) strukturierte Liste aller vom Scoring erfaßten Beiträge wird an (die Funktion, A.d.Ü.) "MatchLog" übergeben.

NewsLocateMID(MessageID: Zeichenkette; var Groupname: Zeichenkette; var ArtNo: Ganzzahlig): Bool´scher Ausdruck
Sendet TRUE zurück, falls eine vorhandene Message-ID (noch) in der Datei "History" aufbewahrt wird. In diesem Fall werden Gruppennamen und Artikelnr. "gesetzt" um auf den betreffenden Artikel zu verweisen.
Andernfalls wird der Ausdruck FALSE zurückgereicht und Gruppennamen und Artikelnr. werden nicht verändert.

NewsLocateMID2(MessageID: Zeichenkette; var Groupname: Variant; var ArtNo: Variant): Bool´scher Ausdruck
Wie im vorherigen Absatz, jedoch mit Variant-Parametern. Bei VBS-Skripten (Windows Script Host) zu verwenden.

NewsDeleteByMID(MessageID: Zeichenkette): Bool´scher Ausdruck
Findet einen durch eine vorhandene Message-ID identifizierten Artikel und löscht ihn in Hamsters Artikelbestand. Der Ausdruck TRUE kommt zurück, wenn der Artikel lokalisiert und gelöscht wurde, andernfalls wird FALSE zurückgesendet.

NewsImport(ArtText, OverrideGroups: Zeichenkette; IgnoreHistory, MarkNoArchive: Bool´scher Ausdruck): Bool´scher Ausdruck
Übermittelt einen vorhandenen Artikel an Hamsters Datenbasis und sendet TRUE zurück, falls der Artikel importiert wurde; ansonsten wird FALSE zurückgesendet.
"ArtText" enthält den zu importierenden Artikel einschließlich aller Kopfzeilen, der Trennzeilen zwischen Kopf- und Textbereich und den Artikelrumpf. Die einzelnen Zeilen müssen durch "CR" + "LF" (0x0d, 0x0a) (Aufbau wie Textdatei, A.d.Ü.) getrennt werden.
Falls "OverrideGroups" leer ist, wird der Artikel in der Gruppe gespeichert, die anhand der "Newsgroup"-Kopfzeile des Artikels bestimmt wurde. Sonst wird er in der Gruppe gespeichert, die durch die Funktion "OverrideGroups" festgelegt wurde. Gibt es keine gültige Gruppe, landet er in der lokalen Gruppe "hamster.misc".
Hat die Funktion "IgnoreHistory" den Wert TRUE, erfolgt kein Abgleich der Message-ID des importierten Artikels mit der Datei "History". Entsprechend wird er importiert, selbst wenn er schon "bekannt" ist.
Hat "MarkNoArchive" den Wert TRUE, wird der importierte Artikel mit "NoArchive=1" in der "X-Hamster-Info:"-Kopfzeile gekennzeichnet. So kann der importierte Artikel z.B. als "vorübergehend" markiert werden um etwa von einer Archivierungssoftware übergangen zu werden (die allerdings noch nicht erhältlich ist). ;-)