Skip to content

COUSR02C

Source: cbl/COUSR02C.cbl

Type: CICS transaction program

COUSR02C — Update User

Purpose

This is a CICS BMS (screen-based) program in the CardDemo mainframe application that lets an administrator update an existing user's details (first name, last name, password, and user type) in the security file (USRSEC). It is part of the user-administration subsystem, invoked from COADM01C (or reached from a sign-on flow) and returns to the calling program when the operator is done.

How it works

  1. MAIN-PARA is the entry point for every CICS invocation of the transaction (CU02).
  2. If EIBCALEN = 0 (program invoked with no commarea), it treats this as an error/direct-start condition, sets the return target to COSGN00C, and performs RETURN-TO-PREV-SCREEN immediately.
  3. Otherwise it copies the incoming commarea into CARDDEMO-COMMAREA.
    • First entry (NOT CDEMO-PGM-REENTER): initializes the output map, and if a user ID was already passed in via CDEMO-CU02-USR-SELECTED (e.g., selected from a prior user-list screen), it pre-loads that ID and performs PROCESS-ENTER-KEY to look the user up automatically, then sends the screen (SEND-USRUPD-SCREEN).
    • Subsequent entries (re-entrant, screen already sent): receives the operator's input (RECEIVE-USRUPD-SCREEN) and dispatches based on the AID key pressed:
    • ENTER → PROCESS-ENTER-KEY (look up the user by ID entered).
    • PF3 → UPDATE-USER-INFO, then navigates back to the calling program (CDEMO-FROM-PROGRAM, defaulting to COADM01C) via RETURN-TO-PREV-SCREEN.
    • PF4 → CLEAR-CURRENT-SCREEN (reset all input fields).
    • PF5 → UPDATE-USER-INFO (save changes but stay on screen).
    • PF12 → returns to COADM01C via RETURN-TO-PREV-SCREEN without saving.
    • Any other key → sets an error flag/message ("Invalid key pressed") and redisplays the screen.
  4. PROCESS-ENTER-KEY validates that a User ID was entered; if not, flags an error and redisplays. Otherwise it clears the display fields, moves the entered ID into SEC-USR-ID, and performs READ-USER-SEC-FILE to fetch the current record, then repopulates the screen fields with the retrieved name/password/type and redisplays.
  5. UPDATE-USER-INFO validates that User ID, First Name, Last Name, Password, and User Type are all non-blank (each failure sets an error and redisplays immediately). If validation passes, it re-reads the user record (READ-USER-SEC-FILE) and compares each field to the values on screen; any difference sets USR-MODIFIED-YES. If something actually changed, it performs UPDATE-USER-SEC-FILE to persist the change; otherwise it displays "Please modify to update..." without writing.
  6. READ-USER-SEC-FILE issues a CICS READ on the USRSEC file with UPDATE (for later rewrite), and branches on the response: NORMAL (record found — shows a "press PF5 to save" prompt), NOTFND (shows "User ID NOT found"), or any other response (shows "Unable to lookup User" and logs RESP/REAS via DISPLAY).
  7. UPDATE-USER-SEC-FILE issues a CICS REWRITE and similarly branches: NORMAL (confirms with a green "User XXXX has been updated..." message), NOTFND, or OTHER (generic failure with logged RESP/REAS).
  8. CLEAR-CURRENT-SCREEN / INITIALIZE-ALL-FIELDS blank all input fields and the message line and redisplay the screen.
  9. SEND-USRUPD-SCREEN always performs POPULATE-HEADER-INFO (title, transaction/program name, current date/time) before sending the COUSR2A map from mapset COUSR02.
  10. RETURN-TO-PREV-SCREEN defaults the target program to COSGN00C if none is set, stamps the commarea with this program's tran ID/name as the "from" info, resets CDEMO-PGM-CONTEXT, and performs an XCTL to hand off control.
  11. Control always ends with EXEC CICS RETURN TRANSID('CU02') COMMAREA(...), making the transaction pseudo-conversational (state is round-tripped via the commarea between screen interactions).

