(C) Copyright 1986-1998  Rainbow Technologies Inc. All Rights Reserved
API.TXT for the C Language implementation of SentinelSuperPro for OS/2,
Win32, Netware NLMs and QNX environments.

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

  For Win32, OS/2, Netware and QNX, the driver encryption (SPROX.EXE) tools
  are not supported because of the shared driver. Also the programming tool
  (SPROEDIT.EXE) is available for WINDOWS and is provided on the DOS
  interface diskettes.

------------
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 two SuperPro passwords: the write password and the overwrite
  password. The overwrite password is composed of two words called 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 and are stored in an UNSIGNED 16-BIT INTEGER
  variable.

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

  The values for the access codes are defined as follows;

    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.

------------------------
RB_SPRO_APIPACKET RECORD
------------------------

  All functions require a pointer to an RB_SPRO_APIPACKET record.
  The record is initialized by the function RNBOsproFormatPacket.
  The record must reside on a DWORD boundary.

  The SuperPro driver uses the data in the RB_SPRO_APIPACKET record to
  communicate with the SuperPro key.  The programmer should never
  modify the data in the RB_SPRO_APIPACKET record.

  It is the programmer's responsibility to allocate memory for the
  RB_SPRO_APIPACKET record, and pass an RBP_SPRO_APIPACKET pointer to
  all functions.

Note: This interface is different than documented in the manual.
      The use of the Unit Handle is replaced with RB_SPRO_APIPACKET. Also
      all functions now require RB_SPRO_APIPACKET. This was done to help
      support multi-threaded applications.

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

  On success, all functions return SP_SUCCESS.  Else, they return an error
  code 2 as defined in the ERROR CODE SUMMARY section at the end of this
  document.

------------------
INTERFACE ROUTINES
------------------

  RNBOsproFormatPacket
  RNBOsproInitialize
  RNBOsproFindFirstUnit
  RNBOsproFindNextUnit
  RNBOsproRead
  RNBOsproExtendedRead
  RNBOsproWrite
  RNBOsproOverwrite
  RNBOsproDecrement
  RNBOsproActivate
  RNBOsproQuery
  RNBOsproGetFullStatus
  RNBOsproGetVersion
  RNBPsproCfgLibParams

--------------------
RNBOsproFormatPacket
--------------------

Description:

  This function initializes and validates the size of the RB_SPRO_APIPACKET
  that is passed.

Format:

SP_STATUS SP_API RNBOsproFormatPacket( SP_OUT RBP_SPRO_APIPACKET thePacket,
                                       SP_IN  RB_WORD            thePacketSize )


where:

  thePacket - is a pointer to a dword aligned RB_SPRO_APIPACKET record.
  thePacketSize - is the size of the RB_SPRO_APIPACKET record.

Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

NOTE:

  This function must be called before any other RNBOspro function.

------------------
RNBOsproInitialize
------------------

Description:

  This function initializes the SuperPro device.

Format:

  SP_STATUS SP_API RNBOsproInitialize( RBP_SPRO_APIPACKET packet )

where:

  packet - is a pointer to a dword aligned RB_SPRO_APIPACKET record.

Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

---------------------
RNBOsproFindFirstUnit
---------------------

Description:

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

Format:

  SP_STATUS SP_API RNBOsproFindFirstUnit( RBP_SPRO_APIPACKET packet,
                                          RB_WORD            developerID )

where:

  packet      - is a pointer to the RB_SPRO_APIPACKET record.
  developerID - is the developer ID for the SuperPro device to find.

Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

--------------------
RNBOsproFindNextUnit
--------------------

Description:

  This function finds the next SuperPro key based on the developer ID
  maintained in the RB_SPRO_APIPACKET record. This function should not
  be called unless RNBOsproFindFirstUnit has returned a successful value.
  If this function returns success, the RB_SPRO_APIPACKET record will
  contain the data for the next SuperPro key. If this function returns an
  error value, the RB_SPRO_APIPACKET record will be marked invalid.
  To re-initialize the RB_SPRO_APIPACKET record, use RNBOsproFindFirstUnit
  and, optionally, RNBOsproFindNextUnit depending upon the number of
  SuperPro keys found and the one your program accesses.

