PAYCHEK/i — Payroll & Human Resources

PAYCHEK/i is an employee payroll and HR application: an employee master with a graduated-tax withholding table, weekly time capture with an edit/validate pass, a full gross-to-net payroll run (regular + overtime earnings, pre-tax deductions, graduated tax, post-tax deductions), payslip and payroll-register printing, employer-contribution and leave accrual, a double-entry GL distribution into a SQL feed, and quarterly / year-end tax reporting with an accumulator reset. The business logic is coded in fixed- and free-form ILE RPG, with an ILE COBOL trial balance and an embedded-SQL GL feed; the periodic work runs as four CL job cycles. This manual is the reference for the operator who runs the cycles and the online screens, and for the developer maintaining the application. It is grounded entirely in the committed source (payroll-app/src/sources.mjs, src/seed.mjs, and the test/py_*.mjs battles). Everything runs in library PAYCHEK.

A. Overview & Architecture ↑ top

A.1 What it does

PAYCHEK/i runs the full weekly-to-annual payroll cycle:

• Time capture & edit — capture one raw time card per employee per work week, then validate it: default nothing, reject an unknown or non-active employee, reject an over-ceiling or non-positive hours card, and split validated raw hours into regular and overtime against the employee's standard week.
• Gross-to-net payroll run — for every validated card compute regular pay, overtime at the employee's OT factor, gross, every active pre-tax deduction, taxable pay, graduated tax withholding, post-tax flat deductions, and net; write the payroll header, the itemised payslip lines, and roll the year-to-date accumulators forward.
• Payslip / register print — print one payslip block per employee and a payroll-register total line to a printer file, and run an ILE COBOL trial balance that proves gross reconciles to net + tax + pre-tax + post-tax.
• Monthly accrual & GL — accrue employer FICA and pension on top of gross, accrue monthly leave entitlements, and post a balanced double-entry payroll journal into the SQL GL feed.
• Annual close — report the quarterly / annual filing position, print W2-style year-end statements, then reset the YTD accumulators for the new tax year.

A.2 The gross-to-net model (every figure is hand-derivable)

The pay calculation is deliberately closed-form and derivable to the cent — the tests assert the exact arithmetic. For one employee for one period (from the source header of sources.mjs):

  regular pay = REGHRS * RATE
  overtime    = OTHRS  * RATE * OTFACT           OTFACT is 7P4, seeded 1.5000
  gross       = regular + overtime
  pre-tax     = gross * DEDRATE                  for every ACTIVE pre-tax ('P') deduction
  taxable     = gross - pre-tax
  tax         = graduated over PYTAXB: each band taxes the slice of taxable
                that falls inside (BLOW, BHIGH] at BRATE
  post-tax    = flat-amount deductions ('F')     DEDAMT
  net         = gross - pre-tax - tax - post-tax

Money multiplications are half-adjusted to the cent (RPG eval(h)): e.g. FICA 2750.00×0.0765 = 210.375 rounds to 210.38, where a truncating calc would give 210.37. Rates are packed 7P4 (four decimal places) because an hourly rate or a 5.25% election rarely lands on cents; money is packed 11P2 (or wider for YTD/GL totals).

A.3 Component & flow

  ONLINE                 DAILY                  WEEKLY                 MONTHLY / ANNUAL
  ------                 -----                  ------                 ----------------
  PYMENU (5250)          PYDAILY  --calls-->    PYWEEK  --calls-->     PYMONTH --calls-->
   1 -> PYEMPIQ            PYTIMLD (raw load)     PYCALC (gross-to-net)  PYERACC (ER FICA/pension)
   2 -> PYSLPIQ (SFL)      PYTIMED (edit/split)   PYSLPRT (payslips)     PYLVACR (leave accrual)
                           PYTIMRP (reject rpt)   PYGLRPT (COBOL bal.)   PYGLDST (SQL GL feed)
                                                                         PYGLRPT (COBOL bal.)
                                                                        PYYEAR  --calls-->
                                                                         PYQTAX (tax summary)
                                                                         PYW2   (W2 + YTD reset)
                                                                         PYQTAX (nil re-check)
     data files (library PAYCHEK)
     -------------------------------------------------------------------------------------
     PYEMP  employee master      PYTIME  time cards (+PYTIMLF by status)
     PYDEDM deduction elections  PYTAXB  graduated tax bands
     PYPAYH payroll headers      PYPAYD  payslip lines (+PYPAYDLF by code)
     PYYTD  YTD accumulators     PYLEAVE leave balances
     PYERCON employer/leave ledger (durable audit trail)
     PYGLFEED SQL GL feed (+PYGLFACC index over ACCT,DRCR)

