QStat Version 2.1a
** UPDATED for 2.1a **
Oct 4, 1998

This release supercedes previous 2.1 releases (2.1z BETA and 2.1y BETA)

Summary of New Features
-----------------------
Unreal 2.15+ support			(option -uns)
Broadcast queries			(prefix address with '+')
Save lists from master servers		(option -qw,outfile and -q2m,outfile)

Bug Fixes
---------
Fixed host cache on Intel platforms
Report Host Not Found as a server error (so it appears in templates
	and raw output)

New variables for output templates
----------------------------------
Server template variables
$HOSTNOTFOUND	True if the host name lookup failed

Player template variables
$MESH		Player mesh (model) name (Unreal only)

Notes
-----
QStat will support the public Unreal master server once it's
done.  The current Unreal master server is private to GameSpy
(snarl).

The broadcast queries is an experimental feature.  I've only
tested it with Quake II.  Other games will be tested and
supported in later releases.  For example, querying the local net for
Q2 servers on the default port:
	qstat -q2s +255.255.255.255
The '+' makes QStat broadcast to the given address.  The default
broadcast address for all nets is 255.255.255.255.  You can
also use a network specific broadcast (eg. 199.2.18.255).  On
Unixes, 'ifconfig -a' will display the broadcast address for
all attached networks.

The ",outfile" option for master servers is handy for dealing with
unreliable master server (such as the id Q2 master).  Run qstat
once to save the servers lists to files, and a second time to
query the servers:
	qstat -q2m,outfile satan.idsoftware.com,idq2.lst
	qstat -f idq2.lst
The first command saves the server list from the id Q2 master into
"idq2.lst".  If the master isn't working, then the file retains
its previous contents.  The second command queries the servers in
that file.

I've also included the templates for an example Unreal server
list web page.

Thanks to my wonderful users for reporting bugs and making
suggestions.  And a special thanks to the Unreal development team for
actually documenting their query protocol (unlike some other well known
first person shooter developers).

Steve, steve@activesw.com



** UPDATED for 2.1y BETA **
Aug 22, 1998

Summary of New Features
-----------------------
HexenWorld support
Revived support for id's Q2 master
New variables for output templates
Faster host cache initialization
More efficient server query (Unix only)
Support for AIX 4.2 and HPUX 11.0


Bug Fixes
---------
Fixed bogus query failure on second server on same IP address.
Fixed to ignore QW and Q2 server packets that contain lots of error
	messages.  Also disabled printing of the "Odd packet" messages.
	They can be enabled with the -errors option.
Fixed output templates on Windows

Non-feature
-----------
Unreal support.  Unreal needs to get fixed before QStat can support it.


HexenWorld support
------------------
Use the -hws command line option, or the HWS server type key.

Revived support for id's Q2 master
----------------------------------
id's Quake II master server was broken for a long time.  QStat
supported id's Q2 master, but the master only rarely returned anything
(and you had to wait up to 30 seconds for a response).  When QuakeSpy
announced that id had fixed their Q2 master, I was surprised that QStat
did not work on the fixed master.  Turns out the "fix" also changed the
query protocol slightly.

New variables for output templates
----------------------------------
General variables
$\		Inhibit output of the next newline.

Server template variables
$HEXENWORLD	True if the server is HexenWorld (use with $IF)
$UNREAL		True if the server is Unreal (use with $IF)

Player template variables
$DEATHS		Number of deaths (Unreal only)
$TEAMNUM	Team number (Unreal only)

un-Unreal support
-----------------
I implemented support for the original Unreal server status protocol.
However, the Unreal server worked so poorly as to be unusable.  Unreal
is getting improved Internet support, but it's not ready yet.  When
Unreal gets fixed, QStat will support the new protocol.


I've also included the templates I use for the status page of my
own Quake II servers.

Steve, steve@activesw.com



** UPDATED for 2.1z BETA **
Feb 28, 1998

Summary of New Features
-----------------------
Output templates (HTML generation)
Server sorting
Host name and IP address cache
Support for Quake II master

