Return functions for C

To call a C function, EGL uses an argument stack, a mechanism that passes arguments between the functions and the calling code.

The EGL calling function pushes its arguments onto the stack and the called C function pops them off of the stack to use the values. The called function pushes its return values onto the stack and the caller pops them off to retrieve the values. The pop and return external functions are provided with the argument stack library. The return external functions are described below; the pop external functions used are described in "Stack functions for C."

The external return functions copy their arguments to storage allocated outside the calling function. This storage is released when the returned value is popped. This situation makes it possible to return values from local variables of the function.

Note: The return functions were originally used with IBM® Informix® 4GL (I4GL); hence the inclusion of "4gl" in the function names.

Library functions for returning values

The following library functions are available to return values:
The following table maps the return function names between I4GL pre-Version 7.31 and Version 7.31 and later:
Pre-Version 7.31 name Version 7.31 and later name
retint ibm_lib4gl_returnMInt
retshort ibm_lib4gl_returnInt2
retlong ibm_lib4gl_returnInt4
retflo ibm_lib4gl_returnFloat
retdub ibm_lib4gl_returnDouble
retdec ibm_lib4gl_returnDecimal
retquote ibm_lib4gl_returnQuotedStr
retstring ibm_lib4gl_returnString
retvchar ibm_lib4gl_returnVarChar
retdate ibm_lib4gl_returnDate
retdtime ibm_lib4gl_returnDateTime
retinv ibm_lib4gl_returnInterval

The argument of ibm_lib4gl_returnQuotedStr( ) is a null-terminated string. The ibm_lib4gl_returnString( ) function is included only for symmetry; it internally calls ibm_lib4gl_returnQuotedStr( ).

The C function can return data in whatever form is convenient. If conversion is possible, EGL converts the data type as required when popping the value. If data type conversion is not possible, an error occurs.

C functions called from EGL must always exit with the statement return(n), where n is the number of return values pushed onto the stack. A function that returns nothing must exit with return(0).


Feedback