begriffs open source - ai-pg/blob - full-docs/txt/ecpg-pgtypes.txt

   1
   2 34.6. pgtypes Library #
   3
   4    34.6.1. Character Strings
   5    34.6.2. The numeric Type
   6    34.6.3. The date Type
   7    34.6.4. The timestamp Type
   8    34.6.5. The interval Type
   9    34.6.6. The decimal Type
  10    34.6.7. errno Values of pgtypeslib
  11    34.6.8. Special Constants of pgtypeslib
  12
  13    The pgtypes library maps PostgreSQL database types to C equivalents
  14    that can be used in C programs. It also offers functions to do basic
  15    calculations with those types within C, i.e., without the help of the
  16    PostgreSQL server. See the following example:
  17 EXEC SQL BEGIN DECLARE SECTION;
  18    date date1;
  19    timestamp ts1, tsout;
  20    interval iv1;
  21    char *out;
  22 EXEC SQL END DECLARE SECTION;
  23
  24 PGTYPESdate_today(&date1);
  25 EXEC SQL SELECT started, duration INTO :ts1, :iv1 FROM datetbl WHERE d=:date1;
  26 PGTYPEStimestamp_add_interval(&ts1, &iv1, &tsout);
  27 out = PGTYPEStimestamp_to_asc(&tsout);
  28 printf("Started + duration: %s\n", out);
  29 PGTYPESchar_free(out);
  30
  31
  32 34.6.1. Character Strings #
  33
  34    Some functions such as PGTYPESnumeric_to_asc return a pointer to a
  35    freshly allocated character string. These results should be freed with
  36    PGTYPESchar_free instead of free. (This is important only on Windows,
  37    where memory allocation and release sometimes need to be done by the
  38    same library.)
  39
  40 34.6.2. The numeric Type #
  41
  42    The numeric type offers to do calculations with arbitrary precision.
  43    See Section 8.1 for the equivalent type in the PostgreSQL server.
  44    Because of the arbitrary precision this variable needs to be able to
  45    expand and shrink dynamically. That's why you can only create numeric
  46    variables on the heap, by means of the PGTYPESnumeric_new and
  47    PGTYPESnumeric_free functions. The decimal type, which is similar but
  48    limited in precision, can be created on the stack as well as on the
  49    heap.
  50
  51    The following functions can be used to work with the numeric type:
  52
  53    PGTYPESnumeric_new #
  54           Request a pointer to a newly allocated numeric variable.
  55
  56 numeric *PGTYPESnumeric_new(void);
  57
  58    PGTYPESnumeric_free #
  59           Free a numeric type, release all of its memory.
  60
  61 void PGTYPESnumeric_free(numeric *var);
  62
  63    PGTYPESnumeric_from_asc #
  64           Parse a numeric type from its string notation.
  65
  66 numeric *PGTYPESnumeric_from_asc(char *str, char **endptr);
  67
  68           Valid formats are for example: -2, .794, +3.44, 592.49E07 or
  69           -32.84e-4. If the value could be parsed successfully, a valid
  70           pointer is returned, else the NULL pointer. At the moment ECPG
  71           always parses the complete string and so it currently does not
  72           support to store the address of the first invalid character in
  73           *endptr. You can safely set endptr to NULL.
  74
  75    PGTYPESnumeric_to_asc #
  76           Returns a pointer to a string allocated by malloc that contains
  77           the string representation of the numeric type num.
  78
  79 char *PGTYPESnumeric_to_asc(numeric *num, int dscale);
  80
  81           The numeric value will be printed with dscale decimal digits,
  82           with rounding applied if necessary. The result must be freed
  83           with PGTYPESchar_free().
  84
  85    PGTYPESnumeric_add #
  86           Add two numeric variables into a third one.
  87
  88 int PGTYPESnumeric_add(numeric *var1, numeric *var2, numeric *result);
  89
  90           The function adds the variables var1 and var2 into the result
  91           variable result. The function returns 0 on success and -1 in
  92           case of error.
  93
  94    PGTYPESnumeric_sub #
  95           Subtract two numeric variables and return the result in a third
  96           one.
  97
  98 int PGTYPESnumeric_sub(numeric *var1, numeric *var2, numeric *result);
  99
 100           The function subtracts the variable var2 from the variable var1.
 101           The result of the operation is stored in the variable result.
 102           The function returns 0 on success and -1 in case of error.
 103
 104    PGTYPESnumeric_mul #
 105           Multiply two numeric variables and return the result in a third
 106           one.
 107
 108 int PGTYPESnumeric_mul(numeric *var1, numeric *var2, numeric *result);
 109
 110           The function multiplies the variables var1 and var2. The result
 111           of the operation is stored in the variable result. The function
 112           returns 0 on success and -1 in case of error.
 113
 114    PGTYPESnumeric_div #
 115           Divide two numeric variables and return the result in a third
 116           one.
 117
 118 int PGTYPESnumeric_div(numeric *var1, numeric *var2, numeric *result);
 119
 120           The function divides the variables var1 by var2. The result of
 121           the operation is stored in the variable result. The function
 122           returns 0 on success and -1 in case of error.
 123
 124    PGTYPESnumeric_cmp #
 125           Compare two numeric variables.
 126
 127 int PGTYPESnumeric_cmp(numeric *var1, numeric *var2)
 128
 129           This function compares two numeric variables. In case of error,
 130           INT_MAX is returned. On success, the function returns one of
 131           three possible results:
 132
 133           + 1, if var1 is bigger than var2
 134           + -1, if var1 is smaller than var2
 135           + 0, if var1 and var2 are equal
 136
 137    PGTYPESnumeric_from_int #
 138           Convert an int variable to a numeric variable.
 139
 140 int PGTYPESnumeric_from_int(signed int int_val, numeric *var);
 141
 142           This function accepts a variable of type signed int and stores
 143           it in the numeric variable var. Upon success, 0 is returned and
 144           -1 in case of a failure.
 145
 146    PGTYPESnumeric_from_long #
 147           Convert a long int variable to a numeric variable.
 148
 149 int PGTYPESnumeric_from_long(signed long int long_val, numeric *var);
 150
 151           This function accepts a variable of type signed long int and
 152           stores it in the numeric variable var. Upon success, 0 is
 153           returned and -1 in case of a failure.
 154
 155    PGTYPESnumeric_copy #
 156           Copy over one numeric variable into another one.
 157
 158 int PGTYPESnumeric_copy(numeric *src, numeric *dst);
 159
 160           This function copies over the value of the variable that src
 161           points to into the variable that dst points to. It returns 0 on
 162           success and -1 if an error occurs.
 163
 164    PGTYPESnumeric_from_double #
 165           Convert a variable of type double to a numeric.
 166
 167 int  PGTYPESnumeric_from_double(double d, numeric *dst);
 168
 169           This function accepts a variable of type double and stores the
 170           result in the variable that dst points to. It returns 0 on
 171           success and -1 if an error occurs.
 172
 173    PGTYPESnumeric_to_double #
 174           Convert a variable of type numeric to double.
 175
 176 int PGTYPESnumeric_to_double(numeric *nv, double *dp)
 177
 178           The function converts the numeric value from the variable that
 179           nv points to into the double variable that dp points to. It
 180           returns 0 on success and -1 if an error occurs, including
 181           overflow. On overflow, the global variable errno will be set to
 182           PGTYPES_NUM_OVERFLOW additionally.
 183
 184    PGTYPESnumeric_to_int #
 185           Convert a variable of type numeric to int.
 186
 187 int PGTYPESnumeric_to_int(numeric *nv, int *ip);
 188
 189           The function converts the numeric value from the variable that
 190           nv points to into the integer variable that ip points to. It
 191           returns 0 on success and -1 if an error occurs, including
 192           overflow. On overflow, the global variable errno will be set to
 193           PGTYPES_NUM_OVERFLOW additionally.
 194
 195    PGTYPESnumeric_to_long #
 196           Convert a variable of type numeric to long.
 197
 198 int PGTYPESnumeric_to_long(numeric *nv, long *lp);
 199
 200           The function converts the numeric value from the variable that
 201           nv points to into the long integer variable that lp points to.
 202           It returns 0 on success and -1 if an error occurs, including
 203           overflow and underflow. On overflow, the global variable errno
 204           will be set to PGTYPES_NUM_OVERFLOW and on underflow errno will
 205           be set to PGTYPES_NUM_UNDERFLOW.
 206
 207    PGTYPESnumeric_to_decimal #
 208           Convert a variable of type numeric to decimal.
 209
 210 int PGTYPESnumeric_to_decimal(numeric *src, decimal *dst);
 211
 212           The function converts the numeric value from the variable that
 213           src points to into the decimal variable that dst points to. It
 214           returns 0 on success and -1 if an error occurs, including
 215           overflow. On overflow, the global variable errno will be set to
 216           PGTYPES_NUM_OVERFLOW additionally.
 217
 218    PGTYPESnumeric_from_decimal #
 219           Convert a variable of type decimal to numeric.
 220
 221 int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst);
 222
 223           The function converts the decimal value from the variable that
 224           src points to into the numeric variable that dst points to. It
 225           returns 0 on success and -1 if an error occurs. Since the
 226           decimal type is implemented as a limited version of the numeric
 227           type, overflow cannot occur with this conversion.
 228
 229 34.6.3. The date Type #
 230
 231    The date type in C enables your programs to deal with data of the SQL
 232    type date. See Section 8.5 for the equivalent type in the PostgreSQL
 233    server.
 234
 235    The following functions can be used to work with the date type:
 236
 237    PGTYPESdate_from_timestamp #
 238           Extract the date part from a timestamp.
 239
 240 date PGTYPESdate_from_timestamp(timestamp dt);
 241
 242           The function receives a timestamp as its only argument and
 243           returns the extracted date part from this timestamp.
 244
 245    PGTYPESdate_from_asc #
 246           Parse a date from its textual representation.
 247
 248 date PGTYPESdate_from_asc(char *str, char **endptr);
 249
 250           The function receives a C char* string str and a pointer to a C
 251           char* string endptr. At the moment ECPG always parses the
 252           complete string and so it currently does not support to store
 253           the address of the first invalid character in *endptr. You can
 254           safely set endptr to NULL.
 255
 256           Note that the function always assumes MDY-formatted dates and
 257           there is currently no variable to change that within ECPG.
 258
 259           Table 34.2 shows the allowed input formats.
 260
 261           Table 34.2. Valid Input Formats for PGTYPESdate_from_asc
 262
 263                Input                  Result
 264           January 8, 1999  January 8, 1999
 265           1999-01-08       January 8, 1999
 266           1/8/1999         January 8, 1999
 267           1/18/1999        January 18, 1999
 268           01/02/03         February 1, 2003
 269           1999-Jan-08      January 8, 1999
 270           Jan-08-1999      January 8, 1999
 271           08-Jan-1999      January 8, 1999
 272           99-Jan-08        January 8, 1999
 273           08-Jan-99        January 8, 1999
 274           08-Jan-06        January 8, 2006
 275           Jan-08-99        January 8, 1999
 276           19990108         ISO 8601; January 8, 1999
 277           990108           ISO 8601; January 8, 1999
 278           1999.008         year and day of year
 279           J2451187         Julian day
 280           January 8, 99 BC year 99 before the Common Era
 281
 282    PGTYPESdate_to_asc #
 283           Return the textual representation of a date variable.
 284
 285 char *PGTYPESdate_to_asc(date dDate);
 286
 287           The function receives the date dDate as its only parameter. It
 288           will output the date in the form 1999-01-18, i.e., in the
 289           YYYY-MM-DD format. The result must be freed with
 290           PGTYPESchar_free().
 291
 292    PGTYPESdate_julmdy #
 293           Extract the values for the day, the month and the year from a
 294           variable of type date.
 295
 296 void PGTYPESdate_julmdy(date d, int *mdy);
 297
 298           The function receives the date d and a pointer to an array of 3
 299           integer values mdy. The variable name indicates the sequential
 300           order: mdy[0] will be set to contain the number of the month,
 301           mdy[1] will be set to the value of the day and mdy[2] will
 302           contain the year.
 303
 304    PGTYPESdate_mdyjul #
 305           Create a date value from an array of 3 integers that specify the
 306           day, the month and the year of the date.
 307
 308 void PGTYPESdate_mdyjul(int *mdy, date *jdate);
 309
 310           The function receives the array of the 3 integers (mdy) as its
 311           first argument and as its second argument a pointer to a
 312           variable of type date that should hold the result of the
 313           operation.
 314
 315    PGTYPESdate_dayofweek #
 316           Return a number representing the day of the week for a date
 317           value.
 318
 319 int PGTYPESdate_dayofweek(date d);
 320
 321           The function receives the date variable d as its only argument
 322           and returns an integer that indicates the day of the week for
 323           this date.
 324
 325           + 0 - Sunday
 326           + 1 - Monday
 327           + 2 - Tuesday
 328           + 3 - Wednesday
 329           + 4 - Thursday
 330           + 5 - Friday
 331           + 6 - Saturday
 332
 333    PGTYPESdate_today #
 334           Get the current date.
 335
 336 void PGTYPESdate_today(date *d);
 337
 338           The function receives a pointer to a date variable (d) that it
 339           sets to the current date.
 340
 341    PGTYPESdate_fmt_asc #
 342           Convert a variable of type date to its textual representation
 343           using a format mask.
 344
 345 int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf);
 346
 347           The function receives the date to convert (dDate), the format
 348           mask (fmtstring) and the string that will hold the textual
 349           representation of the date (outbuf).
 350
 351           On success, 0 is returned and a negative value if an error
 352           occurred.
 353
 354           The following literals are the field specifiers you can use:
 355
 356           + dd - The number of the day of the month.
 357           + mm - The number of the month of the year.
 358           + yy - The number of the year as a two digit number.
 359           + yyyy - The number of the year as a four digit number.
 360           + ddd - The name of the day (abbreviated).
 361           + mmm - The name of the month (abbreviated).
 362
 363           All other characters are copied 1:1 to the output string.
 364
 365           Table 34.3 indicates a few possible formats. This will give you
 366           an idea of how to use this function. All output lines are based
 367           on the same date: November 23, 1959.
 368
 369           Table 34.3. Valid Input Formats for PGTYPESdate_fmt_asc
 370
 371                 Format              Result
 372           mmddyy              112359
 373           ddmmyy              231159
 374           yymmdd              591123
 375           yy/mm/dd            59/11/23
 376           yy mm dd            59 11 23
 377           yy.mm.dd            59.11.23
 378           .mm.yyyy.dd.        .11.1959.23.
 379           mmm. dd, yyyy       Nov. 23, 1959
 380           mmm dd yyyy         Nov 23 1959
 381           yyyy dd mm          1959 23 11
 382           ddd, mmm. dd, yyyy  Mon, Nov. 23, 1959
 383           (ddd) mmm. dd, yyyy (Mon) Nov. 23, 1959
 384
 385    PGTYPESdate_defmt_asc #
 386           Use a format mask to convert a C char* string to a value of type
 387           date.
 388
 389 int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);
 390
 391           The function receives a pointer to the date value that should
 392           hold the result of the operation (d), the format mask to use for
 393           parsing the date (fmt) and the C char* string containing the
 394           textual representation of the date (str). The textual
 395           representation is expected to match the format mask. However you
 396           do not need to have a 1:1 mapping of the string to the format
 397           mask. The function only analyzes the sequential order and looks
 398           for the literals yy or yyyy that indicate the position of the
 399           year, mm to indicate the position of the month and dd to
 400           indicate the position of the day.
 401
 402           Table 34.4 indicates a few possible formats. This will give you
 403           an idea of how to use this function.
 404
 405           Table 34.4. Valid Input Formats for rdefmtdate
 406
 407    Format String Result
 408    ddmmyy 21-2-54 1954-02-21
 409    ddmmyy 2-12-54 1954-12-02
 410    ddmmyy 20111954 1954-11-20
 411    ddmmyy 130464 1964-04-13
 412    mmm.dd.yyyy MAR-12-1967 1967-03-12
 413    yy/mm/dd 1954, February 3rd 1954-02-03
 414    mmm.dd.yyyy 041269 1969-04-12
 415    yy/mm/dd In the year 2525, in the month of July, mankind will be alive
 416    on the 28th day 2525-07-28
 417    dd-mm-yy I said on the 28th of July in the year 2525 2525-07-28
 418    mmm.dd.yyyy 9/14/58 1958-09-14
 419    yy/mm/dd 47/03/29 1947-03-29
 420    mmm.dd.yyyy oct 28 1975 1975-10-28
 421    mmddyy Nov 14th, 1985 1985-11-14
 422
 423 34.6.4. The timestamp Type #
 424
 425    The timestamp type in C enables your programs to deal with data of the
 426    SQL type timestamp. See Section 8.5 for the equivalent type in the
 427    PostgreSQL server.
 428
 429    The following functions can be used to work with the timestamp type:
 430
 431    PGTYPEStimestamp_from_asc #
 432           Parse a timestamp from its textual representation into a
 433           timestamp variable.
 434
 435 timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);
 436
 437           The function receives the string to parse (str) and a pointer to
 438           a C char* (endptr). At the moment ECPG always parses the
 439           complete string and so it currently does not support to store
 440           the address of the first invalid character in *endptr. You can
 441           safely set endptr to NULL.
 442
 443           The function returns the parsed timestamp on success. On error,
 444           PGTYPESInvalidTimestamp is returned and errno is set to
 445           PGTYPES_TS_BAD_TIMESTAMP. See PGTYPESInvalidTimestamp for
 446           important notes on this value.
 447
 448           In general, the input string can contain any combination of an
 449           allowed date specification, a whitespace character and an
 450           allowed time specification. Note that time zones are not
 451           supported by ECPG. It can parse them but does not apply any
 452           calculation as the PostgreSQL server does for example. Timezone
 453           specifiers are silently discarded.
 454
 455           Table 34.5 contains a few examples for input strings.
 456
 457           Table 34.5. Valid Input Formats for PGTYPEStimestamp_from_asc
 458
 459    Input Result
 460    1999-01-08 04:05:06 1999-01-08 04:05:06
 461    January 8 04:05:06 1999 PST 1999-01-08 04:05:06
 462    1999-Jan-08 04:05:06.789-8 1999-01-08 04:05:06.789 (time zone specifier
 463    ignored)
 464    J2451187 04:05-08:00 1999-01-08 04:05:00 (time zone specifier ignored)
 465
 466    PGTYPEStimestamp_to_asc #
 467           Converts a date to a C char* string.
 468
 469 char *PGTYPEStimestamp_to_asc(timestamp tstamp);
 470
 471           The function receives the timestamp tstamp as its only argument
 472           and returns an allocated string that contains the textual
 473           representation of the timestamp. The result must be freed with
 474           PGTYPESchar_free().
 475
 476    PGTYPEStimestamp_current #
 477           Retrieve the current timestamp.
 478
 479 void PGTYPEStimestamp_current(timestamp *ts);
 480
 481           The function retrieves the current timestamp and saves it into
 482           the timestamp variable that ts points to.
 483
 484    PGTYPEStimestamp_fmt_asc #
 485           Convert a timestamp variable to a C char* using a format mask.
 486
 487 int PGTYPEStimestamp_fmt_asc(timestamp *ts, char *output, int str_len, char *fmt
 488 str);
 489
 490           The function receives a pointer to the timestamp to convert as
 491           its first argument (ts), a pointer to the output buffer
 492           (output), the maximal length that has been allocated for the
 493           output buffer (str_len) and the format mask to use for the
 494           conversion (fmtstr).
 495
 496           Upon success, the function returns 0 and a negative value if an
 497           error occurred.
 498
 499           You can use the following format specifiers for the format mask.
 500           The format specifiers are the same ones that are used in the
 501           strftime function in libc. Any non-format specifier will be
 502           copied into the output buffer.
 503
 504           + %A - is replaced by national representation of the full
 505             weekday name.
 506           + %a - is replaced by national representation of the abbreviated
 507             weekday name.
 508           + %B - is replaced by national representation of the full month
 509             name.
 510           + %b - is replaced by national representation of the abbreviated
 511             month name.
 512           + %C - is replaced by (year / 100) as decimal number; single
 513             digits are preceded by a zero.
 514           + %c - is replaced by national representation of time and date.
 515           + %D - is equivalent to %m/%d/%y.
 516           + %d - is replaced by the day of the month as a decimal number
 517             (01–31).
 518           + %E* %O* - POSIX locale extensions. The sequences %Ec %EC %Ex
 519             %EX %Ey %EY %Od %Oe %OH %OI %Om %OM %OS %Ou %OU %OV %Ow %OW
 520             %Oy are supposed to provide alternative representations.
 521             Additionally %OB implemented to represent alternative months
 522             names (used standalone, without day mentioned).
 523           + %e - is replaced by the day of month as a decimal number
 524             (1–31); single digits are preceded by a blank.
 525           + %F - is equivalent to %Y-%m-%d.
 526           + %G - is replaced by a year as a decimal number with century.
 527             This year is the one that contains the greater part of the
 528             week (Monday as the first day of the week).
 529           + %g - is replaced by the same year as in %G, but as a decimal
 530             number without century (00–99).
 531           + %H - is replaced by the hour (24-hour clock) as a decimal
 532             number (00–23).
 533           + %h - the same as %b.
 534           + %I - is replaced by the hour (12-hour clock) as a decimal
 535             number (01–12).
 536           + %j - is replaced by the day of the year as a decimal number
 537             (001–366).
 538           + %k - is replaced by the hour (24-hour clock) as a decimal
 539             number (0–23); single digits are preceded by a blank.
 540           + %l - is replaced by the hour (12-hour clock) as a decimal
 541             number (1–12); single digits are preceded by a blank.
 542           + %M - is replaced by the minute as a decimal number (00–59).
 543           + %m - is replaced by the month as a decimal number (01–12).
 544           + %n - is replaced by a newline.
 545           + %O* - the same as %E*.
 546           + %p - is replaced by national representation of either “ante
 547             meridiem” or “post meridiem” as appropriate.
 548           + %R - is equivalent to %H:%M.
 549           + %r - is equivalent to %I:%M:%S %p.
 550           + %S - is replaced by the second as a decimal number (00–60).
 551           + %s - is replaced by the number of seconds since the Epoch,
 552             UTC.
 553           + %T - is equivalent to %H:%M:%S
 554           + %t - is replaced by a tab.
 555           + %U - is replaced by the week number of the year (Sunday as the
 556             first day of the week) as a decimal number (00–53).
 557           + %u - is replaced by the weekday (Monday as the first day of
 558             the week) as a decimal number (1–7).
 559           + %V - is replaced by the week number of the year (Monday as the
 560             first day of the week) as a decimal number (01–53). If the
 561             week containing January 1 has four or more days in the new
 562             year, then it is week 1; otherwise it is the last week of the
 563             previous year, and the next week is week 1.
 564           + %v - is equivalent to %e-%b-%Y.
 565           + %W - is replaced by the week number of the year (Monday as the
 566             first day of the week) as a decimal number (00–53).
 567           + %w - is replaced by the weekday (Sunday as the first day of
 568             the week) as a decimal number (0–6).
 569           + %X - is replaced by national representation of the time.
 570           + %x - is replaced by national representation of the date.
 571           + %Y - is replaced by the year with century as a decimal number.
 572           + %y - is replaced by the year without century as a decimal
 573             number (00–99).
 574           + %Z - is replaced by the time zone name.
 575           + %z - is replaced by the time zone offset from UTC; a leading
 576             plus sign stands for east of UTC, a minus sign for west of
 577             UTC, hours and minutes follow with two digits each and no
 578             delimiter between them (common form for RFC 822 date headers).
 579           + %+ - is replaced by national representation of the date and
 580             time.
 581           + %-* - GNU libc extension. Do not do any padding when
 582             performing numerical outputs.
 583           + $_* - GNU libc extension. Explicitly specify space for
 584             padding.
 585           + %0* - GNU libc extension. Explicitly specify zero for padding.
 586           + %% - is replaced by %.
 587
 588    PGTYPEStimestamp_sub #
 589           Subtract one timestamp from another one and save the result in a
 590           variable of type interval.
 591
 592 int PGTYPEStimestamp_sub(timestamp *ts1, timestamp *ts2, interval *iv);
 593
 594           The function will subtract the timestamp variable that ts2
 595           points to from the timestamp variable that ts1 points to and
 596           will store the result in the interval variable that iv points
 597           to.
 598
 599           Upon success, the function returns 0 and a negative value if an
 600           error occurred.
 601
 602    PGTYPEStimestamp_defmt_asc #
 603           Parse a timestamp value from its textual representation using a
 604           formatting mask.
 605
 606 int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d);
 607
 608           The function receives the textual representation of a timestamp
 609           in the variable str as well as the formatting mask to use in the
 610           variable fmt. The result will be stored in the variable that d
 611           points to.
 612
 613           If the formatting mask fmt is NULL, the function will fall back
 614           to the default formatting mask which is %Y-%m-%d %H:%M:%S.
 615
 616           This is the reverse function to PGTYPEStimestamp_fmt_asc. See
 617           the documentation there in order to find out about the possible
 618           formatting mask entries.
 619
 620    PGTYPEStimestamp_add_interval #
 621           Add an interval variable to a timestamp variable.
 622
 623 int PGTYPEStimestamp_add_interval(timestamp *tin, interval *span, timestamp *tou
 624 t);
 625
 626           The function receives a pointer to a timestamp variable tin and
 627           a pointer to an interval variable span. It adds the interval to
 628           the timestamp and saves the resulting timestamp in the variable
 629           that tout points to.
 630
 631           Upon success, the function returns 0 and a negative value if an
 632           error occurred.
 633
 634    PGTYPEStimestamp_sub_interval #
 635           Subtract an interval variable from a timestamp variable.
 636
 637 int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tou
 638 t);
 639
 640           The function subtracts the interval variable that span points to
 641           from the timestamp variable that tin points to and saves the
 642           result into the variable that tout points to.
 643
 644           Upon success, the function returns 0 and a negative value if an
 645           error occurred.
 646
 647 34.6.5. The interval Type #
 648
 649    The interval type in C enables your programs to deal with data of the
 650    SQL type interval. See Section 8.5 for the equivalent type in the
 651    PostgreSQL server.
 652
 653    The following functions can be used to work with the interval type:
 654
 655    PGTYPESinterval_new #
 656           Return a pointer to a newly allocated interval variable.
 657
 658 interval *PGTYPESinterval_new(void);
 659
 660    PGTYPESinterval_free #
 661           Release the memory of a previously allocated interval variable.
 662
 663 void PGTYPESinterval_free(interval *intvl);
 664
 665    PGTYPESinterval_from_asc #
 666           Parse an interval from its textual representation.
 667
 668 interval *PGTYPESinterval_from_asc(char *str, char **endptr);
 669
 670           The function parses the input string str and returns a pointer
 671           to an allocated interval variable. At the moment ECPG always
 672           parses the complete string and so it currently does not support
 673           to store the address of the first invalid character in *endptr.
 674           You can safely set endptr to NULL.
 675
 676    PGTYPESinterval_to_asc #
 677           Convert a variable of type interval to its textual
 678           representation.
 679
 680 char *PGTYPESinterval_to_asc(interval *span);
 681
 682           The function converts the interval variable that span points to
 683           into a C char*. The output looks like this example: @ 1 day 12
 684           hours 59 mins 10 secs. The result must be freed with
 685           PGTYPESchar_free().
 686
 687    PGTYPESinterval_copy #
 688           Copy a variable of type interval.
 689
 690 int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest);
 691
 692           The function copies the interval variable that intvlsrc points
 693           to into the variable that intvldest points to. Note that you
 694           need to allocate the memory for the destination variable before.
 695
 696 34.6.6. The decimal Type #
 697
 698    The decimal type is similar to the numeric type. However it is limited
 699    to a maximum precision of 30 significant digits. In contrast to the
 700    numeric type which can be created on the heap only, the decimal type
 701    can be created either on the stack or on the heap (by means of the
 702    functions PGTYPESdecimal_new and PGTYPESdecimal_free). There are a lot
 703    of other functions that deal with the decimal type in the Informix
 704    compatibility mode described in Section 34.15.
 705
 706    The following functions can be used to work with the decimal type and
 707    are not only contained in the libcompat library.
 708
 709    PGTYPESdecimal_new #
 710           Request a pointer to a newly allocated decimal variable.
 711
 712 decimal *PGTYPESdecimal_new(void);
 713
 714    PGTYPESdecimal_free #
 715           Free a decimal type, release all of its memory.
 716
 717 void PGTYPESdecimal_free(decimal *var);
 718
 719 34.6.7. errno Values of pgtypeslib #
 720
 721    PGTYPES_NUM_BAD_NUMERIC #
 722           An argument should contain a numeric variable (or point to a
 723           numeric variable) but in fact its in-memory representation was
 724           invalid.
 725
 726    PGTYPES_NUM_OVERFLOW #
 727           An overflow occurred. Since the numeric type can deal with
 728           almost arbitrary precision, converting a numeric variable into
 729           other types might cause overflow.
 730
 731    PGTYPES_NUM_UNDERFLOW #
 732           An underflow occurred. Since the numeric type can deal with
 733           almost arbitrary precision, converting a numeric variable into
 734           other types might cause underflow.
 735
 736    PGTYPES_NUM_DIVIDE_ZERO #
 737           A division by zero has been attempted.
 738
 739    PGTYPES_DATE_BAD_DATE #
 740           An invalid date string was passed to the PGTYPESdate_from_asc
 741           function.
 742
 743    PGTYPES_DATE_ERR_EARGS #
 744           Invalid arguments were passed to the PGTYPESdate_defmt_asc
 745           function.
 746
 747    PGTYPES_DATE_ERR_ENOSHORTDATE #
 748           An invalid token in the input string was found by the
 749           PGTYPESdate_defmt_asc function.
 750
 751    PGTYPES_INTVL_BAD_INTERVAL #
 752           An invalid interval string was passed to the
 753           PGTYPESinterval_from_asc function, or an invalid interval value
 754           was passed to the PGTYPESinterval_to_asc function.
 755
 756    PGTYPES_DATE_ERR_ENOTDMY #
 757           There was a mismatch in the day/month/year assignment in the
 758           PGTYPESdate_defmt_asc function.
 759
 760    PGTYPES_DATE_BAD_DAY #
 761           An invalid day of the month value was found by the
 762           PGTYPESdate_defmt_asc function.
 763
 764    PGTYPES_DATE_BAD_MONTH #
 765           An invalid month value was found by the PGTYPESdate_defmt_asc
 766           function.
 767
 768    PGTYPES_TS_BAD_TIMESTAMP #
 769           An invalid timestamp string pass passed to the
 770           PGTYPEStimestamp_from_asc function, or an invalid timestamp
 771           value was passed to the PGTYPEStimestamp_to_asc function.
 772
 773    PGTYPES_TS_ERR_EINFTIME #
 774           An infinite timestamp value was encountered in a context that
 775           cannot handle it.
 776
 777 34.6.8. Special Constants of pgtypeslib #
 778
 779    PGTYPESInvalidTimestamp #
 780           A value of type timestamp representing an invalid time stamp.
 781           This is returned by the function PGTYPEStimestamp_from_asc on
 782           parse error. Note that due to the internal representation of the
 783           timestamp data type, PGTYPESInvalidTimestamp is also a valid
 784           timestamp at the same time. It is set to 1899-12-31 23:59:59. In
 785           order to detect errors, make sure that your application does not
 786           only test for PGTYPESInvalidTimestamp but also for errno != 0
 787           after each call to PGTYPEStimestamp_from_asc.