Inputs & outputs

Name Type Purpose
USRSEC VSAM file (CICS dataset, hard-coded name WS-USRSEC-FILE = 'USRSEC ') Stores user security records (ID, first/last name, password, user type). Read with UPDATE option and rewritten to persist edits.
DFHCOMMAREA / CARDDEMO-COMMAREA CICS commarea (linkage section, up to 32767 bytes) Carries cross-program state: reentry flag, from/to program & tranid, and the selected user ID (CDEMO-CU02-USR-SELECTED) passed in from a prior screen (e.g., a user list).
COUSR2A map / COUSR02 mapset BMS screen (SEND/RECEIVE) The user-update screen: displays/collects User ID, First Name, Last Name, Password, User Type, and an error/status message line.
Copybooks: COCOM01Y, COTTL01Y, COUSR02, CSDAT01Y, CSMSG01Y, CSUSR01Y, DFHAID, DFHBMSCA Working-storage layouts COCOM01Y = common commarea layout; COUSR02 = map layout (COUSR2AI/COUSR2AO); CSUSR01Y = security file record layout (SEC-USER-DATA, SEC-USR-ID, etc.); CSMSG01Y = standard message text (e.g., CCDA-MSG-INVALID-KEY); CSDAT01Y = date/time working fields; COTTL01Y = screen title constants; DFHAID/DFHBMSCA = CICS AID key and attribute constants.
No SQL tables — This program does not use DB2/SQL; all persistence is via the USRSEC CICS file.

Things to know

  • No SQL access — despite being part of "CardDemo," this program is pure CICS file I/O (VSAM USRSEC), not DB2.
  • Hard-coded values: transaction ID 'CU02', program name 'COUSR02C', dataset name 'USRSEC ', default fallback programs 'COSGN00C' (no commarea / no from-program) and 'COADM01C' (default caller for PF3/PF12).
  • Error handling is response-code driven but generic: any non-NORMAL/NOTFND response from READ or REWRITE falls into a catch-all OTHER branch that just displays "Unable to lookup/Update User..." and logs WS-RESP-CD/WS-REAS-CD via DISPLAY (goes to CICS transient log, not visible to the operator) — no distinct handling for e.g. record-locked or duplicate conditions.
  • "No changes" is treated as a soft warning, not an error — if PF5/PF3 is pressed but none of the four fields actually changed, the record is not rewritten; the user just sees "Please modify to update...".
  • Double-read pattern: the record is read once in PROCESS-ENTER-KEY (to populate the screen) and read again in UPDATE-USER-INFO before rewriting — this second read also uses UPDATE, which holds a lock on the VSAM record until the following REWRITE/READ completes; if the rewrite is skipped (no changes), the lock is presumably released by CICS at sync point/return, but no explicit UNLOCK is issued in the "no changes" path.
  • Screen-driven control flow relies on CDEMO-PGM-REENTER in the commarea to distinguish first-time invocation from a post-screen-send re-entry — a classic CICS pseudo-conversational pattern; if the commarea is corrupted or missing this flag, behavior could misfire (e.g., re-triggering the initial branch).
  • Field-level validation order in UPDATE-USER-INFO is sequential (User ID → First Name → Last Name → Password → User Type) with only the first failing field reported per submission — the user may need multiple round trips to satisfy all validations.
  • The password field is handled as plain text (SEC-USR-PWD) with no evident masking/encryption logic in this program — worth flagging for any security review.
  • The PF3 path performs UPDATE-USER-INFO (which may fail validation and redisplay the same screen) but the code unconditionally proceeds to RETURN-TO-PREV-SCREEN afterward regardless of whether the update succeeded or an error flag was set — meaning PF3 could exit the screen even when validation failed and nothing was saved. Worth confirming this is intended behavior rather than a bug, since PF5 (save-and-stay) does not exhibit this same exit behavior.

CICS commands

