Request a pointer to a newly allocated numeric variable.

numeric *PGTYPESnumeric_new(void);

Free a numeric type, release all of its memory.

void PGTYPESnumeric_free(numeric *var);

Parse a numeric type from its string notation.

numeric *PGTYPESnumeric_from_asc(char *str, char **endptr);

Valid formats are for example:-2,.794,+3.44,592.49E07or-32.84e-4. If the value could be parsed successfully, a valid pointer is returned, else the NULL pointer. At the moment ECPG always parses the complete string and so it currently does not support to store the address of the first invalid character in*endptr. You can safely setendptrto NULL.

Returns a pointer to a string allocated bymallocthat contains the string representation of the numeric typenum.

char *PGTYPESnumeric_to_asc(numeric *num, int dscale);

The numeric value will be printed withdscaledecimal digits, with rounding applied if necessary.

Add two numeric variables into a third one.

int PGTYPESnumeric_add(numeric *var1, numeric *var2, numeric *result);

The function adds the variablesvar1andvar2into the result variableresult. The function returns 0 on success and -1 in case of error.

Subtract two numeric variables and return the result in a third one.

int PGTYPESnumeric_sub(numeric *var1, numeric *var2, numeric *result);

The function subtracts the variablevar2from the variablevar1. The result of the operation is stored in the variableresult. The function returns 0 on success and -1 in case of error.

Multiply two numeric variables and return the result in a third one.

int PGTYPESnumeric_mul(numeric *var1, numeric *var2, numeric *result);

The function multiplies the variablesvar1andvar2. The result of the operation is stored in the variableresult. The function returns 0 on success and -1 in case of error.

Divide two numeric variables and return the result in a third one.

int PGTYPESnumeric_div(numeric *var1, numeric *var2, numeric *result);

The function divides the variablesvar1byvar2. The result of the operation is stored in the variableresult. The function returns 0 on success and -1 in case of error.

Compare two numeric variables.

int PGTYPESnumeric_cmp(numeric *var1, numeric *var2)

This function compares two numeric variables. In case of error,INT_MAXis returned. On success, the function returns one of three possible results:

• 1, ifvar1is bigger thanvar2

• -1, ifvar1is smaller thanvar2

• 0, ifvar1andvar2are equal

Convert an int variable to a numeric variable.

int PGTYPESnumeric_from_int(signed int int_val, numeric *var);

This function accepts a variable of type signed int and stores it in the numeric variablevar. Upon success, 0 is returned and -1 in case of a failure.

Convert a long int variable to a numeric variable.

int PGTYPESnumeric_from_long(signed long int long_val, numeric *var);

This function accepts a variable of type signed long int and stores it in the numeric variablevar. Upon success, 0 is returned and -1 in case of a failure.

Copy over one numeric variable into another one.

int PGTYPESnumeric_copy(numeric *src, numeric *dst);

This function copies over the value of the variable thatsrcpoints to into the variable thatdstpoints to. It returns 0 on success and -1 if an error occurs.

Convert a variable of type double to a numeric.

int PGTYPESnumeric_from_double(double d, numeric *dst);

This function accepts a variable of type double and stores the result in the variable thatdstpoints to. It returns 0 on success and -1 if an error occurs.

Convert a variable of type numeric to double.

int PGTYPESnumeric_to_double(numeric *nv, double *dp)

The function converts the numeric value from the variable thatnvpoints to into the double variable thatdppoints to. It returns 0 on success and -1 if an error occurs, including overflow. On overflow, the global variableerrnowill be set toPGTYPES_NUM_OVERFLOWadditionally.

Convert a variable of type numeric to int.

int PGTYPESnumeric_to_int(numeric *nv, int *ip);

The function converts the numeric value from the variable thatnvpoints to into the integer variable thatippoints to. It returns 0 on success and -1 if an error occurs, including overflow. On overflow, the global variableerrnowill be set toPGTYPES_NUM_OVERFLOWadditionally.

Convert a variable of type numeric to long.

int PGTYPESnumeric_to_long(numeric *nv, long *lp);

The function converts the numeric value from the variable thatnvpoints to into the long integer variable thatlppoints to. It returns 0 on success and -1 if an error occurs, including overflow. On overflow, the global variableerrnowill be set toPGTYPES_NUM_OVERFLOWadditionally.

