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►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPISEGMENTS
 
LONG GpiPutData(hps, cmdFormat, pcb, pb)
HPS hps;           /* presentation-space handle                    */
LONG cmdFormat;    /* coordinate type                              */
PLONG pcb;         /* address of variable for length of order data */
PBYTE pb;          /* address of buffer for order data             */
 
The GpiPutData function draws the graphics orders given in the buffer
pointed to by the pb parameter. The function carries out the graphics
operation specified by each graphics order. The buffer can contain any
number of graphics orders as long as the buffer does not exceed 63K. The
pcb parameter specifies the number of bytes of graphics-order data in the
buffer. The function converts the coordinates in the graphics orders if the
format specified by the cmdFormat parameter is not the same as the format
used by the presentation space.
 
The GpiPutData function is used typically with the GpiGetData function to
copy graphics orders from one segment to another. For convenience, the last
order in the buffer does not have to be complete. If the order is not
complete, the function does not copy the order. Instead, it replaces the
count in pcb with the count of bytes copied. This count can be used to
locate the incomplete order in the buffer.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies a presentation space.
 
cmdFormat  Specifies the type of coordinates used in the graphics orders. It
           can be one of the following values:
 
           Value            Meaning
           ─────────────────────────────────────────────────────────────────
           DFORM_S370SHORT  Uses S/370-format short (2-byte) integers.
 
           DFORM_PCSHORT    Uses PC-format short (2-byte) integers.
 
           DFORM_PCLONG     Uses PC-format long (4-byte) integers.
 
pcb        Points to a variable. When this function is called, the variable
           specifies the size (in bytes) of the buffer pointed to by the pb
           parameter. When the function returns, the variable contains the
           length of the data copied to the pb buffer.
 
pb         Points to the buffer that contains the graphics-order data. It
           must not contain more than 63K of data.
 
Return Value
 
The return value is GPI_OK or GPI_HITS if the function is successful (it is
GPI_HITS if the detectable attribute is set for the presentation space and a
correlation hit occurs). The return value is GPI_ERROR if an error occurs.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_DATA_TOO_LONG
     PMERR_INV_EDIT_MODE
     PMERR_INV_ELEMENT_POINTER
     PMERR_INV_HPS
     PMERR_INV_IN_CURRENT_EDIT_MODE
     PMERR_INV_LENGTH_OR_COUNT
     PMERR_INV_MICROPS_FUNCTION
     PMERR_INV_ORDER_LENGTH
     PMERR_INV_PUTDATA_CONTROL
     PMERR_PS_BUSY
 
Comments
 
The current drawing mode determines whether the function draws the graphics
orders or copies them to a segment. To copy the graphics orders to the
currently open segment, an application must set the current segment editing
mode to SEGEM_INSERT and move the element pointer to the last element in the
segment. The function can be used in an element bracket if the
graphics-order data does not contain an element bracket.
 
Example
 
This example uses the GpiPutData function to copy graphics orders from one
segment to another:
 
LONG fFormat = DFORM_NOCONV;   /* do 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);       /* open segment to receive the 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 > 0L);
GpiCloseSegment(hps);            /* close segment that received data */
 
See Also
 
GpiBeginElement, GpiEndElement, GpiGetData, GpiSetDrawingMode,
GpiSetEditMode, WinGetLastError
 
                                      ♦