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

Part Number E13066-08
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 driver 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 ODBC applications using the direct driver.

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 database specified by connStr. You can back up a database either to a set of files or to a stream. You can restore the database at a later time using either the ttRestore function or the ttRestore utility. If the database 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 database" 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 database to be backed up.
type ttBackupType Specified the type of backup to be performed. Valid values are as follows:
  • 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 database. 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 database. Otherwise, it performs a full file backup of the database 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.

The following are valid values:

  • 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 database.

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

This example backs up the database 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 database supports only eight incremental-enabled backups.

See also

ttRestore


ttDestroyDataStore

Description

Destroys a database, including all checkpoint files, transaction logs and daemon catalog entries corresponding to the database 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 database to be destroyed. All attributes in this connection string, except the DSN and the DataStore attribute, are ignored.
timeout unsigned int Specifies the number of times to retry before returning to the caller. ttDestroyDataStore continually retries the destroy operation every 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 database is in use.

No retry is performed if this parameter value is 0.


Example

This example destroys a database 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.

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 database, including all checkpoint files, transaction logs and daemon catalog entries corresponding to the database 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 database to be destroyed. All attributes in this connection string, except the DSN and the DataStore attribute, 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 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 database is in use.

No retry is performed if this parameter value is 0.


Example

This example destroys a database 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.

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 database specified by the connection string is kept in RAM by TimesTen after the last application disconnects from the database. TimesTen then unloads the database. This 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 database for which the RAM grace period is set.
seconds unsigned int Specifies the number of seconds TimesTen keeps the database in RAM after the last application disconnects from the database. TimesTen then unloads the database.

Example

This example sets 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 database specified by the connection string into the system RAM. For a permanent database, a call to ttRamLoad is valid only when RamPolicy is set to TT_RAMPOL_MANUAL. For a temporary database, a call to ttRamLoad loads the database 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 database to be loaded into RAM.

Example

This example loads the database 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 database specified by the connection string into the system RAM.

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 database for which the RAM policy is to be set.
policy ttRamPolicyType Specifies the policy used to determine when TimesTen loads the specified database into system RAM. Valid values are the following:
  • TT_RAMPOL_ALWAYS: Specifies that the database should always remain in RAM.

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

  • TT_RAMPOL_INUSE: Specifies that the database is to be loaded into RAM when an application wants to connect to the database. 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 database, the default RAM policy is TT_RAMPOL_INUSE.


Example

This example sets 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 database.

See also


ttRamGrace
ttRamLoad
ttRamUnload

ttRamUnload

Description

Causes TimesTen to unload the database specified by the connection string from the system RAM if the TimesTen RAM policy is set to manual. (Refer to "ttRamPolicySet" in Oracle TimesTen In-Memory Database Reference for related information.) For a permanent database, this call is valid only when RAM policy is set to TT_RAMPOL_MANUAL. For a temporary database, a call to ttRamUnload always tries to unload the database from RAM because RAM policy cannot be set for such a database.

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 the database to be unloaded from RAM.

Example

This example unloads the database from RAM for the payroll DSN.

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

Notes

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

See also


ttRamGrace
ttRamLoad
ttRamPolicy

ttRepDuplicateEx

Description

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

Notes:

  • This utility includes features to recover from a site failure by creating a disaster recovery (DR) read-only subscriber as part of the active standby pair replication scheme. See "Using a disaster recovery subscriber in an active standby pair" in Oracle TimesTen In-Memory Database TimesTen to TimesTen Replication Guide for additional information.

  • If the database 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, TT_REPDUP_INITCACHEDR, and TT_REPDUP_DEFERCACHEUPDATE flag values.

Required privilege

Requires an instance administrator on the receiving local database (where ttRepDuplicateEx is called) and a user with ADMIN privilege on the remote source database. 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* srcDatabase,
                  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;
      int nThreads4initDR;
      int crsManaged;
      /*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 database into which the replica of the remote database is created.
srcDatabase const char* A null-terminated string specifying the remote source database name. This name is the last component of the database path name.
remoteHost const char* A null-terminated string specifying the TCP/IP host name of the system where the remote source database 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 database with ADMIN privileges. This user name is used to connect to the remote source database 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. This element is ignored if remoteRepStart is TT_FALSE. This explicitly identifies the local host. This parameter can be null, which 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 database being set to the port number used for the daemon on the source database.

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

nThreads4initDR int For the disaster recovery subscriber, this determines the number of threads used to initialize the Oracle database on the disaster recovery site.

After the TimesTen database is copied to the disaster recovery system, the Oracle database tables are truncated and the data from the TimesTen cache groups is copied to the Oracle database on the disaster recovery system.

Also see the TT_REPDUP_INITCACHEDR flag below.

crsManaged int For internal use. This should be set to 0 (default).

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 Directs ttRepDuplicateEx to set the replication state (with respect to the local database) in the remote database to the start state before the remote database is copied across the network. This ensures that all updates made after the duplicate operation are replicated from the remote database to the newly created or restored local database.
TT_REPDUP_RAMLOAD Keeps the database in memory upon completion of the duplicate operation. It changes the RAM policy for the database 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 incremental cache groups are not replicated or if ttRepDuplicateEx is being used for rolling out a new or modified replication scheme to a node.
TT_REPDUP_INITCACHEDR Initializes disaster recovery. You must also specify cacheuid and cachepwd in the data structure. Also see nThreads4initDR in the data structure.

Example

This example creates a replica of a remote TimesTen DSN, remote_payroll with the database path name C:\dsns\payroll, to a local DSN local_payroll.

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

The following 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 database specified by the connection string from a backup that has been created using the ttBackup C function or ttBackup utility. If the database already exists, ttRestore will not overwrite it.

For an overview of the TimesTen backup and restore facility, see "Migration, backup, and restoration of the database" 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 database to be restored.
type ttRestoreType Indicates whether the database is to be restored from a file or a stream backup. Valid values are the following:
  • TT_RESTORE_FILE: The database is to be restored from a file backup located at the backup path specified by the backupDir and baseName parameters.

  • TT_RESTORE_STREAM: The database 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 database 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

This example restores the database for the payroll DSN from C:\backup.

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

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);

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

This utility returns the following 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

This example frees a TimesTen utility library environment handle named utilHandle.

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 as follows:
  • 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. The following are valid return values:
  • 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

This utility returns the following 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

This example retrieves 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 utility returns the following 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

This example retrieves 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 thread that executes the rollback.

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 database, which contains the transaction to be rolled back.
xactId const char* The transaction ID for the transaction to be rolled back.

Example

This example rolls back a transaction with the ID 3.4567 in the database 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)
   {
  ...
}