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 28: Export 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_BLOCK_SIZE

    integer

    Specifies the block size in bytes used when returning data to the client.

    The minimum is 256 bytes. The default and maximum are 64330 bytes for Teradata Database V2R6.0 and later.

    Note: This value cannot be larger than the row size supported by the Teradata Database.

    TD_BUFFER_HEADER_SIZE

    integer

    Specifies the row header size allocated for each row in the data buffer returned by the GetBuffer function.

    The row header size must be greater than or equal to the value for the TD_BUFFER_LENGTH_SIZE attribute. The default row header size is 2. For more information on using the GetBuffer function, see “Export Data from a Teradata Database using GetBuffer” on page 30.

    TD_BUFFER_LENGTH_SIZE

    integer

    Specifies the row length size allocated for each row in the data buffer returned by the GetBuffer function.

    Valid row length size values are:

  • 4 = Each row’s length value to be returned as an integer value.
  • 2 = Each row’s length value to be returned as a short value. This is the default value.
  • 0 = Causes no row length value to be returned for each row.
  • For more information on using the GetBuffer function, see “Export Data from a Teradata Database using GetBuffer” on page 30.

    TD_BUFFER_MAX_SIZE

    integer

    Specifies the total maximum size for the data buffer returned by the GetBuffer function. The total maximum size of the data buffer must be large enough to hold at least one row of data including the row header, the actual row of data, and the buffer trailer. When exporting variable length data, the largest row size possible is used when calculating the minimum total maximum size of the data buffer. The default total maximum size of the data buffer is 64,260 (roughly 64k).

    For more information on using the GetBuffer function, see “Export Data from a Teradata Database using GetBuffer” on page 30.

    TD_BUFFER_TRAILER_SIZE

    integer

    Specifies the size of the buffer trailer allocated for the data buffer returned by the GetBuffer function. The default buffer trailer size is zero.

    For more information on using the GetBuffer function, see “Export Data from a Teradata Database using GetBuffer” on page 30.

    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.

    TD_DATA_ENCRYPTION

    varchar

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

    Valid values are:

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

    varchar

    Specifies the DATE data type for the Export driver job.

    Valid values are:

  • IntegerDate = Integer DATE data type. This is the default value.
  • ANSIDate = ANSI fixed-length CHAR(10) DATE data type.
  • TD_IGNORE_MAX_DECIMAL_DIGITS

    varchar

    Signals to the Export driver whether to ignore the TD_MAX_DECIMAL_DIGITS attribute and continue the job if the Large Decimal feature is not supported by the Teradata Database or Teradata CLIv2. This attribute has no impact when used with V2R6.2 or later Teradata Database.

    Valid values are:

  • No (or N) = The Export Driver will use the TD_MAX_DECIMAL_DIGITS attribute. The Export job terminates with an error if the TD_MAX_DECIMAL_DIGITS attribute is used and the Teradata Database level is V2R6.1 or older. This is the default value.
  • Yes (or Y) = The Export driver will ignore the TD_MAX_DECIMAL_DIGITS attribute if the Large Decimal feature is not supported by the Teradata CLIv2 or the Teradata Database. If the Large Decimal feature is not supported then the Export driver continues processing and returns an exit code of four instead of zero to indicate a warning when the TD_Evt_ExitCode event is queried.
  • 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 Security Administration. 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 Security Administration.

    TD_MAX_DECIMAL_DIGITS

    integer

    Specifies the maximum number of decimal digits (a value for the maximum precision) to be returned by the database. Valid values range from 1 to 38 inclusive. The default value is 18.

    TD_MAX_SESSIONS

    integer

    Specifies the maximum number of sessions to log on.

    This MaxSessions value must be greater than one. Specifying a value less than one terminates the job.

    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 or equal to the value of TD_MAX_INSTANCES.

    TD_MIN_SESSIONS

    integer

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

    The MinSessions value must be greater than one and less than or equal to the maximum number of Export driver sessions. Specifying a value less than one terminates the Export 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.

    When 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
  • For detailed information on the Notify feature, see “Export Operator” in Teradata Parallel Transporter Reference.

    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
  • Medium = Notification is provided for all the events except for:

  • File or OUTMODE Open
  • Statement Fetch Begin and End
  • High = Notification is to be provided for all events.

    TD_NOTIFY_METHOD

    varchar

    Specifies the method for reporting events.

    Valid 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 an 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

    Specifies 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 NotifyMethod is Exit.
  • 16 bytes, if NotifyMethod is Msg.
  • TD_OUTLIMIT

    integer

    Limits the number of rows that the Export driver exports.

    Default setting is:

  • No limit
  • Valid values are:

  • Any non-negative integer value
  • Note: In a multiple instance environment, this limit applies only to the particular instance on which it is set, and not to the overall job.

    For example, in an Export job with one master instance and one slave instance, if the out limit for both the master and the slave is set to 10 rows, then the master instance stops after exporting 10 rows and the slave instance stops after exporting 10 rows.

    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 Export 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_RETN_ACT_DATATYPE

    varchar

    Enables or disables returning the actual column data type.

    Valid vales are:

  • ‘Y[es]’ = the Export Driver returns the actual data type.
  • ‘N[o]’ = the Export Driver returns the CHAR data type for TIMESTAMP, TIME, and INTERVAL data types (default).
  • For a sample TPTAPI program to implement Return Actual Data Type, see “Sample Export_To_Load Program for Returning the Actual Data Type” on page 172.

    For conversion information, see Chapter 9: “Converting TIME, TIMESTAMP, and INTERVAL Data Types.”

    TD_SPOOLMODE

    varchar

    Specifies whether to use spool or not while running the current Export job.

    Valid values are:

  • “Spool” = Use Spool. This is the default setting.
  • “NoSpool” = Do not use Spool.
  • Note: This value is valid only if DBS supports NoSpool. If DBS does not support NoSpool, it uses Spool instead.

  • “NoSpoolOnly” = Do not use Spool in any case.
  • Note: If the DBS does not support NoSpool, it terminates the job with an error.

    TD_TASMFASTFAIL

    varchar

    Enables/disables TASM FastFail feature for Export 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 the Export 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, this value must be greater than zero.
  • Specifying a value of zero will disables the tenacity feature.
  • Specifying a value less than zero terminates the Export driver.
  • TD_TENACITY_SLEEP

    integer

    Specifies the number of minutes the Export driver pauses before attempting to log on when the maximum number of load and export operations are already running on the Teradata Database. The default is six minutes.

    This value must be greater than one. If you specify a value less than one, the Export 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 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 PauseAcquisition attribute means that the Export 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 on page 44 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, that file will be overwritten.

    TD_WORKINGDATABASE

    varchar

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