Passing Arguments from an ILE Program to a Non-EPM Program

When passing arguments to any program other than an EPM entry point, use the following conventions:
  • The program name that the ILE C/C++ program calls must be in uppercase. You can use the #pragma map directive to map an internal identifier longer than 10 characters to an object name that is compliant with IBM® i (10 characters or less) in your program.
  • The return code for the program call can be retrieved by declaring the program to return an integer. For example:
    Figure 1. Example of Using the #pragma linkage(PGMNAME, OS) Directive to Retrieve Returned Function Results
    int PGMNAME(void);
#pragma linkage(PGMNAME, OS)
    Note: The declared function in the ILE source must return either int or void. No other type is allowed.

    The value that is returned on the call is the return code for the program call. If the program being called is an ILE program, this return code can also be accessed using the _LANGUAGE_RETURN_CODE macro defined in the header file <milib.h>. If the program being called is an EPM or OPM program, use the Retrieve Job Attributes (RTVJOBA) command to access this return code.

  • If you use the #pragma linkage (PGMNAME, OS) directive, all arguments (except pointers and aggregates) are copied to temporary variables by the compiler. Pointers to the temporary variables are passed to the called program. Non-pointer arguments are passed by value-reference.
    Value reference (sometimes referred to as by value, indirectly) refers to the parameter passing mechanism where:
    • A non-pointer value is copied to a temporary variable, and the address of the temporary variable is passed on. The changes that are made to the variable in the called program are not reflected in the calling program.
    • If the argument you are passing is an aggregate name or a pointer, then the argument is passed directly, and a temporary variable is not created. This means that the data that is refered to by the array or pointer can be changed by the called program.
  • If you want to pass arguments by reference, you must use the address of (&) operator.
When passing arguments to an EPM entry point, use the following conventions:
  • If you have an ILE C program calling an EPM default entry point, then use the #pragma linkage (PGMNAME, OS) directive in your ILE C source to tell the compiler that PGMNAME is an external program, not a bound ILE procedure.
  • If you have an ILE C program calling an EPM non-default entry point, you must use the EPM API QPXXCALL. QPXXCALL can also be used to call EPM default entry points. Because QPXXCALL is an OPM program, you must use the #pragma linkage (QPXXCALL, OS) directive in your ILE C source.