Easytrieve Screen Messages

Kinds of Messages

Not all messages serve the same purpose, and treating them the same confuses operators. Three broad categories cover most needs. Error messages report that something must be fixed before the program can proceed. Confirmation messages reassure the operator that an action succeeded. Status or informational messages describe the current state, such as which page of a list is showing. Deciding which category a message belongs to shapes both its wording and its appearance.

The Message Field

A screen message is just the value of a field you defined for that purpose—call it SCR-MSG. You paint it on the screen as a protected output field on a reserved line so it does not collide with data fields. During processing you move text into SCR-MSG, and the runtime displays whatever it holds on the next paint. Because it is an ordinary field, all the output handling rules apply: it keeps its last value until you change it, so managing it carefully across cycles is essential.

Setting Messages in AFTER-SCREEN

AFTER-SCREEN is where you learn the outcome of the operator's input, so it is where most messages originate. Validation failures set an error message; successful updates set a confirmation. Set the message as close as possible to the decision that produced it, so the wording matches the exact condition.

1
2
3
4
5
6
7
8
9
10
AFTER-SCREEN. PROC
   IF ACCT-NO EQ SPACES
      SCR-MSG = 'ACCOUNT NUMBER REQUIRED'
   ELSE IF NOT NUMERIC(ACCT-NO)
      SCR-MSG = 'ACCOUNT MUST BE NUMERIC'
   ELSE
      PERFORM UPDATE-ACCOUNT
      SCR-MSG = 'ACCOUNT UPDATED SUCCESSFULLY'
   END-IF
END-PROC

Clearing Messages in BEFORE-SCREEN

A message that lingers after its cause is gone is misleading. If BEFORE-SCREEN does not clear SCR-MSG, the operator might fix an error yet still see the old error text, or see a stale success message on an unrelated screen. The rule is to clear the message at the start of each cycle in BEFORE-SCREEN, then let AFTER-SCREEN set a new one only when there is something to say.

1
2
3
4
BEFORE-SCREEN. PROC
   PERFORM LOAD-DISPLAY
   SCR-MSG = SPACES
END-PROC

There is a subtlety worth understanding. AFTER-SCREEN runs, sets a message, and then on the next display BEFORE-SCREEN runs before the operator sees anything. If BEFORE-SCREEN blindly clears the message, the operator would never see it. The common resolution is that the message set in AFTER-SCREEN is intended for the very next display, and clearing happens at the top of the cycle that follows the operator reading it. In practice you set the message last in AFTER-SCREEN and clear it early in BEFORE-SCREEN of the subsequent cycle, so each message shows exactly once. If your release's flow differs, trace one cycle carefully to confirm messages appear for the operator and then disappear.

Writing Messages Operators Understand

The difference between a helpful screen and a frustrating one is often just wording. A good message states what is wrong and what to do, and where possible names the field. Compare INVALID INPUT—which tells the operator nothing—with ACCOUNT MUST BE NUMERIC, which points straight to the fix. Keep messages short enough to fit the message line, use consistent terminology, and avoid internal jargon or raw return codes the operator cannot interpret.

Distinguishing Message Types Visually

Wording is not the only signal. On terminals that support it, use attributes to distinguish categories at a glance: high intensity or red for errors, normal or green for confirmations. Keep the scheme consistent across every screen so operators learn that red means stop and fix. Do not rely on color alone, because some terminals and operators cannot distinguish it—pair color with clear text so the message works in monochrome too.

Messages and Cursor Positioning Together

A message and a cursor are a team. When validation fails, set the error message and record the field that failed so BEFORE-SCREEN can place the cursor there. The operator reads ACCOUNT MUST BE NUMERIC and finds the cursor already resting on the account field. This pairing is the single most effective error-handling pattern in online programming, turning correction into a one-step action.

1
2
3
4
5
6
7
8
9
AFTER-SCREEN. PROC
   IF NOT NUMERIC(ACCT-NO)
      SCR-MSG     = 'ACCOUNT MUST BE NUMERIC'
      ERROR-FIELD = 'ACCT-NO'
   ELSE
      ERROR-FIELD = SPACES
      PERFORM LOOKUP-ACCOUNT
   END-IF
END-PROC

Testing Screen Messages

1. Trigger each validation error and confirm the specific message appears.
2. Fix the error and confirm the message clears rather than lingering.
3. Complete a successful action and confirm the confirmation message shows once.
4. Check that error and confirmation messages are visually distinct.
5. Verify each error message pairs with the cursor on the correct field.

Common Message Mistakes

• Vague text like ERROR or INVALID that gives no guidance.
• Never clearing the message, so old text lingers after the cause is gone.
• Showing raw return codes instead of human-readable explanations.
• Messages too long for the message line, getting truncated.
• Relying on color alone with no distinguishing text.
• Setting a message but forgetting to position the cursor on the related field.

Explain It Like I'm Five

Screen messages are like sticky notes the computer puts on your worksheet. If you make a mistake, it sticks a red note saying exactly what to fix, like write numbers here, not letters. If you do it right, it sticks a happy note saying good job, saved. Before giving you a fresh worksheet it peels off the old note so you are not confused by yesterday's. The best notes tell you both what went wrong and how to fix it, not just a scary word like wrong.

Exercises

1. Write three specific error messages that name the field and the fix.
2. Add message clearing to BEFORE-SCREEN and explain why it belongs there.
3. Rewrite a weak message like INVALID into an actionable one.
4. Pair an error message with cursor positioning on the failing field.
5. Design a consistent color/intensity scheme for errors versus confirmations.