Change Date Variable 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.

Change Date Variable using XCL

Change Date Variable using XCL (CHGDATXCL)

Where allowed to run:

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

Threadsafe: Yes

Parameters
Examples
Error messages

The Change Date Variable using XCL (CHGDATXCL) command is used to change the value of a date variable. The change can be in terms of the number of years, months, or days to add or subtract from a date, the format of the date, or both.

Only valid dates can be changed. For dates with 2-digit years valid dates are in the range of January 1 1940 to December 31 2039. For dates with 2-digit years and a century indicator valid dates are in the range of January 1 1900 to December 31 2899. For dates with 4-digit years valid dates are in the range January 1 0001 to December 31 9999.

All date changes are as if the Gregorian calendar had started in year 0001.

Top

Parameters

Keyword	Description	Choices	Notes
VAR	Date variable	Character value	Required, Positional 1
FMT	Date format	JOB, MDY, YMD, DMY, MDYY, YYMD, DMYY, ISO, USA, EUR, JIS, CMDY, CYMD, CDMY, JUL, LONGJUL, DTS, EPOCH	Optional, Positional 2
DATSEP	Date separator	Character value, FMT, JOB, NONE, BLANK	Optional
DATADJ	Date adjustment	Values (up to 50 repetitions): Element list	Optional
	Element 1: Direction of change	ADD, SUB
	Element 2: Amount of change	Integer
	Element 3: Type of change	DAY, MONTH, YEAR, DAYS, MONTHS, YEARS
BASVAL	Base value	Character value, VAR, CURRENT	Optional
BASFMT	Base format	FMT, JOB, MDY, YMD, DMY, MDYY, YYMD, DMYY, ISO, USA, EUR, JIS, CMDY, CYMD, CDMY, JUL, LONGJUL, DTS, EPOCH, TS	Optional

Top

Date variable (VAR)

Specifies the CL variable to receive the new date value. When BASVAL(*VAR) is specified this CL variable is also used as an input to set the base (or initial) date value.

The minimum required size of the CL variable is determined by the date format (FMT) and date separator (DATSEP) requested. See the help text for FMT to determine the required minimum length of the variable.

If the length of the CL variable is greater than the minimum required size any excess bytes are set to blanks.

This is a required parameter.

character-value: Specify the name of the CL variable to receive the new date value.

Top

Date format (FMT)

Specifies the desired format for the date value returned.

*JOB

The date is to be returned in the format specified by the job attribute DATFMT. The required minimum size of the VAR variable depends on the job date format and whether or not date separators are to be returned.

When the job date format attribute is *YMD, *MDY, or *DMY and DATSEP(*NONE) is specified the required minimum length of the VAR variable is six (6) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is eight (8) bytes.

When the job date format attribute is *JUL and DATSEP(*NONE) is specified the required minimum length of the VAR variable is five (5) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is six (6) bytes.

*MDY

The date is to be returned in the format month, day, and year (MMDDYY). If DATSEP(*NONE) is specified the required minimum length of the VAR variable is six (6) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is eight (8) bytes.

*YMD

The date is to be returned in the format year, month, and day (YYMMDD). If DATSEP(*NONE) is specified the required minimum length of the VAR variable is six (6) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is eight (8) bytes.

*DMY

The date is to be returned in the format day, month, and year (DDMMYY). If DATSEP(*NONE) is specified the required minimum length of the VAR variable is six (6) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is eight (8) bytes.

*MDYY

The date is to be returned in the format month, day, and 4-digit year (MMDDYYYY). If DATSEP(*NONE) is specified the required minimum length of the VAR variable is eight (8) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is ten (10) bytes.

*YYMD

The date is to be returned in the format 4-digit year, month, and day (YYYYMMDD). If DATSEP(*NONE) is specified the required minimum length of the VAR variable is eight (8) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is ten (10) bytes.

*DMYY

The date is to be returned in the format day, month, and 4-digit year (DDMMYYYY). If DATSEP(*NONE) is specified the required minimum length of the VAR variable is eight (8) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is ten (10) bytes.

*ISO

The date is to be returned in the format YYYY-MM-DD. The DATSEP parameter must specify *FMT and the required minimum length is ten (10) bytes.

*USA

The date is to be returned in the format MM/DD/YYYY. The DATSEP parameter must specify *FMT and the required minimum length is ten (10) bytes.

*EUR

The date is to be returned in the format DD.MM.YYYY. The DATSEP parameter must specify *FMT and the required minimum length is ten (10) bytes.

*JIS

The date is to be returned in the format YYYY-MM-DD. The DATSEP parameter must specify *FMT and the required minimum length is ten (10) bytes.

*CMDY

The date is to be returned in the format century, month, day, and year (CMMDDYY). If DATSEP(*NONE) is specified the required minimum length of the VAR variable is seven (7) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is nine (9) bytes.

