\&
.sp 1
.ce 3
\s+1\fBChapter 15\fP\s-1

\s+1\fBSending Encoded Output Commands\fP\s-1
.sp 2
.nr H1 15
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 15: Sending Encoded Output Commands
.XE
.LP
Some applications have access to encoded output commands, such as
for archives or client-side data storage obtained via
.PN PEXEncodeOCs
or
.PN PEXFetchElements .
The functions described in this chapter provide a way for the application
to send this data directly instead of decoding the data and calling the
appropriate output primitive or attribute functions.
.LP
There are two ways provided for sending encoded output commands.  The first is
.PN PEXSendOCs
which is useful if the application has the complete list of encoded output
commands available in contiguous memory.
The second is a set of functions:
.PN PEXStartOCs ,
.PN PEXCopyBytesToOC ,
.PN PEXGetOCAddr ,
.PN PEXFinishOCs .
These are useful if the application has data which is already encoded or which
the application wishes to encode "on-the-fly", but which is not in contiguous
memory.
.PN PEXCopyBytesToOC
can be used to have PEXlib copy individual pieces which are in contiguous memory.
.PN PEXGetOCAddr
can be used to get an address where the application can copy data on its own.
Both of these functions copy data directly into the transport buffer, possibly
avoiding one data copy from the application data into a format necessary to
directly call the PEXlib output command functions.
.LP
None of these functions will convert floating point formats.  It is up to the
application to determine which formats are supported by the PEX server and do
any necessary conversion on the data.  For example, if the PEX server does not
support the floating point format native to the application's machine, the
application will have to convert any native float values into a format supported
by the PEX server.
.LP
For complete information on protocol format, see the
\fIPEX Protocol Specification\fP and the \fIPEX Protocol Encoding\fP.
.bp
.XS
Function Descriptions
.XE
.SH
PEXCopyBytesToOC - Copy Encoded Output Commands
.XS
	PEXCopyBytesToOC
