Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo C Function Reference

buffer() - semantics of elements in tmtype_sw_t

int     /* Initialize a new data buffer */
_tminitbuf(char *ptr, long len)
int    /* Re-initialize a re-allocated data buffer */
_tmreinitbuf(char *ptr, long len)
int    /* Un-initialize a data buffer to be freed */
_tmuninitbuf(char *ptr, long len)
long   /* Process buffer before sending */
_tmpresend(char *ptr, long dlen, long mdlen)
void   /* Process buffer after sending */
_tmpostsend(char *ptr, long dlen, long mdlen)
long   /* Process buffer after receiving */
_tmpostrecv(char *ptr, long dlen, long mdlen)
long   /* Encode/decode a buffer to/from a transmission format */
_tmencdec(int op, char *encobj, long elen, char *obj, long olen)
int    /* Determine server group for routing based on data */  _tmroute(char *routing_name, char *service, char *data, long \  len, char *group)
int    /* Evaluate boolean expression on buffer's data */  _tmfilter(char *ptr, long dlen, char *expr, long exprlen)  
int    /* Extract buffer's data based on format string */  _tmformat(char *ptr, long dlen, char *fmt, char *result, long \  maxresult) 
long   /* Process buffer before sending, possibly generating copy */
_tmpresend2(char *iptr, long ilen, long mdlen, char *optr, long olen, int *flags )

This page describes the semantics of the elements and routines defined in the tmtype_sw_t structure. These descriptions are necessary for adding new buffer types to a process buffer type switch, tm_typesw. The switch elements are defined in typesw(5). The function names used in this entry are templates for the actual function names defined by the BEA Tuxedo system as well as by applications adding their own buffer types. The names map to the switch elements very simply: the template names are made by taking each function pointer's element name and prepending _tm (for example, the element initbuf has the function name _tminitbuf()).

The element type must be non-NULL and up to 8 characters in length. The element subtype can be NULL, a string of up to 16 characters, or the wild card character, "*". If type is not unique in the switch, then subtype must be used; the combination of type and subtype must uniquely identify an element in the switch.

A given type can have multiple sub-types. If all sub-types are to be treated the same for a given type, then the wild card character, "*", can be used. Note that the function tptypes() can be used to determine a buffer's type and sub-type if sub-types need to be distinguished. If some subset of the sub-types within a particular type are to be treated individually, and the rest are to be treated identically, then those which are to be singled out with specific sub-type values should appear in the switch before the sub-type designated with the wild card. Thus, searching for types and sub-types in the switch is done from top to bottom, and the wild card sub-type entry accepts any "leftover" type matches.

dfltsize() is used when allocating or re-allocating a buffer. The larger of dfltsize() and the routines' size parameter is used to create or re-allocate a buffer. For some types of structures, like a fixed sized C structure, the buffer size should equal the size of the structure. If dfltsize() is set to this value, then the caller may not need to specify the buffer's length to routines in which a buffer is passed. dfltsize() can be 0 or less; however, if tpalloc() or tprealloc() is called and its size parameter is also less than or equal to 0, then the routine will fail. It is not recommended to set dfltsize() to a value less than 0.

The names of the functions specified below are template names used within the BEA Tuxedo system. Any application adding new routines to the buffer type switch must use names that correspond to real functions, either provided by the application or library routines. If a NULL function pointer is stored in a buffer type switch entry, the BEA Tuxedo system calls a default function that takes the correct number and type of arguments, and returns a default value.

_tminitbuf() is called from within tpalloc() after a buffer has been allocated. It is passed a pointer to the new buffer, ptr(), along with its size so that the buffer can be initialized appropriately. len() is the larger of the length passed into tpalloc() and the default specified in dfltsize() in that type's switch entry. Note that ptr() will never be NULL due to the semantics of tpalloc() and tprealloc(). Upon successful return, ptr() is returned to the caller of tpalloc().

If a single switch entry is used to manipulate many sub-types, then the writer of _tminitbuf() can use tptypes() to determine the sub-type.

If no buffer initialization needs to be performed, specify a NULL function pointer.

Upon success, _tminitbuf() returns 1. If the function fails, it returns -1 causing tpalloc() to also return failure setting tperrno() to TPESYSTEM.

