Contents

Datetime and Interval Functions

dtaddinv()

Purpose:

To add an interval value to a datetime value 

Syntax:

mint dtaddinv(dtime_t *d, intrvl_t *i, dtime_t *r);

Notes:

  1. d is a pointer to the initialized datetime host variable. The variable must include all the fields present in the interval value.
  2. i is a pointer to the initialized interval host variable.  The interval value must be in the year to month or the day to fraction(5) range.
  3. r is a pointer to the result. The result inherits the qualifier of d.
  4. Failure to initialize the host variables can produce unpredictable results.

Return code:

0   The addition was successful.
<0 Error in addition.

dtcurrent()

Purpose:

Returns the current date and time 

Syntax:

void dtcurrent(dtime_t *d);

Notes:

  1. d i pointer to the initialized datetime host variable.
  2. The function extends the current date and time to agree with the qualifier of the host variable.

dtcvasc()

Purpose:

To convert an ASCII-standard character string to a datetime value 

Syntax:

mint dtcvasc(char *str, dtime_t *d);

Notes:

  1. str is a pointer to the buffer that contains the ASCII-standard datetime string. 
  2. d is a pointer to a datetime variable, initialized with the qualifier that you want the datetime value to have.

Return code:

0          Conversion was successful.
-1260   It is not possible to convert between the specified types.
-1261  Too many digits in the first field of datetime or interval.
-1262  Non-numeric character in datetime or interval.
-1263  A field in a datetime or interval value is out of range or incorrect.
-1264  Extra characters exist at the end of a datetime or interval.
-1265  Overflow occurred on a datetime or interval operation.
-1266  A datetime or interval value is incompatible with the operation.
-1267  The result of a datetime computation is out of range.
-1268  A parameter contains an invalid datetime qualifier.

ifx_dtcvasc()

Purpose:

To convert a character string to a datetime value; allows you to specify the century setting for 2-digit years

Syntax:

mint ifx_dtcvasc(char *str, dtime_t *d, char db_century);

Notes:

  1. str is a pointer to a buffer that contains an ANSI-standard datetime string.
  2. d is a pointer to a datetime variable, initialized with the desired qualifier.
  3. db_century is one of the following characters, which determines which century to apply to the year portion of the date:

     

    Character  Description
    R    Present. The function uses the two high-order digits of the current year to expand the year value.
    P 

     

    		 Past. The function uses the present and past centuries to expand the year value. It compares these two dates against the current date and uses the century that is prior to the current century. If both dates are prior to the current date, the function uses the century closest to the current date.
    F

     

    		Future. The function uses the present and next centuries to expand the year value. It compares these against the current date and uses the century that is later than the current date. If both dates are later than the current date, the function uses the date closest to the current date.
    C
         		  Closest. The function uses the present, past, and next centuries to expand the year value. It chooses the century that is closest to the current date.

Return code:

0         Conversion was successful.
-1260 It is not possible to convert between the specified types.
-1261 Too many digits in the first field of datetime or interval.
-1262 Non-numeric character in datetime or interval.
-1263 A field in a datetime or interval value is out of range or incorrect.
-1264 Extra characters exist at the end of a datetime or interval.
-1265 Overflow occurred on a datetime or interval operation.
-1266 A datetime or interval value is incompatible with the operation.
-1267 The result of a datetime computation is out of range.
-1268 A parameter contains an invalid datetime qualifier.

dtcvfmtasc()

Purpose:

To convert a character string to a datetime value, specifying the format of the string

Syntax:

mint dtcvfmtasc(char *input, char *fmt, dtime_t *d);

Notes:

  1. input is a pointer to a buffer that contains the string to convert.
  2. d is a pointer to the datetime variable, which must be initialized with the desired qualifer.
  3. fmt is a pointer to a buffer containing the formatting mask. The default date format conforms to the standard ANSI SQL format:
%Y-%m-%d %H:%M:%S

Return code:

0   The conversion was successful.
<0 The conversion failed.

dtextend()

Purpose:

To copy a datetime value id to the datetime value od, adding or dropping fields based on the qualifier of od

Syntax:

mint dtextend(dtime_t *id, dtime_t *od);

Notes:

  1. id  is a pointer to the datetime variable to extend.
  2. od is a pointer to the datetime variable containing a valid qualifier to use for the extension.

Return code:

0         The operation was successful.
-1268  A parameter contains an invalid datetime qualifier.

dtsub()

Purpose:

To subtract one datetime value from another 

Syntax:

mint dtsub(dtime_t *d1, dtime_t *d2, intrvl_t *i);

Notes:

  1. d1 is a pointer to an initialized datetime host variable.
  2. d2 is a pointer to an initialized datetime host variable.
  3. i is a pointer to the interval host variable that contains the result.

Return code:

0     The subtraction was successful.
<0   An error occurred while performing the subtraction.

dtsubinv()

Purpose:

To subtract an interval value from a datetime value

Syntax:

mint dtsubinv(dtime_t *d, intrvl_t *i, dtime_t *r);

Notes:

  1. d is a pointer to an initialized datetime host variable. This must include all the fields present in the interval value i.
  2. i is a pointer to an initialized interval host variable.
  3. r is a pointer to the datetime host variable that contains the result.

Return code:

0     The subtraction was successful.
<0   An error occurred while performing the subtraction.

dttoasc()

Purpose:

To convert a datetime value to an ANSI-standard character string 

Syntax:

mint dttoasc(dtime_t *d, char *str);

