Fidonet Awk Utility

[This is preliminary documentation and subject to change.]

Updated: September 8, 2000

Overview

FAwk does for Fidonet message bases what good old Unix awk utility does for text files, that is allows processing of the messages according to the C-like scripts. Existing FAwk version supports FTS-001 (aka *.msg), Squish, JAM and Pkt message bases. It is Win32 console application which can be run on Window 9x, Windows NT and Windows 2000 platforms.

With FAwk one can easily create various mail scanners, robots, bouncers, carbon copiers, etc. tailored to your specific needs without chores of real programming. Full set of message, area, string, time and file management functions is available. In addition, you can define custom functions to use in your scripts.

FAwk also supports for RFC822 and MIME messages, POP3/SMTP server access and Fidonet/Internet messages gating.

Future FAwk releases may include:

·         NNTP support to allow Internet news processing.

·         External .DLL support to allow custom functions.

Installation

Unpack the FAwk archive and tweak the configuration file to you needs. Also it's a good idea to check http://www.kvitek.com/fido for the most recent version available. For editing scripts basic knowledge of C language syntax is helpful. Some understanding of general operation of Fidonet is assumed.

Configuration

By default, FAwk reads its configuration from the file FAwk.cfg found in the current directory. Alternate configuration file name can be specified using /C command line switch.

Detailed description of configuration file keywords can be found in sample configuration file FAwk.cfg and is not included in this document.

FAwk allows selective configuration by means of conditional Include keywords: optional Include keyword parameters specify grep-like masks which are checked against command line parameters and the included file is processed only if one of the command line parameters matches any of the specified masks.

Command line

The list of supported command line options is displayed when you run FAwk with /? command line switch. All unrecognized command line options and parameters can be accessed with CmdLineParam function or used in conditional Include keywords. This allows selective configuration using custom command line parameters.

Setting up areas

All areas which can be processed by FAwk are defined by Area keyword or imported from Squish configuration or standard Areas.Bbs files using SquishCfg and AreasBbs keywords respectively.

Each area has the following attributes:

·         Area tag used to identify the area

·         Area type: NetMail, EchoMail, GroupMail and LocalMail. Except for the GroupMail, these attributes have no special meaning for FAwk. GroupMail areas are special in that when the messages are copied into them from another area, the ^aAREA: kludge specifying the original area is automatically added.

·         Base path specifies message base path.

·         Base type specifies message base type. Current FAwk version supports FTS-001 (*.msg), Squish, JAM and Pkt message bases.

·         Default network address. If not specified, primary network address is assumed. Internally it is used to make up the address kludges in FTS-001 areas, but you can also use it in your scripts as the origination address when sending messages.

Following is the Area  keyword syntax:

Area <areatag> <areapath> <areatype> [default address]

Example:

Area NETMAIL      c:\Fido\Mail\NetMail      FN
Area NETMAIL.Z77  c:\Fido\Mail\NetMail.z77  FN       77:123/6
Area PK.MADMED    c:\Fido\Mail\PKMadMed     SE
Area PK.SQAFIX    c:\Fido\Mail\PKSqaFix     JE
Area GROUPMAIL    c:\Fido\Mail\GroupMail    SG
Area JUNKMAIL     c:\Fido\Mail\JunkMail     SL

Setting up scans

Scan's are specified by the Scan keyword and describe FAwk activity when scanning area matching a set of area masks. Following is the Scan keyword syntax:

Scan areamask […] { script statements }

FAwk processes scans in the order they are defined in the configuration file. For every scan, FAwk goes through the list of known areas looking for the ones which match any of the scan's area masks and if match found, opens the area and executes scan's script for every message in the area.

Example:

Scan NETMAIL  {
   if (IsMyMail()) ForwardToMe();
   if (IsOldMail()) MoveToJunk();
}

Scan PK.* SU.* RU.*  {
   if (Match(Text(), "*kvitek", matchNoCase)) ForwardToMe();
}

Exit codes

FAwk returns one of the following exit codes:

·          0 -- normal exit, no errors or warnings.

·          1 -- some warnings reported.