New Flags
---------
See the documentation (qstatdoc.html) for complete details.

-default server-type
	Set the default server type which should be one of: QS, QW, QWM,
	H2S, Q2, or Q2M.
-Hcache file
	Host name cache file
-sort sort-key
	Sort the servers by the sort-key
	p	sort by ping
	g	sort by game
-Tserver file
	Server output template.  Displayed once per server.
-Tplayer file
	Player output template.  Displayed once per player (if -P is used)
-Theader file
	Header output template.  Displayed once before any servers are output
-Ttrailer file
	Trailer output template.  Displayed once after all servers and players
	are output.
-q2m	Get servers from Quake II master server

Summary of Enhancements
-----------------------
Remove duplicate server addresses before query
Reduce memory usage when -R and/or -P are not specified
Work-around a memory leak in Solaris 2.5
Wait for results from all master servers before starting to query servers
VMS support

Release Notes
-------------
This is a major new release of QStat.  There is over 1400 lines of new
code with all the benefits and drawbacks therein.  I hope you like the
features, but I really hope it's not riddled with bugs.  There might be
some portability issues since I only have access to Solaris, HP-UX, Irix,
and Windows NT.  If you have a problem compiling, please send me a note.

No major new features are planned for 2.1 beyond what you see here.
However, I plan to make enhancements to the sorting and template code
before final release.  Please tell me what is missing.  Obvious
deficiencies include:
- No per-server output files (can't have a server list with a link
  to a page with details about each server).
- Missing $ELSE ($IFNOT is a cheap replacement)
- Flexible $IF expressions would be nice
- The output template variable syntax is kinda lame: you use
  $(IF:RULE(email)) to test for a rule and $(RULE:email) to output the value
- Can only sort on ping and game.  Would like to add map, players, etc
- Can't sort the player lists
- Host cache administration might be nice (re-verify command)
- Host cache sharing.  Use file locking to allow multiple qstats to
  share the same host cache.

Presence on the list above does not guarantee implementation!  Please
tell me what you want, even if it's listed above.

A host name cache can take a _long_ time to build the first time (30
minutes, minimum).  I will try to keep starter cache files on the QStat
web site.  The current cache file for servers in the QW masters
contains over 1000 entries.

I've included sample output templates for HTML.  They are not the
best HTML, but they demonstrate some of the neat tricks you can do.
If you use the templates with '-R', then server rules like email
and web will be output as links next to the server.  If you get
player status (-P), then a subtable is output with player info
formatted with the correct columns for the server type.  A sample
command line to use the templates:

qstat -f myservers.txt -Ts template/server1.html -Th template/header1.html
	-Tp template/player1.html -Tt template/trailer1.html > myservers.html

(The template files in qstat21z.zip have a ".htm" extension)

Finally, the id Quake II master has a bug (gasp!) that makes it _very_
slow to respond some times.  QStat tries to work-around the bug by
increasing the retry interval by 20 times while waiting for a response
from a Quake II master.  The retry interval is restored once all the
masters have been queried.

Thank you for your support.



** UPDATED for 2.0b **
Dec 29, 1997

- Fix map name for Quake II 3.07-09
  The rule key changed from "map" to "mapname".  If both are present,
  then "mapname" takes precedence.
- Q2: Noticed some servers are running custom games.  The rule keys for
  games are confusing:
	"gamename"	Always seems to be set to "baseq2", unless a
			custom game is being run, in which case "gamename"
			is not set at all.
	"gamedir"	Probably the same as "*gamedir" in QW.
	"game"		Always the same as "gamedir" in the servers I
			stat'd.  Maybe this can be used to indicate the
			name as well as the version of the game being
			run.
  For now, QStat displays the value of the "game" key in the non-raw
  output of Q2 servers.
- Print file name and line number information with errors when reading
  files.
- new option: -progress    display progress meter
	Thanks maynard@ultra.net

