Record Formats - Access Module

Teradata Tools and Utilities Access Modules Programmer Guide
Product
Access Module
Release Number
15.10
Language
English (United States)
Last Update
2018-10-07
dita:id
B035-2424
lifecycle
previous
Product Category
Teradata Tools and Utilities

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. See Table 1 for the supported formats for client utilities. See Table 2 for 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.
    •  

    Table 1: 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.
  • 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').
    		•
     

    Table 2: 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.

    Note: 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 ('|').

    Note: 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 and

    x'61 62 63 64 65' is the varchar character data “abcde”

    Note: 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” on page 23.