17.00 - Record Formats - Access Module

Teradata® Tools and Utilities Access Module Programmer Guide

Product
Access Module
Release Number
17.00
Release Date
June 2020
Content Type
Programming Reference
Publication ID
B035-2424-220K
Language
English (United States)

Teradata Data Connector API passes the data format to the attached access module immediately following an open via request code pmiPIDMOptPutF_A. The access module might process the information as per its requirement, or it might return pmrcBadAttrName (Unrecognized attribute name) to Teradata Data Connector API.

The Data Connector API blocks data for write operations and unblocks data for read operations according to the record format specified by the client utility or the Teradata PT DataConnector operator. The tables below show the supported formats for client utilities and the formats for the Teradata PT DataConnector operator.

Formats are determined at runtime by users. When developing an Access Module, users need to know the following:
  • The format of the source data for both read and write operations
  • That the Access Module supports the required format and operation

Always provide user documentation that clearly identifies the record formats and operations (read, write, or both) that are supported by the Access Module.

The flow of data is as follows:
  • For read operations, data flows from the Access Module to the client Data Connector API. The Data Connector API expects, but does not require, the Access Module to provide data in blocks that are comprised of one or more logical records.
  • For write operations, data flows from the Data Connector API to the Access Module. The Data Connector API in most cases provides data in blocks that are comprised of one or more logical records.
Supported Record Formats for Client Utilities 
Format Description
pmIDFtext Records are separated by end-of-record markers.
pmIDFBin1 Data is prefixed by a two-byte record length. This length does not include the two bytes used for the record length.
pmIDFBin1Plus Same as pmIDFBin1 except that each record is followed by an end-of-record marker.
pmIDFBin2 Same as pmIDFBin1 except that the 2 bytes containing the record length include the 2 bytes used for the record length itself.
pmIDFBin2Plus Same as pmIDFBin2 except that each record is followed by an end-of-record marker.
pmIDFnone Data has no internal formatting. In this case, it is the responsibility of the utility to determine record separation, if any.
pmIDLROWFBin1

Data is prefixed by a 4-byte record length.

This length does not include the four bytes used for the record length.

pmIDLROWFBin1Plus

Data is prefixed by a 4-byte record length.

This length does not include the four bytes used for the record length.

Each record is followed by an end-of-record marker.

pmIDLROWFBin2

Data is prefixed by a 4-byte record length.

This length include the 4 bytes used for the record length.

pmIDLROWFBin2Plus

Data is prefixed by a 4-byte record length.

This length include the 4 bytes used for the record length.

Each record is followed by an end-of-record marker.

  • The mnemonics, such as pmIDFBin1, are used for clarity and reference purposes only.
  • End-of-record markers are one-byte fields containing either decimal '10' (x'0a') or decimal '13' (x'0d').
Record Formats for the Teradata PT DataConnector Operator 
Format Description
Binary Each record contains a 2-byte integer data length, n, followed by n bytes of data.
For example, a record containing 6 bytes of text “abcdef” is:
  • Hexadecimal: x'00 06 61 62 63 64 65 66'
  • Character: “...abcdef”
Text Each record contains character data only. Records are separated by an end-of-record (EOR) marker.
The EOR marker can be either a single-byte line feed (X'0A') or a double-byte carriage-return/line feed pair (X'0D0A'). The first EOR marker in the data marks the end of the first record; the end of each remaining record should also be marked with an EOR marker.
For example, a record containing the text “acdc” is:
  • Hexadecimal: x'61 63 64 63 0a'
  • Character: “abcd.”
Delimited Each record is in text format and contains fields (columns) separated by a delimiter character. This delimiter character is provided to the Teradata PT DataConnector operator through its TextDelimiter attribute. If not provided, the TextDelimiter attribute defaults to the pipe character ('|').
The final delimiter (of the last column) is optional.
For example, using a colon as the delimiter (TextDelimeter = ':'), a record with two fields, text “1234” and “abcd,” would be:
  • Hexadecimal: x'31 32 33 34 3a 61 62 63 64 3a 0a'
  • Character: “1234:abcd:.”
Formatted Each record is in a format traditionally known as FastLoad or Teradata format. The data is prefixed with the data length (as with binary format) and followed by an end-of-record (EOR) marker (as with text format).
For example, a record containing 6 bytes of text “abcdef” is:
  • Hexadecimal: x'00 06 61 62 63 64 65 66 0a'
  • Character: “...abcdef.”
Unformatted The data does not conform to any predefined format. The data is entirely described by the specified Teradata PT schema or utility LAYOUT command.

For example:

DEFINE SCHEMA PRODUCT_SOURCE_SCHEMA
DESCRIPTION 'PRODUCT INFORMATION SCHEMA'
(
 COL1 INTEGER,
 COL2 CHAR(4),
 COL3 VARCHAR(8)
);

A record containing the data: integer 20, char “1234,” varchar “abcde” is:

x'00 00 00 14 31 32 33 34 00 05 61 62 63 64 65'

where:

  • x'00 00 00 14' is the integer 20
  • x'31 32 33 34' is the fixed length character “1234”
  • x'00 05' is the length of the varchar field
  • x'61 62 63 64 65' is the varchar character data “abcde”
When using UNFORMATED formatting in MVS, ensure that the actual input data is consistent with the layout defined in the utility script. Discrepancies in the length of logical records could result in data corruption.

For more information about how to use Access Modules with Teradata PT, see Access Modules with the Teradata PT DataConnector Operator.