Runtime stack functions

To pass values between a C function and a program, the C function and the runtime system use the runtime stack. The int parameter of the C function defines the number of input parameters passed on the stack, and the function must return an int value defining the number of values returned on the stack. The parameters passed to the C function must be popped from the stack at the beginning of the C function, and the return values expected by the 4gl call must be pushed on the stack before leaving the C function. If you don't pop / push the specified number of parameters / return values, you corrupt the stack and get a fatal error.

The runtime system library includes a set of functions to retrieve the values passed as parameters on the stack. This table shows the library functions provided to pop values from the stack into C buffers:

Table 1. Library functions provided to pop values from the stack into C buffers
Function	Data type	Details
`void popdate(int4 *dst);`	`DATE`	4-byte integer value corresponding to days since12/31/1899.
`void popboolean(signed char *dst);`	`BOOLEAN`	1-byte integer boolean (1/0/-1)
`void popbigint(bigint *dst);`	`BIGINT`	8-byte integer value
`void popint(mint *dst);`	`INTEGER`	System dependent integer value (int)
`void popshort(int2 *dst);`	`SMALLINT`	2-byte integer value
`void poplong(int4 *dst);`	`INTEGER`	4-byte integer value
`void popflo(float *dst);`	`SMALLFLOAT`	4-byte floating point value
`void popdub(double *dst);`	`FLOAT`	8-byte floating point value
`void popdec(dec_t *dst);`	`DECIMAL`	See structure definition in $FGLDIR/include/f2c headers
`void popquote(char *dst, int len);`	`CHAR(n)`	len = strlen(val)+1 (for the '/0')
`void popvchar(char *dst, int len);`	`VARCHAR(n)`	len = strlen(val)+1 (for the '/0')
`void popdtime(dtime_t *dst, int size);`	`DATETIME`	See structure definition in $FGLDIR/include/f2c headers size = TU_DTENCODE(start, end)
`void popinv(intrvl_t* dst, int size);`	`INTERVAL`	See structure definition in $FGLDIR/include/f2c headers size = TU_IENCODE(len, start, end)
`void poplocator(loc_t **dst);`	`BYTE`, `TEXT`	See structure definition in $FGLDIR/include/f2c headers Important: this function pops the pointer of a loc_t object!

When using a pop function, the value is copied from the stack to the local C variable and the value is removed from the stack.

In programs, Strings (CHAR, VARCHAR) are not terminated by '\0'. Therefore, the C variable must-have one additional character to store the '\0'. For example, the equivalent of a VARCHAR(100) in programs is a char x[101] in C.

To return a value from the C function, you must use one of these functions provided in the runtime system library:

Table 2. Functions provided in the runtime system library to return a value from a C function.
Function	Data type	Details
`void pushdate(int4 val);`	`DATE`	4-byte integer value corresponding to days since12/31/1899.
`void pushdec(const dec_t* val, const unsigned decp);`	`DECIMAL`	See structure definition in $FGLDIR/include/f2c headers
`void pushboolean(const signed char);`	`BOOLEAN`	1-byte integer boolean (1/0/-1)
`void pushbigint(bigint val);`	`BIGINT`	8-byte integer value
`void pushint(mint val);`	`INTEGER`	System dependent integer value (int)
`void pushlong(int4 val);`	`INTEGER`	4-byte integer value
`void pushshort(int2 val);`	`SMALLINT`	2-byte integer value
`void pushflo( float* val);`	`SMALLFLOAT`	4-byte floating point value. Important: function takes a pointer!
`void pushdub( double* val);`	`FLOAT`	8-byte floating point value. Important: function takes a pointer!
`void pushquote(const char *val, int l);`	`CHAR(n)`	len = strlen(val) (without '\0')
`void pushvchar(const char *val, int l);`	`VARCHAR(n)`	len = strlen(val) (without '\0')
`void pushdtime(const dtime_t *val);`	`DATETIME`	See structure definition in $FGLDIR/include/f2c headers
`void pushinv(const intrvl_t *val);`	`INTERVAL`	See structure definition in $FGLDIR/include/f2c headers

When using a push function, the value of the C variable is copied at the top of the stack.