A single payroll event flows: PYDAILY loads and validates the week's cards (setting TSTAT='V') → PYWEEK runs PYCALC, which reads each 'V' card, computes gross-to-net from PYEMP/PYDEDM/PYTAXB, writes PYPAYH+PYPAYD, rolls PYYTD, and flips the card to 'P' → PYMONTH accrues the employer side and distributes to the GL → PYYEAR reports and resets. There is no separate business-rule layer: each RPG program owns its own calculation directly over the keyed files.

A.4 Object inventory

The catalogue is 9 PFs + 2 LFs + 1 SQL table + 1 SQL index, 3 DSPFs and 1 PRTF, driven by 14 RPG programs, 1 COBOL program and 5 CL programs. Sections D and F expand each.

B. Online Transactions & Screens ↑ top

B.1 The command/entry line

PAYCHEK/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 PAYCHEK — the tested jobs run with LIBL = QSYS QGPL PAYCHEK QTEMP and CURLIB = PAYCHEK.

The batch cycles take no CALL parameters: PAYCHEK/i carries no control-row table. Instead each program hard-scopes its period in its own source — the seeded work week is 202631, the tax year is 2026, and the GL batch is 202608 — and re-runs are made safe by per-row idempotency guards rather than a control date (section F.4). Only PYMENU, PYEMPIQ and PYSLPIQ are interactive; every other program runs to completion and DSPLYs a one-line result banner.

B.2 The menu & the two screens (PYMENU / PYEMPIQ / PYSLPIQ)

PYMENU is the driver: it EXFMTs the menu, then CALLs the chosen program (option 1→PYEMPIQ, option 2→PYSLPIQ), reports "Invalid option." for anything else, and exits on F3. Control returns to the menu when the called program ends.

PYEMPIQ — employee inquiry (plain DSPF, format EMPINQ)

Key an employee number; the program CHAINs PYEMP and renders the master record plus the derived standard-week gross (STDHRS × RATE, half-adjusted). An unknown employee clears the detail and shows "Employee not found."; a fresh key re-CHAINs so the previous employee's values never linger.

PYSLPIQ — payslip inquiry with a subfile (PYSLIPD: SSFL / SCTL)

This is the app's subfile screen. It CHAINs a payroll header (PYPAYH) for the keyed employee (fixed work week 202631), renders gross and net, then loads the itemised payslip lines from PYPAYD on a partial (PYWEEK, EMPNO) key so exactly one payslip loads in line order. The subfile is SFLPAG(5) / SFLSIZ(20) with ROLLUP/ROLLDOWN paging and SFLEND(*MORE).

Subfile columns (SSFL) & actions

• Enter — inquire the keyed employee; the subfile is cleared (SFLCLR via *IN31) and reloaded for the new key.
• Roll↑/Roll↓ — page the subfile.
• F3 (Exit) — return to the menu (or end the program if called directly).

B.3 Controls & audit workflow (no four-eyes maker–checker)

Honest statement: PAYCHEK/i does not model a true four-eyes maker–checker / separate-authorization workflow. There is no "one user enters, a second user approves" step: a validated time card is picked up and paid by PYCALC in the same run, and the online screens are inquiry-only (no maintenance option posts a payroll figure). The manual documents the control model the application does have:

• Two-stage state gating on time. A card is captured raw (TSTAT='E'), then the daily edit either validates it ('V', with regular/overtime split) or rejects it ('R', with a reason code). The payroll run pays only 'V' rows and flips them to 'P' (paid); nothing else is payable.
• Reject reason codes (TERRCD). Every rejected card carries E1–E4 (unknown employee / not active / over the 80.00-hour ceiling / non-positive hours) and zeroed payable hours; the PYTIMRP report enumerates the breakdown over the status logical file.
• The employer ledger (PYERCON) as a durable audit trail. Every employer FICA / pension / leave accrual is written to a unique-keyed, accumulating ledger. Keys are derived from a stable business key per employee (FICA/pension in the 3000… band, leave in the 5000… band) so a re-run regenerates the same key and is refused rather than double-posting.
• The payroll identity as a control total. Every period must satisfy gross = net + tax + pre-tax + post-tax. The ILE COBOL PYGLRPT trial balance recomputes this over the headers and reports BALDIFF; a healthy period is BALDIFF 0.00. The GL distribution is posted as balanced debit/credit pairs so SUM(DR) = SUM(CR) in the feed.
• UNIQUE-key integrity. The composite unique keys — PYTIME(TWEEK,EMPNO), PYPAYH(PYWEEK,EMPNO), PYYTD(TAXYR,EMPNO) — are what make the loaders and the payroll run safe to re-run: an already-present row is refused / skipped.

In sum, the control posture is staged state-gating on time cards + a durable employer ledger + reconciling control totals + unique-key idempotency, all enforced in the RPG/data layer, rather than a segregation-of-duties approval workflow.

C. Batch Jobs & the Periodic Cycle ↑ top

PAYCHEK/i's work runs as four CL job cycles rather than one monolithic job: a daily cycle (time capture + edit), a weekly cycle (the payroll run + print + trial balance), a monthly cycle (employer & leave accrual + GL distribution), and an annual cycle (tax summary + W2 + reset). Each CL ADDLIBLE LIB(PAYCHEK), then CALLs its member programs in order and sends a completion banner. There are no CALL parameters and no control-row table; the period is fixed in each program's source (week 202631, year 2026).

-- a scheduled submission is a bare CALL of the cycle CL:
SBMJOB CMD(CALL PGM(PAYCHEK/PYDAILY)) JOB(PYDAILY)
SBMJOB CMD(CALL PGM(PAYCHEK/PYWEEK))  JOB(PYWEEK)

C.1 Full batch program set

C.2 Daily / weekly / monthly / annual detail

Daily — PYDAILY (PYTIMLD → PYTIMED → PYTIMRP)

PYTIMLD writes the week's raw cards, deliberately including exception cards the edit must catch (an unknown employee, a terminated employee, a duplicate key). PYTIMED walks every 'E' card, CHAINs PYEMP, and validates: reason E1 unknown employee, E2 not active, E3 raw hours over the 80.00 weekly ceiling, E4 non-positive hours. A validated card's raw hours are split against STDHRS: hours up to the standard week are regular, the excess is overtime. PYTIMRP reads only 'R' rows over PYTIMLF and reports the reason breakdown.

Expected DSPLY (seeded week 202631):
  PYTIMLD CARDS=6 SKIP=1     6 raw cards; 7th is a duplicate (week,emp) key, refused
  PYTIMED OK=4 REJ=2         E00001/2/3/4 validated; E00009=E1, E00005=E2
  PYTIMRP REJ=2 E1=1 E2=1 E3=0
Reg/OT split: E00001 40/0, E00002 40/5, E00003 35/0, E00004 40/10 (155 reg, 15 OT).

Weekly — PYWEEK (PYCALC → PYSLPRT → PYGLRPT)

PYCALC is the gross-to-net engine (F.3). For each 'V' card it computes the figures, writes one PYPAYH header and the itemised PYPAYD lines, rolls PYYTD forward (creating the row on the first period), and flips the card to 'P'. PYSLPRT prints one payslip block per header plus a register total; PYGLRPT is the COBOL trial balance.

Expected DSPLY:
  PYCALC PAID=4 SKIP=2       4 validated paid, 2 rejects skipped
  PYSLPRT SLIPS=4 NET=4449.10
  PYGLRPT BALDIFF 0.00       gross 5875.00 = net + tax + pre-tax + post-tax

Monthly — PYMONTH (PYERACC → PYLVACR → PYGLDST → PYGLRPT)

PYERACC accrues employer FICA (7.65%) and a pension match (3.00%) on YTD gross, both half-adjusted, into PYERCON and the PYYTD.YERFICA/YERPENS buckets. PYLVACR accrues each active leave entitlement's monthly hours (10.0000 vacation, 4.0000 sick) into LEARNED and recomputes LBAL = LEARNED - LTAKEN. PYGLDST posts a balanced payroll journal into PYGLFEED via embedded exec sql insert.

