                         FrexxLink BBS system v0.3

                             by Bjrn Stenberg

                            2:201/328 @ FidoNet


                            Function Reference


==============================================================================
                             FPL Functions
==============================================================================
   FPL contains a number of internal functions that FrexxLink has no doing
   with, such as the strcmp(), the substr(), strstr() and so on. These
   functions are fully described in the FPLUser.doc document.

==============================================================================
                            System Variables
==============================================================================

 NAME
    errno -- standard C error variable

 TYPE
    int

 DESCRIPTION
    Holds the current error code. The possible error codes are:
       0   No error. All is fine.
      -1   The user provided no input to a getstring() or getint() prompt,
           but hit enter right away.
      -2   A file related function failed to locate a requested file.

------------------------------------------------------------------------------

 NAME
    sys_local -- is this a local logon?

 TYPE
    int

 DESCRIPTION
    Contains 1 if the current process is local only, or 0 if the serial
    communication is active.

------------------------------------------------------------------------------

 NAME
    sys_comport -- what com port is in use?

 TYPE
    int

 DESCRIPTION
    Holds the current COMx port, if FrexxLink was started with a COMx port.
    If FrexxLink was started using a handle, this variable contains 0.

------------------------------------------------------------------------------

 NAME
    sys_comhandle -- what com handle is in use?

 TYPE
    int

 DESCRIPTION
    Holds the current com port handle, if FrexxLink was started with a handle.
    If FrexxLink was started using a com port, this variable contains 0.

------------------------------------------------------------------------------

 NAME
    sys_timeleft -- how much time is there left?

 TYPE
    int

 DESCRIPTION
    Holds the number of seconds until the user time is up.

 SEE ALSO
    setusertime()


==============================================================================
                          Programming Functions
==============================================================================

 NAME
    getstring -- Retreive a string from user

 SYNTAX
    string getstring( [ string Prompt ], [ int Display ] );

 DESCRIPTION
    Retrieves a string from the user, allowing primitive command line
    editing using BACKSPACE.

 PARAMETERS
    If Prompt is supplied, it will be printed before the user can enter any
    input.

    If Display is supplied, it controls what will be echoed back from the
    user's keypresses. A value of 0 will inhibit any echoing. A value of
    -1 will echo the actual input characters and any other value will be
    used as the echo eharacter. If the Display parameter is omitted, -1 is
    assumed.

    You cannot supply Display without also supplying Prompt. If you wish
    to alter the display mode without displaying a prompt, use "" for the
    Prompt parameter.

 RETURNS
    The string entered by the user. If the user entered nothing, errno will
    be set to -1.

------------------------------------------------------------------------------

 NAME
    getint -- Retreive an integer from user

 SYNTAX
    int getint( [ string Prompt ], [ int Display ] );

 DESCRIPTION
    Retrieves an integer from the user, allowing primitive command line
    editing using BACKSPACE.

 PARAMETERS
    If Prompt is supplied, it will be printed before the user can enter
    anything.

    If Display is supplied, it controls what will be echoed back from the
    user's keypresses. A value of 0 will inhibit any echoing. A value of
    -1 will echo the actual input characters and any other value will be
    used as the echo eharacter. If the Display parameter is omitted, -1 is
    assumed.

 RETURNS
    The integer entered by the user. If the user entered nothing, errno will
    be set to -1.

------------------------------------------------------------------------------

 NAME
    getchar -- Retreive a character from user

 SYNTAX
    int getchar( [ string Prompt ], [ int Display ] );

 DESCRIPTION
    Retrieves a character from the user.

 PARAMETERS
    If Prompt is supplied, it will be printed before the user can enter
    anything.

    If Display is supplied, it controls what will be echoed back from the
    user's keypresses. A value of 0 will inhibit any echoing. A value of
    -1 will echo the actual input characters and any other value will be
    used as the echo eharacter. If the Display parameter is omitted, -1 is
    assumed.

 RETURNS
    The value of the character pressed by the user.