_tmreinitbuf() behaves the same as _tminitbuf() except it is used to re-initialize a re-allocated buffer. It is called from within tprealloc() after the buffer has been re-allocated.

If no buffer re-initialization needs to be performed, specify a NULL function pointer.

Upon success, _tmreinitbuf() returns 1. If the function fails, it returns -1 causing tprealloc() to also return failure setting tperrno() to TPESYSTEM.

_tmuninitbuf() is called by tpfree() before the data buffer is freed. _tmuninitbuf() is passed a pointer to the application portion of a data buffer, along with its size, and can be used to clean up any structures or state information associated with that buffer. ptr() will never be NULL due to tpfree()'s semantics. Note that _tmuninitbuf() should not free the buffer itself. The tpfree() function is called automatically for any FLD_PTR fields in the data buffer.

If no processing needs to be performed before freeing a buffer, specify a NULL function pointer.

Upon success, _tmuninitbuf() returns 1. If the function fails, it returns -1 causing tpfree() to print a log message.

_tmpresend() is called before a buffer is sent in tpcall(), tpacall(), tpconnect(), tpsend(), tpbroadcast(), tpnotify(), tpreturn(), or tpforward(). It is also called after _tmroute() but before _tmencdec(). If ptr() is non-NULL, pre-processing is performed on a buffer before it is sent. _tmpresend()'s first argument, ptr(), is the application data buffer passed into the send call. Its second argument, dlen(), is the data's length as passed into the send call. Its third argument, mdlen(), is the actual size of the buffer in which the data resides.

One important requirement on this function is that it ensures that when the function returns, the data pointed to by ptr() can be sent "as is." That is, since _tmencdec() is called only if the buffer is being sent to a dissimilar machine, _tmpresend() must ensure upon return that no element in ptr()s buffer is a pointer to data that is not contiguous to the buffer.

If no pre-processing needs to be performed on the data and the amount of data the caller specified is the same as the amount that should be sent, specify a NULL function pointer. The default routine returns dlen() and does nothing to the buffer.

If _tmpresend2() is not NULL, _tmpresend() is not called and _tmpresend2() is called in its place.

Upon success, _tmpresend() returns the amount of data to be sent. If the function fails, it returns -1 causing _tmpresend()'s caller to also return failure setting tperrno() to TPESYSTEM.

_tmpostsend() is called after a buffer is sent in tpcall(), tpbroadcast(), tpnotify(), tpacall(), tpconnect(), or tpsend(). This routine allows any post-processing to be performed on a buffer after it is sent and before the function returns. Because the buffer passed into the send call should not be different upon return, _tmpostsend() is called to repair a buffer changed by _tmpresend(). This function's first argument, ptr(), points to the data sent as a result of _tmpresend(). The data's length, as returned from _tmpresend(), is passed in as this function's second argument, dlen(). The third argument, mdlen(), is the actual size of the buffer in which the data resides. This routine is called only when ptr() is non-NULL.

If no post-processing needs to be performed, specify a NULL function pointer.

_tmpostrecv() is called after a buffer is received, and possibly decoded, in tpgetrply(), tpcall(), tprecv(), or in the BEA Tuxedo system's server abstraction, and before it is returned to the application. If ptr() is non-NULL, _tmpostrecv() allows post-processing to be performed on a buffer after it is received and before it is given to the application. Its first argument, ptr(), points to the data portion of the buffer received. Its second argument, dlen(), specifies the data's size coming in to _tmpostrecv(). The third argument, mdlen(), specifies the actual size of the buffer in which the data resides.

If _tmpostrecv() changes the data length in post-processing, it must return the data's new length. The length returned is passed up to the application in a manner dependent on the call used (for example, tpcall() sets the data length in one of its arguments for the caller to check upon return).

The buffer's size might not be large enough for post-processing to succeed. If more space is required, _tmpostrecv() returns the negative absolute value of the desired buffer size. The calling routine then resizes the buffer, and calls _tmpostrecv() a second time.

If no post-processing needs to be performed on the data and the amount of data received is the same as the amount that should be returned to the application, specify a NULL function pointer. The default routine returns dlen() and does nothing to the buffer.

On success, _tmpostrecv() returns the size of the data the application should be made aware of when the buffer is passed up from the corresponding receive call. If the function fails, it returns -1 causing _tmpostrecv()'s caller to return failure, setting tperrno() to TPESYSTEM.

