File Open - Access Module

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.