Updated on 2024-06-03 GMT+08:00

Timestamp Type

Table 1 lists the common APIs for timestamp data provided by ECPG.

Table 1 Common timestamp type APIs

API

Description

Remarks

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

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

This function accepts a string str to parse and a pointer to a C char* endptr. It returns the parsed timestamp on success and PGTYPESInvalidTimestamp in case of error. In addition, errno is set to PGTYPES_TS_BAD_TIMESTAMP when an error occurs.

The valid input of PGTYPEStimestamp_from_asc is as follows:
1999-01-08 04:05:06    
January 8 04:05:06 1999 PST    
1999-Jan-08 04:05:06.789-8    1999-01-08 04:05:06.789 (time zone specifier ignored)
J2451187 04:05-08:00    1999-01-08 04:05:00 (time zone specifier ignored)

char *PGTYPEStimestamp_to_asc(timestamp tstamp)

Converts a date to a C char* string.

This function accepts the timestamp tstamp as its unique parameter and returns an allocated string containing the textual representation of the timestamp. The result must be released using PGTYPESchar_free().

void PGTYPEStimestamp_current(timestamp *ts)

Returns the current timestamp.

This function obtains the current timestamp and saves it to the timestamp variable that ts points to.

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

Converts a timestamp variable into a C char* using a format mask.

This function accepts a pointer pointing to the timestamp ts to be converted, a pointer pointing to the output buffer output, the maximum length allocated to the output buffer str_len, and the format mask fmtstr for conversion as its parameters.

The function returns 0 on success and a negative value in case of error.

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

Subtracts a timestamp from another timestamp and saves the result in an interval variable.

This function subtracts the timestamp variable that ts2 points to from the timestamp variable that ts1 points to, and stores the result in the interval variable that iv points to.

The function returns 0 on success and a negative value in case of error.

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

Parses the timestamp value from its textual representation using a format mask.

This function accepts a timestamp textual representation placed in the variable str and a format mask placed in the variable fmt that will be used for conversion. The result will be stored in the variable that d points to.

If the format mask fmt is null, the function rolls back to use the default format mask %Y- %m- %d %H: %M: %S.

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

Adds an interval variable to a timestamp variable.

This function accepts a pointer tin pointing to the timestamp variable and a pointer span pointing to the interval variable. It adds the interval to the timestamp and then saves the result timestamp in the variable that tout points to.

The function returns 0 on success and a negative value in case of error.

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

Subtracts an interval variable from a timestamp variable.

This function subtracts the interval variable that span points to from the timestamp variable that tin points to, and then saves the result in the variable that tout points to.

The function returns 0 on success and a negative value in case of error.

Examples

For details, see Examples.