STC procedure drops HASPCKPT/HASPACE1, breaking mvsMF's jobs API

[mgrossmann]

What is wrong

c35ab59 removed the HASPCKPT and HASPACE1 DDs from samplib/httpd,
reasoning that the only consumer was HTTPJES2 and that "nothing else in the
server opens them". That check was run against httpd/src/ alone. It missed the
consumers that run inside HTTPD's address space.

mvsMF is a CGI module, so it is dispatched by the MVS LINK SVC into the HTTPD
STC's task. libc370's jesopen() (src/jes/jesopen.c:36,46) opens the JES2
checkpoint and spool by ddname:

cp = checkpoint_open("DD:HASPCKPT");
js = spool_open("DD:HASPACE1");

Those are task-level allocations. They have to be in the STC procedure, and
after c35ab59 the shipped procedure no longer has them.

mvsMF calls jesopen() from three places in jobsapi.c:

line	function	endpoint
157	jobListHandler	GET /zosmf/restjobs/jobs
741	do_print_sysout	spool file retrieval
1229	find_job_by_name_and_id	single-job lookup

Symptom

Per request: HTTP 500 (REASON_INCORRECT_JES_VSAM_HANDLE) plus two console
lines — libc370's Unable to open checkpoint dataset DD:HASPCKPT and mvsMF's
MSG_JES_UNAVAILABLE. An operator-visible WTO flood, not a silent failure.

Job submit is unaffected: jesiropn() dynallocs its own INTRDR.

Three separate defects

1. samplib/httpd — a fresh 4.0.0 install has no working jobs API.
2. docs/migration.md:98 — the more severe half. It instructs 3.3.x
   migrators to delete the two DDs, which breaks a system that works today.
3. docs/installation.md — describes /zosmf/* as "where the datasets,
   jobs and files live" and never states the requirement. mvsMF's own install
   docs do not state it either (tracked separately in mvslovers/mvsmf).

The same wrong reasoning is recorded in the root and project CLAUDE.md.

Scope of the fix

The sample library is not an SMP element — the generated inst.jcl says so
itself: "SMP handles the load modules only. The sample library is a plain PDS
restored by TSO RECEIVE." So no PTF and no new FMID: 4.0.1 rebuilds the samplib
XMIT and reships the archive.

Restore the two lines verbatim as they stood in 3.3.x. Not as symbolic
parameters: that adds an installation parameter that can be got wrong, and
changes the PROC interface in a patch release. The hardcoded VOL=SER is a real
portability problem, but the fix for it is libc370 dynallocating the checkpoint
and spool the way jesiropn() already dynallocs the INTRDR — a library change,
filed separately.

Audit of the neighbouring removals

The failure class is "the "nothing uses this" check was scoped to httpd's own
repo". Re-run against every consumer:

• grep -rn "stck2tv|httpds_|HTTPJES2|HTTPDSL" over mvsmf/src, httplua/src,
  httprexx/src — no hits. Those removals were sound.
• httplua dynallocs its own DDs; httprexx needs none.
• The remaining DDs in the procedure are complete. SYSPRINT/SYSTERM/SYSIN
  are absent deliberately — httpstrt.c:47-68 refuses to start if they are
  allocated.

Tasks

• samplib/httpd: restore both DDs, comment says why (mvsMF) and that
  VOL=SER must match the site's JES2 procedure
• docs/migration.md: reverse the instruction
• docs/installation.md: state the requirement where /zosmf/* is described
• CLAUDE.md (root + project): correct the recorded reasoning
• preserve the v4.0.0 release notes in-repo before the release is replaced
• ship 4.0.1

[mgrossmann]

Correction to the issue text: the three call sites do not all answer 500.

call site	on an unreachable JES2
jobListHandler (157)	500, REASON_INCORRECT_JES_VSAM_HANDLE
do_print_sysout (741)	500, same
find_job_by_name_and_id (1229)	returns NULL → its four callers (237, 291, 388, 1783) send 404 job not found

find_job_by_name_and_id() returns NULL for an unreachable JES2 exactly as it
does for a job that is not there, so anything resolving a single job by name and
id reports the wrong cause: the client is told the job does not exist while it
does.

That makes the diagnosis harder, not easier, and it is the argument for reading
the console rather than the status code. The WTO pair is emitted on all three
paths and is the reliable signal.

Fixed in the docs shipped by #257 (d12e81e).

[mgrossmann]

Shipped in v4.0.1.
v4.0.0 was withdrawn; its tag was kept, only the release removed.

Verified on the published artifact, not on the working tree — the samplib XMIT
downloaded back from the release decodes to //HASPCKPT DD and HASPACE1
present, against zero //HASP* DD statements in the 4.0.0 one.

The FMID did not move. No source changed between the two releases, so there
is no functional level to cut: THTP400 still names 4.0.x.

If you installed 4.0.0, add the two DD statements to your existing PROCLIB
member and restart. SMP has nothing to do — the corrected member is in the
sample library, which is not an SMP element, and the load modules are identical.
Do not copy the new procedure over your own: its STEPLIB names
HTTPD.V4R0M1.LINKLIB, the library this package installs into, which does not
exist on a system running 4.0.0. Take the two lines, not the member.

Filed out of this and not blocking anything:

• mvslovers/mvsmf#357 — the requirement stated where a mvsMF installer looks
  for it, plus the NULL conflation found while writing it up:
  find_job_by_name_and_id() returns NULL for an unreachable JES2 exactly as
  for an absent job, so single-job lookup answers 404 job not found for a job
  that exists.
• mvslovers/libc370#142 — jesopen() should dynalloc the checkpoint and spool
  the way jesiropn() already dynallocs the INTRDR, which removes the class and
  gets the site-specific VOL=SER out of every procedure in the ecosystem.