Skip to content

COMEN01C

Source: cbl/COMEN01C.cbl

Type: CICS transaction program

COMEN01C — Main Menu Program (Regular Users)

Purpose

COMEN01C implements the main menu screen for regular (non-admin) users of the CardDemo application. It displays a list of available menu options, validates the user's selection, and transfers control (XCTL) to the target program associated with the chosen option. It also enforces basic access control, preventing regular users from selecting admin-only options.

How it works

Processing is driven by MAIN-PARA, which behaves differently depending on whether the program is being entered fresh or re-entered from a previous transaction:

  • First entry (EIBCALEN = 0): No commarea exists yet, so the program sets CDEMO-FROM-PROGRAM to COSGN00C and performs RETURN-TO-SIGNON-SCREEN, sending control back to the sign-on program. This suggests COMEN01C expects to always be entered with a commarea from the sign-on flow; a direct/cold start is treated as an error path back to sign-on.
  • Re-entry with commarea: The incoming commarea is copied into CARDDEMO-COMMAREA.
  • If this is the first pass for this session (NOT CDEMO-PGM-REENTER), the reentry flag is set, the output map is initialized to LOW-VALUES, and SEND-MENU-SCREEN is performed to display the menu for the first time.
  • Otherwise, RECEIVE-MENU-SCREEN reads the user's input from the terminal, and EIBAID (the key pressed) is evaluated:
    • ENTER → PROCESS-ENTER-KEY validates and processes the selected menu option.
    • PF3 → sets CDEMO-TO-PROGRAM to COSGN00C and performs RETURN-TO-SIGNON-SCREEN (log off back to sign-on).
    • Any other key → sets the error flag, shows an "invalid key" message, and redisplays the menu via SEND-MENU-SCREEN.

PROCESS-ENTER-KEY extracts the option number typed by the user, right-justifies it, and pads blanks with '0'. It then: 1. Validates the option is numeric, non-zero, and within CDEMO-MENU-OPT-COUNT. 2. Checks the option's user-type restriction (CDEMO-MENU-OPT-USRTYPE) against the caller's type; if the user is a regular user (CDEMO-USRTYP-USER) and the option is admin-only ('A'), access is denied. 3. If validation passes, it evaluates the target program name for the selected option: - If the program is COPAUS0C, it first issues EXEC CICS INQUIRE PROGRAM (with NOHANDLE) to check the program is installed before doing an XCTL. If not found, it shows a "not installed" message in red. - If the program name starts with DUMMY, it shows a "coming soon" message in green instead of transferring control (placeholder/unimplemented options). - Otherwise, it sets CDEMO-FROM-TRANID/CDEMO-FROM-PROGRAM, clears CDEMO-PGM-CONTEXT, and performs an unconditional XCTL to the target program, passing the commarea along. 4. After the EVALUATE, SEND-MENU-SCREEN is performed again to redisplay the menu (relevant when an error/message occurred or when the XCTL falls through, e.g. for the DUMMY/not-installed cases).

SEND-MENU-SCREEN performs POPULATE-HEADER-INFO (title, date/time, transaction/program name) and BUILD-MENU-OPTIONS (formats each menu entry as "<num>. <name>" into fields OPTN001O–OPTN012O), then sends the COMEN1A map from mapset COMEN01 with ERASE.

RECEIVE-MENU-SCREEN reads the COMEN1A map input into COMEN1AI using RESP/RESP2 (response codes captured but, notably, not checked afterward).

Finally, MAIN-PARA always ends with EXEC CICS RETURN TRANSID(WS-TRANID) COMMAREA(CARDDEMO-COMMAREA), keeping the user in a pseudo-conversational loop on transaction CM00 until they navigate away via XCTL.

Inputs & outputs

Resource Type Purpose
DFHCOMMAREA (CARDDEMO-COMMAREA) CICS commarea (linkage section) Carries session/navigation state between programs: reentry flag, from/to program & transaction, menu option table (CDEMO-MENU-OPT-*), user type, and program context. Passed in and out via RETURN/XCTL.
Map COMEN1A / mapset COMEN01 BMS screen (via COMEN1AI/COMEN1AO) Terminal I/O: displays header (title, date/time, tran/pgm name), 12 menu option lines (OPTN001O–OPTN012O), and error message (ERRMSGO); receives the typed option number (OPTIONI).
Copybook COCOM01Y Working storage Common CardDemo commarea layout (likely defines CARDDEMO-COMMAREA, CDEMO-* fields, user-type flags).
Copybook COMEN02Y Working storage Menu option table definitions (CDEMO-MENU-OPT-*: name, program name, user-type restriction, count).
Copybook COMEN01 Working storage Map layout for COMEN1A (COMEN1AI/COMEN1AO fields).
Copybook COTTL01Y Working storage Title constants (CCDA-TITLE01/02).
Copybook CSDAT01Y Working storage Date/time layout used for header (WS-CURDATE-*, WS-CURTIME-*).
Copybook CSMSG01Y Working storage Standard message constants (e.g., CCDA-MSG-INVALID-KEY).
Copybook CSUSR01Y Working storage User-related fields (referenced, but the two WS-USER-ID/SEC-USR-TYPE moves are commented out — see below).
Copybooks DFHAID, DFHBMSCA Working storage CICS standard AID key and BMS attribute constants.
Target programs (COSGN00C, COPAUS0C, others via CDEMO-MENU-OPT-PGMNAME) Called via XCTL Sign-on program and business-function programs invoked from the menu. No static CALLs — all navigation is dynamic CICS XCTL based on table-driven program names.

