PERP-1: foundation module for the PreSales ERP demo (perp/)

cfdemo/Rules.mk

@@ -25,7 +25,10 @@ products2l.file: qddssrc/products2l.lf | productsp.file
 
 # Message file and menu
 menu.msgf: menu.msgf
-menu.menu: menu.msgf | menu.file
+# .file MUST be a normal prereq (not order-only) or codermake silently
+# drops the CRTMNU recipe -- see perp/DDL_STYLE_GUIDE.md "codermake
+# gotchas" for the general rule (discovered there, applies here too).
+menu.menu: menu.msgf menu.file
 
 # Simple program
 hellor.pgm: qrpglesrc/hellor.rpgle qddssrc/hellod.dspf | hellod.file

cfdemo/menu.msgf

@@ -2,4 +2,5 @@ crtmsgf msgf($LIBRARY/$NAME)
 addmsgd msgid(usr0001) msgf($LIBRARY/$NAME) msg('call wrkcustr') seclvl(*none) sev(00) fmt(*none)
 addmsgd msgid(usr0002) msgf($LIBRARY/$NAME) msg('call wrkcustro') seclvl(*none) sev(00) fmt(*none)
 addmsgd msgid(usr0003) msgf($LIBRARY/$NAME) msg('call wrkcusteo') seclvl(*none) sev(00) fmt(*none)
+addmsgd msgid(usr0004) msgf($LIBRARY/$NAME) msg('go perpdemo/perpmnu') seclvl(*none) sev(00) fmt(*none)
 addmsgd msgid(usr0090) msgf($LIBRARY/$NAME) msg('signoff') seclvl(*none) sev(00) fmt(*none)

cfdemo/qddssrc/menu.dspf

@@ -24,6 +24,7 @@
      A                                  5  7'1. Work with Customers'
      A                                  6  7'2. Work with Customers (RPGOA)'
      A                                  7  7'3. Work with Customers (EJS)'
+     A                                  8  7'4. Go to PERP menu (PERPMNU)'
      A                                 10  6'90. Sign off'
      A* CMDPROMPT  Do not delete this DDS spec.
      A                                021  2'Selection:                        -

cfdemo/tmp/logs/menu.file.log

