Progress/400
Product Guide


EPI CALL Command

The EPI CALL command allows the Progress 4GL to call programs written in languages supported by OS/400. A called program can receive data in parameters and can return data to a Progress 4GL program in the same parameters.

The following restrictions apply to any OS/400 program called from a Progress 4GL program:

For details on data type support, see the "PARM Parameter" section.

Syntax

The syntax for the EPI CALL command is designed for use by both the Progress programmer and the OS/400 programmer. The EPI CALL syntax mixes both Progress and CL constructs, making it familiar to both types of programmers:

OS400 EPI STATUS(sts) MESSAGES(msg)
CALL PGM(library/program)
PARM(prog-var[extent] AS TYPE(len, decimals) USE use)  

PGM Parameter

The CALL statement uses the PGM parameter to specify the name of the program the 4GL program is calling. The value and use of this parameter match those of the PGM parameter on the CL CALL command. You can explicitly specify the library or use the *LIBL. The PGM parameter is required. If you do not specify a library, the Progress 4GL assumes *LIBL. If the program or library is not found, the Progress 4GL places an error message into the MESSAGES variable.

PARM Parameter

The PARM parameter defines what parameters, if any, Progress passes to the called program and how Progress passes them. Any Progress variable used as a parameter for an HLL program must be defined as a SHARED VARIABLE. Defining variables in this fashion allows the value of the variable to be retrieved and changed efficiently. Progress shared variables are passed to an HLL program as a particular data type. The value prog-var contains the name of a Progress variable. The variable must be defined as a shared variable. A single element of a 4GL array (EXTENT field) can also be used as prog-var.

The Progress variable must be one of the following Progress data types:

Progress requires the AS keyword. This states that the Progress variable will be passed to the called program as TYPE, where type indicates an OS/400 data type. The following OS/400 data types are supported:

Each parameter must have an OS/400 data type and a length. When you define the OS/400 data type, also define its length. To do this, use TYPE(len, decimals), where len indicates the length of the program parameter; and decimals, when required, specifies the number of decimal digits. Packed and Zoned parameters must have the number of decimals defined.

Table 11–2 indicates the rules to follow when defining the mapping between Progress and OS/400 data types.

Table 11–2: Mapping Progress to OS/400 Data Types
Progress
Data Type
OS/400
Data Type
Rules for Mapping
Character
Character
Data is passed as it appears in the Progress variable up to the length of the OS/400 data type.
Integer
Integer
The value of the integer is passed to the HLL program as a four-byte integer field. Overflow could occur if a large number is passed back from the HLL program.
Decimal
Packed
Zoned
The integer is converted to either packed or zoned of the specified length and decimal digits. However, the decimal portion of the packed or zoned field is set to 0 when the HLL program is called. The value of the decimal portions of the number from the HLL program is ignored when converting the value back into a Progress integer.
Decimal
Decimal
Data is passed as it appears in the Progress variable up to the length of the OS/400 data type.
Logical
Character
Data is passed as 1 or 0. A 1 is passed if the value is TRUE. A 0 is passed if the value is FALSE.

The USE parameter indicates how the Progress 4GL program treats the value of the variable. Table 11–3 describes the USE values.

Table 11–3: USE Parameter 
USE Value
Description
INPUT
The Progress variable is treated as input to the called program and its value does not change in the 4GL program.
INPUT-OUTPUT
The Progress variable is treated as input to the called program. When the called program returns, the Progress variable reflects what is passed back from the program.
OUTPUT
The called program is called with a default value. When the called program returns, the Progress variable reflects what is passed back from the program. If the OS/400 data type is CHARACTER, blanks are passed. If the OS/400 data type is numeric, a value of zero (0) is passed.

The following code shows how to construct the EPI command for a call to a CL program:

Progress 4GL Program TestCall.P
DEFINE NEW SHARED VARIABLE Parameter1 AS CHARACTER FORMAT "X(50)".
DEFINE NEW SHARED VARIABLE Parameter2 AS DECIMAL FORMAT "999.9999".
DEFINE NEW SHARED VARIABLE RTN-STAT AS INTEGER.
DEFINE NEW SHARED VARIABLE Messages AS CHARACTER EXTENT 50.

ASSIGN Parameter1 = "This is a test"
ASSIGN Parameter2 = 3.14156.

DISPLAY Parameter1 Parameter2.

OS400 EPI STATUS(RTN-STAT) MESSAGES(Messages)
  CALL PGM(*LIBL/TESTCLP)
    PARM(Parameter1 AS CHARACTER(50) USE INPUT-OUTPUT)
    PARM(Parameter2 AS PACKED(15, 5) USE OUTPUT).

DISPLAY Parameter1 Parameter2. 

CL Program TESTCLP
PGM PARM(&TEXT &NUMBER)

DCL VAR(&TEXT) TYPE(*CHAR) LEN(50)
DCL VAR(&NUMBER) TYPE(*DEC) LEN(15 5)

/* Alter the values of the parameters and return to the caller */

CHGVAR VAR(&TEXT) VALUE(‘to show that it works’)
CHGVAR VAR(&NUMBER) VALUE(123.5623)

RETURN
ENDPGM 

Example Progress 4GL programs and OS/400 programs are provided with your release. Sample HLL programs are available in the Examples Source File in the Progress-supplied product library.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095