Leave for the Holidays and the id boys change the protocol.  A minor
change, but a few QStat users noticed right away.  The change does
not affect people using -raw.



** UPDATED for 2.0a **
Dec 9, 1997

- Support for Quake II servers, see documentation for usage.
- Minor fix to connect time formatting.

I don't have Quake II, but the status protocol is very similar to
QuakeWorld, so I was able to figure it out by poking existing Quake II
servers on the net.  Id has stated that the network protocol will
get an upgrade soon after the in-store release.  As always, QStat
will track these changes as they become available.



** UPDATED for 1.6 **
Nov 30, 1997

Changes since beta5.  Minor enhancements and a few fixes.

- Removed all the annoying copyright restrictions.
- Added option -ne : no empty servers
	Thanks secabeen@fnord.rh.uchicago.edu
- Added option -raw-arg : special for QStatList (see qstat docs)
	Thanks darkgrue@iname.com
- Added option -timeout : total time in seconds before giving up
	Can prevent overlapping runs when cron runs qstat every five
	minutes.
- Added gamedir to QW server output (not -raw)
- Fixed bug getting long server lists from QuakeWorld masters.  Can now
  get lists in excess of 16,000 servers.  How long til that limit is
  exceeded?
- Fixed bug using -H with -qw
- Fixed use of select() so systems with large file descriptor limits
  can query more than 64 servers at a time.
- Overhauled the web page, but it is still gif-less.

QStat 1.6 has been in alpha / beta just short of a year (1.6 alpha
was released Dec 20, 1996).  It has been a good year.  Many thanks
to those who sent suggestions, kind words, and bug reports.  And
appologies to those who have not seen their request implemented,
or who did not even receive a reply.

  "Mmmgufm gumerfm rerfgmmf."
  "That's right, Kenny, Steve is a busy guy and doesn't care about
   your stupid problems."
  "Merfgl! gumerfm rerfgmmf!"
  "Dammit, Kenny, turn down the computer, I can't hear you over the
   splattering bodies."
  "Gumerfm rerfgmmf."
  "Oh.  Kenny says, Steve does care about your problems, but not the
   stupid ones."
  [ A large core dump falls on Kenny, killing him. ]
  "Steve killed Kenny!  You bastard!"

Quake II gives me an excuse to crank up the major version dial.
QStat 2.0 will feature support for Quake II servers.




** UPDATED for 1.6 beta5 **
Oct 5, 1997

Kitchen sink release to add some of the most requested features.

- Extended file format.  The file used with the -f option can include
  server type information to distinguish between Hexen II, Quake, and
  QuakeWorld servers.  You can put all your servers into one file and
  query them all with one qstat invocation.
- Fix bug that caused a QuakeWorld master server query to never timeout.
- New option -h2s for specifying a single Hexen II server to query.
- New option -maxsimultaneous limits the number of simultaneous server
  queries.  Previously configurable by modifying the MAXFD #define in
  qstat.h.
- Updated docs [FINALLY!]
- Compiles on HP-UX 10.20
- Changed packaging: files are in a directory named for the version
  of qstat, and use gzip instead of compress on unix
- Removed pre-QuakeWorld 1.5 support.  The -qw1.5 option is obsolete
  and no longer needed.  As are the -qwuserinfo and -qwseeninfo options.
- Smarter about when to include server type prefix in formatted output

Unless I hear cries for more features, this will be the last beta
before the final release of qstat 1.6.  Now that the docs are up to
date, I've run out of excuses for doing the release.



** UPDATED for 1.6 beta4 **
Sept 2, 1997

Qstat has gone through some minor revs of beta3 and the arrival of
Hexen II sparked the need for another release.  Summary of fixes and
changes:

- Support for Hexen II servers.  Use the -hexen2 mode to query Hexen II
  servers:
	qstat -hexen2 -R -P 165.166.143.15 208.131.24.189
  You cannot mix queries of Quake and Hexen II servers.  This limitation
  will be fixed in the final 1.6 release.  However you can mix QW and
  Hexen II queries in one qstat command.
  [Thanks to Michael Long, mlong@infoave.net, for getting me the protocol
   magic for Hexen II.]