Format:

  SP_STATUS SP_API RNBOsproFindNextUnit( RBP_SPRO_APIPACKET packet )

where:

  packet - is a pointer to the RB_SPRO_APIPACKET record.

Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

------------
RNBOsproRead
------------

Description:

  This function reads a word at the specified address of the SuperPro
  key identified by the RB_SPRO_APIPACKET record.  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 (algorithm) word. For security reasons,
  algorithm words cannot be read.

Format:

  SP_STATUS SP_API RNBOsproRead( RBP_SPRO_APIPACKET packet,
                                 RB_WORD            address,
                                 RBP_WORD           data )


where:

  packet  - is a pointer to the RB_SPRO_APIPACKET record.
  address - is the SuperPro memory address of the word to read.
  data    - will contain the data read from the SuperPro key.
            This variable must reside on a WORD boundary.

Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

--------------------
RNBOsproExtendedRead
--------------------

Description:

  This function reads the word and accesses code at the specified address
  of the SuperPro key identified by the RB_SPRO_APIPACKET record. 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 (algorithm) word. For security reasons, algorithm words
  cannot be read.

Format:

  SP_STATUS SP_API RNBOsproExtendedRead( RBP_SPRO_APIPACKET packet,
                                         RB_WORD            address,
                                         RBP_WORD           data,
                                         RBP_BYTE           accessCode )

where:

  packet     - is a pointer to the RB_SPRO_APIPACKET record.
  address    - is the SuperPro memory address of the word to read.
  data       - will contain the data read from the SuperPro key.
               This variable must reside on a WORD boundary.
  accessCode - is a pointer to a variable that contains the access code
               associated with the word read.

Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

-------------
RNBOsproWrite
-------------

Description:

  This function is used to write a word and its associated access code to
  the SuperPro key identified by the RB_SPRO_APIPACKET record. Writing
  to the SuperPro key requires the write password. The word data is placed
  in the data variable and its associated access code is placed in the access
  code variable. On success, the data and it associated access code
  are 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 cell.

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

Format:

  SP_STATUS SP_API RNBOsproWrite( RBP_SPRO_APIPACKET packet,
                                  RB_WORD            writePassword,
                                  RB_WORD            address,
                                  RB_WORD            data,
                                  RB_BYTE            accessCode )

where:

  packet        - is a pointer to the RB_SPRO_APIPACKET record.
  writePassword - is the write password for the SuperPro key.
  address       - is the address of the word to write.
  data          - will contain the SuperPro word to write.
  accessCode    - will contain the access code associated with the word
                  to write.

Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

-----------------
RNBOsproOverwrite
-----------------

Description:

  This function writes a word and its associated access code to
  the SuperPro key identified by the RB_SPRO_APIPACKET record.  Overwriting
  to the SuperPro key requires the write and overwrite passwords.
  The word data is placed in the data variable and its associated access
  code is placed in the access code variable.  On success, the data and
  its associated access code are written to the specified word on the
  SuperPro key.  If the error code is SP_ACCESS_DENIED, the write password
  and/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-7.

Format:

   SP_STATUS SP_API RNBOsproOverwrite( RBP_SPRO_APIPACKET packet,
                                       RB_WORD            writePassword,
                                       RB_WORD            overwritePassword1,
                                       RB_WORD            overwritePassword2,
                                       RB_WORD            address,
                                       RB_WORD            data,
                                       RB_BYTE            accessCode )

where:

  packet             - is a pointer to the RB_SPRO_APIPACKET record.
  writePassword      - is the write password for the SuperPro key.
  overwritePassword1 - is word 1 of the overwrite password.
  overwritePassword2 - is word 2 of the overwrite password.
  address            - is the address of the word to write.
  data               - will contain the SuperPro word to write.
  accessCode         - will contain the access code associated with the
                       word to write.

Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

