ILE C/C++ Programmer's Guide

Passing Parameters from ILE C++ to a Different High-Level Language

To share data between programs (or between procedures), you need to pass parameters which both programs can use to the called program or procedure. In C++, you use the linkage specification to tell the compiler which parameter passing convention to use on the external call.

When passing parameters from C++ to a different high-level language (HLL) consider:

• Parameter passing style of the HLLs

  Each HLL has its own way of passing parameters. Parameters can be passed as:

  • A pointer to the value
  • A pointer to a copy of the value
  • The value itself

  C++ passes parameters in all three ways. For information on these styles, see Using Default Parameter Passing Styles .

• Interlanguage data compatibility

  Different HLLs support different ways of representing data. Pass only parameters which have a data type common to the calling and called program or procedure. If you are not sure of the exact format of the data that is passed to your program, you may specify to the users of your procedure that an operational descriptor can be passed to provide additional information regarding the format of the passed parameters. For more information, see and Using Operational Descriptors to Pass Parameters of Unknown Data Type.

Using Different Linkage Specifications

Table 20 shows the effect of using different linkage types when passing parameters:

Table 20. Effects of Various Linkage Specifications

Specifying that a Function Has ILE Linkage

The extern keyword followed by the string literals "RPG", "COBOL", or "CL" are used to specify that the function has "ILE" linkage. These string literals perform the same function as the #pragma argument directive in ILE C. The "VREF" linkage also performs the same as the VREF parameter on the #pragma argument directive.

Note:

For more information on the #pragma argument directive, see WebSphere Development Studio: ILE C/C++ Compiler Reference.

Specifying ILE, CL, COBOL, and RPG Linkage

Specifying an ILE, CL, COBOL, or RPG linkage for a function tells the compiler:

• Arguments passed as values or non-pointer arguments are copied to temporary variables and the addresses of the temporary variables are passed to the called procedure.
• Pointer arguments are passed directly to the called procedure.
• If extern "ILE nowiden" is used, then the parameters and return value passed between programs and procedures are not widened; specifying any other ILE linkage widens the parameters.
• Function names are not mangled.

Specifying VREF Linkage

Specifying a VREF linkage is identical to specifying an ILE linkage except that pointer parameters are stored in a temporary variable and the address of the temporary variable is passed as the actual argument.

Specifying that a Function Has External (OS) Linkage

The extern specifier followed by the string-literal "OS" or the string-literal "OS nowiden" is used to declare external programs. These programs may then be called in the same way as a regular function.

When an OS linkage function is called from a C++ program, the compiler generates code and performs the following tasks in sequence:

1. If extern "OS" is used, then the parameters and return value are widened.

   If extern "OS nowiden" is used, then the parameters and return value passed between programs are not widened.

2. Parameters that are passed by value are copied to temporary variables and the addresses of the temporary variables are passed to the called program.

   If a temporary variable is created for a structure, the temporary variable has the same structure and information as the struct parameter passed.

3. Parameters that were passed by reference are still passed by reference.
4. Arrays and pointers are passed by reference.
5. If the argument you are passing is an array name or a pointer, then the argument is passed directly, and a temporary variable is not created. The data referenced by the array or pointer can be changed by the called program.
6. The function name is not mangled.

The program name that the C++ dynamic program calls must be in uppercase. You can use the #pragma map directive to map an internal identifier longer than 10 characters to an OS/400-compliant object name (10 characters or less) in your program. See Renaming Programs and Procedures.

The return code for the dynamic program call can be retrieved by declaring the program to return an integer:

extern "OS" int PGMNAME(void);

The value returned on the call is the return code for the dynamic program call. If the program being called is a C++ program, this return code can be accessed using the _LANGUAGE_RETURN_CODE macro defined in the header file <milib.h>. A C++ program returns four bytes in the _LANGUAGE_RETURN_CODE. If the program being called is an EPM or OPM program, this return code can be accessed using the iSeries Retrieve Job Attributes (RTVJOBA) command.

When a function is called from an OS linkage function pointer, the compiler generates the same code sequence it does when calling an OS linkage function.

Non-pointer arguments are passed by value reference, and changes made to the variables in the called program are not reflected in the calling C++ program.

Specifying that a Function Has C Linkage

Specifying C linkage for a function tells the compiler:

• Parameters are passed using C++ conventions
• Parameters for functions declared with extern "C" are widened
• The function name is not mangled

The extern keyword followed by the string-literal "C" or the string-literal "C nowiden" is used to specify that the function is declared to have "C" linkage instead of "C++" linkage.

Using Different Linkage Specifications (C++ Only)

When using the extern "literal" statement, consider that:

• The string-literal parameter is case-insensitive. For example, extern "OS NOWIDEN", extern "OS nowiden", and extern "os NoWiden", although different in case are all handled in the same way.
• The name of the function must follow the naming conventions of the other language. For example, for OS linkage specifications, the program name and all iSeries objects must be uppercase. See Renaming Programs and Procedures.
• A type definition of a function can be declared to have linkage information. After the type definition is declared, it can be used to declare functions of a particular linkage. The type definition declaration must be enclosed by braces: {}.
• A function cannot be assigned directly to a pointer to a function with a different linkage. A type cast may be used to make this assignment possible. Type casting helps you eliminate parameter mismatching problems without excess constraint. See Type Casting to Override a Function without Overriding Linkage.
• Functions that take function pointers as parameters may not be overloaded based on the linkage of the function pointers, as shown in the following code sample:

  // Using the typedef declarations above
  void foo (OS);
  void foo (CPP);  // undefined behavior, foo already declared
  

