Panel Validation, Return Codes, and Message Handling

Panel validation ensures that user input meets requirements before processing. Return codes indicate how panels were exited, and message handling provides feedback to users. Understanding validation, return codes, and messages is essential for creating robust ISPF panels. This tutorial covers input validation techniques, return code handling, message display, and best practices.

Effective panel validation prevents errors and improves user experience. Return codes enable proper flow control, and messages provide clear feedback. Learning these concepts helps you create professional, user-friendly panels. This tutorial provides practical guidance for validation and error handling.

Understanding Panel Validation

Panel validation checks input before processing.

What is Panel Validation?

Panel validation is:

• Checking user input for correctness
• Ensuring required fields are filled
• Verifying data formats
• Validating value ranges
• Checking data relationships

Validation Location

Validation is performed in:

• )PROC Section: Primary validation location
• Executes when user presses Enter
• Checks variable values
• Sets error messages if validation fails

Input Validation Techniques

Various techniques for validating panel input.

Required Field Validation

Check that required fields are filled:

1
2
3
4
5
6
7
8
9
10
11
)PROC
  IF (&ZDSN = '') +
    DO
      .MSG = 'Dataset name is required'
      .RC = 8
    END
  ELSE +
    DO
      /* Continue processing */
    END
)END

This checks if ZDSN is empty and sets an error message if so.

Format Validation

Validate data formats:

• Check dataset name format
• Validate numeric values
• Verify date formats
• Check character patterns

Example format validation:

1
2
3
4
5
6
)PROC
  IF (&ZDSN = '') +
    .MSG = 'Dataset name required'
  IF (SUBSTR(&ZDSN,1,1) < 'A' | SUBSTR(&ZDSN,1,1) > 'Z') +
    .MSG = 'Dataset name must start with letter'
)END

Range Validation

Validate value ranges:

• Check numeric ranges
• Verify acceptable values
• Validate against limits

Multiple Field Validation

Validate multiple fields:

1
2
3
4
5
6
7
8
9
10
)PROC
  IF (&ZDSN = '') +
    .MSG = 'Dataset name required'
  IF (&ZMEM = '') +
    .MSG = 'Member name required'
  IF (&ZDSN <> '' & &ZMEM <> '') +
    DO
      /* All validations passed */
    END
)END

Return Codes

Return codes indicate panel exit conditions.

Understanding Return Codes

Return codes indicate:

• How the user exited the panel
• Whether processing should continue
• Error conditions
• User actions taken

Common Return Codes

Common return codes:

• 0: User pressed Enter (continue)
• 4: User pressed PF3/End (cancel)
• 8: Error condition
• 12: Severe error
• Other codes for specific conditions

Setting Return Codes

Return codes are set using:

• .RC variable in )PROC
• Automatically by ISPF based on user action
• Based on validation results
• To control panel flow

Example setting return code:

1
2
3
4
5
6
7
8
9
)PROC
  IF (&ZDSN = '') +
    DO
      .MSG = 'Dataset name required'
      .RC = 8
    END
  ELSE +
    .RC = 0
)END

Message Handling

Messages provide feedback to users.

Displaying Messages

Messages are displayed using:

• .MSG variable in )PROC
• Shown when panel redisplay
• Can be error, warning, or informational
• Provides user feedback

Error Messages

Error messages indicate problems:

1
2
3
4
5
6
)PROC
  IF (&ZDSN = '') +
    .MSG = 'Error: Dataset name is required'
  IF (&ZMEM = '') +
    .MSG = 'Error: Member name is required'
)END

Informational Messages

Informational messages provide guidance:

1
2
3
4
)PROC
  IF (&ZCMD = '') +
    .MSG = 'Enter a command or press PF3 to exit'
)END

Success Messages

Success messages confirm actions:

1
2
3
4
5
6
7
)PROC
  IF (&ZCMD = 'S') +
    DO
      .MSG = 'Operation completed successfully'
      .RC = 0
    END
)END

