Skip Headers
Oracle® TimesTen In-Memory Database C Developer's Guide
Release 11.2.1

Part Number E13066-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

8 TimesTen Utility API

The TimesTen Utility Library C language functions documented in this chapter provide a programmable interface to some of the command line utilities documented in "Utilities" in Oracle TimesTen In-Memory Database Reference.

Applications that use this set of C language functions must include ttutillib.h and link with both the TimesTen Data Manager library (libtten on UNIX or ttdv1121.lib and tten1121.lib on Windows) and the TimesTen utility library (libttutil on UNIX and ttutil1121.lib on Windows platforms).

Important:

Applications must call the ttUtilAllocEnv C function before calling any other TimesTen utility library function. In addition, applications must call the ttUtilFreeEnv C function when it is done with the TimesTen utility library interface.

These functions are not supported with TimesTen Client or for Java applications. They are supported only for TimesTen Data Manager ODBC applications.

Return codes

Unless otherwise indicated, the utility functions return these codes as defined in ttutillib.h.

Code Description
TTUTIL_SUCCESS Returned upon success.
TTUTIL_ERROR Returned if an error occurs.
TTUTIL_WARNING Returned upon success, when a warning has been generated.
TTUTIL_INVALID_HANDLE Returned if an invalid utility library handle is specified.

Note:

The application must call the ttUtilGetError C function to retrieve all actual error or warning information.

ttBackup

Description

Creates either a full or an incremental backup copy of the data store specified by connStr. You can back up a data store either to a set of files or to a stream. You can restore the data store at a later time using either the ttRestore function or the ttRestore utility. If the data store is in use at the time of the backup, it must be in shared mode to successfully complete this operation.

For an overview of the TimesTen backup and restore facility, see "Migration, backup, and restoration of the data store" in the Oracle TimesTen In-Memory Database Operations Guide.

Required privilege

Requires ADMIN.

Syntax

ttBackup (ttUtilHandle handle, const char* connStr,
          ttBackUpType type, ttBooleanType atomic,
          const char* backupDir, const char* baseName,
          ttUtFileHandle stream)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
connStr const char* A NULL-terminated string specifying a connection string that describes the data store to be backed up.
type ttBackupType Specified the type of backup to be performed. Valid values are:

TT_BACKUP_FILE_FULL: Performs a full file backup to the backup path specified by the backupDir and baseName parameters. The resulting backup is not enabled for incremental backup.

TT_BACKUP_FILE_FULL_ENABLE: Performs a full file backup to the backup path specified by the backupDir and baseName parameters. The resulting backup is enabled for incremental backup.

TT_BACKUP_FILE_INCREMENTAL: Performs an incremental file backup to the backup path specified by the backupDir and baseName parameters, if that backup path contains an incremental-enabled backup of the data store. Otherwise, an error is returned.

TT_BACKUP_FILE_INCR_OR_FULL: Performs an incremental file backup to the backup path specified by the backupDir and baseName parameters of that backup path contains an incremental-enabled backup of the data store. Otherwise, it performs a full file backup of the data store and marks it incremental enabled.

TT_BACKUP_STREAM_FULL: Performs a stream backup to the stream specified by the stream parameter.

TT_BACKUP__INCREMENTAL_STOP: Does not perform a backup. Disables incremental backups for the backup path specified by the backupDir and baseName parameters. This prevents transaction log files from accumulating for an incremental backup.

atomic ttBooleanType Specifies the disposition of an existing backup with the same baseName and backupDir while the new backup is being created.

This parameter has an effect only on full file backups when there is an existing backup with the same baseName and backupDir. It is ignored for incremental backups because they augment, rather than replace, an existing backup. It is ignored for stream backups because they write to the given stream, ignoring the baseName and backupDir parameters.

TT_FALSE: The existing backup is destroyed before the new backup begins. If the new backup fails to complete, neither the new, incomplete, backup nor the existing backup can be used to restore the database. This option should be used only when the database is being backed up for the first time, when there is a another backup of the database that uses a different baseName or backupDir, or when the application can tolerate a window of time (typically tens of minutes long for large databases) during which no backup of the database exists.

