Ingres CL CV
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - CV
Abstract
This is the specification of the CV facility provided by the compatibility library to perform data conversions.
Revision: 2.1, 27-Mar-1997
Document History
- Revision 2.1, 27-Mar-1997
- Formatted for html.
- Revision 2.0, 29-Jul-94
- <cvgcc.h> exists as documented (17-sep-93). This obsoletes CVtolocal, CVtonet, and CVarch_char, which are removed.
- CVGCC identifiers for GCOS (24-jan-92)
- CVpka spec inconsistencies fixed (there's no fmt arg) (24-jan-92)
- CVpkf added for post-6.4 (24-jan-92).
- CVlx takes a u_longnat (7-may-93).
- CVptra, CVptrax, CVaptr, CVaxptr added (7-may-93).
- Revision 1.0, last modified 29-Aug-91
- Added CVpka and CVapk.
- Fixed some typos.
- Document correct behaviour of CVahxl as unsigned, and taking a pointer to a u_longnat instead of a longnat.
- Remove CV_C_CONST_MACRO; it's been renamed CL_C_CONST_MACRO, and lives in <compat.h>, not <cv.h>.
Specification
Introduction
The CV module provides a plethora of ways to convert numbers to strings, numbers to numbers, etc.
The floating point routines, of necessity, depend on how the system represents floating point numbers. The other routines can be written in a system independent way.
"IMPORTANT COMPATIBILITY NOTE:"
Because CVaf/CVfa are used to convert floating point numbers between string and machine representations, and because the machine representations are stored in an OpenIngres database, CVaf and CVfa must be mirror images of each other NOT only within a specific version of the CL, but ALSO across different versions of the CL. To change how they work across CL versions would introduce incompatibility between versions of database software.
Although not usually a problem, the same is true of all the conversion routines.
Library
CL
Implementing CM and CV for multinational support
The multinational version of OpenIngres requires some changes in the compatibility library for the modules CM and CV. The CV changes are required by the different formats of floating point numbers in different countries.
The implementation of the two floating point conversion routines (CVfa, CVaf) is straight forward. They are usually implemented by calls to OS routines, with simple string manipulation before or after, as appropriate.
Also, check that CVlower and CVupper use the CMtolower and CMtoupper macros. If not they should!
Header File <cv.h>
The header file <cv.h> must be included before using any of the functions provided.
Constants
The file <cv.h> defines the following constants for client use.
CV_DEC_PTR_SIZE
The number of characters needed to represent a pointer as a decimal value. This is 11 on a 32-bit machine and 22 on a 64 bit machine.
CV_HEX_PTR_SIZE
The number of characters needed to represent a pointer as a hex value. This is 8 on a 32-bit machine, and 16 on a 64-bit machine.
Header File <cvgcc.h>
This header provides a macro-level interface for the datatype conversions necessary for heterogeneous networking. It is for the sole use of INGRES/NET.
If any operation cannot be performed as a macro, a CL provider will need to provide actual functions to do the work; these are not directely part of the public CL interface
Cvgc.h would house all the system dependent information necessary to convert local to network transfer syntax and back.
Invariant Constants
These are the network sizes that don't change per-platform.
/*
** Sizes of network types. Constant sizes. Do not change.
*/
# define CV_N_I1_SZ 1
# define CV_N_I2_SZ 2
# define CV_N_I4_SZ 4
# define CV_N_F4_SZ 6
# define CV_N_F8_SZ 10
# define CV_N_CHAR_SZ 1
# define CV_N_PTR_SZ 4
# define CV_N_NAT_SZ 4
# define CV_N_LONG_SZ 4
These are local sizes that don't need to be modified.
/*
** Sizes of local types. Constant definitions. Do not change.
*/
# define CV_L_I1_SZ sizeof( i1 )
# define CV_L_I2_SZ sizeof( i2 )
# define CV_L_I4_SZ sizeof( i4 )
# define CV_L_F4_SZ sizeof( f4 )
# define CV_L_F8_SZ sizeof( f8 )
# define CV_L_CHAR_SZ sizeof( char )
# define CV_L_PTR_SZ sizeof( PTR )
# define CV_L_NAT_SZ sizeof( i4 )
# define CV_L_LONG_SZ sizeof( i4 )
These are used to identify commonly known native machine types, and don't change.
/* ** Name: CV_xxxx_yyy - local syntax ids for atomic datatypes ** ** Description: ** These defines enumerate the various processor specific formats ** for ints and floats. These we call the local syntax ids. ** (Character conversion is undergoing change). New ** representations of ints and floats should be given names and ** ids (0<=id<=127). ** ** When two IIGCC's establish a connection, they compare the ** datatype ids of the processors at each end of the connection. ** If the ids for a datatype are different, that datatype undergoes ** conversion when traveling through the IIGCC. The id -1 matches ** no other ids, and forces conversion. ** ** Note that a single id represents the size and byte ordering ** of both ints and longs. A single id represents the size and ** bit patterns for both a float and a double. ** */ # define CV_HET_TYPE -1 /* Forces het conversion */ # define CV_LH3232_INT 0 /* VAX - lo to hi - 32bit int, long */ # define CV_HL3232_INT 1 /* SUN - hi to lo - 32bit int, long */ # define CV_BG3636_INT 2 /* BULL GCOS 36 bit int, long */ # define CV_LH3264_INT 3 /* Alpha - lo to hi - 32bit int, 64bit long */ # define CV_VAX_FLT 0 /* VAX floats */ # define CV_HL_FLT 1 /* IEEE floats - hi to lo */ # define CV_DRS_FLT 2 /* DRS 500 floating point */ # define CV_LH_FLT 3 /* IEEE floats - lo to hi */ # define CV_CONVEX_FLT 4 /* Convext floats */ # define CV_IBM_FLT 5 /* IBM 360/370 floats */ # define CV_BULLG_FLT 6 /* BULL GCOS floats */ # define CV_PC_FLT 10 /* IBM PC 80x86 floats */ # define CV_ASCII_NCSJ 0x00 /* ASCII */ # define CV_ASCII_NCSN 0x00 # define CV_8859_NCSJ 0x00 /* ISO_8859_1 */ # define CV_8859_NCSN 0x01 # define CV_PC_NCSJ 0x00 /* ASCII_IBMPC */ # define CV_PC_NCSN 0x10 # define CV_EBCDIC_NCSJ 0x01 /* EBCDIC_C */ # define CV_EBCDIC_NCSN 0x00 # define CV_EBCICL_NCSJ 0x01 /* EBCDIC_ICL */ # define CV_EBCICL_NCSN 0x01
The implementor then chooses the right types above and sets the following symbols to the appropriate values, and provides macros for the conversions below. These are commonly handled inside ifdef blocks around the config string.
/*
** Processor specific formats and conversion routines.
*/
# ifdef sun
# define CV_INT_TYPE CV_SUN_INT
# define CV_FLT_TYPE CV_IEEE_FLT
# define CV_NCSJ_TYPE CV_USA_NCSJ
# define CV_NCSN_TYPE CV_ASCII_NCSN
# endif
And later in the file, the following macros must be defined to do the conversions.
CV2x_yy_MACRO - convert datatype from local to NTS and back
Macros to convert from local to Network Transport Syntax (NTS) and back.
| CV2N_I1_MACRO | convert i1 to NTS |
| CV2N_I2_MACRO | convert i2 to NTS |
| CV2N_I4_MACRO | convert i4 to NTS |
| CV2N_NAT_MACRO | convert i4 to NTS |
| CV2N_LONG_MACRO | convert i4 to NTS |
| CV2N_F4_MACRO | convert f4 to NTS |
| CV2N_F8_MACRO | convert f8 to NTS |
| CV2L_I1_MACRO | convert i1 to local |
| CV2L_I2_MACRO | convert i2 to local |
| CV2L_I4_MACRO | convert i4 to local |
| CV2L_NAT_MACRO | convert i4 to local |
| CV2L_LONG_MACRO | convert i4 to local |
| CV2L_F4_MACRO | convert f4 to local |
| CV2L_F8_MACRO | convert f8 to local |
NTS for I1, I2, and I4 is a VAX int of the same size (lo-hi byte order).
NTS for I4 and LONG is the same as for the I4. Truncation may occur on 16 bit int or 64 bit long machines.
NTS for F4 and F8 is described in cvgcc.c.
Inputs:
| src | pointer to source data; element may be unaligned |
| dst | pointer to target area; element may be unaligned |
| status | pointer to status; set only upon error, so it should be cleared before an invocation. |
Outputs:
| dst | receives the converted item. |
| status | set on error, otherwise untouched. |
Returns:
| None |
Executable Interface
The following function-like interfacess are provided.
CVaf - Convert alpha-numeric to floating.
Convert a string containing a floating point number to floating point. The syntax of the number is as follows:
{<sp>} [+|-] {<sp>} {<digit>} [<decimal>{digit}] {<sp>} [<exp>]
Where <exp> is e or E followed by an integer, <sp> is a space character, <digit> is zero through nine, [] is zero or one, and {} is zero or more.
CVaf functionality must remain the same between CL versions to avoid introducing incompatibilities between releases of OpenIngres.
Inputs:
| str | String containing the number. |
| decimal | Decimal character to use |
Outputs:
| val | Where to store the result. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CV_UNDERFLOW | |
| CV_OVERFLOW | |
| CV_SYNTAX |
Definition:
STATUS CVaf(str, decimal, val) char *str; char decimal; f8 *val;
CVahxl - Convert hex alpha-numeric to unsigned longnat
Convert hex alpha-numeric to unsigned longnat.
CVahxl converts an alpha-numeric text string representation of an unsigned hexadecimal value to an unsigned i4 value.
A valid string is of the form:
{<sp>} {<digit>|<a-f>} {<sp>}
Inputs:
| str | string to convert. Valid input characters are the space, the digits 0 through 9, and the letters A through F lowercase a through f are acceptable as well). NO SIGN IS PERMITTED. |
Outputs:
| result | filled in with unsigned i4 value. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CV_SYNTAX |
Definition:
STATUS CVahxl(str, result) char *str; u_i4 *result;
CVal - Convert alpha-numeric to i4
Convert alpha-numeric to i4. A valid string is of the form:
{<sp>} [+|-] {<sp>} {<digit>} {<sp>}
Inputs:
| a | string to convert. |
Outputs:
| i | filled in with longnat value. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CV_SYNTAX | |
| CV_OVERFLOW |
Definition:
STATUS CVal(a, i) char *a; i4 *i;
CVan - Convert alpha-numeric to i4
Convert alpha-numeric to ni4. A valid string is of the form:
{<sp>} [+|-] {<sp>} {<digit>} {<sp>}
Inputs:
| string | String holding alpha-numeric representation of a natural integer. |
Outputs:
| num | The natural integer represented in the input string will be placed here. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CV_SYNTAX | |
| CV_OVERFLOW |
Definition:
STATUS CVan(string, num) char *string; i4 *num;
CVaptr - convert buffer in unsigned decimal characters to a pointer
Converts the input buffer in unsigned decimal representation to a pointer value.
Possible errors include a string that is a value wider than can be represented as a pointer.
This is the exact inverse of CVptra.
Inputs:
| buf | input buffer, assumed to be in unsigned decimal. |
Outputs:
| ptrp | pointer to pointer to stuff. |
Returns:
| OK |
| other error status. |
Definition:
STATUS CVaptr( char *buf, PTR *ptrp );
CVaxptr - convert buffer in unsigned hex characters to a pointer
Converts the input buffer in unsigned hexadecimal representation to a pointer value.
Possible errors include a string that is a value wider than can be represented as a pointer.
This is the exact inverse of CVptrax.
Inputs:
| buf | input buffer, assumed to be in unsigned hex. |
Outputs:
| ptrp | pointer to pointer to stuff. |
Returns:
| OK |
| other error status. |
Definition:
STATUS CVaxptr( char *buf, PTR *ptrp );
CVapk - Convert string to packed decimal
Converts a null terminated character string into a packed decimal value with the requested precision and scale. Acceptable syntax is:
[ '+' | '-' ] digit {digit} [ '.' {digit} ] or
[ '+' | '-' ] '.' digit {digit}
Examples:
| 1 |
| +1234 |
| 12. |
| -12.345 |
| .1 |
| +.1234 |
| -.12 |
Leading and trailing white space and leading zeros are ignored. The status returned will always be the most severe status encountered; all statuses are listed below in order of increasing severity.
Inputs:
| string | The null terminated string representing the decimal value. |
| decpt | Decimal character in use. If this is zero then '.' is used. |
| prec | Precision for result: 1 <= prec <= 31. |
| scale | Scale for result: 0 <= scale <= prec. |
Outputs:
| pk | The resulting packed decimal value is placed here. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CV_TRUNCATE | Some fractional digits had to be truncated in order to use scale. |
| CV_OVERFLOW | Integral part has too many digits (not including leading zeros) i.e. more than (prec - scale) of them. |
| CV_SYNTAX | Could not convert due to syntax error. |
Definition:
STATUS CVapk(string, decpt, prec, scale, pk) char *string; char decpt; i4 prec; i4 scale; PTR pk;
CVfa - Convert floating to alpha-numeric
Convert floating to alpha-numeric.
Converts the double stored in num to a string stored in result having given width precision and fmt. Valid values for fmt are 'e', 'f', 'g', and 'n'. The 'f' format specifies numeric expressions with or without decimal point as implied by the precision. The 'e' format specifies scientific notation. The \&'g' format specifies 'e' or 'f' format depending on what fits. This format also guarantees that decimal points align, whether printed in 'e' or 'f'. The 'n' format is the same as 'g', but the decimal points don't necessarily align. Returns the width of the output field in res_width. CVfa requires the following restriction: width >= (prec > 0) ? 7 : 6. If decimal is not zero, then its value is used in place of '.' as the decimal point.
WARNING: res_width must be a pointer to an i2!
CVfa functionality must remain the same between versions of the CL to avoid introducing incompatibilities between releases of OpenIngres.
Inputs:
| value | value to be converted |
| width | the width of the formatted item |
| prec | number of digits of precision |
| format | format type (e,f,g,n) |
| decimal | character to use as the decimal char |
Outputs:
| ascii | where to put the converted value |
| res_width | where to put the width of the output field |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CV_TOO_WIDE |
Definition:
STATUS CVfa(value, width, prec, format, decimal, ascii, res_width) f8 value; i4 width; i4 prec; char format; char decimal; char *ascii; i2 *res_width;
CVla - Convert long to alpha-numeric
Converts the long integer num to alpha-numeric and stores the result in string, which is assumed to be large enough.
Inputs:
| i | i4 to convert. |
Outputs:
| a | character buffer written. |
Returns:
| None |
Definition:
VOID CVla(i, a) i4 i; char *a;
CVlower - Convert string to lowercase
Convert all characters in string to lowercase in place.
Inputs:
| string | to convert. |
Outputs:
| string | converted string. |
Returns:
| None |
Definition:
VOID CVlower(string) char *string;
CVlx - Convert unsigned i4 to alpha-numeric hex
Converts the long integer num to hexadecimal alpha-numeric and stores the result in string, which is assumed to be large enough.
Inputs:
| num | signed longnat to convert. |
Outputs:
| string | written buffer. |
Returns:
| None |
Definition:
VOID CVlx(num, string) u_i4 num; char *string;
CVna - Convert nat to alpha-numeric
Converts the natural integer num to alpha-numeric and stores the result in string, which is assumed to be large enough.
Inputs:
| num | Natural integer to be converted to an alpha-numeric string. |
Outputs:
| string | Ascii string representing the integer. |
Returns:
| None |
Definition:
VOID CVna(num, string) i4 num; char *string;
CVol - Convert octal to long
Convert octal alpha-numeric to long.
Inputs:
| octal | string to convert. |
Outputs:
| result | i4 value filled in. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CV_SYNTAX |
Definition:
STATUS CVol(octal, result) char octal[]; i4 *result;
CVpka - Convert packed decimal to string
Converts a packed decimal value into a null terminated character string. The caller describes how the output string should be formatted by supplying information on the field width to use, the number of fractional digits, whether to truncate or round, whether to right or left justify, and whether to use 'zero filling' or not.
Usage notes:
The output string is assumed to be at least 'field_wid' + 1 bytes long.
Negative zero is printed as positive 0.
No sign will be displayed for positive numbers. A minus sign will be displayed just to the left of the left most digit displayed.
No decimal point will be displayed if the number of fractional digits being requested is zero.
By default (i.e. not using CV_PKROUND), if there are more scale digits in the decimal value than fractional digits requested, the extra digits will be truncated.
By default (i.e. not using CV_PKLEFTJUST), the ouput string will be right justified, with blank padding on the left if necessary. No blank padding on the right will be done when using CV_PKLEFTJUST; the null terminater will immediately follow the last displayed digit.
By default (i.e. not using CV_PKZEROFILL), leading zeros are converted to blanks. However, if all digits in integral portion of number are 0 then a single 0 is output, unless that would cause the CV_OVERFLOW condition.
Inputs:
| pk | Pointer to the decimal value. | |
| prec | Its precision: 1 <= prec <= 31. | |
| scale | Its scale: 0 <= scale <= prec. | |
| decpt | Decimal character in use. If this is zero then '.' is used. | |
| field_wid | Output field width; that is, the number of characters to use in displaying the decimal value. It is assumed that 'string' is at least 'field_wid' + 1 bytes long. | |
| frac_digs | The number of digits to place to the right of the decimal point. | |
| options | Formatting options; any combination of the following may be ``OR'ed together: | |
| CV_PKROUND | Do rounding instead of truncation, which is the default. | |
| CV_PKLEFTJUST | Left justify the output instead of right justifying, which is the default. | |
| CV_PKZEROFILL | Fill up the entire field width by placing however many leading zeros required to do so. Default is to blank pad. As an example, the number -10.453 placed into an output string where 'field_wid' = 8 and 'frac_digs' = 2 will normally be displayed as " -10.45". If the CV_PKZEROFILL option is being used it will be displayed as "-0010.45". |
Outputs:
| string | The null terminated string representing the decimal value in the format specified. |
| res_len | The length in bytes, including the '\0' terminator, of the result string, `str'. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| CV_TRUNCATE | Some fractional digits were either truncated or rounded in order to use `frac_digs'. |
| CV_OVERFLOW | String was not big enough to hold the output in the desired format. |
Definition:
STATUS CVpka(pk, prec, scale, field_wid, frac_digs, decpt, options, str, res_len) PTR pk; i4 prec; i4 scale; i4 field_wid; i4 frac_digs; char decpt; i4 options; char *str; i4 *res_len;
Examples:
pk (prec,scale) = 10.456 (5,3) field_wid = 10 frac_digs = 2 options = 0;
status will be: OK string will be: " 10.45"
pk (prec,scale) = 10.456 (5,3) field_wid = 10 frac_digs = 2 options = CV_PKLEFTJUST;
status will be: OK string will be: "10.45"
pk (prec,scale) = -10.456 (5,3) field_wid = 10 frac_digs = 2 options = CV_PKLEFTJUST;
status will be: OK string will be: "-10.45"
pk (prec,scale) = 10.456 (5,3) field_wid = 5 frac_digs = 2 options = CV_PKLEFTJUST;
status will be: OK string will be: "10.45"
pk (prec,scale) = -10.456 (5,3) field_wid = 5 frac_digs = 2 options = CV_PKLEFTJUST;
status will be: CV_OVERFLOW string will be: <undefined>
pk (prec,scale) = 10.456 (5,3) field_wid = 10 frac_digs = 2 options = CV_PKZEROFILL;
status will be: OK string will be: "0000010.45"
pk (prec,scale) = -10.456 (5,3) field_wid = 10 frac_digs = 2 options = CV_PKZEROFILL;
status will be: OK string will be: "-000010.45"
pk (prec,scale) = -10.456 (5,3) field_wid = 10 frac_digs = 2 options = CV_PKLEFTJUST | CV_PKZEROFILL;
status will be: OK string will be: "-000010.45"
pk (prec,scale) = .456 (3,3) field_wid = 10 frac_digs = 2 options = 0;
status will be: OK string will be: " 0.45"
pk (prec,scale) = .456 (3,3) field_wid = 3 frac_digs = 2 options = 0;
status will be: OK string will be: ".45"
pk (prec,scale) = .456 (3,3) field_wid = 3 frac_digs = 2 options = CV_PKROUND;
status will be: OK string will be: ".46"
CVpkf - Convert packed decimal to float
Converts a packed decimal value into an eight byte float.
Inputs:
| pk | Pointer to the decimal value. |
| prec | Its precision: 1 <= prec <= 31. |
| scale | Its scale: 0 <= scale <= prec. |
Outputs:
| fnum | The eight byte float result. |
Returns:
| OK | Success. |
Exceptions:
| none |
Side Effects:
| none |
Definition:
STATUS CVpkf(pk, prec, scale, fnum) PTR pk; i4 prec; i4 scale; f8 *fnum;
CVptra - convert pointer to unsigned decimal character representation
Converts the input pointer to an unsigned decimal representation, occupying exactly CV_DEC_PTR_SIZE characters, plus a null termination.
Fixed width, zero padded output is important to the major clients of this interface, MO get and set methods.
Note that CV_DEC_PTR_SIZE will be larger on 64 bit machines than on 32 bit systems.
This is the exact inverse of CVaptr.
Inputs:
| ptr | pointer to convert |
Outputs:
| buf | destination buffer, assumed to be at least CV_DEC_PTR_SIZE + 1 in length. |
Returns:
| none |
Definition:
void CVptrax( PTR ptr, char *buf );
CVptrax - convert pointer to unsigned hex character representation
Converts the input pointer to an unsigned hexadecimal representation, occupying up to CV_HEX_PTR_SIZE characters, plus a null termination. If necessary, the output is padded with leading zeros.
Note that CV_HEX_PTR_SIZE will be larger on 64 bit machines than on 32 bit systems.
This is the exact inverse of CVaxptr.
Inputs:
| ptr | pointer to convert |
Outputs:
| buf | destination buffer, assumed to be at least CV_HEX_PTR_SIZE + 1 in length. |
Returns:
| none |
Definition:
void CVptra( PTR ptr, char *buf );
CVupper - Convert string to uppercase
Convert all characters in string to uppercase in place.
Inputs:
| string | to convert. |
Outputs:
| string | as converted. |
Returns:
| None |
Definition:
VOID CVupper(string) char *string;
|
Ingres Compatability Library |
