ttUtilAllocEnv

Description

Allocates memory for a TimesTen utility library environment handle and initializes the TimesTen utility library interface for use by an application. An application must call ttUtilAllocEnv before calling any other TimesTen utility library function. In addition, an application should call ttUtilFreeEnv when it is done using the TimesTen utility library interface.

Required Privilege

None

Syntax

ttUtilAllocEnv (ttUtilHandle* handle_ptr, char* errBuff,
                unsigned int buffLen, unsigned int* errLen)

Parameters

Parameter	Type	Description
`handle_ptr`	`ttUtilHandle*`	Specifies a pointer to storage where the TimesTen utility library environment handle is returned.
`errBuff`	`char*`	This is a user allocated buffer where error messages (if any) are returned. The returned error message is a null-terminated string. If the length of the error message exceeds `buffLen`-1, it is truncated to `buffLen`-1. If this parameter is null, `buffLen` is ignored and TimesTen does not return error messages to the calling application.
`buffLen`	`unsigned int`	Specifies the size of the buffer `errBuff`. If this parameter is 0, TimesTen does not return error messages to the calling application.
`errLen`	`unsigned int*`	This is a pointer to an unsigned integer where the actual length of the error message is returned. If it is `NULL`, this parameter is ignored.

Return Codes

This utility returns the following code as defined in ttutillib.h.

Code	Description
`TTUTIL_SUCCESS`	Returned upon success.

Otherwise, it returns a TimesTen-specific error message as defined in tt_errCode.h and a corresponding error message in the buffer provided by the caller.

Example

This example allocates and initializes a TimesTen utility library environment handle with the name utilHandle.

char           errBuff [256];
int            rc;
ttUtilHandle   utilHandle;

rc = ttUtilAllocEnv (&utilHandle, errBuff, sizeof(errBuff), NULL);