  		   itraX, REXX library of FTN functions
                   ------------------------------------
                        (c) Igor Shvyrkov,
                        Fidonet: 2:5020/410
                        E-Mail: iazh@freemail.org.mk

		   Itrax's home page: www.chat.ru/~itrax
		   
------------------------------------------------------------------------
DISCLAIMER: this product is provided `as is' so I disclaim everything.
------------------------------------------------------------------------


Table of contents
------------------
1.     Introduction
2.     Why use itraX if there's Itrack out there?
3.     Functions
3.1    General purpose keywords
3.1.1  TEMPLATEPATH <path-name>
3.1.2  LOGFILE <filename>
3.1.3  MAINADDRESS <address> <domain>
3.1.4  CHAT ON|OFF
3.1.5  FLAGDIR <path-name>
3.1.6  DEBUG <n>
3.1.7  IGNOREBSY <ON|OFF>
3.1.8  TOUCHECHOMAIL <YES|NO>
3.1.9  USEREGEXP <YES|NO>
3.1.10 $INCLUDE <filename>
3.1.11 COMPRESSFILE <filename>
3.1.12 RxIgnoreCase <ON|OFF>
3.1.13 LogInclude (LogExclude) <pattern>
3.1.14 TIMESTAMPPATH <path-name>

3.2    DATA <datatype> <blockname>
3.2.1  DATA NODELIST <blockname>  
3.2.2  DATA ADDRESS <blockname>
3.2.3  DATA READDRESSLIST <blockname> 
3.2.4  DATA ROUTING <blockname> 
3.2.5  DATA NAME <blockname>  
3.2.6  DATA PASSWORDNAME <blockname> 
3.2.7  DATA PASSWORDADDRESS <blockname>  
3.2.8  DATA ADDRESSNAME <blockname>   
3.2.9  DATA MESSAGEAGE <blockname> 
3.2.10 DATA SYSTEM <blockname> 
3.2.11 DATA ATTRIBUTE <blockname>  
3.2.12 DATA TEXTSTRING <blockname> 
3.2.13 DATA SUBJECT <blockname>  
3.2.14 DATA FILES <blockname>
3.2.15 DATA FILEAGE <blockname>
3.2.16 DATA PATH <blockname>
3.2.17 DATA MESSAGELENGTH <blockname>
3.2.18 DATA DAYOFWEEK <blockname>
3.2.19 DATA DATE <blockname>
3.2.20 DATA VERSION9 <blockname>
3.2.21 DATA KLUDGE  <blockname>
3.2.22 DATA PKTLENGTH <blockname>
3.2.23 DATA ADDRESSPACKER <blockname>
3.2.24 DATA ECHONAME <blockname>
3.2.25 DATA PROCESSAGE <blockname>

3.3    Area definition keywords
3.3.1  FIDOAREA   <path> <area-name> [<system>] [ECHOMAIL]
3.3.2  SQUISHAREA <path> <area-name> [<system>] [ECHOMAIL]
3.3.3  BINKAREA   <path> <area-name> [<system>] [<password] ...
                 ...[NOMAINZONE] [MULTIDOMAIN] [BRAKEOUTBOUND]
3.3.4  TEXTAREA   <path> <area-name> 
3.3.5  PKTAREA    <path> <area-name> [<system>] [<password] ...
                  ...[<pktlength] [ECHOMAIL] [B-BOX|T-BOX]
3.3.6  JAMAREA <path> <area-name> [<system>] [ECHOMAIL]

3.4    Basic message area functions
3.4.1  SCAN  ( [<areaname>] )
3.4.2  DOBINKOUTBOUND ( <areaname> )
3.4.3  SETROUTING ( <routing> )
3.4.4  SETFLAVOUR ( [<flavors>] )
3.4.5  DOBRAKEOUTBOUND ( <areaname> )

3.5    Functions to work with files
3.5.1  CREATEFILE <fspec|blockname>
3.5.2  KILLFILE <fspec|blockname>


3.6    Selection functions
3.6.1  SELECT[TO]|[FROM] <data>

3.7    Message access functions
3.7.1  READMSG ()
3.7.2  REWIND ()
3.7.3  GETTEXT (<stem_name>)
3.7.4  GETKLUDGES (<stem_name>)
3.7.5  GETVIAS (<stem_name>)
3.7.6  GETHDR (<stem_name>)
3.7.7  GETTO ()
3.7.8  GETFROM ()
3.7.9  GETSUBJECT ()
3.7.10 GETTIME ()
3.7.11 GETROUTING ()
3.7.12 GETATTRIBUTE ()
3.7.13 SETATTRIBUTE (<attr>|<block_name>)
3.7.14 KILL ()
3.7.15 MOVE       ( <areaname> , "-t ...", "-f ..." , ... )
3.7.16 COPYAREA   ( <areaname> , "-t ...", "-f ..." , ... )
3.7.17 BOUNCE     ( "-h ..." "-a ..." , ... )
3.7.18 CREATEMAIL ( "[areaname]" , "@ <addr> [<name>] | block_name" , ...
		   ... "-t ...", "-f ..." , ... )
3.7.19 CHANGEMAIL ( "-t ...", "-f ..." , ... )
3.7.20 CHANGEFROM ( <@address addr | @readdresslist a1 a2 > | <block_name> )
3.7.21 CHANGETO   ( <@address addr | @readdresslist a1 a2 > | <block_name> )
3.7.22 DELETELINE ( [-n] line_no | [-s] [~+@]<string>|<block_name> )
3.7.23 ADDLINE    ( <expandable string>[.] , [linenumber] )
3.7.24 ADDHEADER  ( <template> , [linenumber] )
3.7.25 ADDINTL () 
3.7.26 SETMESSAGETIME (<ftsc_date|seadog_date>)   
3.7.27 CHECKPATH ( <@path pathname1 pathname2> | <path_block_name>)
3.7.28 KILLKLUDGE ( [~!] <@kludge ...> | <block_name> )
3.7.29 SUBSTTEXT  ( [~+] <old_susbtr> , <new_substr> | <block_name> )


3.8    Packing/unpacking functions
3.8.1  UNPACK  (<@path in> | <block_name> [, @path out] | <block_name>)
3.8.2  PACKPKT (<pktarea> , <target_area> , [<AddressPacker>] ,[NOMOVE])


3.9    Miscellaneous functions
3.9.1  LOG (<expandable string>)
3.9.2  WRITESTRING (<filename> , [<expandable string>[.]])
3.9.3  GETUPLINK (<address>)
3.9.4  GETCRC ()
3.9.5  ISBUSY (<bink_area_name>, <address>)
3.9.6  IGNOREBSY (ON|OFF)
3.9.7  ROUTETO (<address>|<block_name>)
3.9.8  ACTIVENODELIST ([+|-]<ndl_tag>)
3.9.9  EXPANDMACRO (<string>)
3.9.10 RENUMBER (<areaname>)
3.9.11 RXSEARCH (<haystack> , [~]<needle>)
3.9.12 GETECHONAME ()
3.9.13 GETAREALIST ()
3.9.14 NDLREBUILD ([<block_name>])
3.9.15 SETFBOXPATH ([path_name])
3.9.16 SETGLOBALVAR (var_name, value)
3.9.17 UNSETGLOBALVAR (var_name)
3.9.18 GETGLOBALVAR (var_name)
3.9.19 GETNODELISTRECORD (<stem_name>, <max>, <address>, [<nodelist block>])
3.9.20 REREADCONFIG ([config_name])
3.9.21 GETNODELISTBLOCK (<stem_name>, [<nodelist block>])
3.9.22 GETMSG (<stem_name>)
3.9.23 GETRAWMSG (<stem_name>)
3.9.24 ZAPTEXT ()

3.10   Alternative configuration functions
3.10.1 DEFKEYWORD(<keyword>, <data>)
3.10.2 DEFDATABLOCK(<block_type>, <stem_name>)

3.11   PKT access functions
3.11.1 READPKT ()
3.11.2 COPYPKT (<area>)
3.11.3 MOVEPKT (<area>)
3.11.4 KILLPKT ()
3.11.5 GETPKTHDR (<stem_name)
3.11.6 SETPKTHDR (<stem_name)


4.     Credits and acknowledgements

APPENDIXES


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

1.  Introduction
------------------

ItraX is a REXX library of FTN functions based on the concept
found in a popular Itrack program.



2. Why use itraX if there's Itrack out there?
----------------------------------------------

Actually, lots of reasons. The most important one is the ability
to write and use REXX scripts. It's well known that at times
Itrack appears to be rather difficult to tame mostly owing to the fact
that it uses its own scripting language, which is, in my opinion,
rather inconvenient and only vaguely resembles a conventional
programming language (well, correct me, but it seems that even a simple
loop can only be implemented there in a rather back-assward way).

REXX, on the contrary, can be regarded as a general purpose scripting
language, which is quite easy to learn, even for those having very
little programming skills.

In other words, this project is an attempt to combine Itrack's power
and REXX's versatility to produce an FTN software having virtually
unlimited capabilities.

Since the initial version, the code has been substantially changed and
extended, so at present itraX is quite different from its "forefather"
offering a few new features, including full support of most popular message
bases, such as JAM and Squish, partial support of echomail handling,
support of The Brake! and T-Mail fileboxes, long bink-style outbound
(originally implemented in The Brake! mailer), built-in arcmail- and pkt-
saw, regular expression support, support of VERSION9 nodelist index
format, unlimited read/write access to every component of an FTN
message, and other enhancements and improvements over the original
Itrack concept based on such native REXX mechanisms, as stems and
shared variable pool.


		     3. Functions

Because  some 'core' functions (and, what is more important, the
concept behind DATA blocks) are based on their Itrack counterparts,
it's highly recommended to first read the Itrack documentation.

3.1    General purpose keywords
---------------------------------------
3.1.1  TEMPLATEPATH <Path-Name>

Sets the directory where to search for template files. If not found,
and by default, the current working directory is tried instead.


3.1.2  LOGFILE <filename>

Sets a log file name. The default is itraX.log


3.1.3  MAINADDRESS <address> <domain>

The mandatory parameter. Defines the main address of this system, which
will be used as a default value in various address substitutions (such
as in vias, etc.), if AKA is not set for the area being processed.

Unlike Itrack, the <domain> part is also mandatory.



3.1.4  CHAT ON|OFF

Defines whether to print output information to screen (such as the current
area name, message numbers, etc.). The default is ON.


3.1.5  FLAGDIR <path-name>

Sets the directory where to search for files defined in DATA FILES
block with `#' prefixed to the filename (see 3.2.14 for details).


