GpiGetData

This function retrieves a buffer of graphic data from the specified segment into the supplied buffer. The data is a list of drawing orders. For details of these, see Graphics Orders

Syntax

GpiGetData(hps, lSegid, plOffset, lFormat, lLength, pbData)

Parameters

hps (HPS) - input

Presentation-space handle.

lSegid (LONG) - input

Segment identifier.

It must be greater or equal to 0.

plOffset (PLONG) - in/out

Segment offset.

A value used to indicate the position in the segment from which data is to be retrieved. It must be set to 0 the first time GpiGetData is called. This indicates that data is to be obtained from the start of the segment. On return, it contains a value that can be used on a subsequent call to continue data retrieval.

The only possible values that can be specified are 0 or the value returned from a previous function.

lFormat (LONG) - input

Coordinate type required.

DFORM_NOCONV - No coordinate conversion performed.

This is the only value and it is required. That is, the parameter must be set to this value.

lLength (LONG) - input

Length of data buffer.

pbData (PBYTE) - output

Data buffer.

For order formats, see Graphics Orders.

Returns

lCount (LONG) - returns

Length of returned data.

>=0:Number of bytes actually returned in pbData

GPI_ALTERROR - Error.

Errors

Possible returns from WinGetLastError

PMERR_INV_HPS (0x207F)

An invalid presentation-space handle was specified.

PMERR_PS_BUSY (0x20F4)

An attempt was made to access the presentation space from more than one thread simultaneously.

PMERR_INV_SEG_NAME (0x20C8)

An invalid segment identifier was specified.

PMERR_INV_SEG_OFFSET (0x20C9)

An invalid offset parameter was specified with GpiPutData.

PMERR_INV_GETDATA_CONTROL (0x2079)

An invalid format parameter was specified with GpiGetData.

PMERR_INV_LENGTH_OR_COUNT (0x2092)

An invalid length or count parameter was specified.

PMERR_INV_MICROPS_FUNCTION (0x20A1)

An attempt was made to issue a function that is invalid in a micro presentation space.

PMERR_SEG_NOT_FOUND (0x2100)

The specified segment identifier did not exist.

PMERR_SEG_IS_CURRENT (0x20FE)

An attempt was made to issue GpiGetData to a segment that was currently open.

PMERR_DATA_TOO_LONG (0x2016)

An attempt was made to transfer more than the maximum permitted amount of data (64512 bytes) using GpiPutData, GpiGetData, or GpiElement.

Remarks

If the buffer is large enough to contain the data requested, the data is returned and lCount is set to show its length.

If the buffer is not large enough, the buffer is filled and lCount is set to the length of the buffer. This may mean that there is an incomplete order at the end of the buffer; even so, it is possible to use GpiPutData subsequently, without having to scan the orders in the buffer.

The application can detect when it has been given all the data by checking the lCount value. If this is less than the value of lLength specified, there is no more data to be returned. If it is equal, there is more data, except in the case where the data just fits in the buffer, which is detected if another GpiGetData function is issued, and a lCount of 0 is returned.

No conversion of coordinates is performed for the DFORM_NOCONV value of the control parameter. The coordinates are in the presentation space format.

This function can be issued while there is a segment open, unless the open segment is the segment referenced by this function. If the segment referenced by this function is open, an error occurs.

The segment transform and viewing transform are not returned by this call.

Example Code

This example uses the GpiGetData function to copy data from one segment to another.

#define INCL_GPISEGMENTS      /* Segment functions               */
#include <os2.h>

HPS  hps;                     /* presentation space handle       */
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];           /* data buffer              */

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 */

Related Functions

• GpiPutData