Validation Patterns

Common validation patterns for panels.

Required Field Pattern

Standard required field validation:

1
2
3
4
5
6
7
)PROC
  IF (&FIELD = '') +
    DO
      .MSG = 'Field name is required'
      .RC = 8
    END
)END

Format Validation Pattern

Format validation example:

1
2
3
4
5
6
)PROC
  IF (LENGTH(&ZDSN) < 3) +
    .MSG = 'Dataset name too short'
  IF (INDEX(&ZDSN,'.') = 0) +
    .MSG = 'Dataset name must contain period'
)END

Multiple Validation Pattern

Validating multiple conditions:

1
2
3
4
5
6
7
8
9
10
11
12
)PROC
  &ERROR = ''
  IF (&ZDSN = '') +
    &ERROR = 'Dataset name required; '
  IF (&ZMEM = '') +
    &ERROR = &ERROR || 'Member name required'
  IF (&ERROR <> '') +
    DO
      .MSG = &ERROR
      .RC = 8
    END
)END

Return Code Handling

Handling return codes in applications.

Checking Return Codes

In REXX, check return codes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/*REXX*/
address ispexec
'DISPLAY PANEL(MYPANEL)'
if rc = 0 then do
  /* User pressed Enter, continue */
end
else if rc = 4 then do
  /* User cancelled */
  exit 0
end
else do
  /* Error condition */
  say 'Error: RC=' rc
  exit 8
end

Return Code Meanings

Understanding return code meanings:

• 0: Success, continue processing
• 4: User cancelled, exit gracefully
• 8: Error, handle error condition
• 12: Severe error, abort processing

Best Practices

Following best practices improves validation quality:

• Validate Early: Validate input as soon as possible
• Clear Messages: Provide clear, specific error messages
• Validate All Required Fields: Check all required fields
• Set Appropriate Return Codes: Use correct return codes
• Handle All Cases: Handle all possible return codes
• Test Validation: Test validation with various inputs
• Provide Helpful Messages: Messages should guide users
• Validate Consistently: Use consistent validation patterns

Explain Like I'm 5: Panel Validation

Think of panel validation like checking homework:

• Validation is like checking your homework before you turn it in. You make sure you answered all the questions, wrote your name, and everything looks correct. If something is wrong, you fix it before turning it in. It's like having a checklist to make sure everything is right!
• Return Codes are like the grade or result you get. If everything is correct (return code 0), you can continue. If you cancelled (return code 4), you stopped working. If there's an error (return code 8), something needs to be fixed. It's like getting a result that tells you what happened!
• Messages are like notes from the teacher. If something is wrong, the teacher writes a note explaining what needs to be fixed. If everything is good, you might get a "good job" note. It's like getting feedback that tells you what to do!
• Validation Process is like the teacher checking your homework. The teacher looks at each answer, checks if it's correct, and writes notes if something is wrong. If everything is good, you get to continue. If something is wrong, you need to fix it. It's like having someone check your work before you can move on!

So panel validation is like having a teacher check your homework, give you a result (return code), and write notes (messages) to help you fix anything that's wrong!

Practice Exercises

Complete these exercises to reinforce your validation skills:

Exercise 1: Basic Validation

Practice basics: add basic validation to a panel, check required fields, set error messages, test validation, and learn basic validation. Master basic validation.

Exercise 2: Format Validation

Practice format: add format validation to a panel, validate data formats, test format checks, and learn format validation. Master format validation.

Exercise 3: Return Code Handling

Practice return codes: handle different return codes, test return code handling, understand return code meanings, and learn return code handling. Master return code handling.

Exercise 4: Message Handling

Practice messages: display different message types, test message display, understand message usage, and learn message handling. Master message handling.

Exercise 5: Complete Validation

Practice complete: implement complete validation with multiple checks, handle all return codes, provide comprehensive messages, and learn complete validation. Master complete validation.

Related Concepts