National Instruments GPIB Software for Windows 95.
Version 1.30.
Copyright 1998 National Instruments Corporation.
All Rights Reserved.


Thank you for purchasing the GPIB Software for Windows 95 to use with
the GPIB-ENET interface.  For additional information on National 
Instruments and our products, please refer to our Web site:

      http://www.natinst.com/gpib/


GPIB Software for Windows 95, Version 1.30, has the following 
characteristics when using the GPIB-ENET interface:


   * iblockx/ibunlockx support (replaces iblock/ibunlock).
   * ibnotify support.


OBSOLETE GPIB-ENET FUNCTIONALITY
--------------------------------

Beginning with firmware revision A.5, the GPIB-ENET no longer supports 
the IbcBlockIfLocked ibconfig option.  Similarly, the IbaBlockIfLock 
ibask option is no longer supported.  Specifying these obsolete 
options with these calls causes an ECAP error to be returned.

The iblock and ibunlock calls are obsolete and have been replaced with
enhanced versions, iblockx and ibunlockx, which should be used instead.
Existing applications that use iblock and ibunlock functions will 
continue to run.  For more information on iblockx and ibunlockx, refer
to the GpibEnet.txt readme file.


CHOOSING A WINSOCK INTERFACE
----------------------------

Using the GPIB software with the GPIB-ENET requires a Windows
Socket (WinSock) Interface, Version 1.1 or higher. This particular
WinSock Interface is provided by Microsoft Windows 95. Additionally,
you can purchase WinSock Interfaces from third party vendors. However,
the GPIB Software for Windows 95, Version 1.30 release, has only been 
tested with the Microsoft supplied WinSock Interface.


LATEST GPIB-ENET FIRMWARE AVAILABILITY
--------------------------------------

The latest firmware image file can be obtained from either our Web or
our FTP sites.  The address to the GPIB section of the National
Instrument's home page is:

      http://www.natinst.com/gpib/

Please refer to the Download section to obtain the firmware image.
Alternatively, you can access our FTP site at:

      ftp://ftp.natinst.com/


ACCESSING A GPIB-ENET FROM MULTIPLE APPLICATIONS
------------------------------------------------

To safely access the same GPIB-ENET from multiple applications on one 
or more computers at the same time, you should use the iblockx and 
ibunlockx functions. The iblockx function prevents one application 
from interrupting a call made to the GPIB-ENET from another 
application. Without it, one application could cause an I/O operation 
initiated by another application to abort or cause other unexpected 
behavior.

The iblockx and ibunlockx functions are described below:
**********************************************************************
IBLOCKX

PURPOSE
        Acquire a board or device GPIB lock for the current process.

FORMAT
        int iblockx (int ud, int LockWaitTime, char * LockShareName)

INPUT
        ud              A board or device unit descriptor
        LockWaitTime    Time period to wait to acquire the requested 
                        lock
        LockShareName   For exclusive GPIB locks, use NULL; for shared
                        GPIB locks, the null terminated string 
                        specifying the lock name

OUTPUT
        ibsta   Current ibsta value

DESCRIPTION

iblockx is used to acquire either a board lock or a device lock for 
the current process. If the requested lock is not immediately 
available, LockWaitTime determines how long to wait for the requested 
lock to become available. LockWaitTime can have the following values:

VALUE           MEANING
-----           -------
TIMMEDIATE      No timeout period: iblockx returns immediately 
                regardless of the availability of the requested lock.
TINFINITE       Infinite timeout period: iblockx does not complete 
                until the requested lock has been acquired.
T10us - T1000s  Specific timeout period: iblockx returns immediately 
                if the requested lock is available, otherwise it waits
                for the lock to become available until the specified 
                timeout period has elapsed. Note, the timeout value is
                a minimum timeout period, the actual period may be 
                longer.

GPIB locks can only be exclusive or shared, not both. Exclusive GPIB 
locks can only be used by a single process. Shared GPIB locks can be 
used by multiple processes. The LockShareName parameter determines 
whether the requested lock is exclusive or shared. If LockShareName is
NULL, an exclusive GPIB lock is requested. If LockShareName is a non-
empty string (it must be less than MAX_LOCKSHARENAME_LENGTH characters
in length), a shared GPIB lock is requested. Multiple processes can 
request the shared GPIB lock by passing the same LockShareName to the 
iblockx. The comparison of LockShareName values is case-sensitive. 
Here are two examples:

1. Acquire an exclusive GPIB lock, don't wait if the lock is not 
   available immediately:
        iblockx (ud, TIMMEDIATE, NULL);

2. Acquire a shared GPIB lock, don't wait if the lock is not available
   immediately:
        iblockx (ud, TIMMEDIATE, "My shared GPIB lock");

In the second example, if the shared GPIB lock already exists, the 
LockWaitTime parameter is ignored since the request can always be 
satisfied immediately.  If the call to iblockx is successful, that is,
if the ERR bit is not set in ibsta, it returns with ibcntl set to the 
number of times iblockx has been successful for the ud for a given 
process (this is the number of outstanding GPIB locks in use by this 
ud for a given process).  An exclusive GPIB lock is associated with a 
process, GPIB interface and possibly a GPIB address. A shared GPIB 
lock is associated with one or more processes, a GPIB interface and 
possibly a GPIB address. An acquired lock remains in effect until the 
lock is released with ibunlockx. Each successful call to acquire a 
lock must have a corresponding call to release the lock; if a process 
makes multiple calls to iblockx, it should make the same number of 
calls to ibunlockx. Like iblockx, ibunlockx returns the number of 
outstanding locks for a given ud in ibcntl. The only way to release a 
GPIB lock is to call ibunlockx on the ud. 

