Argus Online Reference

 

 

What is Argus?

Argus is a comprehensive FTN Mailer designed to work as a multi-line system using two widely used data exchange transports - Dial-up networking and TCP/IP - simultaneously.

Major benefits by using Argus are:

True multitasking using Win32 API
True multi-line mailing system
Extended TCP/IP support

This chapter also describes FTN standards, supported by Argus.

 

True Multitasking Using Win32 API

Argus is a Win32 native application, it is written using the advantages of Win32 Application Programming Interface (API) designed in Windows NT, Windows 2000, Windows 95 and Windows 98. The major advantage - multitasking - gives Argus the possibility to use system resources with maximum performance (especially on multi-processor systems), because most of communication processes could be divided into parallel ones. At the same time, using separate threads for events handling, communication data reading and writing allows Argus to work with a minimum system load, so all other tasks running in a system can function without any delays.

 

Multi-line Mailing System

Because Argus is a true multi-line mailing system, configuration and co-ordination of all lines is truly quick and easy. There are no special limitations to number of concurrent connections - it just depends on a users' possibilities and requirements. The data transfer with a node can be established either via Dial-up or TCP/IP transport - this is determined by transport availability.

Dial-up lines can be started automatically at Argus start-up or manually by a user's request with System / Open Dial-up Line menu command. Each dial-up line requires a communication port, so the number of ports limits the number of lines being active simultaneously in a system.

TCP/IP lines are created and disposed as a result of TCP/IP Daemon functioning. As soon as Argus detects an incoming TCP/IP connection or a new poll via TCP/IP in the Poll Manager, Daemon creates a new mailing system line and starts a file transfer protocol. When a TCP/IP session finishes, Daemon closes the line and ends the connection.

 

Extended TCP/IP Support

Argus supports protocol-independent transport interface of WinSocket 2.0 (which was introduced in Windows NT version 4.0). Using WinSocket 2.0 allows you work seamlessly with a number of transport protocols such as TCP/IP, X.25 etc., use protocol-independent symbolic host name resolution (for example, SAP, X.500 etc., not only DNS), Win32-overlapped input/output modes, shared sockets, conditional acceptance etc.

The current version of Argus supports the most widely used WAN protocol - TCP/IP. In future versions we are planning to implement support for other protocols.

In regard of WinSocket 2.0 and Win32 use and the multi-threaded program architecture, host name resolution, connection and disconnections, input/output operations with TCP/IP are functioning as parallel processes; such way of operation provides optimal resource usage and minimum system load.

TCP/IP Daemon is the centre of control for all TCP/IP operations.

 

FTN Standards Supported

Argus interacts with remote systems using protocols and technology standards described in this chapter. Because Argus is built on FTN Technology (FidoNet Technology Network), it supports standards and proposals developed by FTN committee, common standards of FTN mail system functions are also supported by Argus.

This is the list of FTN standards and proposals that Argus is compliant to. Descriptions of those standards can be obtained from ftp://ftp.fidonet.org

- FTS-0001 mail session (limited to incoming-only). FSC-0039, FSC-0045 and P2K packet types are also supporting to extract remote information.
- YooHoo (FTS-0006) handshake.
- Nodelist (FTS-0005). Also, extended TCP/IP flags are supported.
- EMSI Handshake (FSC-0056) - full implementation.
- WaZOO mail session and file requests (FTS-0006) - full implementation.
- Z-modem file transfer protocol - full transport implementation with Skip/Refuse.
- Hydra file transfer protocol (FSC-0072) - full transport implementation except of chat ability.
- Working Time Nodelist flag (FSC-0062).
- Binkley-style Outbound.
- BinkP Transfer Protocol - full implementation of v1.0 draft specification, extended to file requests.
- Encrypted BinkP session.
- CRAM-MD5.

The reason to implement FTS-0001 mail session and FTS-0006 handshake is to be Fidonet-Policy compliant. Fidonet is the greatest FTN-based network worldwide. Here is an extract of chapter 2.1.8 Fidonet Policy v4:

Any system which wishes to be a part of FidoNet must be able to receive mail during this time using the protocol defined in the current FidoNet Technical Standards Committee publication (FTS-0001 at this writing). It is permissible to have greater capability (for example, to support additional protocols or extended mail hours), but the minimum requirement is FTS-0001 capability during this one hour of the day.

Note, that there are some limitations in Argus implementation of FTS-0001:

- Outgoing FTS-0001 calls are not supported.
- Argus receives only and does not send out files during FTS-0001 session.
- The password length is limited by FTS-0001 to 8 characters. Links with more than 8 characters in a password would be unable to initiate a password-protected FTS-0001 session.
- Skip File and Reject File operations are disabled (as well as refuse/delay).
- No file re-gets.
- Some FTS-0001 mailers do not provide valid file time.
- FTS-0001 protocol may not be fully Year2000 compliant in some implementations.
- CRAM-MD5 is not suported.

 

Working Time Nodelist Flag (FSC-0062)

CM (Continuous/Crash Mail) flag indicates that the node is available at any time of day and night. This means that working time of the node is 00:00-24:00.

Availability flag for non-CM nodes indicating the hours during which the node is available in addition to ZMH (see chapter Calling a Node only within its Working Time for ZMH definitions). This must be in accordance with the recommendations in FSC-0062 and the reference table reproduced below. This flag appears in the Nodelist entry as Txy, where x is a symbol for the opening time and y is a symbol for the closing time. All Txy flags must be specified after U, which is an attribute of extended Nodelist flag.

ATTENTION : All times must be UTC (Universal Time Coordinated)!

A 0:00 F 5:00 K 10:00 P 15:00 U 20:00
a 0:30 f 5:30 k 10:30 p 15:30 u 20:30
B 1:00 G 6:00 L 11:00 Q 16:00 V 21:00
b 1:30 g 6:30 l 11:30 q 16:30 v 21:30
C 2:00 H 7:00 M 12:00 R 17:00 W 22:00
c 2:30 h 7:30 m 12:30 r 17:30 w 22:30
D 3:00 I 8:00 N 13:00 S 18:00 X 23:00
d 3:30 i 8:30 n 13:30 s 18:30 x 23:30
E 4:00 J 9:00 O 14:00 T 19:00
e 4:30 j 9:30 o 14:30 t 19:30

Argus is using this flag for polling a node in its working time.

Argus allows the combing of working time intervals by using several Txy flags. For example, TÑh, TSW means that node is available 2:00-6:30 and 18:00-22:00 UTC.

Argus also supports TxyL extension - it is the same as Txy, but indicating that the time is local, not UTC. For example, TCSL means 2:00-18:00 local time.

CM flag is equivalent to U,TAA.

 

Calling a Node Only Within Its Working Time

Argus is designed so that it will not automatically dial a particular node in any time outside the node's working time interval specified by FSC-0062 Nodelist flag (Txy). The working time flag could be specified either in the Nodelist or in Node Overrides Table. If CM is specified for a node, this means that working time of the node is 00:00-24:00.

Remarks: If there are no working time flags specified for a node, this node may only be automatically dialled within Zone Mail Hour (ZMH).

Zone Mail Hour Table, sorted by UTC (Universal Time Coordinated), follows:

Zone 5 mail hour (01:00 - 02:00 UTC)
Zone 2 mail hour (02:30 - 03:30 UTC)
Zone 4 mail hour (08:00 - 09:00 UTC)
Zone 1 mail hour (09:00 - 10:00 UTC)
Zone 3 mail hour (18:00 - 19:00 UTC)
Zone 6 mail hour (20:00 - 21:00 UTC)

Other zone mail hours are custom and not internally supported by Argus. Use Txy to define custom mail hours.

If a poll is created manually, Argus ignores a node's working time.

 

Binkley-Style Outbound

This chapter explains the general principles of the Binkley-style Outbound structure, used by Argus mailing system.

Binkley-style Outbound was introduced in BinkleyTerm mailing system by Bit Bucket Software, soon it became a standard for the outbound section of mailing systems.

Explained briefly, The Binkley-style Outbound is a directory structure containing outgoing packets. The outbound directory for Default outbound zone is the directory specified in the Outbound entry field of the Directories Configuration dialogue. Outbound directories for other zones are created as directories with the same name as default outbound zone directory, but the name extension of such directory is hexadecimal representation of 12-bit number of the zone. (This is the reason to limit maximal zone number with 4095, which is FFF hex).

OUTBOUND The outbound directory for Default outbound zone)
OUTBOUND.001 The outbound directory for Zone number 1 (North America)
OUTBOUND.03F The outbound directory for Zone number 63 (3F hex)

All outbound packets are divided into two groups: Mail bundles and Attachment lists. Each group has four (actually three, because Direct is equal either to Crash or to Normal - it is determined in the terms of a particular mailing system) subtypes determining the urgency of a packet:

Subtype Initiates a poll Packet contents is transferred during outgoing connection Mail bundle extension Attachment list extension
Crash yes yes .CUT .CLO
Direct yes yes .DUT .DLO
Normal no yes .OUT .FLO
Hold no depends on setup .HUT .HLO

A Mail bundle is a standard FTS-0001 or P2K message packet, so before sending it, the system changes its name to XXXXXXXX.PKT, where each X represents a random hexadecimal digit (usually that hexadecimal combination is actually the time of a packet creation in UNIX format, but it is not relevant in modern mailing systems).

The Attachment list is a text file containing text lines, each of these lines contains the full path name of an outbound file. The very first character in a line may also determine the action after the target file is sent: '^' character placed in the beginning of a line means that the target file must be deleted, '#' means that the target file shall be truncated after its transfer.

The name of each outbound packet for a node has a format NNNNFFFF.EXT, where NNNN is the hexadecimal representation of 16-bit Net number, FFFF is the hexadecimal representation of 16-bit Node number and EXT is the extension determining the group and subtype of the packet (see the table above). Thus, all outbound packets for node with address 469/38.0 will have names 01D50026.EXT

Outbound packets for points are stored in sub-directories of an Outbound directory. Those directories have names of format NNNNFFFF.PNT, NNNN and FFFF have the same meanings as for a node's outbound packet, .PNT is the extension symbolising that it is a point outbound. Outbound packets for points are names as 0000PPPP.EXT, PPPP is the hexadecimal representation of 16-bit Point number and EXT is the extension determining the group and subtype of the packet (see the table above). Thus, point 25 of node 469/38 (469/38.25) will have outbound packets named 00000019.EXT placed in the sub-directory 01D50026.PNT\ of an appropriate outbound directory.

There are some additional Binkley-style extensions, supported by Argus:

.BSY Indicates that the node is busy
.REQ List of file to request from remote
.HRQ List of files, requested by remote

Argus has an ability to open .BSY-files without DELETE_ON_CLOSE mode. Files will be deleting using DeleteFile command. This may be useful on some network file system which don't support DELETE_ON_CLOSE mode. To turn this option on, add the following registry value:

[HKEY_LOCAL_MACHINE\SOFTWARE\RIT\ARGUS\CurrentVersion\IniFile.ini]
"SimpleBSY"=dword:00000001

Outbound SmartMenu is a powerful tool provided for Binkley-style Outbound operation.

 

Outbound SmartMenu

Outbound SmartMenu is a special pop-up menu, called by clicking right mouse button or Space key on outbound node, smartly provides all possible operations with that node.

Attach to current node - invokes file attachment procedure, similar to Tool/Attach files (F8).
Poll to current node - invokes node polling procedure, similar to Poll/Create (F5).
Edit file request to current node - invokes file requesting procedure, similar to Tool/Edit File Request (F7).
Browse Nodelist at current node - invokes nodelist browsing procedure, similar to Tool/Browse Nodelist at (Ctrl+F6)
Create flag for current node - may be used for invoking outbound-polls, similar to Tool/Create Flag (Ctrl+F8)

Outbound SmartMenu makes possible to operate current items as one. “Current items” are all items of one of the following group:

Currently selected outbound file, i.e. current item of current node
All of same file name of current node, i.e. filename.*, when filename.ext is currently selected outbound file.
All of same file extension of current node, i.e. *.ext, when filename.ext is currently selected outbound file.
All of same attach status of current node.
All Entries of current node.
Entire outbound, i.e. all items within Argus Outbound.

The following operations are performed on "current items":

Readdress - allows current items to be re-addressed to another node. Attachment status remains unchanged.
Finalize - makes files as they were sent. It kills the only "kill-sent" files and truncates "truncate-sent". Other files are leaving unchanged, just de-attached.
Change flavour to Crash/Direct/Normal/Hold - changes the attachment status of current items.
Unlink - unlinks (de-attaches) current items without killing them.
Remove broken links - unlinks (de-attaches) files, which are not available within current items. Be careful - links can be temporarily broken due to lost connection to network outbound or other temporary accessing errors.

 

The Argus Environment

This chapter explains the general points of Argus environment.

- Extended Graphical User Interface Elements
- Poll Maneger
- Mailer window
- Main Menu

 

Extened Graphical User Interface Elements; String grids; Log Window; Modem Activity Indicators; Transfer Progress Indicator; Connection Information Panel

This chapter contains the description of specific interface elements used in Argus:

- String grids
- Log Window
- Modem Activity Indicators
- Transfer Progress Indicator
- Connection Information Panel

 

String Grids

String grids are the most popular tool for entering string data information in Argus. There are two types of string grids: fixed and variable number of string rows.

This is an example of a string grid with fixed number of rows:

[String Grid - Fixed]

This is an example of a string grid with variable number of rows:

[String Grid - Variable]

There are four ways to change the values of currently focused grid cells:

Click left mouse button All the contents of the cell becomes selected
Press the Enter key All the contents of the cell becomes selected.
Press F2 key The contents of the cell is unselected
Start typing The contents of the cell is replaced by the typed text

The following operations are allowed in string grids with variable number of rows:

Insert a new row Ctrl + Ins
Delete the current row Ctrl + Del
Delete all rows Ctrl+Shift+Delete or Ctrl+Shift+Y
Add a new row Ctrl + Grey Plus
Move a row Drag the row with the mouse to the desired position and drop it there

You can also work with string grids using pop-up menu by clicking right mouse button inside the grid.

Edit cell Changes the value of the cell
Add row Same as Ctrl + Grey Plus
Insert row Same as Ctrl + Ins
Delete row Same as Ctrl + Del
Delete all rows Same as Ctrl+Shift+Del
Duplicate row Duplicate the cell
Export table Exports the table to a text file
Import table Imports the table from a text file
Help on grid Invokes this help chapter

See also: Mailer Widnow and Extended Graphical User Interface Elements.

 

Log Window

The Last 200 entries of the mailing system log file are stored in the Log Window. The window scrolls so that the last entries of the log are always visible. If the Log Window is focused upon, the automatic scrolling is stopped to make the log inspecting possible and comfortable; automatic scrolling is resumed as soon as another element of the Mailer Window is focused upon.

[Log Box]

 

Modem Activity Indicators

Modem Activity LEDs are located in the lower right corner of the Mailer Window when a Dial-up or TCP/IP line is selected; the LEDs help to show standard modem signals. There is also a modem debugging window in the upper right corner of the Mailer Window when a Dial-up line is active. It is designed to show modem input including control characters, in the upper part and modem output in the lower part.

Standard modem characters are black and control ones are blue.

[Terminal - Out]

[Terminal - In]

See also: Extended Graphical User Interface Elements.

 

Transfer Progress Indicator

[Pie Gauge]

If the total size of files to be transferred during a session is known, the transfer progress is shown on pie charts located in Mailer Window as well as the total size of files to be transferred or received (the last is known only if remote system has sent such information in handshake packet).

See also: Extended Graphical User Interface Elements.

 

Connection Information Panel

This panel appears when a file transfer session is established. It contains the information about the remote system:

[Remote Info]

Connect - is the exact response received from the modem at the time of connection. If a connection is made using the TCP/IP transport protocol, this section contains the IP address and the port number of the remote system.

All other parameters are taken from EMSI packet data:

Station - the name of remote system.

Address - Address List of remote system.

Sysop - the name of remote System Operator (SysOp).

Location - geographical location of remote system.

Phone - remote system's telephone number.

Flags - additional flags.

Mailer - the name and version of mailing system used by remote.

See also: Mailer Widnow and Extended Graphical User Interface Elements.

 

Poll Manager

Argus will poll a node with a 2 minute (+-50%) interval between calls. The tolerance interval of 50% is used to make polling more efficient - from the probability point of view. This interval can be adjusted in Poll Options dialogue box. Below is the description of Polls Panel columns.

Node
FTN address of a node being polled
Phones
A node's 'phone list (numbers are divided with a semicolon)
Owner
The task currently working with a node - could one of Argus' dial-up or TCP/IP lines, TCP/IP Daemon or an external application (the last means that node is busy)
State
The current poll state (dialling / ringing / connect / handshake / EMSI / WaZoo)
Busy
Counts number of BUSY responses during a poll.
No c.
Counts number of NO CARRIER / NO ANSWER responses during a poll.
Fail
Counts number of session failures during a poll. The session may fail due to Carrier loss or session aborts.

Note: If one of a polls counters is exceeded or a VOICE response is detected, Argus will delay the poll for 20 minutes (+-50%). This interval can be adjusted in Poll Options dialogue box, Stand-off minutes.

Type
Polling type:

Manual - the poll is created with Create Poll command. Manual Poll ignores working time of a node (CM and Txy Nodelist flags) and finishes after a successful file transfer session with the corresponding node.It is possible to enter several node addresses in Create Poll input box, divided with a space character. In this case Argus will automatically create a poll for each specified node.

