Virtual ASPI driver for OS/2 2.x
(C) 1994 ARS Computer und Consulting GmbH


ARS Computer und Consulting GmbH
Frankfurter Ring 193a                   Tel. 0 89 / 3 23 66 30-0
D-80807 Muenchen                        Fax  0 89 / 3 24 45 24
					CompuServe: 100265,2651


$Id: english.txt,v 1.1 1994/04/15 17:17:13 rommel Exp $
$Revision: 1.1 $


Contents:

1. Overview
2. Installation
3. DOS Settings
4. Programmer's API
5. Test Programs
6. Compatibility
7. Known Problems
8. Test/Problem Reports


1. Overview

OS/2 2.x contains a driver architecture for SCSI host adaptors and
peripheral devices. It consists of a host adaptor specific driver
(ADD) and, based on this, device managers (DMD) which are either
specific for common classes of devices (hard disks, CD-ROM drives) or
which provide a universal interface for additional application
specific device drivers.

One of these universal device managers in OS/2 2.x implements
Adaptec's ASPI programming interface for OS/2. ASPI (Advanced SCSI
Programming Interface) allows development of applications, which can
communicate with peripheral devices, independent of the actual SCSI
host adaptor. ASPI definitions exist for DOS, Windows, OS/2 and Novell
NetWare 3.x and 4.x servers.

The ASPI programming interface in OS/2 2.x resides in the base device
manager OS2ASPI.DMD (please refer to the OS/2 online documentation for
more information about it). In this implementation, it supports only
OS/2 device drivers which build upon the ASPI interface. Neither can
OS/2 applications nor can DOS and Windows applications running under
OS/2 2.x access the ASPI interface of OS/2 2.x directly.

Since many existing DOS and Windows applications use ASPI to
communicate with SCSI devices (for example, backup software for SCSI
tape devices or image scanning software for SCSI scanners), such
applications could not be used under OS/2 2.x so far.

The includes virtual ASPI driver (VASPI) for OS/2 2.x implements an
ASPI interface for DOS and Windows applications running in DOS and
WIN-OS/2 sessions under OS/2 2.x. Both the ASPI definition for DOS and
the ASPI definition for Windows are implemented. In addition the
driver contains an ASPI interface for OS/2 applications, since they
can otherwise not directly access the OS/2 ASPI and would thus need
their own device drivers for this purpose.


2. Installation

The virtual ASPI driver consists of three drivers modules:

a) the physical VASPI driver which connects to the OS/2 ASPI driver
   (which is installed with BASEDEV=OS2ASPI.DMD), this module is named
   VASPIDD.SYS,

b) the virtual VASPI driver which implements the ASPI definition for
   DOS, named VASPI.SYS and

c) the Windows DLL which implements the ASPI definition for Windows,
   named WINASPI.DLL.

For installation, the two device drivers are loaded in CONFIG.SYS as
follows (we suggest copying both drivers into the \OS2 directory on
your system boot drive):

  DEVICE=C:\OS2\VASPIDD.SYS
  DEVICE=C:\OS2\VASPI.SYS

If you install the drivers on another drive or directory or your
system boots from a different drive than C:, please correct the two
lines as needed.

The exact position of these two lines in CONFIG.SYS is not
significant, but we suggest putting them directly after the
BASEDEV=OS2ASPI.DMD line. If you can't find this line in your
CONFIG.SYS yet, please look up the OS/2 documentation and add it after
the BASEDEV= line which loads the driver for your SCSI host adaptor
(drivers of this kind always have a name ending with .ADD).

The Windows DLL (WINASPI.DLL) must be copied into the WIN-OS/2 system
directory, usually C:\OS2\MDOS\WINOS2\SYSTEM.

With these steps, the installation is completed, but you have to
restart (reboot) your system to make the changes active.

Please ensure that during boot of your system all SCSI peripherals are
correctly connected to the compuer and are also turned on. The OS/2
drivers for most SCSI host adaptore and the OS/2 ASPI device manager
check at load time, if there are devices to manage at all. If that is
not the case, these drivers perhaps don't even load.

Please check also, if the SCSI bus termination is installed correctly.
A common error is that both internal and external devices are
connected to the SCSI host adaptor but the termination on the host
adaptor itself was not removed (the SCSI bus must be terminated only
on both ends). In such cases some or all connected devices may not be
detected and data transfer errors can occur. The termination on the
host adaptor is usually configured with jumpers, DIP switches,
removable resistor packs or even via software.

To determine if and which devices are recognized by the host adaptor
(if that feature is not already provided by your host adaptors BIOS
during the power on self test) you can add the /V option to your host
adaptors BASEDEV driver in CONFIG.SYS. Most OS/2 ADD drivers recognize
this option and respond by displaying version numbers, perhaps
hardware revisions and most often a list of found SCSI devices.

If all drivers load correctly, you can finally use the included test
programs (see below) to retrieve a list of available devices for ASPI
applications. This list will often be shorter that the ADD drivers
list, because some devices may already be in use by other device
managers and are thus not available to the ASPI manager.


3. DOS Settings

After you have installed the driver(s) correctly and have restarted
your system, you will find a new entry in the DOS settings of DOS
program objects, ASPI_ENABLE. This parameter defines, if ASPI is
available in the session started from this object. The default is OFF,
i.e. the ASPI interface is NOT available. Please change this parameter
for all those program objects which you use to start your (DOS and
WIN-OS/2) ASPI applications to ON. The default (OFF) can be changed
globally to ON by adding the option /ON to the line
DEVICE=C:\OS2\VASPI.SYS in your CONFIG.SYS. In this case all DOS and
WIN-OS/2 sessions have ASPI available automatically, but you can still
disable ASPI for each program object individually.


4. Programmer's API