Convert a variable of type numeric to decimal.

int PGTYPESnumeric_to_decimal(numeric *src, decimal *dst);

The function converts the numeric value from the variable thatsrcpoints to into the decimal variable thatdstpoints to. It returns 0 on success and -1 if an error occurs, including overflow. On overflow, the global variableerrnowill be set toPGTYPES_NUM_OVERFLOWadditionally.

Convert a variable of type decimal to numeric.

int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst);

The function converts the decimal value from the variable thatsrcpoints to into the numeric variable thatdstpoints to. It returns 0 on success and -1 if an error occurs. Since the decimal type is implemented as a limited version of the numeric type, overflow cannot occur with this conversion.

Extract the date part from a timestamp.

date PGTYPESdate_from_timestamp(timestamp dt);

The function receives a timestamp as its only argument and returns the extracted date part from this timestamp.

Parse a date from its textual representation.

date PGTYPESdate_from_asc(char *str, char **endptr);

The function receives a C char* stringstrand a pointer to a C char* stringendptr. At the moment ECPG always parses the complete string and so it currently does not support to store the address of the first invalid character in*endptr. You can safely setendptrto NULL.

Note that the function always assumes MDY-formatted dates and there is currently no variable to change that within ECPG.

Table 33-1 shows the allowed input formats.

Return the textual representation of a date variable.

char *PGTYPESdate_to_asc(date dDate);

The function receives the datedDateas its only parameter. It will output the date in the form1999-01-18, i.e., in theYYYY-MM-DDformat.

Extract the values for the day, the month and the year from a variable of type date.

void PGTYPESdate_julmdy(date d, int *mdy);

The function receives the datedand a pointer to an array of 3 integer valuesmdy. The variable name indicates the sequential order:mdy[0]will be set to contain the number of the month,mdy[1]will be set to the value of the day andmdy[2]will contain the year.

Create a date value from an array of 3 integers that specify the day, the month and the year of the date.

void PGTYPESdate_mdyjul(int *mdy, date *jdate);

The function receives the array of the 3 integers (mdy) as its first argument and as its second argument a pointer to a variable of type date that should hold the result of the operation.

Return a number representing the day of the week for a date value.

int PGTYPESdate_dayofweek(date d);

The function receives the date variabledas its only argument and returns an integer that indicates the day of the week for this date.

• 0 - Sunday

• 1 - Monday

• 2 - Tuesday

• 3 - Wednesday

• 4 - Thursday

• 5 - Friday

• 6 - Saturday

Get the current date.

void PGTYPESdate_today(date *d);

The function receives a pointer to a date variable (d) that it sets to the current date.

Convert a variable of type date to its textual representation using a format mask.

int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf);

The function receives the date to convert (dDate), the format mask (fmtstring) and the string that will hold the textual representation of the date (outbuf).

On success, 0 is returned and a negative value if an error occurred.

The following literals are the field specifiers you can use:

• dd- The number of the day of the month.

• mm- The number of the month of the year.

• yy- The number of the year as a two digit number.

• yyyy- The number of the year as a four digit number.

• ddd- The name of the day (abbreviated).

• mmm- The name of the month (abbreviated).

All other characters are copied 1:1 to the output string.

Table 33-2 indicates a few possible formats. This will give you an idea of how to use this function. All output lines are based on the same date: November 23, 1959.

Use a format mask to convert a Cchar*string to a value of type date.

int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);

The function receives a pointer to the date value that should hold the result of the operation (d), the format mask to use for parsing the date (fmt) and the C char* string containing the textual representation of the date (str). The textual representation is expected to match the format mask. However you do not need to have a 1:1 mapping of the string to the format mask. The function only analyzes the sequential order and looks for the literalsyyoryyyythat indicate the position of the year,mmto indicate the position of the month andddto indicate the position of the day.

Table 33-3 indicates a few possible formats. This will give you an idea of how to use this function.

Parse a timestamp from its textual representation into a timestamp variable.

timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);

The function receives the string to parse (str) and a pointer to a C char* (endptr). At the moment ECPG always parses the complete string and so it currently does not support to store the address of the first invalid character in*endptr. You can safely setendptrto NULL.

