Appendix C: Creating C Components

Parameter datatypes

“Datatypes for C method implementation functions” shows the datatypes displayed in EAServer Manager, the datatypes used by C components, and the argument modes. The left column contains the datatype name as it displays in EAServer Manager. The second and third columns contain the names of the corresponding C datatypes for input, inout, and output parameters.

If the EAServer Manager method definition returns a value other than ResultSet or ResultSets, an additional output parameter is added to the front of the implementation function’s parameter list. This additional parameter receives the “logical return code” for the method invocation, as described in “Logical method return values”.

Datatypes for C method implementation functions

EAServer Manager	Mode	C Datatype
boolean	input inout, output, return	CS_BIT CS_BIT *
byte (a single byte)	input inout, output. return	CS_BINARY CS_BINARY *
char (a single character)	input inout, output. return	CS_CHAR CS_CHAR *
float	input inout, output. return	CS_REAL CS_REAL *
double	input inout, output. return	CS_FLOAT CS_FLOAT *
integer<16>	input inout, output. return	CS_SMALLINT CS_SMALLINT *
integer<32>	input inout, output. return	CS_INT CS_INT *
integer<64>	input inout, output. return	CS_LONG CS_LONG *
binary	input inout, output. return	CS_BINARY_HOLDER * CS_BINARY_HOLDER *
string	input inout, output. return	CS_LONGCHAR_HOLDER * CS_LONGCHAR_HOLDER *
string<255>	input inout, output. return	CS_CHAR * CS_CHAR *
timestamp	input inout, output. return	CS_DATETIME CS_DATETIME *

Argument modes

Argument modes specify how an argument is passed. Arguments can have one of these modes:

Input - read-only; arguments are passed by value.
Inout - read/write; arguments are passed by reference.
Output – same as inout, except that input values are ignored.
Return – the method returns a value of this datatype. See “Logical method return values”.

All parameters specified as input are passed by value except for those parameters declared as string, string<255>, or binary in EAServer Manager. Except for binary and string parameters, EAServer always preallocates sufficient space for inout, output, or return parameters. binary and string parameters are mapped to special datatypes, and you may need to reallocate space for the output value as described below.

string<255> parameters

string<255> parameters are passed as a CS_CHAR *. On input, EAServer null-terminates CS_CHAR parameter values using the length meta-information associated with the datatype. On output, updated CS_CHAR parameter values must be null-terminated.

string<255> parameter values cannot be longer than 255 bytes. Use string parameters if your application requires larger values.

string and binary parameters

string parameters are passed in a CS_STRING_HOLDER structure. binary parameters are passed in a CS_BINARY_HOLDER structure. These structures are defined in jagpublic.h as follows:

typedef struct _cs_longchar_holder
{
        CS_LONGCHAR *value;
        CS_INT length;
} CS_STRING_HOLDER;

typedef struct _cs_longbinary_holder
{
        CS_LONGBINARY *value;
        CS_INT length;
} CS_BINARY_HOLDER;

#define CS_LONGCHAR_HOLDER    CS_STRING_HOLDER
#define CS_LONGBINARY_HOLDER  CS_BINARY_HOLDER

To allow backward compatibility with code that was written for EAServer version 1.1, you can use CS_LONGCHAR_HOLDER in place of CS_STRING_HOLDER, and CS_LONGBINARY_HOLDER in place of CS_BINARY_HOLDER.

On input, the value field contains the input value and the length field specifies the input length. For output, you can set a new value and length in the structure as follows:

If the output value is longer than the input length, you must reallocate memory for the value and reset the value and length fields. Use the JagFree and JagAlloc routines as shown in the example below.
If the output value is not longer than the input length, you can copy the output value directly into the buffer addressed by the input value pointer and reset the length field.

The following example calls the JagFree and JagAlloc routines to reallocate a larger value buffer:

JagFree(myholder->value);
myholder->value = JagAlloc(new_length);
if (myholder->value == NULL)
{
    JagLog(JAG_TRUE, “Out of memory!\n”);
    return CS_FAIL;
}
memcpy(myholder->value, new_value, new_length);
myholder->length = new_length;

NULLs

NULLs cannot be passed to or returned by method calls. Instead of using NULL for string parameters, pass zero-length values.

View this book as PDF