RETURN, SEND, RECEIVE, READ, REWRITE

Copybooks

COCOM01Y, COTTL01Y, COUSR02, CSDAT01Y, CSMSG01Y, CSUSR01Y, DFHAID, DFHBMSCA

Paragraph flow

flowchart TD
    MAIN_PARA["MAIN-PARA"]
    PROCESS_ENTER_KEY["PROCESS-ENTER-KEY"]
    UPDATE_USER_INFO["UPDATE-USER-INFO"]
    RETURN_TO_PREV_SCREEN["RETURN-TO-PREV-SCREEN"]
    SEND_USRUPD_SCREEN["SEND-USRUPD-SCREEN"]
    RECEIVE_USRUPD_SCREEN["RECEIVE-USRUPD-SCREEN"]
    POPULATE_HEADER_INFO["POPULATE-HEADER-INFO"]
    READ_USER_SEC_FILE["READ-USER-SEC-FILE"]
    UPDATE_USER_SEC_FILE["UPDATE-USER-SEC-FILE"]
    CLEAR_CURRENT_SCREEN["CLEAR-CURRENT-SCREEN"]
    INITIALIZE_ALL_FIELDS["INITIALIZE-ALL-FIELDS"]
    CLEAR_CURRENT_SCREEN --> INITIALIZE_ALL_FIELDS
    CLEAR_CURRENT_SCREEN --> SEND_USRUPD_SCREEN
    MAIN_PARA --> CLEAR_CURRENT_SCREEN
    MAIN_PARA --> PROCESS_ENTER_KEY
    MAIN_PARA --> RECEIVE_USRUPD_SCREEN
    MAIN_PARA --> RETURN_TO_PREV_SCREEN
    MAIN_PARA --> SEND_USRUPD_SCREEN
    MAIN_PARA --> UPDATE_USER_INFO
    PROCESS_ENTER_KEY --> READ_USER_SEC_FILE
    PROCESS_ENTER_KEY --> SEND_USRUPD_SCREEN
    READ_USER_SEC_FILE --> SEND_USRUPD_SCREEN
    SEND_USRUPD_SCREEN --> POPULATE_HEADER_INFO
    UPDATE_USER_INFO --> READ_USER_SEC_FILE
    UPDATE_USER_INFO --> SEND_USRUPD_SCREEN
    UPDATE_USER_INFO --> UPDATE_USER_SEC_FILE
    UPDATE_USER_SEC_FILE --> SEND_USRUPD_SCREEN

Paragraphs

Paragraph Line Performs
MAIN-PARA 82 RETURN-TO-PREV-SCREEN, PROCESS-ENTER-KEY, SEND-USRUPD-SCREEN, RECEIVE-USRUPD-SCREEN, PROCESS-ENTER-KEY, UPDATE-USER-INFO
PROCESS-ENTER-KEY 143 SEND-USRUPD-SCREEN, READ-USER-SEC-FILE, SEND-USRUPD-SCREEN
UPDATE-USER-INFO 177 SEND-USRUPD-SCREEN, SEND-USRUPD-SCREEN, SEND-USRUPD-SCREEN, SEND-USRUPD-SCREEN, SEND-USRUPD-SCREEN, READ-USER-SEC-FILE
RETURN-TO-PREV-SCREEN 250
SEND-USRUPD-SCREEN 266 POPULATE-HEADER-INFO
RECEIVE-USRUPD-SCREEN 283
POPULATE-HEADER-INFO 296
READ-USER-SEC-FILE 320 SEND-USRUPD-SCREEN, SEND-USRUPD-SCREEN, SEND-USRUPD-SCREEN
UPDATE-USER-SEC-FILE 358 SEND-USRUPD-SCREEN, SEND-USRUPD-SCREEN, SEND-USRUPD-SCREEN
CLEAR-CURRENT-SCREEN 395 INITIALIZE-ALL-FIELDS, SEND-USRUPD-SCREEN
INITIALIZE-ALL-FIELDS 403