TT_TRUE: The existing backup is destroyed only after the new backup has completed successfully. If the new backup fails to complete, the old backup is retained and can be used to restore the database. If there is an existing backup with the same baseName and backupDir then the use of this option ensures that there is no window of time during which neither the existing backup nor the new backup is available for restoring the database, and it ensures that the existing backup will be destroyed only if it has been successfully superseded by the new backup. However, it does require enough disk space for both the existing and new backups to reside in the backupDir at the same time.

backupDir const char* Specifies the backup directory for file backups. It is ignored for stream backups. Otherwise it must be non-NULL.

For TT_BACKUP_INCREMENTAL_STOP, it specifies the directory portion of the backup path that is to be disabled.

For TT_BACKUP_INCREMENTAL_STOP or a file backup, an error is returned if NULL is specified.

baseName const char* Specifies the file prefix for the backup files in the backup directory specified by the backupDir parameter for file backups.

It is ignored for stream backups.

If NULL is specified for this parameter, the file prefix for the backup files is the file name portion of the DataStore attribute in the ODBC definition of the data store.

For TT_BACKUP_INCREMENTAL_STOP, this parameter specifies the basename portion of the backup path that is to be disabled.

stream ttUtFileHandle For stream backups, this parameter specifies the stream to which the backup is to be written.

On UNIX, it is an integer file descriptor that can be written to by using write(2). Pass 1 to write the backup to stdout.

On Windows, it is a HANDLE that can be written to using WriteFile. Pass the result of GetStdHandle(STD_OUTPUT_HANDLE) to write the backup to the standard output.

This parameter is ignored for file backups.

The application can pass TTUTIL_INVALID_FILE_HANDLE for this parameter.


Example

To back up the data store for the payroll DSN into C:\backup:

ttUtilHandle  utilHandle;
int           rc;
rc = ttBackup (utilHandle,  "DSN=payroll", TT_BACKUP_FILE_FULL,
     TT_TRUE, "c:\\backup", NULL, TTUTIL_INVALID_FILE_HANDLE);

Upon successful backup, all files are created in the C:\backup directory.

Note

Each data store supports only eight incremental-enabled backups.

See also

ttRestore


ttDestroyDataStore

Description

Destroys a data store including all checkpoint files, transaction logs and daemon catalog entries corresponding to the data store specified by the connection string. It does not delete the DSN itself defined in the odbc.ini file on the supported UNIX platforms or in Windows registry on the supported Windows platforms.

Required privilege

Requires instance administrator.

Syntax

ttDestroyDataStore (ttUtilHandle handle, const char* connStr,
                    unsigned int timeout)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
connStr const char* A NULL-terminated string specifying the connection string that describes the data store to be destroyed. All data store attributes in this connection string, except DSN and DataStore attributes, are ignored.
timeout unsigned int Specifies the number of times to retry before returning to the caller. ttDestroyDataStore continually retries the destroy operation every 1 second until it is successful or the timeout is reached. This is useful in those situations where the destroy fails due to some temporary condition, such as when the data store is in use.

No retry is performed if this parameter is 0.


Example

To destroy a data store defined by the payroll DSN, consisting of files C:\dsns\payroll.ds0, C:\dsns\payroll.ds1, and several transaction log files C:\dsns\payroll.logn, call:

char            errBuff [256];
int             rc;
unsigned int    retCode;
ttUtilErrType   retType;
ttUtilHandle    utilHandle;
...
...
rc = ttDestroyDataStore (utilHandle, "DSN=payroll", 30);
if (rc == TTUTIL_SUCCESS)
   printf ("Datastore payroll successfully destroyed.\n");
else if (rc == TTUTIL_INVALID_HANDLE)
   printf ("TimesTen utility library handle is invalid.\n");
else
  while ((rc = ttUtilGetError (utilHandle, 0, &retCode,
           &retType, errBuff, sizeof (errBuff), NULL)) !=
           TTUTIL_NODATA)
    {
  ...
  ...
}

ttDestroyDataStoreForce

Description

Destroys a data store including all checkpoint files, transaction logs and daemon catalog entries corresponding to the data store specified by the connection string. It does not delete the DSN itself defined in the odbc.ini file on the supported UNIX platforms or in the Windows registry on supported Windows platforms.

Required privilege

Requires instance administrator.

Syntax

ttDestroyDataStoreForce (ttUtilHandle handle, const char* connstr,
                         unsigned int timeout)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