------------------------------------------------------------------------------

 NAME
    loadstring -- load a text file into a string

 SYNTAX
    string loadstring( string File );

 PARAMETERS
    File must be a fully qualified filename, reachable and readable by the
    current process.

 RETURNS
    The created string. If the file could not be found, the string is set
    to "" and errno is set to -2.

------------------------------------------------------------------------------

 NAME
    savestring -- save a string into a text file

 SYNTAX
    void savestring( string String, string File [, int Mode] );

 PARAMETERS
    String  is the string to be written
    File    must be a fully qualified filename, reachable and writable by the
            current process.
    Mode    is the "write mode", which is:
            0 for normal, nonfiltered writing, which is the default
            1 for "message filter mode", which does two things:
              a) Replaces all LF chars with SPACE (0x20)
              b) Truncates the message at the first occurence of "SEEN-BY: "


------------------------------------------------------------------------------

 NAME
    toupper -- Convert a character to uppercase

 SYNTAX
    int toupper( int Char );

 DESCRIPTION
    Converts a character to uppercase. If Char is not a letter, no change
    will be made. Unlike the standard C equivalence, this function also
    converts 8-bit local characters properly.

 RETURNS
    The value of the converted character.

------------------------------------------------------------------------------

 NAME
    runfile -- Executes an FPL file.

 SYNTAX
    void runfile( string Filename );

 DESCRIPTION
    Executes an FPL file.

 RETURNS
    Nothing

------------------------------------------------------------------------------

 NAME
    printf -- formatted output

 SYNTAX
    void printf( string Format, [ ... ] );

 DESCRIPTION
    printf() produces formatted output. It behaves pretty much exactly like
    the C printf() function, except that floating point numbers aren't
    supported. (This description is not complete, but just explains the
    basic aspects of printf().)

    To take it short, printf() checks the Format string for percent signs
    (%). Everywhere there's a % char, printf will output something special.
    What, and how to output it depends on the characters immediately
    following the %:

    %d   print an integer in base 10
    %s   print a string
    %x   print an integer in base 16 (hexadecimal)
    %%   print a percent sign

    Also, there are some flags and parameters that can be used to define how
    to format the field:

    %5s  print the string to at least 5 characters length. If the string is
         shorter, the output will be padded with space to the left of the
         string. (right justified)
    %-5s same as above, but put the padding spaces to the right of the string.
         (left justified)
    %5d  print an integer to at least 5 characters length, left justified
    %05d print an integer to at least 5 characters length, right justified
         but padded with zeros instead of spaces.

    Example: printf( "%d %s were printed at %02d:%02d\n",5,"dots",10,3)
    will output the string '5 dots were printed at 10:03\n'.

 RETURNS
    1 if a MorePrompt() was answered negatively, i.e the user wants the output
    to stop. 0 in all other cases.

------------------------------------------------------------------------------

 NAME
    lprintf -- local formatted output

 SYNTAX
    void printf( string Format, [ ... ] );

 DESCRIPTION
    lprintf() produces formatted output on the local console only. It works
    just like printf() in all other aspects.

 RETURNS
    Nothing

------------------------------------------------------------------------------

 NAME
    sprintf -- formatted string

 SYNTAX
    string sprintf( string Format, [ ... ] );

 DESCRIPTION
    sprintf() is exactly like printf(), except that it returns the
    resulting string to FPL instead of displaying it on the user screen.

 RETURNS
    The created string

------------------------------------------------------------------------------
 NAME
    setfunc -- set system function

 SYNTAX
    void setfunc( string FuncId, string Code );

 DESCRIPTION
    Defines the action of the predefined system functions

 PARAMETERS
    FuncId is one of the following functions:
       "moreprompt"  When the screen is filled with scrolling text, a "More?
                     (Y/n)" prompt is generally appreciated by the average
                     user. This function defines what that prompt should do.

       "timeleft"    is called once every minute. Use it to keep track of the
                     user's time, warn him when it's running short and to
                     kick him out when time is up etc.

    Code   is a complete FPL statement to execute as the function. It is
           recommended to use a function call here, rather than a complicated
           routine.

    IMPORTANT: All functions called from within these system FPL functions
    must be 'export' declared!

 RETURNS
    Nothing

