17.00 - Add Checkpoint and Restart - Parallel Transporter

Teradata® Parallel Transporter Application Programming Interface Programmer Guide

prodname
Parallel Transporter
vrm_release
17.00
created_date
June 2020
category
Programming Reference
featnum
B035-2516-220K

To prevent the loss of work done due to an execution error, Teradata PT has Checkpoint and Restart functions which establish locations in the data to return to if an error occurs. Both functions are part of the Connection object and can be called at any point after the connection has been initialized. The Checkpoint and Restart functions are available for the Load, Update, and Stream drivers. If an Export driver job fails, the job must start over from the beginning.

Set Checkpoints

The Checkpoint function takes two arguments which are used to return checkpoint data to the user application: a pointer to an unallocated data buffer (the checkpoint data storage area) and a pointer to a TD_Length variable that stores the length of the checkpoint data.

conn->Checkpoint(&buffer,&length);

The Checkpoint function returns the TD_END Method return value when the end of the Checkpoint method has been reached and a successful checkpoint has been taken. At this point, the Checkpoint function also passes checkpoint data to the user application. This is the only point at which valid checkpoint data is returned. For all other return values, no valid checkpoint data will be returned.

Once the Checkpoint function has successfully completed and has returned valid checkpoint data to the user application, the user application must make a copy of the checkpoint data and store it for later use. The character buffer used to pass the checkpoint data to the user application will be overwritten the next time the Checkpoint function is called and will be destroyed when the Connection object is deleted. It is recommended that an external file or table be used to store the checkpoint data to guard against the user application failing.

The user application determines at what interval to call the Checkpoint function. If the Checkpoint function returns an error then the data was not successfully checkpointed and no valid checkpoint data will be returned.

No checkpoint data is returned by the Checkpoint function for the Load driver and no valid checkpoint data is required by the Restart function for the Load driver. Still, it is highly recommended that user applications using the Load driver be prepared to store and retrieve valid checkpoint data when using the Checkpoint and Restart functions in case this feature is required in future releases.

Perform a Restart

Here are the main tasks to restarting a Teradata PT operation:

  1. Terminate the connection in which the error occurred.
  2. Resolve the issue which caused the error to occur.
  3. Create a new connection instance with the same parameters as the original connection which failed.
  4. Set the TD_RESTARTMODE attribute with a value of one.
  5. Call the Initiate function.
  6. Call the Restart function using the checkpoint data from the last successful checkpoint.

The Restart function takes two arguments: a pointer to a character buffer containing the latest checkpoint data and a pointer to a TD_Length variable containing the length of the checkpoint data.

conn->Restart(buffer,length);

The Restart function requires that valid checkpoint data be specified. The checkpoint data used to restart must be a copy of the checkpoint data returned by the last successful checkpoint in order to avoid losing any data. If invalid data is given to the Restart function, error code 21044 will be returned, indicating that invalid arguments have been specified.

If no successful checkpoint was taken prior to the job failing, the job cannot be restarted. In this case all error tables, log tables, and work tables must be dropped and the job must start over from the beginning.

Resubmit the Data

If the job failed during the acquisition phase, then resubmit rows starting from the row after the last successful checkpoint. The user application keeps track of when the last successful checkpoint was taken.