Hamster-Scripts: Functions (Hamster): News database

News database

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

[www.elbiah.de Hamster Playground Documentation]