connStr const char* A NULL-terminated string specifying the connection string that describes the data store to be destroyed. All data store attributes in this connection string except DSN and DataStore attributes are ignored.
timeout unsigned int Specifies the number of seconds to retry before returning to the caller. The ttDestroyDataStoreForce utility continually retries the destroy operation every 1 second until it is successful or the timeout is reached. This is useful when the destroy fails due to some temporary condition, such as when the data store is in use.

No retry is performed if this parameter is 0.


Example

To destroy a data store defined by the payroll DSN, consisting of files C:\dsns\payroll.ds0, C:\dsns\payroll.ds1, and several transaction log files C:\dsns\payroll.logn, call:

char              errBuff [256];
int               rc;
unsigned int      retCode;
ttUtilErrType     retType;
ttUtilHandle      utilHandle;
...
...
rc = ttDestroyDataStoreForce (utilHandle, "DSN=payroll", 30);
if (rc == TTUTIL_SUCCESS)
  printf ("Datastore payroll successfully destroyed.\n");
else if (rc == TTUTIL_INVALID_HANDLE)
  printf ("TimesTen utility library handle is invalid.\n");
else
  while ((rc = ttUtilGetError (utilHandle, 0, &retCode,
                               &retType, errBuff, sizeof (errBuff), NULL)) !=
                               TTUTIL_NODATA)
    {
  ...
  ...
}

ttRamGrace

Description

Specifies the number of seconds the data store specified by the connection string is kept in RAM by TimesTen after the last application disconnects from the data store. TimesTen then unloads the data store. The grace period can be set or reset at any time but is only in effect if the RAM policy is TT_RAMPOL_INUSE.

Required privilege

Requires instance administrator.

Syntax

ttRamGrace (ttUtilHandle handle, const char* connStr, unsigned int seconds)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
connStr const char* A NULL-terminated string specifying a connection string that describes the data store for which the RAM Grace period is set.
seconds unsigned int Specifies the number of seconds TimesTen keeps the data store in RAM after the last application disconnects from the data store. TimesTen then unloads the data store.

Example

To set the RAM grace period of 10 seconds for the payroll DSN:

ttUtilHandle   utilHandle;
int            rc;
rc = ttRamGrace (utilHandle, "DSN=payroll", 10);

See also


ttRamLoad
ttRamPolicy
ttRamUnload

ttRamLoad

Description

Causes TimesTen to load the data store specified by the connection string into the system RAM. For a permanent data store, a call to ttRamLoad is valid only when RamPolicy is set to TT_RAMPOL_MANUAL. For a temporary data store, a call to ttRamLoad loads the data store into RAM.

Required privilege

Requires instance administrator.

Syntax

ttRamLoad (ttUtilHandle handle, const char* connStr)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
connStr const char* A NULL-terminated string specifying a connection string that describes the data store for which the data store is to be loaded into RAM.

Example

To load the data store for the payroll DSN:

ttUtilHandle   utilHandle;
int            rc;
rc = ttRamLoad (utilHandle, "DSN=payroll");

See also


ttRamGrace
ttRamPolicy
ttRamUnload

ttRamPolicy

Description

Defines the policy used to determine when TimesTen loads the data store into the system RAM for the data store specified by the connection string.

Required privilege

Requires instance administrator.

Syntax

ttRamPolicy (ttUtilHandle handle, const char* connStr,
             ttRamPolicyType policy)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
connStr const char* A NULL-terminated string specifying a connection string that describes the data store for which the RAM policy is to be set.
policy ttRamPolicyType Specifies the policy used to determine when TimesTen loads the data store into system RAM for the specified data store. Valid values are the following:
  • TT_RAMPOL_ALWAYS: Specifies that the data store should always remain in RAM.

  • TT_RAMPOL_MANUAL: Specifies that the data store can be loaded into RAM explicitly using either ttRamLoad C function or the ttAdmin -ramLoad command. Similarly, the data store can be unloaded from RAM explicitly by using ttRamUnload C function or using ttAdmin -ramUnload command.

  • TT_RAMPOL_INUSE: Specifies that the data store is to be loaded into RAM when an application wants to connect to the data store. This RAM policy may be further modified using the ttRamGrace C function or using the ttAdmin -ramGrace command.

If you do not explicitly set the RAM policy for the specified data store, the default RAM policy is TT_RAMPOL_INUSE.


