FSH GETBUF: Difference between revisions

Latest revision as of 15:56, 20 February 2020

Legacy Function Warning
It is recommended to use a newer replacement for this function.
Replacement:
Remarks:	REMOVED in OS/2 Version 2.0

FSH_GETBUF is used to access the OS/2 sector cache to retrieve a sector from a particular volume. The pointer to the OS/2 buffer cache element is returned. The data in the buffer may be preread if desired.

Syntax

FSH_GETBUF (iSec, fPreread, hVPB, ppBuf)

Parameters

iSec: sector number on the volume to return

fPreread

indicates whether the sector should be preread.

fPreread == 0x00000000 indicates preread sector.
fPreread == 0x00000001 indicates no prereading of sector.

All other values are reserved.

hVPB: handle to the volume

ppBuf: pointer to location where pointer to buffer data is returned

Returns

Error code if operation failed, 0 otherwise.

ERROR_GETBUF_FAILED - the write to clear out a buffer failed or the read to fill the buffer in failed.

Calling Sequence

int pascal FSH_GETBUF (iSec, fPreread, hVPB, ppBuf)

unsigned long    iSec;
unsigned long    fPreRead;
unsigned long    hVPB;
char * *         ppBuf;

Remarks

Note: FSH_GETFIRSTOVERLAPBUF, FSH_GETBUF and FSH_RELEASEBUF are used to obtain and release buffers. Any buffer that is owned by a thread is unavailable to all other threads until it is freed. At most one buffer may be owned by any thread.

Freeing occurs by calling FSH_FLUSHBUF, FSH_RELEASEBUF, or FSH_GETBUF to retrieve another sector.

The buffer returned is marked as being owned by the calling thread. If any OS/2 buffer is still owned by an FSD when the system call completes, the system will halt with an Internal Error, thus the FSD is responsible for ensuring that all system owned buffers are released before it returns to the router.

Not being preread is a performance optimization for when a file is being grown and a partial sector is being filled in.

Reminder: OS/2 does not validate input parameters, so FSD should call FSH_PROBEBUF where appropriate.

FSH_GETBUF may block.

@@ Line 3: / Line 3: @@
 |Remarks=REMOVED in OS/2 Version 2.0
 }}
-Buffered sector read
+FSH_GETBUF is used to access the OS/2 sector cache to retrieve a sector from a particular volume. The pointer to the OS/2 buffer cache element is returned. The data in the buffer may be preread if desired.
 ==Syntax==
@@ Line 9: / Line 9: @@
 ==Parameters==
-;iSec
+;iSec :sector number on the volume to return
-;fPreread
-;hVPB
+;fPreread : indicates whether the sector should be preread.
+:*fPreread == 0x00000000 indicates preread sector.
+:*fPreread == 0x00000001 indicates no prereading of sector.
-;ppBuf
+:All other values are reserved.
+;hVPB : handle to the volume
+;ppBuf : pointer to location where pointer to buffer data is returned
 ==Returns==
+Error code if operation failed, 0 otherwise.
+ERROR_GETBUF_FAILED - the write to clear out a buffer failed or the read to fill the buffer in failed.
 ==Calling Sequence==
 <PRE>
-int far pascal FSH_GETBUF (iSec, fPreread, hVPB, ppBuf)
+int pascal FSH_GETBUF (iSec, fPreread, hVPB, ppBuf)
-unsigned long iSec;
-unsigned short fPreRead;
-char far * ppBuf;
+unsigned long    iSec;
+unsigned long    fPreRead;
+unsigned long    hVPB;
+char * *         ppBuf;
 </PRE>
 ==Remarks==
+; Note : FSH_GETFIRSTOVERLAPBUF, FSH_GETBUF and FSH_RELEASEBUF are used to obtain and release buffers. Any buffer that is owned by a thread is unavailable to all other threads until it is freed. At most one buffer may be owned by any thread.
+Freeing occurs by calling FSH_FLUSHBUF, FSH_RELEASEBUF, or FSH_GETBUF to retrieve another sector.
+The buffer returned is marked as being owned by the calling thread. If any OS/2 buffer is still owned by an FSD when the system call completes, the system will halt with an Internal Error, thus the FSD is responsible for ensuring that all system owned buffers are released before it returns to the router.
+Not being preread is a performance optimization for when a file is being grown and a partial sector is being filled in.
+; Reminder: OS/2 does not validate input parameters, so FSD should call FSH_PROBEBUF where appropriate.
+FSH_GETBUF may block.
 [[Category:IFS Interfaces]]
 {{DISPLAYTITLE:FSH_GETBUF}}