3.1.6  DEBUG <n>

Sets the debug level (0 or higher). Levels higher than 1 render
the output rather noisy and only recommended for debugging purposes.

The default level is 0, which means no logging whatsoever, except
for headers/footers.

It is also possible to define compulsory include/exclude patterns,
which, when found, will be included/excluded regardless of the current
debug level. (See LogInclude/LogExclude for details).


3.1.7  IGNOREBSY <ON|OFF>

Turns *.bsy checking ON/OFF. If ON, the busy semaphore in the outbound
directory will be ignored, which means that new mails can be added to
?OUT/?LO files for the systems with which the session is currently in
progress. If OFF (which is the default and preferable value), the busy
system will be skipped.


3.1.8  TOUCHECHOMAIL <YES|NO>

During the scan of an area, if itraX finds "fresh" messages (i.e. not seen
on this system), it timestamps them, putting our Via at the end.
But when scanning an area with mixed netmail/echomail messages (such as
incoming *.pkt files), it's normally desirable to leave echomail
messages intact. Setting TOUCHECHOMAIL to NO prevents itraX from adding
its Via to echomail messages. (The alternative would be to configure
the whole area as ECHOMAIL -- see 3.3 for details --  but this
behavior is not always desirable, either).

The default is YES, which means that all unseen messages will be
touched.


3.1.9   USEREGEXP <YES|NO>

Turns regular expression support (see APPENDIX B) on/off.
The default is NO.



3.1.10  $INCLUDE <filename>

Includes an additional configuration file. (Beware of the endless
recursion).

          
3.1.11  COMPRESSFILE <filename>

Sets the name of the archiver definition file.
There are no default values nor for the filename neither for the
archiver definitions. So if arcmail support is desired, you have
to prepare and define this file in the configuration.
The sample configuration file is of the same format as found in Squish
echomail processor and is included (slightly modified) in the itraX
distribution as `compress.cfg'.


3.1.12  RxIgnoreCase <ON|OFF>

If ON, case will be ignored in regular expression search.
The default is OFF, which means that regex search is case sensitive.


3.1.13  LogInclude (LogExclude) <pattern>

Sets the substring pattern which will be included in / excluded from
logging as needed regardless of the current debug value setting.
Of the two, LogExclude has a higher priority, so if both are defined the
inclusion patterns will be checked first. Multiple patterns can be set
for either keyword.

Note: to prevent a considerable slow down, it's recommended that
LogInclude patterns be defined as a string, NOT regular expression.
This can be achieved by temporarily setting USEREGEXP to NO
before LogInclude, then to YES again.

To include leading/trailing spaces in the template, enclose them
in single or double quotes.

Example:

  LogInclude Opening
  LogInclude warning

  LogExclude *   ; keep silence, output just headers/footers
                 ; (in this particular case UseRegExp is on, 
                 ;  which is ok for LogExclude)


3.1.14  TIMESTAMPPATH <path-name>

Sets the directory where to keep files with internal lastread
information for each area. (See SCAN for details) 



3.2     DATA <datatype> <blockname>
------------------------------------


3.2.1  DATA NODELIST <blockname>  

          <Ext> [Zone] <Path> [Nodelist1 ... ]
          ...
	  
       #END# DATA
       

Defines the block of nodelist sets, one set per line.
(Pointlists are NOT supported!!!)

Using of this datablock is deprecated (see below).

Ext  - index filename extension for this nodelist set
Zone - the default zone
Path - nodelist directory path
Nodelist1 ...  - nodelist names

Note:
	
   If a basename or wildcarded name (like name.* or name.???)
   is specified, the matched files will be those with  a three
   digit extension. If more than one match is found, the newest file
   will be picked.


As stated above, the using of this data type is deprecated in favor of
the newer, faster, and better one -- DATA VERSION9 (see 3.2.20)

Unlike the data structure used in DATA NODELIST, VERSION9 
relies on the index file only and no direct access to the actual nodelist
file is required. So using VERSION9 means a considerable gain in
speed.

It is only feasible to use DATA NODELIST when direct access to
nodelist fields is actually what you need, i.e. to obtain sysop's
name, system's name, etc. (see  3.9.21 for details).

Besides, address mask `#' at the position of net/node number
(to match independent nodes in zones/regions) is only supported
for DATA VERSION9 (I forgot why ;).


3.2.2  DATA ADDRESS <blockname>

          <Fido-Address>
          ...
       #END# DATA

Sets the address list, one per line. 

Example:
          
   DATA ADDRESS Links
      2:5020/381
      2:5020/294
   #END# DATA


Examples of the using of a special address mask `#' at different
positions in the address template:

   DATA ADDRESS Addr
          
            2:5020/999.#       ; all nodes of hub segment 999
            2:#/*              ; all independent nodes of zone 2
                               ; (the node position is ignored) 
            *:50/#             ; all independent nodes of region 50
                               ; in any zone
            2:50/#             ; the same as above, for zone 2
                               ; (the point position is ignored) 
   #END# DATA


Note:

  The address mask at the position of net/node number (to match independent
  nodes in zones/regions) only supported for VERSION9 nodelist blocks.


3.2.3  DATA READDRESSLIST <blockname>

          <address 1> <address 2>
          ...
	  
       #END# DATA

Defines the set of address pairs, one pair per line, to modify
From/To fields of the message. The first value of the pair is the
search pattern, while the other is the substitution address.


Example:
        
     DATA READDRESSLIST ReAddr
	  
         2:5020/999 2:5020/666
	    
     #END# DATA

Meaning: If the address 2:5020/999 is found,
         it will be substituted for 2:5020/666        


3.2.4  DATA ROUTING <blockname> 

         [flavors] <destination> [<target 1> [<target 2> [...]]]
         ....
	 
       #end# DATA
         
Defines the routing rules.


Example:
        
    DATA ROUTING Route
    
         Hold 2:5020/381     2:5020/999.* 2:5020/666.*
	 
    #END# DATA
        

Meaning:
         All mail with the recipient's address  which matches patterns
	 `999.*' or `666.*' will be routed to /381 with the Hold flavor.
	 (The final ?UT flavor also depends on message attributes).


flavors  - attribute list used to set message flavor. `!' means that
           the corresponding attribute mask will be reset.

In the address mask, in addition to `*', `#' is also supported
at the following positions:

- at the net number in <target> address to match the whole region
- at the point number in <target> address to select from hub segment
- at the node number in <dest> address to do hubrouting

In all other cases `#' == `*'.


Some examples:

Example:  Hold 2:5020/#       2:5020/666.*  2:5020/999.*
Meaning:  All mail for nodes 666 and 999 will be routed to their hubs.

Example:  Hold 2:5020/999       2:5020/666.#
Meaning:  All mail for nodes 666 and 999 will be routed to 2:5020/999.


Example:  Crash 2:50/999     2:50/#.*
Meaning:  All mail for all nodes and points of region 50 will be routed to
          2:5020/999.


Notes:
          Hub matching will be done in accordance with the order
	  in which nodelists have been defined in the configuration
          file. Search will be made in ALL defined nodelist blocks.

	  If the point number is omitted in the address mask, the
          point 0 is assumed, i.e. only nodes will be matched, and no points.
          If you bear in mind `all nodes and points', you must put `*' at the
          point position.
	  


So long as it is possible (and even preferable) to define multiple
routing rules within a single routing block, the comparison within
the block is made line by line from top to bottom until the first match
is found. That's why you should define stricter rules first,
putting `catch all' patterns at the end.


3.2.5  DATA NAME <blockname> 

         <name>
         ...
	 
       #END# DATA


Sets the list of usernames, one per line. 	 


3.2.6  DATA PASSWORDNAME <blockname> 

         <password> <name>
         ...
	 
       #END# DATA

3.2.7  DATA PASSWORDADDRESS <blockname> 

         <password> <addr>
         ...
	 
       #END# DATA

These two data blocks are used to automatically fill out the password
field of the header when new pkt/?out is created.


3.2.8  DATA ADDRESSNAME <blockname> 

          <address> <name>
          ...
	  
       #END# DATA

Sets address/name pairs, one per line.

Example:
        
   DATA ADDRESSNAME MyName
        
            2:5020/410   Igor Shvyrkov
            2:5020/410.1 Igor Shvyrkov
            
   #END# DATA
        

    
3.2.9  DATA MESSAGEAGE <blockname> 

           [DAYS][:MINS]  [<Nodenumber>]
           ...
	   
       #END# DATA

Sets the message age in days in optionally in minutes.
If selection is made on this block type, only OLDER messages will match.
Optionally, an address mask can also be set. If not set, it defaults to any
address.

 Example:
        
    DATA MESSAGEAGE OldMustDie
        
            30 2:5020/410
            
    #END# DATA
        
Meaning: Matches all messages from or to /410 which are older than 30 days.


3.2.10  DATA SYSTEM <blockname> 

          <address> <domain> <zonelist>
          ...
	  
        #END# DATA

Used for netmail areas as the SYSTEM parameter for AKA matching
depending on the recipient's address.

Example:
            
   DATA SYSTEM System
        
        2:5020/410.1        fidonet 1 2 3 4 5 6 7 
        2:5020/549.410      fidonet 1 2 3 4 5 6 7  
        999:999/999.999     ninenet 999            

   #END# DATA


Unlike Itrack, beginning from version 1.43 AKA matching is made for the
whole address, not for zone only. So you can specify all your
AKAs for the given zone.

If AKA matching fails, MAINADDRESS will be used.


3.2.11  DATA ATTRIBUTE <blockname> 

          <attribute's>
           ...
	   
        #END# DATA
         
Sets the attribute list. Both multiple lines and multiple entries per
line are allowed. When making selection on this block type, all entries
for each line will be ANDed, while the lines themselves will be ORed.
`!' means NOT (inversion comparison will be made).


Example:
            
    DATA ATTRIBUTE BadAttr
                
          Imm Crash !Private
          Loop
          !Intl
                
    #END# DATA
            
Meaning: matches the message which has:

	Imm, Crash set AND Private NOT set
	OR
	Loop set
	OR
	Intl NOT set
         

