(C) Copyright 1986-1998  Rainbow Technologies Inc. All Rights Reserved

API.TXT for Assembly Language.

-------------------
GENERAL INFORMATION
-------------------

------------
DEVELOPER ID
------------

  The developer ID is provided on separate documentation.
If the developer ID is not known, none of the functions will
work.

---------
PASSWORDS
---------

  There are 2 SuperPro passwords, the write password and the
overwrite password. The overwrite password is composed of 2
words, word 1 and word 2.  The passwords are provided on
separate documentation and are required for writing,
algorithm activation and counter decrement operations.

---------
ADDRESSES
---------

  The SuperPro address range is from 00 - 3F Hex.  All
addresses are always specified as Hex.

------------
ACCESS CODES
------------

  The values for the access codes are defined as

    0 - Data word
    1 - Locked data word
    2 - Counter word
    3 - Algorithm word

  The access code values are used in reading and writing to
the SuperPro key.

----------------
UNIT INFO RECORD
----------------

  The SuperPro driver uses the data in the unit info record
for communicating with the SuperPro key.  The programmer
should never modify the data in the unit info record.

  A NIL value can be passed as the unit info record pointer.
In this case the functions will use the data which is
maintained in the application packet interface.  The
application packet interface will always contain the unit
info record data from the last SproFindFirstUnit or
SproFindNextUnit.

  The Assembly definition for the unitInfo field is shown
in the UNITINFO DESCRIPTION at the end of this document.

-------------
RETURN VALUES
-------------

  All functions will return 0, SP_SUCCESS, on success.
All other values indicate an error.  The other error codes
are defined in the ERROR CODE SUMMARY section at the end of
this document.

--------------------
API PACKET STRUCTURE
--------------------

  API packet is used by SUPERPRO core driver to perform various API functions.
The developer sets up different fields according to the requirements of the
desired API, then calls SUPERPRO function.  The error code coming back from
the SUPEPRO driver is stored in both AX and field called 'Status'.  Other
results are stored in appropriate fields.


SP_API_PACKET STRUC
functionCode    DB ?            ;00 function code
SPmode          DB ?            ;01h mode of operation (part of the function)
; . . . . . . . . . . . machine specific variables . . . . . . . . . . . . . .
portAddrs       DW 4 DUP (?)    ;02 addresses of port LPT1 - LPT4
		DB 10 DUP (?)   ;0a resererved
delay5usec      DW ?            ;14 loops to make at least 5 microsecond
delay100usec    DW ?            ;16 loops to make at least 100 microsecond
; . . . . . . . . . . . unit specific variables. . . . . . . . . . . . . . . .
unitInfo        DB 24 dup (?)   ;10 unit information
; . . . . . . . . . . . command specific variables . . . . . . . . . . . . . .
writePassword   DW ?            ;30 write enable password
xtraPassword1   DW ?            ;32 low word of overwrite/activate password
xtraPassword2   DW ?            ;34 high word of overwrite/activate password
memoryAddress   DW ?            ;36 memory cell address
memoryContents  DW ?            ;38 cell content (for read or writes)
status          DB ?            ;3a status returned from driver
accessCode      DB ?            ;3b access code (0-3, high byte reserved)
QueryIn         DD ?            ;3c char far * query string
QueryOut        DD ?            ;40 char far * query results
longResult      DD ?            ;44 query response
dataLength      DW ?            ;48 length of query string (in bytes)
InitialPICMask1 DB ?            ;4ah state of the command port
				;NOTE: InitialPICMask1 equates to this offset.
InitialPICMask2 DB ?            ;4bh contents of data port
				;NOTE: InitialPICMask2 equates to this offset.
reserved2       DB 28 DUP (?)   ;4c reserved for internal use
reserved3       DB 516 DUP (?)  ;68 reserved for internal use

SP_API_PACKET ENDS

