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 thee 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_BUFFER_SIZE integer Specifies the output buffer size, in kilobytes, used for sending Load parcels to the database.
  • The output buffer size and the size of the rows in the Load table determine the maximum number of rows included in each parcel to the database. A larger buffer size reduces processing overhead by including more data in each parcel.
  • Allowable values are 1 through 16384, but if you specify a value of 16384, the actual buffer size gets set to 16775552 bytes, which is less than the full 16MB.
  • The default buffer size is the maximum size allowed, which depends on the database and CLI version. The maximum allowed buffer size is usually 16384K bytes.
  • If you specify a value less than one, the Load driver issues an error message and terminates the job. Any other value specified is evaluated when the connection to the database is made. Because some Teradata Database versions support buffer sizes of 32K only, specifying a value of 64K would be invalid, but the driver does not know this until it connects to the database and queries its version.
  • If the supplied buffer size is too large, the Load driver scales it back to the maximum allowable size.
TD_CHARSET varchar Character Set is the name of the session character set used for the job. On mainframe-attached z/OS platforms, only EBCDIC encoding is supported and is automatically selected. For the list of supported session character sets, see “Extended Character Sets” in Teradata® Parallel Transporter Reference, B035-2436.

In a multi-instance environment the master and all the slave instances should have the same session character set. Also, the data for each instance should be in the same character set as the session character set. If the master instances does not use the TD_CHARSET attribute then the slave instances should not use the attribute. If the master instance specifies a different session character set than any of its slave instances then the Load, Export, and Update drivers will use the master instance’s session character set for the entire job. The Stream driver, however, will let each instance use its own session character set for the job.

Also, note that the session character set for all instances should not change if a restart occurs. If any instance specified a value for TD_CHARSET before the restart then that instance needs to specify the same value for TD_CHARSET when the connection is initiated again and then restarted.

TD_DATA_ENCRYPTION varchar Makes full security encryption of SQL requests, responses, and data available.
  • 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 Load driver job.
  • 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' or 'Y' = Tells the operator to discard the large rows and continue the job.
  • * 'No' or '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 Load driver to drop the existing error tables at the end of the job. By default, the Load driver drops the error tables at the end of a job if the error tables are empty.

If the error tables are not dropped at the end of a successfully terminating job and the same error table names are used in a subsequent Load job then the database returns an error on those subsequent Load jobs, even if those error tables are empty.

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_DROPLOGTABLE varchar Directs the Load driver to drop the existing restart log table at the end of the job. By default, the Load driver drops the restart log table at the end of a job only if the job completes successfully.

If the restart log table is not dropped at the completion of a successful job and the same restart log table name is provided in a subsequent Load job then the results will be unpredictable. This unpredictability is due to the nature of the Teradata FastLoad protocol, where the existence of a restart log table implies the job is a restart and the Load driver may attempt to restart the job at a point in time as dictated by the contents of the restart log table.

The Load driver tries to detect whether this situation has occurred and will attempt to terminate the job with a meaningful error message but this attempt is dependent upon the contents of the restart log table.

Valid values are:
  • Yes (‘Y’) = Drop the restart log table if the job completed successfully. This is the default setting.
  • No (‘N’) = Do not drop the existing restart log table.
TD_ERROR_LIMIT integer Specifies the maximum number of records stored in one of the error tables before the Load driver job is terminated. The ErrorLimit specification applies to each instance of the Load driver.
  • Specifying an invalid value causes the Load driver to terminate. By default, ErrorLimit value is unlimited.
  • The ErrorLimit specification must be greater than zero.
TD_ERROR_TABLE_1 varchar Specifies the name of the first error table. This must be a new table name. You cannot use a name that duplicates the name of an existing table unless you are restarting a paused Load driver job.
  • ErrorTable1 is for containing records rejected during the acquisition phase of the Load driver job because of:
    • Data conversion errors
    • Constraint violations
    • AMP configuration changes
  • The default name for ErrorTable1 is ttname_ET.

For more information on the error table format and the procedure to correct errors, see “FastLoad Errors” in Teradata® FastLoad Reference, B035-2411.

