The RTVDATE command converts a date to the user-specified date format. It optionally adds a duration (number of days) to the date before it is converted. The date that is converted my be specified on the DATE parameter or a symbolic date (such as *JOB or *SYSTEM) may be retrieved and converted. The returned date value is in the user-specified date format after the optional duration has been added (note a negative duration may be specified to subtract a number of days).
RTVDATE RTNDATE( CL-var ) RTNFMT( *JOB | date-format ) +
DATE( *JOB | date operator relative-day ) +
DUR( 0 | duration [ *DAYS | *MONTHS *YEARS ] )
If the day is returned in *YMD format and the date is 7 August 2012, the date is returned as 120807 never 12/08/07. To include date separators (aka, "date edit codes") specify the format on the RTNFMT parameter with the separators, for example, RTNFMT('YY/MM/DD') returns the date as 12/08/07.
In addition a duration can be applied to the date. The duration is added to the user-supplied date or the special date value and the new date is returned. Below is an example of the prompted RTVDATE command.
The RTNDATE parameter accepts a character or numeric CL variable that receives the returned date value. The format of the date value that is returned is specified on the RTNFMT parameter. This CL variable should be large enough to hold the entire returned date string. If it is not large enough, the returned date value is truncated on the left.
The RTNFMT parameter specifies the format of the date to be returned on the RTNDATE parameter. All the usual predefined date format codes are supported, in addition any combination of MM DD, YYYY or YY may be specified including DDD, MMM, Y, YY, and YYYY. For example to return the date of 7 August 2012 as 07AUG2012, specify RTNFMT(DDMMMYYYY).
To suppress leading zeros, specify the letter 'Z' in place of the M, D or Y where you want the zeros suppressed. For example, RTNFMT('ZMDDYY') returns the date 8 August 2012 as '80712'.
To include data separator characters within the returned date, use a custom date format code for this parameter. For example, to return the date 7 August 2012 in YYMD format with separators, specify the date format as 'YYYY/MM/DD'. The returned date will be '2012/08/07'.
The DATE parameter identifies the date to be returned. This parameter is made up of 3 components although only 1 is required to retrieve a valid date.
The DUR parameter indicates the optional duration added to the date being returned. After the date is calculated, this value is added to it before it is returned, yielding the new date. For example if 3 days are added to the date of the January 1, 2012, the date returned is January 4, 2012. The DUR parameter consists of two components. The first is the duration itself, the 2nd is the duration code. Specify *DAYS, *MONTHS or *YEARS to indicate what duration is added to the date. The DUR parameter may be negative if subtraction is desired.
Retrieve the job date:
Return the system date:
RTVDATE RTNDATE(&SYSDATE) DATE(*SYSTEM)
Return the date that "this" job started running:
RTVDATE RTNDATE(&JOBSTR) DATE(*JOBSTART)
Return the system date in YYYYMMDD format:
RTVDATE RTNDATE(&SYSDATE) RTNFMT(*YYMD) DATE(*SYSTEM)
Return "last thursday's" date:
RTVDATE RTNDATE(&LastThurs) DATE(*JOB *PRV *THU)
Return the date of the first Friday of the month:
RTVDATE RTNDATE(&FIRSTFRI) DATE(*JOB *FIRST *FRI)
Return the date for 30 days from the current system date:
RTVDATE RTNDATE(&INVDUE) DATE(*SYSTEM) DUR(30)
Return the date for 1 year from today in YMD format:
DCL &NEXTYEAR TYPE(*DEC) LEN(6 0) RTVDATE RTNDATE(&NEXTYEAR) RTNFMT(*YMD) DUR(1 *YEAR)
The RTVDATE command is powerful and not only retrieves dates but also allows you to specify the return format for that date. For example, the date may be returned to a numeric CL variable that is defined as TYPE(*DEC) LEN(6) but it can also return the date to a CL variable defined as TYPE(*CHAR) LEN(20). What would you do with a 20-position returned date variable?
DCL &CDATE TYPE(*CHAR) LEN(20) RTVDATE RTNDATE(&CDATE) RTNFMT(YYYYMMMDD)
This will return the date as text. For example, if the date being retrieve is July 4, 2012, it is returned as "2012JUL04"
This command is part of the COZTOOLS software package available at www.cozTools.com