·          2 -- some errors reported.

·         -1 -- fatal error.

Script syntax

FAwk script syntax is a subset of the C programming language syntax. Following is formal syntax definition:

statement:
          expression-statement
          compound-statement
          selection-statement
          iteration-statement
          jump-statement

expression-statement:
          [expression];

compound-statement:
          {[statement-list]}

statement-list:
          statement
          statement-list statement

selection-statement:
          if (expression) statement [else statement]

iteration-statement:
          while (expression) statement
          do statement while(expression);
          for ([init-expr];[cond-expr];[loop-expr]) statement

jump-statement
          break;
          continue;

 

If the break or continue statement is encountered in the script outside of any iteration statement, it is applied to the message scan loop, that is break stops processing messages in the current area and proceeds to the next area, while continue stops processing of the current message and proceeds to the next message.

Variables

FAwk scripts support numeric and string variables. There are no specific means to specify variable type: it's defined by last the assigned value.

Variable names are case sensitive.

Variables and predefined constants share the same name space. This means that you can't have variable with the same name as the predefined constant.

Variables are not explicitly declared and are defined as soon as they're encountered in the script. Initially variables have numeric type and the value of zero.

Variables are subject to scope: variable defined in { } block is visible in it and in all its nested { } blocks. Variable instance is lost as soon as it goes out of scope.

So watch for situations like this:

for (i = 0; i < 10; i++) {
    if (i == 5) str = "Fifth element";
}

StdOut("str=%d\n", str);          ; another instance of str!

In the example above, variable str goes out of scope before it's value is displayed. You can fix the problem by declaring str outside of the for loop statement, like in the following example:

str = "";
for (i = 0; i < 10; i++) {
    if (i == 5) str = "Fifth element";
}

StdOut("str=%d\n", str);

You could also fix the problem by replacing for loop compound statement with the simple statement:

for (i = 0; i < 10; i++)
    if (i == 5) str = "Fifth element";

StdOut("str=%d\n", str);

Constants

FAwk scripts support numeric, character and string constants and set of predefined constants.

Numeric constants

These are integers specified as decimal or hexadecimal values.

Example:

x = 1; y = 12; z = 0x0ff;

Character constants

These are integers specified as ASCII characters, hexadecimal values or character escape sequences.

Example:

ch1 = 'A'; ch2 = '\xFF'; ch3 = '\n';

Following character escape sequences are supported:

Sequence

Description

\a

Bell (alert)

\b

Backspace

\f

Form feed

\n

New line

\r

Carriage return

\t

Horizontal tab

\v

Vertical tab

\\

Backslash

\''

Double quote

\'

Single quote

\?

Question mark

 

String constants

These are strings of ASCII characters or escape sequences enclosed in double quotas.

Example:

str = "Hello, Fidonet world\n";

String constants can be concatenated across the white space. For example, the following string specifications are the same as the one above:

str = "Hello, "    "Fidonet "    "world\n";

str = "Hello, "
      "Fidonet "
      "world"
      "\n";

Predefined constants

Predefined constants look like variables but you can't assign value to them.

Predefined constant names are case sensitive.

Predefined constant share the name spaces with the variables so you can’t have variable with the same name as predefined constant.

Message attribute constants (use with Attr and SetAttr):

Constant

Description

Local

Message was created locally

InTransit

Message is in-transit

Private

Private message

Read

Message was read by addressee

Sent

Message was sent to remote system

KillSent

Message will be deleted when sent

ArchiveSent

Message will be archived when sent

Hold

Message is on hold for pick-up by addressee

Crash

Message is crash

Immediate

Send message now, ignore restrictions

Direct

Send directly to destination

Gate

Send via gateway

FileRequest

Message contains file request

FileAttach

Message contains attached file(s)

TruncFile

Attached files are to be truncated when sent

KillFile

Attached files are to be deleted when sent

ReceiptReq

Return receipt requested

ConfirmReq

Confirmation receipt requested

Orphan

Message destination is unknown

Encrypt

Message text is encrypted

Compress

Message text is compressed

Escaped

Message text is seven bit ASCII