------------------------------------------------------------------------------

 NAME
    clear -- clear line counter

 SYNTAX
    void clear( [ int ClearScreen ] );

 DESCRIPTION
    In order to know when to execute the more prompt, a line counter is
    maintained internally by FrexxLink. This function clears that counter,
    so that it will take a screenfull of lines to trigger the more prompt
    again.

 PARAMETERS
    If ClearScreen is 1, the screen clear escape code will be sent.

 RETURNS
    Nothing

------------------------------------------------------------------------------

 NAME
    system -- execute external command

 SYNTAX
    int system( string CmdLine );

 DESCRIPTION
    Executes an external command such as an editor, protocol handler etc.

 PARAMETERS
    CmdLine is the command line to be executed.

 RETURNS
    The returncode of the executed command

------------------------------------------------------------------------------

 NAME
    translate -- translate string from one charset to another

 SYNTAX
    string translate( string Str, int FromSet, int ToSet );

 PARAMETERS
    Str     is the string to be translated
    FromSet is the charset to convert from
    ToSet   is the charset to convert to
              1 = CodePage 850
              2 = CodePage 437
              3 = ISO 8859-1
              4 = Swedish ASCII

 RETURNS
    The translated string

------------------------------------------------------------------------------

 NAME
    fappend -- append string to a file

 SYNTAX
    void fappend( string File, string Str );

 DESCRIPTION
    Appends a string to a file. It does not add a newline to the string,
    so if you want one you must include it in the string.

 PARAMETERS
    File    the path+name of the file to modify
    Str     the string to append to the file

 RETURNS
    Nothing

------------------------------------------------------------------------------

 NAME
    fprepend -- prepend string to a file

 SYNTAX
    void fprepend( string File, string Str );

 DESCRIPTION
    Prepends a string to a file. I.e it works just like fappend() only it
    puts the line at the top of the file instead of at the bottom.

 PARAMETERS
    File    the path+name of the file to modify
    Str     the string to append to the file

 RETURNS
    Nothing

------------------------------------------------------------------------------

 NAME
    fexists -- check if a file exists

 SYNTAX
    int fexists( string File );

 PARAMETERS
    File the filename to look for.

 RETURNS
    1 if the file exists. 0 if it doesn't.

------------------------------------------------------------------------------

 NAME
    getenv -- get environment variable

 SYNTAX
    string getenv( string Variable );

 DESCRIPTION
    Obtains an environment variable from the parent shell. (The 'SET'
    variables in an OS/2 CMD session.)

 PARAMETERS
    Variable is the name of the variable to get

 RETURNS
    The value of the variable if it exists, or "" if it doesn't.

------------------------------------------------------------------------------

 NAME
    tokstr -- tokenize string

 SYNTAX
    string tokstr( string Source, int PartNo [, string Delimiters ] );

 DESCRIPTION
    Copies part of the source string, based on the delimiters and PartNo.

 PARAMETERS
    Source      the source string from which to copy the substrings
    PartNo      the ordinal number of the part to copy. The first part is
                number 1.
    Delimiters  a string containing the delimiter chars used in Source to
                separate the parts. The default is ";".

 RETURNS
    The copied string, or "" (null length string) if no part was found.


==============================================================================
                             User Functions
==============================================================================

 NAME
    inituser -- create a new user

 SYNTAX
    void inituser( void );

 DESCRIPTION
    This function clears all internal structures of any previous user and
    sets up the basis for a new user.

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    loaduser -- load a user file from disk

 SYNTAX
    int loaduser( string Username );

 DESCRIPTION
    Loads a user file from the "Users" directory.

 PARAMETERS
    Username is the username (and filename) of the user to load. It is not
    case sensitive.

 RETURNS
    0 if the user was found, or -1 if it wasn't.

