Build your own ASPI DLL

Simple assembly project to build your own custom ASPI DLL.
Use it to interface your SCSI2 devices.
Ten useful and ready to use functions included.
  • Forewords
  • Scenario
  • The ingredients of the DLL
  • Build it
  • Add your functions
  • Forewords

    A SCSI2 device can execute SCSI2 commands, but to make something useful a number of consecutive commands is generally required. For example: to make a scanner scan a page you should first test whether the unit is ready, then send it an "object position" and a "set window" commands. Finally you should send the scanner a number of consecutive "read" commands to get the raster data.

    The best place to put all these SCSI2 commands is a function into a DLL. An application program will simply call that function, pass it some parameters, and wait for the raster data to arrive (or an error code back from the scanner instead).

    This way application program listings will be very neat and concise, and the code in the DLL will be reusable from many applications.

    My application programs are usually written in C++ using that fantastic tool that's called Borland C++ Builder. These programs use to call some high level functions to drive SCSI2 devices of my interest.

    Those *high* level functions are defined and contained into a DLL, written in win32asm, that does all the *low* level job to make devices do something useful like scanning a page.

    Below I will provide you with a simple DLL skeleton ready to accept new functions that you will define. To make things more interesting I left into the DLL skeleton ten functions of mine:

    • ASPI start function, to start ASPI operations
    • ASPI stop function, to stop ASPI operations
    • SCSI2 bus scan function, very useful and istructive
    • scan page function valid for some popular SCSI2 scanners
    • get CD-R disc info function valid for many SCSI3 CD-R writers
    • show value general purpose function to make you see a 32 bit value at runtime when it's time to debug
    • Open a file to be Base64 encoded useful for e-mail SMTP clients
    • Get Base64 encoded contents of a file useful for e-mail SMTP clients
    • Close the Base64 encoded file useful for e-mail SMTP clients
    • Base64 encode any string useful for e-mail SMTP clients
    Complete details for each function included into the source code, see below.

    Actually the last four functions are not ASPI-bound, but have been added here to complete the article about the ESMTP/SMTP client in the C++ section of these web pages for the programmer.

    Scenario

    Suppose you have a SCSI2 tape drive that you used to deal with under DOS, and now you want to operate it from your Win32 programs. You need a DLL.

    Start building the DLL as shown below, and write a simple C++ program to scan the SCSI2 bus just to see whether the device responds or not (use the supplied SCSI2 bus scan function and eventually have a look at this example).

    Then revise chapter 10 of SCSI2 specification and refresh the theory of operations for sequential-access devices. Decide which functions you need for your application programs and how to implement it using SCSI2 commands.

    That's all. Follow the instructions below and good luck.

    The ingredients of the DLL

    Four file types are required to build the DLL:
    • one ASM file that contains the data segment and the DLL entry point
    • one DEF file that contains the name of the DLL and the name of the functions that have to be exported
    • one or more INC files that have to be included into the ASM file
    • one BAT file that acts as the *makefile* for the DLL to build
    The INC files are not actually required, but using them helps maintaining neat listings and a clear structure of the DLL.

    Build it

    To build the basic ASPI DLL, i.e. the DLL that contains only the five functions above mentioned, you should follow the steps described below. The only prerequisite is having MASM32 installed in your PC.
    These are the steps:
    • make a working directory in your hard disk and name it ASPIDLL; you will use this directory to keep the following files
    • cut this file and paste it into an ASCII file named ASPIDLL.ASM
    • cut this file and paste it into an ASCII file named ASPIDLL.DEF
    • cut this file and paste it into an ASCII file named MAKEDLL.BAT
    • cut this file and paste it into an ASCII file named FFASPI.INC
    • cut this file and paste it into an ASCII file named FFSCAN.INC
    • cut this file and paste it into an ASCII file named FFUTIL.INC
    • cut this file and paste it into an ASCII file named FFCDR.INC
    • cut this file and paste it into an ASCII file named FFBASE64.INC
    • cut this file and paste it into an ASCII file named B64TABLE.INC
    • cut this file and paste it into an ASCII file named WNASPI32.INC (to be put into C:\MASM32\INCLUDE directory)
    • cut this file and paste it into an ASCII file named SCSIDEFS.INC (to be put into C:\MASM32\INCLUDE directory)
    • run MAKEDLL.BAT and have the DLL done, togheter with its LIB import library file for static linking.
    An example of using the DLL to scan the SCSI2 bus is given here. An example to get CD-R disc info (for a disc inserted into a SCSI3 CD-R writer) is given here.

    Add your functions

    Nothing is more simple than adding your functions to the ASPI DLL, provided you are acquainted with win32asm programming. For each new function you should do the following:
    • add the name of the function into the DEF file
    • create a new INC file and include it into ASPIDLL.ASM
    • fill the INC file with the proper code
    • rebuild the DLL
    Remember that the data segment is kept into ASPIDLL.ASM.

    I left the scan page function to give you a complete example of a working routine that you can look at.

    Please contact me if I forgot something or some explanation is not clear enough.

    For those that do not use MASM32 but want to use the SCSI2 bus scan function I put here the zipped version of the compiled DLL. It is 9.728 bytes long (unzipped). Please refer to this project to see how to write an application that scans the SCSI2 bus.