ForcePickup

Force pickup

TypeLocal

Message is for local use only (not for export)

TypeEcho

Message is for conference distribution

TypeNet

Message is direct network mail

Scanned

Message is scanned (squish)

FileUpdateReq

Message contains file update request

AuditRequest

Audit request

NoDisplay

Message may not be displayed to user

Locked

Message is locked, no editing possible

Deleted

Message is deleted

 

File open mode constants (use with OpenFile):

Constant

Description

modeRead

Opens the file for reading only.

modeWrite

Opens the file for writing only.

modeReadWrite

Opens the file for reading and writing.

shareExclusive

Opens the file with exclusive mode, denying other processes both read and write access to the file. Open fails if the file has been opened in any other mode for read or write access, even by the current process.

shareDenyWrite

Opens the file and denies other processes write access to the file. Open fails if the file has been opened in compatibility mode or for write access by any other process.

shareDenyRead

Opens the file and denies other processes read access to the file. Open fails if the file has been opened in compatibility mode or for read access by any other process.

shareDenyNone

Opens the file without denying other processes read or write access to the file. Open fails if the file has been opened in compatibility mode by any other process.

modeNoInherit

Prevents the file from being inherited by child processes.

modeCreate

Create a new file. If the file exists already, it is truncated to 0 length.

modeNoTruncate

Combine this value with modeCreate. If the file being created already exists, it is not truncated to 0 length. Thus the file is guaranteed to open, either as a newly created file or as an existing file. This might be useful, for example, when opening a settings file that may or may not exist already.

typeText

Sets text mode with special processing for carriage return–linefeed pairs.

typeBinary

Sets binary mode.

 

File positioning constants (use with SeekFile):

Constant

Description

seekBegin

Seek from beginning of the file.

seekCurrent

Seek from current position.

seekEnd

Seek from end of the file.

 

File attribute constants (use with Get/SetFileAttr):

Constant

Description

fileArchive

The file or directory is an archive file or directory

fileCompressed

The file or directory is compressed

fileDirectory

Specifies directory

fileEncrypted

The file or directory is encrypted

fileHidden

The file or directory is hidden

fileNormal

The file or directory has no other attributes set. This attribute is valid only if used alone.

fileOffline

The data of the file is not immediately available

fileReadOnly

The file or directory is read-only

fileReparsePoint

The file has an associated reparse point

fileSparseFile

The file is a sparse file

fileSystem

The file or directory is part of, or is used exclusively by, the operating system

fileTemporary

The file is being used for temporary storage

 

Log level constants (use with Log):

Constant

Description

logError

Log errors only.

logWarning

Log warnings and above.

logAction

Log actions and above.

logDetail

Log action details and above.

logDebug

Log function results, execution trace, etc.

 

Pattern match constants (use with Match):

Constant

Description

matchNoCase

No case sensitive match.

matchCase

Case sensitive match.

 

Nodelist info constants (use with GetNodeInfo):

Constant

Description

nodeLine

Return entire nodelist line for the given node

nodeStatus

Return node status (Zone, Region, Hub, Point, etc.)

nodeSystem

Return system name

nodePlace

Return system location

nodeSysop

Return sysop name

nodePhone

Return phone number

nodeFlags

Return node flags

 

Gating constants (use with RfcToFtn and FtnToRfc):

Constant

Description

gateMinInfo

Gate minimum info

gateMaxInfo

Gate maximum info

gateNoFileAtt

Don't gate file attachments

gateAddVia

Add FAwk via kludge

 

Miscellaneous constants:

Constant

Description

NULL

equals to 0

FALSE

equals to 0

TRUE

equals to 1

 

Functions

FAwk supports large set of predefined functions as well as user defined functions.

Predefined functions

Most of these functions are trivial, and more detailed information on some of them can be found in the subsequent chapters. Also, demonstration of many predefined functions can be found in FAwkDemo.cfg.

To get better understanding of area and message related functions you can download Fidonet Mail Access toolkit at http://www.kvitek.com/fido and read its documentation.

