Your application can use GpiGetData and GpiPutData to:
GpiGetData copies a buffer of graphics orders from a named segment, into an area of application storage, whose byte size you specify on input. Only the named segment must not be open when you call this function. The named segment is also known as the source segment.
The first time GpiGetData is called, data retrieval has to start at the beginning of the segment. This is done by declaring an element offset of 0.
Output from GpiGetData depends on whether the area of application storage is large enough to hold the entire buffer of graphics orders. If so, the buffer is returned along with a count of the number of bytes of data returned to you from the segment. If not, the application storage is filled, and the count is set to the size of the application storage. The offset of the element where GpiGetData stopped copying, and the count are returned. Your application can then determine if a subsequent GpiGetData needs to be called, by checking that the count is less than the size (length) of the application storage.
On subsequent GpiGetData functions, the element offset can be 0, or it can be the offset value that was returned from the previous function. In this manner, if your application calls GpiGetData more than once to copy an entire segment, it can "pick up where it left off", rather than recopying the segment from the beginning each time.
You can copy the data from the application storage to a new location in a segment using GpiPutData. This receiving segment is also known as the destination segment. The segment into which you are copying the data can be open when you call GpiPutData.
If GpiGetData does not retrieve a complete segment, the data it does retrieve can be written out to the second segment using GpiPutData, even if the last order copied is incomplete.
The current drawing mode determines whether the graphics orders are executed, stored in the segment, or both. When you call GpiPutData, the current edit mode must be SEGEM_INSERT and, if there is already data in the destination segment, the element pointer must address the last element of the segment.
Because the PM does not support explicit renaming of segments, GpiGetData-GpiPutData is the method you use to rename a segment. That is, create a second segment with the desired name, copy the contents of the first segment to it, then delete the original segment.