The Change Timestamp Variable (CHGTSXCL) command is used to change the value of a timestamp. The change can be in terms of the number of years, months, days, hours, minutes, seconds, milliseconds, or microseconds to add or subtract from a timestamp. The returned result is formatted as 'YYYY-MM-DD-HH.MM.SS.ssssss'.

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

Parameters

Timestamp variable (VAR)

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

This is a required parameter and must be 26 bytes in length.

character-value

Specify the name of the CL variable to receive the new timestamp value.

Timestamp adjustment (TSADJ)

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

The addition or subtraction of one element of a timestamp can impact, and be impacted by, other elements of the timestamp. 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 timestamp indicates that leap year processing should be used.

Note that the order in which you specify the timestamp 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 FROM value.

*SUB

The amount of change specified by the second and third elements of this paramter are to be subtracted from the FROM value.

Element 2: Amount of change

integer

Specify the number of years, months, days, hours, minutes, seconds, milliseconds, or microseconds to change the BASVAL value by. The type of change (years, months, days, hours, minutes, seconds, milliseconds, microseconds) is specified by the third element of this parameter.

Element 3: Type of change

*YEARS

The type of change is in years.

*MONTHS

The type of change is in months.

*DAYS

The type of change is in days.

*HOURS

The type of change is in hours.

*MINUTES

The type of change is in minutes.

*SECONDS

The type of change is in seconds.

*MSECONDS

The type of change is in milliseconds.

*MCRSECONDS

The type of change is in microseconds.

*YEAR

The type of change is in years.

*MONTH

The type of change is in months.

*DAY

The type of change is in days.

*HOUR

The type of change is in hours.

*MINUTE

The type of change is in minutes.

*SECOND

The type of change is in seconds.

*MSECOND

The type of change is in milliseconds.

*MCRSECOND

The type of change is in microseconds.

Base value (BASVAL)

Specifies the bse, or initial, value to be used for the timestamp to be returned with the VAR parameter. The value can be in the form of a timestamp or a date. The format of the value is specified with the BASFMT parameter.

*VAR

The initial timestamp is specified by the VAR parameter.

*CURRENT

The initial timestamp is the current system timestamp.

*CURDATE

The initial timestamp is the start of the current system date.

character-value

Specify the value to be used as the initial timestamp value. The format of the value is specified by the BASFMT parameter.

Base format (BASFMT)

Specifies the format of the BASVAL parameter value. When the format is a date the time elements of the timestamp will be set to the start of the specified date.

*TS

The initial timestamp value is formatted as a timestamp. The format is 'YYYY-MM-DD-HH.MM.SS.mmmmmm'.

*JOB

The initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value is formatted based on the job date format attribute using a 2-digit year.

*MDY

The initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value 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 initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value 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 initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value 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 initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value 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 initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value 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 initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value is formatted with a 2-digit day, a 2-digit month, and a 4-digit day. The use of date separators is optional.

*ISO

The initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value is formatted as an ISO date.

*USA

The initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value is formatted as a USA date.

*EUR

The initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value is formatted as a EUR date.

*JIS

The initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value is formatted as a JIS date.

*CMDY

The initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value 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'.

*CYMD

The initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value 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'.

*CDMY

The initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value 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'.

*JUL

The initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value is formatted with a 2-digit year and a 3-digit day. The use of date separators is optional.

*LONGJUL

The initial timestamp is the start of the day specified with the BASVAL parameter. The BASVAL value is formatted with a 4-digit year and a 3-digit day. The use of date separators is optional.

*DTS

The initial timestamp is the day and time specified with the BASVAL parameter. The BASVAL value is formatted with an 8-byte integer system timestamp. A system timestamp if often returned by system APIs.

*EPOCH

The initial timestamp is the day and time specified with the BASVAL parameter. The BASVAL value is formatted with a 4-byte integer value representing the number of seconds since January 1 1970 at time 00:00:00. This value is often returned by Unix-type system APIs.

Examples for CHGTSXCL

Example 1: Retrieving the Current System Timestamp

    Dcl        Var(&Tgt_TS)    Type(*Char) Len(26)
    ChgTSXCL   Var(&Tgt_TS) BasVal(*Current)
    SndPgmMsg  Msg('The current time is' *BCat &Tgt_TS)

This example retrieves and then displays the current system timestamp.

Example 2: Adding One Month to a Timestamp

    Dcl        Var(&Tgt_TS)    Type(*Char) Len(26)
    ChgVar     Var(&Tgt_TS) +
                 Value('2009-10-22-11.00.00.000000')
    ChgTSXCL   Var(&Tgt_TS) TSAdj((*Add 1 *Month))

This example adds one month to the value of the timestamp in CL variable &Tgt_TS.

Example 3: Setting a Timestamp to 8:30 Today

    Dcl        Var(&Tgt_TS)    Type(*Char) Len(26)
    ChgTSXCL   Var(&Tgt_TS) TSAdj((*Add 8 *Hours) (*Add 30 +
                 *Minutes)) BasVal(*CurDate)
    SndPgmMsg  Msg(&Tgt_TS)

This example sets a timestamp to 8:30 of the current date.

Example 4: Using an Expression to Set a Timestamp

    Dcl        Var(&Tgt_TS)    Type(*Char) Len(26)
    Dcl        Var(&Date_ISO)  Type(*Char) Len(10) +
                 Value('2009-11-05')
    Dcl        Var(&Time_ISO)  Type(*Char) Len(8) +
                 Value('14.00.00')
    ChgTSXCL   Var(&Tgt_TS) TSAdj((*Add 3 *Hours)) +
                 BasVal(&Date_ISO *Cat '-' *Cat &Time_ISO)
    SndPgmMsg  Msg(&Tgt_TS)

This example add 3 hours to the value 2009-11-05-14.00.00.000000 which is expressed with the BASVAL parameter. After the CHGTSXCL command has run the value of CL variable &Tgt_TS is 2009-11-05-17.00.00.000000 representing November 5 2009 at 1700 hours (or 5 PM) in *ISO format.

Error messages for CHGTSXCL

*ESCAPE Messages

XCL5003

Parameter value &1 is not valid for format &2.

XCL5006

Resulting timestamp is 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.