TD_ERROR_TABLE_2 varchar Specifies the name of the second error table. This must be a new table name. You cannot use a name that duplicates the name of an existing table unless you are restarting a paused Load driver job.
  • ErrorTable2 contains records that violated the unique primary index constraint.
  • These types of errors occur during the acquisition phase of the Load driver job.
  • The default name for ErrorTable2 is ttname_UV.

For more information on the error table format and the procedure to correct errors, see “FastLoad Errors” in Teradata® FastLoad Reference, B035-2411.

TD_LOGSQL varchar Directs the Load driver to output the full Teradata SQL request in the trace output file when the driver’s trace is enabled.
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. This is the default setting.
When the driver’s trace is disabled, TD_LOGSQL has no effect.
TD_LOGON_MECH varchar Specifies which logon mechanism to use.
  • 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 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_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 one. Specifying a value less than one terminates the job.
  • 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 Load 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 Load driver sessions. Specifying a value less than one terminates the Load 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.dylib for the Apple macOS platform
  • libnotfyext.so for Linux and all other UNIX platforms

For more information on the Notify feature, see “Load Operator” in 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 is 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 for Error Table 1 and Error Table 2.
  • High = Notification is provided for all events.
TD_NOTIFY_METHOD varchar Specifies the method 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.

    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 specified in the /etc/syslog.conf file.

TD_NOTIFY_STRING varchar Provides a user-defined string that precedes 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 the NotifyMethod is Exit.
  • 16 bytes, if the NotifyMethod is Msg.
TD_PAUSE_ACQ varchar Specifies whether to pause the Load job after the acquisition phase or enter the application phase.
Valid values are:
  • No (or N) for normal Load driver jobs, to distribute all of the rows sent to the database during the acquisition phase to their final destination on the AMPs. This is the default value.
  • Yes (or Y) to pause after the completion of the acquisition phase and skip the application phase. Specifying any other value terminates the job.
  • The absence of any value means that the Load driver job executes both the acquisition phase and the application phase without pausing. This distributes all of the rows sent to the database during the acquisition phase to their final destination on the AMPs.
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 Load 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_ROLENAME varchar Sets the current role for a session.
Valid values are:
  • EXTERNAL
  • NONE
  • NULL
  • ALL

The value for the attribute needs to be provided by the user, and the operator will prepend 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 a database 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_TASMFASTFAIL varchar IEnables/disables TASM FastFail feature for Load Driver.
Valid settings are:
  • = No notification of events is provided. This is the default setting.
  • 'Y]es]' = tasmFastFailReq is set to 'Y'
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 the value for the TdpId attribute, the driver uses the default TdpId established for the user by the system administrator.
TD_TENACITY_HOURS integer Specifies the number of hours that the Load 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 make the tenacity feature available, 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 terminates the Load driver.
TD_TENACITY_SLEEP integer Specifies the number of minutes the Load driver pauses before retrying to log on when the maximum number of Load or Export operations are already running on the database.
  • The minutes value must be greater than zero. If you specify a value less than one, the Load driver responds with an error message and terminates the job.
  • The default is six minutes.
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 auxiliary SQL sessions after the sessions are connected.

The operator does not send the request on the FastLoad protocol sessions, because the database does not allow the request to be sent on the FastLoad protocol sessions.

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:
  • ‘Y[es]’ = enables sending events to TMSM (default)
  • ‘N[o]’ = 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 Load 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 used for trace messages.

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

If a file with the specified name already exists, then the file is 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 Load Driver.
Valid values are:
  • On = enable the Unicode Pass Through feature.Off = disable the Unicode Pass Through feature (default).
TD_WILDCARDINSERT varchar Builds an INSERT statement from the table definition.
Valid values are:
  • No (or N) = No activity. This is the default value.
  • Yes (or Y) = Builds an INSERT statement.

If you set this attribute to Yes and a valid fully supported INSERT statement already exists, an error results.

To be valid, the table name must match the name of the table used in the TargetTable attribute and a semicolon must be the last non-space character in the supplied DML statement as follows:

INS[ERT] [INTO] <tablename>;
TD_WORKINGDATABASE varchar Specifies the name of the database used in a Teradata SQL DATABASE statement that the Load 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.