15.10 - Optional Attributes - Parallel Transporter

Teradata Parallel Transporter Application Programming Interface

prodname
Parallel Transporter
vrm_release
15.10
category
Programming Reference
featnum
B035-2516-035K

Optional Attributes

 

Table 16: Update Driver Optional Attributes 

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, once Teradata 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_AMP_CHECK

    varchar

    Specifies the update driver response to an offline AMP condition.

    Valid settings are:

  • Apply = Inhibits the Update driver job from entering or exiting the application phase when an AMP is offline. This is the default setting.
  • All = Pauses the Update driver job when an AMP is offline.
  • None = Allows the Update job to start, restart, or continue as long as no more than one AMP is offline in a cluster.
  • TD_BUFFER_SIZE

    integer

    Specifies the output buffer size, in kilobytes, used for sending Update parcels to the Teradata Database.

  • The output buffer size and the size of the rows in the Update table determine the maximum number of rows included in each parcel to the Teradata Database. A larger buffer size reduces processing overhead by including more data in each parcel.
  • The allowable values are 1 through 64. However, if you specify a value of 64, the actual buffer size is set to 64260.
  • The default buffer size is the maximum size allowed, which depends on the Teradata Database and CLI version. The maximum buffer size on V2R6.0 and later is 64K bytes.
  • If you specify a value less than one, the Update driver issues an error message and terminates the job. Any other value specified is evaluated when the connection to the Teradata 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 Teradata Database and queries its version.
  • If the supplied buffer size is too large, the Update driver scales it back to the maximum allowable size.
  • TD_CHARSET

    varchar

    Specifies the name or code of the character set to be used for the job. For the list of supported character sets, see “Extended Character Sets” in Teradata Parallel Transporter Reference. On mainframe‑attached z/OS platforms, only EBCDIC encoding is supported and is automatically selected.

    TD_DATA_ENCRYPTION

    varchar

    Activates full security encryption of SQL requests, responses and data.

    Valid values are:

  • Off = No encryption occurs. This setting is the default.
  • On = All SQL requests, responses, and data are encrypted.
  • TD_DATE_FORM

    varchar

    Specifies the DATE data type for the Update 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_DELETE_TASK

    varchar

    Specifies whether to perform the delete task to delete data from a single Teradata Database table. The Delete Task removes rows much more quickly than a DELETE SQL statement.

    You cannot use a delete task on a view.

    Valid settings for option are:

  • Yes (or Y) = Perform the delete task.
  • No (or N) = Do not perform the delete task.
  • Specifying any other value results in an error. The absence of any value is the same as a No value; the Update driver executes an IMPORT task, and none of the above rules apply.

    If the Delete Task attribute processing is enabled, other relevant optional attributes are:

  • TD_TENACITY_HOURS
  • TD_TENACITY_SLEEP
  • TD_AMP_CHECK
  • TD_DROPERRORTABLE

    varchar

    Directs the Update driver to drop the existing error tables at the end of the job. By default, the Update 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 Update job then the Teradata Database will return an error on those subsequent Update jobs, even if those error tables are empty.

    Valid values are:

  • Yes (‘Y’) = Drop the error tables if they are empty at the end of the job. This is the default setting.
  • No (‘N’) = Do not drop the existing error tables.
  • TD_DROPLOGTABLE

    varchar

    Directs the Update driver to drop the existing restart log table at the end of the job. By default, the Update 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 Update job then the results will be unpredictable. This unpredictability is due to the nature of the Teradata MultiLoad protocol, where the existence of a restart log table implies the job is a restart and the Update driver may attempt to restart the job at a point in time as dictated by the contents of the restart log table.

    The Update driver will try 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_DROPWORKTABLE

    varchar

    Directs the Update driver to drop the existing work tables at the end of the job. By default, the Update driver drops the work tables at the end of a job if the job completed successfully.

    If the work tables are not dropped at the end of a successfully‑terminating job and the same work table names are used in a subsequent Update job then the Teradata Database will return an error on those subsequent Update jobs.

    Valid values are:

  • Yes (‘Y’) = Drop the work tables if the job completes successfully. This is the default setting.
  • No (‘N’) = Do not drop the existing work tables.
  • TD_ERROR_LIMIT

    integer

    Specifies the maximum number of records that can be stored in an error table before the Update driver job is terminated. The ErrorLimit specification applies to each instance of the Update driver.

    The ErrorLimit specification must be greater than zero.

    Specifying an invalid value terminates the Update driver. By default, ErrorLimit value is unlimited.

    TD_ERROR_TABLE_1

    varchar

    Specifies the name of the first error table. This must be a new table name. You cannot use the name of an existing table unless you are restarting a paused Update driver job.

    ErrorTable1 contains records that were rejected during the acquisition phase of the Update 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 the Teradata FastLoad Reference.

    TD_ERROR_TABLE_2

    varchar

    Specifies the name of the second error table. This must be a new table name. You cannot use the name of an existing table unless you are restarting a paused Update driver job.

    ErrorTable2 contains records that violated the unique primary index constraint. This type of error occurs during the application phase of the Update 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 the Teradata FastLoad Reference.

    TD_LOGON_MECH

    varchar

    Specifies which logon mechanism is used. The job terminates if the attribute exceeds eight bytes.

    See your site security administrator for specific mechanism names. For a list of available mechanisms, see Security Administration.

    TD_LOGON_MECH_DATA

    varchar

    Passes additional logon mechanism data. See your site security administrator for specific mechanism data. For more information, see Security Administration.

    TD_LOGSQL

    varchar

    Directs the Update 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.
  • Note: When the driver’s trace is disabled, TD_LOGSQL has no effect.

    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 Update 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 Update driver sessions. Specifying a value less than 1 will cause the Update driver to terminate.

    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.sl for HP-UX platforms
  • libnotfyext.so for Linux and all other UNIX platforms
  • 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/DBS error
  • Exit
  • Delete Init
  • Delete Exit
  • Medium = Notification is provided for all the events except:
  • Checkpoint
  • Error Table 1
  • Error Table 2
  • AMPS offline
  • Import Begin
  • Import End
  • High = Notification is to be provided for all events.
  • For detailed information on the Notify feature, see “Update Operator” in Teradata Parallel Transporter Reference.

    TD_NOTIFY_METHOD

    varchar

    Specifies the method for reporting events.

    The methods are:

  • None = No event logging is done. This is the default.
  • 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, HP-UX, 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 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_PAUSE_ACQ

    varchar

    Specifies whether to pause the Update driver job after the acquisition phase or enter the application phase.

    Valid values are:

  • No (or N) = Do not pause. This is the default setting.
  • Yes (or Y) = Pause the Update driver job after the acquisition phase.
  • Specifying any other value terminates the job. The absence of any value causes the Update driver job to execute both the acquisition phase and the application phase without pausing. This distributes all rows sent to the Teradata 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 Update 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 the 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_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 detailed information on replication services components, see Teradata Replication Services Using Oracle GoldenGate and the SQL Data Definition Language.

    TD_TASMFASTFAIL

    varchar

    Enables/disables TASM FastFail feature for Update Driver.

    Valid values are:

  • ‘N[o]’ = tasmFastFailReq is set to 'N' (default)
  • ‘Y]es]’ = tasmFastFailReq is set to 'Y'
  • TD_TDP_ID

    varchar

    Specifies the name of the Teradata Database machine.

  • 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 Update driver attempts to log on when the maximum number of load and export operations are already running on the Teradata 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 terminates the Update driver.

    TD_TENACITY_SLEEP

    integer

    Specifies the number of minutes the Update driver pauses before retrying to log on when the maximum number of load and export operations are already running on the Teradata Database.

    The default is six minutes.

    The minutes value must be greater than zero. If you specify a value less than one, the Update driver responds with an error message and terminates the job.

    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

    Note: 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 (including the version number) in the log file 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 Update 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 Teradata Database during the acquisition phase to their final destination on the AMPs. Table 1 lists which drivers have the Pause Acquisition attribute.
  • TD_OPER_CLI = Activates the tracing function for CLIv2‑related activities (interaction with the Teradata 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 tracing messages. The default setting creates a new file name with the name of the driver followed by a time stamp.

    Note: If a file with the specified name already exists, the file is overwritten.

    TD_WORK_TABLE

    varchar

    Specifies the name of the work table. This must be a new table name. You cannot use an existing table name unless you are restarting a paused Update driver job.

    If the name is not supplied, it is created by the Update driver. The name of the created table is appended with an identifying ttname_WT, ensuring uniqueness.

    TD_WORKINGDATABASE

    varchar

    Specifies the name of the database used in a Teradata SQL DATABASE statement that the Update driver sends to the Teradata Database immediately after connecting the two SQL sessions. Use this attribute to specify a default database other than the logon database.