Cron - the poll is created according to periodical polls dialogue set-up. The poll is much similar to Outb - poll.

Outb - the poll is created by Argus when Crash or Direct packets are detected Outbound. Automatic Poll finishes after a successful file transfer session or the corresponding packet is removed from Outbound by an external application.


Use Outbound SmartMenu for Binkley-style Outbound operation.

 

Mailer Window

This section describes the graphical user interface and how the Mailer Window of Argus works.

The Mailer Window is designed to show the state of a line activated either on Argus start-up or with the System|Open Dial-up Line menu command. To get a line to be shown in the Mailer Window click the appropriate tabs on tab control placed under the Argus main menu.

Mailer Window contains the following elements:

- Log Window.
- Modem Activity Indicators.
- Transfer Progress Indicators.
- Connection Information Panel.
- Time-out Panel.

 

Timeout Panel

Time-out panel displays the countdown (in seconds) to the next expected event.

When [ResetTo] button is pressed, the countdown is zeroed and the expected event is started. Line menu command has the same effect.

When [AddTo] button is pressed 30 seconds are added to the time-out. Line menu command has the same effect.

 

Main Menu

The submenus of Argus' Main menu are:

- System.
- Line.
- Poll.
- Tool.
- Config.
- Help.

 

System Submenu

Open Dial-up Line submenu for opening an inactive Dial-up line. open.linename file-flagIDH_FILEFLAGS also performs this action.
TCP/IP Daemon toggle for opening and closing of TCP/IP Daemon
Interface Language selects the interface language from list of available ones.
Exit quit Argus and close all active lines. (Alt+X keystroke). exit.now file-flagIDH_FILEFLAGS also performs this action.

 

Line Submenu

Commands of this submenu work with the line currently visible on the screen - use Tab Control to get a line displayed.

Reset Cancels active session (if any) and if the line uses Dial-up transport, re-initialising the modem attached, otherwise closes TCP/IP line.
Answer call Forces Argus to answer to incoming call. Useful with auto-answering disabled or on leased lines.
Flush Time-out Zeroes the current operation time-out, i.e. if line is waiting for connection or dial, the command cancels it.
Add to Time-out Adds 30 seconds to the current operation time-out.
Skip File Skips the file being currently received and leaves it for transfer during next session. This command may be misinterpreted by some mailers, so please be careful with it.
Reject File Skips currently incoming file and tells remote do not sent it any further. Some mailers may not accept this command.
Close Shuts down the line currently visible. close.linename file-flagIDH_FILEFLAGS also performs this action.

See also: Mailer Window.

 

Poll Submenu

This submenu contains poll managing commands.

Create invokes Create poll dialogue. It is possible to create one or more polls (use space symbol to divide node addresses)
Poll info displays useful poll information
Reset zeroes the failed tries counter of the selected poll
Delete deletes the selected poll
Delete all deletes all the polls

See also: Poll Manager.

 

Tool Submenu

This submenu contains miscellaneous commands.

Compile Nodelist compiles all Nodelists defined in Nodelist Configuration Dialogue. nodelist.ok file flag also invokes this action.
Browse Nodelist invokes the Nodelist browser
Browse Nodelist at invokes the Nodelist browser at specified node
Edit File Request ... use this command to edit or create a File Request
Attach Files... links specified files to a specified address. Links are placed to Outbound.
Create a Flag... creates a dummy outbound packet with a specified status for a specified node. This is primarilly intended for creating Outb-Polls.
Outbound SmartMenu powerful tool provided for Binkley-style Outbound operation. Details are described in a separate chapter.

 

Config Submenu

Master Password used to protect Argus configuration.
Paths invokes Directory Configuration Dualogue.
Nodelist invokes Nodelist Configuration Dialogue.
Passwords invokes Password Configuration Dialogue.
Start-up invokes Start-up Configuration Dialogue.
Dial-up invokes Dial-up Configuration Dialogue.
TCP/IP Daemon invokes TCP/IP Daemon Configuration Dialogue.
File-Boxes invokes File-Boxes Configuration.
Polls invokes Polls Configuration dialogue.
File requests invokes File Requests Configuration Dialogue.
Externals invokes External Applications Configuration Dialogue.
Events invokes TCP/IP Daemon Configuration Dialogue.
Encrypted Links invokes Encrypted Links Configuration Dialogue.

See also: Configuring Argus.

 

Help submenu

Help Topics invoke help topics list
Help Language select another language for Argus help system
Help on Help runs Windows Help System on “how to use help”
WebSite visit RIT Research Labs Argus Web Site - http://www.ritlabs.com/argus/
Credits great thanks to people there mentioned
License show program licence that you have accepted when installed Argus
About show program version, copyright and registration information
Registration register your copy of Argus. You must enter the registration key, obtained from the dealer, and a password. Visit http://www.ritlabs.com/argus/register.html or mail argus@ritlabs.com for purchasing information.

 

Argus Configuration

This chapter contains following sections:

- Protecting Argus Configuration.
- Directories.
- The Mail System-specific configuration dialogues.
- Confguration of Dial-up connections.
- TCP/IP Daemon configuration.
- Calling a node only within its Working Time.
- Address masks.
- Regular Expressions.

 

Master Password

