8 TimesTen Utility API

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 "Copying, migrating, backing up and restoring a 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

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

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

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

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

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

Example

To load the data store for the payroll DSN:

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

See also

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

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

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

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

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.

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 data store as necessary.

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

• The operating system user name of the instance administrator on the receiving local instance must be the same as the operating system user name of the instance administrator on the remote source data store.

• When ttRepDuplicateEx is called, the uid and pwd Struct elements must specify the user name and password of the user with ADMIN privilege on the remote source data store. This user name is used to connect to the remove source data store to perform the duplicate operation.

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

Struct elements

The ttRepDuplicateEx argument structure contains these elements:

The ttRepDuplicateExArg flags element is constructed from these values:

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.

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 "Copying, migrating, backing up and restoring a 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

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

Return codes

ttUtilAllocEnv returns these codes as defined in ttutillib.h.

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

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

Return codes

ttUtilFreeEnv returns these codes as defined in ttutillib.h.

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:

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

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

See also

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

Return codes

ttUtilGetError returns these codes as defined in ttutillib.h.

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

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

Return codes

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

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

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

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)
   {
  ...
}