The BETIMES Tool

BETIMES is a utility program for changing MPE XL’s current time or date.

Operation

There is often a need to change the current date and/or time that MPE XL maintains. Sometimes, a system is booted up with the incorrect date (or time). Sometimes, it would be convenient to change the date (or time) to test software that is sensitive to these values. MPE XL does not provide a mechanism to change the date or time. Thus, the need for BETIMES.

BETIMES allows the date and/or time to be changed via a simple user interface. If the new date (or time) is known, it can be entered directly with the DATE or TIME commands. If the offset is known (i.e.: the time is one hour too early), then the date (or time) can be changed by just that small amount (with the ADD and SUBTRACT commands).

When MPE XL boots, the START dialog fetches the date and time from a hardware clock. The hardware clock is supposed to have the correct GMT (Greenwich Mean Time) date and time. Additionally, the operating system maintains an offset which, when added to GMT, produces the local date and time. If the GMT time is incorrect, the CLKUTIL program should be used the next time the machine is at the "ISL>" prompt.

NOTE If the date (or time) is corrected with BETIMES, it will have to be re-entered correctly the next time MPE XL reboots.

Why doesn't BETIMES simply update the internal "offset from GMT", and thus eliminate the need to correct the clock when a reboot is finally done? Because the GMT offset is stored in an EEPROM in the computer. Each location in the EEPROM can be written to approximately 10,000 times before it burns out. BETIMES has no desire to be responsible for burning out an important piece of hardware! Lund cautions users to be very wary of running clock utility programs that purport to update the GMT offset!

Capabilities

BETIMES requires that the user have SM capability.

Usage

BETIMES can be run via the supplied UDC or a fully-qualified RUN statement.

UDC

BETIMES <command>

RUN

RUN BETIMES.PUB.LPSTOOLS;INFO=“<command>”

If BETIMES is run with an INFO string, then it is interpreted as a single command, followed by an implicit EXIT command.

Thus, a UDC could be written that would set the date back by one year as follows:

BACKONEYEAR

RUN BETIMES.PUB.LPSTOOLS;INFO="SUBTRACT 1 YEAR"

To see just an overview of BETIMES abilities (and limits), type:

HELP OVERVIEW

Command Summary

Following is a summary list of BETIMES commands.

Table 4.1 BETIMES Commands

Command Code	Description
ADD	Adds to current date and time
DATE	Sets to specified value
EXIT	Terminates BETIMES
GLOBALS	Used for debugging BETIMES
GMTSECS	Reports the number of seconds the clock is offset from GMT time, and the number of seconds that have elapsed since the start of 1970-01-01
HELP	Invokes BETIMES help
NETCLOCK	Fetches the current time from a network time sever via a serial port, and then sets the local machine's clock to that value
NOW	Displays current date and time
RESET	Overrides the MPE/iX SETCLOCK command
SET	Used to set the SETCLOCK command
SUBTRACT	Subtracts from the current date and time
SYNCH	Synchronizes the hardware and software clocks
TICKS	Reports some internal time-oriented operating system values.
TIME	Synonym for DATE
TIMER	Tests the MPE/iX time routines, including the TIMER and PAUSE intrinsics
UPTIME	Reports when the system was booted up
//	Synonym for EXIT
?	Synonym for HELP
: <command>	A colon (:) followed by an MPE command or UDC name is passed to the HPCICOMMAND intrinsic

Command Definitions

This section describes BETIMES commands in detail.

ADD

This command has the following syntax:

ADD # <quantity> [# <quantity>...]

The ADD command adds to the current date and time.

<quantity>	[Years]	0 .. 99
	[MOnths]	0 .. 11
	[Days]	0 .. 31
	[Hours]	0 .. 23
	[MInutes]	0 .. 59
	[Seconds]	0 .. 59
#	a decimal number (with the above limits)

DATE

This command has the following syntax:

DATE [<yyyy/mm/dd> | <mm/dd/yy>] [hh:mm[:ss]]

The DATE command sets the date and/or time to the specified value. A date, a time, or both (in any order) may be entered.

Dates may be entered in International style (a four digit year, one or two digit month, and one or two digit day-of-month), or in American style (one or two digit month, one or two digit day-of- month, and 2 digit year).