------------------
SUPERPRO API's
------------------

  API_INITIALIZE
  API_GET_EXTENDED_STATUS
  API_GET_VERSION
  API_FIND_FIRST_UNIT
  API_FIND_NEXT_UNIT
  API_READ
  API_EXTENDED_READ
  API_WRITE
  API_OVERWRITE
  API_DECREMENT
  API_ACTIVATE_ALGORITHM
  API_QUERY


--------------
API_INITIALIZE
--------------

Description:

     This API initializes the SuperPro device and the
application packet interface variables.

Format:

	    ENTER: functioncode    = API_INITIALIZE
		 : SPmode          = Default interrupt methods
		 : PortAddrs       = Default port addresses
		 : InitialPICMask1 = Default PIC register mask 1
		 : InitialPICMask2 = Default PIC register mask 2

	    LEAVE: Status          = 0 if successful


-----------------------
API_GET_EXTENDED_STATUS
-----------------------

Description:

     This function returns the status from the previous
SuperPro API call.

Format:

	    ENTER: functioncode    = API_GET_EXTENDED_STATUS
	    LEAVE: Status          = Previous API call status


---------------
API_GET_VERSION
---------------

Description:

     This function will return the Sentinel SuperPro driver's
version number. If successful, the version information will
be pointed to by the longResult API packet member. The version
information includes both major and minor driver version,
the revision level and the OS driver type that is being used.

Format:

	    ENTER: functioncode    = API_GET_EXTENDED_STATUS
	    LEAVE: Status        = 0 if successful
		   longResult    = 1st byte, Major version
				 = 2nd byte, Minor version
				 = 3rd byte, revision level
				 = 4th byte, OS driver type


-------------------
API_FIND_FIRST_UNIT
-------------------

Description:

     This function finds the first SuperPro key with the
specified developer ID.  If the SuperPro key is found, the unitinfo field
will contain valid data otherwise the unitinfo field data will be marked
invalid.

Format:

	    ENTER: functioncode   = API_FIND_FIRST_UNIT
		 : memorycontents = developer ID

	    LEAVE: Status         = 0 if successful

------------------
API_FIND_NEXT_UNIT
------------------

Description:

     This function will find the next SuperPro key based on
the developer ID maintained in the unitinfo field.  This
function should not be called unless API_FIND_FIRST_UNIT has
returned a successful value.  If this function returns
success, the unitinfo field will contain the data for the
next SuperPro key.  If this function returns an error value,
the unitinfo field will be marked invalid.  To re-initialize
the unitinfo field, use API_FIND_FIRST_UNIT and optionally
API_FIND_FIRST_UNIT depending upon the number of SuperPro keys
found and which one your program wants to access.

Format:

	    ENTER: functioncode = API_FIND_NEXT_UNIT

	    LEAVE: Status       = 0 if successful
		   unitInfo     = new unitInfo from new key


--------
API_READ
--------

Description:

     This function will read a word at the specified address
of the SuperPro key identified by the unitinfo field.  On
success, the data variable will contain the information from
the SuperPro key.  If the error code is SP_ACCESS_DENIED,
an attempt was made to read a non-readable word (algorithm
word).  For security reasons, algorithm words cannot be
read.

Format:

	    ENTER: functioncode  = API_READ
		 : memoryaddress = address to be read

	    LEAVE: Status        = 0 if successful
		 : memorycontents= contents of the target cell

-----------------
API_EXTENDED_READ
-----------------

Description:

     This function will read the word and access code at the
specified address of the SuperPro key identified by the unitInfo
field.  On success, the data variable will contain the
information from the SuperPro key and the access code
variable will contain the access code.  If the error code is
SP_ACCESS_DENIED, an attempt was made to read a non-
readable word (algorithm word).  For security reasons,
algorithm words cannot be read.

Format:

	   ENTER : functioncode  = API_EXTENDED_READ
		 : memoryaddress = address to be 'xread'

	   LEAVE : Status        = 0 if successful
		 : memorycontents= contents of the target cell
		 : accesscode    = access code of the target cell


---------
API_WRITE
---------

