Programming Guidelines

The following are additional guidelines for writing ASPI for Win32 applications.

• ASPI for Win32 applications/clients should send an ASPI Abort command to terminate pending ASPI requests before exit.
• SRBs and data buffers do not need to be in page-locked memory. The ASPI manager takes care of locking buffers and SRBs.
• If an error SS_BUFFER_TO_BIG is returned by the SendASPI32Command routine, you should break the transfer down into 64 KByte transfers or less. For maximum compatibility, we recommend that you do not request transfer sizes larger than 64 KBytes unless your application requires it.
• If you send an ASPI request with posting or callback enabled, the callback procedure will always be called. The post or callback routine is called as a standard C function. The caller (in this case, the ASPI manager) cleans up the stack.
• ASPI for Win32 is fully re-entrant and permits overlapped, asynchronous I/O. Clients can send additional ASPI requests while others are pending completion. Be sure to use a separate SRB for each ASPI request.
• Be sure to zero out all reserved fields before passing an SRB to ASPI for Win32.
• Be sure that buffers are aligned according to the buffer alignment mask returned by the SC_HA_INQUIRY command. An alignment of at least a double word is recommended.
• All SRB structures sent to SendASPI32Command should be compiled packed with byte alignment.
• Some SCSI devices may have security restrictions that make them inaccessible for read/write operations. In operating systems where security is a feature, accessing a device where the application does not have sufficient security privilege results in a SS_SECURITY_VIOLATION error.
• When scanning for devices, the SendASPI32Command may also return the status SS_NO_DEVICE in the SRB_Status field. Check for this exception in addition to the host adapter status HASTAT_SEL_TO. As previously mentioned, the callback procedure is always called, including this condition.
• The SRB flags SRB_POSTING and SRB_EVENT_NOTIFY are mutually exclusive.