Example

To set the RAM policy to manual for the payroll DSN:

ttUtilHandle   utilHandle;
int            rc;
rc = ttRamPolicy (utilHandle, "DSN=payroll", TT_RAMPOL_MANUAL);

Note

The policy cannot be set for a temporary data store.

See also


ttRamGrace
ttRamLoad
ttRamUnload

ttRamUnload

Description

Causes TimesTen to unload the data store specified by the connection string from the system RAM if the RamPolicy attribute is set to "manual". For a permanent data store, this call is valid only when RAM policy is set to TT_RAMPOL_MANUAL. For a temporary data store, a call to ttRamUnload always tries to unload the data store from RAM because RAM policy cannot be set for such a data store.

Required privilege

Requires instance administrator.

Syntax

ttRamUnload (ttUtilHandle handle, const char* connStr)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
connStr const char* A NULL-terminated string specifying a connection string for which the data store is to be unloaded from RAM.

Example

To unload the data store from RAM for the payroll DSN:

ttUtilHandle   utilHandle;
int            rc;
rc = ttRamUnload (utilHandle, "DSN=payroll");

Notes

When using this function with a temporary data store, TimesTen always attempts to unload the data store.

See also


ttRamGrace
ttRamLoad
ttRamPolicy

ttRepDuplicateEx

Description

Creates a replica of a remote data store on the local system. The process is initiated from the receiving local system. From there, a connection is made to the remote source data store to perform the duplicate operation.

Note:

If the data store does not use cache groups, the following items discussed below are not relevant: cacheuid and cachepwd data structure elements; TT_REPDUP_NOKEEPCG, TT_REPDUP_RECOVERINGNODE, and TT_REPDUP_DEFERCACHEUPDATE flag values.

Required privilege

Requires an instance administrator on the receiving local instance (where ttRepDuplicateEx is called) and a user with ADMIN privilege on the remote source data store. Create the internal user on the remote source store as necessary.

In addition, be aware of the following requirements to execute ttRepDuplicateEx:

Syntax

ttRepDuplicateEx (ttUtilHandle handle,
                  const char* destConnStr,
                  const char* srcDatastore,
                  const char* remoteHost,
                  ttRepDuplicateExArg* arg
                  )
typedef struct
{
      unsigned int size; /*set to size of(ttRepDuplicateExArg) */
      unsigned int flags;
      const char* uid;
      const char* pwd;
      const char* pwdcrypt;
      const char* cacheuid;
      const char* cachepwd;
      const char* localHost;
      int truncListLen;
      const char** truncList;
      int dropListLen;
      const char** dropList;
      int maxkbytesPerSec
      int remoteDaemonPort
      /*new struct elements can only be added here at the end */
} ttRepDuplicateExArg

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
destConnStr const char* A NULL-terminated string specifying the connection string for a local data store into which the replica of the remote data store is created.
srcDatastore const char* A NULL-terminated string specifying the remote source data store name. This name is the last component of the data store path name.
remoteHost const char* A NULL-terminated string specifying the TCP/IP host name of the system where the remote source data store is located.
arg ttRepDuplicateExArg* The address of the structure containing the desired ttRepDuplicateEx arguments. If NULL is passed in for arg or if the value of arg -> size is invalid, TimesTen returns error 12230 ("Invalid argument value") and TTUTIL_ERROR.

Struct elements

The ttRepDuplicateEx argument structure contains these elements:

Element Type Description
size unsigned int Must be set up to sizeof (ttRepDuplicateExArg).
flags unsigned int The bit-wise union of values chosen from the list in the table of flag values.
uid const char* The user name of a user on the remote source data store with ADMIN privileges. This user name is used to connect to the remote source data store to perform the duplicate operation.
pwd const char* The password associated with the user ID.
pwdcrypt const char* The encrypted password associated with the user ID.
cacheuid const char* Cache administration user ID.
cachepwd const char* Cache administration user password.
localHost const char* A NULL-terminated string specifying the TCP/IP host name of the local system. localHost is ignored if remoteRepStart is TT_FALSE. This explicitly identifies the local host. This parameter can be NULL. This is useful if the local host uses a nonstandard name, such as an IP address.
truncListLen int The number of elements in the truncList.
truncList const char** A list of non-replicated tables to truncate after duplicate.
dropListLen int The number of elements in dropList.
dropList const char** A list of non-replicated tables to drop after the duplicate operation.
maxkbytesPerSec int Setting maxkbytesPerSec to a nonzero value specifies that the duplicate operation should not put more than maxkbytesPerSec kilobytes of data per second onto the network. Setting maxkbytesPerSec to 0 or a negative number indicates that the duplicate operation should not attempt to limit its bandwidth.
remoteDaemonPort int Specifies the remote daemon port. Setting remoteDaemonPort to 0 results in the daemon port number for the target data store being set to the port number used for the daemon on the source data store.

