Syntax

    struct ErrorSenseInfoStruct 
    { 
       LONG   numberBytesRequested;
       LONG   numberBytesReturned;
       LONG   reserved[2];
       BYTE   errorSenseData[1];
    };
    

Fields

numberBytesRequested

A 1-LONG field to contain the number of error sense bytes the CDM issuing the HACB would like to receive when an error with a check condition occurs.

When auto error sense is active for a target device, the CDM assigns the desired value in this field prior to executing the HACB request.

For SCSI, the minimum value a CDM can place in this field is 8. Otherwise, no error sense information will be returned.

numberBytesReturned

A 1-LONG field to contain the number of error sense bytes that the device actually returned, if the number is less than the number the CDM requested.

The HAM sets this value when a HACB request results in an error with a check condition and the target host adapter has auto error sense turned on.

The HAM should set this field according to the following formula:

• numberBytesReturned = min (numberBytesRequested, BytesReturnedByDevice);

The following assumptions apply to the formula:

• The CDM must be informed when the length of the sense information returned by the device is less than what the CDM requests.
• The CDM is not concerned with any additional sense information beyond the amount it requested.

reserved

A field of 2-LONGs reserved by NWPA.

errorSenseData

This field is declared as a byte array with one element. NWPA, however, takes advantage of the fact that the C programming language does not bounds check the array. Therefore, the array's base address (&errorSenseData[0]) is used as the starting address where the HAM is to place the target device's auto error sense data.

The CDM decides the actual size of this byte array at run-time, when it allocates the auto error sense buffer during the building of the HACB. To get an auto error sense buffer of suitable size, the CDM allocates a buffer the size of the ErrorSenseInfoStruct plus however many bytes of auto error sense data it wants returned. This amount is the value that the CDM assigns to the numberBytesRequested field; thus, this field specifies the array's total number of elements.

In building a HACB for a target device with auto error sense active, the CDM assigns the total byte length (sizeof (struct ErrorSenseInfoStruct) + numberBytesRequested) of the auto error sense buffer to the HACB's errorSenseBufferLength field.

The CDM and HAM should go through a pointer to an ErrorSenseInfoStruct to access information in the auto error sense buffer. This pointer implies an ErrorSenseInfoStruct format on the buffer's data, allowing the CDM or HAM to correctly dereference its fields. The HAM knows the full size of the buffer from the value the CDM places in the numberBytesRequested field and adding the 17 header bytes. The CDM knows exactly how much return data to read by the value the HAM places in the numberBytesReturned field.

Remarks

The CDM allocates and fills in one of these buffers for each HACB request targeted to a device attached to an adapter using auto error sense. The CDM links one of these buffers to a HACB by assigning the buffer's NetWare® logical (virtual) address to the HACB's vErrorSenseBufferPtr field. The CDM might want to create a reusable pool of these buffers for the sake of performance. Additionally, the buffer must be allocated as I/O contiguous memory, and as explained under the structure's errorSenseData field presented below, the CDM can vary the size of this buffer according to the number of sense bytes it wants returned. The CDM specifies this number in the numberBytesRequested field.

The HAM copies the auto error sense data into the errorSenseData field of this buffer. Also, the HAM returns to the numberBytesReturned field, the lesser of the value in the numberBytesRequested field or the actual number of sense bytes the device will provide.

If the number of sense bytes returned by the device is fewer than what the CDM requested (numberBytesReturned < numberBytesRequested), the CDM should use the value in the numberBytesReturned field as the index for the errorSenseData array.