-----------------
RNBOsproDecrement
-----------------

Description:

  This function decrements the counter at the specified address
  of the SuperPro key identified by the RB_SPRO_APIPACKET record. If the
  function is successful, the counter is decremented by 1. Errors are
  returned 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 exist only 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 RNBOsproActivate.

Format:

  SP_STATUS SP_API RNBOsproDecrement( RBP_SPRO_APIPACKET packet,
                                      RB_WORD            writePassword,
                                      RB_WORD            address )

where:

  packet        - is a pointer to the RB_SPRO_APIPACKET record.
  writePassword - is the write password for the SuperPro key.
  address       - is the address of the counter to decrement.


Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

----------------
RNBOsproActivate
----------------

Description:

  This function is used to activate the inactive algorithm at the specified
  address of the SuperPro key identified by the RB_SPRO_APIPACKET record.
  If the function is successful, the algorithm is made active. Errors are
  returned 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 RNBOsproDecrement.

Format:

  SP_STATUS SP_API RNBOsproActivate( RBP_SPRO_APIPACKET packet,
                                     RB_WORD            writePassword,
                                     RB_WORD            activatePassword1,
                                     RB_WORD            activatePassword2,
                                     RB_WORD            address )


where:

  packet            - is a pointer to the RB_SPRO_APIPACKET record.
  writePassword     - is the write password for the SuperPro key.
  activatePassword1 - is the first word of the activate password.
  activatePassword2 - is the second word of the activate password.
  address           - is the address of the first word of the inactive
                      algorithm to activate.


Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

-------------
RNBOsproQuery
-------------

Description:

  This function is used to query an active algorithm at the specified address
  of the SuperPro key identified by the RBP_SPRO_APIPACKET record. 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 is placed
  in the buffer pointed to by the response pointer. The last 4 bytes
  of the response will also be placed in the Response32 variable.

  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 programmer's
  responsibility to allocate memory for the buffers.

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

Format:

  SP_STATUS SP_API RNBOsproQuery( RBP_SPRO_APIPACKET packet,
                                  RB_WORD            address,
                                  RBP_VOID           queryData,
                                  RBP_VOID           response,
                                  RBP_DWORD          response32,
                                  RB_WORD            length )

where:

  packet      - is a pointer to the RB_SPRO_APIPACKET record.
  address     - is the address of the word to query.
  queryData   - is the pointer to the first byte of the query bytes.
  response    - is the pointer to the first byte of the response bytes.
  response32  - is the pointer that will contain a copy of the last 4 bytes
                of the query response. This variable must point to a
                DWORD-aligned address.
  length      - is the number of query bytes to send to the active algorithm
                and also the length of the response buffer.

  Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

------------------
RNBOsproGetVersion
------------------

Description:

  This function returns the driver's version number and type.

Format:

  SP_STATUS SP_API RNBOsproGetVersion( RBP_SPRO_APIPACKET packet,
                                       RBP_BYTE           majVer,
                                       RBP_BYTE           minVer,
                                       RBP_BYTE           rev,
                                       RBP_BYTE           osDrvrType )

where:

  packet      - is a pointer to the RB_SPRO_APIPACKET record.
  majVer      - is a pointer to the location to store the major version.
  minVer      - is a pointer to to location to store the minor version.
  rev         - is a pointer to to location to store the revision.
  osDrvrType  - is a pointer to location to store the operating system driver
                type. Currently defined types are:

     RB_DOSRM_LOCAL_DRVR  (1) - DOS local driver.
     RB_WIN3x_LOCAL_DRVR  (2) - Windows 3.x local driver.
     RB_WIN32s_LOCAL_DRVR (3) - Windows Win32s local driver.
     RB_WIN3x_SYS_DRVR    (4) - Windows 3.x system driver.
     RB_WINNT_SYS_DRVR    (5) - Windows NT system driver.
     RB_OS2_SYS_DRVR      (6) - OS/2 system driver.
     RB_WIN95_SYS_DRVR    (7) - Windows 95 system driver.
     RB_NW_LOCAL_DRVR     (8) - Netware local driver.
     RB_QNX_LOCAL_DRVR    (9) - QNX local driver.

Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