Expected DSPLY / figures:
  PYERACC ACCRUED=4  FICA=449.44 PENS=176.25
  PYLVACR ACCRUED=6  HRS=48.00
  PYGLDST BATCH=202608 GROSS=5875.00
  GL debits: 6100-WAGE 5875.00, 6200-ERTX 449.44, 6300-ERPN 176.25  (SUM DR = 6500.69)
  GL credits: 2100-NETP 4449.10, 2200-TAXP 990.40, 2300-PRET, 2400-PSTT, 2500-ERTP 449.44, 2600-ERPP

Annual — PYYEAR (PYQTAX → PYW2 → PYQTAX)

PYQTAX sums the YTD accumulators into the filing position: employees paid, total gross, total taxable, total withholding, employer FICA/pension, and the total remittance liability (withholding + employer FICA). PYW2 prints one W2-style statement per employee (BOX1 wages, BOX2 fed tax, BOX3 soc-sec wages, BX12 deferred comp) and then zeroes the YTD accumulator for the new tax year. PYYEAR re-runs PYQTAX after the reset to confirm the year closed to nil.

Expected DSPLY:
  PYQTAX EMPS=4 GROSS=5875.00 TAXBL=5464.50 WH=990.40
  PYQTAX ERFICA=449.44 ERPENS=176.25 LIAB=1439.84
  PYW2 STMTS=4 SKIP=0 GROSS=5875.00
  PYQTAX EMPS=0 GROSS=0.00        post-reset nil re-check

C.3 Ordering & dependencies

• DAILY before WEEKLY. Only the daily edit sets TSTAT='V' and splits reg/OT; PYCALC pays only 'V' cards, so unedited or unloaded cards are not paid.
• WEEKLY before MONTHLY. The employer accrual keys off PYYTD.YGROSS (built by the payroll run), and the GL distribution reads PYPAYH + PYERCON, so the pay run and the accruals must precede the GL feed.
• MONTHLY before ANNUAL. PYQTAX's employer-FICA figure and the remittance liability come from PYYTD.YERFICA, populated by the monthly accrual.
• Within a cycle order is fixed by the CL: within DAILY, load→edit→report; within WEEKLY, calc→print→balance; within ANNUAL, summary→W2/reset→nil re-check (the reset must be after the W2 print and after the pre-reset summary).

D. Data Files (data dictionary) ↑ top

All files are in library PAYCHEK, grounded in the DDS/DDL in sources.mjs. Dates are stored as signed integers in YYYYMMDD form; rates are packed 7P4 (four decimals; 1.5000 = time-and-a-half, 0.0500 = 5%); money is packed 11P2 (or 13P2 for YTD / GL totals). Employee numbers are E00001-style (a letter + 5 digits, so %dec(%subst(empno:2:5)) yields a stable numeric business key).

PYEMP — Employee master (K EMPNO, UNIQUE)

PYTIME — Weekly time cards (K TWEEK, EMPNO, UNIQUE)

PYTIMLF is a non-unique LF over the same record keyed K TSTAT, K EMPNO, so the payroll run and the exception report read one state without scanning the week.

PYPAYH — Payroll header (K PYWEEK, EMPNO, UNIQUE)

PYPAYD — Payslip lines (K PYWEEK, EMPNO, LSEQ, UNIQUE)

PYPAYDLF is a non-unique LF keyed K LCODE, K EMPNO — a "who is paying into this deduction code, and how much" enquiry across every pay period as a keyed read.

PYDEDM — Deduction elections (K EMPNO, DEDCD, UNIQUE)

PYTAXB — Graduated withholding bands (K TAXCD, BSEQ, UNIQUE)

Seeded S1 table: band 1 0.01–500.00 @ 10%, band 2 500.01–1500.00 @ 20%, band 3 above 1500.00 @ 30%.

PYLEAVE — Leave balances (K EMPNO, LVTYP, UNIQUE)

PYYTD — Year-to-date accumulators (K TAXYR, EMPNO, UNIQUE)

PYERCON — Employer-contribution / leave ledger (K ECSEQ, UNIQUE)

PYGLFEED — SQL GL feed (PK GLSEQ; index PYGLFACC on ACCT, DRCR)

Relationships