_tmencdec() is used to encode/decode a buffer sent/received over a network to/from a machine having different data representations. The BEA Tuxedo system recommends the use of XDR; however, any encoding/decoding scheme can be used that obeys the semantics of this routine.

This function is called by tpcall(), tpacall(), tpbroadcast(), tpnotify(), tpconnect(), tpsend(), tpreturn(), or tpforward() to encode the caller's buffer only when it is being sent to an "unlike" machine. In these calls, _tmencdec() is called after both _tmroute() and _tmpresend(), respectively. Recall from the description of _tmpresend() that the buffer passed into _tmencdec() contains no pointers to data that is not contiguous to the buffer.

On the receiving end, tprecv(), tpgetrply(), the receive half of tpcall() and the server abstraction all call _tmencdec() to decode a buffer after they have received it from an `unlike" machine but before calling _tmpostrecv().

_tmencdec()'s first argument, op(), specifies whether the function is encoding or decoding data. op() can be one of TMENCODE or TMDECODE.

When op() is TMENCODE, encobj() points to a buffer allocated by the BEA Tuxedo system where the encoded version of the data will be copied. The un-encoded data resides in obj(). That is, when op() is TMENCODE, _tmencdec() transforms obj() to its encoded format and places the result in encobj(). The size of the buffer pointed to by encobj() is specified by elen() and is at least four times the size of the buffer pointed to by obj() whose length is olen(). olen() is the length returned by _tmpresend. _tmencdec() returns the size of the encoded data in encobj() (that is, the amount of data to actually send). _tmencdec() should not free either of the buffers passed into the function.

When op() is TMDECODE, encobj() points to a buffer allocated by the BEA Tuxedo system where the encoded version of the data resides as read off a communication endpoint. The length of the buffer is elen(). obj() points to a buffer that is at least the same size as the buffer pointed to by encobj() into which the decoded data is copied. The length of obj() is olen(). As obj() is the buffer ultimately returned to the application, this buffer may be grown by the BEA Tuxedo system before calling _tmencdec() to ensure that it is large enough to hold the decoded data. _tmencdec() returns the size of the decoded data in obj(). After _tmencdec() returns, _tmpostrecv() is called with obj() passed as its first argument, _tmencdec()'s return value as its second, and olen() as its third. _tmencdec() should not free either of the buffers passed into the function.

_tmencdec() is called only when non-NULL data needs to be encoded or decoded.

If no encoding or decoding needs to be performed on the data even when dissimilar machines exist in the network, specify a NULL function pointer. The default routine returns either olen() (op() equals TMENCODE) or elen() (op() equals TMDECODE).

On success, _tmencdec() returns a non-negative length as described above. If the function fails, it returns -1 causing _tmencdec()'s caller to return failure, setting tperrno() to TPESYSTEM.

The default for message routing is to route a message to any available server group that offers the desired service. Each service entry in the UBBCONFIG file can specify the logical name of some routing criteria for the service using the ROUTING parameter. Multiple services can share the same routing criteria. In the case that a service has a routing criteria name specified, _tmroute() is used to determine the server group to which a message is sent based on data in the message. This mapping of data to server group is called "data-dependent routing." _tmroute() is called before a buffer is sent (and before _tmpresend() and _tmencdec() are called) in tpcall(), tpacall(), tpconnect(), and tpforward().

routing_name is the logical name of the routing criteria (as specified in the UBBCONFIG file) and is associated with every service that needs data dependent routing. service is the name of the service for which the request is being made. The parameter data points to the data that is being transmitted in the request and len is its length. Unlike the other routines described in these pages, _tmroute() is called even when ptr() is NULL. The group parameter is used to return the name of the group to which the request should be routed. This group name must match one of the group names listed in the UBBCONFIG file (and one that is active at the time the group is chosen). If the request can go to any available server providing the specified service, group should be set to the NULL string and the function should return 1.

If data dependent routing is not needed for the buffer type, specify a NULL function pointer. The default routine sets group to the NULL string and returns 1.

Upon success, _tmroute() returns 1. If the function fails, it returns -1 causing _tmroute()'s caller to also return failure; as a result, tperrno() is set to TPESYSTEM. If _tmroute() fails because a requested server or service is not available, tperrno() is set to TPENOENT.

If group is set to the name of an invalid server group, the function calling _tmroute() will return an error and set tperrno() to TPESYSTEM.

_tmfilter() is called by the EventBroker server to analyze the contents of a buffer posted by tppost(). An expression provided by the subscriber (tpsubscribe()) is evaluated with respect to the buffer's contents. If the expression is true, _tmfilter() returns 1 and the EventBroker performs the subscription's notification action. Otherwise, if _tmfilter() returns 0, the EventBroker does not consider this posting a "match" for the subscription.

If exprlen() is -1, expr() is interpreted as a null-terminated character string. Otherwise expr() is interpreted as exprlen bytes of binary data. An exprlen of 0 indicates no expression.

If filtering does not apply to this buffer type, specify a NULL function pointer. The default routine returns 1 if there is no expression or if expr() is an empty null-terminated string. Otherwise the default routine returns 0.

_tmformat() is called by the EventBroker server to convert a buffer's data into a printable string, based on a format specification named fmt. The EventBroker converts posted buffers to strings as input for userlog() or system() notification actions.

The output is stored as a character string in the memory location pointed to by result(). Up to maxresult() bytes are written in result(), including a terminating null character. If result() is not large enough, _tmformat() truncates its output. The output string is always null terminated.

On success, _tmformat() returns a non-negative integer. 1 means success, 2 means the output string is truncated. If the function fails, it returns -1 and stores an empty string in result().

If formatting does not apply to this buffer type, specify a NULL function pointer. The default routine succeeds and returns an empty string in result().

_tmpresend2() is called before a buffer is sent in tpcall(), tpacall(), tpconnect(), tpsend(), tpbroadcast(), tpnotify(), tpreturn(), and tpforward(). It is also called after _tmroute() but before _tmencdec(). If iptr is not NULL, preprocessing is performed on a buffer before the buffer is sent.

The first argument to _tmpresend2(), iptr, is the application data buffer passed into the send call. The second argument, ilen, is the length of the data as passed into the send call. The third argument, mdlen, is the actual size of the buffer in which the data resides.

Unlike _tmpresend(), _tmpresend2() receives a pointer, optr, which is used to pass a pointer to a buffer into which the data in iptr can be placed, after any required processing is done. Use this pointer if you want to use a new buffer for the data modified by _tmpresend2() instead of modifying the input buffer. The fifth argument, olen, is the size of the optr buffer. The sixth argument, flags, tells _tmpresend2() whether the buffer being processed is the parent buffer (the one being sent). The flags argument is returned by _tmpresend2() to indicate the results of processing.

The size of the optr buffer may not be large enough for successful postprocessing. If more space is required, _tmpresend2() returns the negative absolute value of the desired buffer size. All olen bytes of the optr buffer are preserved. The calling routine then resizes the buffer and calls _tmpresend2() a second time.

If no postprocessing needs to be performed on the data, and the amount of data received is the same as the amount that should be returned to the application, specify a NULL function pointer. The default routine returns ilen and does not modify the buffer.

The following is a valid flag on input to _tmpresend2():

[TMPARENT]

This is the parent buffer (the one being sent).

[TMUSEIPTR]

_tmpresend2() was successful: the processed data is in the buffer referenced by iptr, and the return value contains the length of the data to be sent.

[TMUSEOPTR]

_tmpresend2() was successful: the processed data is in the buffer referenced by optr, and the return value contains the length of the data to be sent.

• The buffer created by processing for transmission is larger than the maximum length allowed for the input buffer.

• Undoing the processing to prepare a buffer for transmission is so complicated that it is easier to copy the data to a different buffer.

The _tmpresend2() function ensures that when a function returns, the data in the buffer to be sent can be sent without further processing. Because _tmencdec() is called only if the buffer is being sent to a dissimilar machine, _tmpresend2() ensures, upon return, that all data is stored contiguously in the buffer to be sent.

tpacall(3c), tpalloc(3c), tpcall(3c), tpconnect(3c), tpdiscon(3c), tpfree(3c), tpgetrply(3c), tpgprio(3c), tprealloc(3c), tprecv(3c), tpsend(3c), tpsprio(3c), tptypes(3c), tuxtypes(5)