The full list of supported attributes (an excerpt from ITRACK.DOC):


Normal message attributes :

PRIVATE       Mail is private

CRASH         Mail is crash

RECEIVED      Mail is received

SENT          Mail is sent

FILE          Mail is a file-attach

INTRANSIT     Mail is in-transit

ORPHAN        Mail is orphan (normally set by external programs)

KILLSENT      Mail is kill/sent

LOCAL         Mail is local

HOLD          Mail is hold

RES1          Reserved Flag

REQUEST       Mail is a file-request

RRQ           Mail is a return-receipt-request

ISRR          Mail is an answer to a return-receipt-request

AUDIT         Mail is an audit-request

UPDATE        Mail is an file-update-request



Extended Attributes in flags Kludge

DIR           Mail is direct

IMM           Mail is immediate

XMA           Mail is Xmail (to be compressed)

CFM           Confirmation Request

ZON           ZoneGate

KFS           Kill File Sent

TFS           Truncate File Sent

FPU           Force Poll ??

HUB           Hub Routing wanted ??

K/S           The version of killsent in the ^AFLAGS Kludge

IT1           ITRACK 1 ( you may use these as you want )

IT2           ITRACK 2 ( but please in rare conditions )

IT3           ITRACK 3 ( only local )

LOK           Locked  this Message should not be sent.ITRACK  now
              handles   locked   Messages   the   same   as   any
              other  Message but in Fidostyle locked Message  are
              Readonly.


Extra:

NPD           


Internally  used attributes. Those attributes are not written  in
any  way to the message, and used only for internal purpose while
processing the message.

NULL          Mail  isn't  containing text, only  kludges  and/or
              tearlines.

LOOP          This mail contains an ITRACK vialine of this system
              in front of others via's

LOOP2         This  mail  contains two ITRACK  vialines  of  this
              system in front of others via's

LOOP3         This  mail contains three ITRACK vialines  of  this
              system in front of others via's

SEEN          This mail contains an ITRACK vialine

LASTVIA       The last vialine is by ITRACK of this System

INVALIDVIAS   If set all Via-Kludges will be invalidated.

INVKLUDGES    If  set  all  Kludges except Msgid, Pid,  Vias  and
              addressing Kludges will be invalidated.

ECHOMAIL      An  "AREA:" statement was found at the beginning of
              the first non-kludge line.

ROUTEDECHO    An "^AAREA:" kludge was found before the first non-
              kludge line.

USER1         Use it as you want :-))

USER2         Use it as you want :-))

USER3         Use it as you want :-))

INTL          Intl  Line was found or Addintl executed. If  reset
              no Intl Line is written to the new message. If only
              the  INTL Attribute is set maybe no Intl Line  will
              be written because the internally hold Intl-Address
              is   perhaps   not  valid,  for  that  ADDINTL   is
              preferred.

INTERZONE     This  flag  will  be  set when, while  reading  the
              message, ITRACK determines that the message will go
              in  another  zone as the origin zone. It  does  not
              depend on whether the message is Zonegate addressed
              or not.

CHANGED       A  scanned Message will only be written to disk  if
              the CHANGED Attribute is set. The CHANGED Attribute
              will be set if a operation changes the contents  of
              a  message.  The first change to a message  is  the
              detection  that  the  last  Vialine  was  no  local
              ITRACKvialine.  And for that the  changed  Flag  is
              set. If you don't want a message to be rewritten by
              ITRACK set reset the changed flag.

IGNOREATTACH  If a mail is written with this attribute
              to  a  BINKAREA  only the mail is  written  in  the
              respective OUT file, but no entry in the  FLO  file
              made.  If you remove this attribute before  killing
              or  moving the mail, the entry in the FLO file will
              be  remove, otherwise the entry remains in the  FLO
              file for later creating a dummy message.
              
The following attribute was added in itraX:


ZALOOP        Triggers a loop under the following condition:
              A mail is routed to a system or has the To: address 
              of a system already found in the Via list immediately
	      following our address. This means that we have already
              sent this message to that system in the past.
              
	      This algorithm has first been implemented in Unimail
	      and is different from the Itrack loop detection
              algorithms (LOOP, LOOP2, LOOP3) in sense that the latter
	      only take into consideration this system address found
	      in Via kludges, which only indicates how many times this
	      mail has been seen on this system, regardless of where
	      it has been received from or where it is going to be
              routed to, which is, in some circumstances (such as
              dynamic re-routing) can trigger a false alarm.



3.2.12   DATA TEXTSTRING <blockname>
            <arbitrary_string>
	    ...
         #END# DATA

Sets (sub)string patterns, one per line, to be selected on message body
text. To include leading/trailing spaces, enclose the pattern in single or
double quotes.

Example:

    DATA TEXTSTRING Str
    
       blahblah
       " blablah "
       
    #END# DATA


3.2.13   DATA SUBJECT <blockname>
             <subject_string>
	     ...
         #END# DATA

Sets one or more subject string patterns, one per line.
To include leading/trailing spaces, enclose the pattern in single or
double quotes.



