Syntax - Parallel Transporter

Teradata® Parallel Transporter Reference

Product
Parallel Transporter
Release Number
17.00
Published
November 2020
Language
English (United States)
Last Update
2022-02-03
dita:mapPath
ric1544831938741.ditamap
dita:ditavalPath
obe1474387269547.ditaval
dita:id
B035-2436
lifecycle
previous
Product Category
Teradata Tools and Utilities

The tbuild command takes as its primary argument the file containing the Teradata PT job script. You can specify tbuild options in any order.



where:

Syntax Element Description
-C Provides a more even distribution of data to consumer operators by instructing producer operators and their underlying data streams to ship data blocks to target consumer operators in a cyclical or round-robin manner.

By default, Teradata PT data streams send a block of data to the first ready/available consumer operator found in the producer's channel set array, only switching processes when the first consumer operator is too busy to accept more input. Using the -C option ensures that data are evenly distributed among consumer operators.

-d Enables debug trace functions for all tasks.

Using this option outputs trace messages and return codes of all internal functions invoked on behalf of tbuild. Internal error condition codes and trace messages are usually helpful for debugging issues occurring at the infrastructure level. However, when using this option along with the trace options provided by the operators, a full trace of the job can be obtained.

If this option is not specified, the debug trace function is disabled.

-e characterSet Specifies the character set encoding of the script. This option also ensures that files in big endian and little endian format are processed correctly regardless of the platform’s native encoding.

If not specified, the default character set is 7-bit ASCII compatible on UNIX OS, Windows and EBCDIC on z/OS.

-e characterSet is required if the job script is encoded in UTF-16.

All values are case insensitive and may be used with or without hyphens, that is, UTF-16, UTF16, utf16-be, and any similar notations are all valid. The following values are valid for characterSet:

  • UTF-16

    (Preferred notation) Endianess defaults to that of the client platform

  • UTF-8

    (Preferred notation) Specifying UTF-8 is optional. Specifying UTF-8 for a non-UTF-8 script generates an error. Endianess is irrelevant for UTF-8 encoding.

  • UTF-16LE

    (Preferred notation) Specifies a job script with little-endian encoding. If executed on a big endian platform, script encoding is converted to big-endian encoding before being executed. Not permitted as a client session character set name.

  • UTF-16BE

    (Preferred notation) Specifies a job script with big-endian encoding. If executed on a little-endian platform, script encoding is converted to little-endian encoding before being executed. Not permitted as a client character set name.

-f fileName Specifies the Teradata PT job script file.
-h value

-h valueK

-h valueM

Specifies the size of the shared memory used among the processes of a Teradata PT job.

Options include:

  • -h value, where value specifies the shared memory size in bytes and can range from 1,048,576 bytes to 4,294,967,295 bytes.
  • -h valueK, where valueK specifies the shared memory size in kilobytes and can range from 1024 K (1,048,576 bytes) to 4,194,304K (4,294,967,295 bytes).
  • -h valueM, where valueM specifies the shared memory size in megabytes and can range from 1M (1,048,576 bytes) to 4096M (4,294,967,295 bytes).

For example,

tbuild -h 24M

If the -h option is not specified, Teradata PT allocates shared memory according to the calculations outlined in Teradata® Parallel Transporter User Guide, B035-2445.

If the -h option is invalid, a warning message is issued, and allocates shared memory according to the calculations outlined in Teradata® Parallel Transporter User Guide, B035-2445.

The -h memory size is invalid, and will be ignored.

If the value of the -h option falls outside of the allowed range, a warning is issued and the size is adjusted to the appropriate minimum or maximum value before allocation. The following messages are issued if the -h option is out of the allowed range:
  • The -h memory size exceeds the maximum allowed value, and will be lowered to 4294967295.
  • The -h memory size is less than the minimum allowed value, and will be raised to 1048576.
-I ConfigurationFileName Specifies a desired configuration file when it's not possible to access the following files:
  • The global configuration file twbcfg.ini, located under TPT install directory
  • The local configuration file .twbcfg.ini, located under the user's home directory
The following global parameters can be defined in a user-specified configuration file:
  • GlobalAttributeFile
  • CheckpointDirectory
  • LogDirectory
These parameter definitions must be specified using the following syntax:
<parameter> = <single-quoted string>
For example, on a Unix system:
CheckpointDirectory='/opt/teradata/client/16.20/tbuild/checkpoint'
LogDirectory='/opt/teradata/client/16.20/tbuild/logs'
The -I option is only supported on Windows and Unix platforms.
-j jobName Optional job name, but strongly recommended so each job can have a unique checkpoint file. The default, if you do not enter a jobName, is the user name followed by a hyphen (“-”) and a generated Teradata PT job sequence number as follows:
<user name>-<job sequence number>
If multiple jobs are to be simultaneously run under the same logon session, specify a unique name for each job because each job must write its own checkpoint file. Without a unique name, concurrent jobs try to write to the same checkpoint file. This causes the jobs to fail.
-l latencyInterval Optional latency interval, specified in seconds, for flushing stale buffers. Latency interval is used exclusively with the Stream operator.

If no value is specified, data is read from the data stream until its buffer is full. Then all buffered records are written to the database.

-L jobLogDirectory Designates the location of the Teradata PT files created during job execution.

jobLogDirectory is the full path name of the directory in which the Teradata PT files are stored.

