Retire the TZOFFSET keyword - #152
Merged
Merged
Conversation
By the time #150 and #151 were done, TZOFFSET had one effect left: the default offset for the DISPLAY TIME command, which takes an offset as an argument anyway. Both purposes its documentation claimed were never real -- the Date: header goes through gmtime64() in http1123.c and the SMF record through localtime() in httprepo.c, and neither has ever read the field. What it did have was a failure mode. "TZOFFSET +02:00" reads like a display preference, but it asserts that the machine's TOD clock runs at UTC+2; set on a system at UTC-5 it silently shifted every JES2 timestamp by seven hours, and took a measurement of three separate control blocks to pin down. Its side effects pointed the same way: __tzset() reached only the task that parsed the Parmlib, so workers and modules kept the system offset, and setenvi("TZOFFSET") published a name nothing reads because tzset() looks at TZ. The escape hatch it nominally provided -- a system whose CVTTZ is wrong -- already exists and works better. TZ in the STC's SYSENV or ENVIRON DD is read by tzset(), which both httpstrt.c and cgistart.c call after loadenv(), so it reaches every task rather than one. The keyword is now accepted and ignored with an HTTPD025W naming the system offset in use and pointing at TZ, so an existing Parmlib still starts the server. httpd->tzoffset stays at offset 0x24 and is written only by set_defaults() from __tzget(); keeping the field avoids shifting the HTTPD block layout that .dsrv and anything else reading offsets depends on. DISPLAY TIME's output said "TZOFFSET=" for the value it shows. That named a setting which no longer exists, so it is "OFFSET=" now, and the command's help line says [minutes] rather than [tzoffset] -- the argument is what it always was, the label was borrowed from the keyword. Docs: configuration.md's Timezone section now describes where the offset comes from and how to override it with TZ, with the retirement recorded as a note for anyone whose Parmlib still has the statement. The keyword is out of both sample configurations, here and in CLAUDE.md. Closes #145
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #145.
Why it goes
By the time #150 and #151 were done,
TZOFFSEThad one effect left: the default offset forDISPLAY TIME, a command that takes an offset as an argument anyway.Both purposes its documentation claimed were never real:
Date:response headergmtime64()inhttp1123.c— verified against a UTC clock, correct to the secondlocaltime()inhttprepo.c— i.e. the task's CRT offsetNeither has ever read the field.
What it did have was a failure mode.
TZOFFSET +02:00reads like a display preference; it actually asserts the machine's TOD clock runs at UTC+2. Set on a system at UTC−5 it silently shifted every JES2 timestamp by seven hours, and it took measuring three separate control blocks to pin down. Its side effects pointed the same way —__tzset()reached only the task that parsed the Parmlib, so workers and modules kept the system offset, andsetenvi("TZOFFSET")published a name nothing reads becausetzset()looks atTZ.The escape hatch it nominally provided — a system whose
CVTTZis wrong — already exists and works better.TZin the STC'sSYSENVorENVIRONDD is read bytzset(), which bothhttpstrt.candcgistart.ccall afterloadenv(), so it reaches every task instead of one.What changes
The keyword is accepted and ignored, with a warning naming the offset actually in use and pointing at the replacement:
Accepted rather than rejected so an existing Parmlib still starts the server.
httpd->tzoffsetstays at offset0x24, written only byset_defaults()from__tzget(). Keeping the field avoids shifting the HTTPD block layout that/.dsrv— and anything else reading offsets — depends on.DISPLAY TIMEsaidTZOFFSET=for the value it prints, naming a setting that no longer exists. It isOFFSET=now, and the help line reads[minutes]rather than[tzoffset]— the argument is what it always was, only the label was borrowed from the keyword.Docs
docs/configuration.md's Timezone section now says where the offset comes from and how to override it withTZ, and records the retirement as a note for anyone whose Parmlib still carries the statement. The keyword is out of both sample configurations — that file andCLAUDE.md.Verification
makeclean under-Wall -Werror, 6 modules link,make test-host63 assertions pass. Deployed toIBMUSER.HTTPD.V4R0M0D.LINKLIB.Live check worth doing, and the reference system is set up for it —
SYS2.PARMLIB(HTTPPRM0)still hasTZOFFSET +02:00, so a restart on this build should:HTTPD025Wlines at startup namingGMT -05:00;F HTTPD,DISPLAY TIMEwith GMT and Local five hours apart andOFFSET=-300— where before this build it showed+120;/jes/statustimestamps unchanged, since Return JES2 job timestamps as ISO 8601 UTC #151 already decoupled them from this field.Then the statement can come out of the Parmlib, and (1) should stop appearing.