Times must be entered in 24-hour format (i.e., military time). The number of seconds is optional and defaults to 0.

NOTE The TIME command is a synonym for DATE.

EXIT or "//"

The EXIT command is used to terminate BETIMES. // is accepted as a synonym.

GLOBALS

The GLOBALS command is used for debugging BETIMES. It reports global time-oriented data structures within MPE/iX.

GMTSECS

Reports the number of seconds the clock is offset from GMT time, and the number of seconds that have elapsed since the start of 1970-01-01. Note that MPE has two methods of to determining this value. "ticks since 1970" is the value in terms of the local time, and gmt_secs is the value in GMT time. Thus, if you are on Pacific Daylight Time, ticks since 1970 should be 7 hours ahead of gmt_secs.

HELP or ?

The HELP command with no parameters displays general help about BETIMES. Help on a specific command is available by typing:

HELP commandname

Example:

HELP ADD

NETCLOCK

The NETCLOCK command has the following syntax:

NETCLOCK [options]

BETIMES has the ability to fetch the current time from a network time sever via a serial port, and then set the local machine's clock to that value.

The options (if any) specified on the command line will override any related options from the BETIMES.CFG file (if any).

The options are described below.

BAUD [=] ####	Baud rate for the serial port. Default is 2400. Example: BAUD = 9600
END	Causes subsequent lines (if any) in the config file to be ignored.
FAKEINPUT	For internal testing. If specified, will not query the network clock for the current time. Instead, DATELINE is used to construct a fake network clock timestamp.
FAKEOUTPUT	For internal testing. If specified, will not set the machine's clock to the value fetched from the network clock server.
FORMAT #	Specifies which format the network clock provides the time in. Only format 1 is supported: (...) ddmmmyy hh:mm:ss Default: 1.
LDEV [=] ldevname_or_number	Specifies the ldev devicename or ldev# for the serial port connected to the network clock. This must be provided, there is no default value.
NOSETCLOCK	Tells BETIMES to use internal time change logic instead of SETCLOCK command to set the machine's time of day. Default: SETCLOCK (if on MPE/iX 5.0 or later)
NOTYPEAHEAD	NOTYPEAHEAD tells BETIMES not to enable type ahead for the netclock serial port. (TYPEAHEAD is on by default)
NOUPDATE	Tells BETIMES that you do NOT want to update the machine's clock to the time found on the network time server. This is useful for testing the BETIMES/NETCLOCK interface, without actually changing the local machine's time.
OUTPUT <Verbose | Quit>	OUTPUT QUIT tells BETIMES to abnormally terminate the BETIMES program if anything goes wrong with a NETCLOCK command. OUTPUT VERBOSE tells BETIMES to simply report any NETCLOCK error, skip the rest of the NETCLOCK command, and return to the command prompt. Default: Verbose
SETCLOCK <Now | Gradual>	Tells BETIMES to use the SETCLOCK command to change the machine's time of day. Either NOW or GRADUAL must be specified. Default: SETCLOCK NOW (if on MPE/iX 5.0 or later)
TRACE	For internal testing. Enables debugging output of the NETCLOCK command's progress.
TYPEAHEAD	TYPEAHEAD tells BETIMES to enable type ahead for the netclock serial port. (TYPEAHEAD is on by default)
UPDATE	UPDATE tells BETIMES that you want to update the machine's clock to the time found on the network time server. Default: UPDATE

BETIMES searches several locations for the configuration file, stopping as soon as it finds a file:

BETIMES.CFG

BETIMESP.CFG

BETIMES.CFG.LPSTOOLS

BETIMESP.CFG.LPSTOOLS

BETIMES.CFG.NUGGETS

BETIMESP.CFG.NUGGETS

Once the options from the command line and the configuration file have been parsed, BETIMES opens a serial port whose formal name is TIMETERM, and whose device name was specified via an LDEV (or PORT) option. The serial port is expected to be connected to a serial network clock.

Sample BETIMES.CFG file:

! betimes.cfg 96/01/11

! input is reasonably free form, one option per line

! Comments are indicated by "!" at start of line, or at the end

! of an option (but not in the middle!)

! In case of questions, contact Lund Performance Solutions at

! (541) 926-380 or Stan Sieler (650) 369-2303

