ITR501 external call

External calls comprise a set of independent modules that are stored in the ITR501 module. They are activated automatically by the Data Manipulation Language (DML) $SEARCH and $CHECK commands.


The ITR501 module exists in C (ITR501C) and COBOL (ITR501).

If you use the ITR501C module, you can use the pre-coded entry points to access the Euroconverter modules and the data stored in an Oracle database. To do so, you must remove the comments characters that precede the instructions for these entry points.

List of entry points values

Entry Point Code Description

From “01” to “73”
(numeric code)

From “0A” to “ZZ” (alphanumeric code)

Customizable functions


Customizable open function called when opening the session.

Particularly useful for opening the files required and connecting to databases


Customizable close function called when closing the session.

Use this function to close files and disconnect from databases


Pre-coded entry points for ITR501C


Call to Euroconverter modules

The return parameter depends on the module that is activated


Field formatting functions


$SEARCH command that activates a « select » on a table column

The return parameter is the first row that meets the “select” criteria


$SEARCH command that activates an Oracle procedure

The return parameter corresponds to the activated procedure


$CHECK command that checks the existence of a value in a table column


$CHECK command that checks a value via an Oracle procedure


Exchanged data

Alphanumeric fields may have different descriptions depending on the programing language and the Latin or UTF-16 format used. For more information, refer to Exits and external calls.

INPUT data

Name in C Name in COBOL Characteristics / Length Use



Alphanumeric / 256

Value of the search or check parameter



Numeric / 3

Length of the expected output parameter
Value varies from 1 to 256
(for a $SEARCH function)



Alphanumeric / 1

Data type of the expected output parameter: “A”, “N”, “S”, “P”, “D”
(for a $SEARCH function)



Alphanumeric / 2

Entry point code



Name in C Name in COBOL Characteristics Use



Alphanumeric / 256

Value of the return parameter
(for a $SEARCH function)



Alphanumeric / 2

Entry point code.



Alphanumeric / 1

Function return code:

  • 0: Search or check successful
  • 9: Search or check failed
  • F: System error



Alphanumeric / 50

Error message if an error is detected



Numeric / 7

Error code if an error is detected



Alphanumeric / 2

Error status if an error is detected


Description conventions

Number Description


Common description conventions


You must set the output data via the function that you developed at the selected entry point


By default, the return code is zero (OK)
If you change it, it must be set to one of the values shown in the preceding table


Each entry point activated in the Transformation-Rule and Enrichment-Rule mapping rules must be declared in ITR501
If it is not declared, the processed Input-Event is set to the anomaly state


By default, the numeric entry points are declared in the external call
Even if no code is written, the return code is OK


The Alphanumeric entry points must be declared in the external call


C language conventions


You must add the following instructions to the switch (nCDPARAM):

  • Case entry_point_code
  • Break


COBOL conventions


You must add the following instruction to the AUTRES-CODES section:
IF LPCDPARAM = “entry_point_code” GO TO P-entry_point_code
Define a P-entry_point_code label

Data field value

The first 25 characters of the sDATA256 (or LPZDATA256) field contain the value of the sender code during the open (entry point “79”).

For a $SEARCH function, it is recommended that you reset this field before loading the return value, in order to avoid “spurious values”.

When you set this field, whatever the field type, you must left-justify the data with the length defined by sLONG (or LPLONG).

ITR501C (C language) provides conversion functions to get and write the data exchanged in the expected format:

  • SPK_Num2Pack: Conversion of an unsigned numeric value into a packed value
  • SPK_Pack2Num: Conversion of a packed value into a numeric value
  • SPK_Num2Sign: Conversion of a numeric value into a signed value
  • SPK_Sign2Num: Conversion of a signed value into a numeric value
  • SPK_IsSPKformat:Checking that a value is numeric (signed or decimal)

For more details on conversion functions, refer to Data conversion – Functions in C.

Prototypes of these functions are available in the:

  • ITR501.h file located for:
    • UNIX in the $RDJ_EXEC/exit directory
    • Windows in the %RDJ_EXEC%\exit directory
  • ITR501 file in the SCRLIB.H MVS library

For information on conversion return values, refer to Return values


To access Oracle, you can use the pre-coded SQL functions available in ITR501 entry points “75” to “78”:

  • SQLSELECT: Get a value using a select instruction on a table column
  • SQLPROC: Get data that results from execution of a procedure
  • SQLDIRECTSELECT:Get a value using a select instruction, for which the full instruction is sent to the function
  • SQLCTRLSELECT: Check that a value exists by running a select instruction

For more details on SQL functions and return values, refer to SQLxxx functions.

If you want to access a database via ITR501 in COBOL, you can use the example provided in the program comments.

Compatibility with RDJ version

The current communication area has been enhanced. However, it remains compatible with RDJ version

The changes in the communication area are as follows:

  • The total length of the communication zone has ben increased from 283 to 380 characters
  • The field names have changed, but their sequence and justification remain identical
  • The length of the error message has been increased from 20 to 50 characters
  • Error and status codes have been added
  • The call point code is alphanumeric (it was numeric in the previous version)

Parameter settings

No particular parameter settings are needed, as the call is made when the $SEARCH and $CHECK functions are executed in the mapping rules (Transformation- Rules and Enrichment-Rules).

Module names

Platform Directory / Library Name C Program COBOL Program



ITR501.h header file




ITR501.h header file




header ITR501H



Processing Type Label Entry Point







Call point xx



Related Links