cozTools-Calc Date/Time Diff (CLDIFF)

Where allowed to run:
  • Batch program (*BPGM)
  • Interactive program (*IPGM)
  • Batch ILE CL module (*BMOD)
  • Interactive ILE CL module (*IMOD)
Threadsafe: No 		Parameters
Examples
Error messages

The Calculate Date/Time Diff (CLDIFF) command calculates the difference (duration) between two date or time values. The two values are the "Older" date value or the "FROM" date parameter and the "Newer" date value or the "TO date parameter. The internal date/time math is performed as follows: 

   duration = NEWER_DATE - OLDER_DATE;

The calculated duration is returned to the CL variable specified on the RTNVAR (returned duration value) parameter.

The DUR (duration) parameter identifies what type of value is returned. It includes a switch so that the results is returned as an Absolute Value. Meaning its sign is removed. This allows either date to be larger than the other and the same value will be returned 3o the RTNVAR parameter.

Restrictions:

Top

Parameters

Keyword Description Choices Notes
FROM Older date/time Element list Required, Positional 1
Element 1: Date or time value Character value, *CURRENT
Element 2: Format (if date) Character value, *DFT, *JOB, *CYMD, *MDY, *YMD, *DMY, *USA, *EUR, *ISO, *JIS
TO Later date/time Element list Required, Positional 2
Element 1: Date or time value Character value, *CURRENT
Element 2: Format (if date) Character value, *DFT, *JOB, *CYMD, *MDY, *YMD, *DMY, *USA, *EUR, *ISO, *JIS
RTNVAR CL var to receive duration Not restricted Required, Positional 3
DUR Duration to return Element list Optional, Positional 4
Element 1: Duration *DAYS, *DAY, *D, *MONTHS, *MONTH, *M, *YEARS, *YEAR, *Y, *SECONDS, *SECOND, *SECS, *SEC, *S, *MINUTES, *MINUTE, *MINS, *MIN, *MN, *HOURS, *HOUR, *H, *MSECONDS, *MSECOND, *MSECS, *MSEC, *MS
Element 2: Return absolute value *ABS, *NOABS, *YES, *NO
Top

Latest date/time (FROM)

Specifies a Date or Time value used to calculate the duration. Normally this is the EARLIER value but it does not need to be. Specify *ABS option on the DUR parameter to remove the sign of the returned duration value.

This is a required parameter.

character-value
Specify the date or time value as a character string. If this value is a Date it should be specified as in *JOB or *CYMD format, unless the date format porition of this parameter is also specified. When a TIME value is specified, it must be in 24-hour clock format and be HHMMSS or HH:MM:SS or any TIME format except *USA (HH:MM AM) which is not supported.
date-format
When a Date is specified for this parameter, use this element to override the format of the date. For example, normally the date is assumed to be in *JOB or *CYMD format. If that is not the case, you may specify any valid date format code. The date will be translated from that format into *JOB format before the CLDIFF command performs the duratino calculation. For example, if the date is 21 June 1988 and the date is specified in YMD format, then FROM(960621 *YMD) would be specified. specified.
Top

Older date/time (TO)

Specifies a date or time value used to calculate the duration. Normally this is the later/newer value but it doesn't need to be. If this value is a date and it should be specified as in *JOB or *CYMD format, unless the date format porition of this parameter is also specified.

This is a required parameter.

character-value
Specify the date or time value as a character string. When a DATE value is specified, it must be either: (1) A 6- or 8-position character value in JOB date format. Or (2) A 7-position character value in *CYMD format (CL date format). If the value is a date and it is in a format other than *JOB or *CYMD, then specify the date format in the second part of this parameter. When a TIME value is specified, it must be in 24-hour clock format and be HHMMSS or HH:MM:SS or any TIME format except *USA (HH:MM AM) which is not supported.
date-format
Specify the date format code for the TO date when a date value is specified for this parameter. Any valid date format is allowed. For example, if the date is 21 June 1996 and the date is specified in DMY format, then TO(210696 *DMY) would be specified. This portion of the parameter is ignored when a Time value is specified.
Top

CL var for returned difference (RTNVAR)

Specifies CL variable that receives the duration.

This is a required parameter.

unrestricted-value
Specify the CL variable of type *CHAR or *DEC to receive the durration. When *CHAR CL variable is specified, the duration is returned, left justified and zero supresesd. When a *DEC value is specified, it must be large enough to hold the duration value; but no specific size is required.
Top

Duration to return (DUR)

Specifies the duration code that controls what calculation is performed. When a Date duration is specified, the FROM/TO parameters must contain a valid date value. When a Time duration is specified, the FROM/TO parameters must contain valid time values. To return the duration as a possitive value regarless of the result from the calculation, specify the absolute value option *ABS on the second part of this parameter.

Element 1: Duration

*DAYS
The number of days between the two dates.
*DAY
The number of days between the two dates.
*D
The number of days between the two dates.
*MONTHS
The number of months between the two dates.
*MONTH
The number of months between the two dates.
*M
The number of months between the two dates.
*YEARS
The number of years between the two dates.
*YEAR
The number of years between the two dates.
*Y
The number of years between the two dates.
*SECONDS
The number of seconds between the two time values.
*SECOND
The number of seconds between the two time values.
*SECS
The number of seconds between the two time values.
*SEC
The number of seconds between the two time values.
*S
The number of seconds between the two time values.
*MINUTES
The number of minutes between the two time values.
*MINUTE
The number of minutes between the two time values.
*MINS
The number of minutes between the two time values.
*MIN
The number of minutes between the two time values.
*MN
The number of minutes between the two time values.
*HOURS
The number of hours between the two time values.
*HOUR
The number of hours between the two time values.
*H
The number of hours between the two time values.

Element 2: Return absolute value

*ABS
The duration is returned as an Absolute Value. That is it is returned as a positive value. If the Duration result is negative, its sign is reversed before it is returned--returning a positive value.
*NOABS
The duration is returned with its natural sign. Positive or negative.
*YES
Same as specifying *ABS.
*NO
Same as specifying *NOABS.
Top

Examples

None
Top

Error messages

Unknown
Top