.XE
.IN "PEXCopyBytesToOC" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXCopyBytesToOC\^(\^Display *\fIdisplay\fP\^, int \fIlength\fP\^, char *\fIdata\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIlength\fP 1i
The number of bytes to copy.
.IP \fIdata\fP 1i
A pointer to the output command data.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function copies the specified number of bytes of data to the transport
buffer.
.LP
It is recommended that the number of bytes be a multiple of four as the
protocol format requires output commands to be aligned on four-byte boundaries.
It is the application's responsibility to ensure that alignment restrictions
are met.
.LP
.PN PEXStartOCs
must be called prior to this.
.RE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXStartOCs ,
.PN PEXFinishOCs ,
.PN PEXGetOCAddr
.RE
.bp
.SH
PEXGetOCAddr - Get Address For Encoded Output Commands
.XS
	PEXGetOCAddr
.XE
.IN "PEXGetOCAddr" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
char *PEXGetOCAddr\^(\^Display *\fIdisplay\fP\^, int \fIlength\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIlength\fP 1i
The number of bytes of data to be written by the application.
.RE
.SH
Returns
.RS
.LP
A pointer to memory where the application can write output command data; a null pointer if unsuccessful.
.RE
.SH
Description
.RS
.LP
This function returns a memory address to the specified number of bytes in
the transport buffer where the application can write data.
.LP
The pointer returned is valid only until the next
.PN PEXGetOCAddr
or
.PN PEXCopyBytesToOC
is called.
.LP
An attempt to request more bytes than remaining in the transport buffer, or
more bytes than returned by
.PN PEXGetOCAddrMaxSize ,
will result in an unsuccessful return value.
.LP
.PN PEXStartOCs
must be called prior to this.
.LP
\fIDO NOT\fP attempt to deallocate or free memory at the address returned
by this function.
.RE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXStartOCs ,
.PN PEXFinishOCs ,
.PN PEXCopyBytesToOC ,
.br
.PN PEXGetOCAddrMaxSize
.RE
.bp
.SH
PEXFinishOCs - Finish Encoded Output Commands
.XS
	PEXFinishOCs
.XE
.IN "PEXFinishOCs" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXFinishOCs\^(\^Display *\fIdisplay\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function should be called to complete the sending of
encoded output commands.  The display connection is unlocked.
.RE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXStartOCs ,
.PN PEXCopyBytesToOC ,
.PN PEXGetOCAddr
.RE
.bp
.SH
PEXSendOCs - Send Encoded Output Commands
.XS
	PEXSendOCs
.XE
.IN "PEXSendOCs" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
void PEXSendOCs\^(\^Display *\fIdisplay\fP\^, XID \fIresource_id\fP\^, PEXOCRequestType \fIreq_type\fP\^, int \fIfloat_format\fP\^, unsigned long \fIoc_count\fP\^, unsigned int \fIlength\fP\^, char *\fIencoded_ocs\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIresource_id\fP 1i
The resource identifier of the renderer or structure.
.IP \fIreq_type\fP 1i
The request type for the output command
.Pn ( PEXOCRender ,
.PN PEXOCStore ,
.PN PEXOCRenderSingle
or
.PN PEXOCStoreSingle ).
.IP \fIfloat_format\fP 1i
The floating point format of the encoded output commands
.Pn ( PEXIEEE_754_32 ,
.PN PEXDEC_F_Floating ,
.PN PEXIEEE_754_64 ,
.PN PEXDEC_D_Floating ).
.IP \fIoc_count\fP 1i
The number of encoded output commands.
.IP \fIlength\fP 1i
The length, in bytes, of the encoded output commands.
.IP \fIencoded_ocs\fP 1i
A pointer to the encoded output commands.
.RE
.SH
Returns
.RS
.LP
None
.RE
.SH
Description
.RS
.LP
This function sends encoded output commands to the specified PEX server display.
.LP
Sending output commands to a structure whose editing mode is
.PN PEXStructureReplace ,
is not really useful.  The behavior will be unpredictable
unless a request type of
.PN PEXOCStoreSingle
is used.  And, if the request type is
.PN PEXOCStoreSingle ,
each output command will simply replace the previous one sent.
Applications should ensure that the structure's editing mode is
.PN PEXStructureInsert ,
when sending multiple output commands.  If it is intended to replace multiple
elements, the application can delete those elements first, and then insert the
new ones.
.RE
.SH
Errors
.RS
.IP \fIBadPEXFloatingPointFormat\fP 1i
The specified floating point format is invalid or unsupported.
.IP \fIBadPEXOutputCommand\fP 1i
The output command contains an invalid value.
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.IP \fIBadPEXStructure\fP 1i
The specified structure resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXDecodeOCs ,
.PN PEXEncodeOCs
.RE
.bp
.SH
PEXStartOCs - Start Encoded Output Commands
.XS
	PEXStartOCs
.XE
.IN "PEXStartOCs" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
Status PEXStartOCs\^(\^Display *\fIdisplay\fP\^, XID \fIresource_id\fP\^, PEXOCRequestType \fIreq_type\fP\^, int \fIfloat_format\fP\^, int \fIoc_count\fP\^, int \fIword_count\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.IP \fIresource_id\fP 1i
The resource identifier of the renderer or structure.
.IP \fIreq_type\fP 1i
The request type for the output command
.Pn ( PEXOCRender ,
.PN PEXOCStore ,
.PN PEXOCRenderSingle
or
.PN PEXOCStoreSingle ).
.IP \fIfloat_format\fP 1i
The floating point format of the output command data
.Pn ( PEXIEEE_754_32 ,
.PN PEXDEC_F_Floating ,
.PN PEXIEEE_754_64 ,
.PN PEXDEC_D_Floating ).
.IP \fIoc_count\fP 1i
The number of output commands to be sent.
.IP \fIword_count\fP 1i
The number of four-byte words of data for the total size of the output commands.
.RE
.SH
Returns
.RS
.LP
Zero is unsuccessful, non-zero otherwise.
.RE
.SH
Description
.RS
.LP
This function locks the display.
Only
.PN PEXCopyBytesToOC
or
.PN PEXGetOCAddr
may be called
between pairs of
.PN PEXStartOCs
and
.PN PEXFinishOCs .
Do not call anything else that may lock the display as this will result in
deadlock.
.LP
The first output command is guaranteed to start on a four-byte boundary.
Output command data may be copied into the transport buffer by calling
.PN PEXCopyBytesToOC .
Output command data may be written directly by the application by calling
.PN PEXGetOCAddr
to get a pointer to memory in the transport buffer.
.LP
.PN PEXFinishOCs
must be called after all the data has been specified.
.LP
The application is responsible for writing valid protocol and the correct number
of words requested.
.LP
If the requested number of words is too large for the display connection
(each server has a maximum request size), the function will return
unsuccessfully.  If this occurs, and the number of output commands was
greater than one, the application should try specifying the data for a
single output command at a time.
If the size of a single output command is too large for the display connection,
the function will return unsuccessfully.
.RE
.SH
Errors
.RS
.IP \fIBadPEXFloatingPointFormat\fP 1i
The specified floating point format is invalid or unsupported.
.IP \fIBadPEXOutputCommand\fP 1i
The output command contains an invalid value.
.IP \fIBadPEXRenderer\fP 1i
The specified renderer resource identifier is invalid.
.IP \fIBadPEXStructure\fP 1i
The specified structure resource identifier is invalid.
.RE
.SH
See Also
.RS
.LP
.PN PEXFinishOCs ,
.PN PEXCopyBytesToOC ,
.PN PEXGetOCAddr
.RE
.bp
.SH
PEXGetOCAddrMaxSize - Macro to Obtain the Maximum Size for PEXGetOCAddr
.XS
	PEXGetOCAddrMaxSize
.XE
.IN "PEXGetOCAddrMaxSize" "" "@DEF@"
.SH
Synopsis
.RS
.FD 0
PEXGetOCAddrMaxSize\^(\^\fIdisplay\fP\^)
.FN
.RE
.SH
Arguments
.RS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful \fBXOpenDisplay\fP call.
.RE
.SH
Description
.RS
.LP
This macro evaluates to the maximum size for the length parameter of
.PN PEXGetOCAddr .
.RE
.SH
Errors
.RS
.IP None 1i
.RE
.SH
See Also
.RS
.LP
.PN PEXGetOCAddr
.RE
.bp
