-----------------------------------------------
Digital Equipment Corporation 
ATMworks 350 
Console Applications
-----------------------------------------------

Release notes for Digital Equipment Corporation's set_mask.exe,
journal.exe, and oppo_mac_addr.exe console applications.

-------------
Sections
-------------

1.)  Introduction
2.)  Operational Requirements
3.)  Operational Notes
4.)  Using the console applications
5.)  Known Bugs

SECTION 1:  INTRODUCTION

This readme.txt file covers the use and operation of three console 
applications; journal exe, set_mask.exe, and oppo_mac_addr.exe.  
The console applications provide a set of engineering utilities that
enable a user to access useful information about the ATMworks 350.
Section 4 contains more details on this information.


SECTION 2:  OPERATIONAL REQUIREMENTS	

To run these console applications, the following requirements must
be met:
  - Running Microsoft Windows NT versions 3.50 or 3.51 
    on a Alpha or Intel-based platform.

  - A Digital ATMworks 350 PCI/ATM NIC,

Loading the executables is easy.  Simply copy them into any 
directory/subdirectory on either the local hard disk or a floppy 
disk.  Then run them from that location.  For example, if you 
copied the executables to d:\utilities, then you would invoke 
"journal" by entering the command "d:\utilities\journal dglpb1".


SECTION 3:  OPERATIONAL NOTES

The operation of all three console applications is simple.  
All three are launched from either a DOS window or from the File
Manager.  Like many console applications, set_mask.exe and 
oppo_mac_addr.exe perform a single function, report the results to
the user's display, and terminate.  However, unlike many console
applications, journal.exe continuously runs until the user presses
<CTRL-C>.  Journal.exe spends all its time querying the driver for
events.  This behavior allows a user set new event masks in one DOS
window, while running journal.exe in another DOS window.  It is 
unnecessary to set an event mask prior to running journal.exe.  
A successful set_mask.exe changes the reported events in 
journal.exe almost immediately. 

The use of the "start" command from a DOS window is recommended
only for journal.exe.

SECTION 4:  USING THE CONSOLE APPLICATIONS

There are a number of modules and event mask available to the user.  They are:

Module IDs:
   Connection Manager:     101
   Signaling:              102
   LEC Data:               103
   LEC Control:            104
   LEC ARP:                105
   Upper Driver:           106
   Lower Driver:           107
   Initialization:         108
   ILMI IO:                109
   Address Registration:   110
   Line Up:                111
   SNMP:                   112
   MIB II:                 113
   ILMI MIB:               114
   DEC MIB:                115
   Utility OS:             116
   Diagnostics:            117
   Flow Control:           118
   OAM:                    119
   ATM IP:                 120
   ATM ARP:                121
   OPPO:                   122
   Classical IP:           123
   Task:                   124

For each module id, there are the following events:

Supported Events:
   Severe Error:                1
   Normal Error:                2
   Warning:                     4
   Assertion Failure:           8
   State Transition:           16
   Normal Event:               32
   Received Control Frame:     64
   Transmitted Control Frame: 128
   Received Data Frame:       256
   Transmitted Data Frame:    512
   Code Path Trace:          1024
   Timer Events:             2048
   Memory Management Events: 4096
   Message Contents:         8192

Events masks are 32 bit values, with each bit having a 
unique meaning.  To select a single event, use the 
corresponding value from the above table.  To select multiple
events, use a sum of values from the above table.  To disable
all events, use the value 0.

Console Applications

1.)  set_mask.exe

	Calling syntax:
	prompt> set_mask ServiceName ModuleID EventMask

	where:
	   set_mask is the executable name.
		ServiceName is the NIC name.
		ModuleID is a value from the above module table.
		EventMask is a value that is described above.
	
	Remarks
		Application returns with no message if set is successful. 
		Otherwise, an error message is displayed.  
		Note, setting an event mask is not a required step.  If a 	
		user does not set a particular event mask for a particular
		module id, a default is used.

	Example Output
		prompt> set_mask Dglpb1 105 2047
		- none on successful set.
		- "Service Dglpb1: Event Mask Set Error on event mask 2047!"
		  "Return code from IOCTL call is: 32"
		   This last message implies that either the event mask is not
		   supported or possibly the module id is not supported.  The 
		   error message is not fatal.  

2.)  oppo_mac_addr.exe

	Calling syntax:
	prompt>  oppo_mac_addr

	Remarks
		This application requires no additional command-line arguments.
		Upon termination, the user will see a list of all Dglpbx 
		services and their MAC addresses.  The MAC address 	
		is the End System Id, or ESI, and can be used in the ATM address
		configuration for LAN Emulation or Classical IP options during
		adapter configuration.

	Example Output
		prompt> oppo_mac_addr
		If successful
		- "Found the following MAC Addresses for Dglpb1:"
		  "The Permanent MAC address is: 08-00-2B-80-21-28"
		  "The Current MAC address is:   08-00-2B-80-21-28"
		
		If failure
		- an error message indicating why a MAC address could not be found.
		  Or nothing if there are no Dglpb services.
		

3.)  journal.exe

	Calling syntax:
	prompt>  journal ServiceName

	where
	 	journal is the executable name
		ServiceName is the NIC name.

	Remarks
		This application provides continuous event reporting for 
		the given ServiceName.  The application doesn't terminate
		until the user presses <CTRL-C> or an execution error occurs.
		The application writes the messages to two places:  the display 	
		and a file called "eventlog.txt".  The application creates the
		file in the same directory as the executable.  The user cannot
		select the file name.

	Example Output
		prompt>  journal Dglpb1
		If successful
		- stream of messages - 1 message per line.
		If failure
		- application terminates


SECTION 5:  BTWs
	1.)  This application does not control the window size or 
	     buffer size of the DOS display.  The user is responsible 
	     for sizing the window and buffer of any DOS window used.  
	     The window and buffer size have no affect on the data 
	     written to the journal file, eventlog.txt, but messages 
	     that overflow the window area are not viewable.

	2.) There are important considerations concerning the created
	    file, eventlog.txt.  The application does not provide any 
	    mechanism to erase or otherwise remove the file contents 
	    once the file is created.  The user is responsible for 
	    deleting this file or manually entering some type of 
	    delimiter indicating a new message set.  Otherwise, this 
	    application will continue appending new messages to the 
	    end of the existing file.
