Retrieve Duration using XCL

Main Menu

Programming Services

Do you need a program written?

Bruce Vining Services can provide highly experienced IBM i developers to supplement your staff with short term contracts. We don't do general ledger but if you are looking for custom solutions involving system functions such as database, communications, security, encryption, print, and work management you will find your answers at Bruce Vining Services.

Retrieve Duration using XCL

PDF

Print

E-mail

Retrieve Duration using XCL (RTVDURXCL)

Where allowed to run:

Batch program (*BPGM)
Interactive program (*IPGM)

Threadsafe: Yes

Parameters
Examples
Error messages

The Retrieve Duration using XCL (RTVDURXCL) command returns the duration, or difference, between two points in time. The duration can be in units of years, months, days, hours, minutes, seconds, or microseconds. The two points in time can be any combination of time fields, date fields, and timestamp fields. Time fields are assumed to be for the current day. Date fields are assumed to represent the start of the day.

If the starting point in time (STRVAL) is earlier than the ending point in time (ENDVAL) the duration will be returned as positive numbers. If the STRVAL value is later than the ENDVAL value the duration will be returned as negative numbers.

All durations are calculated as if the Gregorian calendar had started in year 0001.

Parameters

Keyword	Description	Choices	Notes
STRVAL	Start value	Character value, *CURRENT	Optional, Positional 1
STRFMT	Start format	TS, JOB, MDY, YMD, DMY, MDYY, YYMD, DMYY, ISO, USA, EUR, JIS, CMDY, CYMD, CDMY, JUL, LONGJUL, DTS, EPOCH, HMS, TIMISO, TIMUSA, TIMEUR, TIMJIS	Optional
ENDVAL	End value	Character value, *CURRENT	Optional
ENDFMT	End format	TS, JOB, MDY, YMD, DMY, MDYY, YYMD, DMYY, ISO, USA, EUR, JIS, CMDY, CYMD, CDMY, JUL, LONGJUL, DTS, EPOCH, HMS, TIMISO, TIMUSA, TIMEUR, TIMJIS	Optional
YEARS	Years	Integer	Optional
MONTHS	Months	Integer	Optional
DAYS	Days	Integer	Optional
HOURS	Hours	Integer	Optional
MINUTES	Minutes	Integer	Optional
SECONDS	Seconds	Integer	Optional
MCRSECONDS	Microseconds	Integer	Optional

Start value (STRVAL)

Specifies the starting point in time value.

*CURRENT: The current system date and time is used.
character-value: Specify the starting point in time value. The format of this parameter is determined by the STRFMT parameter.

Start format (STRFMT)

Specifies the format of the STRVAL parameter.

*TS: The STRVAL parameter is formatted as a 26-byte timestamp value. The format is 'YYYY-MM-DD-HH.MM.SS.mmmmmm'.
*JOB: The job date format attribute is used with a 2-digit year.
*MDY: The STRVAL parameter is formatted with a 2-digit month, a 2-digit day, and a 2-digit year. The use of date separators is optional.
*YMD: The STRVAL parameter is formatted with a 2-digit year, a 2-digit month, and a 2-digit day. The use of date separators is optional.
*DMY: The STRVAL parameter is formatted with a 2-digit day, a 2-digit month, and a 2-digit year. The use of date separators is optional.
*MDYY: The STRVAL parameter is formatted with a 2-digit month, a 2-digit day, and a 4-digit year. The use of date separators is optional.
*YYMD: The STRVAL parameter is formatted with a 4-digit year, a 2-digit month, and a 2-digit day. The use of date separators is optional.
*DMYY: The STRVAL parameter is formatted with a 2-digit day, a 2-digit month, and a 4-digit year. The use of date separators is optional.
*ISO: The STRVAL parameter is formatted with a 4-digit year, a '-', a 2-digit month, a '-', and a 2-digit year.
*USA: The STRVAL parameter is formatted with a 2-digit month, a '/', a 2-digit day, a '/', and a 4-digit year.
*EUR: The STRVAL parameter is formatted with a 2-digit day, a '.', a 2-digit month, a '.', and a 4-digit year.
*JIS: The STRVAL paramter is formatted with a 4-digit year, a '-', a 2-digit month, a '-', and a 2-digit day.
*CYMD: The STRVAL parameter is formatted with a 1-digit century, a 2-digit year, a 2-digit month, and a 2-digit day. A century value of 0 represents a year starting with '19', a century value of 9 represents a year starting with '28'. The use of date separators is optional.
*CDMY: The STRVAL parameter is formatted with a 1-digit century, a 2-digit day, a 2-digit month, and a 2-digit year. A century value of 0 represents a year starting with '19', a century value of 9 represents a year starting with '28'. The use of date separators is optional.
*CMDY: The STRVAL parameter is formatted with a 1-digit century, a 2-digit month, a 2-digit day, and a 2-digit year. A century value of 0 represents a year starting with '19', a century value of 9 represents a year starting with '28'. The use of date separators is optional.
*JUL: The STRVAL parameter is formatted with a 2-digit year and a 3-digit day. The use of date separators is optional.
*LONGJUL: The STRVAL parameter is formatted with a 4-digit year and a 3-digit day. The use of date separators is optional.
*DTS: The STRVAL parameter is formatted as an 8-byte system timestamp. A system time stamp is an 8-byte integer value often returned by system APIs.
*EPOCH: The STRVAL parameter is formatted as a 4-byte signed integer value representing the number of seconds since January 1 1970 at time 00:00:00. This 4-byte integer value is often returned by Unix-type system APIs.
*HMS: The STRVAL parameter is formatted as HH:MM:SS. Time separators are optional.
*TIMISO: The STRVAL parameter is formatted as HH.MM.SS. Time separators are optional.
*TIMUSA: The STRVAL parameter is formatted as HH:MM XX where XX can be either AM or PM, upper or lower case. Time separators are required.
*TIMEUR: The STRVAL parameter is formatted as HH.MM.SS. Time separators are optional.
*TIMJIS: The STRVAL parameter is formatted as HH:MM:SS. Time separators are optional.

