17.10 - File Open - Access Module

Teradata® Tools and Utilities Access Module Programmer Guide

Product
Access Module
Release Number
17.10
Release Date
June 2021
Content Type
Programming Reference
Publication ID
B035-2424-061K
Language
English (United States)

The File Open function opens a file for subsequent read and write operations.

The term file refers to a data source or destination on any sort of data storage device (such as magnetic tape, disk, CD-ROM, or another database) that an Access Module supports. The terms read and write refer to data moving from (read) and to (write) the data source/destination. The structure follows:

typedef struct _pmiOpen
{
 char         EyeCatcher[pmiMAX_EC_LEN];  /* Struct eyecatcher string */
 pmUInt32     StructLength;               /* Length of this structure */
 void        *PIData;         /* Access  module Internal Data Pointer */
 pmOpenMode_t OpenMode;                  /* provided to Access Module */
 pmUInt16     BlkHeaderLen;               /* defined by Access Module */
 pmUInt32     BlkSize;                    /* defined by Access Module */
                                                /* File Internal Data */
 void        *FIData;              /*(returned/used by Access Module) */
                      /* File (data stream) supplied to Access Module */
 pmUInt16     FileNameL;                               /* Name length */
  har         FileName[pmiMAX_DDNAME_LEN+1];                  /* Name */
} pmiOpen_t;

where the following is true:

Parameter Field Description
EyeCatcher input Structure description string, such as pmOpenParms.
StructLength input Total structure length, including the EyeCatcher string.
PIData input Value provided by the Access Module in response to a previous initialization request call. This value identifies the instance of the Access Module opening the file.
OpenMode input Indicates the intended use of the file to be opened. The following values are supported.
  • pmOpenModeR opens the file for read-only access.
  • pmOpenModeW opens the file for write-only access.
  • pmOpenModeRW opens the file for write-only access, appending to the end of the file.
BlkHeaderLen output Number of device-dependent bytes that prefix the user data in each block.
BlkSize output Size, in bytes, of the data blocks to be either read from or written to the file.
FIData output Handle/pointer to internal Access Module data. There are no restrictions on the FIData value, and the assigned value will be returned in a subsequent call to the Access Module.
FileNameL input Length of FileName parameter.
FileName input Name of the file to be opened.

Return Codes

The following File Open return codes supplement those listed in Typical Interface Return Codes.

Return Code Description
pmrcFNameTooLong File name specified by the FileName parameter is too long.
pmrcBadFormat Value specified by the Format parameter is invalid.

Usage Notes

Consider the following when specifying File Open parameters:
  • Requirements – A File Open function is required when the Reqtype field of the pmiCmdBlock_t structure is pmiPIDMOpOpen.
  • BlkSize Value – The returned BlkSize value determines client buffering requirements. This value represents the maximum block size that is sent to or received from an Access Module. On read operations, record lengths greater than the BlkSize specification are considered an error condition that overwrites client memory. On write operations, however, if the Teradata client utility needs to avoid spanned logical records, the Access Module typically receives blocks that are smaller than the BlkSize specification.
  • BlkHeaderLen Value – The returned BlkHeaderLen value indicates the number of bytes at the beginning of each block returned on read operations that are specific to an Access Module. If, for example, an Access Module needs to prefix each record with a four-byte block length, and that block length was present at the beginning of the returned read buffer, then the BlkHeaderLen is set to 4. If, however, the Access Module does not include that field in its returned data, then the BlkHeaderLen value is set to 0.