Stack 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 pop external functions are described below according to the data type of the value that each pops from the argument stack. The return external functions are described in Return functions for C.

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

Library functions for returning values

You can call the following library functions from a C function to pop number values from the argument stack:
  • extern void ibm_lib4gl_popMInt(int *iv)
  • extern void ibm_lib4gl_popInt2(short *siv)
  • extern void ibm_lib4gl_popInt4(int *liv)
  • extern void ibm_lib4gl_popFloat(float *fv)
  • extern void ibm_lib4gl_popDouble(double *dfv)
  • extern void ibm_lib4gl_popDecimal(dec_t *decv)
  • extern void ibm_lib4gl_popInt8(ifx_int8_t *bi)
The following table and similar tables below map 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
popint ibm_lib4gl_popMInt
popshort ibm_lib4gl_popInt2
poplong ibm_lib4gl_popInt4
popflo ibm_lib4gl_popFloat
popdub ibm_lib4gl_popDouble
popdec ibm_lib4gl_popDecimal
Each of these functions, like all library functions for popping values, performs the following actions:
  1. Removes one value from the argument stack.
  2. Converts its data type if necessary. If the value on the stack cannot be converted to the specified type, an error occurs.
  3. Copies the value to the designated variable.

The structure types dec_t and ifx_int8_t are used to represent DECIMAL and BIGINT data in a C program. For more information about the dec_t and ifx_int8_t structure types and library functions for manipulating and printing DECIMAL and BIGINT variables, see the IBM® Informix® ESQL/C Programmer's Manual.

Library Functions for Popping Character Strings

You can call the following library functions to pop character values:
  • extern void ibm_lib4gl_popQuotedStr(char *qv, int len)
  • extern void ibm_lib4gl_popString(char *qv, int len)
  • extern void ibm_lib4gl_popVarChar(char *qv, int len)
Pre-Version 7.31 name Version 7.31 and later name
popquote ibm_lib4gl_popQuotedStr
popstring ibm_lib4gl_popString
popvchar ibm_lib4gl_popVarChar

Both ibm_lib4gl_popQuotedStr( ) and ibm_lib4gl_popVarChar( ) copy exactly len bytes into the string buffer *qv. Here ibm_lib4gl_popQuotedStr( ) pads with spaces as necessary, but ibm_lib4gl_popVarChar( ) does not pad to the full length. The final byte copied to the buffer is a null byte to terminate the string, so the maximum string data length is len-1. If the stacked argument is longer than len-1, its trailing bytes are lost.

The len argument sets the maximum size of the receiving string buffer. Using ibm_lib4gl_popQuotedStr( ), you receive exactly len bytes (including trailing blank spaces and the null), even if the value on the stack is an empty string. To find the true data length of a string retrieved by ibm_lib4gl_popQuotedStr( ), you must trim trailing spaces from the popped value.
Note:
The functions ibm_lib4gl_popString( ) and ibm_lib4gl_popQuotedStr( ) are identical, except that ibm_lib4gl_popString( ) automatically trims any trailing blanks.

Library Functions for Popping Time Values

You can call the following library functions to pop DATE, INTERVAL, and DATETIME (TIMESTAMP) values:
  • extern void ibm_lib4gl_popDate(int *datv)
  • extern void ibm_lib4gl_popInterval(intrvl_t *iv, int qual)
You can call the following library function to pop TIMESTAMP values:
  • extern void ibm_lib4gl_popDateTime(dtime_t *dtv, int qual)
Pre-Version 7.31 name Version 7.31 and later name
popdate ibm_lib4gl_popDate
popdtime ibm_lib4gl_popDateTime
popinv ibm_lib4gl_popInterval

The structure types dtime_t and intrvl_t are used to represent DATETIME and INTERVAL data in a C program. The qual argument receives the binary representation of the DATETIME or INTERVAL qualifier. For more information about the dtime_t and intrvl_t structure types and library functions for manipulating and printing DATE, DATETIME, and INTERVAL variables, see the IBM® Informix® ESQL/C Programmer's Manual.

Library Functions for Popping BYTE or TEXT Values

You can call the following function to pop a BYTE or TEXT argument:
  • extern void ibm_lib4gl_popBlobLocator(loc_t **blob)
Pre-Version 7.31 name Version 7.31 and later name
poplocator ibm_lib4gl_popBlobLocator
The structure type loc_t defines a BYTE or TEXT value, and is discussed in the IBM® Informix® ESQL/C Programmer's Manual.

Any BYTE or TEXT argument must be popped as BYTE or TEXT because EGL provides no automatic data type conversion.