End value (ENDVAL)

Specifies the ending point in time value.

*CURRENT: The current system date and time is used.
character-value: Specify the ending point in time value. The format of this parameter is determined by the ENDFMT parameter.

End format (ENDFMT)

Specifies the format of the ENDVAL parameter.

*TS: The ENDVAL parameter is formatted as a 26-byte timestamp value. The format is 'YYYY-MM-DD-HH.MM.SS.mmmmmm'.
*JOB: The job date format attribute is used with a 2-digit year.
*MDY: The ENDVAL parameter is formatted with a 2-digit month, a 2-digit day, and a 2-digit year. The use of date separators is optional.
*YMD: The ENDVAL parameter is formatted with a 2-digit year, a 2-digit month, and a 2-digit day. The use of date separators is optional.
*DMY: The ENDVAL parameter is formatted with a 2-digit day, a 2-digit month, and a 2-digit year. The use of date separators is optional.
*MDYY: The ENDVAL parameter is formatted with a 2-digit month, a 2-digit day, and a 4-digit year. The use of date separators is optional.
*YYMD: The ENDVAL parameter is formatted with a 4-digit year, a 2-digit month, and a 2-digit day. The use of date separators is optional.
*DMYY: The ENDVAL parameter is formatted with a 2-digit day, a 2-digit month, and a 4-digit year. The use of date separators is optional.
*ISO: The ENDVAL parameter is formatted with a 4-digit year, a '-', a 2-digit month, a '-', and a 2-digit year.
*USA: The ENDVAL parameter is formatted with a 2-digit month, a '/', a 2-digit day, a '/', and a 4-digit year.
*EUR: The ENDVAL parameter is formatted with a 2-digit day, a '.', a 2-digit month, a '.', and a 4-digit year.
*JIS: The ENDVAL paramter is formatted with a 4-digit year, a '-', a 2-digit month, a '-', and a 2-digit day.
*CYMD: The ENDVAL parameter is formatted with a 1-digit century, a 2-digit year, a 2-digit month, and a 2-digit day. A century value of 0 represents a year starting with '19', a century value of 9 represents a year starting with '28'. The use of date separators is optional.
*CDMY: The ENDVAL parameter is formatted with a 1-digit century, a 2-digit day, a 2-digit month, and a 2-digit year. A century value of 0 represents a year starting with '19', a century value of 9 represents a year starting with '28'. The use of date separators is optional.
*CMDY: The ENDVAL parameter is formatted with a 1-digit century, a 2-digit month, a 2-digit day, and a 2-digit year. A century value of 0 represents a year starting with '19', a century value of 9 represents a year starting with '28'. The use of date separators is optional.
*JUL: The ENDVAL parameter is formatted with a 2-digit year and a 3-digit day. The use of date separators is optional.
*LONGJUL: The ENDVAL parameter is formatted with a 4-digit year and a 3-digit day. The use of date separators is optional.
*DTS: The ENDVAL parameter is formatted as an 8-byte system timestamp. A system time stamp is an 8-byte integer value often returned by system APIs.
*EPOCH: The ENDVAL parameter is formatted as a 4-byte signed integer value representing the number of seconds since January 1 1970 at time 00:00:00. This 4-byte integer value is often returned by Unix-type system APIs.
*HMS: The ENDVAL parameter is formatted as HH:MM:SS. Time separators are optional.
*TIMISO: The ENDVAL parameter is formatted as HH.MM.SS. Time separators are optional.
*TIMUSA: The ENDVAL parameter is formatted as HH:MM XX where XX can be either AM or PM, upper or lower case. Time separators are required.
*TIMEUR: The ENDVAL parameter is formatted as HH.MM.SS. Time separators are optional.
*TIMJIS: The ENDVAL parameter is formatted as HH:MM:SS. Time separators are optional.