• PYTIME.EMPNO, PYDEDM.EMPNO, PYLEAVE.EMPNO, PYPAYH.EMPNO, PYYTD.EMPNO → PYEMP.EMPNO (the spine).
• PYTIME.EMPNO → PYEMP for the rate / OT factor / tax code the payroll run reads.
• PYEMP.TAXCD → PYTAXB.TAXCD (the graduated band set for that employee).
• PYPAYD (PYWEEK, EMPNO) → PYPAYH (the itemised lines behind each header).
• PYERCON.EMPNO → PYEMP; PYGLFEED is an aggregate feed keyed only by GLSEQ / ACCT.
• All join / lookup keys are declared UNIQUE composite keys (there are no declared referential constraints; integrity is by key discipline in the programs).

E. Operations Runbook ↑ top

E.1 Day-in-the-life

1. Confirm the job's library list includes PAYCHEK (LIBL = QSYS QGPL PAYCHEK QTEMP).
2. One-off, on a fresh library: CALL PAYCHEK/PYSETUP then CALL PAYCHEK/PYREFLD (expect PYREFLD EMP=5 DED=6 BAND=3 LEAVE=6).
3. Run the daily time-capture cycle: SBMJOB CMD(CALL PGM(PAYCHEK/PYDAILY)). Post-check PYTIMLD CARDS=6 SKIP=1, PYTIMED OK=4 REJ=2, PYTIMRP REJ=2 E1=1 E2=1.
4. Handle inquiries interactively through CALL PAYCHEK/PYMENU (option 1 employee, option 2 payslip).

Pre-checks: raw cards captured and edited (all cards out of the 'E' state) before the weekly run; the reference data seeded once.

E.2 Payroll run, period & year close

1. Weekly run: SBMJOB CMD(CALL PGM(PAYCHEK/PYWEEK)). Confirm PYCALC PAID=4 SKIP=2, PYSLPRT SLIPS=4 NET=4449.10, and the COBOL PYGLRPT BALDIFF 0.00.
2. Monthly close: CALL PAYCHEK/PYMONTH. Confirm the accrual banners and the balanced GL feed.
3. Annual close: CALL PAYCHEK/PYYEAR. Confirm the summary, the W2 print, and the post-reset nil re-check.
4. Reconcile the figures below against the payroll headers and the GL feed.

Reconciling figures (the exact cents the cycle battle asserts against a hand-derived oracle, for the seeded 4-employee week):

• Payroll identity — gross 5875.00 = net 4449.10 + tax 990.40 + pre-tax 410.50 + post-tax 25.00 (the COBOL trial balance reports BALDIFF 0.00).
• E00003 proves a suspended election — its 4% 401(k) is DEDSTAT='S', so pre-tax is 0.00 and taxable equals gross; the payslip has no 401K line.
• E00004 reaches the third band — 500×10% + 1000×20% + 975×30% = 542.50.
• Employer accrual — FICA total 449.44 (76.50 + 109.01 + 53.55 + 210.38; note 2750.00×0.0765 = 210.375 half-adjusts up to 210.38), pension total 176.25.
• Leave accrual — 4 vacation @ 10.0000 + 2 sick @ 4.0000 = 48.0000 hours.
• GL feed — DR total 6500.69 = gross 5875.00 + er FICA 449.44 + er pension 176.25, and SUM(DR) = SUM(CR); six liability credits under the 2% accounts.
• Annual filing — taxable 5464.50, withholding 990.40, remittance liability withholding 990.40 + employer FICA 449.44 = 1439.84; after PYW2 the YTD accumulators are zero for the new year.

E.3 Failure & re-run rules

Each program DSPLYs a result banner. PAYCHEK/i has no control-date table; every re-run is made safe by a per-row idempotency guard, so a cycle can simply be resubmitted.

F. Developer Reference ↑ top

The program surface, from sources.mjs. All objects are in library PAYCHEK; source members live in QDDSSRC / QRPGLESRC / QCBLLESRC / QSQLSRC / QCLSRC, created and compiled by PYSETUP.

F.1 Batch programs

PYREFLD (RPGLE) — reference-data loader

Writes 5 employees (4 active + 1 terminated), 6 deduction elections (3 active pre-tax, 1 suspended, 2 post-tax flat), the 3-band S1 tax table, and 6 leave entitlements.

PYTIMLD (RPGLE) — raw time-card loader