---------------------
RNBOsproGetFullStatus
---------------------

Description:

  This function is used to return extended status information.
  It is provided for support purposes only.

Format:

  RB_WORD SP_API RNBOsproGetFullStatus( RBP_SPRO_APIPACKET packet )

where:

  packet      - is a pointer to the RB_SPRO_APIPACKET record.

Return value:

  Returns an RB_WORD value that can be interpreted by Rainbow's technical
  support department.

--------------------
RNBOsproCfgLibParams
--------------------

Description:

    This function is used to set or get library configuration. The setting
    of configuration parameters affect only the local (linked) driver.
    A system driver is configured through the documented method for
    the linked driver. You must call RNBOsproInitialize for the parameters
    to take effect. Calling RNBOsproFormatPacket voids all previous
    configurations. This function must be called after RNBOsproFormatPacket
    and before RNBOsproInitialize.


Format:

  SP_STATUS SP_API RNBOsproCfgLibParams( RBP_SPRO_APIPACKET  packet,
                                         RBP_SPRO_LIB_PARAMS libParams )

where:

  packet      - is a pointer to the RB_SPRO_APIPACKET record.
  libParams   - is a pointer to an RB_SPRO_LIB_PARAMS record.

Return values:

  On success, returns SP_SUCCESS.  Else, returns an error code as
  defined in the ERROR CODE SUMMARY section at the end of this document.

-----------------
PACKET DEFINITION
-----------------

typedef RB_DWORD[SPRO_APIPACKET_SIZE/sizeof(RB_DWORD)] RB_SPRO_APIPACKET;
typedef RBP_VOID                     RBP_SPRO_APIPACKET;


------------------------------
LIBRARY PARAMETERS DEFINITIONS
------------------------------

typedef struct _RB_SP_OS_PARAMS {
SP_IO  RB_WORD osType;                    /* type of operating system   */
SP_OUT RB_WORD osVer;                     /* version of operating system*/
} RB_SP_OS_PARAMS;
typedef RB_SP_OS_PARAMS SP_PTR RBP_SP_OS_PARAMS;

typedef struct _RB_SP_PORT_PARAMS {
SP_IO  RB_WORD  logPortNum;               /* logical port number        */
SP_IO  RB_WORD  sysPortNum;               /* system  port number        */
SP_IO  RB_WORD  portType;                 /* port type                  */
SP_IO  RB_WORD  phyAddr;                  /* physical address           */
SP_OUT RB_WORD  mappedAddr;               /* map address                */
SP_IO  RB_WORD  deviceRetryCnt;           /* device retry count         */
SP_IO  RB_WORD  contentionRetryCnt;       /* port contention retry count*/
SP_IO  RB_WORD  padding1;
SP_IO  RB_DWORD contentionMethod;         /* port contention method     */
SP_IO  RB_DWORD contentionRetryInterval;  /* port contention retry int  */
SP_IO  RB_DWORD flags1;                   /* port flags                 */
} RB_SP_PORT_PARAMS;
typedef RB_SP_PORT_PARAMS SP_PTR RBP_SP_PORT_PARAMS;

typedef union  _RB_SP_CFG_PARAMS {
SP_IO RB_WORD        machineType;      /* machine type: IBM, NEC, or FMR*/
SP_IO RB_WORD        delay;            /* number of loops for 2us delay */
SP_IO RB_WORD        maskInterrupts;   /* interrupts to mask            */
SP_IO RB_WORD        routerFlags;      /* request routing flags         */
SP_IO RB_SP_OS_PARAMS   osParams;      /* OS parameters                 */
SP_IO RB_SP_PORT_PARAMS portParams;    /* port parameters               */
} RB_SP_CFG_PARAMS;
typedef RB_SP_CFG_PARAMS SP_PTR RBP_SP_CFG_PARAMS;