No SQL tables and no batch files are used — this is a pure CICS/BMS transaction program (matches parser facts: empty sql_tables/files).

Things to know

  • Cold-start handling: An EIBCALEN = 0 entry (no commarea) is treated as invalid and simply routes the user back to COSGN00C, rather than displaying an error — worth confirming this is the intended behavior for direct transaction entry (e.g., typing CM00 at a blank screen).
  • Unchecked RECEIVE response: RECEIVE-MENU-SCREEN captures RESP/RESP2 into WS-RESP-CD/WS-REAS-CD but the code never inspects them afterward — a mapfail or other error from the RECEIVE is silently ignored, which could lead to processing on stale/empty input data.
  • Hard-coded program names: COSGN00C (sign-on) and COPAUS0C are hard-coded literals in the logic. COPAUS0C gets special treatment (an INQUIRE PROGRAM existence check before XCTL) that no other option receives — an inconsistency worth noting for maintainers, since other options assume the target program is always present.
  • DUMMY-prefixed programs: Any menu option whose program name starts with DUMMY is treated as a "coming soon" placeholder and never actually XCTL'd — this is a naming convention baked into the code rather than a flag, so renaming a placeholder program without the DUMMY prefix would change behavior.
  • Dead/commented-out code: In PROCESS-ENTER-KEY, the lines MOVE WS-USER-ID TO CDEMO-USER-ID and MOVE SEC-USR-TYPE TO CDEMO-USER-TYPE are commented out, meaning user ID/type are not refreshed into the commarea before XCTL in the "OTHER" (normal) branch — the called program relies on whatever was already set in the commarea from a prior program.
  • Input parsing quirk: The option number is derived by scanning OPTIONI backward for the last non-space character, then right-justifying and replacing remaining spaces with '0' via INSPECT. This means a single blank input could become "00" and correctly fail numeric/zero validation, but the logic is easy to misread and worth double-checking against edge cases (e.g., partially blank input).
  • Access control is table-driven but coarse: Admin-only restriction is a simple single-character check (CDEMO-MENU-OPT-USRTYPE(WS-OPTION) = 'A') combined with CDEMO-USRTYP-USER; the actual user-type values and menu table contents live in copybooks (COMEN02Y, COCOM01Y) not shown here, so full validation logic can't be confirmed from this source alone.
  • Fixed 12-option limit: BUILD-MENU-OPTIONS only handles menu positions 1–12 (OPTN001O–OPTN012O) via a hard-coded EVALUATE; any CDEMO-MENU-OPT-COUNT greater than 12 would silently fall to WHEN OTHER … CONTINUE and not be displayed.
  • Transaction ID hard-coded: WS-TRANID is fixed to 'CM00' and used both for the RETURN TRANSID and for setting CDEMO-FROM-TRANID — no dynamic lookup.

CICS commands

RETURN, INQUIRE, XCTL, SEND, RECEIVE

Copybooks

COCOM01Y, COMEN01, COMEN02Y, COTTL01Y, CSDAT01Y, CSMSG01Y, CSUSR01Y, DFHAID, DFHBMSCA

Paragraph flow

flowchart TD
    MAIN_PARA["MAIN-PARA"]
    PROCESS_ENTER_KEY["PROCESS-ENTER-KEY"]
    RETURN_TO_SIGNON_SCREEN["RETURN-TO-SIGNON-SCREEN"]
    SEND_MENU_SCREEN["SEND-MENU-SCREEN"]
    RECEIVE_MENU_SCREEN["RECEIVE-MENU-SCREEN"]
    POPULATE_HEADER_INFO["POPULATE-HEADER-INFO"]
    BUILD_MENU_OPTIONS["BUILD-MENU-OPTIONS"]
    MAIN_PARA --> PROCESS_ENTER_KEY
    MAIN_PARA --> RECEIVE_MENU_SCREEN
    MAIN_PARA --> RETURN_TO_SIGNON_SCREEN
    MAIN_PARA --> SEND_MENU_SCREEN
    PROCESS_ENTER_KEY --> SEND_MENU_SCREEN
    SEND_MENU_SCREEN --> BUILD_MENU_OPTIONS
    SEND_MENU_SCREEN --> POPULATE_HEADER_INFO

Paragraphs

Paragraph Line Performs
MAIN-PARA 75 RETURN-TO-SIGNON-SCREEN, SEND-MENU-SCREEN, RECEIVE-MENU-SCREEN, PROCESS-ENTER-KEY, RETURN-TO-SIGNON-SCREEN, SEND-MENU-SCREEN
PROCESS-ENTER-KEY 115 SEND-MENU-SCREEN, SEND-MENU-SCREEN, SEND-MENU-SCREEN
RETURN-TO-SIGNON-SCREEN 196
SEND-MENU-SCREEN 208 POPULATE-HEADER-INFO, BUILD-MENU-OPTIONS
RECEIVE-MENU-SCREEN 225
POPULATE-HEADER-INFO 238
BUILD-MENU-OPTIONS 262