If you want to develop own DOS or Windows applications for ASPI, you
can use the documentation and sample code available from Adaptec. If
you want to develop OS/2 ASPI applications but want to avoid writing
your own device driver interfacing with OS/2's ASPI manager, you can
use the API included in VASPIDD.SYS.

You can find sample DOS and OS/2 ASPI applications in the \SAMPLES
directory in the distribution of this driver. It contains the source
code for the DOS and OS/2 test programs for ASPI (as mentioned below)
and a C header file with the ASPI definitions for DOS and OS/2 ASPI
applications.

The DOS test program can be compiled with Microsoft C, version 6.00 or
newer. For other compilers, changes are required because inline
assembly language statements are used for access to the DOS ASPI
interface. This sample program does of course also work under plain
DOS with standard ASPI drivers.

The OS/2 test program can be compiled as 16-bit application with
Microsoft C, version 6.00 or Watcom C/C++ 16, version 9.5 or higher.
To generate a 32-bit version, IBM C Set++, Watcom C/C++ 32, version
9.5 or higher or the GNU C compiler can be used. For other compilers
only minimal changes should be required, since the standard I/O
control interface is used for access to VASPIDD.SYS.

This API for OS/2 ASPI applications knows a "posting" and a "non-
posting" mode, just like the DOS and Windows versions (see Adaptec
ASPI documentation for an explanation what posting means). However,
because of the proteced architecture of OS/2, postimg mode is only
possible for device drivers interfacing directly with the OS/2 ASPI
manager. SCSI requests via the API in VASPIDD.SYS are always processed
in posting mode, but the post routine is contained in this driver and
there is no way to define a post routine in the calling application.
That means that a request via this API does only return to the calling
application when it was completely processed, the application will be
blocked until this is the case. However, this blocking only affects
the calling thread. If the application has to do other work during
this time, it must be multithreaded.

Posting for DOS and Windows ASPI applications works, it is simulated
by the virtual ASPI driver, because existing DOS and Windows
applications use that feature.

There can be more than one application or thread accessing the API at
a time, the VASPIDD.SYS driver is reentrant.


5. Test Programs

In the distribution there are two test programs, ASPI.EXE (a DOS
application) and ASPI2.EXE (an OS/2 application), that can be used for
diagnostic purposes. They are sample programs too (see above) and
their source code is included.

Both programs, DOS and OS/2 version, use ASPI to list all SCSI host
adaptors in the system and all SCSI peripheral devices connected to
them, as long as they are not yet in use by other device managers (as
it is the case with hard disks and CD-ROM drives). For all devices
found the device type, vendor name and device name are listed.


6. Compatibility

The following DOS and Windows applications were testes successfully
for compatibility:

a) SCSI tape backup software (with a Tandberg TDC-4100 streamer)

- NovaStore NovaBack, version 3.57
- CorelSCSI Tape Backup for DOS, version 1.22
- CorelSCSI Tape Backup for Windows, version 1.14
- GNU tar (GTAK 1.00)
- GNU tar (ASPI-TAR)

b) SCSI image scanning software

- HP DeskScan for Windows, versions 1.51 and 2.0
- Calera WordScan+ for Windows (OCR software with scanner interface)
- ImpOS/2 1.10 (image processing software with scanner interface)
  (This OS/2 software cann access a DOS HP scanner device driver via a
  auxiliary program in a DOS session.)

(These applications were tested with a HP ScanJet IIcx and the
included ASPI compatible DOS device driver SJIIX.SYS.)

- HighScan for Windows, version 3.1, scanner: Siemens ST-400
- Agfa PC View Color, version 1.02, scanner: Agfa Arcus Plus
- Agfa FotoLook, version 1.26E, scanner: Agfa Arcus Plus

The HP DeskScan and Agfa FotoLook applications also provide a TWAIN
interface for Windows applications and let thus other Windows
applications access the scanner if they support TWAIN, for example,
Adobe PhotoStyler or Corel PhotoPain (part of Corel Draw 4.0 for
Windows).

If you use other software with this VASPI driver which is not listed
here, please send us a short notice to allow us adding it to this
compatibility list.


7. Known Problems

- If the ASPI interface is turned off for a DOS session (via the DOS
  settings), some ASPI compatible software still assumes erroneously
  the availability of an ASPI interface. This also occures if only the
  OS/2 ASPI device manager (OSASPI.DMD) is installed but not the VASPI
  driver. It is thus not a problem in the VASPI driver but caused by
  the fact that both the OS/2 ASPI manager (OS2ASPI.DMD) and ASPI
  managers under plain DOS use the same device name, SCSIMGR$.

- If you run Windows ASPI applications in fullscreen WIN-OS/2
  sessions, it is normal if during processing of SCSI requests which
  take rather long to complete (tape rewinding, for example) the mouse
  pointer cannot be moved. This is caused by the fact that the session
  is blocked in the ASPI driver during this time.

- The Centrol Point backup programs in the DOS (8.0, 9.0) and Windows
  (2.0) versions of the PC-TOOLS packages do not work reliably with
  this VASPI driver. While these programs can access SCSI tape
  devices, they may crash at random occasions, causing the affected
  DOS or WIN-OS/2 session to be terminated.


8. Test/Problem Reports

If you should have problems using an ASPI compatible DOS or Windows
software with this VASPI driver, please send a report with the
following items included:

- version and serial number of the VASPI driver
- exact type, name, version and vendor of the affected software
- type and manufacturer of the SCSI peripheral device
- type and manufacturer of the SCSI host adaptor
- source, name and date/size of the host adaptor driver (.ADD)
- source, name and date/size of the OS/2 ASPI manager (OS2ASPI.DMD)
- operating system version (if not OS/2 2.1)
- computer bus architecture (ISA, EISA, MCA, PCI)

and your address, phone and fax number.