------------------------------------------------------------------------------
 NAME
    saveuser -- save a user file to disk

 SYNTAX
    int saveuser( String Username );

 DESCRIPTION
    Saves a user to disk in the "Users" directory.

 PARAMETERS
    Username is the name of the user to save. It is not case sensitive.

 RETURNS
    0 if the user was saved correctly, or -1 if the file could not be created.

------------------------------------------------------------------------------
 NAME
    getuservar -- get user variable

 SYNTAX
    string getuservar( string VarName );

 PARAMETERS
    VarName is the name of the user variable. It is not case sensitive.

 RETURNS
    The string

------------------------------------------------------------------------------
 NAME
    setuservar -- set user variable

 SYNTAX
    void setuservar( string VarName, string Value );

 PARAMETERS
    VarName is the name of the user variable. It is not case sensitive.
    Value   is what the user variable is assigned. Case is preserved.

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    setuserid -- set user id for internal use

 SYNTAX
    void setuserid( string UserId );

 DESCRIPTION
    FrexxLink uses an internal identifier for some things like the message
    map filename. This function sets that identifier. It is recommended that
    you set this to the same as the user name, or you may have problems
    sorting out which user is connected to which id...

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    charset -- set charset conversion

 SYNTAX
    void charset( int UserSet, int DataSet );

 DESCRIPTION
    Internally, FrexxLink handles all text as CodePage 850. In order to
    supply proper charset conversion for things like messages and such,
    it is necessary set the charset used.

 PARAMETER
    UserSet specifies the user's charset.
    DataSet specifies the charset used in the current message area.

 RETURNS
    Nothing

------------------------------------------------------------------------------

 NAME
    screenlen -- get/set user screen length

 SYNTAX
    int screenlen( [ int Lines ] );

 PARAMETERS
    Lines is the number of lines on the user's screen. By supplying this
  PARAMeter, the previous value will be overwritten.

 RETURNS
    The number of lines per screen.

------------------------------------------------------------------------------
 NAME
    setusertime -- set the amount of user time left

 SYNTAX
    void setusertime( int Seconds );

 DESCRIPTION
    This functions sets the amount of time for the current user. Every time
    the minute count "clicks" down, the system FPL function "timeleft" is
    called.

 PARAMETERS
    Seconds is the number of seconds until the user time is up.

 RETURNS
    Nothing

 SEE ALSO
    setfunc(), sys_timeleft



==============================================================================
                         Message Area Functions
==============================================================================

 NAME
    gotomarea -- set current message area

 SYNTAX
    int gotomarea( string Tag, string Path );

 DESCRIPTION
    Sets the internal "cursor" to the specified area. All subsequent message
    functions are applied to this area.

 PARAMETERS
    Tag is the area tag, used in the MsgMap file for marking read messages.
    Path is the path+base filename to the squish data files for this area.

 RETURNS
    -1 if the call failed. 0 otherwise.

------------------------------------------------------------------------------
 NAME
    getmarea -- get information about current message area 

 SYNTAX
    int getmarea( string Id );

 PARAMETERS
    Id  is the information identifier:
       "total"    the total number of messages in the area.
       "unread"   the number of unread messages in the area.
       "highest"  the number of the highest message in the area.

 RETURNS
  SEE above.

