\& .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