Export Event Handlers

Kourier Integrator Online Help

Export Specification Event Handlers

For complex exports, Kourier allows a programmer access to the various steps needed to create the information included in an export dataset. There are two ways that a programmer can interface with the Kourier export engine: Export Subroutines or Event Handlers. Both of these approaches offer similar capabilities. Using Event Handlers have the following (minor) advantages:

You don’t need access to TCL to use Event Handlers.
You don’t need to know how to execute TCL commands like KT.BASIC and KT.CATALOG.

Export Subroutines have the following (minor) advantages:

The 6 major steps available to the programmer are all in one source code item.
Export Subroutines where the only way to access the export engine prior to release 4.3.

For information on using Export Subroutines click here.

Event Handlers can be used to generate some or all of the information in the export dataset. The programmer has access to the following events.

Event Handler

Option	Usage
Declarations	Use this event handler to define equated constants or to reference other included files.
Before Select	Called once and is used to modify the selection criteria of an export dynamically or to implement application based security.
Dataset Init	Called once and is used to initialize variables, setup named common variables, etc.
Dataset Header	Called once and is used to output the dataset’s heading information.
Dataset Detail	Called once for every record processed and allows for the generation of almost any output. If this timing is used, the programmer must call the subroutine KT.RMLIST to output data based upon the export's definition. Example: `CALL KT.RMLIST(EXPORTFMT$,OP$)`
Dataset Footer	Called once and is used to output the dataset’s footing information.

Accessible Variables

@ID

For U2 to SQL/File or REST Exports, this variable will contain the item-id of the record that is currently being processed in the DataSet Detail Event Handler. For all other Event Handlers this variable will contain and empty string. For ODBC to SQL/File or Flat-file Exports, this variable will always contain an empty string.

@RECORD

For U2 to SQL/File or REST Exports, this variable will contain the contents of the record that is currently being processed in the DataSet Detail Event Handler. For all other Event Handlers this variable will contain and empty string. For ODBC to SQL/File or Flat-file Exports, this variable will contain the contents of the row that is currently being processed in the DataSet Detail Event Handler. The data from each Source Column is copied into the attribute corresponding to the Line number of the field specified in the export. For all other Event Handlers this variable will contain and empty string.

EXPORTFMT$

This read-only variable contains an encoded representation of the Export Format (e.g. TAB, XML, etc.) that was specified in the export. This variable must be passed to the subroutine KT.RMLIST so it can serialize the data into the requested format. The KT.RMLIST subroutine is most commonly used in the DataSet Detail Event Handler.FIELD$

ERR.NO$

This variable can be used to raise an exception and terminate the processing of the export. It should contain the item-id of a message in either the KUST-MESSAGES or KORE-MESSAGES file. Best practice would be to raise an exception it in either BeforeSelect or DataSet Init Event Handler.

ERR.PARMS$

This variable may contain any parameters associated with the exception being raised in the ERR.NO$ variable. The list of parameters is multi-value delimited.

FILENAME$

For U2 to SQL/File or REST Exports, this read-only variable will contain the primary Export Data File name as defined in the export. For REST exports, if the Export Data File name contains a substitution expression, this variable will contain the fully processed substitution expression (e.g. if the value of a parameter named Location is FLA and the Export Data File field contains the string {%Location_DEALS} this variable will contain the string FLA_DEALS). For ODBC to SQL/File or Flat-file Exports, this read-only variable will contain the Source Table name specified in the export. If the Source Table name contains a substitution expression, this variable will contain the fully processed substitution expression.

OP$

In the DataSet Header, DataSet Detail and DataSet Footer Event Handlers, this variable is used to return the serialized data to include in the export dataset being built. For all other Event Handers, this variable will be ignored.

SKIP$

In the DataSet Detail Event Handler, this variable can be set to indicate that the current record being processed should not be included in the dataset being built by the export.

PROPS$

A dynamic array that contains run-time information for the export that can be useful to the programmer. Use the equated constants defined in the KORE-INCLUDES KEX.EQUATES include to reference the various fields in the PROPS$ variable.

Following are the Extract/Set properties using the <KEX$XXX> variable syntax.

Variable	Description
PROPS$<KEX$SENTENCE>
PROPS$<KEX$DATAFILE>	This read-only variable will contain the primary Export Data File name as defined in the export. See FILENAME$ for more details.
PROPS$<KEX$ICTR>	This read-only variable will contain the number of records included in the dataset being built. It is updated after the DataSet Detail Event Handler has completed is execution.
PROPS$<KEX$RCTR>	This read-only variable will contain the number of records read while the dataset being built. It is updated after the DataSet Detail Event Handler has completed is execution.
PROPS$<KEX$EXPORTTYPE>	This variable has been deprecated. Use EXPORTFMT$ instead.
PROPS$<KEX$BYEXPVNO>	This read-only variable will contain the value number selected if the Export Select statement uses a BY-EXP or BY-EXP-DSND keyword. Otherwise, it will contain an empty string.
PROPS$<KEX$EXPORTID>	This read-only variable contains the name of the export being processed.
PROPS$<KEX$SELFILE>	This variable will contain the Select Data File name as specified in the export. This variable can only be updated in the BeforeSelect Event Handler.
PROPS$<KEX$SELUSING>	This variable will contain the Select Using File name as specified in the export. This variable can only be updated in the BeforeSelect Event Handler.
PROPS$<KEX$SELSTMT>	This variable will contain the Select Statement as specified in the export. This variable can only be updated in the BeforeSelect Event Handler.
PROPS$<KEX$IHTTPHDRS>	This read-only variable will contain the inbound HTTP headers, in header style format, when a REST export is being processed. Otherwise, it will contain an empty string.
PROPS$<KEX$OHTTPHDRS>	This variable will contain outbound HTTP headers, in header style format, when a REST export is being processed. Otherwise, it will contain an empty string.
PROPS$<KEX$QUERYHDRS>	This variable will contain the query parameters specified in the HTTP request, in header style format, when a REST export is being processed. Otherwise, it will contain an empty string.
PROPS$<KEX$SQLNETCHG>	This variable will contain Net Change Where string specified in the export. It can only be updated in the BeforeSelect Event Handler and is only available when processing an ODBC export.
PROPS$<KEX$SQLSTMT>	This variable will contain SQL statment string specified in the export. It can only be updated in the BeforeSelect Event Handler and is only available when processing an ODBC export.
PROPS$<KEX$USER1>	Reserved for programmer usage.
PROPS$<KEX$USER2>	Reserved for programmer usage.
PROPS$<KEX$USER3>	Reserved for programmer usage.
PROPS$<KEX$USER4>	Reserved for programmer usage.
PROPS$<KEX$USER5>	Reserved for programmer usage.

Scope of Use

This Event Handler interface can be used from a Kourier export. To access information in the PROPS$ variable, use the equated constants as described in KORE-INCLUDES KEX.EQUATES.