ATMI C Function Reference
|
 |
 |
|
 |
 |
buffer(3c)
Name
buffer()—Semantics of elements in tmtype_sw_t.
Synopsis
int /* Initialize a new data buffer */
_tminitbuf(char *ptr, long len)
int /* Reinitialize a reallocated data buffer */
_tmreinitbuf(char *ptr, long len)
int /* Uninitialize 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, long *flags )
long /* Multibyte code-set encoding conversion */
_tmconvmb(char *ibufp, long ilen, char *enc_name, char *obufp, long olen, long
*flags)
Description
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 ATMI 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 wildcard 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 subtypes. If all subtypes are to be treated the same for a given type, then the wildcard character, "*", can be used. Note that the function tptypes() can be used to determine a buffer's type and subtype if subtypes need to be distinguished. If some subset of the subtypes 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 subtype values should appear in the switch before the subtype designated with the wildcard. Thus, searching for types and subtypes in the switch is done from top to bottom, and the wildcard subtype entry accepts any "leftover" type matches.
dfltsize() is used when allocating or reallocating a buffer. The larger of dfltsize() and the routines' size parameter is used to create or reallocate 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.
Routine Specifics
The names of the functions specified below are template names used within the BEA Tuxedo ATMI 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 ATMI system calls a default function that takes the correct number and type of arguments, and returns a default value.
_tminitbuf
_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 subtypes, then the writer of _tminitbuf() can use tptypes() to determine the subtype.
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
_tmreinitbuf() behaves the same as _tminitbuf() except it is used to reinitialize a reallocated buffer. It is called from within tprealloc() after the buffer has been reallocated.
If no buffer reinitialization 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
_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
_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, preprocessing 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 preprocessing 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
_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
_tmpostrecv() is called after a buffer is received, and possibly decoded, in tpgetrply(), tpcall(), tprecv(), or in the BEA Tuxedo ATMI 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
_tmencdec() is used to encode/decode a buffer sent/received over a network to/from a machine having different data representations. The BEA Tuxedo ATMI 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 ATMI system where the encoded version of the data will be copied. The unencoded 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 ATMI 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 ATMI 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.
_tmroute
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
_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
_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
_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():
The flags returned in flags specify the results of _tmpresend2(). Possible values are:
_tmpresend2()was successful: the processed data is in the buffer referenced byiptr, and the return value contains the length of the data to be sent.
If TMUSEOPTR is returned, the processing done after messages are transmitted is different from the processing done by _tmpresend(): the iptr buffer remains unchanged and _tmpostsend() is not called. If TMUSEIPTR is returned, _tmpostsend() is called, as it is called for _tmpresend(). It is the responsibility of the caller to allocate and to free or cache the optr buffer.
There are several reasons why you may want to use this approach for a typed buffer:
- 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.
If no preprocessing needs to be performed on the data, and the amount of data specified by the caller is the same as the amount that should be sent, specify a NULL function pointer for _tmpresend2() in the buffer type switch. If _tmpresend2() is NULL, _tmpresend() is called by default.
Upon success, _tmpresend2() returns the amount of data to be sent or, if a larger buffer is needed, the negative absolute value of the desired buffer size. If the function fails, it returns -1, causing the caller of _tmpresend2() to also return failure, setting tperrno to TPESYSTEM.
_tmconvmb
_tmconvmb() is called after tmpostrecv() to convert multibyte data from a source encoding to a target encoding. The first argument to _tmconvmb(), ibufp, is a pointer to a stream of bytes—the multibyte data—to be converted. The second argument, ilen, is the number of bytes in ibufp. The third argument, enc_name, is one of the encoding names used in the processing. For an MBSTRING buffer, the third argument is the target encoding name; for an FML32 buffer, the third argument is the source encoding name.
_tmconvmb() receives a pointer, obufp, which is used to pass a pointer to a buffer into which the data in ibufp can be placed, after any required code-set encoding conversion is done. Use this pointer if you want to use a new buffer for the data converted by _tmconvmb() instead of modifying the input pointer. The fifth argument, olen, is the size of the obufp buffer. The flags argument is returned by _tmconvmb() to indicate the results of processing.
The size of the obufp buffer may not be large enough for successful post processing. If more space is required, _tmconvmb() returns the negative absolute value of the desired buffer size. All ilen bytes of the ibufp buffer are preserved. The calling routine then resizes the buffer and calls _tmconvmb() a second time.
If no code-set encoding conversion needs to be performed on the data, and the encoding name of the sending process is the same as the encoding name of the receiving process, specify a NULL function pointer. The default routine returns ilen and does not convert the buffer. If this function does not know how to convert the code-set encoding, it returns -1.
The value returned in flags specifies the result of _tmconvmb(). Possible values are:
_tmconvmb()was successful: the processed data is in the buffer referenced byibufp, and the return value contains the length of the converted data to be passed to the service.
Upon success, _tmconvmb() returns the amount of data buffer that had code-set encoding conversion or, if a larger buffer is needed, the negative absolute value of the desired buffer size. If the function fails, it returns -1, causing the caller of _tmconvmb() to also return failure, setting tperrno to TPESYSTEM.
See Also
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)
