You can write the conversion routine in any language that conforms to the standard calling and argument-passing conventions, although we recommend C.

 

This is the C prototype for a conversion function:

 

int APIENTRY conv_rtn_name (char         *pField,

                            unsigned int wType,

                            unsigned int wFieldLen,

                            unsigned int wOpCode,

                            PEASELTYPE   pData,

                            char         *pArg);

 

int is the value returned by the external conversion routine upon completion. It should be 0 if the conversion was successful. It should be non-zero if the conversion was unsuccessful.

 

pField is a pointer to the field within ESL memory where the data to be converted resides or where the converted data will be stored, depending on the direction of the conversion specified by wOpCode. pField is the target field for the data to be converted if wOpCode is CONVERT_TO_EXTERNAL. pField is the source field for the converted data if wOpCode is CONVERT_TO_EASEL.

 

wType is an unsigned int that specifies the type of ESL variable being converted. (Note that wType can be any type specified by the ESL developer. The writer of the external conversion routine must ensure that the routine returns a non-zero value and writes a message to the errorlog for any ESL type it cannot convert.)

 

wFieldLen is the length of the field (pointed to by pField) within the ESL structure. This argument is taken from the size specification in the using clause for the field. The external conversion routine should never read or write data beyond the length specified by wFieldLen.

 

wOpCode is an unsigned int that specifies the direction of the conversion. This value will always be one of the following constants, defined in the include file ESLTYPE.H:

 

CONVERT_TO_EASEL 

CONVERT_TO_EXTERNAL

 

If wOpCode is CONVERT_TO_EASEL, the external conversion routine should convert the data pointed to by pField to the ESL type for the field specified by wType, and store the converted value in the location pointed to by pData, as described below.

 

If the routine receives CONVERT_TO_EXTERNAL, it should convert the ESL value supplied in pData to the external storage format for the field, verify that the conversion was successful, and write the converted value to the location pointed to by pField, which points to the actual external field.

 

pData is a pointer to a data structure defined in ESLTYPE.H. This is actually a pointer to a C-language union that contains three C- language fields:

 

#pragma pack (1)

typedef union _EaselType 

{         

long                 Integer; 

double                Float; 

HSTRING            hString;

} 

EASELTYPE, *PEASELTYPE;

#pragma pack ()

 

These three types correspond to the three possible ESL types that can be specified for a field:  integer, float, or string.

 

If the wOpCode parameter is CONVERT_TO_EASEL, then the routine must convert the data pointed to by the pField parameter into the ESL type specified by the wType parameter. The conversion routine must also store the converted value in the appropriate field within the pData union.

 

pArg is a pointer to a null-terminated character string. There are no requirements for how the external conversion routine interprets this string. When the conversion routine is called, the string contains whatever value was specified following the format keyword in the using clause. This provides a way to specify additional information to the routine. External conversion routines should always check the pArg pointer to make sure it is not NULL, before attempting to dereference it.