17.00 - Runtime Parameters - Parallel Data Pump

Teradata® Parallel Data Pump Reference

prodname
Parallel Data Pump
vrm_release
17.00
created_date
June 2020
category
Programming Reference
featnum
B035-3021-220K

The following table describes the runtime parameters used by Teradata TPump on mainframe-attached and workstation-attached systems.

Runtime Parameters/Systems 
Mainframe-attached Workstation-attached Description
BRIEF -b Specifies reduced print output, which limits Teradata TPump printout to the minimal information required to determine the success of the job:
  • Header information
  • Logon/logoff information
  • Candidate records
  • Insert, update, and delete results
  • Error table counts
BUFFERS = numberofbuffers -f numberofbuffers Sets the number of request buffers.

For Teradata Tools and Utilities 06.02.00 and earlier, the buffers runtime parameter can be set from 2 to a maximum of 10. The default value is 2.

Beginning with Teradata Tools and Utilities 06.02.00.01, the buffers runtime parameter can be set with a lower limit of 2 and no upper limit. The default value is 3.

The maximum number of request buffers that may be allocated is BUFFERS * session_count.

Beginning with Teradata Tools and Utilities 06.02.00.01, request buffers are a global resource, so buffers are assigned to any session as needed, and then returned to a free pool. At any point in time, the number of request buffers assigned to a session can vary from zero to BUFFERS * session_count.

Prior to Teradata Tools and Utilities 06.02.00.01, a request buffer was permanently owned by the session to which it was first assigned, and so could not be used by any other session. The maximum number of requests buffers that a session could own was determined by the value of BUFFERS.

CHARSET = charactersetname -c charactersetname Defines a character set for the Teradata TPump job.

The character set specification remains in effect for the entire Teradata TPump job, even if the database system resets, causing the Teradata TPump job to be restarted.

The character set specification does not remain in effect if the client system fails, or if the Teradata TPump job is canceled. In these cases, when the job is resubmitted, the job must use the same character set specification that was used on the initial job. If a different character set specification is used when such a job is resubmitted, the data loaded by the restarted job will not appear the same as the data loaded by the initial job.

If a character set specification is not entered, the default is whatever character set that is specified for the database when Teradata TPump was invoked.

See Overview for more information on supported character sets.

When using a UTF-16 client character set on the network or UTF-8 client character set on the mainframe, specify the client character set name by the runtime parameter (that is, “-c” on the network and “CHARSET” on the mainframe.)

Not Applicable -i scriptencoding Specifies the encoding form of the job script.

If this parameter is not specified and the client character set is UTF-16, Teradata TPump interprets the job script to UTF-16. If character-type data is also specified in the script, Teradata TPump converts the string literals and the corresponding field in the import data to the same character set before comparing or concatenating them. (String literals are specified with .APPLY…WHERE….; LAYOUT…CONTINUEIF….; FIELD…NULLIF…; FIELD…||…commands.)

Valid encoding options are:
  • UTF-8 or UTF8
  • UTF-16BE, or UTF16BE, or UTF16-BE
  • UTF-16LE, or UTF16LE, or UTF16-LE
  • UTF-16 or UTF16

The specified encoding character set applies to all script files included by the .RUN FILE commands.

The UTF-16 or UTF-8 Byte Order Mark (BOM) can be present or absent in the script file.

When UTF-16 BOM is present and 'UTF-16' is specified, Teradata TPump interprets the script according to the endianness indicated by the UTF-16 BOM. When the UTF-16 BOM is not present, Teradata TPump interprets the script according to the endianness indicated by the encoding option.

Not Applicable -u outputencoding Specifies the encoding form of the job output.

The parameter is valid only when the UTF-16 client character set is used.

If is not placed ahead of other runtime parameters when invoking the job, a warning message will be printed.

Available output encoding options are:
  • UTF-16BE, or UTF16BE, or UTF16-BE
  • UTF-16LE, or UTF16LE, or UTF16-LE
  • UTF-16 or UTF16

UTF-16BE instructs Teradata TPump to print the job output in big endian UTF-16 encoding scheme.

UTF-LE instructs Teradata TPump to print the job output in little endian UTF-16 encoding scheme. On big endian client systems, UTF-16 instructs Teradata TPump to print the job output in big endian UTF-16 encoding scheme. On little endian client systems, UTF-16 instructs Teradata TPump to print the job output in little endian UTF-16 encoding scheme.

UTF-16 BOM is printed as a part of job output for:
  • UTF-16BE, or UTF16-BE, or UTF16BE
  • UTF-16LE, or UTF16-LE, or UTF16LE
  • UTF-16 or UTF16 encoding
CONFIG =filename -C filename Specifies the configuration file for the Teradata TPump job.
The configuration file contains various configuration and tuning parameters for Teradata TPump. The particular usefulness of this file is for values that:
  • are site- or host-specific
  • script that developers may not necessarily be aware of
  • will likely change independently of Teradata TPump scripts.

The installation of Teradata TPump installs a default configuration file. On a UNIX system, it also installs a shell script that calls Teradata TPump using the default configuration file on the command line.

The format of the entries in the file is:

<keyword> <value>
  • Lines in the file that do not begin with a valid keyword are ignored.
  • Keywords are case-insensitive.
  • On UNIX systems, this file is called tdatpump.cfg and is expected to be found in the directory /usr/lib.
  • If the configuration file is not found, the program issues a warning message and uses the default values wherever necessary.

At this time, the only valid keyword is INMEMSORT, which is an integer data type containing the maximum number of bytes that can be sorted in memory. Teradata TPump recovery logic uses this value. This keyword can be modified to increase the amount of memory available for sorting.

If this keyword is not provided in the configuration file, or the configuration file is not provided, the default value for INMEMSORT is 6,000,000 for a UNIX system, 12,000,000 for z/OS, and 3,000,000 for Windows.

PRDICITY periodicityvalue -d periodicityvalue Specifies to change the periodicity value to control the rate at which statements are transferred to the database.

This parameter may be adjusted to improve the Teradata TPump workflow.

This parameter is in effect whenever the BEGIN LOAD command uses the RATE parameter to control the rate that statements are sent to the database. The default periodicity value is four 15-second periods per minute.

The periodicityvalue variable contains a value between 1 and 1500, which is the value range for the number of periods specified. The default value is 4.

Alternatively, periodicity can be changed by executing the TPumpMacro.UserUpdateSelect macro (provided with Teradata TPump Monitor SQL scripts) to update the monitor interface table while the job is running.

ERRLOG= error filename -e error filename Specifies to use the error logging function.

Using this parameter creates an alternate error log file to hold messages generated by Teradata TPump. Specifying an alternate file name produces a duplicate record of all Teradata TPump error messages. This allows any errors detected to be examined without having to go through the entire output stream.

The errorfilename defined is the location where error messages are copied. Directory identifiers can also be included in the file names defined.

On a UNIX system, the maximum length of the file name depends on the UNIX OS version currently in use.

On mainframe-attached client systems, the alternate file specification is limited to eight characters, and on z/OS, it must be to a DD name defined in the JCL.

  • If the file names defined already exist, they are overwritten. Otherwise, they are automatically created.
  • There is no default error log errorfilename specification.
MACROS -m Invocation option to tell Teradata TPump to keep macros that were created during the job run.

These macros can be used as predefined macros for the same job.

In order to use the same script after the -m parameter is used in the previous run, the EXECMACRO command must be added to the script.

To avoid duplicate macro names, a random number from 1 to 99 is used in each macro name when the NAME command is not used. The format in which the macro is created is as follows:

MYYYYMMDD_HHMMSS_LLLLL_DDD_SSS
where the following is true:
  • LLLLL is the low-order 5 digit of the logon sequence returned by the database from the .LOGON command.
  • DDD is the .DML sequence (ordinal) number. This value is not reset to one for successive loads (.BEGIN LOAD) in a single job, but continues to be incremented.
  • SSS is the SQL statement sequence (ordinal) number within the .DML group.
RTYTIMES=nn -t nn Specification for retry times.

The default for nn is 16. If nn = 0, retry times will be set back to 16.

The retry times options in the BEGIN LOAD can override this option for the requests/data sent between "BEGIN LOAD" and "END LOAD" pair.

'tpump command' -r tpump command Invocation option that can signify the start of a Teradata TPump job.
This is usually a RUN FILE command specifying the file containing the Teradata TPump job script because only one Teradata TPump command may be specified. For example, on a UNIX system:
 '.RUN FILE tpump.script;'
VERBOSE -v Specifies to turn on verbose mode.

Using this parameter provides additional statistical data in addition to the regular statistics.

In verbose mode, the input file from which statistics are normally displayed includes such additional statistics as the number of database requests sent, in addition to the normal number of requests.

In verbose mode, Teradata TPump displays each retry-able error when it occurred.

Not Applicable -y Specification for the data encryption option.

When specified, data and requests will be encrypted in all sessions used by the job.

The encryption options in the BEGIN LOAD or the PARTITION commands can override this option for the sessions associated with those commands

Not Applicable < infilename Name of the standard input file containing the Teradata TPump commands and Teradata SQL statements.

The infilename specification redirects the standard input (stdin). If an infilename specification is not entered, the default is stdin. If end-of-file is reached on the specified input file, the input does not refer to stdin and the job terminates.

On mainframe-attached client systems, the DD control statement must be used to specify the input file before Teradata TPump is invoked.
Not Applicable > outfilename Name of the standard output file for Teradata TPump messages.

The outfilename specification redirects the standard output (stdout). If an outfilename specification is not entered, the default is stdout,

If an outfilename specification is used to redirect stdout, do not use the same outfilename as an output or echo destination in the DISPLAY or ROUTE commands. Doing so produces incomplete results because of the conflicting write operations to the same file.
On mainframe-attached client systems, the DD control statement must be used to specify the output file before the utility is invoked.
RVERSION -V Display version number and stop.
  • See the invocation examples in INMOD and Notify Exit Routine Examples for sample JCL listings, commands, and output samples for the invocation options.
  • The first occurrence of the runtime parameter is in effect if the duplicates are specified. The remaining parameters are omitted with a warning message “UTY1624 Warning: Run time parameters detected and omitted”.