Those of you who are familiar with Microsoft Visual C++ and Win32 programming will no doubt recognize that most of string functions come from MFC's CString class, while many file oriented functions have direct Win32 counterparts, so feel free to use appropriate documentation if you have access to it.

Area functions:

Function

Description

Area()

Returns area name

AreaType()

Returns area type (NetMail, EchoMail, GroupMail, LocalMail)

AreaAddr()

Returns area default network address

BaseType()

Returns area message base type (Fts,JAM,Squish,Pkt)

BasePath()

Returns area message base path

BasePathExt()

Returns area message base path extension

cMsg()

Returns number of messages in an area

SetLastReadMsg()

Set last read message unique id for the given user id

GetLastReadMsg()

Get last read message unique id for the given user id

SetNextMsg(umsg)

Set next message unique id to process in the Scan loop

 

Message functions:

Function

Description

FromName()

Returns message From name

FromAddr()

Returns message From address

ToName()

Returns message To name

ToAddr()

Returns message To address

Subj()

Returns message subject

Text()

Returns message text

Attr()

Returns message attributes as number

AttrString()

Returns message attributes as string

TimeWritten()

Returns time when message has been written

TimeReceived()

Returns time when message has been received

TimeProcessed()

Returns time when message has been processed

Kludge(kludge,n)

Returns n'th instance of the specified kludge.

If no kludge specified (""), returns n'th kludge in a message

iMsg()

Returns message index

nMsg()

Returns message number

uMsg()

Returns message unique identifier

SetFromName(s)

Sets message From name

SetFromAddr(s)

Sets message From address

SetToName(s)

Sets message To name

SetToAddr(s)

Sets message To address

SetSubj(s)

Sets message subject

SetText(s)

Sets message text

SetAttr(attr)

Sets message attributes as number

SetTimeWritten(t)

Sets time when message has been written

SetTimeReceived

Sets time when message has been received

SetTimeProcessed

Sets time when message has been processed

DelKludge(kl,n)

Deletes n'th instance of the specified kludge.

If no kludge specified (""), deletes n'th kludge in a message

AddKludge(kludge)

Adds specified kludge

AddEomKludge(kl)

Adds specified end-of-message kludge

CopyMsg(area)

Copies message to specified area

MoveMsg(area)

Moves message to specified area

DeleteMsg()

Deletes message

SaveMsg()

Saves message

SendMsg(...)

Sends message, parameters are: (area,from,to,subj,attr,text)

 

String functions:

Function

Description

GetAt(s,n)

Returns the character at a given position

SetAt(s,n,c)

Sets a character at a given position.

GetLength(s)

Returns the number of characters in a string.

Upper(s)

Converts all the characters in string to uppercase characters.

Lower(s)

Converts all the characters in string to lowercase characters.

Mid(s,n,count)

Extracts the middle part of a string.

Left(s,count)

Extracts the left part of a string.

Right(s,count)

Extracts the right part of a string.

Replace(s,s1,s2)

Replaces indicated substring with other substring.

Remove(s,ch)

Removes all instances of a given character from a string.

Insert(s,n,s1)

Inserts a substring at the given index within the string.

Delete(s,n,count)

Deletes characters at the given position from a string.

Find(s,s1,start)

Finds substring inside a string starting at given position.

FindReverse(s,ch)

Finds last occurrence of the character in the given string

Match(s,pat,case)

Performs pattern match within the string

Expand(s)

Replaces @xx@ fields in string with values of @xx@ variables

Format(fmt,...)

Formats string using printf-like format specification

Dec(str)

Converts decimal string to a numeric value

Hex(str)

Converts hexadecimal string to a numeric value

AnsiToOem(str)

Converts Ansi string to Oem

OemToAnsi(str)

Converts Oem string to Ansi

Crc32(str,crc)

Calculates CRC32 of the specified string

 

File functions:

Function

Description

StdOut(fmt,...)

Writes printf-like formatted string to standard output

StdErr(fmt,...)

Writes printf-like formatted string to error output

Log(lvl,fmt,...)

Writes printf-like formatted string to log file

OpenFile(fn,mode)