------------------------------------------------------------------------------
 NAME
    getmessage -- get a subpart of a message

 SYNTAX
    string getmessage( int MsgNo, string PartId [, int ReplyNo] );

 PARAMETERS
    MsgNo specifies which message to read from.
    PartId specifies which part of the message to fetch:
      "body"     - the message body, truncated below the first occurence of
                   " * Origin: ".
      "from"     - the 'From' field
      "to"       - the 'To'   field
      "subject"  - the 'Subject' field
      "origaddr" - the originating 4D address (Zone:Net/Node.Point)
      "destaddr" - the destination 4D address (Zone:Net/Node.Point)
      "date"     - the creation date of the message (YY-MM-DD HH:MM)
      "replyto"  - the message number this message is a reply to, or 0 if this
                   message isn't a reply
      "control"  - the ^A kludges of the message. Each SOH (0x01) is replaced
                   with a newline character.
      "replies"  - the message number(s) of the replies to this message. This
                   is where the ReplyNo parameter comes in. It specifies which
                   reply to check for, starting with #1. There can be a
                   maximum of 10 replies to every message. This function
                 RETurns "0" if there is no reply with the specified number.
                   Replies are always stored 1->10, so once you find a 0 it's
                   no use checking the rest of the replies.

 RETURNS
  SEE above

------------------------------------------------------------------------------
 NAME
    printmsg -- display message body with quote colouring and word wrapping

 SYNTAX
    void printmsg( string Body, string QuoteCol, string TextCol );

 DESCRIPTION
    FidoNet messages can be somewhat messy to handle, so here's a function that
    does all that neat formatting and colouring stuff for you.
    It replaces all LF (0x0a) characters whith SPACE (0x20) and then outputs
    each paragraph (i.e. lines separated with CR (0x0d)) neatly wrapped.
    All paragraphs having a '>' character in the first 10 characters are
    considered quoted and are thus prefixed with the QuoteCol string.
    All "normal" text paragraphs immediately following a quote are prefixed
    with the TextCol string.

 PARAMETERS
    Body     - The body of a message
    QuoteCol - The escape sequence (or whatever) for the quoted lines colour
    TextCol  - The escape sequence for normal lines

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    nextmsg -- Find next unread message in thread

 SYNTAX
    int nextmsg( int Message );

 DESCRIPTION
    Finds the next unread message.

 PARAMETERS
    If Message is a valid message number, nextmsg() will scan Message's
    thread for an unread reply. If Message is -1, nextmsg() will scan
    for the first unread message in the area.

 RETURNS
    Next unread message number. If the thread is exhausted, nextmsg()
  RETurns -1. If the area is exhausted, nextmsg() returns 0.

------------------------------------------------------------------------------
 NAME
    markmsg -- check read mark for message

 SYNTAX
    int msgmsg( int MsgNo [, int Set ] );

 PARAMETERS
    MsgNo is the number of the message to check
    Set   is an optional flag which changes the value of the mark:
           0 marks the message as unread
           1 marks the message as read
          -1 does not modify the mark (default)

 RETURNS
    0 if the message is marked as unread, otherwise 1.

------------------------------------------------------------------------------
 NAME
    savemsgmap -- store map of read messages

 SYNTAX
    void savemsgmap( void );

 DESCRIPTION
    Stores a map of read messages in the "MsgMap" directory, in a filename
    as set by the setuid() function.

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    createmsg -- clear all internal message structures

 SYNTAX
    void createmsg( void );

 DESCRIPTION
    Clears all stuff internally used for sending messages. Use this before
    putmsg()ing stuff.

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    putmsg -- assign message part value

 SYNTAX
    void putmsg( string PartId, string Value );

 DESCRIPTION
    Adds part of a message to the internal message buffer.

 PARAMETERS
    PartId is the part which is to be assigned:
      "body"     - the message body
      "from"     - the 'From' field
      "to"       - the 'To'   field
      "subject"  - the 'Subject' field
      "origaddr" - the originating 4D address (Zone:Net/Node.Point)
      "destaddr" - the destination 4D address (Zone:Net/Node.Point)
      "control"  - the ^A kludges of the message, with SOH (0x01) characters
                   positioned correctly. FrexxLink does not alter this field
                   in any way before sending it, so it's all up to you!

    Value is the value to set.

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    putmsgflag -- set message flags

 SYNTAX
    void putmsgflag( string FlagId, int Value );

 PARAMETERS
    FlagId is the flag identifier:
      "private",
      "crash",
      "read",
      "sent",
      "file",
      "forward",
      "orphan",
      "kill",
      "local",
      "hold",
      "freq",
      "rreq",
      "receipt",
      "ureq",
      "scanned",
      "uid",
    Value is 0 if the flag is to be cleared, or 1 if the flag should be set.

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    getmsgflag -- get message flags

 SYNTAX
    int getmsgflag( int MsgNo, string FlagId );

 DESCRIPTION
    Checks if a message contains a specific flag.

 PARAMETERS
    MsgNo  is the number of the message to be examined

    FlagId is the flag identifier:
      "private",
      "crash",
      "read",
      "sent",
      "file",
      "forward",
      "orphan",
      "kill",
      "local",
      "hold",
      "freq",
      "rreq",
      "receipt",
      "ureq",
      "scanned",
      "uid",

 RETURNS
    1 if the flag is set. 0 otherwise.


