User exit—%USER

Use this function to call a user exit program from an expression. This function provides flexibility when complex logic that cannot be expressed using the provided column functions is required. You can use this function to call a user exit program with input parameters.

Note: The CDC Replication Engine for Microsoft SQL Server does not support this function. If you are using a replication engine other than CDC Replication Engine for Db2® for z/OS®, you cannot use this function to call a stored procedure.

Syntax

%USER('program_name', parm1, parm2, ..., parmn

Parameters

program_name

Specifies the name of the user exit program. You must enclose values of this parameter in single quotation marks. You can write the user exit program in any high-level language. You must place an executable object for the user exit program in the CDC Replication installation directory prior to starting refresh or mirroring.

parm1, parm2, ..., parmn

Specify columns or literals that are passed as parameters to the user exit program (maximum 20).

In the user exit program that you write, you must declare a data structure that defines specific fields for the result and each input parameter (parm1, parm2, ..., parmn).

Field	Length and data type	Description
DATATYPE	Two-byte binary	Specifies the data type of the result or input parameter: 1—Character 2—Date 3—Float 4—Integer 5—Packed numeric 6—Time 7—Zoned numeric
LENGTH	Two-byte integer	Specifies the length of the result or input parameter in bytes.
DIGITS	Two-byte binary	Specifies the number of digits in the result or input parameter.
DECPLC	Two-byte binary	Specifies the number of decimal places in the result or input parameter.
NULLIND	Two-byte binary	Specifies whether or not the result or input parameter is NULL: 0—Result or input parameter is not NULL. 1—Result or input parameter is NULL.
DTMFMT	Four-byte character	Specifies the date format in the result or input parameter: USA United States date format. ISO ISO (International Organization for Standardization) date format. EUR European date format. JIS Japanese Industrial Standard. YMD The date format is yymmdd. MDY The date format is mmddyy. *DMY The date format is ddmmyy.
`VALUE`		Specifies one of the following: For each input parameter, the field that contains the input parameter value passed to the user exit program. For the user exit program result, the field that contains the result returned by the user exit program. The name of this field in the user exit program is user-defined.

Result data type

The data type of the result returned by the user exit program.

Examples

%USER(‘USERSEL1',
BRANCH)

This function calls the COBOL program USERSEL1, passing the BRANCH column as a parameter. USERSEL1 checks whether or not BRANCH is set to '11'. If it is, then the user exit program returns a one-byte character value of Y. Otherwise, it returns a character value of N.

Note: The following user exit program is provided for illustration purposes only and should be tested for all production environments.

IDENTIFICATION DIVISION.
PROGRAM-ID. USERSEL1.
AUTHOR. IBM CORP.
INSTALLATION. IBM CORP.
DATE-COMPILED.
*******************************************************************
* Program : USERSEL1.
* ----------------
* Version: 1.0
* ----------------
* Description: SAMPLE COBOL USER ENTRY POINT PROGRAM
* ----------------
*
******************************************************************
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. IBM-AS400.
OBJECT-COMPUTER. IBM-AS400.
******************************************************************
* D A T A D I V I S I O N
******************************************************************
DATA DIVISION.
******************************************************************
* W O R K I N G S T O R A G E S E C T I O N
******************************************************************
WORKING-STORAGE SECTION.
*
01 DATATYPES COMP-4.
03 TYP-CHAR PIC S9(4) VALUE 1.
03 TYP-DATE PIC S9(4) VALUE 2.
03 TYP-FLOAT PIC S9(4) VALUE 3.
03 TYP-INTEGER PIC S9(4) VALUE 4.
03 TYP-PACKED PIC S9(4) VALUE 5.
03 TYP-TIME PIC S9(4) VALUE 6.
03 TYP-ZONED PIC S9(4) VALUE 7.
******************************************************************
* L I N K A G E S E C T I O N
******************************************************************
LINKAGE SECTION.
01 RETURN-VALUE.
03 RV-DATATYPE PIC S9(4) COMP-4.
03 RV-LENGTH PIC S9(4) COMP-4.
03 RV-DIGITS PIC S9(4) COMP-4.
03 RV-DECPLC PIC S9(4) COMP-4.
03 RV-NULLIND PIC S9(4) COMP-4.
03 RV-DTMFMT PIC X(4).
03 RV-SELECT PIC X(1).
01 PARM-1.
03 P1-DATATYPE PIC S9(4) COMP-4.
03 P1-LENGTH PIC S9(4) COMP-4.
03 P1-DIGITS PIC S9(4) COMP-4.
03 P1-DECPLC PIC S9(4) COMP-4.
03 P1-NULLIND PIC S9(4) COMP-4.
03 P1-DTMFMT PIC X(4).
03 P1-BRANCH PIC X(2).
******************************************************************
* P R O C E D U R E D I V I S I O N
******************************************************************
PROCEDURE DIVISION USING RETURN-VALUE
PARM-1.
ML-0010.
*
* This example program checks parm 1 for a value of ‘11' and if found,
* returns ‘Y', else returns ‘N'.
*
* Define the Returned Value as a 1-byte character field.
*
MOVE TYP-CHAR TO RV-DATATYPE.
MOVE 1 TO RV-LENGTH.
MOVE ZERO TO RV-DIGITS.
MOVE ZERO TO RV-DECPLC.
MOVE ZERO TO RV-NULLIND.
MOVE SPACES TO RV-DTMFMT.
*
* Test for a value of ‘11' in the first parameter.
*
IF P1-BRANCH IS EQUAL TO ‘11'
MOVE ‘Y' TO RV-SELECT
ELSE
MOVE ‘N' TO RV-SELECT.
EXIT PROGRAM.