- In the formatted display output (as opposed to -raw), a Hexen II server
  is indicated with a H2S prefix.  This will only be seen if qstat is
  using different quake protocols at the same time (eg. query a Hexen II
  and QW server in the same command).
- Various fixes to deal with bogus packets from QW servers.  The lastest
  one is caused when the QW server info packet is truncated.  It appears
  that there is a fixed buffer of 1600 bytes in the QW server for building
  server info responses.  The QW server programmers may want to consider
  increasing this value.  On Ethernet, two packets must be used to send
  1600 bytes (Ethernet frame size 1518, subtract ~50 for header, leaving
  ~1468 for data).  Might as well set the buffer size to ~3000 bytes so
  two full packets can be used.
- There's some wierd problem on Linux which causes bind() to occasionally
  fail with EADDRINUSE.  Fixed the code to consider this a transient
  error and retry the address at a later time.  If you saw messages like:
	bind: Address already in use
	send: Invalid argument
  from qstat, then this fixes that.

No time table for the final 1.6 release.  Other than updating the docs,
I don't plan any significant new features.



** The docs have not yet been updated.  This is all you get for now. **

** UPDATED for 1.6 beta3 **
April 3, 1997

D'oh!  Should never do releases just after midnight.  Beta2 had an
old win32 executable.  Also forgot to check for NULL map name in
the -raw display code.  Sorry!


** UPDATED for 1.6 beta2 **
April 2, 1997

Features in 1.6 beta2 beyond beta1
Fix crash on negative player colors
New option -qw1.5
	Use the QuakeWorld 1.5 protocol.  Affects the interaction
	with a QW master (-qw).  Fortunately, the rest of the protocol
	hasn't changed.  I imagine the user and seen info won't be
	available from a QW 1.5 master.  The user and seen flags will
	remain until I have a better understanding of where QW is going.

Had to fix a bunch of crashes related to QW 1.5 servers.  Some of them
don't have common keys like "map".


** UPDATED for 1.6 beta1 **
Feb 7, 1997

Features in 1.6 beta1 over the 1.6 alpha releases:
Changes to -qw option
	Support for user names and user ids
	Defaults values ("qstat") for user id and password.  Most of
	the QW masters have a qstat user with "qstat" as the password.
New option -qws
	Fetch and display stats for a single QW server.
New option -qwuserinfo
	Fetch and display user information from a QW master.
New option -qwseeninfo
	Fetch and display user information from a QW master.
bug fix
	Better handling of error packets from QW servers and masters.
	No more "huh?"

Thanks to Kris Nosack (kn@byu.edu) for comments and bug reports.

** The following has been updated to reflect the changes and
** additions in 1.6 beta1.


The main feature of this release is support for QuakeWorld.  A couple
minor bug fixes have also been made.

QuakeWorld support has been integrated into qstat.  You can query
normal Quake servers and QuakeWorld servers at the same time.  A new
prefix is used to distinguish between the different server types.


New options
-----------

All of these options can be used together in a single run of qstat.

To query QuakeWorld servers, use the -qw or -qws options.  The first
will get the list of QW servers from a QW master and query all of
them for status information.  The latter, -qws, will just query the
given QW server for status information.  These options are the only
way to get QuakeWorld server stats.
Hosts added with -f or on the command-line are treated like normal
Quake servers.

-qw host:port:uid:password

host		host name or IP address of QW Master Server
port		port number (defaults to 27000 if blank)
uid		valid QW user id or name on host
password	password for user

To get the server list from a master server, qstat needs a valid login
on the master.  A default login and password can be used if the uid and
password are not given.  The default is "qstat" for both values.  All
the known masters should have a "qstat" user with the same password.

-qws host:port

host		host name or IP address of QW server
port		post number (defaults to 27500 if blank)

If you don't use -qw or -qws, qstat will behave identically to qstat 1.5.

