Extreme 5

Adding Hexadecimal Conversion Functionality
As a Persistent Stored Module (PSM) to Empress

1. Introduction

The purpose of this technical note is two-fold:

1. Convert data to hexadecimal values
2. Demonstrate how to write a polymorphic function

This technical note will guide user through the steps that are needed to create one new function that will allow user to:

1. Convert integers to its equivalent hexadecimal string
2. Convert character data to its equivalent hexadecimal string

The respective function, built by using Empress SQL Persistent Stored Module (PSM) technology, is named:

to_hex

For example, SELECT command which incorporates the above function (id is a table attribute of an integer data type while a data is an attribute ofa character data type):

SELECT id, to_hex(id), data, to_hex(data) FROM t1 LIST;

could generate the following results:



                                                

                                                    
id: -2147483647
TO_HEX(id): 80000001
data: SMALL INTEGER
TO_HEX(data): 534d414c4c20494e5445474552

id: 2147483647
TO_HEX(id): 7fffffff
data: BIG INTEGER
TO_HEX(data): 42494720494e5445474552
                                                
                                            

Implementation

The basic algorithm is as follows:

1. convert integer data to its equivalent hexadecimal value via the C library sprintf.
2. convert character data to its equivalent hexadecimal value via the C library sprintf.

APPENDIX

The following script can be executed with EMPRESS RDBMS V8.62 installed on a UNIX system in order to acquire the above described functionality.

#!/bin/sh

if [ -z $EMPRESSPATH ]
then
        echo "This demo requires that EMPRESSPATH is set."
        exit 1
fi

cat > ./module.c <<EOM
#include <mscc.h>
#include <usrfns.h>
#include <stdio.h>
#include <string.h>

/*
*
* Par1: input:  character data
* Par2: output: hexadecimal string
* Par3: control variable for input/output parameter 1
* Par4: control variable for output parameter 1
* Par5: status variable [whether or not function was alright, maxlength = 5]
* Par6: runtime name [filled in by Empress]
* Par7: external name of function [filled in by Empress]
* Par8: error message [maxlength is 256]
*/

GLOBAL_SHARED_FUNC void to_hex_char     (
                                        char*           input_str,
                                        char**          out,
                                        long*           in_ctrl1,
                                        long*           out_ctrl1,
                                        char*           sqlstate,
                                        char*           rtname,
                                        char*           extname,
                                        char*           errmsg
                                        )
{
        char*   buf;
        int     len;
        int     i;
        int     j;

        /* Set the output to be null */
        *out_ctrl1 = -1L;
        *out = (char) 0;

        /* input_str should not be zero, but check just in case */
        if (input_str == 0 && *in_ctrl1 >= 0)
        {
                strcpy (sqlstate, "INPUT");
                strcpy (errmsg,
                        "Problem: INPUT string is null");
                return;
        }
        /* If the first parameter is null, just return null */
        if (*in_ctrl1 == -1L)
        {
                strcpy (sqlstate, "INPUT");
                strcpy (errmsg,
                        "Problem: INPUT string is null");
                return;
        }

        /* We want to allocate enough space for hexadecimal string
         * one input byte = 2 output bytes (ie: 5 = 05 ) */
        len = strlen (input_str);
        buf = (char*) mspsm_malloc ((len *2)  +1);

        *out_ctrl1 =  0L;
        for (i = 0, j=0; i < len; i++, j+=2)
        {
                sprintf (buf +j, "%2.2x", *(input_str +i));
        }
        *out = buf;
}

/*
*
* Par1: input:  integer data
* Par2: output: hexadecimal string
* Par3: control variable for input/output parameter 1
* Par4: control variable for output parameter 1
* Par5: status variable [whether or not function was okay, maxlength = 5]
* Par6: runtime name [filled in by Empress]
* Par7: external name of function [filled in by Empress]
* Par8: error message [maxlength is 256]
*/

GLOBAL_SHARED_FUNC void to_hex_int      (
                                        gen_integer     input_num,
                                        char**          out,
                                        long*           in_ctrl1,
                                        long*           out_ctrl1,
                                        char*           sqlstate,
                                        char*           rtname,
                                        char*           extname,
                                        char*           errmsg
                                        )
{
        char*           buf;

        /* Set the output to be null */
        *out_ctrl1 = -1L;
        *out = (char) 0;

        /* If the first parameter is null, just return null */
        if (*in_ctrl1 == -1L)
        {
                strcpy (sqlstate, "INPUT");
                strcpy (errmsg,
                        "Problem: INPUT integer is null");
                return;
        }

        /* one input byte = 2 output bytes (ie: 5 = 05 ) */
        buf = (char*) mspsm_malloc ((sizeof(gen_integer) *2)  +1);

        *out_ctrl1 =  0L;
        if (input_num <= (unsigned long) 0xff)
                sprintf (buf, "%2.2lx", input_num);
        elif (input_num <= (unsigned long) 0xffff)
                sprintf (buf, "%4.4lx", input_num);
        elif (input_num <= (unsigned long) 0xffffff)
                sprintf (buf, "%6.6lx", input_num);
        elif (input_num <= (unsigned long) 0xffffffff)
                sprintf (buf, "%8.8lx", input_num);
        else
        {
                *out_ctrl1 =  -1L;
                buf[0] = '\0';
        }
        *out = buf;
}
EOM

echo "Creating the shared object 'module.dll'."
emppsmcc -o module.dll module.c


if [ -d db ]
then
        echo "Removing 'db'"
        emprmdb db
fi
echo "Creating 'db'"
empmkdb db

empbatch db <<EOM
!echo "Creating and defining module 'Hexadecimal'."
CREATE MODULE Hexadecimal
        FUNCTION to_hex (GENERIC CHAR)
        RETURNS GENERIC CHAR
        EXTERNAL NAME to_hex_char
        PARAMETER STYLE SQL;
        FUNCTION to_hex (GENERIC INTEGER)
        RETURNS GENERIC CHAR
        EXTERNAL NAME to_hex_int
        PARAMETER STYLE SQL;
END MODULE;
CREATE TABLE t1 (id longinteger, data nlstext(80,1024,1024,1));
INSERT INTO t1 VALUES (
-2147483647, "SMALL INTEGER",
2147483647, "BIG INTEGER");

UPDATE MODULE Hexadecimal FROM './module.dll';

SELECT to_hex(id), id, to_hex(data), data FROM t1 LIST;
EOM

rm module.c module.dll