ITR501 external call

This chapter describes the external call and how to use it.

Overview

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.

Characteristics

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

“79”

Customizable open function called when opening the session.

Particularly useful for opening the files required and connecting to databases

“80”

Customizable close function called when closing the session.

Use this function to close files and disconnect from databases

 

Pre-coded entry points for ITR501C

“70”

Call to Euroconverter modules

The return parameter depends on the module that is activated

“71”

Field formatting functions

“75”

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

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

“76”

$SEARCH command that activates an Oracle procedure

The return parameter corresponds to the activated procedure

“77”

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

“78”

$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 Manage exits and external calls.

INPUT data

Name in C Name in COBOL Characteristics / Length Use

sDATA256

LPZDATA256

Alphanumeric / 256

Value of the search or check parameter

sLONG

LPLONG

Numeric / 3

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

sCLASSE

LPCLASSE

Alphanumeric / 1

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

sCDPARAM

LPCDPARAM

Alphanumeric / 2

Entry point code

OUTPUT data

Name in C Name in COBOL Characteristics Use

sDATA256

LPZDATA256

Alphanumeric / 256

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

sCDPARAM

LPCDPARAM

Alphanumeric / 2

Entry point code.

FLAG

LPFLAG

Alphanumeric / 1

Function return code:

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

lsZONERR

LPZONERR

Alphanumeric / 50

Error message if an error is detected

sCDERR

LPCDERR

Numeric / 7

Error code if an error is detected

sSTATUS

LPSTATUS

Alphanumeric / 2

Error status if an error is detected

Implementation

Description conventions

Number Description

 

Common description conventions

1

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

2

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

3

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

4

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

5

The Alphanumeric entry points must be declared in the external call

 

C language conventions

6

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

  • Case entry_point_code
  • Break

 

COBOL conventions

6

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 1.5.3.2

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

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

Windows

%RDJ_EXEC%\exit

ITR501.c
ITR501.h header file

ITR501.cbl

UNIX

$RDJ_EXEC/exit

ITR501.c
ITR501.h header file

ITR501.cbl

MVS

&RDJEXEC..SRCLIB

ITR501C
header ITR501H

ITR501

 

Processing Type Label Entry Point

Open

P79

79

Close

P80

80

Call point xx

Pxx

xx

Related Links