I use the following command to query QW servers:

	qstat -qw 204.50.178.66


To get QuakeWorld user information, use the -qwuserinfo and -qwseeninfo
options.  A QW login is not required to get user information.

-qwuserinfo host:port user-list

host            host name or IP address of QW Master Server
port            port number (defaults to 27000 if blank)
user-list	list of QW users (ids or names)

The display for a user will include everything in their record.  The
color name option (-ncn) is applied to 'topcolor' and 'bottomcolor'.
The user-list must be _one_ command line argument; use double-quotes
to enclose multiple users if they're separated with spaces.  You can
also use back-slashes to separate users.

-qwseeninfo host:port user-list

host            host name or IP address of QW Master Server
port            port number (defaults to 27000 if blank)
user-list	list of QW users (ids or names)

The last seen information comes directly from the master, qstat does
not perform any additional formatting.  The user-list should be _one_
command line argument; use double-quotes to enclose multiple users if
they're separated with spaces.  You can also use back-slashes to
separate users.

To get user information for me and qstat and find out who was last
slagging me:

	qstat -qwuserinfo 204.50.178.66 "Act-Steve qstat" -qwseeninfo 204.50.178.66 Act-Steve


Display format
--------------

The QW servers return different information than the normal servers,
so I had to extend the output style.  The first field of a server
status line is the server type:

QS	normal Quake server
QW	QW server
QWM	QW master server
QWU	QW user information
QWE	QW last seen information

The for-human-comsumption output is pretty self-evident, but the raw
output needs some explanation.  The output for normal Quake servers
has not changed.

QWM server status fields
	server address, number of QW servers
	[the uid and password are removed before display, no rules or
	 player info is output]

QW server status
	server address, server name, map name, max players,
	current players, avg response time, number of retries
	[If -R is specified, a line of server rules is output.  The
	 format is the same as for normal servers: key1=value1,key2=value2]
	[If -P is specified, one line is output for each player.]
	player uid, player name, frags, connect time, shirt color,
	pants color, ping, skin

QWU
	key1, value1, key2, value2, ...
	[The first seven keys will always be the same; name, userid,
	 skill, efficiency, rank, frags, deaths.  But I would not count
	 on that as I'm a fickle programmer and may change my mind.]

QWE
	seen-info
	[qstat just displays the string returned by the master.  The
	 user name is embedded in there, but you'll have to parse it
	 out.]

All the existing display options apply to QW servers.

Run qstat by hand to better understand the new output before trying to
incorporate it into your web page.


Errors
------

QStat has a variety of ways of reporting errors such as time outs
and server errors.  If you see something between angle brackets,
<like this>, that's an error message directly from a server or
master.

Some day I'll document how errors are displayed in the raw format.
But for now I trust you web masters can figure it out


Final words
-----------

This version is very beta.  If you would like qstat to work differently
let me know.  And of course, if you have problems or questions, please
let me know.

Known bugs
----------

qstat often fails to get all the QW server lists if multiple QW masters
are specified.  You'll see a TIMEOUT or "no response" from the QWM when
this happens.  I have a fix in mind, but I'm tired and there's beer
waiting for me at home.

An error is not displayed if qstat times out getting user or last seen
information.


Steve Jankowski
steve@activesw.com


---

Version 1.5 adds player info, server rules, response times, and
performance improvements.  A large number of flags were added to support
different output formatting options.  Web masters should check out
the -raw option which displays all server info with your choice
of delimiter.  Updated copyright to be more specific about allowable
use.  Updated the web page with links to Quake protocol pages.

Version 1.4 includes a number of new features and bug fixes.  There is
now support for Linux, flags to set retry timeout and interval, flags
to limit output to running or not full servers.  A bug was fixed which
caused qstat to have a long delay the first time it was run on Windows
95/NT.

Version 1.3 fixes a bug introduced in 1.2 and adds a Windows 95/NT
executable.  The bug caused DOWN servers to be reported multiple
times.

Version 1.2 fixes the bug with running out of file descriptors.