Years (YEARS)

Specifies the CL variable to receive the number of years between the STRVAL and ENDVAL values. Returned durations represent whole units of time so a duration of 13 months is returned as 1 year.

integer: Specify a variable defined as Type(*Int).

Months (MONTHS)

Specifies the CL variable to receive the number of months between the STRVAL and ENDVAL values. Returned durations represent whole units of time so a duration of 40 days is returned as 1 month.

integer: Specify a variable defined as Type(*Int).

Days (DAYS)

Specifies the CL variable to receive the number of days between the STRVAL and ENDVAL values. Returned durations represent whole units of time so a duration of 25 hours is returned as 1 day.

integer: Specify a variable defined as Type(*Int).

Hours (HOURS)

Specifies the CL variable to receive the number of hours between the STRVAL and ENDVAL values. Returned durations represent whole units of time so a duration of 65 minutes is returned as 1 hour.

integer: Specify a variable defined as Type(*Int).

Minutes (MINUTES)

Specifies the CL variable to receive the number of minutes between the STRVAL and ENDVAL values. Returned durations represent whole units of time so a duration of 65 seconds is returned as 1 minute.

integer: Specify a variable defined as Type(*Int).

Seconds (SECONDS)

Specifies the CL variable to receive the number of seconds between the STRVAL and ENDVAL values. Returned durations represent whole units of time so a duration of less than one second is returned as 0 seconds.

integer: Specify a variable defined as Type(*Int).

Microseconds (MCRSECONDS)

Specifies the CL variable to receive the number of microseconds between the STRVAL and ENDVAL values.

integer: Specify a variable defined as Type(*Int).

Examples for RTVDURXCL

Example 1: Retrieving Months, Days, and Hours

    Dcl        Var(&Months) Type(*Int)
    Dcl        Var(&Days)   Type(*Int)
    Dcl        Var(&Hours)  Type(*Int)
    RtvDurXCL  StrVal('2009-11-03') StrFmt(*ISO) +
                 EndVal('11/04/09') EndFmt(*MDY) +
                 Months(&Months) Days(&Days) Hours(&Hours)

This example retrieves the number of months, days, and hours between a starting value of November 3 2009 and an ending value of November 4 2009. After the command runs the CL variable &Months will have a value of 0, variable &Days will have a value of 1, and variable &Hours will have a value of 24.

Example 2: Retrieving Days Between and Expression and the Current Date

    Dcl        Var(&Days)   Type(*Int)
    Dcl        Var(&Str_Month) Type(*Char) Len(2) +
                 Value('10')
    Dcl        Var(&Str_Day)   Type(*Char) Len(2) +
                 Value('13')
    Dcl        Var(&Str_Year)  Type(*Char) Len(4) +
                 Value('2009')
    RtvDurXCL  StrVal(&Str_Month *Cat &Str_Day *Cat +
                 &Str_Year) StrFmt(*MDYY) Days(&Days)

This example retrieves the number of days between a starting value of October 13 2009 in *MDYY format and the current date in timestamp format.

Error messages for RTVDURXCL

*ESCAPE Messages

XCL5003: Parameter value &1 is not valid for format &2.
XCL5008: The duration is too large to express in &1.
XCL9002: Function did not complete. See previously listed messages related to possible user errors.
XCL9003: Function did not complete. See previously listed messages for possible cause.
XCL9004: Function did not complete. See previously listed messages for possible cause.

Joomla 1.5 Templates by Joomlashack