Error & Message Handling

These errors can be categorized as program-defined errors and system errors. Program-defined errors are those you anticipate and handle within your CL program, while system errors are unforeseen issues that may require system messages.

To Handle Errors and Messages in IBM i MONMSG and SNDPGMMSG are the basic command available.

The MONMSG command is a fundamental construct for error handling in CL programs. It is used to monitor specific messages and take actions when those messages occur.

In error handling, it is common to display error messages to the user and/or log them for later analysis. You can use the SNDPGMMSG command to send a message to the program message queue or display it on the user’s screen.

The SNDBRKMSG command can be used to send a break message, stopping program execution.

Error and message handling in CL programming are vital for creating robust applications on the IBM i platform. By effectively handling errors and providing informative messages, you can improve the reliability and maintainability of your programs.

In IBM i (formerly AS/400) CL programming, handling errors and messages is a critical part of ensuring the reliability and robustness of your programs. CL (Control Language) is a scripting language used on the IBM i platform to automate tasks and create programs.

MONMSG

In IBM i, the MONMSG (Monitor Message) command is used for error handling. It allows you to monitor for specific messages and take predefined actions when those messages are issued.

Below is an example and syntax with a detailed explanation of how to use MONMSG with an example:

Syntax of the MONMSG Command:

MONMSG MSGID (message-identifier) EXEC (command)

MSGID: This parameter specifies the message identifier you want to monitor for. we can specify a specific message identifier, a generic message identifier (using asterisks), or a message file name.

EXEC: This parameter specifies the command to execute if the monitored message is received. we can execute various commands, including GOTO, SNDPGMMSG or a custom program.

Example:

Let us think we have a CL (Control Language) program that processes files, and we want to handle any potential errors gracefully. we can use MONMSG like this:

PGM

/* Attempt to open a file */

OVRDBF FILE(INPUT) TOFILE(MYLIB/MYFILE) OVRSCOPE(*JOB)

/* Monitor for any file open errors */

MONMSG MSGID(CPF502B) EXEC(DO)

/* Display an error message */

SNDPGMMSG MSG('Error opening file MYLIB/MYFILE') +

MSGTYPE(*ESCAPE)

/* Handle the error, maybe by logging it and ending the program */

/* Add your error-handling logic here */

ENDDO

/* Continue processing if the file was opened successfully */

/* Add your file processing logic here */

/* Close the file */

DLTOVR FILE(INPUT)

ENDPGM

Description of example:

• The program attempts to open a file using the OVRDBF command.
• The MONMSG command is used to monitor for the specific message CPF502B, which is issued when there is an error opening a file. When this message is encountered, the program jumps to the DO block.
• Inside the DO block, an error message is sent using SNDPGMMSG, and we can add our custom error handling logic.
• After handling the error, we can either end the program or continue with additional processing logic.
• This is a basic example of how to use MONMSG for error handling in IBM i. we can customize it based on our specific requirements and the types of messages you want to monitor in your application.

SNDPGMMSG

In IBM i, the SNDPGMMSG command is used to send a program message to a user or message queue. It is commonly used for error handling and reporting. You can find below a detailed explanation of error handling using SNDPGMMSG with an example.

SNDPGMMSG Command Syntax:

SNDPGMMSG MSG(‘Your message text’) TOUSR(UserProfile) MSGTYPE(*DIAG) MSGDTA(‘Message data’)

MSG: Specifies the message text.

TOUSR: Specifies the user profile to send the message to.

MSGTYPE: Specifies the message type. Use *DIAG for diagnostic messages (common for errors).

MSGDTA: Specifies additional message data.

Example of Error Handling using SNDPGMMSG:

Let’s say, we have a CL program that performs some operations and needs to handle errors by sending messages. Here’s an example:

/* Sample CL Program */

/* Declare variables */

DCL VAR(&ERROR) TYPE(*LGL) VALUE(‘0’) /* Initialize error flag to false */

/* Perform some operations */

/* … */

/* Check for an error condition */

IF (&SOME_CONDITION) THEN

CHGVAR VAR(&ERROR) VALUE(‘1’) /* Set error flag to true */

SNDPGMMSG MSG(‘An error occurred’) TOUSR(USER123) MSGTYPE(*DIAG)

GOTO CMDLBL(ERROR_HANDLING)

ENDIF

/* More operations */

/* Error Handling Label */

