buffer(3c)-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)
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.
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.
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 Event Broker 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 Event Broker performs the subscription's notification action. Otherwise, if _tmfilter returns 0, the Event Broker 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 Event Broker server to convert a buffer's data into a printable string, based on a format specification named fmt. The Event Broker 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.
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)