The function returns the parsed timestamp on success. On error,PGTYPESInvalidTimestampis returned anderrnois set toPGTYPES_TS_BAD_TIMESTAMP. SeePGTYPESInvalidTimestampfor important notes on this value.

In general, the input string can contain any combination of an allowed date specification, a whitespace character and an allowed time specification. Note that timezones are not supported by ECPG. It can parse them but does not apply any calculation as thePostgreSQLserver does for example. Timezone specifiers are silently discarded.

Table 33-4 contains a few examples for input strings.

Converts a date to a C char* string.

char *PGTYPEStimestamp_to_asc(timestamp tstamp);

The function receives the timestamptstampas its only argument and returns an allocated string that contains the textual representation of the timestamp.

Retrieve the current timestamp.

void PGTYPEStimestamp_current(timestamp *ts);

The function retrieves the current timestamp and saves it into the timestamp variable thattspoints to.

Convert a timestamp variable to a C char* using a format mask.

int PGTYPEStimestamp_fmt_asc(timestamp *ts, char *output, int str_len, char *fmtstr);

The function receives a pointer to the timestamp to convert as its first argument (ts), a pointer to the output buffer (output), the maximal length that has been allocated for the output buffer (str_len) and the format mask to use for the conversion (fmtstr).

Upon success, the function returns 0 and a negative value if an error occurred.

You can use the following format specifiers for the format mask. The format specifiers are the same ones that are used in thestrftimefunction inlibc. Any non-format specifier will be copied into the output buffer.

• %A- is replaced by national representation of the full weekday name.

• %a- is replaced by national representation of the abbreviated weekday name.

• %B- is replaced by national representation of the full month name.

• %b- is replaced by national representation of the abbreviated month name.

• %C- is replaced by (year / 100) as decimal number; single digits are preceded by a zero.

• %c- is replaced by national representation of time and date.

• %D- is equivalent to%m/%d/%y.

• %d- is replaced by the day of the month as a decimal number (01-31).

• %E*%O*- POSIX locale extensions. The sequences%Ec%EC%Ex%EX%Ey%EY%Od%Oe%OH%OI%Om%OM%OS%Ou%OU%OV%Ow%OW%Oyare supposed to provide alternative representations.

  Additionally%OBimplemented to represent alternative months names (used standalone, without day mentioned).

• %e- is replaced by the day of month as a decimal number (1-31); single digits are preceded by a blank.

• %F- is equivalent to%Y-%m-%d.

• %G- is replaced by a year as a decimal number with century. This year is the one that contains the greater part of the week (Monday as the first day of the week).

• %g- is replaced by the same year as in%G, but as a decimal number without century (00-99).

• %H- is replaced by the hour (24-hour clock) as a decimal number (00-23).

• %h- the same as%b.

• %I- is replaced by the hour (12-hour clock) as a decimal number (01-12).

• %j- is replaced by the day of the year as a decimal number (001-366).

• %k- is replaced by the hour (24-hour clock) as a decimal number (0-23); single digits are preceded by a blank.

• %l- is replaced by the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank.

• %M- is replaced by the minute as a decimal number (00-59).

• %m- is replaced by the month as a decimal number (01-12).

• %n- is replaced by a newline.

• %O*- the same as%E*.

• %p- is replaced by national representation of either "ante meridiem" or "post meridiem" as appropriate.

• %R- is equivalent to%H:%M.

• %r- is equivalent to%I:%M:%S %p.

• %S- is replaced by the second as a decimal number (00-60).

• %s- is replaced by the number of seconds since the Epoch, UTC.

• %T- is equivalent to%H:%M:%S

• %t- is replaced by a tab.

• %U- is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number (00-53).

• %u- is replaced by the weekday (Monday as the first day of the week) as a decimal number (1-7).

• %V- is replaced by the week number of the year (Monday as the first day of the week) as a decimal number (01-53). If the week containing January 1 has four or more days in the new year, then it is week 1; otherwise it is the last week of the previous year, and the next week is week 1.

• %v- is equivalent to%e-%b-%Y.

• %W- is replaced by the week number of the year (Monday as the first day of the week) as a decimal number (00-53).

