HOSTEL/i — Hotel Reservations & Front-Desk / Folio Management

SteelFrame X application operation manual  ·  ← back to Operation Manuals  ·  Sign On

HOSTEL/i is a hotel front-desk and folio-management application: reservation capture and room allocation by type, check-in, a nightly room+tax posting (the night audit), incidental and payment application, check-out with settlement, weekly housekeeping turnover and no-show release, a monthly occupancy/revenue report and a room-revenue/tax GL feed, and a year-end folio archive. The application is a classic IBM i estate app: RPG IV programs over keyed DB2 for i physical and logical files, one ILE COBOL control report, DDS display and printer files, embedded SQL for the GL distribution, and CL job cycles. This manual is the reference for the operator who runs the online screens and the four periodic cycles, and for the developer maintaining the application. It is grounded entirely in the committed source (hotel-app/src/sources.mjs, src/seed.mjs, and the test/ht_*.mjs drivers). Everything runs in library HOSTEL.

A. Overview & Architecture ↑ top

A.1 What it does

HOSTEL/i services the full life of a hotel stay, from reservation to settled folio to year-end archive:

• Reservation capture & allocation — a new reservation requests a room type; allocation locks the type's nightly rate onto the reservation and walks the type-keyed room access path for the first vacant-clean room, earmarking it immediately. No free room of the type → the reservation is waitlisted.
• Check-in & night audit — check-in flips a booked reservation checked-in on its arrival date and posts the first night's room + occupancy tax; the night audit posts one further night's room + tax on every subsequent processing date, raising the folio balance by exactly that amount.
• Incidentals & payments — ad-hoc food & beverage / minibar lines are accrued into the balance once; payment lines (posted negative) are applied against the balance once.
• Check-out & settlement — a stay whose balance is settled (≤ 0) and whose departure date has come checks out, releasing its room vacant-dirty and settling every open folio line. An unsettled folio cannot check out.
• Weekly turnover & no-show release — housekeeping returns vacant-dirty rooms to the sellable pool; the no-show sweep releases the rooms of booked reservations whose arrival date passed without a check-in.
• Monthly & annual close — an occupancy/revenue printer report, a room-revenue/tax GL post (movement since the last close), an ILE COBOL folio control report, and a year-end folio-history archive with a counter reset.

A.2 Architecture & the status model

HOSTEL/i is a conventional record-level-access RPG estate app, not a two-layer SQL-PL design: business logic lives in the RPG programs, which read and update keyed DB2 files directly (CHAIN / READ / READE / UPDATE / WRITE). Embedded SQL appears in exactly one place — HTGLPST, the GL post — and one ILE COBOL program, HTAUDRPT, produces a folio control report. The whole estate is built and compiled by one CL setup program (HTSETUP) and driven by four CL job cycles (HTDAILY, HTWEEK, HTMONTH, HTYEAR).

The heart of the application is the reservation status model on HTRESV.RSTAT, which every program keys its behaviour off:

RSTAT	Meaning	Set by
N	New — captured, room type requested, no room yet.	Front desk (reservation write).
W	Waitlisted — no room of the type was free at capture.	HTRESERV.
B	Booked — a specific room assigned, arrival pending.	HTRESERV.
I	Checked in — guest in-house, folio open.	HTCHKIN.
O	Checked out — stay settled and closed.	HTCHKOUT.
X	Cancelled.	Front desk.
S	No-show — past arrival, never checked in.	HTNOSHOW.

A parallel room status on HTROOM.RSTAT drives availability: V vacant-clean (sellable), O occupied (taken off the pool at booking), D vacant-dirty (checked out, needs housekeeping before resale), X out-of-order (never allocated). The "stamp it once, trust the stamp" invariant used across the estate applies here to the rate: RATELOCK captures the room-type rate at booking so a later rate change never reprices a guest already holding a reservation.

A.3 Component & flow

  ONLINE                      BATCH CYCLES (CL job streams)
  ------                      ----------------------------
  HTMENU (5250)               HTDAILY  --> HTRESERV  (allocate room by type)
    opt 1 -> HTRESVIQ                      HTCHKIN   (check in arrivals + night 1)
    opt 2 -> HTFOLIQ (SFL)                 HTNAUDIT  (post each further night room+tax)
                                           HTINCTAL  (accrue F&B / minibar lines)
                                           HTPAYAPL  (apply PY payment lines)
                                           HTCHKOUT  (settle + release room dirty)
                            HTWEEK   --> HTHSKP    (dirty -> clean)
                                         HTNOSHOW  (release no-show rooms)
                            HTMONTH  --> HTOCCRPT  (occupancy/revenue printer report)
                                         HTGLPST   (room-rev/tax GL post, embedded SQL)
                                         HTAUDRPT  (ILE COBOL folio control report)
                            HTYEAR   --> HTARCHIV  (folio archive + counter reset)
                                         HTAUDRPT

  HTRESV (reservation header, RBAL mirror) <----writes---- every posting program
     |  \                                   HTFOLIO (one row per charge/payment line)
     |   +--> HTROOM (V/O/D/X availability) HTGLDIST (SQL GL distribution, HTGLPST)
     +------> HTRTYP (type rate) / HTGUEST (guest master)