Description:

     This function is used to write a word and its associated
access code to the SuperPro key identified by the unitinfo
field.  Writing to the SuperPro key, requires knowing the
write password.  The word data is placed in the data variable
and it's associated access code in the access code variable.
On success, the data and it's associated access code have been
written to the specified word on the SuperPro key.  If the
error code is SP_ACCESS_DENIED, either the write password
was incorrect or an attempt was made to overwrite a locked
word on the SuperPro key.

     The write function can only be used to overwrite words
with an access code of 0 in the SuperPro key.  To overwrite
words with other access codes, use API_OVERWRITE function.

Format:

	    ENTER: functioncode  = API_WRITE
		 : memoryaddress = target cell address
		 : memorycontents= value to write to target cell
		 : accesscode    = access code for target cell
		 : writePassword = write password

	    LEAVE: Status        = 0 if successful

-------------
API_OVERWRITE
-------------

Description:

     This function is used to write a word and its associated
access code to the SuperPro key identified by the unitInfo
field.  Overwriting to the SuperPro key, requires knowing the
write password and the overwrite passwords.  The word data is
placed in the data variable and it's associated access code in
the access code variable.  On success, the data and it's
associated access code have been written to the specified word
on the SuperPro key.  If the error code is SP_ACCESS_DENIED
either the write password or the overwrite passwords were
incorrect.

     This function can be used to overwrite any word on the
SuperPro key with the exception of the words at addresses 0,
1 and 4.

Format:

	    ENTER: functioncode  = API_OVERWRITE
		 : memoryaddress = target cell address
		 : memorycontents= value to write to target cell
		 : accesscode    = access code for target cell
		 : writePassword = write password
		 : xtraPassword1 = overwrite password 1
		 : xtraPassword2 = overwrite password 2

	    LEAVE: Status        = 0 if successful


-------------
API_DECREMENT
-------------

Description:

     This function is used to decrement the counter at the
specified address of the SuperPro key identified by the unitInfo
field.  If the return value is successful, the counter
has been decremented by 1.  Error return values would occur
if the counter is already 0, the word at the address is
not a counter or the write password is incorrect.

     If the counter is associated with an active algorithm
and the counter is decremented to 0, the associated
algorithm will be made inactive.

     The counter and associated algorithm can appear in the
SuperPro as
     Address    Data
      N - 2     Counter
      N - 1     Counter
	N       Algorithm word 1
      N + 1     Algorithm word 2

     If either or both counters exist, the counter is
associated with the algorithm.  This association will only
exist for
     N = 0C, 14, 1C, 24, 2C, 34, 3C Hex.

     An algorithm can have both an associated password and
associated counters.  The counters can be used to make the
algorithm inactive and the password can be used to make the
algorithm active.  See API_ACTIVATE_ALGORITHM.

Format:

	    ENTER: functioncode  = API_DECREMENT
		 : memoryaddress = cell address to decrement
		 : writePassword = write password

	    LEAVE: Status        = 0 if successful

----------------------
API_ACTIVATE_ALGORITHM
----------------------

Description:

     This function is used to activate the inactive
algorithm at the specified address of SuperPro key
identified by the unitInfo field.  If the return value is
successful, the algorithm has been made active.  Error
return values would occur if the write password is invalid,
the activate password is invalid or the address is not the
address of word 1 of an algorithm having an activate
password.

     The algorithm and associated password will appear in
the SuperPro as
    Address    Data
       N       Algorithm word 1
     N + 1     Algorithm word 2
     N + 2     Activate password word 1
     N + 3     Activate password word 2

 where
   N = 08, 0C, 10, 14, 18, 1C, 20, 24, 28, 2C, 30, 34, 38,
       3C Hex

     An algorithm can have both an associated password and
associated counters.  The counters can be used to make the
algorithm inactive and the password can be used to make the
algorithm active.  See API_DECREMENT.