There are two classes of GPIB locks: board locks and device locks. If 
the ud is a board descriptor, the iblockx call is for a board lock. A 
board lock provides exclusive access to a GPIB interface. If the ud is
a device descriptor, the iblockx call is for a device lock. A device 
lock provides exclusive access to the GPIB device at the primary 
address and secondary address on the access bus for the given ud. 
Device locks are useful for ensuring a particular GPIB device is 
dedicated to your application or if multiple applications need to 
coordinate the sharing of a single GPIB device.

There are two rules that determine whether a request to acquire a GPIB
lock succeeds. They are:

a. If a process has a lock for device D with access board B: no 
   process can acquire a lock on board B, but any process can acquire 
   locks on devices other than D with access board B.

b. If a process has a lock for board B: no process can acquire board 
   or device locks associated with board B.

If a process has acquired a board lock, all GPIB calls by that process
for that board occur normally except for ibonl which returns ELCK 
until the board is unlocked with an ibunlockx call. All GPIB calls by 
other processes for that board are disallowed and fail with the ERR 
bit set in ibsta and iberr set to ELCK. The acquisition of a board 
lock gives an application complete control over a GPIB interface. It 
also prevents any other GPIB applications in the system from being 
able to run properly.  If a process has acquired a device lock, all 
device-level GPIB calls by that process for that device and board 
occur normally with four exceptions: ibpad, ibsad, ibbna, and ibonl. 
These four calls are disallowed because they can cause a change in the
primary address, secondary address or connect board of the locked 
device. If the device is locked, these four calls have no effect and 
return with the ERR bit set in ibsta and iberr set to ELCK. You must 
release the device lock with ibunlockx before using any of these 
calls.  When a process has a device lock, all device-level GPIB calls 
by other processes that require the locked pad/sad/board resources are
disallowed and fail with the ERR bit set in ibsta and iberr set to 
ELCK.  Furthermore, all board-level GPIB calls for the locked connect 
board resource are disallowed and fail similarly with ELCK.

Note: if your process uses multiple device handles for the same 
pad/sad/board triplet and it wants to use GPIB locks, it must call 
iblockx for each of the device handles it wants to share the lock 
between.  Alternatively, the process can acquire and lock a single 
device handle instead of using multiple handles and use that single 
handle as a process global.

Possible Errors
        EDVR    Either ud is invalid or the driver is not installed. 
                ibcntl contains a system dependent error code.
        ENEB    The interface board is not installed or is not 
                properly configured.
        EARG    LockWaitTime is invalid or, for shared GPIB locks, 
                LockShareName exceeds MAX_LOCKSHARENAME_LENGTH in 
                length.
        EOIP    Asynchronous I/O is in progress.
        ECAP    GPIB driver does not support iblockx and ibunlockx.
        ELCK    Unable to acquire the requested lock because the 
                requested lock is already owned.

Status Bits Affected (Normal Operation)
        TIMO    Unasserted.
        ERR     Unasserted.

Status Bits Affected (Error)
        TIMO    Asserted, if the request times out.
        ERR     Asserted.

**********************************************************************
IBUNLOCKX

PURPOSE
        Release a board lock or device lock for the current process.

FORMAT
        int ibunlockx (int ud)

INPUT
        ud      A board or device unit descriptor

OUTPUT
        Function Return Current ibsta value

DESCRIPTION

ibunlockx is used to release either a board lock or a device lock that
was previously acquired with the iblockx function by the current 
process. Note that a GPIB lock can only be released by the process 
that acquired it. If the call is successful, ibcntl contains the 
number of locks remaining in effect for the ud for a given process.

For more information on GPIB locks, please refer to the iblockx 
function.

Possible Errors
        EDVR    Either ud is invalid or the driver is not installed. 
                ibcntl contains a system dependent error code.
        ENEB    The interface board is not installed or is not 
                properly configured.
        ECAP    Process has not acquired a GPIB lock for the input ud.

Status Bits Affected (Normal Operation)
        TIMO    Unasserted.
        ERR     Unasserted.

Status Bits Affected (Error)
        ERR     Asserted.

**********************************************************************


ADDITIONAL IBERR REPORTING FOR GPIB-ENET
----------------------------------------

Almost all the errors that could occur with iberr are listed in either
the Error Codes section in the on-line help or in the "Error Codes
and Solutions" appendix in the "NI-488.2M Function Reference Manual 
for Win32". However, there are two new errors which are not listed in
the references already mentioned, but are listed here:

     Error        iberr      Meaning
     Mnemonic     Value
----------------------------------------------------------------------
     ECFG         24         This error is returned when a board-level
                             configuration is sent to a GPIB-ENET 
                             which is already on-line and configured
                             differently.  This usually occurs when
                             multiple applications try to access the
                             same GPIB-ENET.  When a GPIB-ENET is 
                             first put on-line by an application, it 
                             is configured with the default board 
                             settings as configured by the GPIB 
                             Configuration Utility.  When a second 
                             application tries to put the same 
                             GPIB-ENET on-line and send it new default
                             board settings, which are different than 
                             what the first application sent it, ECFG 
                             is returned and the board settings on the
                             GPIB-ENET are left unchanged.

                             ECFG is only a warning, and in the case 
                             of ibfind and ibdev calls, the descriptor
                             returned is valid, only the GPIB-ENET is
                             not configured as specified with the GPIB
                             Configuration Utility.

     ELCK         21         This error is returned when the requested
                             command cannot be performed because of an
                             existing lock by another application
                             accessing the same GPIB-ENET interface.
                             See the description of iblockx and 
                             ibunlockx above.


