Invoking a C function from an EGL program

You can invoke (or call) a C function from an EGL program through a Library part with the stereotype nativeLibrary.

Before you following the instructions below, you must compile and link your C code as identified in Calling C functions through EGL libraries.

To invoke a C function from an EGL program:
  1. Using the function invocation statement, specify the following:
    • The name of the C function
    • Any arguments to pass to the C function
    • Any variables to return to the EGL program
  2. Create an EGL Library part with the stereotype nativeLibrary containing the function definition.
  3. With the USE statement, specify the EGL native library in the calling module.

For example, the following function invocation statement calls the C function sendmsg( )

sendmsg(chartype, 4, msg_status, return_code);

It passes two arguments (chartype and 4, respectively) to the function and expects two arguments to be passed back (msg_status and return_code, respectively). This is made clear by defining the function in a native library as follows:

Library I4GLFunctions type nativeLibrary
			{callingConvention = I4GL, dllName = "mydll"}
			Function sendmsg(chartype char(10) in, i int in, 
                       msg_status int out, return_code int out)
			end
end

The arguments passed are specified using the "in" parameter and the arguments to be returned are specified using the "out" parameter.

callingConvention
specifies that the arguments will be passed between functions and the calling code using the argument stack mechanism.
dllName
specifies the C shared library in which this function exists.
Note: The C shared library name can also be specified using the vgj.defaultI4GLNativeLibrary system property. If both dllName and the system property have been specified, the dllName will be used.

The C function receives an integer argument that specifies how many values were pushed on the argument stack (in this case, two arguments). This is the number of values to be popped off the stack in the C function. The function also needs to return values for the msg_status and return_code arguments before passing control back to the EGL program.

The C function should not assume it has been passed the correct number of stacked values. The C function should test its integer argument to see how many EGL arguments were stacked for it.

This example shows a C function that requires exactly one argument:

int nxt_bus_day(int nargs);
{
    int theDate;
    if (nargs != 1)
    {
       fprintf(stderr,
          "nxt_bus_day: wrong number of parms (%d)\n",
          nargs );
       ibm_lib4gl_returnDate(0L);
       return(1);
    }
    ibm_lib4gl_popDate(&theDate);
    switch(rdayofweek(theDate))
    {
    case 5: /* change friday -> monday */
          ++theDate;
    case 6: /* saturday -> monday*/
          ++theDate;
    default: /* (sun..thur) go to next day */
          ++theDate;
    }
    ibm_lib4gl_returnDate(theDate); /* stack result */
    return(1) /* return count of stacked */
 }
 

The function returns the date of the next business day after a given date. Because the function must receive exactly one argument, the function checks for the number of arguments passed. If the function receives a different number of arguments, it terminates the program (with an identifying message).


Feedback