Allocating a Typed Buffer


	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 \| Programming \| Topic List \| Previous \| Next \| Contents

Programming a BEA Tuxedo Application Using C

Initially, no buffers are associated with a client process. Before a message can be sent, a client process must allocate a buffer of a supported type to carry a message. A typed buffer is allocated using the tpalloc(3c) function, as follows.

char*
tpalloc(char *type, char *subtype, long size)

The following table describes the arguments to the tpalloc() function.

tpalloc() Function Arguments

Argument
Description

type

Pointer to a valid typed buffer.

subtype

Pointer to the name of a subtype being specified (in the view description file) for a VIEW, VIEW32, or X_COMMON typed buffer.

In the cases where a subtype is not relevant, assign the NULL value to this argument.

size

Size of the buffer.

The BEA Tuxedo system automatically associates a default buffer size with all typed buffers except CARRAY, X_OCTET, and XML, which require that you specify a size, so that the end of the buffer can be identified.

For all typed buffers other than CARRAY, X_OCTET, and XML, if you specify a value of zero, the BEA Tuxedo system uses the default associated with that typed buffer. If you specify a size, the BEA Tuxedo system assigns the larger of the following two values: the specified size or the default size associated with that typed buffer.

The default size for all typed buffers other than STRING, CARRAY, X_OCTET, and XML is 1024 bytes. The default size for STRING typed buffers is 512 bytes. There is no default value for CARRAY, X_OCTET, and XML; for these typed buffers you must specify a size value greater than zero. If you do not specify a size, the argument defaults to 0. As a result, the tpalloc() function returns a NULL pointer and sets tperrno to TPEINVAL.

Argument	Description
type	Pointer to a valid typed buffer.
subtype	Pointer to the name of a subtype being specified (in the view description file) for a VIEW, VIEW32, or X_COMMON typed buffer. In the cases where a subtype is not relevant, assign the NULL value to this argument.
size	Size of the buffer. The BEA Tuxedo system automatically associates a default buffer size with all typed buffers except CARRAY, X_OCTET, and XML, which require that you specify a size, so that the end of the buffer can be identified. For all typed buffers other than CARRAY, X_OCTET, and XML, if you specify a value of zero, the BEA Tuxedo system uses the default associated with that typed buffer. If you specify a size, the BEA Tuxedo system assigns the larger of the following two values: the specified size or the default size associated with that typed buffer. The default size for all typed buffers other than STRING, CARRAY, X_OCTET, and XML is 1024 bytes. The default size for STRING typed buffers is 512 bytes. There is no default value for CARRAY, X_OCTET, and XML; for these typed buffers you must specify a size value greater than zero. If you do not specify a size, the argument defaults to 0. As a result, the tpalloc() function returns a NULL pointer and sets tperrno to TPEINVAL.

The VIEW, VIEW32, X_C_TYPE, and X_COMMON typed buffers require the subtype argument, as shown in the following example.

Allocating a VIEW Typed Buffer

struct aud *audv;  /* pointer to aud view structure */
 . . .
audv = (struct aud *) tpalloc("VIEW", "aud", sizeof(struct aud));
 . . .

The following example shows how to allocate an FML typed buffer. Note that a value of NULL is assigned to the subtype argument.

Allocating an FML Typed Buffer

FBFR *fbfr;  /* pointer to an FML buffer structure */
 . . .
fbfr = (FBFR *)tpalloc("FML", NULL, Fneeded(f, v))
 . . .

The following example shows how to allocate a CARRAY typed buffer, which requires that a size value be specified.

Allocating a CARRAY Typed Buffer

char *cptr;
long casize;
. . .
casize = 1024;
cptr = tpalloc("CARRAY", NULL, casize);
. . .

Upon success, the tpalloc() function returns a pointer of type char. For types other than STRING and CARRAY, you should cast the pointer to the proper C structure or FML pointer.

If the tpalloc() function encounters an error, it returns the NULL pointer. The following list provides examples of error conditions:

Failure to specify a size value for a CARRAY, X_OCTET, or XML typed buffer
Failure to specify a type (or subtype in the case of VIEW)
Specifying a type that is not known to the system
Failure to join the application before attempting allocation

For a complete list of error codes and explanations of them, refer to tpalloc(3c) in the BEA Tuxedo C Function Reference.

The following listing shows how to allocate a STRING typed buffer. In this example, the associated default size is used as the value of the size argument to tpalloc().

Allocating a STRING Buffer

char *cptr;
 . . .
cptr = tpalloc("STRING", NULL, 0);
. . .