This option cannot be used in duplicate operations for data stores with automatic port configuration.


The ttRepDuplicateExArg flags element is constructed from these values:

Value Description
TT_REPDUP_NOFLAGS No flags.
TT_REPDUP_COMPRESS Enables compression of the data transmitted over the network for the duplicate operation.
TT_REPDUP_REPSTART ttRepDuplicateEx sets the replication state (with respect to the local data store) in the remote data store to the start state before the remote data store is copied across the network. This ensures that all updates made after the duplicate operation are replicated from the remote data store to the newly created or restored local data store.
TT_REPDUP_RAMLOAD Keeps the data store in memory upon completion of the duplicate operation. It changes the RAM policy for the data store to "manual".
TT_REPDUP_DELXLA ttRepDuplicateEx removes all the XLA bookmarks as part of the duplicate operation.
TT_REPDUP_NOKEEPCG Do not preserve the cache group definitions. ttRepDuplicateEx converts all cache group tables into regular tables.

By default, cache group definitions are preserved.

TT_REPDUP_RECOVERINGNODE Specifies that ttRepDuplicateEx is being used to recover a failed node for a replication scheme that includes an AWT or autorefresh cache group. Do not specify TT_REPDUP_RECOVERINGNODE when rolling out a new or modified replication scheme to a node. If ttRepDuplicateEx cannot update metadata stored on the Oracle database and all incremental autorefresh cache groups are replicated, then updates to the metadata will be automatically deferred until the cache and replication agents are started.
TT_REPDUP_DEFERCACHEUPDATE Forces the deferral of changes to metadata stored on the Oracle database until the cache and replication agents are started and the agents can connect to the Oracle database. Using this option can cause a full autorefresh if some of the incremental cache groups are not replicated or if ttRepDuplicateEx is being used for rolling out a new or modified replication scheme to a node.

Example

To create a replica of a remote TimesTen DSN, remote_payroll, whose data store path name is C:\dsns\payroll to a local DSN, local_payroll, use the following:

ttUtilHandle utilHandle;
int rc;
ttRepDuplicateExArg arg;

memset(&arg, 0, sizeof(arg));
arg.size = sizeof(ttRepDuplicateExArg);
arg.flags = TT_REPDUP_REPSTART | TT_REPDUP_DELXLA;
arg.localHost = "mylocalhost";
arg.uid="myuid";
arg.pwd="mypwd";
rc=ttRepDuplicateEx(utilHandle,"DSN=local_payroll","payroll","remotehost", &arg);

See also

These built-in procedures are described in "Built-In Procedures" in Oracle TimesTen In-Memory Database Reference.


ttReplicationStatus
ttRepPolicySet
ttRepStop
ttRepSubscriberStateSet
ttRepSyncGet
ttRepSyncSet

ttRestore

Description

Restores a data store specified by the connection string from a backup that has been created using the ttBackup C function or ttBackup utility. If the data store already exists, ttRestore will not overwrite it.

For an overview of the TimesTen backup and restore facility, see "Migration, backup, and restoration of the data store" in Oracle TimesTen In-Memory Database Operations Guide.

Required privilege

Requires instance administrator.

Syntax

ttRestore (ttUtilHandle handle, const char* connStr, 
           ttRestoreType type, const char* backupDir, 
           const char* baseName, ttUtFileHandle stream,
           unsigned intflags)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
connStr const char* A NULL-terminated string specifying a connection string that describes the data store to be restored.
type ttRestoreType Indicates whether the data store is to be restored from a file or a stream backup. Valid values are the following:
  • TT_RESTORE_FILE: The data store is to be restored from a file backup located at the backup path specified by the backupDir and baseName parameters.

  • TT_RESTORE_STREAM: The data store is to be restored from a stream backup read from the given stream.