@@ -0,0 +1,92 @@
+CPC7301:  File QDDSSRC created in library AITSK00019.
+CPC7305:  Member MENU added to file QDDSSRC in AITSK00019.
+CPC7301:  File MENU created in library AITSK00019.
+  5770SS1 V7R5M0  220415                  Data Description               AITSK00019/MENU          8/23/26 16:28:31        Page    1
+  File name . . . . . . . . . . . . . . . . . . . . . :   MENU
+    Library name  . . . . . . . . . . . . . . . . . . :   AITSK00019
+  File attribute  . . . . . . . . . . . . . . . . . . :   Display
+  Source file containing DDS  . . . . . . . . . . . . :   QDDSSRC
+    Library name  . . . . . . . . . . . . . . . . . . :   AITSK00019
+  Source member containing DDS  . . . . . . . . . . . :   MENU
+  Source member last changed  . . . . . . . . . . . . :   08/26/26  16:28:30
+  Source listing options  . . . . . . . . . . . . . . :   *SOURCE    *LIST      *NOSECLVL  *NOEVENTF
+  DDS generation severity level . . . . . . . . . . . :   20
+  DDS flagging severity level . . . . . . . . . . . . :   00
+  Authority . . . . . . . . . . . . . . . . . . . . . :   *LIBCRTAUT
+  Replace file  . . . . . . . . . . . . . . . . . . . :   *YES
+  Text  . . . . . . . . . . . . . . . . . . . . . . . :
+  Compiler  . . . . . . . . . . . . . . . . . . . . . :   IBM System i5 Data Description Processor
+                                       Data Description Source
+  SEQNBR  *...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8  Date
+       1       A* Free Form Menu: MENU
+       2       A                                      DSPSIZ(24 80 *DS3                  -
+       3       A                                             27 132 *DS4)
+       4       A                                      CHGINPDFT
+       5       A                                      INDARA
+       6       A                                      PRINT(*LIBL/QSYSPRT)
+       7       A          R MENU
+ *                  CPD5235-.*********
+ *                  CPD8111-**********
+       8       A                                      DSPMOD(*DS3)
+       9       A                                      LOCK
+      10       A                                      SLNO(01)
+      11       A                                      CLRL(*ALL)
+ *                                            CPD8018-*
+      12       A                                      ALWROL
+ *                                            CPD8018-*
+      13       A                                      CF03
+      14       A                                      HELP
+      15       A                                      HOME
+      16       A                                      HLPRTN
+      17       A                                  1  2'MENU'
+      18       A                                      COLOR(BLU)
+      19       A                                  1 29'Agentic Coding Demo Menu'
+      20       A                                      DSPATR(HI)
+      21       A                                      COLOR(WHT)
+      22       A                                  3  2'Select one of the following:'
+      23       A                                      COLOR(BLU)
+      24       A                                  5  7'1. Work with Customers'
+      25       A                                  6  7'2. Work with Customers (RPGOA)'
+      26       A                                  7  7'3. Work with Customers (EJS)'
+      27       A                                  8  7'4. Go to PERP menu (PERPMNU)'
+      28       A                                 10  6'90. Sign off'
+      29       A* CMDPROMPT  Do not delete this DDS spec.
+      30       A                                021  2'Selection:                        -
+      31       A                                          '
+                          * * * * *   E N D   O F   S O U R C E   * * * * *
+  5770SS1 V7R5M0  220415                  Data Description               AITSK00019/MENU          8/23/26 16:28:31        Page    2
+                                           Expanded Source
+                                                                                           Field       Buffer position
+  SEQNBR  *...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 length        Out     In
+       2                                              DSPSIZ(24 80 *DS3                  -
+       2                                                     27 132 *DS4) CHGINPDFT +
+       5                                              INDARA PRINT(*LIBL/QSYSPRT)
+       7                  R MENU                      DSPMOD(*DS3) LOCK SLNO(01) +
+      11                                              CLRL(*ALL) ALWROL CF03 HELP HOME +
+      16                                              HLPRTN
+      17                                          1  2'MENU' COLOR(BLU)                        4
+      19                                          1 29'Agentic Coding Demo Menu' +            24
+      20                                              DSPATR(HI) COLOR(WHT)
+      22                                          3  2'Select one of the following:' +        28
+      23                                              COLOR(BLU)
+      24                                          5  7'1. Work with Customers'                22
+      25                                          6  7'2. Work with Customers (RPGOA)'        30
+      26                                          7  7'3. Work with Customers (EJS)'          28
+      27                                          8  7'4. Go to PERP menu (PERPMNU)'          28
+      28                                         10  6'90. Sign off'                          12
+      30                                         21  2'Selection:                        -    38
+      30                                                  '
+                  * * * * *   E N D   O F   E X P A N D E D   S O U R C E   * * * * *
+  5770SS1 V7R5M0  220415                  Data Description               AITSK00019/MENU          8/23/26 16:28:31        Page    3
+                                              Messages
+     ID      Severity  Number
+ * CPD5235      10        1      Message . . . . :   Record name same as name of file being created.
+ * CPD8018      10        2      Message . . . . :   Keyword may not function as expected with DSPMOD.
+ * CPD8111      10        1      Message . . . . :   Record may not function as expected.
+  5770SS1 V7R5M0  220415                  Data Description               AITSK00019/MENU          8/23/26 16:28:31        Page    4
+                                           Message Summary
+     Total          Informational          Warning        Error       Severe
+                        (0-9)              (10-19)       (20-29)      (30-99)
+         4                 0                    4             0            0
+ * CPC7301      00               Message . . . . :   File MENU created in library AITSK00019.
+                          * * * * *   E N D   O F   C O M P I L A T I O N   * * * * *

cfdemo/tmp/logs/menu.menu.log

@@ -0,0 +1 @@
+CPC9801:  Object MENU type *MENU created in library AITSK00019.

cfdemo/tmp/logs/menu.msgf.log

@@ -0,0 +1 @@
+CPC9801:  Object MENU type *MSGF created in library AITSK00019.

perp/.codermake/config.json

@@ -0,0 +1,10 @@
+{
+  "targetRelease": "V7R4M0",
+  "compileOptions": {
+    "crtbndrpg":  { "dbgview": "*all" },
+    "crtrpgmod":  { "dbgview": "*all" },
+    "crtsqlrpgi": { "dbgview": "*source" },
+    "crtbndcbl":  { "dbgview": "*all" },
+    "runsqlstm":  { "commit": "*none", "errlvl": "10" }
+  }
+}

perp/AGENTS.md