This option is not supported on z/OS.

-m statisticsInterval Specifies a time interval, in seconds, in which to collect statistical information about operators.

If this option is not specified, no statistical information is collected.

-n Specifies that the job can continue to run even if a job step returns an error.
  • If a job step receives a non-zero exit code, the job will continue.
  • If a step exits with a status of “failure” (exit code higher than 4), the subsequent steps will bypass the checkpoint file left by the previously failed step.

The required syntax is:

tbuild -f <scriptFile> -n

If this option is not specified, the job will stop if a step fails.

-o Writes the consumer private logs to standard output after a job completes.

If the -o option is not specified, logs will not be written to standard output.

-r checkpointDirectory Specifies that checkpoint files are to be stored in a directory called “CheckpointDirectory.”

If the -r option is not specified, then checkpoint files will be stored in the default checkpoint directory that is defined in the Teradata PT configuration file.

-R restartLimit Option that overrides the default value of five tries at automatic (job) restart. If you specify -R, enter a value or the system will reject the command and return an error. The restartLimit value must be between 0 and 512. The value zero prevents automatic job restart.
-s jobstepIdentifier Directs job execution to start at the specified job step.

Job steps are identified by a job step name in a script or by an implicit job step number that corresponds to the physical order of job steps in a script, such as 1, 2, 3.

The job will start at the specified job step, skipping over all job steps that come before it in the job script.

This option also removes checkpoint files:
  • used by any skipped steps
  • used by a previous execution of the same job
  • that would have been carried forward because of a failure or premature termination of one or more of the preceding steps

Since checkpoint files subject to these conditions are not valid for subsequent steps, the system will remove them before starting the step specified for the -s option.

The -s option formerly supported silent mode. Silent mode is no long available.
-S DD:ddname

-S dsName

-S sysoutClass

Enables tbuild to write both the private and public logs to a specified location for z/OS platforms. Choose from the following logDestination options:
  • To specify a ddname: tbuild -S logDestination

    where logDestination is DD:<ddname>, the target ddname for the log file.

  • To specify a dsname: tbuild -S logDestination

    where logDestination is <dsname>, the target dataset name for the logfile.

    A fully qualified dataset name is indicated by enclosing the name in single quote marks.
  • To specify a SYSOUT class: tbuild -S logDestination

    where logDestination is <sysout class>, the SYSOUT class for the log file.

If the -S option is not specified, tbuild does not write the private or public log to a specified location. However, tbuild still writes the logs to the dataset referenced by the JOBLOG DD statement.

-t Enables the trace option for all tasks.

If this option is not specified, trace is disabled.

-u jobVariables Allows you to specify job variable values on the command line.

Use this option to specify job variable assignments on the command line for the current execution of the job script.

There are multiple sources of job variable assignments within a job script, which are invoked in a priority order hierarchy. For more information, see “Using Job Variables” and related topics in the Teradata® Parallel Transporter User Guide, B035-2445.

In the following example, UsrID and Pwd are defined as job variables and they are used to supply runtime values for the UserName and UserPassword attributes:

ATTRIBUTES
(
   VARCHAR UserName = @UsrID,
   VARCHAR UserPassword = @Pwd
);

The following command supplies runtime values for these job variables:

tbuild -f scriptFileName -u "UsrID = 'John Doe', Pwd = 'ABC123' "
-v jobVariablesFile Allows job variable values to be specified in an external file.

This is similar to the -u option for assigning values at run time to job variables specified in a script, except that the variable values are stored in an external file that is referenced by tbuild through the following command:

tbuild -f scriptFileName -v jobVariablesFile

Where jobVariableFile is a file which contains the values for substitution:

UsrID = 'John Doe',
Pwd = 'ABC123'

If you are not executing the tbuild command in the directory where the job variables file is stored, jobVariablesFile must be a fully qualified filename. The job variables file may be saved in ASCII, UTF-8, or UTF-16, both with and without a UTF byte order mark.

-V Displays the Teradata PT version number without running a job.

Do not use with any other option. The option works only on UNIX and Windows platforms.

-w restartWaitPeriod Specifies a time interval, in seconds, between two restarts.

If this option is not specified, there will be no wait period between auto restarts.

The valid restart wait period value must be a positive integer between 1 and 86400 (seconds).

-W processTimeout

Specifies the number of seconds TPT will wait for a subprocess to spawn. The value can be an integer between 1 and 900. Consider using this option if jobs frequently fail with the following error:

Error: Timed out waiting for task initialization.

If the -W option is not specified, TPT will use the default of 120 seconds.

If the -W option is invalid (i.e. 0 or non-numeric), TPT will use the default value of 120 seconds The following message is issued if the -W option is invalid:

TPT_INFRA: TPT04215: Warning: The -W timeout value is invalid and will be ignored.

If the -W option is greater than the maximum allowed value of 900 seconds, TPT will use the maximum value of 900 seconds and display the following message:

TPT_INFRA: TPT04214: Warning: The -W timeout value is greater than the maximum allowed value and will be lowered to 900.

-z checkpointInterval Option that specifies a time interval, in seconds, between checkpoints.

If this option is not specified, there will be no interval checkpointing, unless a checkpoint interval is specified in the job script.

If a checkpoint interval is specified in both places, the -z option specification takes precedence.

The valid checkpoint interval values are between 0 and 86400 (seconds).