typedef struct _RB_SPRO_LIB_PARAMS {
SP_IN RB_WORD   cmd;                   /* command - set/get parameters  */
SP_IN RB_WORD   func;                  /* function to set/get           */
SP_IO RB_SP_CFG_PARAMS params;
} RB_SPRO_LIB_PARAMS;
typedef RB_SPRO_LIB_PARAMS SP_PTR RBP_SPRO_LIB_PARAMS;


where:
        cmd is one of the following commands:

        RB_SET_LIB_PARAMS_CMD - set library parameters (not available for OS/2).
        RB_GET_LIB_PARAMS_CMD - get library parameters

        func is one of the following functions:

        RB_MACHINE_TYPE_FUNC  - set/get machine type
        RB_DELAY_FUNC         - set/get delay value
        RB_MASK_INTS_FUNC     - set/get mask interrupts
        RB_ROUTER_FLAGS_FUNC  - set/get router flags
        RB_OS_PARAMS_FUNC     - set/get O/S parameters
        RB_PORT_PARAMS_FUNC   - set/get port parameters

        params is one of the following parameters based on the
        function code (func):

        machineType - is the parameter for the RB_MACHINE_TYPE_FUNC function.
                      This parameter can be configured or retrieved from
                      the library. Valid values are:

                      RB_AUTODETECT_MACHINE - autodetect machine type
                      RB_IBM_MACHINE        - IBM type hardware.
                      RB_NEC_MACHINE        - NEC PC-9800 hardware.
                      RB_FMR_MACHINE        - Fujitsu FMR hardware.

                      The default value is RB_AUTODETECT_MACHINE.

       delay        - is the parameter for the RB_DELAY_FUNC function.
                      This parameter can be configured or retrieved from the
                      library. Valid values are:

                      RB_USE_AUTOTIMING     - use autotiming.
                      1 - 32767             - actual number of machine
                                              loops to simulate a delay of
                                              2 microseconds.

                      The default value is RB_USE_AUTOTIMING.

     maskInterrupts - is the parameter for the RB_MASK_INTS_FUNC function.
                      This parameter can be configured or retrieved from the
                      library. Valid values are a bit mask defined as follows:

                      RB_IRQ_MASK_LPT1 - masks the H/W interrupt for LPT1.
                      RB_IRQ_MASK_LPT2 - masks the H/W interrupt for LPT2.
                      RB_IRQ_MASK_TIMER - masks the H/W interrupt for the
                                         system timer.
                      RB_IRQ_MASK_DEF - maks the H/W interrupts for LPT1 and
                                         the system timer.

                      To mask more than one interrupt, simply perform a
                      "bit wise" OR on the masks.

                      The default value is RB_IRQ_MASK_DEF.

        routerFlags - is the parameter for the RB_ROUTER_FLAGS_FUNC function.
                      This parameter contains routing flags. Valid
                      flags are:

                      RB_ROUTER_USE_LOCAL_DRVR - use linked in driver
                                                 where available.
                      RB_ROUTER_USE_SYS_DRVR   - use system driver
                                                 where available.
                      RB_ROUTER_AUTODETECT_DRVR- use system or local driver.

                      This parameter directs the library on which
                      driver to use: local, system, or whichever is
                      available. NOTE: We do not support a local driver
                      for Windows NT or OS/2!

                      The default value is the RB_ROUTER_AUTODETECT_DRVR
                      function.

           osParams - is the parameter block for RB_OS_PARAMS_FUNC.
                      This parameter block contains the following values:

                      osType - is the type of operating system the library
                               is running under. Valid values are:

             RB_AUTODETECT_OS_TYPE - defines that the library will try to
                                     autodetect the native operating system.
                      RB_OS_WIN3x  - Windows 3.x operating environment.
                      RB_OS_WINNT  - Windows NT operating system.
                      RB_OS_OS2    - OS/2 operating system.
                      RB_OS_WIN95  - Windows 95 operating system.
                      RB_OS_WIN32s - Windows Win32s environment.
                      RB_OS_NW     - Netware operating system.
                   
                      The default value is RB_AUTODETECT_OS_TYPE.

                      osVer - is the operating system version the library is
                              currently running under. This parameter is
                              read-only.

         portParams - is the parameter block for the RB_PORT_PARAMS_FUNC
                      function. These records must be defined in
                      consecutive order (0,1,2,...). The parameter
                      block contains the following values:

               logPortNum - is the logical port number to get or
                            set values to. Valid values are
                            RB_FIRST_LOG_PORT through RB_LAST_LOG_PORT.

               sysPortNum - is the system port number assigned to
                            the base address.

               portType   - is the type of parallel port.
                            Valid values are:

                  RB_AUTODETECT_PORT_TYPE - autodetects the port type
                                            (IBM machines only).
                         RB_PS2_PORT_TYPE - defines an IBM AT or
                                            PS/2 bi-directional port.
                     RB_PS2_DMA_PORT_TYPE - defines an IBM PS/2 DMA port.
                         RB_NEC_PORT_TYPE - defines a NEC PC-9800
                                            series port.
                         RB_FMR_PORT_TYPE - defines a Fujitsu FMR
                                            series port.

                phyAddr   - defines the physical port address for
                            the defined logical port number.

             mappedAddr   - defines the I/O mapped address for
                            legacy applications. This parameter
                            is read-only.

           deviceRetryCnt - defines the number of retries to perform
                            if an I/O communciations error is
                            detected on a device. Valid values
                            are 0 (disable) through -1 (indefinite).
                            The default value is RB_DEV_RETRY_CNT_DEF (100).

       contentionRetryCnt - defines the number of retries to perform
                            when contending for a parallel port
                            between other tasks. Valid values are 0
                            (disable) through -1 (indefinite). The
                            default value is RB_PORT_CONT_RETRY_CNT_DEF (100).

         contentionMethod - is a bit mask defining the contention
                            methods to use. Valid values are:

            RB_CONT_METH_SYS_ALLOC - use system port allocation if
                                     available.
            RB_CONT_METH_NT_RIRQL  - use Windows NT's raise IRQ level
                                     (NT only). This parameter is
                                     read-only for local access.
            RB_CONT_METH_SYS_INT   - disable system interrupts during a
                                     query. (Win32s only.)
            RB_CONT_METH_MASK_INT  - mask interrupts (as defined by the
                                     maskInterrupts parameter) during a
                                     query.
            RB_CONT_METH_WIN_CS    - use Windows 3.x/95 critical section
                                     during a query. This parameter is
                                     read-only for local access.
            RB_CONT_METH_POLL_HW   - poll the port for access.
            RB_CONT_METH_RBW       - enable collision detection during a
                                     query.
        RB_CONT_METH_DRVR_DEFINED  - use the driver's default method for
                                     port contention. This bit value
                                     overrides all others.
        RB_PORT_CONT_RETRY_INT_DEF - 300 milleseconds.

               To mask more than one contention method, simply perform a
               "bit wise" OR on the masks.

        contentionRetryInterval - is the amount of time in milliseconds
                                  to wait between retry attempts if
                                  the port is busy. Valid values
                                  are 0 (disable) through -1
                                  (indefinite). The default value is
                                  RB_PORT_CONT_RETRY_INT_DEF.

            flags1 - is a bit mask defining port-specific features.
                     Valid values are:

                 RB_VALIDATE_PORT - if defined, the driver will validate
                                    all ports to their existence.
             RB_USER_DEFINED_PORT - indicates that this port is user-
                                    defined. This parameter is read-
                                    only.
          RB_CONT_HNDLR_INSTALLED - indicates that this port has system
                                    contention handling support.
                                    This parameter is read-only.

------------------
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.
