1. Programming an Oracle Tuxedo ATMI Application Using C
  2. Managing Typed Buffers
  3. Allocating a Typed Buffer

2.2 Allocating a Typed Buffer

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 tpacall(3c) function, as follows: 

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

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

Table 2-2 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, X_COMMON, or RECORD typed buffer.

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

size Size of the buffer.

The Oracle 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 Oracle Tuxedo system uses the default associated with that typed buffer. If you specify a size, the Oracle 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 listing.

Listing Allocating a VIEW Typed Buffer 

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

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

Listing Allocating an FML Typed Buffer 

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

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

Listing 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 Oracle Tuxedo ATMI 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().

Listing Allocating a STRING Buffer 

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

The following listing shows how to allocate a RECORD typed buffer. In this example, the size is retrieved from Frneeded(). RECORD typed buffers requires the subtype argument.

Listing Allocating a RECORD Buffer 

struct RECORD *rec; /* pointer to an RECORD buffer structure */
. . . 
rec = (struct RECORD *)tpalloc("RECORD", "CUSTOMER", Frneeded("CUSTOMER"));
 . . .

See Also:

Parent topic: Managing Typed Buffers