17.00 - Optional Attributes - 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
Attribute and Type Type Description
TD_ACCOUNT_ID varchar Specifies the account associated with the specified user name. When omitted, this attribute defaults to the account identifier of the immediate owner database.
TD_AUTORESTART varchar Teradata PT APT notifies the user application, upon database restarts, that the database crashed.
Valid values are:
  • Yes ('Y') = The user application receives a response about the database crash once the database is online (default).
  • No ('N') = The user application receives the CLI 220 error message when the database is down during the acquisition phase of Teradata PT API.
TD_APPENDERRORTABLE varchar Directs the Stream driver to use the existing error table that is specified in the TD_ERROR_TABLE attribute in this table. By default, if the specified error table already exists, the Stream driver terminates the job with an error message.
Set the TD_DROPERRORTABLE attribute in this table to align the Stream driver default setting.
Valid values are:
  • No ('N') = Do not use the existing error table. This is the default setting.
  • Yes ('Y') = Use the existing error table. The Stream driver will create the error table if the error table does not exist. If the error table does exist, the Stream driver will display the number of rows already in the error table in the trace file for the job if one exists (see TD_TRACE_LEVEL and TD_TRACE_OUTPUT in this table). If the structure of the existing error table is not compatible with the error table the Stream driver creates, the job terminates with an error message at the first attempt to insert or update to the existing error table.
TD_ARRAYSUPPORT varchar Specifies default array support option for all DMLGroups. Each DMLGroup can modify this setting through the AddArraSupport function defined in DML Group Class.
Valid values are:
  • On = Array support is turned on. This is the default setting if the database supports the array support functionality. An error will be returned and the job terminated if Array support is turned on for a database that does not support this feature.
  • Off = Array support is turned off. This is the default setting if the database does not support the array support functionality.
    Performance improves when Array Support is enabled.
TD_BUFFERS integer Specifies whether to increase the number of request buffers.

The range of values has a lower limit of two and no upper limit. The default value is three.

The maximum number of request buffers you can allocate is the number of buffers multiplied by the number of connected sessions.

Because request buffers are a global resource, 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 the maximum number you allocate.

TD_CHARSET varchar Specifies the name or code of the character set to be used for the job. On mainframe-attached z/OS platforms, only EBCDIC encoding is supported and is automatically selected.

For the list of supported character sets, see “Extended Character Sets” in Teradata® Parallel Transporter Reference, B035-2436.

TD_DATA_ENCRYPTION varchar Provides full security encryption of SQL requests, responses and data.
Valid values are:
  • Off = No encryption occurs. This is the default setting.
  • On = All SQL requests, responses, and data are encrypted.
TD_DATE_FORM varchar Specifies the DATE data type for the Stream driver job.
Valid settings are:
  • IntegerDate = Integer DATE data type. This is the default setting.
  • ANSIDate = ANSI fixed-length CHAR(10) DATE data type.
TD_DISCARDLARGEROW varchar Optional attribute that tells the operator whether or not to discard large rows (greater than 64K), because the operator is talking to a database that does not support large rows.
Valid values are:
  • Yes ('Y') = Tells the operator to discard the large rows and continue the job.
  • No ('N') = Tells the operator to terminate the job when a large row is encountered (default).
When you enable this option and the operator is talking to a database that does not support large rows, the operator will discard the large rows. The discarded rows will not be saved.
TD_DROPERRORTABLE varchar Directs the Stream driver to drop the existing error table at the end of the job. By default, the Stream driver drops the error table at the end of a job if the error table is empty.
Use the TD_APPENDERRORTABLE attribute in this table to direct the Stream driver to continue using the existing error table.
Valid values are:
  • Yes ('Y') = Drop the error table if it is empty at the end of the job. This is the default setting.
  • No ('N') = Do not drop the existing error table.
