7.7 Calling environment functions

Environment functions are routines the exit can call to retrieve context information from Extract or Replicat. These functions are summarized below and each of the functions is explained in more detail in the remainder of the chapter. Syntax examples are included for C, TAL, and COBOL.

Note:

Each COBOL syntax section documents the ?CONSULT =EXTRACT (or =REPLICAT) compiler directive. Actually, this directive is declared only once no matter how many functions are called in the user exit. Make sure it points to the correct object type, which will be Extract for an Extract.

Function Summary

Function	Description
COMPRESS_RECORD | COMPRESS_RECORD2	Use when some of a target table's columns are present after mapping. Typically, use in conjunction with DECOMPRESS_RECORD.
DECOMPRESS_RECORD | DECOMPRESS_RECORD2	Makes compressed SQL updates easier to process and map.
FETCH_CURRENT_RECORD	Obtains the current Enscribe key-sequenced or entry-sequenced target record.
FETCH_CURRENT_RECORD_WITH_LOCK	Obtains the current Enscribe key-sequenced or entry-sequenced target record while locking the record for update.
GET_ALTKEY_INFO	Returns information on a file's alternate key.
GET_COLUMN_INDEX	Given a column name, returns the column index number.
GET_COLUMN_NAME	Given a column index, returns the column's name.
GET_ENV_VALUE	Returns the source or target file name in internal or external format.
GET_EXTRBA	Gets the current position in the extract trail.
GET_EXTSEQNO	Gets the sequence number of the current extract trail.
DATEDIFF	Retrieves the source or target file name.
GET_FILENAME_EXTERNAL	Returns the external format file name value in a string instead of fname.
GET_FOPEN_NUM	Gets the open number of the current file.
GET_NUM_COLUMNS	Returns the number of columns.
GET_RECORD | GET_RECORD2	Use for custom field conversions that may not be handled by Extract or Replicat.
GET_RECORD_LENGTH | GET_RECORD_LENGTH2	Retrieves the length of the target record.
GET_SYSKEY_LENGTH	Retrieves the SYSKEY length for the current record.
GET_TRANSACTION_IND	Supplies a data records position in a transaction, such as first, last, or middle.
GET_USER_TOKEN_VALUE	Allows user to retrieve the value of a user token.
GGS_EMSMESSAGE	Allows a user exit to write an EMS message.
GGS_REPORTMESSAGE	Allows a user exit to write to the report file.
SET_TARGET_RECORD2	Sets the values of a modified record.
SET_TARGET_FILENAME_EXTERNAL	Sets the file name target record using an external format.
SET_TARGET_RECORD_LENGTH2	Sets the length of a modified record.

The function RESULT

The RESULT value returned by each function indicates whether or not the function was successful. Possible values are listed below, but different functions may be limited in those they will use.

Return value	Description
EXIT_ENV_SOURCE_FILE	Indicates the 24-byte internal format source file name.
EXIT_ENV_SOURCE_FILE_EXT	Indicates the source file name in external format.
EXIT_ENV_TARGET_FILE	Indicates the target file name in internal format.
EXIT_ENV_TARGET_FILE_EXT	Indicates the target file name in external format.
EXIT_FN_RET_OK	Function succeeded.
EXIT_FN_RET_FETCH-ERROR	An error occurred when attempting to fetch a record.
EXIT_FN_RET_INVALID_COLUMN	A non-existent column was referred to in the function call.
EXIT_FN_RET_INVALID_CONTEXT	Function called at improper time.
EXIT_FN_RET_NOT_SUPPORTED	The request is not supported.
EXIT_FN_RET_INVALID_PARAM	An invalid parameter was passed to the function.

User exit libraries

Three copy libraries define error codes, constants, and structures that are passed to and from the user exits. C user exits should use XLIBC and TAL should use XLIBTAL. For COBOL the library is XLIBCOB.

The function prototypes for C user exits are defined in the library usrdecs. For TAL the library is usrdect. These should be included in the user exit routine.