Master Password is purposed to encrypt config.bin file using DES/CBC-56bit and MD5 algorithms to prevent your Argus configuration data (especially encrypted links' keys) from being stolen. Once set, Master Password would be asked each time Argus starts up, and before changing encrypted links' keys. If you would forget your Master password, there would be no easy practical way to retrieve the configuration data. Please use it very carefully. We also recommend backing up the original config.bin to a safe place.

DES cryptographic algorithms, used by Argus, are written by Eric Young (eay@mincom.oz.au). MD5 stands for RSA Data Security, Inc. MD5 Message-Digest Algorithm.

 

Pathnames Configuration

To get Argus to work correctly the user should define the paths to particular files and the Inbound / Outbound directories. This can be done using the Config / Path Names dialogue window.

This Chapter explains the Argus Home Directory and Special Directories.

The Home Directory is the root directory of the mailing system. If there is no full path defined for a specific directory, it will be placed in the Home directory.

Special Directories is a string grid, paths of Secure Inbound, Insecure Inbound, Temporary Inbound, Outbound and Log directories are defined there.


Default Zone number configuration

The default Zone number is used to determine the destination of files placed in the Outbound directory with the name defined in the Special Directories string grid. For example, if R:\FL\OUT is defined in the string grid as the Outbound directory and the Default Zone number is 2 (Europe), all outbound files for Zone 2 will be stored in R:\FL\OUT\, all files for other zones will be stored in directories R:\FL\OUT.XXX (XXX is hexadecimal representation of a zone number).

See also: Binkley-style Outbound.

 

Special Directories

Mailing system directories: Secure inbound, Insecure inbound, Temporary inbound, Outbound and Log are discussed here.

Usually all Mailing system directories are placed within the Home Directory. If this is the case the user may omit full path names (like C:\FIDO\ARGUS\LOG) by defining the path to a directory in relation to the Home Directory. If one has, for instance a Home Directory named C:\FIDO\ARGUS and wants to store Log files in the C:\FIDO\ARGUS\LOG directory, you only need to enter LOG in the appropriate place on the Special Directories configuration grid. If a path name begins with the backslash symbol ('\') the directory will be placed on the same drive as the Home Directory. If a drive name is specified in a path, there is no relation between that path and the Home Directory (the path name is absolute, in other words).

The following is an example of how the Special Directories path names are translated. The Home Directory is defined as C:\FIDO\ARGUS.

Record Translated to
LOG C:\FIDO\ARGUS\LOG
IN\SEC C:\FIDO\ARGUS\IN\SEC
\IN\PROT C:\IN\PROT
R:\FL\OUT R:\FL\OUT

 

Home Directory

Home directory is the main working directory of Argus. All configuration and working files of the Mailing system are stored there. These include: Argus configuration file (config.bin), the file with history lists of entry fields (history.bin), the incomplete/bad files log (badwazoo.log), the compiled Nodelist (nodelist.bin), and File-Flags. Special Directories are usually stored in the Home Directory to keep things neat and tidy (but this is not a necessity). The current path to the Home Directory is shown in the appropriate dialogue window panel. To change it, use the 'Change' button in the right side of the panel. In most cases the Home Directory is defined just once at the installation of Argus and there is usually no need to change its path in future.
 

Secure Inbound

Secure inbound is the directory where completely received files during password-protected file transfer sessions are stored.

See also: Special Directories.
 

Insecure inbound

Insecure inbound is the directory where completely received files during non-password-protected file transfer sessions are stored.

See also: Special Directories.
 

Temporary Inbound

Temporary inbound is the directory where files are momentarily stored whilst they are being received. Once files are completely received they are moved into the Secure Inbound, Insecure Inbound or Incoming File-Boxes directories, or into a file-box.

If there is a file with the same name in either the Secure or Insecure Inbound directory, the file to be moved will be kept in the Temporary Inbound until the duplicate named file is deleted or moved from the destination directory. The file can be deleted or moved, for example, by an external program like mail tosser or file-echo processor.

If a file is not completely received due an unexpected termination of the session, the received part of the file will be stored in the Temporary Inbound directory during three days, until the file can be completed. In the next file transfer session the file transfer will resume from where it left off and not from the beginning of the file. Parts smaller than 16K are not stored in temporary inbound. Also, files with PKT extension are not stored here.

For reliable operation, the files from temporary inbound are moved, not copied, thus make sure that all inbound directories (temporary, secure, insecure, file-box) are on the same physical drive or volume in order Win32 API MoveFile() function would not fail with error "The system cannot move the file to a different disk drive".

See also: Special Directories.
 

Outbound

Outbound is a buffer directory for all outgoing files. See Binkley-Style Outbound structure for details.

See also: Special Directories
 

Log

Log is the directory where Log files are stored. Log files contain the activity history of Poll Manager (file polls.log), TCP/IP Deamon (file ipdaemon.log), periodically-launched applications log (file cronapps.log) and all dial-up and TCP/IP lines defined.

See also: Special Directories.
 

The Mail System-Specific Configuration Dialogues

This chapter explains how to configure the data specific to the location of the system and its intercommunication using the following dialogues:

- Nodelist configuration
- Password configuration
- File Request configuration
- Starup configuration

 

Nodelist Configuration

The Nodelist is a list of nodes working within an FTN network. The Nodelist is an official document within the network (see FTS-0005 document for more details). Argus can work with one or more defined nodelists as well as without any Nodelist at all.

The Nodelist is configured using Nodelist Configuration dialogue available in Config submenu.


Files

Files is a string grid for specifying file names of Nodelists and Pointlists used by Argus.
It is possible to use Wildcards and Regular Expressions in file names.

* any combination of one or more symbols
? any symbol
% any decimal digit ('0'-'9')

Note that unlike other cases, Wildcards and Regular Expressions here are used not to select multiple files matching given Wildcard or Regular Expression but select only one file, newest from all matching.

The number of Nodelist files defined is not limited, neither is their overall size.

Argus will allow you to work without a Nodelist. In this case the 'phone numbers (IP-addresses) of nodes you're usually calling should be configured in the appropriate dialogue boxes.

The following is an example of a Files string grid with a standard FidoNet Nodelist and the Pointlist of net 2:5020:

[Nodelist Files]


'Phones

'Phones is the string grid of telephone numbers prefix conversion. If a 'phone number begins with a prefix specified in the 'Phone Prefix column, the prefix will be replaced with the contents of the “Replace With” part of the appropriate grid row. If there is no prefix specified in a grid row, all numbers except those converted with the grid rows above will be dialled with the prefix from the “Replace With” part of such a row.

This is an example of 'Phones string grid:

[Nodelist Phones]

According to this table, prefix 7-095- will be replaced with an empty string (so 'phone numbers with this prefix will be treated as local), prefix 373-2- will be replaced with 8w0422, all other numbers will be dialled with 8w10- prefix. Thus, the 'phone number 373-2-146151 will be dialled as 8w0422146151, number 7-095-654321 - as 7654321, and the ''phone number 46-46-738100 will be dialled as 8w1046-46-738100.

Argus also checks nodelist.ok file-flag in its Home Directory and recompiles the Nodelist automatically.

 

Password configuration

Passwords of file transfer session are defined in the Password Configuration string grid. It is possible to define one password for several nodes (the node addresses should be divided with a space). Note that address masks and Regular Expressions are not allowed.

If using CRAM-MD5, passwords are case-sensitive, in other cases passwords are not case-sensitive.

If the mailer got an incoming connection with a system that has no password defined in the Password configuration, the session is non-password-protected. All the files and mail packets received during such a session are placed in Insecure Inbound. However, if the remote system sends a password in the session handshake packet, Argus adds “Remote proposes password....” record to the log file.

If a calling system sends a password other than that configured for one or more of its addresses, the session is terminated with a log record “Remote presented .... when .... required” (or “Remote presented no password when .... required”). Before the termination, Argus sends handshake packet with “BAD_PASSWORD” (or “NO_PASSWORD”) keyword instead of the real password to let the remote system know the reason for failure. After that, “Password security violation - disconnecting” is added to the log and the caller is disconnected.

If passwords match, the session is password-protected and all the received files will be placed in Secure Inbound, “Password-protected session” record is added to the log.

You may also define passwords via Password atom.

When Argus needs a password for particular node, it first looks for Password atom, then seeks in the list loaded from auxiliary passwords file and then in the grid.


Auxiliary Passwords File

You may specify here a file that defines additional passwords besides of listed in the string grid. The format of the file follows, one password per line:

AddressList | Password

Example:

2:469/38 | SUPER
2:469/77 2:469/84 | PUPER

Auxiliary passwords file is loading into memory on Argus Start-up and by detection of PASSWORD.OK file-flag in Argus Home Directory. Results of parsing of the file are logged in polls log.

 

Startup Parameters Configuration

Argus start-up parameters are configured in Start-up Configuration dialogue.


Configuring the automatic opening of Dial-up lines


By default, Argus is configured so that there are no lines opened at start-up. It is possible to determine which lines are to be opened at start-up - this just saves you having to open them manually. Note that all the lines to be opened must be pre-configured.

The lines to be opened at start-up are listed in Dial-up Lines / Auto-open list box. All other lines (which could be open manually using System / Open Dial-up Line command) are listed in Dial-up Lines / Manual-open list box.

To make lines open automatically at start-up, select the desired lines in the Manual-open list-box and press the '>' button - the lines will be moved into Auto-open list. To remove an auto-opening line from the Auto-open list, select it in the Auto-open list box and press the '<' button.


Configuring TCP/IP Daemon start-up

If you want TCP/IP Daemon to start automatically each time Argus starts, tick the Auto-run TCP/IP Daemon checkbox.


Fast logging

By default, Argus keeps log files closed and opens them only when it is necessary to append new data. It makes possible to move or erase these files without restarting of Argus. Option Fast logging tells Argus to keep log files always opened to avoid permanent opening and closing these files whenever it is needed to append a new log record. It saves system resources and execution time, but can prevent from moving / erasing / truncating log files during Argus execution.

Please note that improper use of Fast logging in OFF mode may be dangerous. If Argus fails to open a log file for writing, it will never try to open it again while running. So do not open log files in a mode that will prevent Argus from writing. Better way would be to rename the file to a temporary name, analyse it, and then, possibly, move somewhere to archive directory.

See also: Extended logging.


Log WZ pending/incomplete

This options turns on/off logging number of files in temporary inbound. There may be two reasons when incoming files are stored in temporary inbound after a session terminates. First reason is when Argus was unable to move received files from temporary inbound (e.g. due to file with same name already exists in destination directory). Such files in temporary inbound are called pending files. Second reason is when a session was aborted during a file transfer was in progress, so the file wasn't completely received. Such files are called incomplete files.


ODBC logging

This option turns on ODBC logging, as described in ODBC logging chapter.


 

Extended logging

Instead of simple log files, intended to be viewed by system operator, Argus also logs additional files:

access_log Common chronology of transferred files in NCSA format
agent_log Common chronology of remote mailer types in NCSA format
binary_log Common chronology of sessions and transferred files and bytes in binary format

NCSA logs access_log and agent_log are possible to analyse by any NCSA-compliant log analiser. The example of such analysis is available at http://www.ritlabs.com/stat/argus.html - the most recent statistics of RIT Zeppelin Fido Server (2:469/38), produced by analog2.11/Win32 © Stephen R. E. Turner.

The structure format of binary log file binary_log is compatible with the same in T-Mail © Andy Elkin and BinkD © Dima Maloff. Use T-Hist © Michael Markowsky (2:5020/378@fidonet) for processing binary_log.

It is possible to use custom values for access_log, agent_log and binary_log files names to avoid troubles on 8.3 file systems. To change them, create a registry key

HKEY_LOCAL_MACHINE\SOFTWARE\RIT\ARGUS\CurrentVersion\IniFile.ini
Names of String Values:
access_log
agent_log
binary_log

 

Configuration of Dial-up Connections

This chapter contains the information specific to working via Dial-up communications. If you are using Argus for only for TCP/IP connectivity, you may pass this chapter and read about TCP/IP Configuration.

There are the following sections in this chapter:

- Main Dial-up configuration panel
- Mailer Line configuration
- EMSI Data configuration
- Communication Port configuration
- Line bits setup
- Modem configuration
- Modem control characters
- Dialling rectrictions
- Node overrides table

 

Main Dial-up configuration panel

The Main Dial-up configuration panel consists of six pages, five of them are handling configuration parameter groups, the sixth one contains Node Overrides Table


Configuration parameter groups of Argus

Lines Setup of Argus' Mailer lines
Station EMSI Data Templates
Ports Setup of Communication Ports used in Argus
Modems Setup of modems used in Argus
Restrictions Dialling Restriction schemes

Configuration Panel buttons

New Create a new item of the current group with default parameters.
Edit Edit the current group item selected.
Copy Clone the selected item of the current group.
Delete Delete the selected item of the current group. It is not possible delete the last item of Lines group and a default items of other groups.
Undelete Recover the last deleted item of the current group.
Default Make the selected item of the current group default..

 

Mailer Line Configuration

This dialogue is designed to set up a Mailer Lines parameters. Those parameters are used to determine what name the line should have, EMSI data must be transferred, the lines' hardware configuration etc. For combo boxes, default parameters for a group may be used - in this case if the default of a group is changed, the line will automatically use the new default value.

Line name Name of the line as it appears on Tab title in Tab Control.
Station template EMSI data to be sent in handshake packet by the line
Port Communication port used by the line.
Modem Modem uses by the line.
Restrictions Dialling restrctions for the line.
Log file name The name of the line's log file. If there is no full path name specified, the file will be stored in the Log directory .

 

EMSI Data Configuration

EMSI Data configuration dialogue box contains three pages: EMSI, Banner and AKA.


EMSI

The information about the system to be transferred in EMSI-connection. Usually it is the same as in the Nodelist.

Station Name The system name
Address list Address (AKA) list of the system, divided by space
Sysop name System Operator' name
Location Geographical location of the system
Phone The system's data telephone number
Flags Nodelist flags

Banner

Banner is the text displayed to user connected to Argus with a generic terminal program (not with FTS-mailer) to obtain some console-based service by typing an enter sequence. Banner usually contains invitation, system policies, and the list of enter-sequences.


AKA

Argus is able to transfer to a particular remote system address list that differs from specified in EMSI data table.

Remote addresses field can contain addresses and/or address masks (separated by spaces), as well as Regular Expressions. So Argus will present AKA list taken not from EMSI data table but from Local addresses field, whenever it connects with such system.

AKA replacement works on EMSI connection and on BinkP as well.

Note that the primary address of a password-protected session is considered not a first address of AKA list but the first password-protected address. There can be several addresses protected with one password though. Primary address is used to link requested files to, also during SRIF requests, and to be mentioned in binary_log. Address filtering mechanism of Post-processors is also based on primary address.

 

Communication Ports Configuration

Asynchronous communications port parameters: COM port number, baud rate, flow control and data/stop/ parity bits.

Note that baud rates higher than 57600 should be used with caution - hardware or operating system could be too slow to manage the data flow which will cause the appearance of CE_BREAK, CE_OVERRUN, CE_FRAME, etc. errors in log file. The description of serial communication errors is beyond the scope of this manual.

 

Line bits setup

This dialogue, called from Communication Port configuration dialolue, is designed to setup data, parity and stop bits transferred by a communication port.

[Line Bits Settings]

No parity, 8 data bits and 1 stop bit are the most widely used parameters. Usually there is no special need to change them.

 

Modem Configuration


General Commands

Modem control characters are allowed.

Init. ^ATZ| Modem initialisation string. This string is sent to modem at line start-up, after a file transfer session finish and each two minutes of line inactivity (modem check). Use Modem Disable Reinit atom to disable periodical modem check. Make sure that most modems accept commands and report RING only when DTR is high, so don't remote ^ character that raises DTR.
Answer ATA! Answering string - this string is sent to the modem whenever RING response is detected and Argus goes into connection waiting state.
Dial prefix ATDP Dialling command prefix. Complete dialling command includes the prefix, the number to dial and the suffix.
Dial suffix ! Dialling command suffix. Usually it is ! (control character CR without waiting)
Hang-up !`v~~^`!!` Physical disconnect command that is sent to a modem only when DCD signal is high. Most of the modern modems could disconnect with lowering DTR signal and holding it down during one second. The string given in this example send CR, waits 0.1 sec, lowers DTR signal, waits 1.0 sec (usually it is enough), raises DTR, waits 0.1 sec, sends CR twice, and waits for 0.1 sec again.
Info none Info command is sent to the modem after a session termination, before sending Init string. The result of this command is logged. You may use Response Log Format atom to format data came from a modem. By default, Info command is not defined, so no info command at all is sent.

Responses

The standard modem responses are set in this string grid. All possible responses are divided by a space. Space characters in response string must be replaced with underline characters. You may not use wildcards but may use Regular Expressions here.


Flags

It is possible to pre-initialise the modem in special manner just before calling a node with particular Nodelist flags (flags could be set in the nodes configuration of Argus). Dial Prefix and Dial Suffix could depend on flags as well.

Each row of Flags string grid is a combination of Flags list and override of Init. string / Dial Prefix / Dial Suffix corresponding to the Flags list. Flags list a logical expression where space character is OR operator and comma character is AND operator (AND has higher priority than OR).

For example:
Flags list column Meaning
PEP PEP
HST H16 HST or H16
V32B,V42B V32B with V42B
ZYX,V34 32T either ZYX with V34 or V32T

Overrides of Init. string / Dial Prefix / Dial Suffix placed in the second column of Flags grid are divided by slash character. If the appropriate value is to be taken from General Commands (no need to override the value in special manner), single full stop character must be used.

The following example illustrates the formation of dialling pre-init string and dialling command and, using values from General Commands and Flags Init/Prefix/Suffix.This also illustrates how different settings of Flags Init/Prefix/Suffix could change formation of dialling command and dialling pre-init string.

This example illustrates different Flags Init/Prefix/Suffix values generating different pre-init string and dialling commands with constant General Commands settings. The number is taken for example 323323 .

General Commands settings
Init. ATZ|
Dial Prefix ATDP
Dial Suffix !

Flags Init/Prefix/Suffix Pre-Init string Dialling command Comment
ATB1|/ATM0DP/! ATB1| ATDP323323! Init. string - ATB1|
Prefix - ATM0DP
Suffix - !
ATM0|/ATDT ATM0| ATDT323323! Init. string - ATM0|
Prefix - ATDT
Suffix - !
ATH1| ATH1| ATDP323323! Prefix and suffix are taken from General Commands
/ATX7DP/@! none ATX7DP323323@! There is no initialisation string to be sent
ATB0|/./@! ATB0| ATDP323323@! Single full stop in Dial Prefix override - Dial Prefix is taken from General Commands

 

Modem Control Characters

This is the table of interpretation of control characters allowed in Commands string grid of Modem Configuration dialogue:

Character Hex code Action
` 60h 0.1 sec delay
~ 7Eh 0.5 sec delay
^ 5Eh raise DTR signal
v 76h lower DTR signal
| 7Ch send CR (0Dh) symbol and wait for OK response with 3 sec time-out
! 21h send CR without waiting
\ 5Ch send the next character as is (without treating it as a control character).
E.g.: \~ - sends tilde character

 

Fax reception

Argus has ability of Fax reception using external receiver programs or internal routines. Each modem has a "Fax" tab that defines whether internal or external Fax receiver is to be used. Answer like +FCON, CONNECT FAX, or +FCO from modem signals the established facsimile connection,

Most of modern fax-modems have Class 2 because it is easy to use and implement software support, that is why your fax-modem must be set to use Class 2 to make it possible to receive faxes using Argus as a front-end . To do this, use +FCLASS=2 (or +FCLASS=2.0 for USR modems) in modem init string to initiate Fax Class 2 operation. All other fax classes are not supported in the current version of Argus. Please refer to your modem's manual to determine the fax class supported by your modem. Note that Class 1 is not supported when using with either internal or external fax receiver.

External fax receiver software

When external software is used, and Argus launches an external fax receiver, as mentioned in External Fax Receiver string of Modem configuration dialogue. It is possible to use handshake switches as described in Doors chapter.

This is an example of Config/Dial-up/Modems setting for ZyXEL E+ modem for receiving faxes using BGFAX B.J. Guillot:

External Fax receiver
c:\bgfax\bgfax32.exe /fzyx c:\bgfax h%h z /dte:%b
Commands / Init
ATZ|AT+FCLASS=6|
Commands / Answer
AT+FAA=1;A!

Internal fax receiver software

Each mailer line now has a "Fax Inbound" fields. Received fax pages are placed there in TIFF (Tagged Image Format File). Internal Fax receiver supports both fax services Class 2 and Class 2.0.

Answer strings are generally the same as for external receiver.
For class 2 fax modems:
~AT&F|AT+FCLASS=2|AT+FLID="ID"|AT+FAA=1;a!

For class 2.0 fax modems:
~AT&F|AT+FCLASS=2.0|AT+FLI="ID"|AT+FNR=1,1,1,1|at+FAA=1;a!

It is possible to launch an external application (or set a file-flag) to handle a received TIFF fax document. Prefixes are the same as in Externals/Post-processors. Use macros to obtain a file name of received TIFF fax document:

%PATHNAME% fully-qualified file name, e.g. d:\fl\infax\03Jan003.tif
%PATH% path to the file, e.g. d:\fl\infax\
%NAME% file name (without path and extension, e.g. 03Jan003)
%EXT% file extension, e.g. .tif

Combination %PATH%%NAME%%EXT% is identical to %PATHNAME%


DTE rate problem

The most of Class 2 fax modems switch DTE rate to 19.2 Kbps on detection of the first Phase B preamble, but some modems leave DTE rate unchanged. DTE rates of the mailer and the fax modem must be synchronised. This is gained by proper setting of "Switch DTE to 19.2 Kbps" option of "Fax" tab of "Modem configuration" dialogue box. Reception of debris after +FCON or +FCO means improper DTE switch mode setting.

 

Dialling Restriction Schemes

Dialling restrictions schemes are designed to determine whether a poll is currently valid (i.e. it initiates 'phone call) for a particular dial-up line or not. Each dial-up line has its own restriction scheme; however, several lines could use one restriction scheme.

Before polling from a particular dial-up line, Argus checks whether the poll is valid according to the lines Required and Forbidden groups; the call is initiated only if the poll is valid according to both condition groups for that line.

Scheme name - name of restriction scheme (as it appears in a line Restriction scheme combo box)

Required - necessary conditions for a poll to be valid.

Forbidden - conditions making a poll invalid.

Three condition types are implemented in the current version of Argus: address mask (possibly with Regular Expressions), Nodelist flags and the beginning of a 'phone number (usually 10 or 11 digits).

Conditions in each group are divided with a space character.

Items within a row are combined with logical AND operation, rows within a grid are combined with logical OR operation.

For example:

Required
+7-095- CM 2:50*/* HST Call a node only if its 'phone number starts with +7-095- and it has CM and HST Nodelist flags and the node is in Region 50 of Zone 2
Forbidden
2:5020/666.* +7-095-212- ISDN Dont call a node if it and its boss has a node number 2:5020/666 and its 'phone number starts with +7-095-212- and it has PEP and ISDN Nodelist flags

 

Node Overrides Table

Node Overrides Table is a string grid and it is designed for re-defining (overriding) the Nodelist information (to add or override 'phone numbers, Nodelist flags and working time) for a particular node. If you want to override the 'phone number of a node or add some more numbers (in the event of a node having a multi-line mail system), you can use FTN addresses instead of 'phone numbers - in this case the 'phone numbers are taken from the Nodelist.

There are two opportunities, which the Node Overrides Table gives to the user. Firstly, there is no real need to use the Nodelist and the secondly is that it is possible to define some special flags and use them in overrides in combination with Dialling Restrictions Schemes.

If a node is not listed in the Nodelist used by Argus, but there is a Node Overrides Table entry for that node and there are no flags specified, the node is not treated as CM - all Crash or Direct packets detected in Outbound will not initiate a poll outside ZMH (moreover, point addresses will never be polled), so sending files to such node a can only be done manually. It is recommended you specify working times of a node in overrides using either the CM or Txy Nodelist flags even if that node is listed but it has no working time flags in the Nodelist. See chapter Calling a Node only within its Working Time for ZMH definitions.

Example:

Node Override Comment
55:133/561 +31-133-456-1850 Phone number has changed
55:133/562 55:133/562,U,TBK Working time has changed
5:133/555 5:133/555,U,TAB,TDE Working time has two intervals
55:133/563 55:133/563,CM,V34 Node has a new (V.34) modem
3:34/3443 333-031,CM 333-032,CM 333-033,CM This is a 3-line CM node
3:383/513 3:383/513 3:383/550 3:383/560 This node has three other AKAs (which should be taken from the Nodelist)
3:383/514 3:383/513,HST,CM 3:383/550,V34,U,TACL First line of this node is CM and second one has working time from 00:00 to 02:00 local time.

Use Override Line Editor for more comfortable editing of node overrides.

Besides of custom flags, Argus handles some special flags:

NOHYD Prevents from establishing Hydra. Hydra is a bi-directional file transfer protocol, defined in FSC-0072. See also Transmit Hydra Disabled atom.
NOZM Prevents from establishing ZModem. ZModem is a file transfer protocol. This flag is a conjunction of flags NODZA, NOZAP, NOZMO. See also Transmit ZModem Disabled atom.
NODZA Prevents from establishing DirZap. DirZap is a ZModem variation, which uses 8K-block and does not escape control characters.
NOZAP Prevents from establishing ZedZap. ZedZap is a ZModem variation, which uses 8K-block and escapes control characters.
NOZMO Prevents from establishing ZedZip. ZedZip is a ZModem variation, which uses 1K-block and escapes control characters.
NONIAGARA Prevents from establishing Niagara. Niagara protocol establishes the layer that provides BinkP (with CRAM-MD5) and Encrypted BinkP over a dial-up connection. This atom applies only to dial-up lines, not to TCP/IP daemon. See also Transmit Niagara Disabled atom.
NOEMSI Prevents from establishing EMSI handshake. See also Transmit EMSI Disabled atom.
NOYOOHOO Prevents from establishing YooHoo handshake. See also Transmit YooHoo Disabled atom.
NODUMMYZ Do not send a dummy packet on ZModem. By default (if this atom is not applied), Argus sends a dummy packet if there is nothing to send on ZModem session. See also Transmit Dummy-Z Disabled atom.

Example of using special flags:

Node Override Comment
55:133/561 55:133/561,NOHYD Do not establish Hydra protocol when dialling this node.
55:133/562 55:133/562,NOZM Do not establish ZModem protocol when dialling this node.

Auxiliary Dial-up Nodes file

You may specify here a file that defines additional overrides besides of listed in the string grid. The format of the file follows, one override per line:

Address | Override

Example:

2:469/38 | 373-2-246-530,CM,ZYX 373-7-222-222,CM,HST
3:383/514 | 3:383/513,HST,CM 3:383/550,V34,U,TACL

Auxiliary dial-up node overrides file is loading into memory on Argus Start-up and by detection of DUPOVR.OK file-flag in Argus Home Directory. Results of parsing of the file are logged in polls log.

 

Override Line Editor

Argus Override Line Editor (Config/Dial-up/Nodes/Edit) allows more comfortable editing of an override line of Node Overrides Table. The Editor allocates one line of its string grid per remote's 'phone number. It also allows human-readable Online Time representation in local time e.g. while in Node Overrides Table you should specify U,TAB,TLX, here you can simpy write 03:00-04:00,14:00-02:00 if you are in GMT+2 time zone.

 

TCP/IP configuration

This chapter explains how Argus should be configured to use TCP/IP transport. If you are using only Dial-up connections, there is no real need to read this section.

- TCP/IP Daemon
- TCP/IP Daemon configuration
- Special TCP/IP flags

 

TCP/IP Daemon

Daemon is the control centre, which simultaneously handles the dynamic creation and shutting down of TCP/IP lines, controlling outgoing polls and incoming connections.

When an incoming TCP/IP connection is detected, Daemon creates a new TCP/IP mailer line and initiates high-level file transfer protocol corresponding to the port where the connection is detected. Protocols and ports are defined in TCP/IP Daemon configuration dialogue

There are three FTN file transfer protocols implemented in Argus for working with TCP/IP:

- Raw
- Telnet
- BinkP

 

Telnet TCP/IP protocol

Telnet is the same as Raw with only difference between them is that default IP port numbers are 23 and 60177 and data transfer is made accordingly to Internet standard defined in RFC 845.
 

Raw TCP/IP protocol

In Raw TCP/IP protocol data is treated the same way as a communication port data, so file transfer protocols used during Raw TCP/IP connections are the same as protocols used for Dial-up connections. IP port number 60179 is usually used for Raw TCP/IP connections.
 

BinkP protocol

BinkP is a new transfer protocol designed especially for using IP connections for FTN developed in 1996 by Dima Maloff. This protocol does not imitate a Dial-up connection, so it allows to use maximum performance because the absence of irrelevant data transferred within Dial-up connections (such as checksums for example) and using of two-way data flow. The default IP port number for BinkP is 24554. BinkP could be used over Dial-up as well. In that case Niagara algorithms would be used on Transport Layer. BinkP allows flow encryption and CRAM-MD5.
 

Encrypted BinkP-Sesstion

Argus Mailer introduces an optional encryption layer between Transport Layer (TCP or Niagara) and Protocol Layer (BinkP). Note that encryption sessions require CPU overhead.

Encrypted sessions are setting up in Config/Encrypted Links. This dialogue allows specifying the nodes that are allowed to connect using encrypted session only. You must also specify the password for the link, which is after the input rendered to DES 56-bit session key and stored to config.bin. We recommend using Master Password as one of solutions to prevent encrypted links' keys from being stolen with config.bin. If you would forget the link's password, there would be no easy practical way to retrieve it.
 

CRAM-MD5

Challenge-Response Authentication Mechanism (CRAM) allows to avoid transmitting cleartext, reusable passwords since it utilises MD5 Message Digest Algorithm.

CRAM is used by default on BinkP if the remote mailer also supports CRAM. Usage of CRAM on other protocols (FTS-0001, ZModem, Hydra) is not supported.

Please not that if using CRAM, passwords are case-sensitive.

 

TCP/IP Daemon configuration

TCP/IP Daemon configuration dialogue is invoked with Config / TCP/IP Daemon menu command.


General

TCP/IP connection parameters are configured here.

The Incoming Ports string grid allows you to set-up TCP/IP ports which should be checked by TCP/IP Daemon to receive incoming connections. Each of three currently available protocols could be set for a number of TCP/IP ports - use space characters to divide port numbers in the string grid entry. If there are no ports set for a protocol, the protocol is not used by Argus for receiving incoming connections.

Argus can also use SOCKSv4 proxy server.


Station

This is the information about the system which will be transferred in the handshake packet. This information is almost the same as EMSI data, but if you are planning to connect with systems which are using BinkD by Dima Maloff, you should configure addresses in the Address List as 5-D FTN addresses (5-D FTN address is the 4-D FTN address plus '@' character and network name after it; e.g.: 2:469/38.77@fidonet.org) - if an address is not transferred in 5-D format, BinkD may refuse the connection.


Restrictions

These are the restrictions for outgoing connections. The principles of these restrictions are similar to those of Dialling Restrictions schemes

Required - conditions necessary for a poll to be valid. All the conditions stated must be satisfied to make a poll valid. If there are no conditions stated, a poll is valid.

Forbidden - conditions making a poll invalid. If at least one of the conditions stated is satisfied the poll is invalid. If there are no conditions stated, a poll is valid.

Two condition types are implemented in the current version of Argus: address mask (possibly with Regular Expressions) and Nodelist flags.


Nodes

This string grid has the same purpose as Node overrides table , the only difference is that instead of telephone numbers IP addresses are used (it is possible to use symbolic addresses as well as digital ones) and it is possible to define IP port numbers which are available on a particular node.

Symbolic IP address should be enclosed in quotation marks, e.g.: 193.219.215.11 or "fido.ritlabs.com". If a non-standard IP port is used, its number should be put after the IP address followed by underline, e.g.: 193.219.215.11_60177 or "fido.ritlabs.com"_60177.

Flags specific for a particular node could be obtained from an IP Nodelist (the basic difference between conventional and IP nodelists is the use of IP addresses instead of 'phone numbers) or defined directly in the overrides.

You may specify an auxiliary nodes file, which defines additional overrides besides of listed in the string grid. The format of the file follows, one override per line:

Address | Override

Example:

2:469/38 | "fido.ritlabs.com",CM,BND
3:383/514 | "fido.host.com",CM,IFC "fido.host.com",CM,TELNET

Auxiliary TCP/IP node overrides file is loading into memory on Argus Start-up and by detection of IPOVR.OK file-flag in Argus Home Directory. Results of parsing of the file are logged in polls log.

DNS

Argus also supports DNS distributed nodelists.

IP addresses of FTN nodes can be from DNS by rendering their FTN addresses to host domain name and resolving this name. The rendering is performing by the following scheme:

[p<Point>.]f<Node>.n<Net>.z<Zone>.<RootDomain>

The default root domain for Fidonet-reserved FTN-zones (1,2,3,4,5,6) is fidonet.net. E.g., the IP address of node 1:2/3.4, according to this scheme, is to be the same as of host p4.f2.n3.z1.fidonet.net.

Root domains for each address mask are configured in DNS tab of TCP/IP Daemon Configuration dialogue. Address mask may also contain Regular Expressions.

Here are parts of a FAQ on fidonet.net domain. The most recent list is available at:

http://www.doe.carleton.ca/~nsoveiko/fido/fido-over-ip.FAQ.english.html#fidonet.net

Q? What is fidonet.net?
A: fidonet.net is an Internet domain registered to facilitatedevelopment and deployment of fido-over-internet technology of all kinds and flavours.
Q? How fidonet.net sub-domain and host names are assigned?
A: Sub-domain and host names are formed in the same way as for the fidonet.org domain. For example, if your 4D Fidonet address is A:BBB/CCC[.DDD], then your domain address would be [pDDD.]fCCC.nBBB.zA.fidonet.net. Such unique address mapping allows one to obtain a node's IP address knowing only it's FTN address.
Q? What is the difference between fidonet.net and fidonet.org than?
A: Fidonet.org domain was registered with the purpose of exchanging mail between Internet RFC822-style and Fidonet mail systems. In other words, hosts in the fidonet.org domains are Fidonet-Internet gateways that are supposed to accept mail by both SMTP and FTS-0001 (or, better EMSI) protocols. There is no such restriction on hosts in fidonet.net domains (see below). Technology developed and tested in fidonet.net domain in the future might migrate to the fidonet.org domain subject to approval of the latter's administration.
Q? What do I do to get a fidonet.net host name?
A: Your system should have binkp capability. This protocol is currently supported by binkd and Argus mailers. You should contact a person who is responsible for DNS in your Fidonet network. You can use nslookup to figure out if your network already has a DNS server. If there is none, please contact Fyodor Ustinov, 2:5020/79, ufm@prospect.com.ru to arrange a DNS record for you.
Q? I am using Vmodem. Why should I install something else in order to be listed in fidonet.net?
A: Common sense is that Fidonet systems should be able to exchange mail directly. In order to make this possible, they should support some protocol which will be the least common denominator for a given transport. FTS-0001 is such a protocol for conventional dial-up transport. Vmodem-based technologies do not make a good candidate for the least common denominator protocol because for many platforms these technologies are not free they merely adapt dial-up technology for TCP/IP transport retaining many drawbacks of the former and without taking full advantage of the latter. On the contrary, binkp is an open specification protocol designed to operate over reliable connections with unpredictable delays (such as TCP connections) has a portable implementation that is distributed in sources under terms of GNU public license. So, it seems to be a natural choice for the least common denominator protocol.

 

File-boxes

Binkley-Style Outbound is not the only place where outgoing files are kept. It is possible to associate a separate directory for storing outgoing files for each node. Argus periodically scans these directories. If a program of the sysop copies files to this directory, the files would be attached to the node using the status corresponding to this directory.

Use Config/File-Boxes dialogue box (Ctrl+B) to set up file-boxes.

Options/Root directory input line of this diallog allows to define a root for all file-box directories listed in Nodes/Path string grid. The rules of adding Root directory to file-box directory are the same as for Home Directory of Config/Paths.

Value of string of a Node column may be a valid FTN address or a Pure Address Mask (i.e. such address mask cannot combine both asterisk and digit characters without a separator, e.g. 2:*/*.* is allowed and 2*:*/*.* is not allowed) or Regular Expression.

Value of string of a Status column may be one of the following:

C Crash-status file-box
D Direct-status file-box
N Normal-status file-box
H Hold-status file-box
* Any-status file-box

Value of string of a Path column may contain macros.

%ZONE FTN zone in decimal (1-4 decimal digits)
%NET FTN network in decimal (1-5 decimal digits)
%NODE FTN node in decimal (1-5 decimal digits)
%POINT FTN point in decimal (1-5 decimal digits)
%HZONE FTN zone in hex (3 hex digits)
%HNET FTN net in hex (4 hex digits)
%HNODE FTN node in hex (4 hex digits)
%HPOINT FTN point in hex (4 hex digits)
%XZONE FTN zone in radix-32 (2 radix-32 digits)
%XNET FTN net in radix-32 (3 radix-32 digits)
%XNODE FTN node in radix-32 (3 radix-32 digits)
%XPOINT FTN point in radix-32 (2 radix-32 digits)
%STATUS Status (C=Crash, D=Direct, N=Normal, H=Hold)
%TSTATUS Same as %STATUS, but empty value represents Normal status.
%STMAIL Same as combination %XZONE%XNET%XNODE.%XPOINT%TSTATUS
%LTMAIL Same as combination %ZONE.%NET.%NODE.%POINT?%TSTATUS

As you see, macros are used to bound a path to particular nodes if value of string of a Node column contains a mask or Regular Expression. To be able to bind multiple directories to a node, value of string of Path column may also contain *, ?, % wildcards or Regular Expressions.

Value of string of a Path column may contain additional path (separated by pipe ("|") character) to where files sent from this file-box will be moved. For reliable operation the files are moved, not copied.

Example: c:\ab\out|c:\ab\sent

This path is called sent path. Make sure that file-box and sent path directories are on the same physical drive or volume in order Win32 API MoveFile() function would not fail with error "The system cannot move the file to a different disk drive".

If not sent path is specified, files would be deleted after successful transfer.

Sent path may contain additional macros, representing current local date.

%YEAR Year in decimal (4 digits).
%MONTHN Month in decimal (2 digits), 1 = January, 2 = February, etc.
%MONTHA Month in abbreviation (3 letters), Jan = January, etc.
%MONTHS Month in short abbreviation (2 letters), Jn = January, etc.
%DAY Day of month in decimal (2 digits).
%DOWN Day of week in decimal (1 digit), 0 = Sunday, 1 = Monday, etc.
%DOWA Day of week in abbreviation (3 letters), Sun = Sunday, etc.
%DOWS Day of week in short abbreviation (3 letters), Su = Sunday, etc.
%HOUR Hour in decimal (2 digits).
%MINUTE Minute in decimal (2 digits).
%SECOND Second in decimal (2 digits).

Files in file-boxes are displaying in Outbound Manager Tab, but no operation is permitted on them via Outbound SmartMenu. SmartMenu only applies to files attached via Binkley Outbound.

Example of File Boxes configuration grid:

Node Status Path
2:469/38 N out38|sent38

Root directory: c:\fl

In this case, files that are copied to c:\fl\out38 directory will be automatically attached to node 2:469/38 with normal status. This means, according to Normal status, that all the files from the directory will be transmitted to the node on either incoming or outgoing call. After successful transmission, files will be moved to c:\fl\sent38 directory.

Another example, now using a macro:

Node Status Path
2:469/*.0 N out%NODE|sent%NODE

In this case, file-box for 2:469/38 will be out38, same as in previous example, but we are also defining file-boxes for all nodes of 2:469. File-box for 2:469/39 will be out39, for 2:469/40 will be out40, and so on.

To define T-Mail-compatible file-boxes tree in c:\t-mail\fboxes, use the fillowing:

Node Status Path
*:*/*.* * c:\t-mail\fboxes\%STMAIL

 

Special TCP/IP Nodelist flags

TCP Accordingly to IP Nodelist standard (which is used in regions 46, 50 of zone 2), this flag is required to show that node is able to receive incoming TCP/IP connections. Argus may ignore the absence of this flag - using of IP-address instead of 'phone number is enough.
IFC Raw (ifcifo) (the default port number is 60179)
TEL or TELNET Telnet (the default port number is 23)
BND or BINKD BinkP (the default port number is 24554)

There are also special flags, described in Node Overrides section.

 

Cron

Cron format is a simple but powerful way of describing periods.

Format

* * * * * or Minute Hour Day Month DayOfWeek

Range
Minute 0-59
Hour 0-23
Day 1-31
Month 1-12
DayOfWeek 1-7 (1 = Monday, 2 = Tuesday, ..., 7 = Sunday)

You can also use a list of values, separated by commas e.g. "1,3,7", or using dash character to specify a range “1-5”. You can also specify an asterisk character - it defines a full range of values.

The item runs only if all criterias are fulfilled.

Examples:

* * * * * Every minute.
59 23 31 12 5 One minute before year's end, and only if the last day is a Friday.
45 17 7 6 * Every year at 17:45 on June 7th.
0,15,30,45 0,6,12,18 1,15,31 * * On every full quarter of an hour at midnight, 6 in the morning, noon, 6 in the evening on the 1st, 15th and 31st of every month on weekdays only.
0 12 * * 1-5 At noon on every day, if it is a weekday.
* * * 1,3,5,7,9,11 * Every minute in January, March, May, July, September and November.
1,2,3,5,20-25,30-35,59 23 31 12 * At the last day of the year at 23:01, 23:02, 23:03, 23:05, 23:20, 23:21, 23:22, 23:23, 23:24, 23:25, 23:30, 23:31, 23:32, 23:33, 23:34, 23:35, 23:59.
0 9 1-7 * 1 On every first Monday of a month, at 9 o'clock in the morning.
0 0 1 * * At midnight on every month.
* 0-11 * * * Every minute till midnight.
* * * 1,2,3 * Every minute in January, February, March only!
0 0 * * * Execute every day at midnight.
0 0 * * 3 Every Wednesday at midnight!

Removing rightmost asterisks can shorten Cron string:

Full notation Shortened notation
* * * * * *
59 23 31 12 5 59 23 31 12 5
45 17 7 6 * 45 17 7 6

0,15,30,45 0,6,12,18 1,15,31 * * 0,15,30,45 0,6,12,18 1,15,31
0 12 * * 1-5 0 12 * * 1-5
* * * 1,3,5,7,9,11 * * * * 1,3,5,7,9,11
1,2,3,5,20-25,30-35,59 23 31 12 * 1,2,3,5,20-25,30-35,59 23 31 12
0 9 1-7 * 1 0 9 1-7 * 1
0 0 1 * * 0 0 1
* 0-11 * * * * 0-11
* * * 1,2,3 * * * * 1,2,3
0 0 * * * 0 0
0 0 * * 3 0 0 * * 3

Cron step values can be used in conjunction with ranges. Following a range with "/<number>" specifies skips of the number's value through the range. For example, "0-23/2" can be used in the hours field to specify command execution every other hour (the alternative of previous standard is "0,2,4,6,8,10,12,14,16,18,20,22"). Steps are also permitted after an asterisk, so if you want to say "every two hours", just use "*/2".

 

File Requests Configuration


General


Main settings of File Requests service.

This string grid is designed to specify directories with files that may be requested within file transfer sessions (file base). It is possible to protect files of a particular directory with a password so a requesting system must send the same password whenever it requests a file from that directory. Please note that passwords are passing to remote in non-secure manner as a cleartext. Password comparing is case-sensitive.

Disable all requests All file requests are denied if the box is ticked. NRQ flag will be sent by Argus in EMSI packet to advise a calling system not to send REQ files.
Recursive paths Search for files recursively in all sub-directories of directories specified in the Requested directories grid. The depth of recursion is not limited.
Allow Masks Allow file requests with Wildcards and Regular Expressions. There are some notes on using WildCards. User may request *.jpg to receive all JPEG files from directories, specified in the Requested directories grid. Complex masks (e.g. DOOM*2_%.*) are also supported. Besides * and ?, there is a support of % mask character, that allows any digit on its position. Masks are allowed only in name portion of file, not in path portion. E.g. c:\games\*.* is valid but c:\games\*\readme.txt is invalid. Also, for requesting a file, caller must not specify path portion of the file.
Real-time search Search for files during file transfer session. If it is off, Argus builds and index file for requestable files and gets the information from there - it is faster for large file bases, but it requires re-compilation of the index file each time the file base is updated.

Aliases

Argus allows callers to request files using Aliases (also called magic names), a caller does not need to know the real name of files requested. For example, FidoNet Nodelist is requestable from most FidoNet nodes as NODELIST while the real name of the Nodelist file is changing every week. Another example is the file list of a system, which is often requested using the Alias FILES.

Aliases are defined in Aliases string grid; Path column contains full path names of files to be sent for a particular Alias request, divided with a comma, space or semicolon; The Password column contains an optional password for each Alias entry. Password comparing is case-sensitive.

Wildcards and Regular Expressions are also allowed in Aliases string grid. The rules of using wildcards are the same as for Allow Masks checkbox of General tab (see above). When using wildcards, you may also specify > prefix before the file name. It will select the only newest (by modification date) file from the masked list.

Example of Aliases string grid with NODEDIFF alias for the latest nodediff.

Alias Path
NODEDIFF >R:\AF\NODELIST\NODEDIFF.Z%%

External Request Processing (SRIF)

Argus has an external file request processing support using SRIF (Standard Request Information File), developed by Gordian Schuermann & Mirko Mucko.

External request processing is enabled or disabled using option Use SRIF. When this option is set, all other options above mentioned in this chapter are disabled, and all file requests are processed by the External Request Processor (ERP), not by Argus. The objective of SRIF method is to pass as a command line argument to ERP the name of temporary SRIF-file (which is created and erased after it is used, by Argus), containing all necessary information about files being requested.

The ERP file name and command line parameters are configured in Standard Request Information File - External Processor field. Special keyword %SRIF%, used only in this field, is being replaced to the name of temporary SRIF-file

This is an example of using AllFix © Harms Software Eng. as an ERP:
c:\fido\allfix\allfix.exe Rp -SRIF %SRIF%

Question Mark character (“?”) before file name instructs to execute the process in hidden mode. Exclamation Mark character (“!”) instructs to execute the process in normal window mode. Detached mode can be used only for launching Win32 console applications. Double Question Mark (“??”) instructs to execute the process in DETACHED mode (without using console window) . An attempt to execute DETACHED Win3.1 or DOS application causes an error.

Processes can be launched with the following priority levels:

< Low (IDLE_PRIORITY_CLASS)
+ High (HIGH_PRIORITY_CLASS)
* Real-time (REALTIME_PRIORITY_CLASS)

Processes are executing with normal priority (NORMAL_PRIORITY_CLASS) in minimised window by default.

 

Address masks

The asterisk character (*) is used to group addresses with a mask.

Example:

1:*/*.* All addresses in Zone 1
2:46*/*.* All addresses in Region 46 of Zone 2
2:469/* Same as 2:469/*.* - all nodes and points in Net 469 of Zone 2
2:469/*.0 All 3-D nodes in Net 469 of Zone 2 (without points)
2*:50*/10* All nodes with node numbers starting with 10 (e.g.: 10, 102, 1001 etc.) in all Nets with numbers starting with 50 (e.g.: 500, 5020, 501 etc.) of all Zones with numbers starting with 2 (e.g.: 2, 22, 21, 202 etc.)
*:*/* All FTN addresses

 

Polls

Polls are configuring by dialogue box Config/Polls. The box contains three tabs.


Periodical

Argus has an ability to create polls automatically, using Cron-periods. Polls created with cron are identical to polls, created by Outbound, and are disposed after a successful outgoing session with poll destination node.

If a periodical polls appeared when a poll to specified destination node already exists, all counters (Busy / No Carrier / No Answer) of this poll are zeroed.

See also Poll Manager.


Options

The values of Busy, No c. and Fail fields are used as maximal values of poll counters, when reached, the poll is set to Stand-off (Idle) mode.

Retry Seconds field sets the number of seconds to wait before making next poll. The actual time length of Retry and Stand-off intervals is a random value within 0.5*n .. 1.5*n, or saying in other words, +-50%. For example, when Retry Seconds value is set to 100, the polls would be repeated with a random interval from 50 to 150 seconds. The tolerance interval of 50% is used to make polling more efficient - from the probability point of view.

Transmit hold on outgoing allows hold-flavoured bundles to be transmitted to remote during an outgoing connection.

The resume is that maximal values of poll counters are configuring here. When the value is reached, the poll falls asleep on “Stand-Off minutes”, else the poll would be redialled again after at least “Retry seconds”. Transmit Hold on outgoing defines whether hold-attaches would be transferred on outgoing sessions or not.


External

External polls allow executing an external application instead of polling nodes, specified in Address list (you may use address masks and Regular Expressions here) field of the dialogue. Application string format is the same as in Config/Externals/Doors or Config/Dial-up/Modems/External Fax Receiver, i.e. all Handshake Switches are applied and new introduced (as well as environment variables):

%w ARGUS_NODE External poll's node address, eg "2:469/38"
%x ARGUS_STATION Station name from nodelist, if applies
%v ARGUS_LOCATION Site location from nodelist, if applies
%X ARGUS_SYSOP Sysop's name from nodelist, if applies
%y ARGUS_PHONE Phone number or IP address from nodelist or overrides
%Y ARGUS_FLAGS Node flags from nodelist or overrides
%W ARGUS_SPEED Node speed from nodelist, if applies

Options' format is:

OkRange BusyRange NoCRange FailRange TimeoutMinutes TimeoutExitCode

It is possible to use enumerations and intervals in Ranges, (like as in cron). eg "1,3,9-15". They also can be skipped by "." (point) character. If none of values matches, the poll is considered to be completed OK. E.g., options field "0 1 2,5-7 3,4 10 8" means that an external poll is OK when the application returns exit code 0, busy on exit code=1, no connect on 2,5,6,7 and fail on 3,4. "10" means than the application would be terminated after 10 minutes of its execution, if it would not exit by itself. If the application was terminated by time-out, its exit code is set to TimeoutExitCode, i.e. 8 in the example above. The default value of TimeoutExitCode (if missed) is 1. If TimeoutMinutes value missed, the application would only exit by itself (if it would).

 

Events

Event is designed to change some parameters (such as modem init strings, minimal allowed connect speed and so on) of the mailer line it is linked to.

Event has a cron-period, length of activity and atom list.

Opposite to periodically-launching applications and periodical polls, which are also using cron periods, event has no global influence on mailer - it changes some parameters of only lines it is linked to.

Atom - is an item that changes one mailer line option.

Thus, event that changes modem init string and required condition of dialling restriction, must contain two atoms: Modem Command Init Atom and Restrictions Required Atom.

Event changes parameters of only those lines, to which it is linked!

To link an event to a line use Events page of Mailer Line Configuration dialogue of Config / Dial-up menu.

See also:
Cron,
Atoms reference

 

Atoms

Atom is an item of event that changes one mailer line option.

Thus, event that changes modem init string and required condition of dialling restriction, must contain two atoms: Modem Command Init Atom and Restrictions Required Atom.

This is a list of atoms, currently supported by Argus:

Modem Command Init Modem Init String.
Can be used, for example, for disabling modem speaker in appropriate time, or for setting some protocol initialisation strings according a schedule. This atom applies only to dial-up lines, not to TCP/IP daemon.
Modem Command Answer Modem Answer String.
Most commonly used to set-up an appropriate protocol for incoming connections according a schedule. This atom applies only to dial-up lines, not to TCP/IP daemon.
Modem Command Prefix Modem Dial Prefix String.
Most commonly used to set-up an appropriate protocol for outgoing connections according a schedule, or when working via office 'phone system. This atom applies only to dial-up lines, not to TCP/IP daemon.
Modem Command Suffix Modem Dial Prefix String. This atom applies only to dial-up lines, not to TCP/IP daemon.
Modem Command Hang-up Modem Hang-up Command String.
This usually applied in conjunction with Modem Command Init Atom. This atom applies only to dial-up lines, not to TCP/IP daemon.
Modem Disable Reinit Do not re-initialise a modem automatically. By default (if this atom is not applied), a modem is re-initialising after two minutes of inactivity. This atom applies only to dial-up lines, not to TCP/IP daemon.
Restriction Required
Restriction Forbidden
Required/forbidden restriction strings.
Can be used, when working with telephone companies, which vary cost of outgoing calls according to time of day. This atom can also be used with stations that work according to a specified schedule.
Replace Station Change all station settings to a new template from Config /Dial-up / Modems.
Used on nodes that works depending on schedule. This atom applies only to dial-up lines, not to TCP/IP daemon.
Replace Modem Change all modem settings to a new template from Config /Dial-up / Station.
Used that modem works with different settings to a specified schedule. Note, that when using this atom, communication port still lefts unchanged. This atom applies only to dial-up lines, not to TCP/IP daemon.
Replace Restriction Replace restriction scheme to another one from Config / Dial-up / Restrictions.
Can be used instead of two atoms: Restriction Required and Restriction Forbidden. This atom applies only to dial-up lines, not to TCP/IP daemon.
Accept Files Required
Accept Files Forbidden
Files required / forbidden for receiving.
Can be used in ZMH to prevent receiving other files but FTS-0001 or P2K mail packets. (see chapter Calling a Node only within its Working Time for ZMH definitions.
Accept Nodes Required
Accept Nodes Forbidden
Nodes, required/ forbidden to establish incoming connection with.
Can be used on hubs with time-shared access.
Accept Nodes Only Pwd-Prot Allows only password-protected incoming sessions. Non-password-protected incoming connections would be dropped. This atom doesnt affect outgoing connections.
Accept Link Required
Accept Link Forbidden
Link codes, required / forbidden for incoming connection.
Link codes are enumerated through spaces. E.g. HST ARQ.
Can be used for bouncing connections without error correction protocols.
Accept Speed Min Minimal allowed speed of incoming connections. This atom applies only to dial-up lines, not to TCP/IP daemon.
Transmit Speed Min Minimal allowed speed of outgoing connections. This atom applies only to dial-up lines, not to TCP/IP daemon.
Accept FReq Disable Refuses processing of incoming file requests.
Accept FReq Duration Pwd-Prot
Accept FReq Duration Public
Limits session duration for file request. While serving a file request, Argus attaches files until the period of time needed to transfer these files do not exceed the number of minutes specified in the atom. Connection speed is used to calculate the time needed to transfer files. This atom limits the maximal number of requested files per session, by approximate session duration, but do not affect session duration, if, for example, transfer speed felt down during a session.
Accept FReq Size Pwd-Prot
Accept FReq Size Public
Limits the total size of files for file request. While serving a file request, Argus attaches files until the total size of attached files do not exceed the size specified in the atom.
Accept FReq Count Pwd-Prot
Accept FReq Count Public
Limits the number of files for file request. While serving a file request, Argus attaches files until the number of attached files do not exceed the value specified in the atom.
Rings Number of rings to answer.
(0 = disable automatic answers)
Transmit Files Forbidden
Transmit Files Required
Controls outgoing files. Similar to Accept Files Required/Forbidden. Note that these two atoms do not affect on File Requests (.REQ) and Crash-Flavoured attaches (.CLO/.CUT)
Accept Niagara Disabled
Transmit Niagara Disabled
Prevents from establishing Niagara. Niagara protocol establishes the layer that provides BinkP (with CRAM-MD5) and Encrypted BinkP over a dial-up connection. This atom applies only to dial-up lines, not to TCP/IP daemon.
Accept Hydra Disabled
Transmit Hydra Disabled
Prevents from establishing Hydra. Hydra is a bi-directional file transfer protocol, defined in FSC-0072.
Accept ZModem Disabled
Transmit ZModem Disabled
Prevents from establishing ZModem. ZModem is a file transfer protocol.
Accept FTS-0001 Disabled Prevents from establishing FTS-0001.
Accept No Incoming Use serial port for outgoing call only. During the activity of this atom, serial port is used for outgoing calls only. In the remaining time other applications rather than Argus can use the port. This atom applies only to dial-up lines, not to TCP/IP daemon.
Accept YooHoo Disabled
Transmit YooHoo Disabled
Prevents from establishing YooHoo handshake.
Accept EMSI Disabled
Transmit EMSI Disabled
Prevents from establishing EMSI handshake.
Door Additional door. Adds specified door enter string and executable to the active list of doors (Config/External/Doors).
Password Additional password. Adds specified node password to the active list of passwords (Config/Passwords).
Accept Dummy-Z Disabled
Transmit Dummy-Z Disabled
Do not send a dummy packet on ZModem. By default (if this atom is not applied), Argus sends a dummy packet if there is nothing to send on ZModem session.
Input WatchDog Reset Resets the line.
Input WatchDog ExtApp Executes specified External Application.
Accept Nodes Only Listed Accept calls Only from addresses Listed in nodelist or Argus passwords or overrides.
Input Log Format Scans data came from modem, and if it matches Regular Expression, formats the data and logs.
Response Log Format Works the same way as Input Log Format atom except it does only scan data came from modem after Answer or Info commands.
Accept BPS Efficiency Min Percent of minimal BPS efficiency on incoming connections.
Transmit BPS Efficiency Min Percent of minimal BPS efficiency on outgoing connections.
Log EMSI Data Turns logging EMSI of data on.
Accept CPS Min Minimal CPS on incoming connections.
Transmit CPS Min Minimal CPS on outgoing connections.
Accept Duration Max Maximal duration of incoming session in minutes.
Transmit Duration Max Maximal duration of outgoing session in minutes.

Example on Response Log Format Atom

This example is for ZyXEL U1496 E+ modem (taken from Bink/+ Config File by Vsevolod Fedotov)

Modem|General/Commands|Info:

ATI2|

Response Log Format Atom, Regular Expression:

ZyXEL U-MODEM LINK STATUS REPORT\s*
Chars Sent *(\w+) *Chars Received *(\w+)\s*
Octets Sent *(\w+) *Octets Received *(\w+)\s*
Blocks Sent *(\w+) *Blocks Received *(\w+)\s*
Blocks Resent *(\w+) *Max Outstanding *(\w+)\s*
Max Block Size *(\w+) *Retrains Requested *(\w+)\s*
Link Duration *(\w+) *Retrains Granted *(\w+)\s*
T401 Timeouts *(\w+) *T402 Timeouts *(\w+)\s*
FCS Errors *(\w+) *Round Trip Delay *(\w+)\s*
Xmitter Underrun *(\w+) *Receiver overrun *(\w+)\s*
Last Speed/Protocol *(.+)\b\s*
Disconnect Reason *(.+)\b\s*

Response Log Format Atom, Format Specifier:

Was $19 during $11 min, RTT=$16 T
Tx/Rx: $1/$2 chrs, $3/$4 octs, $5+$7/$6 blks
Retrains $10/$12, Timeouts $13/$14, FCS Errors $15, Overruns $17/$18
Disconnect reason: $20

See also:
Events
Poll manager
Configuring Argus

 

External applications configuration

Argus currently supports three types of external applications:

Post-processors
Doors
Periodically-launching applications

Post-processors, doors and periodically launching applications are configuring in Config / Externals dialogue.

 

Post-processors

Post-processors configuration section used to define external applications, which are starting after the completion of file transfer session and to define incoming file-boxes.

External Applications
Post-processors are the applications intended to do some job with received files after the session finishes. The examples of post-processors are echo tossers, netmail trackers, file-echo processors etc. To make a Post-processor starting after the session if particular files are received, you should specify the mask filter for those files (list of file masks or Regular Expressions, divided by space character) in "Mask list" field.

%ARCMAIL% special keyword is equivalent to ArcMail mask list (*.su? *.mo? *.tu? *.we? *.th? *.fr? *.sa?).

Mask list String to execute Comment
*.su? *.mo? *.tu? *.we? *.th? *.fr? *.sa? c:\fido\lanius\squish.exe in out squash Execute Squish echo-mail processor after receiving mail bundle
%ARCMAIL% c:\fido\lanius\squish.exe in out squash Execute Squish echo-mail processor after receiving mail bundle
*.tic c:\fido\fileecho\allfix.exe file -tossbad Execute Allfix file-echo processor after receiving TIC file

You may use the following prefix characters to change the visibility mode or priority level of an external application.

Question Mark character (“?”) before command/file name instructs to execute the process in hidden mode. Exclamation Mark character (“!”) instructs to execute the process in normal window mode. Detached mode can be used only for launching Win32 console applications. Double Question Mark (“??”) instructs to execute the process in DETACHED mode (without using console window) . An attempt to execute DETACHED Win3.1 or DOS application causes an error.

Processes can be launched with the following priority levels:

< Low (IDLE_PRIORITY_CLASS)
+ High (HIGH_PRIORITY_CLASS)
* Real-time (REALTIME_PRIORITY_CLASS)

Processes are executing with normal priority (NORMAL_PRIORITY_CLASS) in minimised window by default.

It is also possible to run an external application after the session with a particular node or a list of nodes. Just specify the node address or a mask in Mask List field. You can also specify a combination of addresses and file masks in a single field. The items of such a list are combined with logical OR operation.


Incoming File-Boxes

Post-processors configuration section is also used to define incoming file-boxes. Argus makes possible to dispatch incoming files to several inbound directories, depending to remote's primary address or file name wildcard. Ampersand ('&') character, preceding the string of "String to execute" field of Config/Externals/Post-processors is used to define that the files with conditions (remote's primary address or file name wildcard) matched in "Mask list" field must be placed in the inbound directory defined after the '&' character rather than putting into Secure/Insecure inbound.

This is an example of moving files, received from points of node 2:469/59, to INPNT directory.

Mask list String to execute
2:469/59.* &INPNT

To moving files with overriding a file that is already stored in incoming file-box, use '^' character after ampersand character, e.g. &^INPNT.

Value of string of a incoming file-box path name may contain macros, representing primary address of remote system:

%ZONE zone in decimal (1-4 decimal digits)
%NET network in decimal (1-5 decimal digits)
%NODE node in decimal (1-5 decimal digits)
%POINT point in decimal (1-5 decimal digits)
%HZONE zone in hex (3 hex digits)
%HNET net in hex (4 hex digits)
%HNODE node in hex (4 hex digits)
%HPOINT point in hex (4 hex digits)
%XZONE zone in radix-32 (2 radix-32 digits)
%XNET net in radix-32 (3 radix-32 digits)
%XNODE node in radix-32 (3 radix-32 digits)
%XPOINT point in radix-32 (2 radix-32 digits)

Also, the following macros, representing current local date are allowed for incoming file-box path:

%YEAR Year in decimal (4 digits).
%MONTHN Month in decimal (2 digits), 1 = January, 2 = February, etc.
%MONTHA Month in abbreviation (3 letters), Jan = January, etc.
%MONTHS Month in short abbreviation (2 letters), Jn = January, etc.
%DAY Day of month in decimal (2 digits).
%DOWN Day of week in decimal (1 digit), 0 = Sunday, 2 = Monday, etc.
%DOWA Day of week in abbreviation (3 letters), Sun = Sunday, etc.
%DOWS Day of week in short abbreviation (3 letters), Su = Sunday, etc.
%HOUR Hour in decimal (2 digits).
%MINUTE Minute in decimal (2 digits).
%SECOND Second in decimal (2 digits).

Note that launching external application or sorting incoming files to file-boxes, based on remote address, when address mask is listed, only occur on password-protected session.

 

Doors


Doors

Doors are special communication programs, that can be called from an FTN Mailer when a special character sequence is received instead of an FTN handshake packet. If a user calls an Argus-hosted system using a generic terminal program, he/she can enter such door program by typing such sequence. There is no special limitation for number of Doors could be called from Argus; if you want callers to know what Doors can be started, be sure that you have put such information in the Banner of a Mailer Line.

The most common enter sequence for BBS programs is two escape characters. Because escape character is not printable, backslash character should be used instead.

"Door and parameters" field contains path to a door's executable file and handshake switches.

Question Mark character (“?”) before file name instructs to execute the process in hidden mode. Exclamation Mark character (“!”) instructs to execute the process in normal window mode. Detached mode can be used only for launching Win32 console applications. Double Question Mark (“??”) instructs to execute the process in DETACHED mode (without using console window) . An attempt to execute DETACHED Win3.1 or DOS application causes an error.

Processes can be launched with the following priority levels:

< Low (IDLE_PRIORITY_CLASS)
+ High (HIGH_PRIORITY_CLASS)
* Real-time (REALTIME_PRIORITY_CLASS)

Processes are executing with normal priority (NORMAL_PRIORITY_CLASS) in minimised window by default.


Handshake Switches

The Door command line may contain special switches that are translated into appropriate string values before the external application is started. Each command switch starts with the percent symbol followed by a command character. All handshake command line switches are case sensitive, for example %c may not be used instead of %C.

This is an example of "Door and parameters" line translation into appropriate execution string, DTE rate is 57600, DCE rate is 21600, mailer line number is 2 and the port handle is 64:

Door and parameters d:\max\maxn.exe -s%b -b%B -n%n -p%h
Translated execution string d:\max\maxn.exe -s57600 -b21600 -n2 -p64

Even if there no command switches were specified, Argus still creates Environment variables, which could be used by launched application:

Environment
Description
Dial-up value
TCP/IP value
%B ARGUS_DCE
Connect speed
DCE (modem to modem)
as assumed in TCP/IP Daemon configuration dialogue box
%b ARGUS_DTE
Port speed
DTE (computer to modem)
same as %B
%e ARGUS_CONNECT
Connect string (spaces replaced to underlines)
as returned after modem CONNECT word, e.g.:
"16800/ARQ/HST
as returned after Argus TCP/IP CONNECT word, e.g.:
"To 194.213.233.33 #24554”]
%E ARGUS_CONTROL
Translated error control code
"MNP" if any of MNP, ARQ or REL string is present in the connect string. Otherwise null.
Always "TCP/IP"
%L ARGUS_NAME
Mailer line name (spaces replaced to underlines)
as in dial-up/lines/line name
"TCP/IP" plus number of TCP/IP connections, e.g.: "TCP/IP 3"

%n ARGUS_LINE
Mailer line number
Number of entry in dial-up/lines list, e.g. "1" for the first line listed.
Number of active TCP/IP connection, e.g. "2" for "TCP/IP 2" line
%h ARGUS_HANDLE
Communication resource handle
COM port Win32 handle
WinSock2 overlapped socket handle
%C ARGUS_NUMBER
Port number
COM port number, e.g.: "1" for COM1 or "4" for COM4
TCP/IP port number, e.g.: 24554 for BinkD
%p ARGUS_INDEX
Port index
zero-based COM port number, e.g.: "0" for COM1 or "3" for COM4
same as %C

If an external application is a true Win32-executable, it can inherit Win32-handle of an open communication port (or of connected Winsock2 overlapped socked) and use it for data transfer.


Special %Z switch

%Z switch is always translated to an empty string - it is intended to instruct Argus to close the communication port before executing of an external application, and to re-open the port after the application terminates. Z% switch is designed for launching of Windows 3.1 and DOS applications which are unable to operate with Win32-handles, so they must open and initialise the port by themselves.

Parameter %Z must be used with great care, because modem control signals (including DTR) are dropped by Windows communication driver when closing port. Most of modems used DTR dropping and rising as an initialisation sequence, thus your modem must be configured to ignore DTR signal to pass communication port to DOS and Windows 3.1 properly.

Handshake Switches are also designed to be applied in External Fax Receiver string of modem configuration dialogue.

The following steps, provided by Sean Rima, can be an example of setting up Argus with Proboard BBS (the modem is USR Sportster 28800 with Fax). These settings are for Windows NT and Windows 2000 but can be easily converted to Windows 95 and Windows 98.

1. Add the FOSSIL driver to \winnt\system32\config.nt eg device=c:\dos\bnu.sys /p=01
2. Argus Config --> Dial-up --> Modems, Choose the Modem and in INIT, Add AT&C1&D0
3. Argus Config --> Externals --> Doors, Add line “Enter = pp”, “Door and Paramenters = c:\pb\proboard.exe %Z -b%B -p%C

 

Periodically-launching applications

Argus can launch external applications and commands of system interpreter periodically.

Attention: executing commands of system interpreter are supported in Argus for Windows NT and Windows 2000 only. In Argus for Windows 95 and Windows 98 is possible to launch executable files only. Nevertheless, BAT-files and system interpreter commands are able to execute by passing them directly as a command.com /c arguments, eg.: c:\windows\command.com /C myfile.bat

See also Cron.


 

Node Inspector

Node inspector (Ctrl+I), invoked by Config/Node Inspector menu items is a dialogue box that allows editing all settings of a node in a single place. This is a powerful tool for hubs with great number of links.

 

File-Flags

File-flags are the temporary files in Argus Home Directory. By means of file-flags, external programs or system operator can force Argus to do something. Argus periodically scans Home Directory for file-flags, and, after detection deletes the file-flag.

nodelist.ok Compile the nodelist. Identical to Compile Nodelist item of Tool menu (Shift-F6).
exit.now Exit Argus. Identical to Exit item of System menu (Alt+X).
password.ok Import auxiliary password file.
dupovr.ok Import auxiliary dial-up node overrides file.
ipovr.ok Import auxiliary TCP/IP node overrides file.
close.linename Close a line. E.g. if the line is named "Line4", the flag should be named "close.Line4"
open.linename Opens a line.
close.ip Close TCP/IP daemon.
open.ip Open TCP/IP daemon.
active.linename Indicates that a line is currently active i.e. opened.
active.ip Indicates that TCP/IP daemon is currently active i.e. opened.
current.ip Indicates that at least one TCP/IP connection is currently opened.

Please note that "close.linename" & "open.linename" flags are deleted only in case of successful open / close operation. E.g. open.line1 flag will not be deleted until the line actually opens with a valid serial port.

 

Import passwords

If you are upgrading to Argus from a mailer listed below or wish to use Argus in conjunction with other mailer, you may easily import password configuration. Import passwords dialogue box is invoked from Config/Passwords, Import button. You may import override configuration as well.


BinkD © Dima Maloff

You will be prompted for the path to BinkD configuration file. Argus doesn't support nested configuration files of BinkD, so if you keep BinkD passwords in a separate file, you should point to it. Argus will parse selected file in search of "NODE" keyword. Also, FTN addresses following "NODE" keyword must be in full 4D/5D notation. If your BinkD configuration file has shortened form of addresses (e.g. for nodes from your own zone/net) Argus would not import them. Argus supports only one pair Address/Password per line when importing BinkP configuration file.


Bink/+ © serge terekhov

You will be prompted for the path to Bink/+ configuration file. Argus supports nested configuration files of Bink/+, so if you keep Bink/+ passwords in a separate file, you shouldn't point to it unless all addresses are in full 4D/5D notation or this file has ADDRESS keyword. Argus will parse selected file in search of "ADDRESS" (default address for expanding shortened addresses), " INCLUDE" (nested configuration file) and "OVERRIDE" keywords.


T-Mail © Andy Elkin

You will be prompted for the path to T-Mail configuration file. Argus supports nested configuration files of T-Mail. Note that you should point to T-Mail main configuration file, not to "subst"- or "security-"file. Argus will parse selected file in search of the following keywords: "ADDRESS" (default address for expanding shortened addresses), "INCLUDE" (nested configuration file), "SUBSTLIST" (path to T-Mail file with substitutes; "PASSWORD" keyword will be in search there) and "SECURITY" (path to T-Mail file with passwords).


Xenia © Arjen G. Lentz

You will be prompted for the path to Xenia configuration file. Argus supports nested configuration files of Xenia. Argus will parse selected file in search of the following keywords "INCLUDE" (nested configuration file) and "PASSWORD" (password record) keyword. Also, FTN addresses following "PASSWORD" keyword must be in full 4D/5D notation. If your Xenia configuration file has shortened form of addresses (e.g. for nodes from your own zone/net) Argus would not import them. Xenia configuration file may specify several addresses to be bound to a password in a single line, Argus will properly import such entries.


FrontDoor 2.12 © Joaquim Homrighausen

You will be prompted for the path to FrontDoor passwords file (password.fd). FrontDoor configuration file is a binary file. Import of other data rather than passwords from FrontDoor is not supported. Other versions of FrontDoor rather then 2.12 are also not supported, unless they have 100%-compatible password file format. You may try at your own risk.


MainDoor 1.10 © Francisco Sedano Crippa

You will be prompted for the path to MainDoor passwords file (password.fd). MainDoor configuration file is a binary file. Import of other data rather than passwords from MainDoor is not supported. Other versions of MainDoor rather then 1.10 are also not supported, unless they have 100%-compatible password file format. You may try at your own risk.

 

Import nodes

If you are upgrading to Argus from a mailer listed below or wish to use Argus in conjunction with other mailer, you may easily import node overrides, this information will be inserted into node overrides table for dial-up lines and TCP/IP Daemon. Import nodes dialogue box is invoked from Config/Dialup / Nodes tab / Import button for Dial-up nodes and from Config/TCP/IP Daemon / Nodes tab / Import button for TCP/IP nodes.


BinkD © Dima Maloff

You will be prompted for the path to BinkD configuration file. Argus doesn't support nested configuration files of BinkD, so if you keep list of nodes in a separate file, you should point to it. Argus will parse selected file in search of "NODE" keyword. Also, FTN addresses following "NODE" keyword must be in full 4D/5D notation. If your BinkD configuration file has shortened form of addresses (e.g. for nodes from your own zone/net) Argus would not import them. Imported entries will be inserted into Nodes tab of Config/TCP/IP Daemon configuration dialogue, for such noes no other information except TCP/IP address (fully-qualified domain name of dotted-decimal IP address) will be extracted; "CM,BND" flags will be automatically assigned.


Bink/+ © serge terekhov

You will be prompted for the path to Bink/+ configuration file. Argus supports nested configuration files of Bink/+, so if you keep list of nodes in a separate file, you shouldn't point to it unless all addresses are in full 4D/5D notation or this file has ADDRESS keyword. Argus will parse selected file in search of "ADDRESS" (default address for expanding shortened addresses), "INCLUDE" (nested configuration file) and "OVERRIDE" keywords. Imported entries may be inserted into Nodes tab of both Dial/Up and TCP/IP configuration dialogues; the decision is made upon flags specified for a node in Bink/+ configuration file.


T-Mail © Andy Elkin

You will be prompted for the path to T-Mail configuration file. Argus supports nested configuration files of T-Mail. Note that you should point to T-Mail main configuration file, not to "subst"- or "security-"file. Argus will parse selected file in search of the following keywords: "ADDRESS" (default address for expanding shortened addresses), "INCLUDE" (nested configuration file), "SUBSTLIST" (path to T-Mail file with substitutes; "PHONE", "HIDDEN", "HIDDEN_ADDRESS", "TIME" and "FLAGS" keyword will be in search there; value of "TIME" keyword will be converted to Txy). Imported entries may be inserted into Nodes tab of both Dial/Up and TCP/IP configuration dialogues; the decision is made upon flags specified for a node in T-Mail configuration file.


Xenia © Arjen G. Lentz

You will be prompted for the path to Xenia configuration file. Argus supports nested configuration files of Xenia. Argus will parse selected file in search of the following keywords "INCLUDE" (nested configuration file) and "PHONE" keyword. Also, FTN address following "PHONE" keyword must be in full 4D/5D notation. If your Xenia configuration file has shortened form of addresses (e.g. for nodes from your own zone/net) Argus would not import them. Xenia configuration file may specify phone numbers / TCP/IP addresses to be bound to a node in a single line or even in multiple lines, Argus will properly import such entries. Imported entries may be inserted into Nodes tab of both Dial/Up and TCP/IP configuration dialogues; the decision is made upon flags specified in Xenia configuration file.

 

Address input window

You may type one or several, if allowed, (delimited by space character) 4D/5D FTN addresses in the input line. To pick previously entered addresses, press Alt+Down or use mouse to invoke drop-down list. You may click Browse button to Invoke Nodelist Browser window to pick a node from currently compiled nodelist.

 

File Request Editor

File Request Editor is a window invoked from Tool / Edit File Request. This window has a string grid with two columns "File" and "Password".

Values of "File" column are file names or aliases (also called magic names). When specifying an alias, you need not to know the real name of requested file. For example, FidoNet Nodelist is requestable from most FidoNet nodes as NODELIST while the real name of the Nodelist file is changing every week. Another example is the file list of a system, which is often requested using the Alias FILES. You may also specify a file mask, if remote mailer (a mailer on a node from which you request files) allows that. If remote mailer is Argus, aliases, file names and file masks (optionally) are allowed. Argus neither transmits nor handles full-path-name file requests. Note that if the value of "File" column has space a character, Argus will transmit to remote mailer space characters replaced to "\20" sequences.

Values of "Password" column are passwords for specified files, not session passwords.

 

Send Modem Commands

You may send strings to modem interactively. Use Line/Send Modem Commands menu item or press F9. This works when the modem is idle. Modem control characters are allowed.

 

Nodelist Browser

Node inspector (Ctrl+I), invoked by Tool/Browse Nodelis menu items is a window that allows browsing currently compiled nodelist in a form of a tree.

 

Where to use Regular Expressions

Regular Expressions may be used in file masks, address masks, Modem Responses and File-Boxes configuration, i.e. anywhere where generic masks are allowed (though Modem Responses do not allow generic masks)

Argus uses Perl-Compatible Regular Expressions library (c) 1997-2000 University of Cambridge. This library was written by Philip Hazel <ph10@cam.ac.uk>, University Computing Service, New Museums Site, Cambridge CB2 3QG, England, Phone: +44 1223 334714.

Information about Perl-Compatible Regular Expressions (PCRE) syntax is given in a separate chapter, written by Philip Hazel.


Syntax

To insert a Regular Expression, use '~' character as a marker. Next character (following '~' marker) will be used as a delimiter to define the end of a Regular Expression. Any text found between delimiting characters will be treated as a Regular Expression.

The syntax is:

before~#regularexpression#after

where "before" and "after" is optional text that will be compared as a generic mask (a character matches itself, '?' matches any character, '*' matches a sequence of characters).

"regularexpression" is a text of a Regular Expression.

'#' - delimiter character.


Examples

The following string (found where a file mask should be)

~#cat(aract|erpillar|)\..*#

will match a file named "cat", "cataract", or "caterpillar", with any extension.

the above example is equivalent to

~#cat(aract|erpillar|)#.*

because the text after delimiter (".*") is treated as a generic mask, i.e. '.' matches a dot character and '*' matches any sequence of characters.

Here is another example of using regular expressions in Modem Responses:

~#^RING(\x20\d)?$#

This will match word "RING", optionally following a digit after space character.


List Separators and Regular Expression Delimiters

Because of space (or other) character may be used as a separator in Argus Configuration String Grids, such character should not occur in non-escaped form inside a regular expression. This is because of separator characters in a string grid (e.g. space) have greater priority than a regular expression delimiters (e.g. '#').

To avoid using string grid separator character in a Regular Expression, use hex codes (e.g. \x20 for space character) or corresponding patterns (e.g. \s , that will match any whitespace character).

If you plan using '#' character within a regular expression, you may also use it's hex code, but better way would be choosing another delimiter.

~`^RING(\x20#\d)?$`

To insert ~ character into a generic mask, double it to avoid using it as a regular expression marker.


Anchoring in File Masks

Note that you don't need to anchor your regular expressions (using '^' and '$') in file masks - they would be anchored automatically. If you need to skip some characters before of after, use ".*")


PCRE Default Options

The settings of PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and PCRE_EXTENDED options (described in separate chapter) can be changed from within the pattern by a sequence of Perl option letters enclosed between "(?" and ")", although the following default options are used:

When matching file names and path names - PCRE_CASELESS.
When matching modem responses - PCRE_MULTILINE, because the regular expression is matching against the entire multi-line input data stream coming from a modem.
In all other cases none of PCRE options are set by default.

 

Regular Expressions Syntax (Advanced)

Argus uses Perl-compatible regular expressions.(PCRE) library. The library is a set of functions that implement regular expression pattern matching using the same syntax and semantics as Perl 5, with just a few differences. The current implementation corresponds to Perl 5.005. The syntax and semantics of the regular expressions supported by PCRE are described in this chapter.

- Meta-Characters.
- Backslash.
- Circumflex and Dollar.
- Full Stop (Period, Dot).
- Square Brackets.
- Vertical Bar.
- Internal Option Setting.
- Subpatterns.
- Repetition.
- Back References.
- Assertions.
- Once-Only Subpatterns.
- Conditional Subpatterns.
- Comments.
- Performance.
- Limitiations.
- Differences From Perl.

PCRE Library and this chapter (Regular Expressions Syntax (Advanced)) are written by Philip Hazel <ph10@cam.ac.uk>, University of Cambridge Computing Service, Cambridge, England. Phone: +44 1223 334714. Copyright © 1997-2000 University of Cambridge

Regular expressions are also described in the Perl documentation and in a number of other books, some of which have copious examples. Jeffrey Friedl's "Mastering Regular Expressions", published by O'Reilly (ISBN 1-56592-257-3), covers them in great detail. The description here is intended as reference documentation.


 

Meta-Characters

A regular expression is a pattern that is matched against a subject string from left to right. Most characters stand for themselves in a pattern, and match the corresponding characters in the subject. As a trivial example, the pattern

The quick brown fox

matches a portion of a subject string that is identical to itself. The power of regular expressions comes from the ability to include alternatives and repetitions in the pattern. These are encoded in the pattern by the use of meta-characters, which do not stand for themselves but instead are interpreted in some special way.

There are two different sets of meta-characters: those that are recognised anywhere in the pattern except within square brackets, and those that are recognised in square brackets. Outside square brackets, the meta-characters are as follows:

\ general escape character with several uses
^ assert start of subject (or line, in multiline mode)
$ assert end of subject (or line, in multiline mode)
. match any character except newline (by default)
[ start character class definition
| start of alternative branch
( start subpattern
) end subpattern
? extends the meaning of (
also 0 or 1 quantifier
also quantifier minimizer
* 0 or more quantifier
+ 1 or more quantifier
{ start min/max quantifier

Part of a pattern that is in square brackets is called a "character class". In a character class the only meta-characters are:

\ general escape character
^ negate the class, but only if the first character
- indicates character range
] terminates the character class

The following sections describe the use of each of the meta-characters.

 

Backslash

The backslash character has several uses. Firstly, if it is followed by a non-alphameric character, it takes away any special meaning that character may have. This use of backslash as an escape character applies both inside and outside character classes.

For example, if you want to match a "*" character, you write "\*" in the pattern. This applies whether or not the following character would otherwise be interpreted as a meta-character, so it is always safe to precede a non-alphameric with "\" to specify that it stands for itself. In particular, if you want to match a backslash, you write "\\".

If a pattern is compiled with the PCRE_EXTENDED option, whitespace in the pattern (other than in a character class) and characters between a "#" outside a character class and the next newline character are ignored. An escaping backslash can be used to include a whitespace or "#" character as part of the pattern.

A second use of backslash provides a way of encoding non-printing characters in patterns in a visible manner. There is no restriction on the appearance of non-printing characters, apart from the binary zero that terminates a pattern, but when a pattern is being prepared by text editing, it is usually easier to use one of the following escape sequences than the binary character it represents:

\a alarm, that is, the BEL character (hex 07)
\cx "control-x", where x is any character
\e escape (hex 1B)
\f formfeed (hex 0C)
\n newline (hex 0A)
\r carriage return (hex 0D)
\t tab (hex 09)
\xhh character with hex code hh
\ddd character with octal code ddd, or backreference

The precise effect of "\cx" is as follows: if "x" is a lower case letter, it is converted to upper case. Then bit 6 of the character (hex 40) is inverted. Thus "\cz" becomes hex 1A, but "\c{" becomes hex 3B, while "\c;" becomes hex 7B.

After "\x", up to two hexadecimal digits are read (letters can be in upper or lower case).

After "\0" up to two further octal digits are read. In both cases, if there are fewer than two digits, just those that are present are used. Thus the sequence "\0\x\07" specifies two binary zeros followed by a BEL character. Make sure you supply two digits after the initial zero if the character that follows is itself an octal digit.

The handling of a backslash followed by a digit other than 0 is complicated. Outside a character class, PCRE reads it and any following digits as a decimal number. If the number is less than 10, or if there have been at least that many previous capturing left parentheses in the expression, the entire sequence is taken as a back reference. A description of how this works is given later, following the discussion of parenthesized subpatterns.

Inside a character class, or if the decimal number is greater than 9 and there have not been that many capturing subpatterns, PCRE re-reads up to three octal digits following the backslash, and generates a single byte from the least significant 8 bits of the value. Any subsequent digits stand for themselves. For example:

\040 is another way of writing a space
\40 is the same, provided there are fewer than 40 previous capturing subpatterns
\7 is always a back reference
\11 might be a back reference, or another way of writing a tab
\011 is always a tab
\0113 is a tab followed by the character "3"
\113 is the character with octal code 113 (since there can be no more than 99 back references)
\377 is a byte consisting entirely of 1 bits
\81 is either a back reference, or a binary zero followed by the two characters "8" and "1"

Note that octal values of 100 or greater must not be introduced by a leading zero, because no more than three octal digits are ever read.

All the sequences that define a single byte value can be used both inside and outside character classes. In addition, inside a character class, the sequence "\b" is interpreted as the backspace character (hex 08). Outside a character class it has a different meaning (see below).

The third use of backslash is for specifying generic character types:

\d any decimal digit
\D any character that is not a decimal digit
\s any whitespace character
\S any character that is not a whitespace character
\w any "word" character
\W any "non-word" character

Each pair of escape sequences partitions the complete set of characters into two disjoint sets. Any given character matches one, and only one, of each pair.

A "word" character is any letter or digit or the underscore character, that is, any character which can be part of a Perl "word". The definition of letters and digits is controlled by PCRE's character tables, and may vary if locale- specific matching is taking place (see "Locale support" above). For example, in the "fr" (French) locale, some character codes greater than 128 are used for accented letters, and these are matched by \w.

These character type sequences can appear both inside and outside character classes. They each match one character of the appropriate type. If the current matching point is at the end of the subject string, all of them fail, since there is no character to match.

The fourth use of backslash is for certain simple assertions. An assertion specifies a condition that has to be met at a particular point in a match, without consuming any characters from the subject string. The use of subpatterns for more complicated assertions is described below. The backslashed assertions are

\b word boundary
\B not a word boundary
\A start of subject (independent of multiline mode)
\Z end of subject or newline at end (independent of multiline mode)
\z end of subject (independent of multiline mode)

These assertions may not appear in character classes (but note that "\b" has a different meaning, namely the backspace character, inside a character class).

A word boundary is a position in the subject string where the current character and the previous character do not both match \w or \W (i.e. one matches \w and the other matches \W), or the start or end of the string if the first or last character matches \w, respectively.

The \A, \Z, and \z assertions differ from the traditional circumflex and dollar (described below) in that they only ever match at the very start and end of the subject string, whatever options are set. They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options. The difference between \Z and \z is that \Z matches before a newline that is the last character of the string as well as at the end of the string, whereas \z matches only at the end.

 

Circumflex and Dollar

Outside a character class, in the default matching mode, the circumflex character is an assertion which is true only if the current matching point is at the start of the subject string. Inside a character class, circumflex has an entirely different meaning (see below).

Circumflex need not be the first character of the pattern if a number of alternatives are involved, but it should be the first thing in each alternative in which it appears if the pattern is ever to match that branch. If all possible alternatives start with a circumflex, that is, if the pattern is constrained to match only at the start of the subject, it is said to be an "anchored" pattern. (There are also other constructs that can cause a pattern to be anchored.)

A dollar character is an assertion which is true only if the current matching point is at the end of the subject string, or immediately before a newline character that is the last character in the string (by default). Dollar need not be the last character of the pattern if a number of alternatives are involved, but it should be the last item in any branch in which it appears. Dollar has no special meaning in a character class.

The meaning of dollar can be changed so that it matches only at the very end of the string, by setting the PCRE_DOLLAR_ENDONLY option at compile or matching time. This does not affect the \Z assertion.

The meanings of the circumflex and dollar characters are changed if the PCRE_MULTILINE option is set. When this is the case, they match immediately after and immediately before an internal "\n" character, respectively, in addition to matching at the start and end of the subject string. For example, the pattern /^abc$/ matches the subject string "def
abc" in multiline mode, but not otherwise. Consequently, patterns that are anchored in single line mode because all branches start with "^" are not anchored in multiline mode. The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set.

Note that the sequences \A, \Z, and \z can be used to match the start and end of the subject in both modes, and if all branches of a pattern start with \A is it always anchored, whether PCRE_MULTILINE is set or not.

 

Full Stop (Period, Dot)

Outside a character class, a dot in the pattern matches any one character in the subject, including a non-printing character, but not (by default) newline. If the PCRE_DOTALL option is set, then dots match newlines as well. The handling of dot is entirely independent of the handling of circumflex and dollar, the only relationship being that they both involve newline characters. Dot has no special meaning in a character class.

 

Square Brackets

An opening square bracket introduces a character class, terminated by a closing square bracket. A closing square bracket on its own is not special. If a closing square bracket is required as a member of the class, it should be the first data character in the class (after an initial circumflex, if present) or escaped with a backslash.

A character class matches a single character in the subject; the character must be in the set of characters defined by the class, unless the first character in the class is a circumflex, in which case the subject character must not be in the set defined by the class. If a circumflex is actually required as a member of the class, ensure it is not the first character, or escape it with a backslash.

For example, the character class [aeiou] matches any lower case vowel, while [^aeiou] matches any character that is not a lower case vowel. Note that a circumflex is just a convenient notation for specifying the characters which are in the class by enumerating those that are not. It is not an assertion: it still consumes a character from the subject string, and fails if the current pointer is at the end of the string.

When caseless matching is set, any letters in a class represent both their upper case and lower case versions, so for example, a caseless [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not match "A", whereas a caseful version would.

The newline character is never treated in any special way in character classes, whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE options is. A class such as [^a] will always match a newline.

The minus (hyphen) character can be used to specify a range of characters in a character class. For example, [d-m] matches any letter between d and m, inclusive. If a minus character is required in a class, it must be escaped with a backslash or appear in a position where it cannot be interpreted as indicating a range, typically as the first or last character in the class.

It is not possible to have the literal character "]" as the end character of a range. A pattern such as [W-]46] is interpreted as a class of two characters ("W" and "-") followed by a literal string "46]", so it would match "W46]" or "-46]". However, if the "]" is escaped with a backslash it is interpreted as the end of range, so [W-\]46] is interpreted as a single class containing a range followed by two separate characters. The octal or hexadecimal representation of "]" can also be used to end a range.

Ranges operate in ASCII collating sequence. They can also be used for characters specified numerically, for example [\000-\037]. If a range that includes letters is used when caseless matching is set, it matches the letters in either case. For example, [W-c] is equivalent to [][\^_`wxyzabc], matched caselessly, and if character tables for the "fr" locale are in use, [\xc8-\xcb] matches accented E characters in both cases.

The character types \d, \D, \s, \S, \w, and \W may also appear in a character class, and add the characters that they match to the class. For example, [\dABCDEF] matches any hexadecimal digit. A circumflex can conveniently be used with the upper case character types to specify a more restricted set of characters than the matching lower case type. For example, the class [^\W_] matches any letter or digit, but not underscore.

All non-alphameric characters other than \, -, ^ (at the start) and the terminating ] are non-special in character classes, but it does no harm if they are escaped.

 

Vertical Bar

Vertical bar characters are used to separate alternative patterns. For example, the pattern

gilbert|sullivan

matches either "gilbert" or "sullivan". Any number of alternatives may appear, and an empty alternative is permitted (matching the empty string). The matching process tries each alternative in turn, from left to right, and the first one that succeeds is used. If the alternatives are within a subpattern (defined below), "succeeds" means matching the rest of the main pattern as well as the alternative in the subpattern.

 

Internal Option Setting

The settings of PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and PCRE_EXTENDED can be changed from within the pattern by a sequence of Perl option letters enclosed between "(?" and ")". The option letters are

i PCRE_CASELESS Letters in the pattern match both upper and lower case letters. It is equivalent to Perl's /i option.
m PCRE_MULTILINE By default, PCRE treats the subject string as consisting of a single "line" of characters (even if it actually contains several newlines). The "start of line" metacharacter (^) matches only at the start of the string, while the "end of line" metacharacter ($) matches only at the end of the string, or before a terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as Perl.

When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the subject string, respectively, as well as at the very start and end. This is equivalent to Perl's /m option. If there are no "\n" characters in a subject string, or no occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect.

s PCRE_DOTALL If this bit is set, a dot metacharater in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option is equivalent to Perl's /s option. A negative class such as [^a] always matches a newline character, independent of the setting of this option.
x PCRE_EXTENDED If this bit is set, whitespace data characters in the pattern are totally ignored except when escaped or inside a character class, and characters between an unescaped # outside a character class and the next newline character, inclusive, are also ignored. This is equivalent to Perl's /x option, and makes it possible to include comments inside complicated patterns. Note, however, that this applies only to data characters. Whitespace characters may never appear within special character sequences in a pattern, for example within the sequence (?( which introduces a conditional subpattern.

For example, (?im) sets caseless, multiline matching. It is also possible to unset these options by preceding the letter with a hyphen, and a combined setting and unsetting such as (?im-sx), which sets PCRE_CASELESS and PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED, is also permitted. If a letter appears both before and after the hyphen, the option is unset.

The scope of these option changes depends on where in the pattern the setting occurs. For settings that are outside any subpattern (defined below), the effect is the same as if the options were set or unset at the start of matching. The following patterns all behave in exactly the same way:

(?i)abc
a(?i)bc
ab(?i)c
abc(?i)

which in turn is the same as compiling the pattern abc with PCRE_CASELESS set. In other words, such "top level" settings apply to the whole pattern (unless there are other changes inside subpatterns). If there is more than one setting of the same option at top level, the rightmost setting is used.

If an option change occurs inside a subpattern, the effect is different. This is a change of behaviour in Perl 5.005. An option change inside a subpattern affects only that part of the subpattern that follows it, so

(a(?i)b)c

matches abc and aBc and no other strings (assuming PCRE_CASELESS is not used). By this means, options can be made to have different settings in different parts of the pattern. Any changes made in one alternative do carry on into subsequent branches within the same subpattern. For example,

(a(?i)b|c)

matches "ab", "aB", "c", and "C", even though when matching "C" the first branch is abandoned before the option setting. This is because the effects of option settings happen at compile time. There would be some very weird behaviour otherwise.

The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can be changed in the same way as the Perl-compatible options by using the characters U and X respectively. The (?X) flag setting is special in that it must always occur earlier in the pattern than any of the additional features it turns on, even when it is at top level. It is best put at the start.

 

Subpatterns

Subpatterns are delimited by parentheses (round brackets), which can be nested.
Marking part of a pattern as a subpattern does two things:

1. It localizes a set of alternatives. For example, the pattern

cat(aract|erpillar|)

matches one of the words "cat", "cataract", or "caterpillar". Without the parentheses, it would match "cataract", "erpillar" or the empty string.

2. It sets up the subpattern as a capturing subpattern (as defined above). Opening parentheses are counted from left to right (starting from 1) to obtain the numbers of the capturing subpatterns.

For example, if the string "the red king" is matched against the pattern

the ((red|white) (king|queen))

the captured substrings are "red king", "red", and "king", and are numbered 1, 2, and 3.

The fact that plain parentheses fulfil two functions is not always helpful. There are often times when a grouping subpattern is required without a capturing requirement. If an opening parenthesis is followed by "?:", the subpattern does not do any capturing, and is not counted when computing the number of any subsequent capturing subpatterns. For example, if the string "the white queen" is matched against the pattern

the ((?:red|white) (king|queen))

the captured substrings are "white queen" and "queen", and are numbered 1 and 2. The maximum number of captured substrings is 99, and the maximum number of all subpatterns, both capturing and non-capturing, is 200.

As a convenient shorthand, if any option settings are required at the start of a non-capturing subpattern, the option letters may appear between the "?" and the ":". Thus the two patterns

(?i:saturday|sunday)
(?:(?i)saturday|sunday)

match exactly the same set of strings. Because alternative branches are tried from left to right, and options are not reset until the end of the subpattern is reached, an option setting in one branch does affect subsequent branches, so the above patterns match "SUNDAY" as well as "Saturday".

 

Repetition

Repetition is specified by quantifiers, which can follow any of the following items:

a single character, possibly escaped
the . metacharacter
a character class
a back reference (see next section)
a parenthesized subpattern (unless it is an assertion - see below)

The general repetition quantifier specifies a minimum and maximum number of permitted matches, by giving the two numbers in curly brackets (braces), separated by a comma. The numbers must be less than 65536, and the first must be less than or equal to the second. For example:

z{2,4}

matches "zz", "zzz", or "zzzz". A closing brace on its own is not a special character. If the second number is omitted, but the comma is present, there is no upper limit; if the second number and the comma are both omitted, the quantifier specifies an exact number of required matches. Thus

[aeiou]{3,}

matches at least 3 successive vowels, but may match many more, while

\d{8}

matches exactly 8 digits. An opening curly bracket that appears in a position where a quantifier is not allowed, or one that does not match the syntax of a quantifier, is taken as a literal character. For example, {,6} is not a quantifier, but a literal string of four characters.

The quantifier {0} is permitted, causing the expression to behave as if the previous item and the quantifier were not present.

For convenience (and historical compatibility) the three most common quantifiers have single-character abbreviations:

* is equivalent to {0,}
+ is equivalent to {1,}
? is equivalent to {0,1}

It is possible to construct infinite loops by following a subpattern that can match no characters with a quantifier that has no upper limit, for example:

(a?)*

Earlier versions of Perl and PCRE used to give an error at compile time for such patterns. However, because there are cases where this can be useful, such patterns are now accepted, but if any repetition of the subpattern does in fact match no characters, the loop is forcibly broken.

By default, the quantifiers are "greedy", that is, they match as much as possible (up to the maximum number of permitted times), without causing the rest of the pattern to fail. The classic example of where this gives problems is in trying to match comments in C programs. These appear between the sequences /* and */ and within the sequence, individual * and / characters may appear. An attempt to match C comments by applying the pattern

/\*.*\*/

to the string

/* first command */ not comment /* second comment */

fails, because it matches the entire string due to the greediness of the .* item.

However, if a quantifier is followed by a question mark, then it ceases to be greedy, and instead matches the minimum number of times possible, so the pattern

/\*.*?\*/

does the right thing with the C comments. The meaning of the various quantifiers is not otherwise changed, just the preferred number of matches. Do not confuse this use of question mark with its use as a quantifier in its own right. Because it has two uses, it can sometimes appear doubled, as in

\d??\d

which matches one digit by preference, but can match two if that is the only way the rest of the pattern matches.

If the PCRE_UNGREEDY option is set (an option which is not available in Perl) then the quantifiers are not greedy by default, but individual ones can be made greedy by following them with a question mark. In other words, it inverts the default behaviour.

When a parenthesized subpattern is quantified with a minimum repeat count that is greater than 1 or with a limited maximum, more store is required for the compiled pattern, in proportion to the size of the minimum or maximum.

If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equivalent to Perl's /s) is set, thus allowing the . to match newlines, then the pattern is implicitly anchored, because whatever follows will be tried against every character position in the subject string, so there is no point in retrying the overall match at any position after the first. PCRE treats such a pattern as though it were preceded by \A. In cases where it is known that the subject string contains no newlines, it is worth setting PCRE_DOTALL when the pattern begins with .* in order to obtain this optimization, or alternatively using ^ to indicate anchoring explicitly.

When a capturing subpattern is repeated, the value captured is the substring that matched the final iteration. For example, after

(tweedle[dume]{3}\s*)+

has matched "tweedledum tweedledee" the value of the captured substring is "tweedledee". However, if there are nested capturing subpatterns, the corresponding captured values may have been set in previous iterations. For example, after

/(a|(b))+/

matches "aba" the value of the second captured substring is "b".

 

Back References

Outside a character class, a backslash followed by a digit greater than 0 (and possibly further digits) is a back reference to a capturing subpattern earlier (i.e. to its left) in the pattern, provided there have been that many previous capturing left parentheses.

However, if the decimal number following the backslash is less than 10, it is always taken as a back reference, and causes an error only if there are not that many capturing left parentheses in the entire pattern. In other words, the parentheses that are referenced need not be to the left of the reference for numbers less than 10. See the section entitled "Backslash" above for further details of the handling of digits following a backslash.

A back reference matches whatever actually matched the capturing subpattern in the current subject string, rather than anything matching the subpattern itself. So the pattern

(sens|respons)e and \1ibility

matches "sense and sensibility" and "response and responsibility", but not "sense and responsibility". If caseful matching is in force at the time of the back reference, then the case of letters is relevant. For example,

((?i)rah)\s+\1

matches "rah rah" and "RAH RAH", but not "RAH rah", even though the original capturing subpattern is matched caselessly.

There may be more than one back reference to the same subpattern. If a subpattern has not actually been used in a particular match, then any back references to it always fail. For example, the pattern

(a|(bc))\2

always fails if it starts to match "a" rather than "bc". Because there may be up to 99 back references, all digits following the backslash are taken as part of a potential back reference number. If the pattern continues with a digit character, then some delimiter must be used to terminate the back reference. If the PCRE_EXTENDED option is set, this can be whitespace. Otherwise an empty comment can be used.

A back reference that occurs inside the parentheses to which it refers fails when the subpattern is first used, so, for example, (a\1) never matches. However, such references can be useful inside repeated subpatterns. For example, the pattern

(a|b\1)+

matches any number of "a"s and also "aba", "ababaa" etc. At each iteration of the subpattern, the back reference matches the character string corresponding to the previous iteration. In order for this to work, the pattern must be such that the first iteration does not need to match the back reference. This can be done using alternation, as in the example above, or by a quantifier with a minimum of zero.

 

Assertions

An assertion is a test on the characters following or preceding the current matching point that does not actually consume any characters. The simple assertions coded as \b, \B, \A, \Z, \z, ^ and $ are described above. More complicated assertions are coded as subpatterns. There are two kinds: those that look ahead of the current position in the subject string, and those that look behind it.

An assertion subpattern is matched in the normal way, except that it does not cause the current matching position to be changed. Lookahead assertions start with (?= for positive assertions and (?! for negative assertions. For example,

\w+(?=;)

matches a word followed by a semicolon, but does not include the semicolon in the match, and

foo(?!bar)

matches any occurrence of "foo" that is not followed by "bar". Note that the apparently similar pattern

(?!foo)bar

does not find an occurrence of "bar" that is preceded by something other than "foo"; it finds any occurrence of "bar" whatsoever, because the assertion (?!foo) is always true when the next three characters are "bar". A lookbehind assertion is needed to achieve this effect.

Lookbehind assertions start with (?<= for positive assertions and (?<! for negative assertions. For example,

(?<!foo)bar

does find an occurrence of "bar" that is not preceded by "foo". The contents of a lookbehind assertion are restricted such that all the strings it matches must have a fixed length. However, if there are several alternatives, they do not all have to have the same fixed length. Thus

(?<=bullock|donkey)

is permitted, but

(?<!dogs?|cats?)

causes an error at compile time. Branches that match different length strings are permitted only at the top level of a lookbehind assertion. This is an extension compared with Perl 5.005, which requires all branches to match the same length of string. An assertion such as

(?<=ab(c|de))

is not permitted, because its single top-level branch can match two different lengths, but it is acceptable if rewritten to use two top-level branches:

(?<=abc|abde)

The implementation of lookbehind assertions is, for each alternative, to temporarily move the current position back by the fixed width and then try to match. If there are insufficient characters before the current position, the match is deemed to fail. Lookbehinds in conjunction with once-only subpatterns can be particularly useful for matching at the ends of strings; an example is given at the end of the section on once-only subpatterns.

Several assertions (of any sort) may occur in succession. For example,

(?<=\d{3})(?<!999)foo

matches "foo" preceded by three digits that are not "999". Furthermore, assertions can be nested in any combination. For example,

(?<=(?<!foo)bar)baz

matches an occurrence of "baz" that is preceded by "bar" which in turn is not preceded by "foo".

Assertion subpatterns are not capturing subpatterns, and may not be repeated, because it makes no sense to assert the same thing several times. If an assertion contains capturing subpatterns within it, these are always counted for the purposes of numbering the capturing subpatterns in the whole pattern. Substring capturing is carried out for positive assertions, but it does not make sense for negative assertions.

Assertions count towards the maximum of 200 parenthesized subpatterns.

 

Once-Only Subpatterns

With both maximizing and minimizing repetition, failure of what follows normally causes the repeated item to be re-evaluated to see if a different number of repeats allows the rest of the pattern to match. Sometimes it is useful to prevent this, either to change the nature of the match, or to cause it fail earlier than it otherwise might, when the author of the pattern knows there is no point in carrying on.

Consider, for example, the pattern \d+foo when applied to the subject line

123456bar

After matching all 6 digits and then failing to match "foo", the normal action of the matcher is to try again with only 5 digits matching the \d+ item, and then with 4, and so on, before ultimately failing. Once-only subpatterns provide the means for specifying that once a portion of the pattern has matched, it is not to be re-evaluated in this way, so the matcher would give up immediately on failing to match "foo" the first time. The notation is another kind of special parenthesis, starting with (?> as in this example:

(?>\d+)bar

This kind of parenthesis "locks up" the part of the pattern it contains once it has matched, and a failure further into the pattern is prevented from backtracking into it. Backtracking past it to previous items, however, works as normal.

An alternative description is that a subpattern of this type matches the string of characters that an identical standalone pattern would match, if anchored at the current point in the subject string.

Once-only subpatterns are not capturing subpatterns. Simple cases such as the above example can be thought of as a maximizing repeat that must swallow everything it can. So, while both \d+ and \d+? are prepared to adjust the number of digits they match in order to make the rest of the pattern match, (?>\d+) can only match an entire sequence of digits.

This construction can of course contain arbitrarily complicated subpatterns, and it can be nested.

Once-only subpatterns can be used in conjunction with lookbehind assertions to specify efficient matching at the end of the subject string. Consider a simple pattern such as

abcd$

when applied to a long string which does not match it. Because matching proceeds from left to right, PCRE will look for each "a" in the subject and then see if what follows matches the rest of the pattern. If the pattern is specified as

^.*abcd$

then the initial .* matches the entire string at first, but when this fails, it backtracks to match all but the last character, then all but the last two characters, and so on. Once again the search for "a" covers the entire string, from right to left, so we are no better off. However, if the pattern is written as

^(?>.*)(?<=abcd)

then there can be no backtracking for the .* item; it can match only the entire string. The subsequent lookbehind assertion does a single test on the last four characters. If it fails, the match fails immediately. For long strings, this approach makes a significant difference to the processing time.

 

Conditional Subpatterns

It is possible to cause the matching process to obey a subpattern conditionally or to choose between two alternative subpatterns, depending on the result of an assertion, or whether a previous capturing subpattern matched or not. The two possible forms of conditional subpattern are

(?(condition)yes-pattern)
(?(condition)yes-pattern|no-pattern)

If the condition is satisfied, the yes-pattern is used; otherwise the no-pattern (if present) is used. If there are more than two alternatives in the subpattern, a compile-time error occurs.

There are two kinds of condition. If the text between the parentheses consists of a sequence of digits, then the condition is satisfied if the capturing subpattern of that number has previously matched. Consider the following pattern, which contains non-significant white space to make it more readable (assume the PCRE_EXTENDED option) and to divide it into three parts for ease of discussion:

( \( )? [^()]+ (?(1) \) )

The first part matches an optional opening parenthesis, and if that character is present, sets it as the first captured substring. The second part matches one or more characters that are not parentheses. The third part is a conditional subpattern that tests whether the first set of parentheses matched or not. If they did, that is, if subject started with an opening parenthesis, the condition is true, and so the yes-pattern is executed and a closing parenthesis is required. Otherwise, since no-pattern is not present, the subpattern matches nothing. In other words, this pattern matches a sequence of non-parentheses, optionally enclosed in parentheses.

If the condition is not a sequence of digits, it must be an assertion. This may be a positive or negative lookahead or lookbehind assertion. Consider this pattern, again containing non-significant white space, and with the two alternatives on the second line:

(?(?=[^a-z]*[a-z])
\d{2}[a-z]{3}-\d{2} | \d{2}-\d{2}-\d{2} )

The condition is a positive lookahead assertion that matches an optional sequence of non-letters followed by a letter. In other words, it tests for the presence of at least one letter in the subject. If a letter is found, the subject is matched against the first alternative; otherwise it is matched against the second. This pattern matches strings in one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are letters and dd are digits.

 

Comments

The sequence (?# marks the start of a comment which continues up to the next closing parenthesis. Nested parentheses are not permitted. The characters that make up a comment play no part in the pattern matching at all.

If the PCRE_EXTENDED option is set, an unescaped # character outside a character class introduces a comment that continues up to the next newline character in the pattern.

 

Performance

Certain items that may appear in patterns are more efficient than others. It is more efficient to use a character class like [aeiou] than a set of alternatives such as (a|e|i|o|u). In general, the simplest construction that provides the required behaviour is usually the most efficient. Jeffrey Friedl's book contains a lot of discussion about optimizing regular expressions for efficient performance.

When a pattern begins with .* and the PCRE_DOTALL option is set, the pattern is implicitly anchored by PCRE, since it can match only at the start of a subject string. However, if PCRE_DOTALL is not set, PCRE cannot make this optimization, because the . metacharacter does not then match a newline, and if the subject string contains newlines, the pattern may match from the character immediately following one of them instead of from the very start. For example, the pattern

(.*) second

matches the subject "first\nand second" (where \n stands for a newline character) with the first captured substring being "and". In order to do this, PCRE has to retry the match starting after every newline in the subject.

If you are using such a pattern with subject strings that do not contain newlines, the best performance is obtained by setting PCRE_DOTALL, or starting the pattern with ^.* to indicate explicit anchoring. That saves PCRE from having to scan along the subject looking for a newline to restart at.

 

Limitiations

There are some size limitations in PCRE but it is hoped that they will never in practice be relevant. The maximum length of a compiled pattern is 65539 (sic) bytes. All values in repeating quantifiers must be less than 65536. The maximum number of capturing subpatterns is 99. The maximum number of all parenthesized subpatterns, including capturing subpatterns, assertions, and other types of subpattern, is 200.

The maximum length of a subject string is the largest positive number that an integer variable can hold. However, PCRE uses recursion to handle subpatterns and indefinite repetition. This means that the available stack space may limit the size of a subject string that can be processed by certain patterns.

 

Differences From Perl

The differences described here are with respect to Perl 5.005.

1. By default, a whitespace character is any character that the C library function isspace recognizes, though it is possible to compile PCRE with alternative character type tables. Normally isspace matches space, formfeed, newline, carriage return, horizontal tab, and vertical tab. Perl 5 no longer includes vertical tab in its set of whitespace characters. The \v escape that was in the Perl documentation for a long time was never in fact recognized. However, the character itself was treated as whitespace at least up to 5.002. In 5.004 and 5.005 it does not match \s.

2. PCRE does not allow repeat quantifiers on lookahead assertions. Perl permits them, but they do not mean what you might think. For example, (?!a){3} does not assert that the next three characters are not "a". It just asserts that the next character is not "a" three times.

3. Capturing subpatterns that occur inside negative lookahead assertions are counted, but their entries in the offsets vector are never set. Perl sets its numerical variables from any such patterns that are matched before the assertion fails to match something (thereby succeeding), but only if the negative lookahead assertion contains just one branch.

4. Though binary zero characters are supported in the subject string, they are not allowed in a pattern string because it is passed as a normal C string, terminated by zero. The escape sequence "\0" can be used in the pattern to represent a binary zero.

5. The following Perl escape sequences are not supported: \l, \u, \L, \U, \E, \Q. In fact these are implemented by Perl's general string-handling and are not part of its pattern matching engine.

6. The Perl \G assertion is not supported as it is not relevant to single pattern matches.

7. Fairly obviously, PCRE does not support the (?{code}) construction.

8. There are at the time of writing some oddities in Perl 5.005_02 concerned with the settings of captured strings when part of a pattern is repeated. For example, matching "aba" against the pattern /^(a(b)?)+$/ sets $2 to the value "b", but matching "aabbaa" against /^(aa(bb)?)+$/ leaves $2 unset. However, if the pattern is changed to /^(aa(b(b))?)+$/ then $2 (and $3) get set.

In Perl 5.004 $2 is set in both cases, and that is also true of PCRE. If in the future Perl changes to a consistent state that is different, PCRE may change to follow.

9. Another as yet unresolved discrepancy is that in Perl 5.005_02 the pattern /^(a)?(?(1)a|b)+$/ matches the string "a", whereas in PCRE it does not. However, in both Perl and PCRE /^(a)?a/ matched against "a" leaves $1 unset.

10. PCRE provides some extensions to the Perl regular expression facilities:

(a) Although lookbehind assertions must match fixed length strings, each alternative branch of a lookbehind assertion can match a different length of string. Perl 5.005 requires them all to have the same length.

(b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $ meta-character matches only at the very end of the string.

(c) If PCRE_EXTRA is set, a backslash followed by a letter with no special meaning is faulted.

(d) If PCRE_UNGREEDY is set, the greediness of the repetition quantifiers is inverted, that is, by default they are not greedy, but if followed by a question mark they are.


 

ODBC Logging

To turn ODBC Logging on, create in "ODBC Data Source Administrator" a data source named "ArgusLog". In the database, create a table named LogStrings with the following mandatory columns: three text columns called "Logger", "RecTag", and "RecMsg" and a timestamp column "RecTime". You may also add additional 'row number' fields, but make sure they are automatically updated, Argus would never write there. Argus doesn't currently log other information to ODBC. To add log records, Argus executes the following SQL statement:

INSERT INTO LogStrings (Logger, RecTag, RecTime, RecMsg) VALUES (?, ?, ?, ?)

You may issue the following SQL statement to create LogStrings table under Microsoft Access:

create table LogStrings (
 RecId counter NOT NULL CONSTRAINT RecIdIndex PRIMARY KEY,
 Logger char(20) NOT NULL,
 RecTag char(1) NOT NULL,
 RecTime date NOT NULL,
 RecMsg char(250) NOT NULL);

Then go to Config/Start-up, turn ODBC logging on and restart Argus. ODBC errors are logged to "odbcerr.log" file in Argus logs directory.

 

We need your help!

There are parts that are not included in this manual because we are simply have no time to write such comprehensive program and the help file simultaneously. If you are willing and feel able to help us please contact us via e-mail: argus@ritlabs.com or 2:469/84@fidonet

 


Copyright © 1996-2000 RIT Research Labs. All rights reserved.