------------------------------------------------------------------------------
 NAME
    sendmsg -- write message to message base

 SYNTAX
    void sendmsg( void );

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    msgid -- create new MSGID

 SYNTAX
    int msgid( void );

 DESCRIPTION
    This function creates a new message ID of the type you are required to put
    into your FidoNet messages. The FTS-09 document specifies that no two
    messages from a system may contain the same MSGID for at least three years.
    I have solved this by counting the time passed since the last 5-year
    shift, in 1/10th of seconds. That means that my counter reset last time
    1995-01-01 00:00 and is increasing constantly at a speed of 864000 clicks
    per day. Even with this speed, the counter will not wrap for about 13
    years, so I think we're on the safe side.

 RETURNS
    The message id.

------------------------------------------------------------------------------
 NAME
    msgmember -- check area membership

 SYNTAX
    int msgmember( [ int Flag ] );

 DESCRIPTION
    FrexxLink supports the concept or area membership. This function controls
    whether the current user (as specified with setuid()) is a member of the
    current area (as specified with gotomarea()) or not.

 PARAMETERS
    Flag is an optional parameter, changing the state of membership:
      0 clears the member flag
      1 sets the member flag
     -1 does not modify the member flag (default)

 RETURNS
    The state of membership for the area.

------------------------------------------------------------------------------
 NAME
    delmsg -- delete a message

 SYNTAX
    void delmsg( int MsgNo );

 DESCRIPTION
    Deletes a message from the message base.

 PARAMETERS
    MsgNo is the number of the message to delete.

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    setmareasize -- define maiximum size of a message area

 SYNTAX
    void setmareasize( int MaxSize );

 DESCRIPTION
    Sets the maximum size of the current message area. The tosser will
    start throwing away old messages when this number is reached.
    You only need to call this function when you wish to modify the maximum
    size of the area.

 PARAMETERS
    MaxSize  is the maximum number of messages in the area.

 RETURNS
    Nothing


==============================================================================
                           File Area Functions
==============================================================================

 NAME
    gotofarea -- set current file area

 SYNTAX
    void gotofarea( string ListPath, string FilePath );

 DESCRIPTION
    Defines the current file area. All subsequent file area functions will use
    this setting

 PARAMETERS
    ListPath is the path and filename to the list file for this area.
    FilePath is the path to where the actual files of this area are stored.

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    filelist -- list files in current file area

 SYNTAX
    int filelist( [ string Type ], [ string Field ], [ string Key ] );

 DESCRIPTION
    Lists files in the current directory, all or a selected few. If searching
    is enabled, this function will output two newlines before the first file
    match is printed.

 PARAMETERS
    If no parameters are supplied, this function will list all files as they
    are listed in the list file, including comments and separator lines.

    Type   controls what kind of searching is to be done. Possible parameters
           are "string" and "date". If Type is set to "date", the Field
	   and Key parameters are not required.

    Field  if "string" is chosen as search type, this field is used to define
           which string field is to be searched for matching text. Setting this
         PARAMeter to "TX" will actually search both the "TX" field and the
	   filename. This parameter is case sensitive.

    Key    is the string to search for in the field specified by Field. It
           is not case sensitive.

 RETURNS
    1 if the user has pressed Ctrl-C. 0 otherwise.

