GpiPutData
This function passes a buffer of graphics orders to the current segment, or draws the orders, or both of these. For details of the orders, see Graphics Orders.
Syntax
GpiPutData(hps, lFormat, plCount, pbData)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- lFormat (LONG) - input
- Coordinate type used.
- This parameter can have one of the following values:
- DFORM_NOCONV : No coordinate conversion performed
- DFORM_S370SHORT : S/370 format short (2-byte) integers
- DFORM_PCSHORT : PC format short (2-byte) integers
- DFORM_PCLONG : PC format long (4-byte) integers.
- plCount (PLONG) - in/out
- Length of graphic data.
- Set by the application to the length of order data in pbData. If an incomplete order occurred, it is updated, on return, to the offset of the start of the incomplete order.
- plCount must be greater or equal to 0 and less or equal to 64 152 bytes (63KB).
- pbData (PBYTE) - input
- Orders to be copied.
Return Value
- lHits (LONG) - returns
- Correlation and error indicators.
- GPI_OK : Successful
- GPI_HITS : Correlate hits
- GPI_ERROR : Error.
Remarks
The orders passed may be added to the current segment, drawn immediately, or both, depending on the current drawing mode (see GpiSetDrawingMode), and whether the primitives are within a segment. If there is an incomplete order at the end of the buffer, plCount is updated to point to the start of the incomplete order. The application can then concatenate this partial order in front of the next buffer. The orders End Prolog and Set Viewing Transform are not allowed. This function is valid within an element bracket (see GpiBeginElement). It can contain GpiBeginElement and GpiEndElement orders, while these are in the correct sequence with respect to the currently opened segment in segment store. The data in the buffer is converted, if necessary, to the presentation space format (defined when the presentation space is first created; see GpiCreatePS). This function is invalid if the editing mode (see GpiSetEditMode) is set to SEGEM_REPLACE, and also in SEGEM_INSERT mode if the element pointer is not pointing to the last element.
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_PUTDATA_FORMAT (0x20BB)
- An invalid format parameter was specified with GpiPutData.
- 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_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.
- PMERR_INV_ELEMENT_POINTER (0x206B)
- An attempt was made to issue GpiPutData with the element pointer not pointing at the last element.
- PMERR_INV_REPLACE_MODE_FUNC (0x20C0)
- An attempt was made to issue GpiPutData with the editing mode set to SEGEM_REPLACE.
- PMERR_ORDER_TOO_BIG (0x20E8)
- An internal size limit was exceeded while converting orders from short to long format during GpiPutData processing. An order was too long to convert.
Example Code
This example uses the GpiPutData function to copy graphics orders from one segment to another.
#define INCL_GPISEGMENTS /* Segment functions */
#include <os2.h>
HPS hps; /* presentation space handle */
LONG fFormat = DFORM_NOCONV;/* do not convert coordinates */
LONG offSegment = 0L; /* offset in segment */
LONG offNextElement = 0;/* offset in segment to next element */
LONG cb = 0L; /* bytes retrieved */
BYTE abBuffer[512]; /* data buffer */
GpiOpenSegment(hps, 3L); /* open segment to receive the data */
do { /* retrieve data from segment 2 */
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 > 0L);
GpiCloseSegment(hps); /* close segment that received data */