Opens specified file in a given mode

CloseFile(file)

Closes file

SeekFile(f,of,fm)

Seeks file to the specified position

GetFileSize(f)

Returns file size in bytes

SetFileSize(f,cb)

Sets file size (shrinks or expands the file)

IsEndOfFile(f)

Checks for end-of-file condition

ReadLine(file)

Reads a line from the file

WriteLine(file,s)

Writes a line to the file

CopyFile(fn,fn1)

Copies an existing file to a new file

MoveFile(fn,fn1)

Moves an existing file or a directory.

DeleteFile(fn)

Deletes an existing file

FileExists(fn)

Checks file existence

EnumFiles(mask)

Enumerates files given file name mask

GetFileAttr(fn)

Returns file attributes

SetFileAttr(fn,a)

Sets file attributes

CreateDir(dir)

Creates specified directory

RemoveDir(dir)

Removes specified directory

 

System functions:

Function

Description

GetEnv(var)

Returns specified environment variable

System(cmd)

Executes specified command

Sleep(millisec)

Suspends the execution for a specified interval

LocalTime()

Returns current local time

UTCOffset()

Returns current UTC offset in hours

FormatTime(fmt,t)

Formats time using strftime-like formatting

GetLastError()

Returns last system error

FormatError(e)

Formats system error message given system error number

 

SMTP functions:

Function

Description

GetSmtpHost

Returns SMTP host address

GetSmtpUser

Returns SMTP user name

OpenSmtp

Opens session on SMTP host

CloseSmtp

Closes session on SMTP host

SendSmtpMsg

Sends message to SMTP host

 

POP3 functions:

Function

Description

GetPop3Host

Returns POP3 host address

GetPop3User

Returns POP3 user name

OpenPop3

Opens session on POP3 host

ClosePop3

Closes session on POP3 host

GetPop3MsgCount

Returns POP3 message count

GetPop3MsgUid

Returns POP3 message unique identifier

GetPop3Msg

Returns POP3 message

DelPop3Msg

Deletes POP3 message

 

RFC message functions:

Function

Description

RfcFrom

Returns message From field

RfcTo

Returns message To field

RfcCc

Returns message Cc field

RfcBcc

Returns message Bcc field

RfcSubj

Returns message Subject field

RfcDate

Returns message Date field

RfcMessageId

Returns message Message-ID field

RfcReplyTo

Returns message Reply-To field

RfcReturnPath

Returns message Return-Path field

RfcText

Returns message text

RfcFile

Returns message file attachments

RfcGetField

Returns message field given its index

RfcGetTime

Returns message time converted from Date field

RfcGetUTCOffset

Returns message UTC offset converted from Date field

RfcGetName

Returns name given Internet address specification

RfcGetAddr

Returns address given Internet address specification

RfcAddField

Adds specified message field

RfcDelField

Deletes specified message field

CreateRfcMsg

Creates new message given components

 

Gating functions:

Function

Description

RfcToFtn

Converts Internet message to Fidonet message

FtnToRfc

Converts Fidonet message to Internet message

 

Miscellaneous functions:

Function

Description

FAwk()

Returns FAwk name and version string

SystemAddr()

Returns system address as specified in configuration file

SystemName()

Returns system name as specified in configuration file

SysopName()

Returns sysop name as specified in configuration file

CfgKey(key)

Checks if specified keyword is present in the config file

CfgKeyParam(kn)

Returns n'th parameter of specified keyword in the config file

CmdLineParam(prm)

Returns command line parameter matching specified mask.

CheckAddr(addr)

Checks if specified network address exists in the nodelist

GetNodeInfo(a,n)

Returns nodelist info for the given network address

Dump(var)

Dumps specified variable. If no variable specified (""), dumps

all variables visible in the current context.

 

User defined functions

FAwk supports user defined functions declared with the Function keyword in the configuration file.

User defined functions are global. This means that they are available in any script context.

User defined function names are case sensitive.

User defined function names share the same name space as the predefined functions. This means that you can't have user defined function with the same name as the predefined one.

User defined function parameters and variables have local scope. This means that they are not visible outside the function definition.

