16.10 - Syntax - Parallel Transporter

Teradata Parallel Transporter Reference

Product
Parallel Transporter
Release Number
16.10
Published
July 2017
Content Type
Programming Reference
Publication ID
B035-2436-077K
Language
English (United States)

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 Option that 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 Option that 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 Option that 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 Option that specifies the Teradata PT job script file.
-h value

-h valueK

-h valueM

Option that 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 134, 217, 728 bytes.
  • -h valueK, where valueK specifies the shared memory size in kilobytes and can range from 1024 K (1, 048, 576 bytes) to 131, 072 K (134, 217, 728 bytes).
  • -h valueM, where valueM specifies the shared memory size in megabytes and can range from 1M (1, 048, 576 bytes) to 128 M (134, 217, 728 bytes).

For example,

tbuild -h 9700K

If the -h option is not specified, Teradata PT allocates 10,000,000 bytes of shared memory.

If the -h option is invalid, a warning message is issued, and Teradata PT allocates the default memory size of 10,000,000 bytes. The following message is issued if the -h option is invalid:

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

    Type: Warning

    Explanation: The memory size value is not numeric.

    Remedy: Correct the -h option value.

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:

  • Message: The -h memory size exceeds the maximum allowed value, and will be lowered to 134217728.

    Type: Warning

    Explanation: The memory size value exceeds the maximum allowed value.

    Remedy: Correct the -h option value.

  • Message: The -h memory size is less than the minimum allowed value, and will be raised to 1048576.

    Type: Warning

    Explanation: The memory size value is less than the minimum allowed value.

    Remedy: Correct the -h option value.

-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 Teradata Database.

-L jobLogDirectory Option that 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 Option that 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 Option that 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 Option that 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 Option that 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 can be any whole number greater than zero or equal to zero. The value zero prevents automatic job restart.

-s jobstepIdentifier Option that 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

Option that 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 Option that enables the trace option for all tasks.

If this option is not specified, trace is disabled.

-u jobVariables Option that 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 Option that 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

WherejobVariableFile is a file which contains the values for substitution:

UsrID = 'John Doe',
Pwd = 'ABC123'
-V Option that 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.

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