*CYMD

The date is to be returned in the format century, year, month, and day (CYYMMDD). If DATSEP(*NONE) is specified the required minimum length of the VAR variable is seven (7) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is nine (9) bytes.

*CDMY

The date is to be returned in the format century, day, month, and year (CDDMMYY). If DATSEP(*NONE) is specified the required minimum length of the VAR variable is seven (7) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is nine (9) bytes.

*JUL

The date is to be returned in the format year and day of year (YYDDD). If DATSEP(*NONE) is specified the required minimum length of the VAR variable is five (5) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is six (6) bytes.

*LONGJUL

The date is to be returned in the format year and day of year (YYYYDDD). If DATSEP(*NONE) is specified the required minimum length of the VAR variable is seven (7) bytes. If DATSEP(*NONE) is not specified the required minimum length of the VAR variable is eight (8) bytes.

*DTS

The date is to be returned in the format of a system time stamp. A system time stamp is an 8-byte integer value often used with system APIs. The DATSEP parameter must specify *FMT and the required minimum length is eight (8) bytes.

*EPOCH

The date is to be returned in the format of a 4-byte signed integer value representing the number of seconds since January 1 1970 at time 00:00:00. This format is often used by Unix-type APIs. The DATSEP parameter must specify *FMT and the required minimum length is four (4) bytes.

Top

Date separator (DATSEP)

Specifies the date separator to be used when returning the VAR value. For FMTs of *ISO, *USA, *EUR, *JIS, *DTS, and *EPOCH the DATSEP value must be *FMT. These formats use a predetermined date separator that cannot be changed.

*FMT: The date separator is determined by the date format requested. For formats other than *ISO, *USA, *EUR, *JIS, *DTS, and *EPOCH the date separator will be based on the date separator job attribute.
*JOB: The date separator is determined by the date separator job attribute.
*NONE: No date separator will be used.
*BLANK: The blank character will be used.
character-value: Specify the date separator to be used.

Top

Date adjustment (DATADJ)

Specifies any addition or subtraction that should be performed on the BASVAL when returning the VAR value.

The addition or subtraction of one element of a date can impact, and be impacted by, other elements of the date. For instance adding one (1) month to January 30 can result in a date of either February 28 or February 29 depending on whether the year element of the date indicates that leap year processing should be used.

Note that the order in which you specify the date changes can impact the returned value. For instance adding one (1) month to February 28 2009 and then adding two (2) days will result in March 30 2009. Reversing the order, adding two (2) days and then one (1) month will result in April 2 2009.

You can specify 50 values for this parameter.

Element 1: Direction of change

*ADD: The amount of change specified by the second and third elements of this parameter are to be added to the BASVAL value.
*SUB: The amount of change specified by the second and third elements of this parameter are to be subtracted from the BASVAL value.

Element 2: Amount of change

integer: Specify the number of days, months, or years to change the BASVAL value by. The type of change (days, months, or years) is specified by the third element of this parameter.

Element 3: Type of change

*DAY: The type of change is in days.
*MONTH: The type of change is in months.
*YEAR: The type of change is in years.
*DAYS: The type of change is in days.
*MONTHS: The type of change is in months.
*YEARS: The type of change is in years.

Top

Base value (BASVAL)

Specifies the initial date to be used for the date to be returned with the VAR parameter.

*VAR: The initial date is specified by the VAR parameter.
*CURRENT: The initial date is the current system date.
character-value: Specify the date to be used as the initial value. The format of this parameter is determined by the BASFMT parameter.

Top

Base format (BASFMT)

Specifies the format of the BASVAL parameter.

*FMT: The BASVAL parameter value is formatted based on the FMT parameter value.
*JOB: The job date format attribute is used with a 2-digit year.
*MDY: The BASVAL 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 BASVAL 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 BASVAL 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 BASVAL 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 BASVAL 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 BASVAL 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 BASVAL parameter is formatted with a 4-digit year, a '-', a 2-digit month, a '-', and a 2-digit year.
*USA: The BASVAL parameter is formatted with a 2-digit month, a '/', a 2-digit day, a '/', and a 4-digit year.
*EUR: The BASVAL parameter is formatted with a 2-digit day, a '.', a 2-digit month, a '.', and a 4-digit year.
*JIS: The BASVAL paramter is formatted with a 4-digit year, a '-', a 2-digit month, a '-', and a 2-digit day.
*CYMD: The BASVAL 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 BASVAL 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 BASVAL 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 BASVAL parameter is formatted with a 2-digit year and a 3-digit day. The use of date separators is optional.
*LONGJUL: The BASVAL parameter is formatted with a 4-digit year and a 3-digit day. The use of date separators is optional.
*DTS: The BASVAL 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 BASVAL 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.
*TS: The BASVAL parameter is formatted as a 26-byte timestamp value. The format is 'YYYY-MM-DD-HH.MM.SS.mmmmmm'.