backupDir const char* For TT_RESTORE_FILE, specifies the directory where the backup files are stored.

For TT_RESTORE_STREAM, this parameter is ignored.

baseName const char* For TT_RESTORE_FILE, specifies the file prefix for the backup files in the backup directory specified by the backupDir parameter.

If NULL is specified, the file prefix for the backup files is the file name portion of the DataStore attribute of the data store ODBC definition.

For TT_RESTORE_STREAM, this parameter is ignored.

stream ttUtFileHandle For TT_RESTORE_STREAM, specifies the stream from which the backup is to be read.

On UNIX, it is an integer file descriptor that can be read from using read(2). Pass 0 to read the backup from stdin.

On Windows, it is a HANDLE that can be read from using ReadFile. Pass the result of GetStdHandle(STD_INPUT_HANDLE) to read from the standard input.

For TT_RESTORE_FILE, this parameter is ignored. The application can pass TTUTIL_INVALID_FILE_HANDLE for this parameter.

flags unsigned int Reserved for future use. Specify 0.

Example

To restore the data store for the payroll DSN from C:\backup, use:

ttUtilHandle   utilHandle;
int            rc;

rc = ttRestore (utilHandle, "DSN=payroll", TT_RESTORE_FILE,
              "c:\\backup", NULL, TTUTIL_INVALID_FILE_HANDLE, 0);

See also

ttBackup


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 must call ttUtilFreeEnv when it is done with 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* 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* 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

ttUtilAllocEnv returns these codes 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);

See also


ttUtilFreeEnv
ttUtilGetError
ttUtilGetErrorCount

ttUtilFreeEnv

Description

Frees memory associated with the TimesTen utility library handle.

An application must call ttUtilAllocEnv before calling any other TimesTen utility library function. In addition, an application must call ttUtilFreeEnv when it is done with the TimesTen utility library interface.

Required privilege

None.

Syntax

ttUtilFreeEnv (ttUtilHandle handle, char* errBuff,
               unsigned int buffLen, unsigned int* errLen)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
errBuff char* A user allocated buffer where error messages are to be 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* 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

ttUtilFreeEnv returns these codes as defined in ttutillib.h.

Code Description
TTUTIL_SUCCESS Returned upon success.
TTUTIL_INVALID_HANDLE Returned if an invalid utility library handle is specified.

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

To free a TimesTen utility library environment handle named utilHandle, do as follows.

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

rc = ttUtilFreeEnv (utilHandle, errBuff, sizeof(errBuff), NULL);

See also


ttUtilAllocEnv
ttUtilGetError
ttUtilGetErrorCount

ttUtilGetError

Description

Retrieves the errors and warnings generated by the last call to the TimesTen C utility library functions excluding ttUtilAllocEnv and ttUtilFreeEnv.

Required privilege

None.

Syntax

ttUtilGetError (ttUtilHandle handle, unsigned int errIndex,
                unsigned int* retCode, ttUtilErrType* retType,
                char* errbuff, unsigned int buffLen,
                unsigned int* errLen)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
errIndex unsigned int Indicates error or warning record to be retrieved from the TimesTen utility library error array. Valid values are:
  • 0: Retrieve the next record from the utility library error array.

  • 1...n: Retrieve the specified record from the utility library error array, where n is the error count returned by the ttUtilGetErrorCount call.

retCode unsigned int* Returns the TimesTen-specific error or warning codes as defined in tt_errCode.h.
retType ttUtilErrType* Indicates whether the returned message is an error or warning. Valid return values are:
  • TTUTIL_ERROR

  • TTUTIL_WARNING

errBuff char* A user allocated buffer where error messages (if any) are to be 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* A pointer to an unsigned integer where the actual length of the error message is returned. If it is NULL, TimesTen ignores this parameter.

Return codes

ttUtilGetError returns these codes as defined in ttutillib.h.

Code Description
TTUTIL_SUCCESS Returned upon success.
TTUTIL_INVALID_HANDLE Returned if an invalid utility library handle is specified.
TTUTIL_NODATA Returned if no error or warming information is retrieved.

Example

To retrieve all error or warning information after calling ttDestroyDataStore for the DSN named payroll:

char            errBuff[256];
int             rc;
unsigned int    retCode;
ttUtilErrType   retType;
ttUtilHandle    utilHandle;