User defined function result is assigned to a variable with the same name as the function name. This also defines the type of function result.

Example:

Function MyFunc(param1, param2) {
       StdOut("MyFunc: %d %d\n", param1, param2);
       MyFunc = param1 + param2;
}

File FAwkFunc.cfg contains some commonly used user defined functions.

Log(logLevel, …)

Before writing formatted string to the log file, this function replaces all instances of \r, \n, and similar characters with their escape sequences ("\r", "\n", etc.) and appends a plain newline characters to the end of string so that log file integrity is a maintained automatically.

If this function is called with logWarning or logError logging level, it updates the FAwk's exit code to 1 or 2 respectively, unless current exit code is higher.

Expand(str)

This function expands the fields in the given string with the values of the variables with the same names as the field names. The field is any number of non-space characters surrounded with @@. To specify the @ character in the text, double it.

If variable which specifies field value is of numeric type it is converted to equivalent string representation automatically.

This function is helpful when you need to generate a  piece of text based on the template. Automatically generated notification messages, reports, etc. are typical applications.

Example:

@FromName@ = FromName();   @FromAddr@ = FromAddr();
@ToName@ = ToName();   @ToAddr@ = ToAddr();
@Subj@ = Subj();
@ReplyText@ = "Get the hell out of there!";

template = LoadFile("ReplyTemplate.txt");
text = Expand(template);


File ReplyTemplate.txt may contain something like this:

In reply to message from @FromName@ at @FromAddr@ to
@ToName@ at @ToAddr@ regarding "@Subj@", we have to say
the following:
@ReplyText@

Format(fmt,…) format specification

Format specification has the following form:

%[flags] [width] [.precision] type

Each field of the format specification is a single character or a number signifying a particular format option. The simplest format specification contains only the percent sign and a type character (for example, %s). If a percent sign is followed by a character that has no meaning as a format field, the character is copied to resulting string. For example, to print a percent-sign character, use %%.

The optional fields, which appear before the type character, control other aspects of the formatting, as follows:

type

Required character that determines whether the associated argument is interpreted as a character, a string, or a number.

Type

Description

c

Specifies a character.

d

Signed decimal integer.

I

Signed decimal integer.

o

Unsigned octal integer.

u

Unsigned decimal integer.

x

Unsigned hexadecimal integer, using “abcdef.”

X

Unsigned hexadecimal integer, using “ABCDEF.”

s

Specifies a string.

 

flags

Optional character or characters that control justification of output and printing of signs, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag can appear in a format specification.

Flag

Description

Left align the result within the given field width.

+

Prefix the output value with a sign (+ or –) if the output value is of a signed type.

0

If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and – appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) the 0 is ignored.

blank

Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear.

#

When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively.

Ignored when used with c, d, i, u, or s.

 

width

The second optional field of the format specification is the width specification. The width argument is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values — depending on whether the – flag (for left alignment) is specified — until the minimum width is reached. If width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned numbers).

The width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if width is not given, all characters of the value are printed (subject to the precision specification).

If the width specification is an asterisk (*), an integer argument from the argument list supplies the value. The width argument must precede the value being formatted in the argument list. A nonexistent or small field width does not cause the truncation of a field; if the result of a conversion is wider than the field width, the field expands to contain the conversion result.

precision

The third optional field of the format specification is the precision specification. It specifies a nonnegative decimal integer, preceded by a period (.), which specifies the number of characters to be printed, the number of decimal places, or the number of significant digits. Unlike the width specification, the precision specification can cause truncation of the output value. If precision is specified as 0 and the value to be converted is 0, the result is no characters output.

If the precision specification is an asterisk (*), an integer argument from the argument list supplies the value. The precision argument must precede the value being formatted in the argument list.

The type determines the interpretation of precision and the default when precision is omitted, as shown in the following table.

Type

Description

c

The precision has no effect.

d, i, u, o, x, X

The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision.

s

The precision specifies the maximum number of characters to be printed. Characters in excess of precision are not printed.

 

FormatTime(fmt,…) format specification