ERROR_HANDLING:

IF (&ERROR *EQ ‘1’) THEN

SNDPGMMSG MSG(‘Error Handling: Processing stopped due to an error) TOUSR(USER123) MSGTYPE(*DIAG)

ENDPGM /* Terminate the program */

ENDIF

/* Program continues if no error */

ENDPGM         /* End of program */

Description of  example:

• We declare a variable &ERROR to track whether an error occurred (initially set to ‘0’ for false).
• After performing some operations, we check for a condition (&SOME_CONDITION) that could indicate an error. If the condition is met, we set &ERROR to ‘1’ and send a diagnostic message using SNDPGMMSG.
• We use a label (ERROR_HANDLING) to handle errors. If &ERROR is set to ‘1’, we send an error message and terminate the program.
• If no error occurred, the program continues its execution, and eventually, it ends gracefully.
• This is a simplified example, and in a real-world scenario, you would have more detailed error handling and possibly log messages to a message queue for further analysis. The SNDPGMMSG command is just one part of error handling on IBM I, and you can customize it further based on your specific needs.

Example:

Usages :

Error handling and message handling are essential aspects of CL programming on IBM i for the following reasons:

Program Reliability: Error handling helps ensure the reliability of your CL programs by allowing you to detect and respond to unexpected conditions or errors. This helps prevent program crashes or unexpected behaviour.

User Feedback: Message handling allows you to communicate with users or operators by sending messages. This can be used to provide feedback, instructions, or warnings, making your programs more user-friendly.

Diagnostic Information: Messages often contain diagnostic information that can be valuable for troubleshooting and debugging. When an error occurs, capturing and logging messages can aid in identifying the root cause.

Graceful Program Termination: Proper error handling ensures that a program terminates gracefully, releasing any acquired resources and cleaning up after itself. This is crucial for maintaining system stability.

Conditional Processing: By monitoring specific messages (e.g., CPF messages for errors), you can implement conditional processing in your CL programs. For example, you might want to take different actions depending on the type of error encountered.

Logging and Auditing: You can log messages to keep a record of program activities, errors, or significant events. This log can be useful for auditing and tracking program behaviour over time.

Interaction with Other Programs: CL programs often interact with other programs or processes. Proper error handling ensures that the calling program or process can respond appropriately to errors raised by the called program.

In summary, error handling and message handling in CL programming on IBM i are crucial for ensuring program reliability, providing feedback to users, diagnosing issues, and maintaining overall system stability.

They enable you to create robust and user-friendly applications on this platform.

Restrictions :

Limited Error Information: CL programs primarily handle messages, and the information provided in messages may be limited. To access more detailed error information, you may need to rely on APIs or interact with other system components.

Message Queue Limitations: Messages are typically sent to message queues, and there may be limitations on the number of messages that can be held in a queue. If the queue becomes full, new messages may be lost.

Message IDs: When using the MONMSG command to monitor for specific messages, you need to know the message IDs in advance. If IBM i introduces new message IDs in future releases, your monitoring may need updates.

Resource Locking: Error handling should be cautious when dealing with resource locks, as improper handling can lead to resource contention issues.

Compatibility Considerations :

IBM I Versions: Error handling and message handling techniques in CL programming are generally consistent across different versions of IBM i, but there might be slight variations or enhancements in newer releases. It is a good practice to check the documentation specific to your IBM i version for any updates or changes.

Message Queue Types: IBM i supports different types of message queues, including program message queues and message queues associated with user profiles. The choice of message queue type can impact how messages are handled and accessed.

Message Queues in Subsystems: When working with subsystems, you need to consider how message queues are managed within the subsystem environment. Subsystem configurations can affect how messages are routed and monitored.

User Profile Settings: User profile settings, such as message queue authorities and message queue monitoring settings, can affect the behaviour of error handling and message handling in CL programs.

Library Lists: Ensure that any message files or message descriptions used in your CL programs are accessible through the library list of the job running the program.

Message File Changes: If you update or change message files or message descriptions, be aware of the potential impact on your CL programs that rely on those messages.

Message Text Language: Consider the language settings of message descriptions and message files. Messages may be presented in different languages based on user or system preferences.

It is important to keep these restrictions and compatibility considerations in mind when designing and maintaining error handling and message handling in IBM i CL programs. Staying informed about system updates and best practices is crucial for effective error and message management.