Top

Examples for CHGDATXCL

Example 1: Change the Date Format with One Variable

Dcl        Var(&Tgt_Date)  Type(*Char) Len(10)
ChgVar     Var(&Tgt_Date) Value('1091020')
ChgDatXCL  Var(&Tgt_Date) Fmt(*MDYY) +
             BasVal(*Var) BasFmt(*CYMD)

This example demonstrates changing a date format. The CL variable &Tgt_Date (Target Date) is set to the value '1091020' which represents October 20 2009 in date format *CYMD. The CHGDATXCL command returns the *MDYY formatted value '10/20/2009' in CL variable &Tgt_Date. Date separators are returned due to the default for the DATSEP parameter of *FMT. DATSEP(*FMT) uses the job date separator attribute DATSEP when returning a *MDYY date format.

The BASVAL keyword could have been omitted from the example as *VAR is the default value.

Example 2: Change the Date Format with Two Variables

Dcl        Var(&Orig_Date) Type(*Char) Len(10)
Dcl        Var(&Tgt_Date)  Type(*Char) Len(10)
ChgVar     Var(&Orig_Date) Value('1091020')
ChgDatXCL  Var(&Tgt_Date) Fmt(*MDYY) +
             BasVal(&Orig_Date) BasFmt(*CYMD)

This example demonstrates changing a date format. The CL variable &Orig_Date (Original Date) is set to the value '1091020' which represents October 20 2009 in date format *CYMD. The CHGDATXCL command returns the *MDYY formatted value '10/20/2009' in CL variable &Tgt_Date.

Example 3: Change the Date

Dcl        Var(&Tgt_Date)  Type(*Char) Len(10)
ChgVar     Var(&Tgt_Date) Value('1091020')
ChgDatXCL  Var(&Tgt_Date) Fmt(*CYMD) +
             DatAdj((*Add 2 *Days))

This example demonstrates adjusting the value of a date. The CL variable &Tgt_Date is set to the value '1091020' which represents October 20 2009 in date format *CYMD. The CHGDATXCL command adds two days this value and returns the *CYMD formatted value '109/10/22' in CL variable &Tgt_Date.

Example 4: Change the Date and the Format

Dcl        Var(&Tgt_Date)  Type(*Char) Len(10)
ChgVar     Var(&Tgt_Date) Value('1091020')
ChgDatXCL  Var(&Tgt_Date) Fmt(*MDYY) +
             DatAdj((*Add 2 *Days)) +
             BasVal(*Var) BasFmt(*CYMD)

This example demonstrates changing both the value and the format of a date. The CL variable &Tgt_Date is set to the value '1091020' which represents October 20 2009 in date format *CYMD. The CHGDATXCL command adds two days this value and returns the *MDYY formatted value '10/22/2009' in CL variable &Tgt_Date.

Example 5: Add 30 Days to the Current Date

Dcl        Var(&Tgt_Date)  Type(*Char) Len(10)
ChgDatXCL  Var(&Tgt_Date) Fmt(*ISO) DatAdj((*Add 30 +
             *Days)) BasVal(*Current)

This example adds 30 days to the current date and returns the value in *ISO format. If the current date is October 20 2009 the returned value of CL variable &Tgt_Date will be '2009-11-19' representing November 19 2009.

Example 6: Add 2 Days to a Date Expression

Dcl        Var(&Tgt_Date)   Type(*Char) Len(10)
Dcl        Var(&Orig_Year)  Type(*Char) Len(2) +
             Value('09')
Dcl        Var(&Orig_Month) Type(*Char) Len(2) +
             Value('11')
Dcl        Var(&Orig_Day)   Type(*Char) Len(2) +
             Value('05')
ChgDatXCL  Var(&Tgt_Date) Fmt(*Eur) DatAdf((*Add 2 *Days)) +
             BasVal(&Orig_Month *Cat &Orig_Day +
             *Cat &Orig_Year) BasFmt(*MDY)

This example adds 2 days to the calculated BASVAL value of 110509 representing November 5 2009 in *MDY format. After the CHGDATXCL command runs CL variable &Tgt_Date will be set to the value '07.11.2009' representing November 7 2009 in *EUR format.

Top

Error messages for CHGDATXCL

*ESCAPE Messages

XCL5001: Resulting date cannot be represented with format &1.
XCL5002: VAR parameter must be a minimum size of &2 for FMT(&1) and DATSEP(&4).
XCL5003: Parameter value &1 is not valid for format &2.
XCL5005: Date adjustment &1 &2 &3 results in a date outside of supported range.
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.

Top

Release the NEW Power of CL