• Functions that are defined with non-C++ linkage specifications accept parameters using the appropriate convention for that linkage. You do not need to widen parameters, as show in the following code sample:

  extern "C" void foo (char);  // chars are widened in C
  // In another compilation unit we then have
  extern "C" void foo (char c) // this parameter is correctly widened
  {
      // implementation of foo (char);
  }
  

• Attempting to define a function with either extern "OS", extern "OS nowiden", or extern "builtin" linkage results in undefined behavior, as shown in the following code sample:

  extern "OS" void FOOPGM (char);  // declaration: OK
  extern "OS" void FOOPGM (char c) // definition: undefined behavior
  {
      // implementation of FOOPGM
  }
  

• The declaration of a function pointer is:

  extern "OS" {
    typedef void (*fp) (char);
  }
  fp FOO;
  

  Note:

  Function FOO() is declared to be a function pointer of type fp.

• The widening rules for all the linkage specifications shown in Table 20 are:

  • Any data type that is smaller than int is widened to int
  • float is widened to double
  • Address and Data pointers are not widened
  • struct has the same structure and information as the struct parameter passed
• Data objects can be declared inside the extern linkage declaration:

  extern "OS" {
       int a1;
  }
  extern "OS" int a2;
  

  Note:

  Variable a1 is defined while variable a2 is only declared.

• Functions FOO1(), FOO2(), and FOO3() are all declared as OS linkage functions. Functions FOO1() and FOO2() are declared by using the declaration-list syntax. FOO3() is declared by using the simple declaration.

  extern "OS" {
      void FOO1 (char, char *);
      void FOO2 (int, int *);
  }
  extern "OS" int FOO3 (double, double *);
  

• In C++ linkage specifications, function identifiers are mangled. In all other linkage specifications, all function identifiers are identical to the exported names unless changed by the #pragma map directive.

  Note:

  For the syntax and description, see WebSphere Development Studio: ILE C/C++ Compiler Reference.

Using Default Parameter Passing Styles

To pass parameters between ILE C/C++ and other ILE languages, especially ILE C, ILE RPG, or ILE COBOL, you must ensure that the other procedure is set up to accept data by reference.

ILE C++ uses the same calling mechanisms for calling any ILE HLL program or procedure: extern linkage specification.

ILE C++ passes and receives parameters using three passing methods:

By value, directly

The value of the data object is placed directly into the argument list.

By value, indirectly

The value of the data object is copied to a temporary location. The address of the copy, a pointer, is placed into the argument list.

By reference

A pointer to the data object is placed into the argument list. Changes made by the called procedure to the argument are reflected in the calling procedure.

Other ILE languages may have different methods of passing data. See Table 21.

Table 21. Default Argument Passing Style for ILE Programs

Table 22 shows the common parameter passing methods for the ILE procedures.

Table 22. Default Argument Passing Style for ILE Procedures

Using Operational Descriptors to Pass Parameters of Unknown Data Type

To pass a parameter to a procedure even though the data type is not precisely known to the called procedure you can use operational descriptors. Operational descriptors provide descriptive information to the called procedure regarding the form of the argument. This information allows the procedure to properly interpret the passed parameter. Use operational descriptors only when they are expected by the called procedure.

Note:

For more information on operational descriptors, see:

• ILE Concepts
• WebSphere Development Studio: ILE C/C++ Compiler Reference

The C++ compiler supports operational descriptors for describing null-terminated strings. A character string in C++ is defined by: char string_name[n], char * string_name, or string-literal.

C++ defines a string as a contiguous sequence of characters terminated by and including the first null character. In another language, a string may be defined as consisting of a length specifier and a character sequence. When passing a string from a C++ function to a function written in another language, an operational descriptor can be provided with the argument to allow the called function to determine the length and type of the string being passed.

To use operational descriptors, you specify a #pragma descriptor directive in your source to identify functions whose arguments have operational descriptors. Operational descriptors are then built by the calling procedure and passed as hidden arguments to the called procedure. For the syntax, see WebSphere Development Studio: ILE C/C++ Compiler Reference.

The following examples illustrates the use of operational descriptors in ILE C/C++. They show:

• The #pragma descriptor for func1() with a #pragma descriptor directive for the function in a header file oper_desc.h. See Figure 251.
• An ILE C program that calls func1(). See Figure 252.
• The ILE C source code of func1() that contains an ILE API that is used to get information from the operational descriptor. See Figure 235.

Example: Calling a Function with Operational Descriptors

The following figure shows an ILE C program that calls func1(). When the function func1() is called, the compiler generates operational descriptors for the three arguments that are specified on the call.

Figure 235. ILE C Source to Call a Function with Operational Descriptors

#include "oper_desc.h"

...

main()

{

   char  a[5] = {'s', 't', 'u', 'v', '\0'};

   char *c;

   c = "EFGH";

   ...

   func1(a, "ABCD", c);

}

(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.