TAPE_STATUS
TapeMiniSetPosition(
IN OUT PVOID MinitapeExtension,/* optional */
IN OUT PVOID CommandExtension,/* optional */
IN OUT PVOID CommandParameters,
IN OUT PSCSI_REQUEST_BLOCK Srb,
IN ULONG CallNumber,
IN TAPE_STATUS StatusOfLastCommand,/* optional */
IN OUT PULONG RetryFlags/* optional */
);
TapeMiniSetPosition handles the device-specific aspects of an IOCTL_TAPE_SET_POSITION request. It is one of the TapeMiniProcessCommand routines in a miniclass driver and is called by the tape class driver. This routine is required.
Parameters
MinitapeExtension
Points to the driver-specific minitape extension. The pointer is NULL if the miniclass driver did not specify a minitape extension.
CommandExtension
Points to the command extension. The pointer is NULL if the miniclass driver did not specify a command extension.
CommandParameters
Points to a buffer containing the parameters for the command. The structure for each I/O command (IOCTL) is defined in minitape.h.
Srb
Points to the partially filled SRB. TapeMiniSetPosition must fill in the CDB in the SRB. TapeMiniSetPosition might fill in other SRB members, depending on the requirements of its device(s).
CallNumber
Specifies the number of times the routine has been called to process a given tape command. CallNumber is zero the first time this routine is called for a given command and is incremented until the command request is complete.
StatusOfLastCommand
Specifies the status of the last command. The tape miniclass driver can set RETURN_ERRORS in RetryFlags to have the tape class driver return errors to the miniclass driver rather than directly to the application. Zero if RETURN_ERRORS was not set.
RetryFlags
Points to a value that specifies what action the tape class driver should take when a tape device reports an error.
The low-order word specifies the number of retries to perform in the event of a SCSI command failure. The default is zero (no retries).
The high-order word contains flags:
·By default, the RETURN_ERRORS and IGNORE_ERRORS flags are clear and the tape class driver returns a failure status to the requesting application if an error occurs.
·If RETURN_ERRORS is set, the tape class driver returns a failure status, but returns control to the TapeMiniProcessCommand routine rather than to the application.
·If IGNORE_ERRORS is set, the tape class driver converts a failure status to a success status, and returns control to the TapeMiniProcessCommand routine rather than the application.
Return Value
TAPE_STATUS_SEND_SRB_AND_CALLBACK
Indicates to the tape class driver that the SRB has been filled in and is ready to be given to the device. By default, the tape miniclass driver’s TapeMiniProcessCommand routine is called back if the SRB is successfully completed by the tape class driver. A miniclass driver can modify the default behavior using RetryFlags.
TAPE_STATUS_CALLBACK
Directs the tape class driver to increment CallNumber and call back to the TapeMiniProcessCommand routine, without sending an SRB to the tape device.
TAPE_STATUS_CHECK_TEST_UNIT_READY
Directs the tape class driver to fill in an SRB for the TEST UNIT READY command and send the SRB to the device.
TAPE_STATUS_XXX
Any other return code indicates to the tape class driver that the command is complete and indicates success, failure, or warning. Possible completion return values for this routine include, but are not limited to:
TAPE_STATUS_SUCCESS
TAPE_STATUS_INVALID_DEVICE_REQUEST
TAPE_STATUS_NOT_IMPLEMENTED
Comments
TapeMiniSetPosition builds SRBs with CDBs to position a tape. It can take one or more SRBs to complete the request. TapeMiniSetPosition returns each SRB to the tape class driver which sends it along to the device.
TapeMiniSetPosition must fill in the following members in the SRB before returning to the tape class driver:
·Cdb - Points to the SCSI CDB for the command. Clear the CDB with TapeClassZeroMemory before filling it in.
·CdbLength - Specifies the number of bytes in the CDB.
TapeMiniSetPosition can optionally fill in the following members in the SRB:
·DataBuffer - Points to the data buffer to be transferred. Use TapeClassAllocateSrbBuffer to allocate a DataBuffer of length greater than or equal to DataTransferLength.
·DataTransferLength - Specifies the number of bytes to be transferred for this SCSI command. This member is set by TapeClassAllocateSrbBuffer.
·TimeOutValue - Specifies a timeout value for this comand, overriding the default timeout value.
·SrbFlags - Specifies a flag for this command. The SRB_FLAGS_DATA_OUT flag must be set if the SCSI command is sending data to the tape drive. This member can be zero if the SCSI command is receiving data from the tape drive or if no data is being transferred by the command.
See Also