ZXNet эхоконференция «zxnet.pc»

Hемедленно нажми на RESET, All!


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 [default address]

Example:

Area NETMAIL c:FidoMailNetMail FN
Area NETMAIL.Z77 c:FidoMailNetMail.z77 FN 77:123/6
Area PK.MADMED c:FidoMailPKMadMed SE
Area PK.SQAFIX c:FidoMailPKSqaFix JE
Area GROUPMAIL c:FidoMailGroupMail SG
Area JUNKMAIL c:FidoMailJunkMail 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
", 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
", 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
", 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 = '
';

Following character escape sequences are supported:

Sequence

Description

a

Bell (alert)



Backspace

f

Form feed




New line




Carriage return



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
";

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
";
str = "Hello, "
"Fidonet "
"world"
"
";

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
", 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
,
, and similar characters with their
escape sequences ("
", "
", 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
, so you might need to use Replace("
", "
")
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!
"
"Please check logs...
"
);

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"

'name'

name

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

\n

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