RTVDATE (Retrieve and Convert Date) Command

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.

Required Parameters

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.

Optional Parameters

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.

1. Date - The date to be returned. This can be a real date in CL date format (which is specified in standard CL command date format: CYYMMDD or MMDDYY or the job date format) or one of the following symbolic dates values:
• *JOB - The job date.
• *SYSTEM - The system date.
• *JOBSTART - The date the job entered the system; the "job start" date.
• *YESTERDAY - Yesterday's date based on the system date.
• *TODAY - Today's date based on the system date.
• *TOMORROW - Tomorrow's date based on the system date.
• *BOM - use the first of the month for the current system date.
• *EOM - Use the end of month date for the current system date.
2. Operator - This value controls the actual date returned relative to the Date. It is used in conjunction with Relative Date value. Specify any of the relative operations, including:
• *PRV returns the date for the previous day of the week defined on the Relative Day component.
• *THIS returns the next date for the day identified on the Day component unless the Base Date is already that day, in which case the same date as the base date is returned.
• *NEXT returns the next date for the day identified on the Day component.
• *FIRST returns the first date of the month (from the Base Date) that is the day identified on the Relative Day component.
• *LAST returns the last (final) date of the month (from the Base Date) for the day identified on the Relative Day component.
• *EOM returns the date of the end of the month for the date identified on the Base Date parameter--the Day component is ignored.
• *BOM returns the date of the 1st of the month for the date identified on the Base Date parameter--the Day component is ignored.
• 1 to 5 returns the date of the 1st to 5th occurrence of the day identified on the Relative Day component for the month identified in the Base Date.
3. Relative Day - Specify one of the 7 special values for the day of the week. Valid choices include *SUN, *MON, *TUE, *WED, *THU, *FRI, *SAT

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.

Examples

Retrieve the job date:

RTVDATE RTNDATE(&JOBDATE)

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"

Requirements:

• IBM i v5.4 or later.
• COZTOOLS *SRVPGM
• RTVDATE Command Definition
• RTVDATE RPG IV Program

This command is part of the COZTOOLS software package available at www.cozTools.com