Notes:

  1. d is a pointer to the initialized datetime variable to convert.
  2. str is a pointer to the buffer that receives the ANSI-standard DATETIME string for the value in d. It includes one character for each delimiter, plus the fields, which are of the following sizes:
Field   Field Size
year   four digits
fraction of datetime   as specified by precision
all other fields   two digits

For example, datetime year to fraction(5):

YYYY-MM-DD HH:MM:SS.FFFFF

Return code:

0     The conversion was successful.
<0   The conversion failed.

dttofmtasc()

Purpose:

To convert a datetime value to a character string, specifying the format

Syntax:

mint dttofmtasc(dtime_t *d, char *output, mint str_len, char *fmtstr);

Notes:

  1. d  is a pointer to the initialized datetime variable to convert.
  2. output is a pointer to the buffer that receives the string for the value in d.
  3. str_len is the length of the output buffer.
  4. fmtstr is a pointer to the buffer that contains the formatting mask to use for the output string. The default date format conforms to the standard ANSI SQL format:
    %Y-%m-%d %H:%M:%S

Return code:

0     The conversion was successful.
<0   The conversion failed. Check the text of the error message.

incvasc()

Purpose:

To convert an ANSI-standard character string to an interval value

Syntax:

mint incvasc(char *str, intrvl_t *i);

Notes:

  1. str a pointer to a buffer containing an ANSI-standard INTERVAL string.
  2. i is a pointer to an initialized interval variable.

Return code:

0          The conversion was successful.
-1260   It is not possible to convert between the specified types.
-1261  Too many digits in the first field of datetime or interval.

incvfmtasc()

Purpose:

To convert a character string having the specified format to an interval value

Syntax:

mint incvfmtasc(char *input, char *fmt, intrvl_t *intvl);

Notes:

  1. input is a pointer to the string to convert.
  2. intvl is a pointer to the initialized interval variable.
  3. fmt is a pointer to the buffer containing the formatting mask to use for the input string, which must be either in year to month, or in day to fraction ranges.

Return code:

0     The conversion was successful.
<0   The conversion failed.

intoasc()

Purpose:

To convert an interval value to an ANSI-standard character string 

Syntax:

mint intoasc(intrvl_t *i, char *str);

Notes:

  1. i is a pointer to the initialized interval variable.
  2. str is a pointer to the buffer containing the ANSI-standard interval string.

Return code:

0     The conversion was successful.
<0   The conversion failed.

intofmtasc()

Purpose:

To convert an interval value to a character string, specifying the format 

Syntax:

mint intofmtasc(intrvl_t *i, char *output, mint str_len, char *fmtstr);

Notes:

  1. i is a pointer to an initialized interval variable to convert.
  2. output is a pointer to the buffer that receives the string for the value in i.
  3. strlen is the length of the outbuf buffer.
  4. fmtstr is a pointer to the buffer that contains the formatting mask,  which must be either in year to month, or in day to fraction ranges.

Return code:

0     The conversion was successful.
<0   The conversion failed.

invdivdbl()

Purpose:

To divide an interval value by a numeric value

Syntax:

mint invdivdbl(intrvl_t *iv, double dbl, intrvl_t *ov);

Notes:

  1. iv is a pointer to an initialized interval variable to be divided.
  2. dbl is a numeric divisor value, which can be a positive or negative number.
  3. ov is a pointer to an interval variable with a valid qualifier in the year to month class or the day to fraction(5) class.
  4. Both the iv and ov qualifiers must belong to the same qualifier class

Return code:

0         The division was successful.
<0       The division failed.
-1200  A numeric value is too large (in magnitude).
-1201  A numeric value is too small (in magnitude).
-1202  The dbl parameter is zero (0).

invdivinv()

Purpose:

To divide one interval value by another 

Syntax:

mint invdivinv(intrvl_t *i1, intrvl_t *i2, double *res);

Notes:

  1. i1 is a pointer to an initialized interval variable that is the dividend.
  2. i2 is a pointer to an initialized interval variable that is the divisor.
  3. res is a pointer to the double value that is the quotient.
  4. The qualifiers for i1 and i2 must belong to the same interval class, either year to month or day to fraction(5).

Return code:

0       The division was successful.
<0     The division failed.
-1200 A numeric value is too large (in magnitude).
-1201 A numeric value is too small (in magnitude).
-1266 An interval value is incompatible with the operation.
-1268 A parameter contains an invalid interval qualifier.

invextend()

Purpose:

To copy an interval value i to the interval value o, adding or dropping fields based on the qualifier of o 

Syntax:

mint invextend(intrvl_t *i, intrvl_t *o);

Notes:

  1. i a pointer to the initialized interval variable to extend.
  2. o is a pointer to the interval variable with a valid qualifier to use for the extension.

Return code:

0         The conversion was successful.
<0       The conversion failed.
-1266  An interval value is incompatible with the operation.
-1268  A parameter contains an invalid interval qualifier.

invmuldbl()

Purpose:

To multiply an interval value by a numeric value

Syntax:

mint invmuldbl(intrvl_t *iv, double dbl, intrvl_t *ov);

Notes:

  1. iv is a pointer to the interval variable to multiply.
  2. dbl is the numeric double value, which can be a positive or negative number.
  3. ov is a pointer to the resulting interval variable containing a valid qualifier.
  4. Both iv and ov must belong to the same interval class, either year to month or day to fraction(5).

Return code:

0         The multiplication was successful.
<0       The multiplication failed.
-1200  A numeric value is too large (in magnitude).
-1201  A numeric value is too small (in magnitude).
-1266  An interval value is incompatible with the operation.
-1268  A parameter contains an invalid interval qualifier.