rc = ttDestroyDataStore (utilHandle, "DSN=PAYROLL", 30);
if ((rc == TTUTIL_SUCCESS) 
  printf ("Datastore payroll successfully destroyed.\n");
else if (rc == TTUTIL_INVALID_HANDLE)
  printf ("TimesTen utility library handle is invalid.\n");
else
    while ((rc = ttUtilGetError (utilHandle, 0,
        &retCode, &retType, errBuff, sizeof (errBuff),
        NULL)) != TTUTIL_NODATA)
    {
...
...
}

Notes

Each of the TimesTen C functions can potentially generate multiple errors and warnings for a single call from an application. To retrieve all of these errors and warnings, the application must make repeated calls to ttUtilGetError until it returns TTUTIL_NODATA.

See also


ttUtilAllocEnv
ttUtilFreeEnv
ttUtilGetErrorCount

ttUtilGetErrorCount

Description

Retrieves the number of errors and warnings generated by the last call to the TimesTen C utility library functions excluding ttUtilAllocEnv and ttUtilFreeEnv. Each of these functions can potentially generate multiple errors and warnings for a single call from an application. To retrieve all of these errors and warnings, the application must make repeated calls to ttUtilGetError until it returns TTUTIL_NODATA.

Required privilege

None.

Syntax

ttUtilGetErrorCount (ttUtilHandle handle,
                     unsigned int* errCount)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
errCount unsigned int* Indicates the number of errors and warnings generated by the last call, excluding ttUtilAllocEnv and ttUtilFreeEnv, to the TimesTen utility library.

Return codes

The ttUtilGetErrorCount function returns these codes as defined in ttutillib.h.

Code Description
TTUTIL_SUCCESS Returned upon success.
TTUTIL_INVALID_HANDLE Returned if an invalid utility library handle is specified.

Example

To retrieve the error and warning count information after calling ttDestroyDataStore for the DSN named payroll:

int            rc;
unsigned int   errCount;
ttUtilHandle   utilHandle;

rc = ttDestroyDataStore (utilHandle, "DSN=payroll", 30);
if (rc == TTUTIL_SUCCESS) 
  printf ("Datastore payroll successfully destroyed.\n")

else if (rc == TTUTIL_INVALID_HANDLE) 
  printf ("TimesTen utility library handle is invalid.\n");
else
{
rc = ttUtilGetErrorCount(utilHandle, &errCount);
  ...
  ...
}

Notes

Each of the TimesTen utility library functions can potentially generate multiple errors and warnings for a single call from an application. To retrieve all of these errors and warnings, the application must make repeated calls to ttUtilGetError until it returns TTUTIL_NODATA.

See also


ttUtilAllocEnv
ttUtilFreeEnv
ttUtilGetError

ttXactIdRollback

Description

Rolls back the transaction indicated by the transaction ID that is specified. The intended user of ttXactIdRollback is the ttXactAdmin utility. However, programs that want to have a thread with the power to roll back the work of other threads must ensure that those threads call the ttXactIdGet built-in procedure before beginning work and put the results into a location known to the rolling back thread.

Required privilege

Requires ADMIN.

Syntax

ttXactIdRollback (ttUtilHandle handle, const char* connStr,
                  const char* xactId)

Parameters

Parameter Type Description
handle ttUtilHandle Specifies the TimesTen utility library environment handle allocated using ttUtilAllocEnv.
connStr const char** The connection string of the data store, which contains the transaction to be rolled back.
xactId const char* The transaction ID for the transaction to be rolled back.

Example

To roll back a transaction with the ID 3.4567, in the data store named payroll:

char            errBuff [256];
int             rc;
unsigned int    retCode;
ttUtilErrType   retType;
ttUtilHandle    utilHandle;
...
rc = ttXactIdRollback (utilHandle, "DSN=payroll", "3.4567");
if (rc == TTUTIL_SUCCESS)
  printf ("Transaction ID successfully rolled back.\n");
else if (rc == TTUTIL_INVALID_HANDLE)
  printf ("TimesTen utility library handle is invalid.\n");
else
  while ((rc = ttUtilGetError (utilHandle, 0, &retCode,
  &retType, errBuff, sizeof (errBuff), NULL)) != TTUTIL_NODATA)
   {
  ...
}