en:ibm:ifs:helpers:dovolio
Book Creator
 Add this page to your book
Book Creator
 Remove this page from your book  

 Manage book(0 page(s))
 Help

FSH_DOVOLIO

Purpose

This function performs I/O to the specified volume.

Calling Sequence 

int far pascal FSH_DOVOLIO(operation, fAllowed, hVPB, pData, pcSec, iSec)
 
unsigned short operation;
unsigned short fAllowed;
unsigned short hVPB;
char far * pData;
unsigned short far * pcSec;
unsigned long iSec;

Where

operation is the bit mask indicating read/read-bypass/write/write-bypass,
and verify- after-write/write-through and no-cache
operation to be performed.
Bit 0x0001 off indicates read.
Bit 0x0001 on indicates write.
Bit 0x0002 off indicates no cache bypass.
Bit 0x0002 on indicates cache bypass.
Bit 0x0004 off indicates no verify-after-write operation.
Bit 0x0004 on indicates verify-after-write operation.
Bit 0x0008 off indicates errors signaled to the hard error daemon.
Bit 0x0008 on indicates hard errors will be returned directly.
Bit 0x0010 off indicates I/O is not write-through.
Bit 0x0010 on indicates I/O is write-through.
Bit 0x0020 off indicates data for this I/O should probably be cached.
Bit 0x0020 on indicates data for this I/O should probably not be cached.
All other bits are reserved and must be zero.

The difference between the cache bypass and the no cache bits is in the type of request packet that the device driver will see. With cache bypass, it will get a packet with command code 24, 25, or 26. With no cache, it will get the extended packets for command codes 4, 8, or 9. The advantage of the latter is that the write-through bit can also be sent to the device driver in the same packet, improving the functionality at the level of the device driver.

fAllowed is a bit mask indicating allowed actions:
Bit 0x0001 on indicates FAIL allowed
Bit 0x0002 on indicates ABORT allowed
Bit 0x0004 on indicates RETRY allowed
Bit 0x0008 on indicates IGNORE allowed
Bit 0x0010 on indicates ACKNOWLEDGE only allowed
If this bit is set, none of the other bits may be set.

All other bits are reserved and must be set to zero.

hVPB is the volume handle for the source of I/O.

pData is the long address of the user transfer area.

pcSec is the pointer to the number of sectors to be transferred.

On return, this is the number of sectors successfully transferred.

iSec is the sector number of the first sector of the transfer.

Returns

If no error is detected, a zero error code is returned. If an error is detected, one of the following error codes is returned:

  • ERROR_PROTECTION_VIOLATION – indicates the supplied address/length is invalid.
  • ERROR_UNCERTAIN_MEDIA – indicates the device driver can no longer reliably tell if the media has been changed.

This occurs only within the context of an FS_MOUNT call.

  • ERROR_TRANSFER_TOO_LONG – indicates the transfer is too long for the device.
  • Device-driver/device-manager errors listed /DDERR/

Remarks

This function formats a device driver request packet for the requested I/O, locks the data transfer region, calls the device driver, and reports any errors to the hard error daemon before returning to the FSD. Any retries indicated by the hard error daemon or actions indicated by DosError are done within the call to FSH_DOVOLIO.

FSH_DOVOLIO may be used at all times within the FSD. When called within the scope of a FS_MOUNT call, it applies to the volume in the drive without regard to which volume it may be. However, since volume recognition is not complete until the FSD returns to the FS_MOUNT call, the FSD must be careful when an ERROR_UNCERTAIN_MEDIA is returned. This indicates the media has gone uncertain while we are trying to identify the media in the drive. This may indicate the volume that the FSD was trying to recognize was removed. In that case, the FSD must release any resources attached to the hVPB passed in the FS_MOUNT call and return ERROR_UNCERTAIN_MEDIA to the FS_MOUNT call. This will direct the volume tracking logic to restart the mount process.

OS/2 will validate the user transfer area for proper access and size and will lock the segment.

Verify-after-write specified on a read is ignored.

On 80386 processors, FSH_DOVOLIO will take care of memory contiguity requirements of device drivers. It is advisable, therefore, that FSDs use FSH_DOVOLIO instead of calling device drivers directly. This will improve performance of FSDs running on 80386 processors.

FSH_DOVOLIO may block.

Note: OS/2 does not validate input parameters. An FSD, therefore, should call FSH_PROBEBUF where appropriate.