3.2.14   DATA FILES <blockname>

          [#]<dir> [!]fname1 [!]fname2 ...
           ...
         #END# DATA
         
Set the file list, also known as semaphore set. For matching rules see
DATA ATTRIBUTE (3.2.11). Optionally, file name can be prefixed with `#'.
This means that file name will be set relative to FLAGDIR
directory path (see FLAGDIR). If there is a directory name followed by
`#' (no spaces is allowed!) this directory has precedence over FLAGDIR.
Otherwise, the file name is considered absolute.

Example:

    FLAGDIR .\flags
    
    DATA FILES
        # a b
    #END# DATA
    
Meaning:  Fully qualified file names will be .\flags\a  .\flags\b

Example:
    DATA FILES
       #c:\fd\inbound  .*\.[A-z][A-z][0-9]
    #END# FILES

Meaning: Any files in the directory `c:\fd\inbound', with a three-symbol
         extension, the first two of which are letters, and the last one
         is a digit.

Note that this block type is to be used with selection functions only,
and is not meant for KillFile or CreateFile, where the direct names
are expected.


3.2.15  DATA FILEAGE <blockname>

          [DAYS][:MINS]  [#]  fname1  fname2 ...
            ...
        #END# DATA

Select returns true (1), if a file from one of the filename sets is
older than DAYS + MINUTES. `#' restricts the search to the current
directory.


3.2.16  DATA PATH <blockname>

          <path>
          ...
	  
        #END# DATA

Sets the pathname list, a path per line, used by CHECKPATH (see 3.7.27)
to adjust filename specification found in the subject line for file attaches.

Attention: to avoid ambiguity, the full path is expected!


3.2.17   DATA MESSAGELENGTH <blockname>

           <length> [<Nodenumber>]
           ...
	   
         #END# DATA
         
Sets the message size in bytes. Select() will return true for all
messages bigger than <length>. An optional address mask can be
specified, which defaults to any address. When doing relaxed matching
(~), only the address mask will be taken into consideration (if
defined), while the size will be ignored.


3.2.18  DATA DAYOFWEEK <blockname>

           [SUN][MON][TUE][WED][THU][FRI][SAT]
           ...
	  
        #END# DATA

Sets the list of weekdays. Select() for this type will return true if
one of the set values corresponds to the current weekday.


3.2.19  DATA DATE <blockname>

          <day>.<month>.<year> [dayofweek list]
          ...
	  
        #END# DATA


Sets a date template. Any of the three positions can accept wildcards (*),
which means `any' (day, month, or year respectively). All positions
must be filled. An optional weekday can be defined. In this case,
Select() will return true if one of the date positions matches AND the
weekday corresponds to the current date, too. By default, only the date
is taken into account, assuming `any weekday'.

Example:
  
   DATA DATE d

     21.05.97
     22.5.97
     13.*.97 Fri

   #end# DATA


Meaning: Select() will return true, if today is one of the following:
         May 21, 1997,  May 22, 1997, or it's Friday 13th of
	 any month in 1997.


Note: By date we mean a calendar date, not the message date.
So, unlike most of other data types, calling Select() for this type
does not require ReadMsg() to have been previously executed.


3.2.20  DATA VERSION9 <blockname>

          <Ext> [Zone Region] <Path> [Nodelist1 ... ]
         ...
	 
        #END# DATA

Defines one or more nodelist sets for fast nodelist access based
on `Version 9 Nodelist Index'. (Pointlists are NOT supported!!!)
                     

Ext  -   index filename extension for this nodelist set

Zone   - the default zone
Region - the default region (not network!)
         (if Zone has been set, you also MUST to specify Region!)
	 Zone/Region definition is only makes sense for separate
	 network nodelist segments, for instance net5020.*
Path   - nodelist directory pathname
Nodelist1 ...  - nodelist names


Nodelist name pickup rules are similar to those explained in DATA NODELIST
item (see 3.2.1).


3.2.21  DATA KLUDGE  <blockname>

          <kludge_string>
          ...
	 
        #END# DATA

Sets the list of kludges, used in such functions as SELECT and
KILLKLUDGE (see 3.7.28). Only the name must be specified, without the leading
kludge control character ( ascii (1) ).


3.2.22  DATA PKTLENGTH <blockname>

          <len> <addressmask>
          ...
	  
        #END# DATA

Sets the maximum pkt file size for the given address mask. Used in
conjunction with PKTAREA (see 3.3.5). By default, the size is defined
in bytes. Optionally, you can specify K for kilobytes, or M for mbytes.

Examples:

      PKTAREA <path> <areaname> PktLen
      ...

      DATA PKTLENGTH PktLen

        100000  2:5020/410.*
        200k    2:5020/*.*
        1M      *:*/*.*

      #END# DATA


3.2.23   DATA ADDRESSPACKER <blockname>

           <addr_mask>  <packer_ID>|-  <len>|-  [<flags> ...] 
           ...
         #END# DATA

This type is used as an argument  for PACKPKT (see 3.8.2).
         
addr_mask       - address mask

packer_ID       - archiver name, as defined in the archiver file
		  (see COMPRESS). The dash (`-') instead of the packer name
		  indicates that unpacked mail will be attached for
                  this address.
                  
len             - maximum bundle size for the given address (known as saw).
                  if 0 or the dash is specified, then pkt-saw will be off
                  for that address.

 flags       	- BinkArea attributes.  Sets the ?LO flavor.
		  It's also possible to redefine Kfs/Tfs for the 
		  the file attach specification in ?LO. (The default is
		  Tfs (#) for arcmail, and Kfs (^) for pkt, which can
		  be reset/modified using `!', etc.)
		  If no flags specified, the default flavor will be
                  used which is FLO.

Example:

    DATA ADDRESSPACKER Apack

      2:5020/381     -   -    CRASH 
      2:5020/999    RAR 2M    
      2:5020/*.*    ZIP 500k  HOLD
      
    #END# DATA
                  


3.2.24   DATA ECHONAME <blockname>
            <echoname>
            ....
         #END# DATA


Sets the echomail area name list, one entry per line. Select() for this type
will return true if the current message is echomail, i.e. it has
the first non-kludge line starting from `AREA:' pattern.

Has the same functionality as GetEchoName (see 3.9.12),
but is more convenient when making selection on several area names.



3.2.25    DATA PROCESSAGE <blockname>

Same as DATA MESSAGEAGE (see 3.2.9) but is used to check the age of a message
based on the timestamp in the via line set when the message was processed on
this system (lastvia time). If the message has never been timestamped
on this system, select() on this block will always return false.



3.3    Area definition keywords
------------------------------------------------

3.3.1           FIDOAREA   <path> <area-name> [<system>] [ECHOMAIL]

    path      - directory path name

    area-name - area name

    system    - optional DATA SYSTEM block name (see DATA SYSTEM)

    Echomail  - whether this is an echomail area

                If so, then when creating/copying/moving
		mails across various areas the netmail-specific
                kludges, namely INTL, DOMAIN, FMPT, TOPT, and Via
                will be omitted from the original message and won't be
                included in a newly created message. Besides, all
                attributes are cleared, and the Local attribute is set.
                You can always redefine attributes as needed using -a
                key for the corresponding copying/moving function
		(see below).
		

3.3.2           SQUISHAREA <path> <area-name> [<system>] [ECHOMAIL]

Same as FIDOAREA. <path> = path + squish area base name (w/o extension)



3.3.3           BINKAREA   

    <path> <area-name> [<system>] [<password] [NOMAINZONE] [MULTIDOMAIN]

    In addition to the previously explained arguments, it has the
    following ones:
    
    <password>  - DATA PASSWORD block name (for automatical password
                  setting in ?UT files) 
      
    NOMAINZONE  - If given, binkstyle outbound directory extension will be set
                  to the zone number for all zones, including the
                  primary zone taken from DATA SYSTEM or MAINADDRESS.
                  Otherwise, the outbound directory for the primary
                  zone has no extension.

                  
    MULTIDOMAIN - Domain outbound: useful for members of several FTN networks:
                  outbound ?UT packets will be created in a directory
		  named after the domain of the network to which the
                  the address belongs, relative to the outbound base
                  directory. The domain is taken for SYSTEM or MAINADDRESS.
                  
                  Example:
    
                  Data System System
                      255:1/1    255 DrovNet
                  #END# Data
    
                  BinkArea \Outbound  OUT System Multidomain
    
                  After executing DoBinkOutbound()
                  packet to 255:2/2 with Crash flavor will go to
                  to the following file name:
    
                  \Outbound\DrovNet.0ff\00020002.cut

  BRAKEOUTBOUND - If defined, outbound file naming will be in the long
                  binkstyle outbound format, as found in The Brake! mailer.

         	  The long bink style outbound has the following format:
                  
                  Domain.Zone.Net.Node.Point.Flavor.{List|Mail|Busy}
                  
                  where:
		  
                       Flavor = {Immediate|Crash|Direct|Hold|Normal}
                       Mail corresponds to .?ut
                       List corresponds to .?lo
                       Busy corresponds to .bsy semaphore

		  For the address in the previous example,
		  after executing DoBinkOutbound(), the following
		  file will be created:

                  \OutBound\DrovNet.255.2.2.0.Crash.Mail


3.3.4           TEXTAREA   <path-name> <area-name>

Defines a text area. The area is write only, i.e. no scanning is
possible. The message body is written to the file called <path-name>.
Headers and kludges are left out.

If <path-name> is defined as  `path\name\#.BLA', all processed messages
will be dumped to the files with incremental names and fixed extension,
such as 1.BLA, 2.BLA, and so on, one message per file.

Old messages are not overwritten, i.e. the numbering is done beginning
from the message with the highest number so far in that directory
(similar to the algorithm used for *.msg area type).

If in place of a name pattern one of the following characters is used: < >
the file name will be built as follows:

  <fromNet>_<fromNode>.<fromPoint>  (for `<'  which can be thought of as
                                     `mail TO us')
  
   OR
   
   <toNet>_<toNode>.<toPoint>       (for `>' which can be thought of as
                                     `mail FROM us')

   For example:

   TextArea .\archive\< ToMe

   Which means that a mail to 5020/549.16 will be dumped to a file
   with the following name:

  .\archive\5020_549.16


If the target file is to be created on a FAT partition,
and its name doesn't fit into 8.3 pattern (ouch!), then an attempt will
be made to remove underscore from the file name. If still not fitted,
basename will be truncated to eight characters, while the extension
(which is in effect a point address) will be likewise truncated to
contain three characters.



3.3.5           PKTAREA    <path> <area-name> [<system>]...
                ...[<password] [<pktlength] [ECHOMAIL] [B-BOX|T-BOX]

Defines a pkt area, which can be both inbound and/or outbound, or even not
at all bound area. File attaches are not processed when message is
packed into this area. All messages to a given address processed during
one itraX run will be packed into the same packet unless it's too big
according to the <pktlength> (see argument description below).

If <password> block name is defined (see DATA PASSWORD), password will
be automatically inserted into the packet header.

If <pktlength> is defined, pkt-saw will be turned on for this area.


The other arguments:

B-BOX - Defines filebox in The Brake! format:
        domain.zone.net.node.point.flavor
        
T-BOX - Defines filebox in T-Mail format:
        zone.net.node.point[.H]

If either of the following arguments is given, this area will
be treated as filebox to store pkt files. The path name is set
relative to <path> and may be dynamically redefined using
SetFboxPath function (see 3.9.15).



3.3.6          JAMAREA <path> <area-name> [<system>] [ECHOMAIL]

Takes the same arguments as FIDOAREA.



3.4   Basic message area functions
-----------------------------------------------

3.4.1           SCAN ([<arename>  [timestamp_file] ])

Select an area to scan. This function must be executed before
any message access functions, such as ReadMsg (see 3.7.1).

If an optional <timestamp_file> argument is given, the internal lastread
information will be taken into account when processing messages in
this area: only messages newer than the last stored in the time stamp
file will be processed.


For different area types the lastread timestamp is deducted differently:


FIDOAREA -    Date when the file was created or last updated.
           
SQUISHAREA -  Message arrival date. If absent (zero), the message
              creation date is taken (probably written on our system).

JAMAREA -     The date when message was processed or received.
              If both are present, the later is taken.
              If both are absent (zeroes), the message creation date is
              taken (probably written on our system).


For other area types this argument has no effect.


Note:

It's also possible to call Scan() without arguments, which
effectively deselects the current area. This can only be required
to make it possible to Renumber (see 3.9.10) the current area which must be
inactive for that purpose.


3.4.2           DOBINKOUTBOUND (<areaname>)

Packs temporary ?IP/?IF packets into outbound directory defined as a
part of <areaname> definition (see 3.3.x).

Packing can be done in one of the following formats:
standard binkley outbound (?ut/?lo) and long binkley outbound
(see BRAKEOUTBOUND argument for BINKAREA).


3.4.3           SETROUTING (<routing>)

Sets the routing address according to the <routing> block (see DATA
ROUTING).

If no match was found, direct routing will be set. For that reason it
makes sense to use Select() on the <routing> block first.

If a match was found, flavor will be also taken from the <routing> block.
The final flavor also depends on the message attributes which have the
following priority (from the highest):  HOLD IMM CRASH DIRECT NORMAL


3.4.4           SETFLAVO[U]R ([<attributes>])

Adds/removes set of flavor attributes from/to the already set flavor
mask for the current message. If called without arguments, flavor will
be set according to the message attributes.

Example: Call SetFlavor( "Dir !Hold" )



3.4.5           DOBRAKEOUTBOUND ( <areaname> )

Same as DoBinkOutbound (see 3.4.2), but long binkley outbound format
is used (see 3.3.3 for details).



3.5    Functions to work with files
-----------------------------------------------


3.5.1           CREATEFILE (<@ fspec|blockname>)

Creates the given file name. The file name can be set directly (using @
in front of the filename) or as a block name. In the latter case, all
files defined in that block will be created, except for those having `!'
in front of their names in the block definition.

If all target files have been successfully created,
this function return true. False is returned otherwise.

Example: call CreateFile("@ semaphore.000")


3.5.2           KILLFILE <fspec|blockname>

Deletes the given file name.
This type has the same calling semantics as explained in 3.5.1

If all target files have been successfully deleted,
this function returns true. False is returned otherwise.


3.6    Selection functions
----------------------------------------------------------------------

3.6.1           SELECT[TO]|[FROM] ([!][@][~]<data>)

Selects a message based on certain criteria given as <data> type.
Takes a single argument, the direct data or data block name.

SELECTTO deals with the recipient part of the message if applicable
(such recipient's address and name).

SELECTFROM deals with the sender part of the message if applicable.

SELECT deals with both the sender and recipient part of the message
and actually calls SELECTTO+SELECTFROM on the same message.

Even though most block types are `neutral' and can't be considered as TO
or FROM part of the message, so you can just use SELECT on them, in
most cases it's not desirable as it only imposes an unnecessary
overhead because comparison will be made twice.  So it makes sense to
use either SELECTTO or SELECTFROM for those neutral data types.


<data> can be prefixed with one of the following modifiers:

@   - Direct data definition. For example, to pass a direct data
      of DATA NAME type : call SelectTo "@name Myname"
~   - Relaxed comparing. Has different semantics for different data
      types. For example, when making relaxed selection on DATA ADDRESS type,
      the point number will be ignored (as if there was `*' at the point
      position in the address mask).
      For string types, ~ means case insensitive search.

!   - Inversion, i.e. Select() functions returns true if no match was
      found for the given data pattern.

Return: 1 (ok)
        0 (fail)

3.7    Message access functions
------------------------------------------

3.7.1           READMSG ()

The core function which reads the current message into memory
making it active (which is referred to as `the current message'
throughout this documentation). Only one message can be active at a time.
All further message access/manipulation functions will operate
on the active message, and it is therefore mandatory to call ReadMsg()
as the very first thing AFTER Scan() and BEFORE trying to access any
of the message components. Otherwise those functions will have no effect.

Return values:  True  (msg read ok) 
                False (end of area)


The return value was conceived to be analyzed to get out of area scan
loop when there are no messages left:

call Scan SomeArea
Do While ReadMsg()
    ...
End


3.7.2           REWIND ()

Go to the first message in the current area.


3.7.3           GETTEXT (<stem>)

Sucks the message body (no kludges) into the <stem>.


Returned stem structure:  stem.0 - the number of the lines read (n)

                          stem.1 
                    			...     -  the lines themselves
                          stem.n                             
                       

3.7.4           GETKLUDGES (<stem>)

Sucks the message kludges (without leading ascii(1) ) into the <stem>.

Returned stem structure:   stem.0 - the number of the lines read (n)

                           stem.1 
                    			...     -  the lines themselves
                           stem.n                             


3.7.5           GETVIAS (<stem>)

Sucks the message Via kludges (without leading `@Via ') into the <stem>.

Returned stem structure:   stem.0 - the number of the lines read (n)

                           stem.1 
                    			...     -  the lines themselves
                           stem.n                             


3.7.6           GETHDR (<stem>)

Returns the header of the current message. The resulting stem is filled
as follows:

        stem.0 = fromName
        stem.1 = fromAddr
        stem.2 = toName
        stem.3 = toAddr
        stem.4 = subject
        stem.5 = ftsc_date
        stem.6 = attributes (string separated by spaces)
	
        
3.7.7           GETTO ()

Returns the recipient's address and name.


3.7.8           GETFROM ()

Returns sender's address and name.

3.7.9           GETSUBJECT ()

Returns the subject field of the current message.


3.7.10          GETTIME ()

Returns the date field of the current message.


3.7.11          GETROUTING ()

Returns the routing address of the current message.


3.7.12          GETATTRIBUTE ()

Returns attributes of the current message as a space-separated string.


3.7.13          SETATTRIBUTE (<attr>|<block_name>)

Sets/clears one or more attributes of the current message.
Takes a single argument, which can be @ followed by a string of
attributes separated by spaces (recall the direct data syntax)
or a DATA ATTRIBUTE block name. In the latter case, all attributes
defined in a block will be set/cleared as defined.

Example: call SetAttribute "Imm !Hold"
Meaning: "Imm" will be set, while Hold will be cleared

Note that redefinition of the current attributes has no effect on
the message flavor that is internally set when message is
initially read into memory using ReadMsg (see 3.7.1). To adjust the message
flavor according to the new attribute set, call SetFlavor (see 3.4.4)
without arguments.


3.7.14          KILL ()

Deletes (kills, erases, removes, nukes, destroys, gets rid of)
the current message.


3.7.15          MOVE       ( <areaname> , "-t ...", "-f ..." , ... )

Moves the current message to area <areaname>. This function (as well as
a few others, described below) can take the following set of keys (modifiers)
as an argument list:

-t    <@ [to_addr] [to_name]     | block_name>
-f    <@ [from_addr] [from_name] | block_name>

    	Modifies from/to address and/or username of the current message
	respectively. If both address and name are set directly (using @),
	the address must come first! As a block name, the following
	types are recognized: ADDRESS, NAME, ADDRESSNAME.
	
  
-s <@ subject> | <subj_data_block>        

        Modifies the subject of the current message.
	Argument: either direct data or DATA SUBJECT block name.
	In case of data block with multiple entries, the first one
	will be picked.

-a  <@ attribute | block_name>
        
	Modifies the message attributes. In case of direct data
	a string of space separated attributes is expected and
	an additional attribute is recognized: CLEAR (reset all).
	In case of a DATA ATTRIBUTE block, all the attributes defined
	in the block will be applied.

-h[#] <file_name>                      
    
	Embeds a template file <file_name> into the message body
	beginning from the line # (defaults to the first non-kludge line).

	The template file can contain macros (discussed in 3.9.9)
	in the form of %MacroName%. The same form is used to expand
	environment variables, as well as itraX global variables
	which can be set using SetGlobalVar (see 3.9.16).
	
	Environment variables, global variables, and macros share the
        same namespace, with the environment variables having the highest
        priority. To avoid namespace collision, you can enclose
	an internal global variable or macro in double %'s (%%Name%%).
	
	In addition, if a stem has been previously defined somewhere in the
        script, you can include it in the template as a stem name followed by
        a comma and enclosed in single or double %'s (%%STEM.%%).
	

-l[#] <@ line_string>[.] | <textsring_datablock>

	Adds a string to the message body at line # (defaults to the
	first non-kludge line).

  
    -l0    - adds a string to the message body BEFORE the first
             kludge line.
  
    -l-1   - adds a string to the message body at the end of the text:
             in the position AFTER tearline/origin but BEFORE the first
             lower kludge, such as PATH/SEEN-BY/Via/Recv.


  The string can be passed direct, or by specifying a DATA TEXTSTRING
  block name (the first defined string is picked). In the former case
  it's also   possible to pass an array of strings as a stem variable in
  the following format:
  
   s.0 = n (the number of the passed strings)
   
   s.1
   ...     the strings
   s.n
   
  To differentiate between a variable and a stem, the stem name must
  be ended in dot!

  Note that while it's possible to specify both -h and -l at the same time,
  it's not recommended because irrespectively of the order
  in which these two keys are defined the header (-h) has a higher
  priority. So if -l is applied right after -h, the previously inserted
  header's position within the message body can change.


-d [ftsc_date | seadog_date]

  Changes the date of the current message. Date is accepted in
  ftsc or seadog format. If no date provided, the current date will be
  set (the message is said to be `touched').

-e <area_name>

  Inserts the echomail kludge in the form AREA: <area_name> before the
  first kludge of the message body. Makes sense for pkt areas.
  Only the direct string is accepted.

-o [origin_string]

  Inserts an origin line in the message body. No dupe origin checking is
  performed. Only the direct string is accepted.

-r [tearline_string]

  Inserts a tearline in the message body. No dupe tearline checking is
  performed. Only the direct string is accepted.

-u [address string | route block]

  Overrides the routing for the current message. If address is
  specified direct, routing will be unconditionally set to that address.
  If a DATA ROUTING block name is given, it has the same effect as
  executing SETROUTING (see 3.4.3). The using of this key may come in handy
  if a new  mail is created using CREATEMAIL (see 3.7.18) right in the
  outbound  directory, or just to set routing on-the-fly, as follows:

  call MOVE binkout -u <routing>  ; where <routing> is DATA ROUTING
                                  ; block name
				  
-p [ pkt_hdr_stem ]

  If the target area is of pkt type, sets pkt header according to the
  data contained in pkt_hdr_stem (see 3.11.6 SetPktHdr)

  

More examples of using various keys:

  t = "-t @ 2:5020/410 Igor Shvyrkov"
  f = "-f @ 2:520/999"
  a = "-a attr_block"
  l = "-l @ moved mail"
  call Move MyMail , t , f , a , l


This is how a stem of strings can be passed:

  ls.0 = 2
  ls.1 = "String1"
  ls.2 = "String2"
  call Move MyMail , ls.


Return value: target file name 


3.7.16          COPYAREA   ( <areaname> , "-t ...", "-f ..." , ... )

Copies the current message to area <areaname>.
Supports the set of the keys (tfsahldeorup) described in 3.7.15.

Return value: target file name


3.7.17          BOUNCE     ( "-h ..." "-a ..." , ... )

Bounces the current message back to the original sender.
All kludges, tearline, and origin, if any, of the original message
get invalidated.

Supports the set of the keys (tfsahldeorup) described in 3.7.15, with the only
exception: it's not possible to change the sender's address
since it will be automatically set by BOUNCE.


3.7.18 		CREATEMAIL ( "[areaname]" , ...
			    ... "@ <addr> [<name>] | block_name" , ...
		   	    ... "-t ...", "-f ..." , ... )

Creates a new message in area <areaname>. If <areaname> is an empty
string (""), the message will be created in the current active area
previously set by SCAN (see 3.4.1). The second argument must contain
a valid address (a direct string or an ADDRESS block name) optionally
followed by a user name represented as a direct string or an
ADDRESSNAME block name. In such a case the -t key is redundant and only
supported for compatibility with other functions which use all of the
keys.

Supports the set of the keys (tfsahldeorup) described in 3.7.15.

Example: to_who = "@ 2:5020/999 Ivan Govnov"
	 f = "-f @"
	 s = "your second name considered abusive"
	 h = "-h2 warn_tpl"

	 call CreateMail "" , to_who , f ,  s , h

	 call CreateMail "netmail" , "@ addr_block" , "-h  tpl_name"

Return value: target file name 


3.7.19          CHANGEMAIL ( "-t ...", "-f ..." , ... )

Changes the message (header and/or text) according to the specified
keys.

Supports the set of the keys (tfsahldeorup) described in 3.7.15.


3.7.20 		CHANGEFROM ( <@address <addr> | 
			      @readdresslist <addr1> <addr2> >|
			      <block_name> )
3.7.21 		CHANGETO   ( <@address <addr> | 
			      @readdresslist <addr1> <addr2> >|
			      <block_name> )

These two functions change the address of the recipient/sender
respectively.

The address argument can be supplied both in the direct and block name
form. The following block types are recognized:
1) DATA ADDRESS: the first defined address is used.
2) DATA READDRESSLIST: a pair of addresses is used.
The first address of the pair is the search target. If match was found,
the second address will be used in substitution.


Example: call ChangeFrom "@readdresslist 7:*/*.* 2:*/*.*"
Meaning: All mail originating from zone 7 will appear as coming from zone 2.
	    
Example: call ChangeTo "@address 2:5020/999"
Meaning: Unconditionally sets the recipient's address to 2:5020/999.

Example: call ChangeTo ReAddr
Meaning: the sender's address will be changed in accordance  with settings
         in the READDRESSLIST block `ReAddr'.
	    

3.7.22          DELETELINE ( [-n] line_no | [-s] [~+@]<string>|<block_name> )

Deletes a string in the current message. An optional line number or a
substring pattern can be given. The -n key means that a line number
follows. The -s key means that a string pattern follows. If neither of
the keys was specified, the argument is regarded as a line number if it has
all digits, or as a substring pattern otherwise. To avoid ambiguity,
the using of the above mentioned keys is recommended.

The `+' modifier means "delete all", i.e. all found occurrences of the
specified substring will be deleted. By default, only the first match
will be deleted.

Return value: true if something was deleted, false otherwise.


Example: call DeleteLine "-n 1"
Meaning: Deletes the 1st non-kludge line

Example: call DeleteLine "1"
Meaning: The same as above

Example: call DeleteLine "-s @1"
Meaning: Deletes a line which consists of a single character ``1''

Example: call DeleteLine "~@substr"
Meaning: Deletes the first found line which contains a ``substr''
         substring pattern

Example: call DeleteLine "-s +~@substr"
Meaning: All lines having the ``substs'' pattern will be deleted.
         (note, that the using of -s is redundant here).
                            
Example: call DeleteLine StrBlock
Meaning: the search pattern will be taken from the StrBlock data block.



3.7.23          ADDLINE    ( <expandable string>[.] , [linenumber] )

Add a string to the current message at a <linenumber>, if specified,
or at top by default. It is also possible to pass a stem variable,
which must end in a dot.

Example:

 s.0 = 2  ; the number of the passed strings
 s.1 = "String1"
 s.2 = "String2"

 call AddLine s.
 drop s.
 


3.7.24          ADDHEADER  ( <template[.tpl]> , [linenumber] )

Add a header to the current message at  <linenumber>, if specified,
or at top by default. <template> is the template file name. The default
extension is tpl. If a file with an empty extension should be used, its
name must end in a dot. The file will be searched in the following
places (in the order of precedence) :
1) relative to %ITRAX%\TEMPLATEDIR
2) relative to .\TEMPLATEDIR (if set)
3) as an absolute file name


3.7.25          ADDINTL()

Inserts the INTL kludge in the message. If the kludge is already present,
the function has no effect.


3.7.26          SETMESSAGETIME (<ftsc_date|seadog_date>)   

Sets the date of the current message. The date is accepted in the
ftsc or seadog format. If no date provided, the current date will be
set (the message is said to be `touched').


3.7.27          CHECKPATH (<@path pathname1 pathname2> |
                           <path_block_name>)

This function makes it easier to handle in-transit file attaches, to
track down stray or missing attaches, and so forth.

If the current message contains a file attachment (the FILE attribute
is set), the following actions will be performed:

File name specification is taken from the Subject field.
If it is a full name, the path component is stripped.
The base name will then be searched for in each directory specified as an
argument to this function as direct data (path list separated by spaces)
or as a DATA PATH block name.

If the file <fname> has been found in the directory <path>, the Subject
field will be changed to contain the following string: <path>\<fname>,
i.e. the fully qualified name of the attached file.

If there were more then one file in the Subject line, the same
procedure is performed for each file. If the size of the newly formed
Subject line exceeds the maximum size (71 chars), additional messages
will be generated as needed.

If the search fails, the filename will be put back on the Subject line
in the abridged form (without the previously stripped path). So the
path will stripped from the original file specification in any case.

If the Subject field has been changed as a result of the execution of
this function, the CHECKEDPATH attribute will be set. This may mean
either of the following:

1) The file was found in one of the supplied paths, and the Subject
   field now contains this file's full path name.
   
2) The file was not found but the file specification of the original
   Subject field contained a path which was stripped.
   

Return value: True  - all the files listed in the Subject field were found
                      in one of the path arguments supplied
              False - otherwise


3.7.28          KILLKLUDGE ( [ [~!] <@kludge ...> | <block_name>] )

Deletes one or more kludges in the current message according to the
specified search pattern, which may direct data or a DATA KLUDGE block
name. If called without arguments, all found kludges will be removed.

Modifiers:

~ - substring search
! - negation (inverse search)


Example: Call KillKludge "~@kludge X-" ;
Meaning: Deletes all kludge lines containing ``X-'' substring.

Example: Call KillKludge "~!@RealName"
Meaning: Deletes all kludge lines except for ``RealName'' kludge


3.7.29           SUBSTTEXT  ( [~+] <old_susbtr> , <new_substr> |
                              <block_name> )

Performs (sub)string substitution in the current message.

If two arguments are given, they must represent direct strings.
The first string is the search pattern, while the second one
is the replacement string.

If only a single argument is present, it must be a DATA TEXTSTRING block name.
The block must consist of the line pairs, with the first line being the
search pattern, while the second one being the replacement string.

For example:

 Data TextString TextStr
 
  old_substr1 ; search pattern
  new_substr1 ; replacement pair
  ;
  old_substr2 ; search pattern
  new_substr2 ; replacement pair
  ;
  unpaired_str ; if found, will be replaced to empty
  ....
  
 #end# Data

If the number of the block entries is odd, the last unpaired string
will have an empty string as its replacement pair.


Modifiers:

+ -  global substitution (all occurrences found will be substituted)
~ -  substring search (otherwise the whole string must match)

Return value: True  - at least one substitution took place
              False - otherwise


Example: call SubstText "old_string" , "new_string"
Meaning: Changes the first occurrence of `old_string' string to `new_string'

Example: call SubstText "+~ old_substr" , "new_substr"
Meaning: Changes all occurrences of `old_substr' substring to `new_substr'
  
Example: call SubstText "~TextStr"
Meaning: search/replacement pairs are taken from TextStr block


3.8    Packing/unpacking functions
------------------------------------

3.8.1  UNPACK     (<@path in> | <block_name> [, @path out] | <block_name>)

Unpack arcmail bundles. The first argument must be either a direct
path name, or a DATA PATH block name and represents the path where the
bundles reside. The second argument, if specified, is the directory
path where to store extracted packets. It defaults to the same
directory where the bundles reside.

Beginning from version 1.40 an additional ``%d'' macro
has been added to the set of macros in the archiver configuration file
(see 3.1.11). Used in the Extract keyword, it expands to the  directory
in which to store unpacked files. An example for OS/2 unzip:

Extract unzip -j -C -o %a %f -d %d

Using this macro makes it possible to eliminate some drawbacks that
the old unpacking algorithm had; namely, it temporarily changed to the
target directory for each bundle being processed which made it
impossible to define relative paths for unpacking, logging, and so on.


3.8.2  PACKPKT  (<pktarea> , <target_area> , [<AddressPacker>] , [NOMOVE])

Packs pkt files into arcmail bundles.

pktarea       - Source PKTAREA name.

target_area   - Target area name. Can be of BINKAREA or PKTAREA type.
                In the former case a new entry will be made in a respective
                ?LO file. In the latter case, the resulting bundle will
                be placed directly into the target area directory, which is in
                effect a filebox of one of the two supported types.
		This means that the target PKTAREA must have been previously
                defined as a filebox (see 3.3.5).

			  
AddressPacker - DATA ADDRESSPACKER block name

NOMOVE        - If the target area type is BINKAREA, the bundle will
                created by default in the directory where the
                corresponding ?LO file resides. If NOMOVE is set, the
                bundle will be created in the source directory. 
                Unpacked pkt files always stay in the source directory.
                

Packing can be done in one of the two supported binkley outbound
formats: standard binkley outbound, and long outbound (see BRAKEOUTBOUND
argument in the description of BINKAREA, 3.3.3).


3.9   Miscellaneous functions
-----------------------------


3.9.1           LOG (<expandable string>)

Puts an arbitrary string into the log file.


3.9.2           WRITESTRING ( <@filename|block_name> , 
                             [<expandable string>[.]] )

Writes a string into a file. The first argument is the file name given
as a direct name or as a DATA FILES block name. In the latter case, the very
first file will be picked from the block. To include leading/trailing
spaces, enclose them in single or double quotes. The second argument
is an expandable string. If it ends in a backslash (`\'), no newline will
be appended to the output string. It is also possible to pass a
stem of strings. The stem variable name must end in a dot.

For example:

 s.0 = 2  ; the number of the passed strings
 s.1 = "String1"
 s.2 = "String2"

 call WriteString "@ fname" , s.
 drop s.



3.9.3           GETUPLINK (<address>)

Returns the address of the uplink of a node with the address <address>.
All active nodelists are searched (both DATA NODELIST and DATA VERSION9).
In case of failure, an empty string is returned.


3.9.4           GETCRC ()

Returns CRC32 of the current message (header+kludges+text) in the hex form.


3.9.5           ISBUSY (<bink_area_name>, <address>)

Checks if a system is busy (session in progress).
<bink_area_name> is outbound area name where busy semaphores are
created. <address> is the address of a system in question.


Return:  True  - BUSY 
         False - FREE



3.9.6           IGNOREBSY (ON|OFF)

Dynamically turns bsy semaphore checking on/off.



3.9.7           ROUTETO (<address>|<block_name>)

Unconditionally sets the routing for the current message. 



3.9.8           ACTIVENODELIST ([+|-]<ndl_tag>)


Dynamically activates/deactivates one or more nodelist blocks
previously defined as DATA NODELIST or DATA VERSION9.
If the nodelist block name is prefixed with + or - modifier
then this particular block(s) will be activated/deactivated.
Otherwise only the specified blocks will become active, while the other
will be deactivated. Only active nodelist blocks are used for nodelist
lookup functions. By default, all defined nodelist blocks are active.
Note that this function takes only ONE argument -- a string of
nodelist block names separated by spaces.

Example: Call ActiveNodelist "+Ndl1 -Ndl2"
Meaning: Ndl1 is on now, Ndl2 is off now, the state of others is unchanged

Example: Call ActiveNodelist "Ndl1 Ndl2"
Meaning: Ndl1 and Ndl2 are on, all others are off


3.9.9           EXPANDMACRO (<string>)

Expands internal itraX macros (see the list below).
Note that %'s are redundant here.
Most of functions also try to expand their arguments as macros, so
it is possible to pass macros in the functions arguments. In this case
enclosing the macro name in %'s is necessary.

The following is the complete list of the supported macros.
Actually it's an excerpt from Itrack documentation with some changes.
Unsupported macros are not included. Subfields are not supported.

%FROMNAME%     From name of the message

%FROM%         From address of the message

%INTLFROM%     Intl from Address of the message

%MSGIDFROM%    Address located in the MSGID-kludge

%TONAME%       To name of the message

%TO%           To Address of the message

%INTLTO%       Intl to address of the message

%REPLYTO%      Address located in the REPLY-kludge

%TODOMAIN%     The  destination domain of the message.
               The   domain  is  the  result  of   the
               matching  of  the  destination  address
               against  the DATA SYSTEM block  of  the
               area the message was read from.

%FROMDOMAIN%   The  origin domain of the message.  The
               domain is the result of the matching of
               the    origin   address   against   the
               DATA  SYSTEM  block  of  the  area  the
               message was read from.

%ROUTETO%      Routing Information in the message

%TIME%         Time String of the message

%ATTRIBUTES%   List of message attributes



%SUBJECT%      Returns  the  whole  subject  of  a message. 
          

%LINECOUNT%    Returns  the  number of  textlines  NOT
               counting kludgelines. (Empty lines count).

The same for the original message

%OLDFROMNAME%
%OLDFROM%
%OLDMSGIDFROM%
%OLDINTLFROM%
%OLDTONAME%
%OLDTO%
%OLDINTLTO%
%OLDREPLYTO%
%OLDROUTETO%
%OLDDOMAIN%
%OLDTIME%
%OLDSUBJECT%
%OLDSUBJECT%
%OLDLINECOUNT%
%OLDATTRIBUTES%

System specific macros

%PROGRAM%          Program name including version.

%SYSTEM%           Matched System address

%SYSTEMTIME%       Current  System  time formatted  as  in
                   Vialine

%LOCALTIME%        Local time as : 11:04:44

%LOCALDATE%        Local date as : Mon/Day/Year


New stuff not in Itrack:

%PKTTO%            Returns To/From address from the header of
%PKTFROM%          the file being processed (pkt, ?ut, " ?lo)



3.9.10              RENUMBER ([<area_name>])

This function has different meaning for different area types:

FIDOAREA: renumbers the specified area 
JAMAREA, SQUISHAREA: packs the specified area

If called without arguments, all defined areas will be processed.

The target area must be inactive (see SCAN, 3.4.1).


3.9.11              RxSearch (<haystack> , [~]<needle>)

Regular expression search for <needle> in <haystack>.
Prefixing the search pattern with the ``~'' modifier renders
search case insensitive. Both patterns are first checked for macro
expansion.

Returns true on success, false otherwise.

rc = RxSearch( "~THRAKaTTaCk" , "(VROOM)|(THRaK)" ) ; rc = 1 (true)


3.9.12              GETECHONAME ()

If the current message is echomail, returns the echo name
which is extracted from AREA: kludge.

if RxSearch(getEchoName(), "~six") then do 
   call Kill
   iterate
end

Using select on DATA ECHONAME is probably a more convenient way to
achieve the same result.



3.9.13              GETAREALIST(stem)

Returns the stem filled with the list of all defined areas.

Can be used to scan `all the areas defined' :

call GetAreaList(list)

do i = 1 to list.0

  call Scan list.i
  
  do while ReadMsg()
    ...
  end
  
end



3.9.14              NDLREBUILD([<block_name>])

Forces recompilation of all nodelists in the specified nodelist block
(normally they are only recompiled when a newer nodelist file was
found).  If called without arguments, all defined nodelist blocks will
be recompiled. Both  NODELIST and VERSION9 nodelist blocks are
supported.



3.9.15              SETFBOXPATH ([path_name])

Used to override the filebox directory for the current message on the
fly. Can be used to form the filebox directory for PKTAREA in a custom
format other than the two supported ones (The Brake! and T-Mail) for
which the right path is calculated automatically. The path is
considered to be relative to the areapath set for the current area in
PKTAREA definition (see 3.3.5). The path, set by this function, has
precedence over the automatically formed standard filebox path. If
called without arguments, the previously set custom path will be
reset.

Example:

do while readmsg()
 call SetRouting PktRouting
 ra = getRouting()
 fbp = ra.zone'.'ra.net'.'ra.node'.'ra.point'.my_own_trick'....
 call CopyArea PktArea    
end


3.9.16              SETGLOBALVAR (<var_name>, <value>)

Defines a global variable <var_name> and set its value into <value>.
The defined global variable can be used in templates to be expanded in the
same way as macros and environment variables are expanded.



3.9.17              UNSETGLOBALVAR (<var_name>)

Unsets global variable <var_name>



3.9.18              GETGLOBALVAR (<var_name>)

Returns value of a global variable <var_name>.



3.9.19              GETNODELISTRECORD (<stem_name>, <max>, <address>,
                                      [<nodelist block>])

Returns a complete nodelist entry or a filled stem variable with one or
several nodelist entry fields for a given address.

Argument list:

stem_name - stem name

max       - the maximum expected number of the fields to return in the stem.
            If <max> is zero, stem will be unused and return value will be a
            nodelist record as is, so you can parse it yourself as
            needed. If <max> is less than the actual number of the
            record fields, the last element will contain all other
            fields in the unparsed form (comma separated). If <max> is
            greater that the actual record field number,
	    the real number of the stem members will be filled
            beginning from s.1, and s.0 will be set accordingly.
	    
	    
nodelist  - An optional DATA NODELIST block name
block       (VERSION9 not supported for this function!)
            If not set, defaults to all defined DATA NODELIST blocks.


Note that if a non-zero length stem is returned, underscores in Sysop's
Name and System Name will be substituted for spaces.



3.9.20              REREADCONFIG ([config_name])

Re-read the configuration file. If an optional configuration file name
is omitted, itrax.cfg is assumed.


3.9.21              GETNODELISTBLOCK (<stem_name>, [<nodelist block>])

Returns stem with nodelist file names for the given DATA NODELIST
or VERSION9 block.


3.9.22              GETMSG (<stem_name>)

Returns stem with the whole message: text and all invalidated kludges


3.9.23              GETRAWMSG (<stem_name>)

Same as the previous, but returns text and kludges as is, without
invalidating them.


3.9.24              ZAPTEXT ()

Kills all text lines of the current message (kludges are kept intact).



3.11   PKT access functions

The functions below provide interface for direct pkt access, which
makes it possible to treat the whole packet as a single message, which can
be copied, moved, killed, or iterated over, just like a usual message.


3.11.1              READPKT ()

Reads pkt into memory.

Return: true/false


3.11.2              COPYPKT (<area>)

Copies pkt to area <area>. Both source and destination areas must of
pkt type.

Return: true/false


3.11.3              MOVEPKT (<area>)

Moves pkt to area <area>. Both source and destination areas must of
pkt type. 

Return: true/false


3.11.4              KILLPKT ()

Deletes pkt. The area must be of pkt type.

Return: true/false


Warning: these three functions act upon  UNREAD part of the current pkt,
i.e only unread part will be copied, moved, or deleted. As an example,
to kill all the messages in current pkt, do the following:

Do While ReadMsg()
  call Kill  /* kill the current msg */
  call KillPkt /* kill the rest of pkt  */
end  



An example of using these functions together:

call scan pkt
do while ReadMsg()

  call GetPktHdr h.

  if (h.6 = tmail_ftsc_code) then do     /* if this packet was generated */
                                         /* by t-mail */
    call KillMsg					 
    call KillPkt                         /* just kill it for fun :-) */
    iterate                              /* go to next one */
  end
  else if (h.6 = itrack_ftsc_code) then do
    call ReadPkt                         /* leave this packet alone */
    iterate                              /* and skip to next one */
  end
  else do
    call Move    pkt2
    call MovePkt pkt2      
  end
  
end


call scan pkt
do while ReadPkt()
  call ReadMsg      /* read the 1st message of every packet in this area */
  ...
end



3.11.5              GETPKTHDR (<stem>)

If the current area is pktarea, returns stem filled with the following fields
of the pkt header of the current pkt file:

stem.0  = 10 (the number of stem members)
stem.1  = from address;
stem.2  = to address;
stem.3  = time;
stem.4  = password;
stem.5  = prodCodeH;
stem.6  = prodCodeL;
stem.7  = verMinor;
stem.8  = verMajor;
stem.9  = prodData;
stem.10 = pkt file name;

Note: binary fields (5-9) are represented as hex digits

An example:

/* scan all the packets in the current area and change To: address of
/* each pkt header to 2:5020/999 */
call scan pkt
do while ReadPkt()
  if (ReadMsg()) then do
    call GetPktHdr h.
    if (h.0 = 10) then do
      h.2 = "2:5020/999"
      call SetPktHdr h.
    end
  end
end


3.11.6            SETPKTHDR (<stem_name)

If the current area is pkt area, sets pkt header according to the stem.
See 3.11.5 for stem format.


3.10   Alternative configuration functions
-----------------------------------------


3.10.1              DEFKEYWORD(<keyword>, <data>)

This function makes it possible to dynamically define any of the
supported keywords (see 3.1) or define an area (see 3.3) right from the
script.

Example: call DefKeyWord "UseRegExp" , "YES"



3.10.2              DEFDATABLOCK([<block_type>,] <stem_name>)


This function has the same functionality as DATA block definition
within the configuration file but can be called right from the script
to dynamically adjust the current configuration. If a block with this
name already present, it will be redefined.

There are two basic approaches:


1) The first argument indicates a block type to define, while the second
is data stem. The stem name must correspond to the DATA block name.
The 0th element of the stem holds, as usual, the number of stem elements
(i.e. the number of data lines in a conventional data block)

Example:

  Lacrimosa.0 = 2
  Lacrimosa.1 = "Tilo Wolff"
  Lacrimosa.2 = "Anne Whatshername"

  Call DefDataBlock "NAME" , Lacrimosa.
  drop Lacrimosa.

  This is analogous to the following:

  DATA NAME Lacrimosa
    Tilo Wolff
    Anne Whatshername
  #END# DATA


2) The function takes exactly one argument, which is a nested stem
   of the following format:

  <stem_base_name>.<block_type1>.<block_name1>.0 = n (total line number)
  ....
  <stem_base_name>.<block_type1>.<block_name1>.n
  ....
  <stem_base_name>.<block_type2>.<block_name2>.0
  ....
  <stem_base_name>.<block_type2>.<block_name2>.n
  .....  

  call DefDataBLock stem_base_name.


The second method allows for the definition of multiple blocks of various
types within a single stem tree.

Example:  

  s.NAME.MyName.0 = 2
  s.NAME.MyName.1 = "Igor Shvyrkov"
  s.NAME.MyName.2 = "Sysop"
  s.ADDRESS.MyAddr.0 = 2
  s.ADDRESS.MyAddr.1 = "2:5020/410"
  s.ADDRESS.MyAddr.2 = "2:5020/410.1"

  call DefDataBlock s.
  drop s.

  
  The definition above is equivalent to the following `conventional'
  block definitions in the configuration file:

  DATA NAME MyName
    Igor Shvyrkov
    Sysop
  #END# DATA

  DATA ADDRESS MyAddr
    2:5020/410
    2:5020/410.1
  #END# DATA

  
4. Credits and acknowledgements

- FTN software mentioned in this document:

  Itrack:       netmail tracker by Frank Pradde
  The Brake!:   mailer by John Gladkih
  T-Mail:       mailer by Andy Elkin
  Unimail:      netmail processor by Vadim Rumyantsev
  Version9:     nodelist index format by serge terekhov

- The list of various people who directly or indirectly contributed
  to development of this product by providing bugreports, contributing
  their working configuration & scripts, as well as assisting in distribution
  of itraX, and so on.  In no particular order:

  Dmitry Shevchenko,   2:5055/63
  Andrew Cherepivsky,  2:5020/1302
  Kat Kubatkin,        2:468/13
  Alex Belozuerov,     2:5014/1
  Andrey Shakhmatov,   2:5010/141
  Alexey Khoroshikh,   2:5020/549
  Dmitry Mochenev,     2:5020/549.16
  Eugene Kazarinov,    2:5020/3700
  Ivan Greenov,        2:464/8086
  Vladimir Papaev,     2:5020/1311
  

(I may have forgotten someone, so if you think you deserve to be included in
this list, please let me know :)


- Authors and band names which amused me at my busy hours while writing
  this software as well as at leisure time :)
  (<almost> in no particular order)

  Peter Hammil & Van der Graaf Generator
  Robert Fripp & King Crimson
  Jethro Tull
  <early> Genesis
  <early> Mike Oldfield
  Pink Floyd
  ELP
  Yes
  Rush
  Frank Zappa
  Brian Eno
  Tangerine Dream
  CAN
  The Doors
  Slade
  Patty Melony & The Chieftains
  Eileen Ivers
  Andy Irvine & Davy Spillane
  Michael Flatley's Lord of the Dance soundtrack
  Lacrimosa
  Judas Priest
  Accept
  Udo
  Running Wild
  Celtic Frost
  OOMPH!
  Morbid Angel
  Manowar
  Blind Guardian
  Rhapsody
  Dschinghis Khan
  Victor Pelevin
  Stephen King


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

APPENDIX A : Command line argument list for itraX.exe
-----------------------------------------------------

Usage: itraX [OPTION]... [SCRIPT]...
 

  -b, --ignore-bsy      same as  IgnoreBSY ON (see 3.1.7)
  -C, --chat-off        same as  Chat OFF (see 3.1.4)
  -c, --config [name]   alternative configuration file          
  -d, --debug  [level]  same as  DEBUG (see 3.1.6)
  -e, --touch-echomail  same as  TouchEchomail YES (see 3.1.8)
  -h, --help            prints option list to screen
  -i, --icase           same as RxIgnoreCase ON (see 3.1.12)
  -l, --logfile         same as LogFile (see 3.1.2)
  -r, --regex           same as UseRegExp YES (see 3.1.9)

  -[n] [arg1,arg2,...]  n=1...9
                        comma separated script argument list

Options and script names, as well as their arguments can be
intermixed and follow in no particular order (thanks to getopt,
borrowed from gnu libc). 
 
Example:

itraX.exe -i -1 s1_a1,s1_a2 -2 s2_a1,s2_a2 s1.cmd s2.cmd s3.cmd -3 s3_a1 -r

 s1.cmd, s2.cmd, s3.cmd -- script names
    s1_a1 and s1_a2 -- arguments for s1.cmd
    s2_a1 and s2_a2 -- arguments for s2.cmd
    s3_a1           -- argument  for s3.cmd

Note: By default, configuration file is called itraX.cfg and is
searched in path set by ITRAX environment variable.  If it is not set
an absolute path is assumed.  Otherwise it is searched relative to the
current directory. This holds true for other functions and keywords which
define directory paths.


APPENDIX B : Regular Expressions
-------------------------------------------------

Regular expressions are supported in the extended format
(see below for details).



Restrictions:

1) When making selection with UseRegExp turned on, no relaxed comparing (~)
will be performed. Use RxIgnoreCase for that purpose.


2) For the time being, regular expressions can be used for the following
data types only:

 DATA NAME
 DATA ADDRESSNAME
 DATA SUBJECT
 DATA TEXTSTRING
 DATA KLUDGE

3) For performance reasons, regular expressions are not supported
for direct data definition (@) in Select(). (The reason is
that in order to be used in a comparison, a regular expression needs to
be compiled first, which, when happens within a lengthy loop, will
impair performance severely).


Implemented based on the source code taken from 
regular expression library, version 0.12.
Copyright (C) 1985, 89, 90, 91, 92, 1993
Free Software Foundation, Inc. 


REGULAR EXPRESSIONS  (an excerpt from man grep)

       A  regular expression is a pattern that describes a set of
       strings.  Regular expressions are constructed  analagously
       to  arithmetic  expressions, by using various operators to
       combine smaller expressions.

       Grep understands two different versions of regular expres-
       sion  syntax:  ``basic''  and  ``extended.''
       The following  description applies  to  extended regular
       expressions; differences for basic regular expressions are
       summarized afterwards.

       The fundamental building blocks are  the  regular  expres-
       sions  that  match  a  single character.  Most characters,
       including all letters and digits, are regular  expressions
       that  match  themselves.   Any  metacharacter with special
       meaning may be quoted by preceding it with a backslash.

       A list of characters enclosed by [ and ] matches any  sin-
       gle  character in that list; if the first character of the
       list is the caret ^ then it matches any character  not  in
       the   list.    For   example,   the   regular   expression
       [0123456789] matches any single digit.  A range  of  ASCII
       characters  may  be specified by giving the first and last
       characters, separated by a hyphen.  Finally, certain named
       classes  of  characters  are  predefined.  Their names are
       self  explanatory,  and  they  are  [:alnum:],  [:alpha:],
       [:cntrl:],  [:digit:],  [:graph:],  [:lower:],  [:print:],
       [:punct:],  [:space:],  [:upper:],  and  [:xdigit:].   For
       example,  [[:alnum:]] means [0-9A-Za-z], except the latter
       form is  dependent  upon  the  ASCII  character  encoding,
       whereas  the  former is portable.  (Note that the brackets
       in these class names are part of the symbolic  names,  and
       must  be  included  in addition to the brackets delimiting
       the bracket list.)  Most metacharacters lose their special
       meaning  inside  lists.   To  include a literal ] place it
       first in the list.  Similarly,  to  include  a  literal  ^
       place  it  anywhere but first.  Finally, to include a lit-
       eral - place it last.

       The period .  matches any single character.  The symbol \w
       is  a  synonym  for  [[:alnum:]]  and  \W is a synonym for
       [^[:alnum]].

       The caret ^ and the dollar sign $ are metacharacters  that
       respectively  match  the empty string at the beginning and
       end of a line.  The symbols \< and \>  respectively  match
       the  empty string at the beginning and end of a word.  The
       symbol \b matches the empty string at the edge of a  word,
       and  \B  matches the empty string provided it's not at the
       edge of a word.

       A regular expression matching a single  character  may  be
       followed by one of several repetition operators:
       ?      The  preceding item is optional and matched at most
              once.
       *      The preceding item will be  matched  zero  or  more
              times.
       +      The  preceding  item  will  be  matched one or more
              times.
       {n}    The preceding item is matched exactly n times.
       {n,}   The preceding item is matched n or more times.
       {,m}   The preceding item is optional and  is  matched  at
              most m times.
       {n,m}  The preceding item is matched at least n times, but
              not more than m times.

       Two regular expressions may be concatenated; the resulting
       regular  expression  matches any string formed by concate-
       nating two substrings that respectively match the concate-
       nated subexpressions.

       Two  regular expressions may be joined by the infix opera-
       tor |; the resulting regular expression matches any string
       matching either subexpression.

       Repetition  takes  precedence over concatenation, which in
       turn takes precedence over alternation.   A  whole  subex-
       pression  may be enclosed in parentheses to override these
       precedence rules.

       The backreference \n, where n is a single  digit,  matches
       the  substring previously matched by the nth parenthesized
       subexpression of the regular expression.



APPENDIX C: itraX.dll dynamic library

First, a short introduction on internal itraX implementation.
Under OS/2 itraX.exe is actually a wrapper for itraX.dll.
It just accepts command line argument list and passes control to
itraX.dll which does the real job. Obviously, it is possible to
dynamically load itraX.dll directly from a REXX script using RxFuncAdd.

Interface to the dynamic library provides the following
initialization/deinitialization functions:

InitItrax([config_name])
------------------------
Initializes the dynamic library, which includes the following tasks:
- configuration file is read (defaults to itraX.cfg and can be redefined)
- REXX functions are registered

Must be called first, before trying to call any itraX function.
                  
                   
DeInitItrax()
-----------------
Does the opposite thing: cleans things up, deregisters REXX functions, etc.
Should be called when all done.


An example of using itraX.dll from a REXX script:

--- shell.cmd   START ---

/*   REXX   */

  Signal On Halt Name UserBreak

  call RxFuncAdd 'InitItrax', 'itrax', 'InitItrax'
  call SysLoadFuncs
  
  call InitItrax

  do FOREVER

    FILENAME = "dotrack.now"
    call SysFileTree FILENAME, "fh", "F"  ; check for semaphore presense

    if fh.0 <> 0 then do ; if found

      'del 'FILENAME     ; nuke it

      call Log "Executing script `track.cmd'"  
      call track.cmd    ; do the job
      call ...
      ...
      
    end

    ; go to sleep again
    ...

  end

UserBreak:

  call Log "User break signalled"
  call DeInitItrax
  
--- shell.cmd  END ---    



End of documentation
------------------------------------------------------------------------
Last revised: 09.08.99