------------------------------------------------------------------------------
 NAME
    newfiles -- search for files newer than a specific date

 SYNTAX
    int newfiles( int Date );

 DESCRIPTION
    Scans current file area looking for files not older than Date. If there
    exists a field 'DA' on a file description line, newscan() uses the date
    specified in that field. Otherwise, newscan() examines the file on the
    disk and obtains the creation date.

 PARAMETERS
    Date   the time in integer format, i.e. seconds from 1970.

 RETURNS
    1 if the user has pressed Ctrl-C. 0 otherwise.

------------------------------------------------------------------------------
 NAME
    typefile -- display a text file onscreen

 SYNTAX
    int typefile( string Filename ); 

 PARAMETERS
    Filename   the path+filename of the file to display.

 RETURNS
    -1 if the file was not found. 0 if all is fine.

------------------------------------------------------------------------------
 NAME
    fileinfo -- get specifics about a disk file

 SYNTAX
    int fileinfo( string Filename, string Field );

 PARAMETERS
    Filename   the path+filename of the file to examine.

    Field      a string describing what information is requested:
        "size"   the size of the file in bytes.
        "time"   the creation time of the file, as an integer.

 RETURNS
    The result examination, or -1 if the file was not found.

------------------------------------------------------------------------------
 NAME
    dszfield -- parse a dszlog type file

 SYNTAX
    string dszfield( string DszLog, int Line, string Field );

 DESCRIPTION
    Many transfer protocols produce a result log in the format defined by
    the DSZ software. This is a convenience function to decipher such a log
    file.

 PARAMETERS
    DszLog	the path+filename of the DSZ-style log file
    Line	the line number to examine. Each file transfered in a batch
                gets a line of its own, so this parameter simply says which
                file in order you wish to examine.

    Field	the information field requested:
           "protocol"   a one character string describing the protocol used
                        in transfer. An upper case character means upload,
                        lower case download.
                        'z' and 'Z' are used for Zmodem.
                        'x' and 'X' are used for Xmodem.
                        'e' and 'E' are used to signal that the transfer was
                        unsuccessful (a fatal error occured).
           "fsize"      the size of the transfered file in bytes
           "dte"	the dte (computer to modem) speed
           "cps"	the achieved transfer speed i bytes per second
           "errors"	the number of non-fatal errors during the transfer
           "stops"	the number of transfer stops occured
           "psize"	the packet size used (for Xmodem and other packet
                        oriented protocols. Zmodem does not use packets).
           "file"	the (path and) name of the file transferred
           "serial"	the serial number of the remote protocol handler

 RETURNS
    The requested field.

   NOTES
    Use the protocol field to check the number of lines. If the protocol is
    "" (zero length string) that means there are no more files in the log.

------------------------------------------------------------------------------
 NAME
    splitpath -- split a path+file string into path and filename

 SYNTAX
    string splitpath( string FullName, string Field );

 DESCRIPTION
    Copies either the path or the filename out of a full path+filename string.
    The algorithm used is to locate the last '\' character in the string and
    consider the filename to begin at the next character. Everything before
    that is the path.

 PARAMETERS
    FullName    the path to be split. ex: "C:\FrexxLink\Top.FPL"
    Field       the part requested:
           "path"   the path, WITHOUT trailing backslash
           "file"   the filename

 RETURNS
    The requested field.

------------------------------------------------------------------------------
 NAME
    clrftags -- clear file tags

 SYNTAX
    void clrftags( void );

 DESCRIPTION
    Clears the internal file tags and resets the tag counter to 1.

 PARAMETERS
    None

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    getftag -- get a file tag

 SYNTAX
    string getftag( int TagNo );

 DESCRIPTION
    The tag list FrexxLink keeps consists of 99 path+file strings,
    containing the last 99 files listed using filelist() and newfiles().
    getftag() copies one of those tag strings.

 PARAMETERS
    TagNo    the number of the tag you wish to get.

 RETURNS
    The tag string, if TagNo is the number of a tag that actually exists.
    Otherwise, an empty string ("") is returned.

 SEE ALSO
    clrftags()