Writes week 202631's raw cards including deliberate exceptions (unknown, terminated, duplicate key). Idempotent on the UNIQUE (TWEEK, EMPNO) key via a CHAIN(EN)/skip guard.

PYTIMED (RPGLE) — daily edit/validate

Reads each 'E' card, CHAINs PYEMP, applies E1–E4, splits reg/OT against STDHRS, and updates the card to 'V'/'R'. Re-CHAINs the card after the master lookup (the lookup moves the file cursor).

PYTIMRP (RPGLE) — reject report

READE over PYTIMLF keyed 'R'; counts the reason-code breakdown.

PYCALC (RPGLE) — the weekly gross-to-net run

See F.3.

PYSLPRT (RPGLE) — payslip / register print

Prints one payslip block per header (partial-key READE of PYPAYD in line order) plus a register total, to the PYSLIPP printer file with overflow on *IN90.

PYERACC (RPGLE) — employer accrual

FICA 0.0765 + pension 0.0300 of YGROSS, half-adjusted, into PYERCON (key 30000000 + digits*10 + n) and PYYTD. Idempotent on the stable key.

PYLVACR (RPGLE) — leave accrual

Each active entitlement earns LACCR hours; LEARNED grows, LBAL = LEARNED - LTAKEN. Ledgered at key 50000000 + digits*10 + type#.

PYGLDST (SQLRPGLE) — GL distribution

Accumulates PYPAYH and PYERCON, then writes balanced DR/CR pairs to PYGLFEED via free-form exec sql insert. Gross = net + tax + pre-tax + post-tax by construction, so it balances.

PYQTAX (RPGLE) — tax summary

Sums PYYTD into EMPS/GROSS/TAXBL/WH and ERFICA/ERPENS; liability = WH + employer FICA.

PYW2 (RPGLE) — W2 print + YTD reset

Prints BOX1/BOX2/BOX3/BX12 per employee, then zeroes every PYYTD field for the new year (skips an already-zero accumulator).

PYGLRPT (ILE COBOL) — trial balance

Reads PYPAYH sequentially; computes W-CHK = net + tax + pre + post and W-DIFF = gross - W-CHK; DISPLAYs the totals and BALDIFF.

F.2 Online programs & DDS

PYMENU (RPGLE) / PYMENUD (DSPF)