@@ -0,0 +1,89 @@
+# Instructions for Agents — PERP module
+
+This directory holds the **PreSales ERP (PERP)** module — a greenfield ERP
+demo playground built alongside `cfdemo/` in this repo.
+
+Tracked in Jira project **PERP**; design reference lives in Confluence page
+[PreSales ERP Development Project (PERP)](https://profoundlogicsupport.atlassian.net/wiki/spaces/CPP/pages/2511470593/).
+
+## Before touching anything
+
+Read **[DDL_STYLE_GUIDE.md](DDL_STYLE_GUIDE.md)** first. It sets the conventions
+for every table, index, view, and CL in this module. In particular:
+
+- One `.table.sql` file per table, snake_case
+- Explicit `FOR SYSTEM NAME` / `FOR COLUMN` on every table and column
+- Standard audit block on every table (`created_at/by`, `updated_at/by`, `is_active`)
+- FKs and CHECKs declared in DDL, not enforced in app code
+- Composite PKs with `company_code` leading on multi-tenant tables
+- All tables journaled from day one (see `qclsrc/perpjrn.clle`)
+- No `SET OPTION COMMIT = *NONE` in RPG — real commitment control against the
+  perp journal
+
+## Runtime-only gotchas that clean compiles won't catch
+
+Three gotchas on this environment routinely compile clean at severity 00
+and then crash at runtime on the first exercise. Always factor these in
+when adding a new RPG or SQLRPGLE program under `perp/qrpglesrc/`:
+
+- **`ctl-opt datfmt(*iso)` is mandatory for any program that touches
+  Date values.** The job DATFMT is `*MDY` (year range 1940-2039).
+  Without the ctl-opt override every RPG Date variable inherits that
+  narrow range as its storage format and any value outside it (a
+  `0001-01-01` sentinel, an SQL fetch of an out-of-range date, a DSPF
+  `L DATFMT(*ISO)` read) crashes with `RNQ0114`. Three-layer fix:
+  - Put `datfmt(*iso)` on `ctl-opt`.
+  - Parse every literal with `%date('yyyy-mm-dd' : *ISO)`.
+  - Keep any Date value that will be assigned to an SQL host variable
+    inside 1940-2039 (e.g. sentinels `1940-01-01`/`2039-12-31`) — the
+    SQL precompiler generates its intermediate host vars with the JOB
+    DATFMT and ignores `ctl-opt datfmt(*iso)`, so the SQL side stays
+    capped at *MDY even after the first two fixes.
+
+  Full analysis in `DDL_STYLE_GUIDE.md` §13. This bit every PO program
+  during PERP-7 and burned three round-trips before the third layer
+  landed — don't repeat.
+
+- **`%subst(varchar : 1 : N)` fails when `N > %len(current data)`, not
+  just when `N > declared max`.** A VARCHAR(20) column holding
+  `'OPEN'` (4 chars) can't answer `%subst(..., 1, 10)` — `RNQ0100`.
+  For "fit into a fixed-width display field", drop the `%subst` and
+  use direct assignment: RPG right-pads or truncates automatically.
+  Only reach for `%subst` when you actually need a middle slice, and
+  guard with `%min(%len(...), N)` when you do.
+
+- **`%editc(int : 'X')` produces hex, not decimal.** For displaying a
+  numeric doc-number as a plain string (PO number, requisition
+  number, line number), use `%char()`. `%editc` with `'X'` returns
+  the hex representation of the internal byte pattern — PERP-7's
+  first live browse rendered every PO number as `0000000000` before
+  this was caught.
+
+## Build target
+
+Objects build into the **`PERPDEMO`** library on IBM i. `PERPDEMO` is a
+shared demo library (not the per-task library) and has been created for this
+purpose. When you build from this module, point `IBMI_BUILD_LIBRARY` at
+`PERPDEMO` for these sources.
+
+Source physical files in `PERPDEMO` (all `RCDLEN(112)`):
+`QRPGLESRC`, `QDDSSRC`, `QSQLSRC`, `QCLSRC`, `QCMDSRC`, `QMENUSRC`, `QSRVSRC`,
+`QPNLSRC`.
+
+## Directory layout
+
+| Subdir       | Holds                                                          |
+|--------------|----------------------------------------------------------------|
+| `qddlsrc/`   | SQL DDL — `.table.sql`, `.index.sql`, `.view.sql`, `.proc.sql` |
+| `qrpglesrc/` | RPG ILE / SQLRPGLE programs and modules                        |
+| `qddssrc/`   | DDS — `.pf`, `.lf`, `.dspf`, `.prtf` (5250 baseline only)      |
+| `qclsrc/`    | CL / CLLE — library setup, journaling, hooks                   |
+| `.codermake/config.json` | Module-scoped compile options (adds `runsqlstm`)   |
+| `Rules.mk`   | Module build rules — always edit this, never the Makefile      |
+
+## Building
+
+Run `codermake` from the repo root as usual. The module-local
+`.codermake/config.json` layers on top of the repo-level one and adds the
+`runsqlstm` compile options used to build `.table.sql` / `.index.sql` /
+`.view.sql` / `.proc.sql` sources into `PERPDEMO`.