Format:

	    ENTER: functioncode  = API_ACTIVATE_ALGORITHM
		 : memoryaddress = target cell address
		 : xtraPassword1 = Activate password 1
		 : xtraPassword2 = Activate password 2

	    LEAVE: Status        = 0 if sucessful

---------
API_QUERY
---------

Description:

     This function is used to query an active algorithm at
the specified address of the SuperPro key identified by the
unitInfo field.  The address should be the first word of
the active algorithm.  The query data pointer will point to
the first byte of the data to be passed to the active
algorithm.  The length of the query data is specified in the
length variable.  On success, the query response of the same
length will be placed in the buffer pointed to by the response
pointer.  The last 4 bytes of the response will also be placed
in the longResult field.

     Each query byte may contain any value from 0 to 255.
Each response byte may also contain any value from 0 to 255.
The length of the response will always be the same as the
length of the query bytes.  It is the programmers
responsibility to allocate the memory for the buffers.

     If the address is not the first word of an active
algorithm, the return status will be successful and the
response buffer data will be the same as the query buffer
data.

Format:

	    ENTER: functioncode  = API_QUERY
		 : memoryaddress = target cell address
		 : QueryIn       = 32-bit pointer to packed query string
		 : QueryOut      = 32-bit pointer to packed response
		 : datalength    = length of the packed query string

	    LEAVE: Status        = 0 if sucessful
		 : QueryOut      = 32-bit pointer to packed response
		 : longResult    = last 4 bytes of the response


----------------------
UNITINFO DESCRIPTION
----------------------

API_UNIT_INFO STRUC
DeveloperID             DW ?   ;10 unit's developer id
serialNumber            DW ?   ;12 word serial_number
port                    DW ?   ;14 port address of the unit
unitReserved            DB 18 DUP (?) ; reserved area
API_UNIT_INFO ENDS
------------------
ERROR CODE SUMMARY
------------------

  The following is a summary of all recoverable error code.  Since this error
  code table supports multiple products, please note the product column to
  verify the error codes that apply to your product.

  Status Codes are obtained differently for each product.  For a Sentinel
  Pro, issue either a Get Status command ("03") or a Get Extended Status
  command ("04") in the Sentinel Pro.  For the Sentinel Superpro, the result
  is the error code.  Please consult your manual for more details.

  The following list contains all available status codes that can be
  returned by the Rainbow driver. Some of these codes are specific to a
  particular environment, such as Windows NT.

  Note that the names given here may be different than those found in the
  include files. In those files the names often have a unique prefix.
  Please refer to the section ERROR CODE DESCRIPTION for more details.



  The following is a summary of:
  KEY - SP (Sentinel Pro)
        SX (Sentinel Superpro)           SP   SX
                                         --   --
    SUCCESS                       0       X    X
    INVALID_FUNCTION_CODE         1            X
    INVALID_PACKET                2       X    X
    UNIT_NOT_FOUND                3       X    X
    ACCESS_DENIED                 4            X
    INVALID_MEMORY_ADDRESS        5            X
    INVALID_ACCESS_CODE           6            X
    PORT_IS_BUSY                  7       X    X
    WRITE_NOT_READY               8            X
    NO_PORT_INSTALLED             9       X    X
    ALREADY_ZERO                  10           X
    DRIVER_NOT_INSTALLED          12      X    X
    COMMUNICATIONS_ERROR          13      X    X
    VERSION_NOT_SUPPORTED         18      X    X
    OS_ENV_NOT_SUPPORTED          19      X    X
    QUERY_TOO_LONG                20      X    X
    DRIVER_IS_BUSY                30           X
    PORT_ALLOCATION_FAILURE       31      X    X
    PORT_RELEASE_FAILURE          32      X    X
    AQUIRE_PORT_TIMEOUT           39      X    X
    SIGNAL_NOT_SUPPORTED          42      X    X
    INIT_NOT_CALLED               57      X    X
    DRIVER_TYPE_NOT_SUPPORTED     58      X    X
    FAIL_ON_DRIVER_COMM           59      X    X

       The documented errors are all recoverable errors.  If you receive
    any unknown error numbers, please report the error number( extended
    error number if possible) to Rainbow Technologies Technical Support.