EXFMT PYMENU; option 1 CALL 'PYEMPIQ', option 2 CALL 'PYSLPIQ', else "Invalid option."; F3 (CA03/*IN03) exits.

PYEMPIQ (RPGLE) / PYEMPD (DSPF, format EMPINQ)

Plain screen; CHAINs PYEMP on IEMP, renders the master and the derived STDHRS × RATE gross (eval(h)), clears on a miss.

PYSLPIQ (RPGLE) / PYSLIPD (DSPF, SSFL/SCTL subfile)

Subfile screen (SFLPAG 5 / SFLSIZ 20 / ROLLUP/ROLLDOWN / SFLEND(*MORE)); clears the subfile with *IN31 after the EXFMT returns the new key, then reloads PYPAYD on a partial (PYWEEK, EMPNO) key. See the B.2 note on the engine stale-row render defect.

F.3 The gross-to-net engine (PYCALC)

The PAY1 subroutine, per validated card, in order:

1. Skip non-'V' cards; guard the (PYWEEK, EMPNO) header key (already paid → skip); CHAIN PYEMP for rate / OT factor / tax code; skip a non-active employee.
2. eval(h) wregp = REGHRS × RATE; eval(h) wotp = OTHRS × RATE × OTFACT; gross = regular + overtime. Write the REG earning line (and the OT line if OTHRS > 0, carrying the effective rate RATE×OTFACT).
3. READE PYDEDM by employee: for each DEDSTAT='A' & DEDTYP='P', eval(h) wamt = gross × DEDRATE; accumulate pre-tax; write the P line.
4. taxable = gross - pre-tax. READE PYTAXB by tax code in band order: for each active band, tax the slice of taxable inside (BLOW, BHIGH] at BRATE, half-adjusted; write one T (FWH) line.
5. READE PYDEDM again: for each DEDSTAT='A' & DEDTYP='F', add DEDAMT; write the F line. net = gross - pre-tax - tax - post-tax.
6. Write the PYPAYH header; roll PYYTD forward (create on the first period, else update & increment YPERIODS); re-CHAIN the time card and flip it to 'P'.

F.4 Idempotency & access-path patterns

• Composite-key guards. Guards use a full KLIST (both key parts), never a partial CHAIN on the first part alone, which would match the wrong employee — PYPAYH (PYWEEK, EMPNO), PYTIME (TWEEK, EMPNO), PYYTD (TAXYR, EMPNO).
• Stable business keys for ledgered accruals. PYERCON keys are derived from the employee number digits (%dec(%subst(empno:2:5))) so a re-run regenerates the same key and is refused (CHAIN(EN) + LEAVESR). FICA/PENS use the 30000000 band, LEAV the 50000000 band — disjoint ranges.
• Re-CHAIN after a lookup. Any subroutine that CHAINs a second file re-CHAINs the driving record before updating it, because the lookup moved that file's cursor (PYTIMED, PYCALC, PYERACC, PYLVACR, PYW2 all do this).
• Alternate access paths. PYTIMLF (K TSTAT) lets the edit/report read one card state without a full scan; PYPAYDLF (K LCODE) supports a by-deduction-code enquiry; the SQL index PYGLFACC over (ACCT, DRCR) resolves the six liability credits.
• Embedded SQL. PYGLDST uses free-form exec sql insert into PAYCHEK.PYGLFEED values (…); — the only SQL-writing program; everything else is native keyed I/O.

F.5 Reject reason-code table (TERRCD, set by PYTIMED)

A rejected card carries the reason in TERRCD, is set TSTAT='R', and has REGHRS and OTHRS zeroed, so it can never be paid.

G. Glossary ↑ top

Accrual (employer / leave)

Recognising a cost the employer owes on top of gross (FICA, pension) or an entitlement earned (leave hours), posted to the PYERCON ledger and the YTD / leave buckets.

Basis / packed decimal (nP m)

The DDS packed-decimal declaration: total digits n, m decimals. Rates are 7P4 (four decimals), money 11P2, wide totals 13P2.

Deduction (pre-tax / post-tax)

A pre-tax ('P') deduction is rate-based and reduces taxable pay (e.g. 401(k)); a post-tax ('F') deduction is a flat amount taken after tax (e.g. union dues). A DEDSTAT='S' election is suspended and not taken.

FICA

The employer's payroll-tax contribution, here modelled as a flat 7.65% of gross (a deliberately simple, auditable figure, not a wage-base-capped regulatory model).

Graduated withholding

Tax computed band by band: each PYTAXB band taxes the slice of taxable pay inside (BLOW, BHIGH] at its marginal BRATE, summed. Seeded S1: 10% / 20% / 30%.

Gross-to-net

The payroll calculation from gross earnings down to net pay: gross - pre-tax - tax - post-tax.

Half-adjust (eval(h))

RPG rounding to the last retained digit (round half up), so a money multiplication lands on exact cents rather than truncating (2750.00×0.0765 = 210.375 → 210.38).

Idempotent

Safe to run again with the same result. Here every loader / run / accrual is idempotent via a UNIQUE composite key or a stable ledger key, not via a control date.

Overtime factor (OTFACT)

The multiplier applied to overtime hours (seeded 1.5000, time-and-a-half); the effective OT rate is RATE×OTFACT.

Payroll identity

The control total gross = net + tax + pre-tax + post-tax, verified by the COBOL trial balance (BALDIFF 0.00) and by the balanced GL feed.

SBMJOB

Submit Job — the IBM i command that queues a program to run as a batch job (e.g. SBMJOB CMD(CALL PGM(PAYCHEK/PYWEEK))).

Subfile

A 5250 display construct listing many rows on one screen (DDS SFL/SFLCTL). PYSLPIQ's payslip-line list is a subfile.

Time-card states (TSTAT)

E entered (raw), V validated (edit passed, reg/OT split), R rejected (with a reason code), P paid (picked up by the payroll run).

W2-style statement

The year-end per-employee summary printed by PYW2 (BOX1 wages, BOX2 fed tax, BOX3 soc-sec wages, BX12 deferred comp), after which the YTD accumulators reset.

YTD accumulator (PYYTD)

The per-employee, per-tax-year running totals the quarterly report sums and the year-end statement prints, reset to zero by the annual roll.