A single processing event — say, one night's audit — flows: HTNAUDIT reads its fixed run date → for each checked-in stay not yet audited today it posts a room line and a tax line to HTFOLIO and raises HTRESV.RBAL by room+tax → the reservation header's RBAL mirror then answers "what is owed" without re-summing the folio. The RLAUDT stamp on the header makes a same-day re-run a no-op.

A.4 Object inventory

Object	Type	Role
HTRTYP	PF	Room-type / rate master.
HTROOM	PF	Room master (availability by number).
HTROOMLF	LF	Rooms keyed by RTYPE (availability-by-type walk).
HTGUEST	PF	Guest master.
HTRESV	PF	Reservation header (the stay lifecycle + RBAL mirror).
HTRESVLF	LF	Reservations keyed by ARRDT (arrivals / no-show walk).
HTFOLIO	PF	Folio charge/payment lines (composite key RESVNO,FSEQ).
HTFOLLF	LF	Folio lines keyed by FCODE (revenue-by-department).
HTGLDIST	SQL table	Room-revenue/tax GL distribution (HTGLDACC index).
HTRESVD / HTFOLD / HTMENUD	DSPF	Inquiry, subfile-folio and menu display files.
HTOCCP	PRTF	Occupancy/revenue printer file.
HTREFLD	RPG	Seed reference data (types, rooms, guests).
HTRESERV	RPG	Reservation capture + room allocation.
HTCHKIN	RPG	Check-in + first night's room+tax.
HTNAUDIT	RPG	Night audit (each further night's room+tax).
HTINCTAL	RPG	Incidental (F&B/minibar) accrual.
HTPAYAPL	RPG	Payment application.
HTCHKOUT	RPG	Check-out + settlement + room release.
HTHSKP	RPG	Weekly housekeeping turnover sweep.
HTNOSHOW	RPG	Weekly no-show release sweep.
HTOCCRPT	RPG	Monthly occupancy/revenue report.
HTGLPST	SQLRPGLE	Monthly room-revenue/tax GL post.
HTARCHIV	RPG	Annual folio archive + counter reset.
HTRESVIQ / HTFOLIQ / HTMENU	RPG	Online inquiry, subfile-folio, menu.
HTAUDRPT	ILE COBOL	Folio control report (room/tax reconciliation).
HTSETUP	CL	Create every object & compile every program.
HTDAILY / HTWEEK / HTMONTH / HTYEAR	CL	The four job-cycle streams.

The full catalogue is 5 physical files + 3 logical files + 1 SQL table (with index), 3 display files and 1 printer file, driven by 15 RPG programs, 1 ILE COBOL program and 5 CL programs. Sections D and F expand each.

B. Online Transactions & Screens ↑ top

B.1 The command/entry line

HOSTEL/i has no CICS transaction identifiers and no transid switch. On IBM i, each program is reached by name from a 5250 command-entry line (or a JOBQ/scheduler for the batch cycles). The operator equivalent of "type a transid and Enter" is "type a CALL command and Enter". Before invoking anything, the job's library list must include HOSTEL — the tested jobs run with LIBL = QSYS QGPL HOSTEL QTEMP and CURLIB = HOSTEL.

To do this	Type on the command line
Open the operator menu	CALL HOSTEL/HTMENU
Open the reservation inquiry directly	CALL HOSTEL/HTRESVIQ
Open the folio inquiry (subfile) directly	CALL HOSTEL/HTFOLIQ
Run the daily cycle	CALL HOSTEL/HTDAILY (or SBMJOB it)
Run the weekly cycle	CALL HOSTEL/HTWEEK
Run the monthly close	CALL HOSTEL/HTMONTH
Run the annual archive	CALL HOSTEL/HTYEAR
Build/compile the whole estate	CALL HOSTEL/HTSETUP
Load the seed reference data	CALL HOSTEL/HTREFLD

The batch drivers take no CALL parameters. Only HTMENU, HTRESVIQ and HTFOLIQ are interactive; every batch program runs to completion and DSPLYs a one-line result (its counts) to the job log.

B.2 The menu & inquiry screens

HOSTEL/i has three interactive programs. The menu (HTMENU / HTMENUD) is the entry point; it CALLs one of the two inquiry programs by option and returns on F3. The inquiry programs are read-only — they display reservation and folio data but do not post or maintain it. All maintenance (reservations, incidentals, payments) is data-entry into the files plus the batch cycle; see B.3.

HTMENU — operator menu

• Option 1 — CALLs HTRESVIQ (reservation inquiry).
• Option 2 — CALLs HTFOLIQ (folio inquiry with subfile).
• Any other non-blank option — the menu re-displays with Invalid option. in the message line (DMSG).
• F3 (CA03) ends the program; F3 inside a called inquiry returns to the menu.

HTRESVIQ / HTRESVD — reservation inquiry (plain screen)

A plain (non-subfile) screen. Key a reservation number and Enter; the program CHAINs HTRESV and (for the guest name) HTGUEST, and renders the header plus the locked rate and folio balance. An unknown number clears the detail and shows Reservation not found.

Field	Type (DDS)	Shows
IRESV	8A input/output	Reservation number keyed in.
DGNAME	30A output	Guest name (from HTGUEST).
DRTYPE / DROOM	3A / 4A output	Room type and assigned room number.
DSTAT	1A output	Reservation status (RSTAT).
DRATE	14A output	Locked nightly rate (RATELOCK, edited).
DARR / DDEP	10A output	Arrival / departure dates.
DBAL	14A output	Folio balance from the RBAL mirror (edited).
DMSG	50A output	Found / not-found message line.

HTFOLIQ / HTFOLD — folio inquiry (subfile)

The app's subfile screen. DDS record FSFL under control record FCTL, SFLPAG(5) per page, SFLSIZ(20), with ROLLUP/ROLLDOWN paging keys and SFLEND(*MORE). Key a reservation number and Enter; the program clears the subfile (*IN31 drives SFLCLR), CHAINs the header/guest, then READEs every folio line for that reservation into the subfile and displays it. A subsequent enquiry clears and reloads — a genuine clear-then-reload discipline so an unknown number does not redisplay the previous stay's rows.

Field	Type (DDS)	Shows
IRESV	8A input/output	Reservation number keyed in.
DGNAME / DSTAT / DBAL	output	Header: guest, status, folio balance.
SSEQ	3Y,0 output	Folio line sequence (FSEQ).
SCODE	2A output	Charge code: RM/TX/FB/MB/PY/YE.
SDT	10A output	Line date (FDT, edited).
SAMT	12A output	Line amount (FAMT, edited; PY is negative).
SFST	1A output	Line status: O open, S settled, A accrued/applied.

B.3 Controls & audit workflow

Honest statement: HOSTEL/i does not model a four-eyes maker–checker / separate-authorization workflow, and it has no dedicated audit-trail file. The inquiry screens are read-only; front-desk maintenance is performed by writing reservation and folio rows (the test drivers do this directly against HTRESV/HTFOLIO) and then running the daily cycle, which applies each new row exactly once. The control model the application does have is built from state gating and idempotency:

• Status gating. Every posting program keys off RSTAT/FSTAT and skips anything not in the state it acts on: HTRESERV only touches N; HTCHKIN only B arrivals due; HTNAUDIT only I; HTCHKOUT only settled I stays past departure; HTNOSHOW only B past arrival.
• Settlement gate on check-out. HTCHKOUT refuses to close a stay whose RBAL > 0 (counted as HELD), so an unsettled folio cannot check out — the front desk's real control point.
• The folio as the journal. HTFOLIO is a complete, append-only-in-practice ledger: one row per room night, tax, incidental, payment and year-end archive line, each carrying its code, date, amount and status. HTAUDRPT (ILE COBOL) reconciles it: totalling room, tax and other, and counting open lines — the after-the-fact accountability report.
• The RBAL mirror as the control figure. The reservation header carries RBAL so the header alone answers "what is owed"; every posting program keeps it in step (room+tax at check-in and audit, incidental accrual, payment application), and the AR-style invariant — balance rises by exactly one night per audit — is what the daily battle asserts.
• Idempotency guards (see F.3) — the RLAUDT same-day stamp, the FSTAT flip on accrued/applied lines, and the GL post's movement-since-last-close read-back all prevent double-counting on a re-run.

In sum, the control posture is state gating + a settlement gate + a reconstructable folio ledger + idempotency, all in RPG record-level logic, rather than a segregation-of-duties approval workflow or a trigger-written audit file.

C. Batch Jobs & the Periodic Cycle ↑ top

HOSTEL/i runs as four CL job-cycle streams rather than one monolithic nightly job: a daily cycle (the reservation-to-folio flow), a weekly cycle (housekeeping + no-show), a monthly close (report + GL + control report), and an annual roll (archive + reset). Each CL simply ADDLIBLE HOSTEL then CALLs its programs in order; the batch programs take no parameters. This is the SBMJOB idiom — a scheduled submission is a bare CALL of the cycle CL.

-- submit a (parameterless) cycle
SBMJOB CMD(CALL PGM(HOSTEL/HTDAILY)) JOB(HTDAILY)
SBMJOB CMD(CALL PGM(HOSTEL/HTWEEK))  JOB(HTWEEK)
SBMJOB CMD(CALL PGM(HOSTEL/HTMONTH)) JOB(HTMONTH)
SBMJOB CMD(CALL PGM(HOSTEL/HTYEAR))  JOB(HTYEAR)

C.1 Full batch program set

Program	Cycle	Purpose	Files	Output (DSPLY)
HTRESERV	Daily	Allocate a room by type to each new (N) reservation; lock the rate; else waitlist.	HTRESV(UF), HTRTYP(IF), HTROOMLF(UF)	HTRESERV BOOKED=n WAITLIST=n SKIP=n
HTCHKIN	Daily	Check in B arrivals due (ARRDT≤rundate); post night-1 room+tax.	HTRESV(UF), HTFOLIO(UF A)	HTCHKIN CHECKEDIN=n SKIP=n
HTNAUDIT	Daily	Post each further night's room+tax on checked-in stays not yet audited today.	HTRESV(UF), HTFOLIO(UF A)	HTNAUDIT POSTED=n SKIP=n
HTINCTAL	Daily	Accrue open F&B/minibar folio lines into RBAL once (stamp FSTAT='A').	HTFOLIO(UF), HTRESV(UF)	HTINCTAL ACCRUED=n SKIP=n
HTPAYAPL	Daily	Apply open PY payment lines against RBAL once (stamp FSTAT='A').	HTFOLIO(UF), HTRESV(UF)	HTPAYAPL APPLIED=n SKIP=n
HTCHKOUT	Daily	Check out settled (RBAL≤0) stays past departure; release room 'D'; settle open lines. Unsettled → held.	HTRESV(UF), HTROOM(UF), HTFOLIO(UF)	HTCHKOUT OUT=n HELD=n SKIP=n
HTHSKP	Weekly	Turn every vacant-dirty (D) room back to vacant-clean (V).	HTROOM(UF)	HTHSKP CLEANED=n
HTNOSHOW	Weekly	Mark B reservations past arrival as no-show (S); release their earmarked room to V.	HTRESVLF(UF), HTROOM(UF)	HTNOSHOW RELEASED=n
HTOCCRPT	Monthly	Print every occupied room with guest and folio balance; total occupied + balance.	HTROOM/HTRESV/HTGUEST(IF), HTOCCP(PRTF)	HTOCCRPT ROOMS=n BAL=n
HTGLPST	Monthly	Sum posted room + tax revenue; post the movement since last close (cash Dr / room Cr / tax Cr).	HTFOLIO(IF), HTGLDIST(SQL)	HTGLPST BATCH=202608 ROWS=n
HTAUDRPT	Monthly/Annual	ILE COBOL folio control report: total room/tax/other, count lines and open lines.	HTFOLIO (indexed)	HTAUDRPT ROOM/TAX/OTHER/LINES/OPEN
HTARCHIV	Annual	Write one YE archive line per settled (O) stay with its full room+tax+incidental turnover; reset RNIGHTS/RLAUDT.	HTRESV(UF), HTFOLIO(UF A)	HTARCHIV ARCHIVED=n RESET=n SKIP=n

C.2 Daily / weekly / monthly / annual detail

Daily — HTDAILY

Runs the six programs above in order: HTRESERV → HTCHKIN → HTNAUDIT → HTINCTAL → HTPAYAPL → HTCHKOUT. Allocation walks the type-keyed room LF in (RTYPE,ROOMNO) order for the first vacant-clean room; a booked room is taken off the vacant pool immediately (RSTAT→'O') so a second reservation cannot double-book it. Occupancy tax is a flat 10% of the room charge. The daily chain is safely re-runnable end to end — every step's guard makes a re-run a no-op.

Expected DSPLY (four seeded reservations, two STD rooms free):
  HTRESERV BOOKED=3 WAITLIST=1     2 STD + 1 DLX booked; 3rd STD waitlisted (0103 is OOO)
  HTCHKIN  CHECKEDIN=2             2 arrivals due 20260801 (DLX arrives 20260802, not yet)
  HTNAUDIT POSTED=2                a 2nd night for both -> each folio 110.00 -> 220.00
  HTINCTAL ACCRUED=1               one 45.00 F&B line -> 265.00
  HTPAYAPL APPLIED=2               full 265.00 -> 0.00; partial 100.00 -> 120.00
  HTCHKOUT OUT=1 HELD=1            settled stay out (room -> D); unsettled 120.00 held

Weekly — HTWEEK

Runs HTHSKP → HTNOSHOW. Housekeeping returns every vacant-dirty room (left by a check-out) to vacant-clean; the no-show sweep walks the arrival-date-keyed reservation LF and, for every B booked stay whose arrival date has passed (relative to HTNOSHOW's 20260805 run date) without a check-in, marks it S and releases its room to V.

Expected DSPLY:
  HTHSKP   CLEANED=1               the checked-out room 0101 D -> V
  HTNOSHOW RELEASED=1              DLX RESV0004 never checked in -> S, room 0201 -> V

Monthly — HTMONTH

Runs HTOCCRPT → HTGLPST → HTAUDRPT. The occupancy report lists each occupied room with its checked-in guest and running balance. The GL post sums every room and tax folio line ever posted, then posts only the movement since the last close — it reads back what is already on 4100-ROOM/2200-TAX and subtracts it, so a re-run in the same period posts zero rows. Each post is a balanced set: cash debit = room credit + tax credit. The COBOL control report reconciles the folio totals independently.

Expected DSPLY (one checked-in stay, 2 nights, balance 220.00):
  HTOCCRPT ROOMS=1 BAL=220.00
  HTGLPST  BATCH=202608 ROWS=3     1100-CASH D 220.00, 4100-ROOM C 200.00, 2200-TAX C 20.00
  HTAUDRPT ROOM 200.00 / TAX 20.00 / LINES 4 / OPEN 4

Annual — HTYEAR

Runs HTARCHIV → HTAUDRPT. For every settled (checked-out, O) reservation still carrying nights, the archive sums the stay's room+tax+F&B+minibar turnover from its own folio lines and writes one summary line into the same folio file under code YE at a reservation-derived sequence band (900 + RNIGHTS×2) that no live posting program uses, then resets RNIGHTS=0 and RLAUDT=0 so next year's audit does not inherit this year's counters. The RNIGHTS=0 reset is itself the re-run guard.

Expected DSPLY (one settled stay, 220.00 turnover):
  HTARCHIV ARCHIVED=1 RESET=1      one YE line of 220.00; counters cleared

C.3 Ordering & dependencies

• Within the daily chain the order is fixed by the CL and matters: allocate before check-in (a room must be assigned before arrival), check-in before the night audit (night 1 is posted at check-in, the audit posts night 2+), incidentals/payments before check-out (check-out refuses an unsettled balance), and check-out last (it releases the room for housekeeping).
• DAILY before WEEKLY. Housekeeping cleans the rooms that check-out left dirty; the no-show sweep releases rooms that check-in never occupied — both consume states the daily chain produces.
• DAILY (and any front-desk posting) before the MONTHLY close. The occupancy report, GL post and COBOL control report all read the folio and reservation state, so run the period's dailies first, then the close.
• MONTHLY before ANNUAL, and the stay checked out before archive. HTARCHIV only archives settled (O) reservations, so a stay must be paid and checked out before the year-end roll can summarise and reset it.

D. Data Files (data dictionary) ↑ top

All files are in library HOSTEL, grounded in the DDS and SQL DDL in src/sources.mjs. Dates are stored as signed numeric YYYYMMDD (8S,0) or YYYYMM for the GL batch; money is packed decimal (nP m). "P" = packed, "S" = zoned/signed, "A" = character.

HTRTYP — Room-type / rate master (unique key RTYPE)

Field	Type	Meaning
RTYPE	3A	Room-type code (key), e.g. STD/DLX/STE.
RDESC	20A	Description, e.g. STANDARD DOUBLE.
RATE	9P 2	Standard nightly rate this type books at.
MAXOCC	1S 0	Maximum guests the type sleeps.
RSTAT	1A	A active (sellable); else withdrawn.

Seeded types: STD 100.00/maxocc 2, DLX 150.00/maxocc 2, STE 250.00/maxocc 4 (all active).

HTROOM — Room master (unique key ROOMNO)

Field	Type	Meaning
ROOMNO	4A	Room number (key), e.g. 0101.
RTYPE	3A	Room type it belongs to (drives its rate).
RFLOOR	2S 0	Floor number.
RSTAT	1A	V vacant-clean, O occupied, D vacant-dirty, X out-of-order.

Seeded rooms: 0101/0102 STD V, 0103 STD X (out-of-order — drives the waitlist case), 0201 DLX V, 0301 STE V.

HTROOMLF — Room logical, keyed by RTYPE (then ROOMNO)

Alternate access path over HTROOM keyed RTYPE, ROOMNO — the availability-by-type walk allocation genuinely wants (find a free room of the requested type) instead of scanning the whole room list in room-number order.

HTGUEST — Guest master (unique key GUESTID)

Field	Type	Meaning
GUESTID	6A	Guest id (key), e.g. G00001.
GNAME	30A	Guest name.
GPHONE	15A	Phone number.
GVIP	1A	VIP Y/N — cosmetic on the inquiry screen, not load-bearing in the arithmetic (no invented VIP discount).
GSTAT	1A	A active.

Seeded guests: G00001 JANET OKAFOR (N), G00002 MARCUS VANCE (VIP Y), G00003 PRIYA RAMASWAMY (N), G00004 TOM LINDQVIST (N).

HTRESV — Reservation header (unique key RESVNO)

Field	Type	Meaning
RESVNO	8A	Reservation number (key), e.g. RESV0001.
GUESTID	6A	Owning guest.
RTYPE	3A	Requested room type.
ARRDT / DEPDT	8S 0	Arrival / departure dates (YYYYMMDD).
ROOMNO	4A	Assigned room (blank until booked; blank on waitlist).
RSTAT	1A	Stay lifecycle: N/W/B/I/O/X/S (see A.2).
RATELOCK	9P 2	Room-type rate stamped at booking (never repriced later).
RNIGHTS	3S 0	Nights already posted by the night audit (re-run guard; 0 = year-end reset).
RLAUDT	8S 0	Last calendar date audited (same-day double-post guard).
RBAL	11P 2	Folio running-balance mirror — what the stay owes.

HTRESVLF — Reservation logical, keyed by ARRDT (then RESVNO)

Alternate access path keyed ARRDT, RESVNO — the arrivals list the front desk works from (who is due in today) and the walk the no-show sweep needs (who is still B past their arrival date).

HTFOLIO — Folio charge/payment lines (unique composite key RESVNO, FSEQ)

Field	Type	Meaning
RESVNO	8A	Reservation the line belongs to (key part 1).
FSEQ	3S 0	Line sequence within the stay (key part 2).
FDT	8S 0	Line date (YYYYMMDD).
FCODE	2A	RM room, TX occupancy tax, FB food&beverage, MB minibar, PY payment (negative), YE year-end archive.
FAMT	11P 2	Line amount (payments are negative).
FSTAT	1A	O open, S settled, A accrued/applied into RBAL.

HTFOLLF — Folio logical, keyed by FCODE (then RESVNO, FSEQ)

Alternate access path keyed FCODE, RESVNO, FSEQ — the revenue-by-department view (room vs tax vs F&B vs minibar) the monthly close and GL post want without re-summing every folio.

HTGLDIST — GL distribution (SQL table, PK GLSEQ)

Field	Type	Meaning
GLSEQ	DECIMAL(8,0)	GL row sequence (PK) — never restarted; MAX+1 each post.
GLBATCH	DECIMAL(6,0)	Batch/period, e.g. 202608.
ACCT	CHAR(9)	Account: 1100-CASH, 4100-ROOM, 2200-TAX.
DRCR	CHAR(1)	D debit / C credit.
AMT	DECIMAL(11,2)	Posted amount.
GLREF	CHAR(8)	Reference, e.g. ROOMREV.
GLDT	DECIMAL(8,0)	GL date (YYYYMMDD).

Index HTGLDACC on (ACCT, DRCR) supports the movement-since-last-close read-back.

Display & printer files

• HTRESVD (DSPF) — record RESVINQ, the plain reservation inquiry screen for HTRESVIQ.
• HTFOLD (DSPF) — subfile record FSFL under control FCTL (SFLSIZ 20 / SFLPAG 5 / ROLLUP/ROLLDOWN / SFLEND(*MORE)), the folio inquiry for HTFOLIQ.
• HTMENUD (DSPF) — record HTMENU, the operator menu for HTMENU.
• HTOCCP (PRTF) — records OCCHDR/OCCDTL/OCCTOT, the occupancy/revenue report HTOCCRPT prints.

Relationships

• HTRESV.GUESTID → HTGUEST.GUESTID; HTRESV.RTYPE → HTRTYP.RTYPE (rate source at booking).
• HTRESV.ROOMNO → HTROOM.ROOMNO (the earmarked/occupied room); HTROOM.RTYPE → HTRTYP.RTYPE.
• HTFOLIO.RESVNO → HTRESV.RESVNO (per-stay ledger; FSEQ sequences the lines).
• HTGLDIST is an aggregate ledger populated only by HTGLPST (no per-row FK).
• The three LFs (HTROOMLF, HTRESVLF, HTFOLLF) are alternate access paths over their PFs, not new data.

E. Operations Runbook ↑ top

E.1 Day-in-the-life

1. Confirm the job's library list includes HOSTEL (LIBL = QSYS QGPL HOSTEL QTEMP).
2. Capture the day's reservation requests as HTRESV rows with RSTAT='N' (guest, type, arrival, departure; room blank, balances zero).
3. Post any incidentals as HTFOLIO lines (FCODE='FB'/'MB', FSTAT='O') and any payments (FCODE='PY', FAMT negative, FSTAT='O').
4. Submit the daily cycle: SBMJOB CMD(CALL PGM(HOSTEL/HTDAILY)).
5. Post-check the daily run (see below).
6. Handle look-ups interactively through CALL HOSTEL/HTMENU (reservation and folio inquiry).
7. On the weekly schedule, submit HTWEEK to clean turned-over rooms and release no-shows.

Post-checks after the daily cycle (each program DSPLYs its counts to the job log):

• HTRESERV BOOKED/WAITLIST reconcile to the new requests vs available rooms of each type; booked rooms are now O and off the vacant pool.
• HTCHKIN CHECKEDIN equals the B arrivals due; each checked-in stay is I with a two-line folio (room + tax) and RBAL = rate + 10% tax.
• HTNAUDIT POSTED equals the in-house stays not yet audited today; the AR invariant — each audited stay's RBAL rose by exactly one night (rate + tax), no more.
• HTINCTAL ACCRUED / HTPAYAPL APPLIED equal the open incidental / payment lines; each moved RBAL by exactly the line amount and the line flipped to FSTAT='A'.
• HTCHKOUT OUT/HELD — only settled (RBAL≤0) stays past departure checked out (room → D, open lines → S); any unsettled stay is HELD, still I, room still O.

E.2 Month-end & year-end close

Month-end:

1. Confirm the period's daily cycles have run and front-desk postings are applied.
2. Submit HTMONTH. Confirm HTOCCRPT ROOMS=/BAL=, HTGLPST BATCH=202608 ROWS=, and the HTAUDRPT totals.
3. Review and reconcile the GL distribution:

SELECT ACCT, DRCR, AMT FROM HOSTEL.HTGLDIST ORDER BY GLSEQ;

Reconciling figures (the same ones the cycles battle checks by hand against the seeded scenario — one checked-in STD stay, 2 nights):

• Room revenue — 4100-ROOM credit = Σ posted RM folio lines = 2 × 100.00 = 200.00 (tax excluded).
• Occupancy tax — 2200-TAX credit = Σ posted TX lines = 2 × 10.00 = 20.00.
• Cash — 1100-CASH debit = room + tax = 200.00 + 20.00 = 220.00; the batch balances (Dr 220.00 = Cr 200.00 + 20.00).
• Movement guard — a second HTGLPST in the same period posts 0 further rows: it reads back what is already on 4100-ROOM/2200-TAX and subtracts it (ROWS=0).
• COBOL control — HTAUDRPT independently reports ROOM 200.00, TAX 20.00, LINES 4, OPEN 4 (folio not yet settled).

Year-end: after the settled stays have checked out, submit HTYEAR. Confirm HTARCHIV ARCHIVED=/RESET=; each settled stay gets one YE folio line carrying its full room+tax(+F&B+minibar) turnover (e.g. 220.00) and its RNIGHTS/RLAUDT reset to 0.

E.3 Failure & re-run rules

Every program DSPLYs its counts; a healthy re-run of an already-processed cycle shows all-zero action counts (nothing left in the acted-on state). The estate tests assert every cycle is safely re-runnable.

Situation	Behaviour	Action
Daily chain fails partway	Completed steps left their state stamped (RSTAT/FSTAT/RLAUDT); pending rows untouched.	Re-submit HTDAILY: each step skips what it already did and finishes the rest. Idempotent by state.
Re-run allocation	Only N reservations are processed.	Safe no-op: HTRESERV BOOKED=0 WAITLIST=0.
Re-run night audit same day	RLAUDT ≥ run date guard skips every stay.	Safe no-op: POSTED=0, balances unchanged. A new night requires advancing the run date (see F.4).
Re-run incidental / payment	A line already folded into RBAL is FSTAT='A'.	Safe no-op: ACCRUED=0 / APPLIED=0; never double-counted.
Check-out of an unsettled stay	Balance > 0 → counted as HELD, left checked-in.	Post/apply a payment to clear the balance, then re-run HTCHKOUT.
Re-run GL post same period	Movement-since-last-close read-back nets to zero.	Safe no-op: ROWS=0; the ledger is not double-posted. A refused insert is not counted as a posted row (guarded on sqlcod=0).
Re-run annual archive	RNIGHTS=0 reset signal is already set.	Safe no-op: ARCHIVED=0 RESET=0; a stay is never archived twice.

F. Developer Reference ↑ top

The complete program surface, from src/sources.mjs. All objects are in library HOSTEL. Fixed-form RPG C-specs and free-form /free blocks are used side by side, mirroring the estate's ibmi/samples.js convention.

F.1 Programs

HTREFLD (RPG) — seed reference data

Writes the 3 room types, 5 rooms and 4 guests. DSPLYs HTREFLD RTYPE=3 ROOM=5 GUEST=4. Run once after HTSETUP.

HTRESERV (RPG) — reservation capture + allocation. Daily.

For each N reservation: CHAIN HTRTYP for the rate; SETLL/READE the type-keyed HTROOMLF for the first V room; if found, flip room to O, set reservation ROOMNO/RATELOCK/RSTAT='B'; else RSTAT='W'. Re-CHAINs the reservation after the room walk moved the cursor.

HTCHKIN (RPG) — check-in + first night. Daily.

For each B stay with ARRDT ≤ run date: RSTAT='I', RNIGHTS=1, RLAUDT=run date, RBAL = rate + tax; WRITE folio lines FSEQ 1 (RM) and 2 (TX). Tax = rate × 10 / 100.

HTNAUDIT (RPG) — night audit. Daily.

For each I stay with RLAUDT < run date and DEPDT > RLAUDT: post one more room+tax pair at FSEQ = RNIGHTS×2 + 1 (and +1), RNIGHTS++, RLAUDT=run date, RBAL += rate + tax. Stays past departure are not billed further.

HTINCTAL (RPG) — incidental accrual. Daily.

Walks HTFOLIO; for each O line that is not RM/TX/PY, stamps it A and adds FAMT to the reservation's RBAL once.

HTPAYAPL (RPG) — payment application. Daily.

Walks HTFOLIO; for each O line with FCODE='PY' (amount already negative), stamps it A and adds the negative FAMT to RBAL once (reducing it).

HTCHKOUT (RPG) — check-out + settlement. Daily.

For each I stay with DEPDT ≤ run date: if RBAL > 0, count HELD and leave; else RSTAT='O', release room to D, and set every open folio line to S.

HTHSKP (RPG) — housekeeping. Weekly.

Walks HTROOM; every D room becomes V.

HTNOSHOW (RPG) — no-show release. Weekly.

Walks HTRESVLF (arrival-keyed); each B stay with ARRDT < run date becomes S and its room is released to V.

HTOCCRPT (RPG) — occupancy/revenue report. Monthly.

For each O (occupied) room, finds the checked-in reservation that holds it, resolves the guest, and prints room/type/status/guest/balance via HTOCCP; totals count and balance with overflow (*IN90) header reprint.

HTGLPST (SQLRPGLE) — GL post. Monthly.

Sums every RM and TX folio line; via embedded SQL reads MAX(GLSEQ) and the already-posted 4100-ROOM / 2200-TAX credits, subtracts them, and inserts the balanced movement (cash Dr, room Cr, tax Cr). A refused insert (sqlcod ≠ 0) is not counted.

HTARCHIV (RPG) — folio archive + reset. Annual.

For each O stay with RNIGHTS ≠ 0: sums the stay's RM/TX/FB/MB folio lines, WRITEs one YE line at FSEQ = 900 + RNIGHTS×2, then resets RNIGHTS=0, RLAUDT=0.

HTRESVIQ / HTFOLIQ / HTMENU (RPG) — online

Reservation inquiry (CHAIN HTRESV/HTGUEST), folio subfile inquiry (clear + reload FSFL), and the menu that CALLs them by option. All read-only.

HTAUDRPT (ILE COBOL) — folio control report

Reads HTFOLIO sequentially by key; accumulates room / tax / other and counts total lines and open lines; DISPLAYs the five totals. The independent reconciliation of the RPG postings.

HTSETUP (CL) — build

DLTF the files, CRTPF/CRTLF/CRTDSPF/CRTPRTF from QDDSSRC, RUNSQLSTM the GL table + index from QSQLSRC, CRTBNDRPG all 15 RPG programs and CRTBNDCBL the COBOL program.

F.2 Access paths & the allocation walk

The three logical files exist because each carries a genuinely different leading key from its PF, giving a program the ordering it actually needs:

• HTROOMLF (RTYPE-keyed) — allocation does SETLL(WTYPE) then READE by type, so it walks only rooms of the requested type in room-number order and takes the first V one. The base HTROOM is ROOMNO-keyed; the LF is RTYPE-keyed — genuinely different orderings, which is what makes the walk worth having (the build test asserts this).
• HTRESVLF (ARRDT-keyed) — the no-show sweep walks reservations in arrival-date order to find B stays whose arrival has passed.
• HTFOLLF (FCODE-keyed) — a revenue-by-department path (room / tax / F&B / minibar) for reporting without re-summing every folio.

Programs that walk a keyed file to enumerate rows and then need the header again re-CHAIN the header afterwards, because the row walk moved the shared cursor — e.g. HTRESERV re-CHAINs HTRESVR after the room walk, and HTARCHIV re-CHAINs after summing folio lines.

F.3 Idempotency guards

Guard	Where	How it prevents a double
RSTAT skip	HTRESERV/HTCHKIN/HTNAUDIT/HTCHKOUT/HTNOSHOW	Only rows in the acted-on state are processed; a processed row has moved to a new state.
RLAUDT stamp	HTNAUDIT	RLAUDT ≥ run date skips a stay already audited on that date — the same-day double-post guard.
FSTAT flip	HTINCTAL / HTPAYAPL	A line folded into RBAL is stamped A; a re-run only sees O lines.
Movement read-back	HTGLPST	Reads already-posted 4100-ROOM/2200-TAX and subtracts, so a re-run's delta is zero (never restarts GLSEQ at 1).
RNIGHTS=0 reset	HTARCHIV	A reset stay carries RNIGHTS 0; a live stay always ≥ 1, so a second annual run finds nothing to archive.
Settlement gate	HTCHKOUT	Refuses RBAL > 0; a stay cannot be closed (or double-closed) with money owing.

F.4 The run-date model

Every date-sensitive program carries its processing date as a compiled literal in a WRUNDT/WBATCH field rather than reading a control row:

Program	Literal	Meaning
HTCHKIN	20260801	Check-in / first-night run date.
HTNAUDIT	20260802	Night-audit run date (posts night 2).
HTCHKOUT	20260803	Check-out run date.
HTNOSHOW	20260805	No-show sweep run date.
HTGLPST	202608 / 20260831	GL batch period / GL row date.
HTARCHIV	20261231	Year-end archive-line date.

Operational consequence: the shipped estate is a hand-checkable oracle across the first days of August 2026 — the night audit posts exactly one further night, check-out lands on the departure date, and the no-show sweep fires for the DLX reservation that was never checked in. To advance the model to a new business date in a real deployment, the run-date literals are the single edit point (change WRUNDT and recompile), not a control-row update. This is an honest limitation of the sample: it trades a live clock for a deterministic, auditable oracle.

G. Glossary ↑ top

Allocation

Assigning a specific room to a reservation. HTRESERV walks the type-keyed room LF for the first vacant-clean room of the requested type and earmarks it (room → O, reservation → B); no room free → waitlisted (W).

Folio

A guest stay's running bill — here the set of HTFOLIO lines for one reservation, each a room night, tax, incidental, payment or year-end archive line. HTRESV.RBAL mirrors its balance.

Night audit

The nightly hotel batch that posts each in-house stay one more night's room charge and tax. HTNAUDIT; guarded by RLAUDT so it cannot double-post the same date.

Occupancy tax

A flat 10% of the room charge, posted as a separate TX folio line alongside each RM night.

No-show

A booked reservation whose arrival date passed without a check-in. HTNOSHOW marks it S and releases its earmarked room back to the vacant pool.

Rate lock (RATELOCK)

The room-type nightly rate stamped onto the reservation at booking, so a later rate change never reprices a guest already holding a reservation — "stamp it once, trust the stamp".

RBAL mirror

The folio running balance carried on the reservation header, so the header alone answers "what is owed" without a folio scan; every posting program keeps it in step.

Room status (V/O/D/X)

Availability of a physical room: vacant-clean (sellable), occupied, vacant-dirty (checked out, needs housekeeping before resale), out-of-order (never allocated).

Settlement gate

HTCHKOUT's refusal to close a stay whose balance is still positive — an unsettled folio cannot check out.

SBMJOB

Submit Job — the IBM i command that queues a program to run as a batch job (e.g. SBMJOB CMD(CALL PGM(HOSTEL/HTDAILY))). The cycle CLs take no parameters.

Subfile

A 5250 display construct listing many rows on one screen (DDS SFL/SFLCTL). HTFOLIQ's folio-line list is a subfile (SFLSIZ 20 / SFLPAG 5, roll keys).

Turnover sweep (housekeeping)

HTHSKP's weekly pass returning every vacant-dirty room to vacant-clean so it can be sold again.