----------------------
ERROR CODE DESCRIPTION
----------------------

  0 - SUCCESS

  1 - INVALID FUNCTION CODE was specified - See your language's include
         file for valid API function codes.  Generally, this error should not
         occur if you are using a Rainbow-provided interface to communicate
         with the driver.

  2 - INVALID PACKET - A checksum error was detected in the command packet,
         indicating an internal inconsistency.  The packet record structure
         may have been tampered with.  Generally, this error should not occur
         if you are using a Rainbow-provided interface to communicate the
         driver.

  3 - UNIT NOT FOUND - The specific unit could not be found.  Make sure you
         are sending the correct information to find the unit.  This error
         is returned by other functions if the unit has disappeared( that is,
         unplugged).

  4 - ACCESS DENIED - You attempted to perform an illegal action on a word.
         For example, you may have tried to read an algorithm/hidden word,
         write to a locked word, or decrement a word that is not a data nor
         counter word.

  5 - INVALID MEMORY ADDRESS - You specified an invalid SentinelSuperPro
         memory address.  Valid addresses are 0-63 decimal(0-3F hex).
         Cells 0-7 are invalid for many operations.  Algorithm descriptors
         must be referenced by the first (even) address.

  6 - INVALID ACCESS CODE - You specified an invalid access code.  The
         access code must be 0(read/write date), 1(read only data), 2
         (counter), or 3(algorithm/hidden).

  7 - PORT IS BUSY - The requested operation could not be completed because
         the port is busy.  This can happen if there is considerable printer
         activity, or if a unit on the port is performing a write operation
         and is blocking the port.  Try the function again.

  8 - WRITE NOT READY - The write or decrement could not be performed due to
         a momentary lack of sufficient power.  Try the operation again.

  9 - NO PORT FOUND - No parallel ports could be found on the workstation.

 10 - ALREADY ZERO - You tried to decrement a counter or data word that
         already contains the value 0.  If you are using the counter to
         control demo prgram executions, this condition may occur after the
         corresponding algorithm descriptor has been reactivated with its
         activation password.

 12 - DRIVER NOT INSTALLED - The system device driver was not installed or
         or detected.  Communication was the unit was not possible.  Please
         verify that the device driver is properly loaded.

 13 - COMMUNICATIONS ERROR - The system device driver is having problems
         communicating with the unit.  Please verify that the device driver
         is properly installed.

 18 - VERSION NOT SUPPORTED - The current system device driver is outdated.
         Please update the system device driver.

 19 - OS Environment not supported - The Operating System or Environment is
         currently not supported by the client library.  Please contact Tech
         Support.


 20 - QUERY TOO LONG - The maximum query string supported in 56 characters.
         Send a shorter string.

 30 - DRIVER IS BUSY - The system device driver is busy. Try the operation
         again.

 31 - PORT ALLOCATION FAILURE - Failed to allocate a parallel port through
         the Operating System's parallel port contention handler.

 32 - PORT RELEASE FAILURE - Failed to release a previously allocated
         parallel port through the Operating System's parallel port
         contention handler.

 39 - ACQUIRE PORT TIMEOUT - Failed to acquire access to a parallel port
         within the defined time-out.

 42 - SIGNAL NOT SUPPORTED - The particular machine does not support a signal
         line.  For example, an attempt was made to use the ACK line on a
         NEC 9800 computer.  The NEC 9800 does not have an ACK line.
         Therefore, this error is reported.

 57 - INITIALIZE NOT CALLED - Failed to call the client library's initialize
         API. This API must be called prior to the API that generated this
         error.

 58 - DRIVER TYPE NOT SUPPORTED - The type of driver access, either direct
         I/O or system driver, is not supported for the defined Operating
         System and client library.

 59 - FAILURE ON DRIVER COMMUNICATION - The client library failed on
         communicating with a Rainbow system driver.