LDEV = 255	! ldev for netclock info
BAUD = 2400	! baud rate for ldev
FORMAT = 1	! netclock format (only 1 is supported)
SETCLOCK = NOW	! NOW or GRADUAL
	! Note: if SETCLOCK omitted, uses BETIMES
	! inline code instead of SETCLOCK command
OUTPUT = VERBOSE	! inline code instead of SETCLOCK command
END	! stop reading cfg file

NOW

This command simply displays the current date and time.

RE[SET]

This command has the following syntax:

[RE]SET options

Options:

[no]SETCLOCK

SUBTRACT

This command has the following syntax:

SUBTRACT <number> <quantity> [<number> <quantity> ...]

The SUBTRACT command subtracts from the current date and time.

<quantity>	[Years]	0 .. 99
	[MOnths]	0 .. 11
	[Days]	0 .. 31
	[Hours]	0 .. 23
	[MInutes]	0 .. 59
	[Seconds]	0 .. 59
<number>	a decimal number (with the above limits)

SYNCH

This command has the following syntax:

SYNCH <HARDware | SOFTware>

The SYNCH command tells BETIMES to synchronize the hardware and software clocks, something that MPE/iX normally does every now and then (i.e., at unknown intervals!).

HARDware	Changes the hardware clock to match the software clock.
SOFTware	Changes the software clock to match the hardware clock and is NOT recommended.

In general, the use of SYNCH is not recommended, because MPE does a good job of synchronizing the clocks itself.

TICKS

The TICKS command reports some internal time-oriented operating system values.

TIMER

The TIMER command tests the MPE/iX time routines, including the TIMER and PAUSE intrinsics.

NOTE It isn't unusual for the TIMER command to notice that the PAUSE intrinsic is pausing for slightly less time than it should on values like 0.1 seconds. Moral: don't rely on PAUSE to successfully pause for times less than a second or so.

UPTIME

The UPTIME command reports when the system was booted up.

TOOLBOX STANDARDS

The ToolBox collections from Lund Performance Solutions have a uniform user interface. As a result, in addition to the commands specific to each Toolbox tool, most tools allow the commands described in "TOOLBOX STANDARDS".

BETIMES Examples

Examples 1 uses the ADD command. To set the clock ahead by one hour, at the BETIMES prompt enter:

ADD 1 HOUR

To set the clock ahead by one year, two months, and three days, at the BETIMES prompt enter:

ADD 1 Y 2 MO 3 D

Or:

add 1 year, 2 months, 3 days

Example 2 uses the SUBTRACT command. To set the clock back by one year, two months and three days, at the BETIMES prompt enter:

SUB 1 Y 2 MO 3 D

To set the clock back by one year, at the BETIMES prompt enter:

SUB 1 year

Example 3 uses the GMTSECS command. At the BETIMES prompt enter:

gmtsecs

ticks since 1970 -> 864752789 secs [...]

gmt_secs () = 864777989 secs ($338b7705)

local - gmt = -25200 secs (-7.0 hours)

Example 4 uses the TICKS command. At the BETIMES prompt enter:

ticks

Ticks:

since 1970 $c49f47aeabff40 (864753525895 millisecs)

global_timer $c49f47ad7c5270 (864753525584 millisecs)

cpu_0 $c49f47aeabff47

+ CR16 $c49f481f24608f

+last_cr16 $c49f481f246332

BETIMES Error Messages

Each BETIMES error message is described in the following table.

Table 4.2 BETIMES Error Messages

Message	Cause	Action
OOPS: TIMER intrinsic no longer works!	BETIMES is not compatible with the version of /iX (or XL) on which it is running.	As HP releases new operating system version, BETIMES needs adjustment to keep in sync with changes that HP implements. To correct this state, warm boot (TC) your machine.
Unable to locate TIMER globals.	Probably due to changes HP made to the operating system between major updates (i.e., patches).	Call Lund Performance Solutions Technical Support. Please provide the Build-id for your operating system, machine series, and BETIMES version when you call.
You need SM or OP capability to run this program.	User needs SM or OP. Since BETIMES should really only be used by the system manager, it checks to make sure that the user has SM or OP capability.	Have the system manager change the time, or run the GRANT System Manager’s Toolbox to give yourself SM capability.