Format specification consists of one or more formatting codes; the formatting codes are preceded by a percent sign (%). Characters that do not begin with % are copied unchanged to resulting string. The formatting codes are listed below:

 

Format code

Description

%a

Abbreviated weekday name

%A

Full weekday name

%b

Abbreviated month name

%B

Full month name

%c

Date and time representation appropriate for locale

%d

Day of month as decimal number (01 – 31)

%H

Hour in 24-hour format (00 – 23)

%I

Hour in 12-hour format (01 – 12)

%j

Day of year as decimal number (001 – 366)

%m

Month as decimal number (01 – 12)

%M

Minute as decimal number (00 – 59)

%p

Current locale’s A.M./P.M. indicator for 12-hour clock

%S

Second as decimal number (00 – 59)

%U

Week of year as decimal number, with Sunday as first day of week (00 – 53)

%w

Weekday as decimal number (0 – 6; Sunday is 0)

%W

Week of year as decimal number, with Monday as first day of week (00 – 53)

%x

Date representation for current locale

%X

Time representation for current locale

%y

Year without century, as decimal number (00 – 99)

%Y

Year with century, as decimal number

%z, %Z

Time-zone name or abbreviation; no characters if time zone is unknown

%%

Percent sign

 

As in the Format function, the # flag may prefix any formatting code. In that case, the meaning of the format code is changed as follows.

Format code

Description

%#a, %#A, %#b, %#B, %#p, %#X, %#z, %#Z, %#%

# flag is ignored

%#c

Long date and time representation, appropriate for current locale. For example: “Tuesday, March 14, 1995, 12:41:29”

%#x

Long date representation, appropriate to current locale. For example: “Tuesday, March 14, 1995”.

%#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y

Remove leading zeros (if any).

 

FormatTime function output is locale dependant. By default, FAwk uses US English locale, but you can force it to switch to the system default locale by specifying the UseSystemDefaultLocale keyword in the configuration file.

SendMsg()

This function has the following parameters:

SendMsg(Area, From, To, Subj, Attr, Text)

Parameters are:

Area

Specifies an area to send the message to. This could be any area tag defined in the Area keywords.

From

Specifies message sender name and origination address. The name goes before address and must be separated from the address with at least one space. If the name is not specified, default name Sysop is assumed. Address may be followed by the domain specification.

To

Specifies message receiver name and destination address. The syntax is the same as for the From parameter.

Subj

Specifies message subject. Most systems limit size of the message subject to 72 characters.

Attr

Specifies message attributes. Note that most systems require Local attribute to be set for the locally sent netmail messages to be processed.

Text

Specifies message text. According to FTS-001 standard, message lines are separated with \r, so you might need to use Replace("\n", "\r") function if you read message text from the text file.

Example:

SendMsg("NETMAIL",
        SysopName() + " " + SystemAddr(),
        "Pete Kvitek 2:5020/6.1@fidonet",
        "FAwk notification",
        Local | Private | KillSent,
        "Hi there!\r"
        "Please check logs...\r"
       );

GetLastReadMsg(uid)

This function returns last read unique message id for the specified user id or 0 if none exists. The result of this function can be passed to SetNextMsg in order to control number of messages to scan.

Note: for JAM bases which require user name in addition to user id, FAwk always assumes user name "FAwk".

SetLastReadMsg(uid, umsg)

This function sets last read unique message id for the specified user id.

Note: for JAM bases which require user name in addition to user id, FAwk always assumes user name "FAwk".

SetNextMsg(umsg)

This function sets unique message if of the next message to process in the Scan loop. If there is no message with specified unique message id, this function returns 0.

To prevent endless scan loops, if this function is used within the scan block, it fails if specified unique message id is less than the current message unique id.

Normally you use this function in conjunction with Get/SetLastReadMsg functions to prevent scanning of already processed messages. Example:

Scan *

Begin {
       ; Get the last read message unique message id and
       ; start scanning from the next message if any

       umsg = GetLastReadMsg(uid = 1);
       if (!SetNextMsg(umsg + 1)) break;
}