TD_DROPMACRO varchar Specifies whether to keep or drop the macro created during the current Stream job.
Valid values are:
  • Yes ('Y') = Drop the macro. This is the default setting.
  • No (N') = Keep the macro.
TD_ERROR_LIMIT integer Specifies the maximum number of records stored in one of the error tables before the Stream driver job is terminated. By default, the ErrorLimit value is unlimited.

The ErrorLimit specification must be greater than zero.

Specifying an invalid value terminates the Stream driver.

The ErrorLimit specification applies to each instance of the Stream driver.

TD_ERROR_TABLE varchar Specifies the name of the error table. ErrorTable must be a new table name. You cannot use the name of an existing table unless you are restarting a Stream driver job. If the name is not supplied, it will be created by the Stream driver.
The Error Table contains information concerning:
  • Data conversion errors
  • Constraint violations
  • Other error conditions

It is acceptable, and even good practice, to prefix the error table with a database name as a qualifier. This means that because the database may have a lot of PERM space, which space will not have to be increased for all databases with tables involved in the load.

If the database for the error table is not specified, the table is placed in the database associated with the user logon.

See “Reading TPump Error Tables” in Teradata® Parallel Data Pump Reference, B035-3021 for information on the error table format and the procedure to correct errors.

TD_LDILOADGROUP varchar Specifies the value of LDILoadGroup.

This value is required if TD_LDILOADJOB is set to Yes ('Y').

For example, AddAttribute(TD_LDILOADGROUP,(char*)"GRP1")

TD_LDILOADJOB varchar To enable/disable the Isolated Load feature for STREAM driver.
Valid values are:
  • No ('N') = No Isolated Load (default)
  • Yes ('Y') = Request Isolated Load.

    The stream driver will send "BEGIN ISOLATED LOADING ON <target table(s)> USING QUERY_BAND 'LDILoadGroup=<...>;' IN MULTIPLE SESSION;" request to the database if the target tables are qualified.

    The target table(s) has(have) to be created as "WITH ISOLATED LOADING FOR ALL".

    For example:

    CREATE TABLE testtable,
                 FALLBACK,
                 WITH ISOLATED LOADING FOR ALL
                 (COL1   VARCHAR(5),
                 COL2   VARCHAR(5));');
TD_LDIMACROTABLENAME varchar Specifies the LDI table names for the pre-defined macros. It is required when pre-defined macro(s) is used and TD_LDILOADJOB is set to Yes ('Y').

Use AddArrayAttribute to specify multiple LDI table names.

TD_LOGON_MECH varchar Specifies which logon mechanism is used.
  • See your site security administrator for specific mechanism names. For a list of available mechanisms, see Teradata Vantage™ - Advanced SQL Engine Security Administration, B035-1100.
  • The job terminates if the attribute exceeds eight bytes.
TD_LOGON_MECH_DATA varchar Passes along additional logon mechanism data.

See your site security administrator for specific mechanism data. For more information, see Teradata Vantage™ - Advanced SQL Engine Security Administration, B035-1100.

TD_LOGSQL varchar Directs the Stream driver to output the full Teradata SQL request in the trace output file with the driver’s trace is enabled. By default, when the driver’s trace is enabled, the Stream driver outputs the Teradata SQL request, up to 32 kilobytes, in the trace output file.
Valid values:
  • Yes ('Y') = Output the full Teradata SQL in the trace output file when the driver’s trace is enabled. The maximum length of the Teradata SQL is 1 megabyte.
  • No ('N') = Do not output the Teradata SQL in the trace output file.
When the driver’s trace is disabled, TD_LOGSQL has no effect.
TD_MACROCHARSET varchar Enables or disables the MacroCharSet feature. If the TD_MACROCHARSET attribute is enabled, you can specify the column MacroCharSet name for character columns. The value is discarded for other column types.
Valid values:
  • Yes ('Y') = Enables the MacroCharSet feature
  • No ('N') = Disables the MacroCharSet feature

For syntax to enable TD_MACROCHARSET and the AddColumn syntax when TD_MACROCHARSET is enabled, see Using the MacroCharSet Feature.

TD_MACRODATABASE varchar Specifies the database that contains any macros used by the Stream driver. The default macro database is the restart log table database.
TD_MAX_SESSIONS integer Specifies the maximum number of sessions to log on. The default is one session per available AMP. The maximum value cannot be more than the number of AMPS available.

The MaxSessions value must be greater than zero. Specifying a value less than one causes the job to terminate.

The MaxSessions value must be greater than or equal to the value of TD_MAX_INSTANCES.

TD_MIN_SESSIONS integer Specifies the minimum number of sessions required for the Stream driver job to continue. The default is one session.

The MinSessions value must be greater than zero and less than or equal to the maximum number of Stream driver sessions. Specifying a value less than one terminates the Stream driver.

TD_MSG_ENCODING TD_Encoding Specifies the encoding for the messages passed between Teradata PT and a Teradata PT application.
TD_NOTIFY_EXIT varchar Specifies the name of the user-defined notify exit routine with an entry point named _dynamn.
If no name is supplied, the following default names are used:
  • libnotfyext.dll for Windows
  • libnotfyext.dylibfor the Apple macOS platform
  • libnotfyext.so for all other UNIX platforms

For more information on the Notify feature, see “Stream Operator” in the Teradata® Parallel Transporter Reference, B035-2436.

TD_NOTIFY_LEVEL varchar Indicates the level at which certain events are reported.
The valid settings are:
  • Off = No notification of events will be provided. This is the default setting.
  • Low = Notification is provided for these events:

    Initialize

    CLIv2/Database error

    Exit

  • Medium = Notification is provided for all the events except:

    Checkpoint Begin

    Import Begin

    Import End

    Error Table

    Checkpoint End

    Interim Run Statistics

  • High = Notification is provided for all events.
TD_NOTIFY_METHOD varchar Indicates the method used for reporting events.
The methods are:
  • None = No event logging is done. This is the default method.
  • Msg = This method sends the events to a log.
  • Exit = This method sends the events to a user-defined notify exit routine and to the system log.

    On Windows, the events are sent to the EventLog that can be viewed using the Event Viewer. The messages are sent to the application log.

    On AIX, Linux, and Solaris platforms, the destination of the events is dependent upon the setting specified in the file called /etc/syslog.conf.

TD_NOTIFY_STRING varchar Provides a user-defined string to precede all messages sent to the system log. This string is also sent to the user-defined notify exit routine.
The maximum length of the string is:
  • 80 bytes, if NotifyMethod is Exit.
  • 16 bytes, if NotifyMethod is Msg.
TD_PACK integer Specifies the number of statements to pack into a multiple statement request. The maximum value is 2400. The default value is 20.
When the job is loading 1 or more deferred LOB columns, the largest possible pack factor is 4096 because the database can support up to 4096 spool files per request.
TD_PACKMAXIMUM varchar Triggers the Stream driver to dynamically determine the maximum possible pack factor for the current Stream job.
Valid values are:
  • No ('N') Use the default pack factor. This is the default setting.
  • Yes ('Y') Determine maximum possible pack factor.
TD_PAUSELDI varchar Specifies whether to pause the Isolated Load feature of STREAM driver.
Valid values are:
  • No ('N') = The Stream driver will send the "END ISOLATED LOADING FOR QUERY_BAND 'LDILoadGroup=<value>;';" to the database if "BEGIN ISOLATED LOADING ON <target table(s)> USING QUERY_BAND 'LDILoadGroup=<value>;' has been sent. This is the default value.
  • Yes ('Y') = The Stream driver will not send the "END ISOLATED LOADING FOR QUERY_BAND 'LDILoadGroup=<value>;';" to the database.
TD_PERIODICITY integer Specifies that the DML statements sent by the Stream driver to the database be as evenly distributed as possible over each one minute interval. The periodicity value sets the number of sub-intervals per minute. The TPT API user needs to pass the user's command for the Periodicity option to TPT API. TPT API needs to pass the user's command to the Stream driver.

For example, if the rate is 1600 and the periodicity is 10, then the maximum number of statements submitted is 160 (1600/10) every 6 (60/10) seconds.

Valid values are between 1 and 600. The default value is 4, that is, four 15-second intervals per minute. If the statement rate is unlimited, the periodicity value is ignored.

TD_QUERY_BAND_SESS_INFO varchar Provides a user-defined query band expression that is set for every SQL session connected by the Teradata PT driver. The following is an example of a valid query band expression:
a=1;b=2;c=3;d=4;

If the TD_QUERY_BAND_SESS_INFO is set, the following request will be sent by every SQL session connected by the Teradata PT Stream driver:

SET QUERY_BAND =’<User-Defined Query Band Expression>’ FOR SESSION;

Setting the TD_QUERY_BAND_SESS_INFO attribute in jobs running against non-supported versions of Teradata Database causes a non-fatal error. No error code is returned to the user during initiation and the job is allowed to proceed. The log table will not be dropped at the end of the job and the TD_Evt_ExitCode event returns a warning value of four instead of the normal success value of zero if queried. In this case, error information can be found in the trace file.

TD_RATE integer character Specifies the maximum number of DML statements per minute that the Stream driver can submit to the database per minute. The user needs to pass the command for the Rate option to TPT API. TPT API needs to pass the user command to the Stream driver.

When a job step contains multiple occurrences of the Stream driver with differing Rate values, Teradata PT automatically uses the lowest Rate value for all instances.

Values for TD_RATE must be one of the following:
  • Integer value > zero
  • Character string value 'unlimited' (default)

    'unlimited' tells the Stream driver to send as many DML statements to the database as the user specified.

TD_ROLENAME varchar Sets the current role for a session.
The valid values are:
  • EXTERNAL
  • NONE
  • NULL
  • ALL

The value for the attribute needs to be provided by the user, and the operator prepends the hard-coded string SET ROLE . For more information, see Teradata Vantage™ - SQL Data Definition Language Syntax and Examples, B035-1144.

  • TPTAPI and the operator do not validate the value for this attribute. The operator passes the value to the database as is. The database will validate the value. The operator will terminate the job with an error when the validation fails.
  • C style comments are allowed in the value and will be passed to the database.
  • ANSI-style comments are not supported in the value. The operator can terminate the job with a syntax error when the value contains an ANSI style comment.
  • A semicolon is not allowed in the value, because the operator allows only a single statement per request. The TPTAPI Application will Terminate, as Operator will terminate the job with an operator error when the value contains a semicolon.
TD_REPLICATION_OVERRIDE varchar Overrides the normal replication services controls. The default is not to send any SET SESSION OVERRIDE REPLICATION statement to the database.
The following valid values are not case-sensitive:
  • On = Sends SET SESSION OVERRIDE REPLICATION ON to the database. Normal replication services controls are overridden.
  • Off = Sends SET SESSION OVERRIDE REPLICATION OFF to the database. Normal replication services controls are not overridden.

For more information on replication services components, see Teradata Replication Services Using Oracle GoldenGate (B035-1152) and Teradata Vantage™ - SQL Data Definition Language Detailed Topics , B035-1184 .

TD_ROBUST varchar Specifies whether or not to use robust restart logic for recovery and restart operations.

In robust mode, one database row is written in the log restart table for every request issued. These rows are the request log. Because the database completely finishes or rolls back, a the request log always accurately reflects the completion status of an import.

Valid values are:
  • Yes ('Y') = Use robust restart logic. This is the default setting. In the robust mode, a number of partial checkpoint rows are written to the request log between checkpoints for each packed request. The rows are deleted each time a checkpoint is written.

    In Robust recovery mode, the Stream driver must next ascertain how much processing has been completed since the last logged checkpoint. This is accomplished by reading back a set of Partial Checkpoints from the database, sorting them and then reprocessing all transactions that were left incomplete when the job was interrupted.

  • No ('N') = Use simple restart logic. Restarts begin where the last checkpoint occurred in the job. Any processing completed after that checkpoint is redone, which could lead to duplicate rows being sent to the target table. This method eliminates the extra overhead of the additional database writes used in the robust mode, and it is adequate for DML statements that can be repeated without changing the results of the operation.

If you are not sure about using robust restart logic, it is always safe to set the robust attribute to Yes.

TD_TDP_ID varchar Specifies the name of the database system.
  • The dbcname can be up to 256 characters and can be a domain server name.
  • TDP stands for Teradata Director Program and is specified for mainframe z/OS platforms.
  • If you do not specify a value for the TD_TDP_ID attribute, the Stream driver uses the default TDPID established for the user by the system administrator.
TD_TENACITY_HOURS integer Specifies the number of hours that the Stream driver continues trying to log on when the maximum number of load and export operations are already running on the database.
  • The default value is four hours. To enable the tenacity feature, the hours value must be greater than zero.
  • Specifying a value of zero will disable the tenacity feature.
  • Specifying a value of less than zero will cause the Stream driver to terminate.
TD_TENACITY_SLEEP integer Specifies the number of minutes that the Stream driver pauses before retrying to log on when the maximum number of load and export operations are already running on the database.
  • The default is six minutes.
  • The minutes value must be greater than zero. If you specify a value less than one, the Stream driver responds with an error message and terminates the job.
TD_TIME_ZONE_SESS_INFO varchar Optional attribute that allows you to change the default time zone displacement for the duration of the operator's job session.

When you provide a value for this attribute, the operator will build the "SET TIME ZONE <timeZoneValue>;" SQL request.

The operator will send the request to the database on the main control and data SQL sessions after the sessions are connected

Following are some of the possible valid values:
  • LOCAL
  • USER
  • 'America Pacific'
  • TPTAPI and the operator do not validate the value for this attribute. The operator passes the value to the database as is. The database will validate the value. The operator will terminate the job with an error when the validation fails.
  • C style comments are allowed in the value and will be passed to the database.
  • ANSI-style comments are not supported in the value. The operator will terminate the job with a syntax error when the value contains an ANSI-style comment.
  • A semicolon is not allowed in the value, because the operator allows only a single statement in the "SET TIME ZONE SQL" request. The TPT API application will terminate, because the operator will terminate the job with an operator error when the value contains a semicolon.

For more information on the SET TIME ZONE SQL attribute, see Teradata Vantage™ - SQL Data Definition Language Syntax and Examples, B035-1144.

TD_TMSMSUPPORT varchar Enables and disables sending events to TMSM.
Valid values are:
  • Yes ('Y') = enables sending events to TMSM (default)
  • No ('N') = disables sending events to TMSM
TD_TRACE_LEVEL
The TraceLevel attribute is an internal diagnostic aid. Use only if instructed to by Teradata support. TD_OFF should always be specified.
integer Specifies the types of diagnostic messages written by each instance of the driver to an external log file. The diagnostic trace function provides more detailed information in the log file (including the version number) to aid in problem tracking and diagnosis.

Use the AddArray attribute method to specify the two types of tracing levels: driver tracing and infrastructure tracing.

TD_OFF is the default setting for both driver tracing and infrastructure tracing. No external log file is produced unless this default is changed. Specifying TD_OFF for both driver tracing and infrastructure tracing is the same as disabling tracing. If the TraceLevel is set to any value other than TD_OFF, an external log file is created for each instance of the driver.

The trace levels for driver tracing are:
  • TD_OFF = Disables driver tracing.
  • TD_OPER = Activates the tracing function for driver specific activities.The absence of any value for the PauseAcq attribute means that the Stream driver job will execute both the acquisition phase and the application phase without pausing. This will distribute all of the rows that were sent to the database during the acquisition phase to their final destination on the AMPs. Available Teradata Parallel Transporter Functions lists which drivers have the Pause Acquisition attribute.
  • TD_OPER_CLI = Activates the tracing function for CLIv2-related activities (interaction with the database).
  • TD_OPER_NOTIFY = Activates the tracing function for activities related to the Notify feature.
  • TD_OPER_OPCOMMON = Activates the tracing function for activities involving the opcommon library.
  • TD_OPER_ALL = Activates tracing for all of the above activities.

The trace levels for infrastructure tracing should only be used when you are directed to by Teradata support. TD_OFF, which disables infrastructure tracing, should always be specified.

TD_TRACE_OUTPUT varchar Specifies the name of the external file to use for tracing messages.

The default setting creates a new file name with the name of the driver followed by a time stamp.

If a file with the specified name already exists, then the file will be overwritten.
TD_TRANSFORM_GROUP varchar Sets the active transform for Complex Data Types (CDTs) with multiple transforms in the current session. The following CDTs have multiple transforms:
  • ST_GEOMETRY
  • XML
  • JSON
  • DATASET

When a value is provided for this attribute, the operator builds the "SET TRANSFORM GROUP FOR TYPE <tranformgrouValue>;" SQL request.

The operator sends the request to the database on the SQL session, after the session is complete.

  • TPTAPI and the operator do not validate the value for this attribute. The operator passes the value to the database as is. The database validates the value. The operator terminates the job with an error when the validation fails.
  • C style comments are allowed in the value and will be passed to the database.
  • ANSI-style comments are not supported in the value. The operator will terminate the job with a syntax error when the value contains an ANSI-style comment.
  • A semicolon is not allowed in the value, because the operator allows only a single statement per request. TPTAPI will terminate the job with an operator error when the value contains a semicolon.
TD_TREATDBSRESTARTASFATAL varchar Tells the operator whether or not to terminate the job when a database restart occurs.
Valid values are:
  • 'No' ('N') = The operator does not terminate if a database restart occurs (default). The database restart is treated as retryable.
  • 'Yes' ('Y') = The operator terminates if a database restart occurs.
TD_UNICODEPASSTHROUGH varchar Enables and disables the Unicode Pass Through feature for the Stream Driver.
Valid values are:
  • On = enable the Unicode Pass Through feature
  • Off = disable the Unicode Pass Through feature (default).
TD_WORKINGDATABASE varchar Specifies the name of the database used in a Teradata SQL DATABASE statement that the Stream driver sends to the database immediately after connecting the two SQL sessions. Use this attribute to specify a default database other than the logon database.