------------------------------------------------------------------------------
File name:	RESOLVE.TXT			Revision date:	1998.01.19
Created by:	Ulf Ronald Andersson		Creation date:	1997.05.13
mailto:		dlanor@oden.se			version:	1.08
------------------------------------------------------------------------------
Purpose:	Describes the cache control commands available
		through the resolver domain name argument string
		of the RESOLVE.STX module for STinG.  There is
		also an update history of the module at the end.
------------------------------------------------------------------------------
Remarks:	Much of this information is of no interest to the
		average user who does not use STinG for LAN, but
		only for a dial-up connection to an ISP.  LAN users
		will find it useful to set up local network names.
		This way the resolver eliminates nameserver needs.
------------------------------------------------------------------------------
Introduction:

Most TCP/IP client programs allow the user to type in IP addresses in the form
of symbolic domain names or numeric (dotted IP) addresses. These are then used
as an argument in calling the resolver module to gain the missing information.
By using a command syntax  illegal for either  symbolic or  numeric addresses,
my resolver module allows such interfaces to be used for commands as well.

The recommended method to use these commands is to do so through the 'Resolve'
tool of the STinG dialer program written by  Peter  Rottengatter.  Using other
client interfaces should also work but may have side effects in those programs.
(Usually causing connection attempts to the IP addresses of stored entries.)

All command keywords begin and end with square brackets ('[' and ']'), and any
unknown sequence starting with a left square bracket will have no effect,  but
will cause the resolver to return the  error code 'E_CANTRESOLVE'.  That  code
will also be returned for any commands that fail, regardless of actual causes.

The reason for this is that some clients test for that error code only.  These
would attempt to use some garbage data if I use another error code, with bombs
resulting from that attempt.  All successful commands will resolve some  cache
entry on completion, to provide a visible indication of the success.  The only
exceptions are [FIRST] and [NEXT] when used so as to get a nonexistent entry.
That will naturally return E_CANTRESOLVE, though there was no real failure.

Blank characters (Tabs and spaces) will be ignored both around and between all
keywords, arguments and separators, but may not be used within such units.

NB: Here period signs ('.') are not considered as unit separators, but rather
    as operators, building full addresses and names from substrings.  Domain
    names and dotted IP numbers are not allowed any internal blanks.
    The only separators currently defined are '=' and ':'

Within the square brackets of a command character case is neither preserved
nor significant, so "[LOAD]" does the same as "[load]" or even "[LoAd]" etc.

------------------------------------------------------------------------------
Command list:		Six commands are defined at present

[LOAD]		no argument	Loads the CACHE.DNS file into RAM from disk
[SAVE]		no argument	Saves the CACHE.DNS file from RAM onto disk
[FIRST]		no argument	Resolves the root entry of DNS RAM cache
[NEXT]		no argument	Resolves the next entry of DNS RAM cache
[CNAME]	arg1 = arg2 : arg3	Defines a canonical domain name for an IP
[ALIAS] arg1 = arg2 : arg3	Defines an alias domain name for an IP

The last two commands have identical syntax and the meaning of argument is:

arg1	The domain name.	eg: hugin.oden.se	(My ISP's main server)
arg2	The dotted IP.		eg: 193.45.240.2	(IP number of the same)
arg3	Time To Live (seconds)	eg: 172800		(valid for two days)

The TTL entry and the preceding ':' are optional, and if excluded a default of
10 years will be used. This is intended for entry of semi-permanent IP numbers
on your local networks, and  allows fully symbolic addresses to be used on any
small  intranet as well as on internet.  No nameserver is needed for this, and
that is important since none is available under TOS as yet.

NB: In order to define an alias, you must *FIRST* define the canonical name of
    that IP number.  Aliases are linked in via the canonical entries, so those
    must exist first.  (This is handled automatically for network queries.)

The two commands [FIRST] and [NEXT] can be used to scan through all entries of
the cache since E_CANTRESOLVE is returned as the end of the cache is reached.

For technical reasons FIRST here means the latest defined CNAME, and the last
entry will be the oldest ALIAS of the oldest CNAME, or that CNAME itself if
the oldest one does not have any aliases.  This is how the cache is organized,
and the scanning order follows this pattern consistently.  Thus aliases are
defined relative to their CNAME, and the order in which they were defined
also relates only to the other aliases of the same CNAME.

------------------------------------------------------------------------------
Command results as returned to the resolving client program:

keyword		Results
-------		-------
[LOAD]		Resolves the 'root' entry of successfully loaded cache
[SAVE]		Resolves the 'current' entry of the cache on successful save
[FIRST]		Resolves the 'root' entry of the cache, unless it is empty
[NEXT]		Resolves the 'next' entry of the cache, unless already at end
[CNAME]		Resolves the entry defined, if that succeeds
[ALIAS]		Resolves the entry defined, if that succeeds

NB: For safety reasons given in the introduction, all failures of the commands
    will be returned to the calling client as the error code  'E_CANTRESOLVE'.
    That is the only code which ensures that no erroneous data will be used as
    if it was valid, which could lead to 'bombs'.

NB: Since most clients will attempt to make some use of each resolved address,
    I strongly suggest that only the STinG dialer's 'Resolve' tool be used to
    enter the commands.  That is the only client I know of which will never
    use the so resolved addresses on the network.

------------------------------------------------------------------------------
Update history for RESOLVE.STX

Version		Major changes from last version
-------		-------------------------------
  1.08		Corrected a misleading string in an error message.
98.01.19	Revised negative caching of failed inquiries for
		numerical IP's.  The new method will allow proper
		resolving at later date when the resulting dummy
		name has been saved for reuse by a client (hotlists).

  1.07		Added module basepage pointer to LAYER structure.
97.10.25	This is a new standard defined to ease debugging.

  1.06		Modified [NEXT] to recognize cache end in user scans
97.09.24	Fixed bug returning E_NOMEM on RAM error to use E_CANTRESOLVE
		Fixed bomber bug in cache that struck ALIASes without CNAMEs
		Added multiple IP return to network DNS queries
		Added multiple caching for DNS queries with multiple results
		Added multiple IP return to DNS cache queries
		Added ICMP error message response, so all LAN machines notice
		  when DNS requests to ISP fail due to offline state

  1.05		Removed case sensitivity from command word interpreter
97.09.12	Restructured some caching code

  1.04		Fixed some command bugs
97.08.06	Fixed some caching bugs
		Changed local name ttl default to eternity, to avoid losing
		  entries when starting without proper time set.

  1.03		First proper release
97.06.??	Implemented cache commands
		Fixed various bugs
		Restructured some DNS query code

  1.02		First functional version
97.05.??	Combined caching with network queries
		Implemented UDP retries with TCP fallback
		
 0.00-1.01	Early experimental versions, first by Peter then later by me
  various	These included separately developed code for network queries
		and for the basic cache system (still largely retained).

------------------------------------------------------------------------------
End of file:	RESOLVE.TXT
------------------------------------------------------------------------------