{
       ; Process messages...

       ; Set last read message unique message id to the
       ; very last message scanned in the message base
      
       if (iMsg() == cMsg() - 1) SetLastReadMsg(uid, uMsg());
}

CreateRfcMsg()

This function creates Internet message.

CreateRfcMsg(From, To, Subject, Text, Files)

Parameters are:

From

Specifies From name and address in one the following formats:

   "name" <address>
   'name' <address>
   name <address>
   address

To

Specifies To name and address. Format is the same as for the From parameter. Multiple To addresses should be separated by ';' character.

Subject

Specifies message subject. Empty string "" specifies no message subject.

Text

Specifies message text. Empty string "" specifies no message text.

Files

Specifies files to attach to the message. Multiple files should be separated by ';' character. Empty string "" specifies no attached files.

Return value is Internet message handle which can be used in subsequent calls to RfcXXX and SendSmtpMsg functions.

RfcToFtn()

This function converts Internet message to Fidonet message.

RfcToFtn(Msg, Area, Flags)

Parameters are:

Msg

Internet message handle returned by CreateRfcMsg or GetPop3Msg functions.

Area

Fidonet area name to store the converted message to.

Flags

Specifies OR'ed gating flags:

Gating flag

Description

gateMinInfo

Suppress gating of most Internet message fields

gateMaxInfo

Gate all Internet message fields

gateNoFileAtt

Suppress gating of attached files

gateAddVia

add FAwk Via kludge to the gated message

FtnToRfc()

This function converts Fidonet message to Internet message.

FtnToRfc(Flags)

Parameters are:

Flags

Specifies OR'ed gating flags:

Gating flag

Description

gateMinInfo

Suppress gating of most Fidonet message kludges

gateMaxInfo

Gate all Fidonet message kludges

gateNoFileAtt

Suppress gating of attached files

gateAddVia

add FAwk Via kludge to the gated message

 

Return value is Internet message handle which can be used in subsequent calls to RfcXXX and SendSmtpMsg functions.

Miscellaneous

Grep-like masks and patterns

FAwk's grep-like masks and Match function use a subset of grep-like regular expressions, the following symbols are treated specially:

Symbol

Description

?

match any character

*

match zero or more characters

\

literally match the next character

[aeiu0-9]

match a,e,i,u and 0 thru 9

[^aeiu0-9]

match anything but a,e,i,u and 0 thru 9

 

License

This software is provided as is, in no case Pete Kvitek or any of Pete Kvitek's companies, may be held responsible for any damages it can produce, directly or indirectly. If it breaks your keyboard apart, you own both parts.

COMMERCIAL distribution and/or use of this program and the supplied materials is PROHIBITED without written permission of Pete Kvitek.

You are a COMMERCIAL user if you make a profit from running your FidoNet(tm) system, or if it is being run by (or for) a corporation, government, company, foundation, or any other organization.

NONCOMMERCIAL distribution is permitted under the following terms:

·         You may copy and distribute this program and supplied materials in an UNMODIFIED form only. You may charge a distribution fee for the physical act of transferring a copy, but no more than necessary to recover your actual transfer costs.

·         You may not incorporate all or any part of this program and supplied materials into a package which is not completely free for all noncommercial users and without prior written permission of Pete Kvitek.

·         The privileges to use are granted only to NONCOMMERCIAL users, which are running FAwk as a private individuals with no sponsors, and only if their FidoNet(tm) systems are not making (or helping to make) a profit.

Credits

FAwk uses Fidonet Mail Access toolkit by Pete Kvitek, available with full source code under GPL license at http://www.kvitek.com/fido.

JAM(mbp) - Copyright 1993 Joaquim Homrighausen, Andrew Milner, Mats Birch, Mats Wallin. ALL RIGHTS RESERVED.

Squish message base. Copyright 1989,1995 by Lanius Corporation.
All rights reserved.

Distribution

Latest FAwk version is available at:

freq: FAWK 2:5020/6@fidonet
http://www.kvitek.com/fido

If you have questions or comments, please contact:

mail: pete@kvitek.com
Fido: Pete Kvitek@2:5020/6