------------------------------------------------------------------------------
 NAME
    getffield -- get file description field

 SYNTAX
    string getffield( string Filename, string Field );

 DESCRIPTION
    Every file description line consists of several file fields. getffield()
  RETurns the value of a field for a specific file.
    The description file used is the one specified with gotofarea().

 PARAMETERS
    Filename  the name of the file whose description contains the field
    Field     the two-character field name to look for, case sensitive

 RETURNS
    The contents of the file field, or "" if no such field exists for the
    specified file.

 SEE ALSO
    gotofarea(), setffield()

------------------------------------------------------------------------------
 NAME
    setffield -- set file description field

 SYNTAX
    void setffield( string Filename, string Field, string Contents );

 DESCRIPTION
    Sets the contents of a file description field. If no such field exists
    for the specified file, it will be created.

 PARAMETERS
    Filename  the name of the file whose field should be set
    Field     the two-character field name to set, case sensitive
    Contents  the new contents of the description field

 RETURNS
    Nothing

 SEE ALSO
    gotofarea(), getffield()

------------------------------------------------------------------------------
 NAME
    fkill -- remove a file description line

 SYNTAX
    void fkill( string Filename );

 DESCRIPTION
    Removes the description line for Filename from the description file.
    The first line encountered describing the specified filename is simply
    removed from the list file. If the list file contains several entries
    for the same filename, only the first one is removed.

 PARAMETERS
    Filename   the name of the file whose description line should be removed

 RETURNS
    Nothing

------------------------------------------------------------------------------
 NAME
    fmove -- move a file description line

 SYNTAX
    void fmove( string Filename, string NewList );

 DESCRIPTION
    Moves the description line for Filename from the current description file
    to the top of another file.

 PARAMETERS
    Filename   the name of the file whose description line should be moved
    NewList    the path+filename of the description file to where the line
               should be moved

 RETURNS
    Nothing


==============================================================================
                             Time Functions
==============================================================================

 NAME
    nowtime -- find out current system time

 SYNTAX
    int nowtime( void );

 DESCRIPTION
    notime() returns the current system time in the number of seconds
    since 1970.

 PARAMETERS
    None

 RETURNS
    The time.

------------------------------------------------------------------------------
 NAME
    timepart -- get part of a time (better description wanted!)

 SYNTAX
    int timepart( int Time, string Field );

 DESCRIPTION
    This function allows you to extract a single part from a time, such
    as the year, the month number or the minute.

 PARAMETERS
    Time    the time to use, in seconds from 1970.
    Field   the time part to return:
        "year"     the year, 1970-
        "month"    the month, 1-12
        "day"      the day of the month, 1-31
        "hour"     the hour, 0-23
        "minute"   the minute, 0-59
        "second"   the second, 0-59      

 RETURNS
    The time part requested.

------------------------------------------------------------------------------
 NAME
    time2str -- convert an integer to a time string

 SYNTAX
    string time2str( int Time );

 DESCRIPTION
    Converts an integer representing the number of seconds from 1970 into
    a string in the format "YYYY-MM-DD,HH:MM:SS"

 PARAMETERS
    Time   the time to convert

 RETURNS
    The time, as a string.

------------------------------------------------------------------------------
 NAME
    str2time -- convert a time string into an integer

 SYNTAX
    int str2time( string Time );

 DESCRIPTION
    Converts a string in the format "YYYY-MM-DD,HH:MM:SS" into an integer
    representing the number of seconds since 1970.
    Actually, the time format is "YYYY.MM.DD.HH.MM.SS" where the '.' chars
    can be any character at all.

 PARAMETERS
    Time   the time string to convert

 RETURNS
    The time, as an integer.


