Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►  ◄Changes►               ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPISEGMENTS
 
LONG GpiGetData(hps, idSegment, poff, cmdFormat, cb, pb)
HPS hps;           /* presentation-space handle              */
LONG idSegment;    /* segment identifier                     */
PLONG poff;        /* address of variable for segment offset */
LONG cmdFormat;    /* conversion type                        */
LONG cb;           /* length in bytes of the data buffer     */
PBYTE pb;          /* address of buffer for data             */
 
The GpiGetData function copies graphics orders from the specified segment to
the specified buffer. The function continues to copy the graphics orders
from the segment to the buffer until all orders in the segment have been
copied or the number of bytes specified by the cb parameter have been
copied. If the function fills the buffer, the last order in the buffer may
not be complete since the function does not stop on an order boundary when
copying to the buffer. In any case, the function returns the number of bytes
copied to the buffer.
 
The function starts copying graphics-order data from the location specified
by the poff parameter. If this parameter is zero, the function copies from
the beginning of the segment. After copying the data, the function replaces
the value in poff with the offset to the next byte of data to copy from the
segment (if any). This value can be used to specify the next location to
copy.
 
The GpiGetData function cannot be used to copy data from an open segment,
but it can be used to copy data while some other segment is open.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
idSegment  Specifies the segment identifier.
 
poff       Points to the variable that contains the offset from the
           beginning of the segment to the next byte of graphics order data
           to copy. If this parameter is zero, the function copies from the
           beginning of the segment.
 
cmdFormat  Specifies the coordinate conversion type. It can be one of the
           following values:
 
           Value            Meaning
           ─────────────────────────────────────────────────────────────────
           DFORM_NOCONV     Copies coordinates without converting. The
                            coordinates are in the format used by the
                            presentation space.
 
           DFORM_PCLONG     Converts coordinates to PC-format long (4-byte)
                            integers.
 
           DFORM_PCSHORT    Converts coordinates to PC-format short (2-byte)
                            integers.
 
           DFORM_S370SHORT  Converts coordinates to S/370-format short
                            (2-byte) integers.
 
cb         Specifies the length in bytes of the buffer to receive the
           graphics orders.
 
pb         Points to the buffer that receives the graphics-order data.
 
Return Value
 
The return value is the number of graphics-order bytes copied if the
function is successful or GPI_ALTERROR if an error occurred.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_DATA_TOO_LONG
     PMERR_INV_GETDATA_CONTROL
     PMERR_INV_HPS
     PMERR_INV_LENGTH
     PMERR_INV_LENGTH_OR_COUNT
     PMERR_INV_MICROPS_FUNCTION
     PMERR_INV_SEG_NAME
     PMERR_INV_SEG_OFFSET
     PMERR_PS_BUSY
     PMERR_SEG_IS_CURRENT
     PMERR_SEG_NOT_FOUND
 
Example
 
This example uses the GpiGetData function to copy data from one segment to
another.
 
LONG fFormat = DFORM_NOCONV;     /* does not convert coordinates      */
LONG offSegment = 0L;            /* offset in segment                 */
LONG offNextElement = 0L;        /* offset in segment to next element */
LONG cb = 0L;                    /* bytes retrieved                   */
BYTE abBuffer[512];
 
GpiOpenSegment(hps, 3L);         /* opens segment to receive data     */
do {
    offSegment += cb;
    offNextElement = offSegment;
    cb = GpiGetData(hps, 2L, &offNextElement, fFormat, 512L, abBuffer);
 
    /* Put data in other segment. */
 
    if (cb > 0L) GpiPutData(hps, /* presentation-space handle         */
        fFormat,                 /* format of coordinates             */
        &cb,                     /* number of bytes in buffer         */
        abBuffer);               /* buffer with graphics-order data   */
 
} while (cb > 0);
GpiCloseSegment(hps);            /* closes segment that received data */
 
See Also
 
GpiPutData, WinGetLastError
 
                                      ♦