Change Time 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 Time Variable using XCL

Change Time Variable using XCL (CHGTIMXCL)

Where allowed to run:

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

Threadsafe: Yes

Parameters
Examples
Error messages

The Change Time Variable using XCL (CHGTIMXCL) command is used to change the value of a time variable. The change can be in terms of the number of hours, minutes, or seconds to add or subtract from a time, the format of the time, or both.

Top

Parameters

Keyword	Description	Choices	Notes
VAR	Time variable	Character value	Required, Positional 1
FMT	Time format	HMS, ISO, USA, EUR, *JIS	Optional, Positional 2
TIMSEP	Time separator	Character value, FMT, NONE, JOB, BLANK	Optional
TIMADJ	Time 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	HOUR, MINUTE, SECOND, HOURS, MINUTES, SECONDS
BASVAL	Base value	Character value, VAR, CURRENT	Optional
BASFMT	Base format	FMT, JOB, HMS, ISO, USA, EUR, JIS, TS, DTS, EPOCH	Optional

Top

Time variable (VAR)

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

This is a required parameter.

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

Top

Time format (FMT)

Specifies the desired format for the time value returned.

*HMS: The time is to be returned in the format HH:MM:SS. Alternative time separators can be specified with the TIMSEP parameter.
*ISO: The time is to be returned in the format HH.MM.SS. The TIMSEP parameter must specify *FMT.
*USA: The time is to be returned in the format HH:MM XX where XX may be AM or PM. The TIMSEP parameter must specify *FMT.
*EUR: The time is to be returned in the format HH.MM.SS. The TIMSEP parameter must specify *FMT.
*JIS: The time is to be returned in the format HH:MM:SS. The TIMSEP parameter must specify *FMT.

Top

Time separator (TIMSEP)

Specifies the time separator to be used when returning a time value when using *HMS formatting.

*FMT: The time separator is determined by the time format requested. This special value must be specified if FMT is *ISO, *USA, *EUR, or *JIS.
*NONE: No time separator will be used.
*JOB: The time separator is determine by the time separator job attribute.
*BLANK: The time separator is the blank character.
character-value: Specify the time separator to be used.

Top

Time adjustment (TIMADJ)

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

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 hours, minutes, or seconds to change the BASVAL value by. The type of change (hours, minutes, or seconds) is specified by the third element of this parameter.

Element 3: Type of change

*HOURS: The type of change is in hours.
*MINUTES: The type of change is in minutes.
*SECONDS: The type of change is in seconds.
*HOUR: The type of change is in hours.
*MINUTE: The type of change is in minutes.
*SECOND: The type of change is in seconds.

Top

Base value (BASVAL)

Specifies the base, or initial, time to be used for the time returned with the VAR parameter.

*VAR: The initial time is specified by the VAR parameter.
*CURRENT: The initial time is the current system time.
character-value: Specify the time 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 BASVAL parameter is formatted as HH:MM:SS with the actual time separators as defined by the time separator job attribute.
*HMS: The BASVAL parameter is formatted as HH:MM:SS. Time separators are optional.
*ISO: The BASVAL parameter is formatted as HH.MM.SS. Time separators are optional.
*USA: The BASVAL parameter is formatted as HH:MM XX where XX can be either AM or PM, upper or lower case. Time separators are required.
*EUR: The BASVAL parameter is formatted as HH.MM.SS. Time separators are optional.
*JIS: The BASVAL parameter is formatted as HH:MM:SS. Time separators are optional.
*TS: The BASVAL parameter is formatted as a timestamp. Only the time of day portion of the timestamp will be used in setting the initial value. The format is 'YYYY-MM-DD-HH.MM.SS.mmmmmm'.
*DTS: The BASVAL parameter is formatted as an 8-byte system timestamp. Only the time of day portion of the timestamp will be used in setting the initial value. A system timestamp is an 8-byte integer value often returned by system APIs.
*EPOCH: The BASVAL parameter is formatted as a 4-byte integer value representing the number of seconds since January 1 1970 at time 00:00:00. Only the time of day portion of the timestamp will be used in setting the initial value. This 4-byte integer value is often returned by Unix-type system APIs.

Top

Examples for CHGTIMXCL

Example 1: Retrieving the Current System Time

   Dcl        Var(&Tgt_Time)  Type(*Char) Len(8)
   ChgTimXCL  Var(&Tgt_Time) BasVal(*Current)
   SndPgmMsg  Msg('The current time is' *BCat &Tgt_Time)

This example retrieves and then displays the current system time.

Example 2: Adding 30 Minutes to a Time Value

   Dcl        Var(&Tgt_Time)  Type(*Char) Len(8)
   ChgVar     Var(&Tgt_Time) Value('11:00:00')
   ChgTimXCL  Var(&Tgt_Time) TimAdj((*Add 30 *Minutes))

This example add 30 minutes to the time value in CL variable &Tgt_Time.

Top

Error messages for CHGTIMXCL

*ESCAPE Messages

XCL5003: Parameter value &1 is not valid for format &2.
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