• %w- is replaced by the weekday (Sunday as the first day of the week) as a decimal number (0-6).

• %X- is replaced by national representation of the time.

• %x- is replaced by national representation of the date.

• %Y- is replaced by the year with century as a decimal number.

• %y- is replaced by the year without century as a decimal number (00-99).

• %Z- is replaced by the time zone name.

• %z- is replaced by the time zone offset from UTC; a leading plus sign stands for east of UTC, a minus sign for west of UTC, hours and minutes follow with two digits each and no delimiter between them (common form for RFC 822 date headers).

• %+- is replaced by national representation of the date and time.

• %-*- GNU libc extension. Do not do any padding when performing numerical outputs.

• $_* - GNU libc extension. Explicitly specify space for padding.

• %0*- GNU libc extension. Explicitly specify zero for padding.

• %%- is replaced by%.

Subtract one timestamp from another one and save the result in a variable of type interval.

int PGTYPEStimestamp_sub(timestamp *ts1, timestamp *ts2, interval *iv);

The function will subtract the timestamp variable thatts2points to from the timestamp variable thatts1points to and will store the result in the interval variable thativpoints to.

Upon success, the function returns 0 and a negative value if an error occurred.

Parse a timestamp value from its textual representation using a formatting mask.

int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d);

The function receives the textual representation of a timestamp in the variablestras well as the formatting mask to use in the variablefmt. The result will be stored in the variable thatdpoints to.

If the formatting maskfmtis NULL, the function will fall back to the default formatting mask which is%Y-%m-%d %H:%M:%S.

This is the reverse function toPGTYPEStimestamp_fmt_asc. See the documentation there in order to find out about the possible formatting mask entries.

Add an interval variable to a timestamp variable.

int PGTYPEStimestamp_add_interval(timestamp *tin, interval *span, timestamp *tout);

The function receives a pointer to a timestamp variabletinand a pointer to an interval variablespan. It adds the interval to the timestamp and saves the resulting timestamp in the variable thattoutpoints to.

Upon success, the function returns 0 and a negative value if an error occurred.

Subtract an interval variable from a timestamp variable.

int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tout);

The function subtracts the interval variable thatspanpoints to from the timestamp variable thattinpoints to and saves the result into the variable thattoutpoints to.

Upon success, the function returns 0 and a negative value if an error occurred.

Return a pointer to a newly allocated interval variable.

interval *PGTYPESinterval_new(void);

Release the memory of a previously allocated interval variable.

void PGTYPESinterval_new(interval *intvl);

Parse an interval from its textual representation.

interval *PGTYPESinterval_from_asc(char *str, char **endptr);

The function parses the input stringstrand returns a pointer to an allocated interval variable. At the moment ECPG always parses the complete string and so it currently does not support to store the address of the first invalid character in*endptr. You can safely setendptrto NULL.

Convert a variable of type interval to its textual representation.

char *PGTYPESinterval_to_asc(interval *span);

The function converts the interval variable thatspanpoints to into a C char*. The output looks like this example:@ 1 day 12 hours 59 mins 10 secs.

Copy a variable of type interval.

int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest);

The function copies the interval variable thatintvlsrcpoints to into the variable thatintvldestpoints to. Note that you need to allocate the memory for the destination variable before.

Request a pointer to a newly allocated decimal variable.

decimal *PGTYPESdecimal_new(void);

Free a decimal type, release all of its memory.

void PGTYPESdecimal_free(decimal *var);

An argument should contain a numeric variable (or point to a numeric variable) but in fact its in-memory representation was invalid.

An overflow occurred. Since the numeric type can deal with almost arbitrary precision, converting a numeric variable into other types might cause overflow.

An underflow occurred. Since the numeric type can deal with almost arbitrary precision, converting a numeric variable into other types might cause underflow.

A division by zero has been attempted.

A value of type timestamp representing an invalid time stamp. This is returned by the functionPGTYPEStimestamp_from_ascon parse error. Note that due to the internal representation of thetimestampdata type,PGTYPESInvalidTimestampis also a valid timestamp at the same time. It is set to1899-12-31 23:59:59. In order to detect errors, make sure that your application does not only test forPGTYPESInvalidTimestampbut also forerrno != 0after each call toPGTYPEStimestamp_from_asc.