When writing a Control Language Program (CLP) on IBM i (AS400), various CL commands are embedded within the program to interact with the system, manage processes, and communicate with users. Unlike some external commands like CRTCLPGM used for compiling programs, the commands used within a CLP program are designed to perform specific tasks during execution. In this article, we will cover essential commands typically used inside CLP programs, focusing on their purpose and practical usage in program flow.
Here are the basic CL commands we'll explore:
- WRKOBJ (Work with Objects)
- RUNSQLSTM (Run SQL Statements)
- SNDPGMMSG (Send Program Message)
- SNDMSG (Send Message)
- MONMSG (Monitor Message)
1. WRKOBJ (Work with Objects)
WRKOBJ is primarily an interactive command but can also be useful within CL programs when combined with object-checking commands such as CHKOBJ or DSPOBJD to verify the existence or state of system objects like files, programs, and libraries.
Usage in CLP Program
In CLP programs, you generally use commands like CHKOBJ to verify the existence of objects (which might be part of a pre-check step in your CLP), but you can use WRKOBJ outside of program control. Here's how CHKOBJ could work in place of WRKOBJ in a CLP program:
Syntax: CHKOBJ
CHKOBJ OBJ(LIBRARY/OBJECT) OBJTYPE(*FILE)
Example in CLP:
PGM /* Check if the object exists */ CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE) MONMSG MSGID(CPF9801) EXEC(DO) /* If file does not exist, send a message and terminate */ SNDPGMMSG MSG('File MYFILE not found in MYLIB') TOPGMQ(*EXT) RETURN ENDDO /* If object exists, continue with further operations */ SNDPGMMSG MSG('Object found, proceeding') TOPGMQ(*EXT) /* Continue program logic */ ENDPGM
This example demonstrates how to check whether a file (MYFILE) exists in a specific library. If it doesn't, the program sends a message and stops further execution using the RETURN command. This is a basic and essential technique when working with objects within CLP programs.
2. RUNSQLSTM (Run SQL Statements)
The RUNSQLSTM command is used to execute SQL statements stored in a source member. SQL provides powerful capabilities for interacting with the database, and when you need to incorporate database manipulations within a CLP program, SQL statements can be called using RUNSQLSTM.
Syntax
RUNSQLSTM SRCFILE(LIBRARY/SOURCEFILE) SRCMBR(SOURCEMEMBER)
Example in CLP:
Let’s assume you need to update a database file in the middle of a CLP program. You could store the SQL command in a source member and call it from the CLP:
PGM /* Pre-checks and other logic */ /* Run an SQL statement to update records */ RUNSQLSTM SRCFILE(MYLIB/QSQLSRC) SRCMBR(UPDREC) SNDPGMMSG MSG('SQL statement executed successfully') TOPGMQ(*EXT) /* Further program logic */ ENDPGM
In this example, the SQL statement is stored in the source member UPDREC in the source physical file QSQLSRC. This technique is especially useful when working with complex SQL operations such as updates, inserts, or creating database objects directly from within a CLP program.
3. SNDPGMMSG (Send Program Message)
SNDPGMMSG is one of the most important commands used in CLP programs. It allows you to send messages to the external message queue or job log, which is crucial for informing users or operators about the status of the program. It replaces the deprecated DSPLY statement.
Syntax
SNDPGMMSG MSG('message text') TOPGMQ(*EXT)
Example in CLP:
PGM DCL VAR(&USERID) TYPE(*CHAR) LEN(10) /* Retrieve the current user profile */ RTVJOBA USER(&USERID) /* Send a message to the job log */ SNDPGMMSG MSG('Hello ' *CAT &USERID *TCAT ', Welcome!') TOPGMQ(*EXT) /* Continue with program execution */ ENDPGM
In this example, the program retrieves the current user profile using the RTVJOBA command and then sends a personalized message to the message queue using SNDPGMMSG. This is a practical way to send feedback to the user during execution.
4. SNDMSG (Send Message)
The SNDMSG command is used to send messages to other users or system operators. While SNDPGMMSG sends messages to the job log or message queue, SNDMSG communicates directly with users on the system, making it ideal for sending notifications.
Syntax
SNDMSG MSG('message text') TOUSR(user or group)
Example in CLP:
PGM /* Backup completed, notify the system administrator */ SNDMSG MSG('Backup process for MYLIB completed successfully.') TOUSR(SYSADMIN) /* Continue with further operations */ ENDPGM
In this example, once a task (such as a backup) is completed, the program sends a notification to the system administrator (SYSADMIN). This is a common pattern in CLP programs that handle system maintenance or batch processing.
5. MONMSG (Monitor Message)
MONMSG is used to monitor for specific errors or exceptions that occur during the execution of a command in a CLP program. When a monitored condition occurs (e.g., a missing object or failed operation), the program can handle the error gracefully by performing alternative actions, logging the error, or even terminating the process.
Syntax
MONMSG MSGID(message ID) EXEC(command or block of commands)
Example in CLP:
PGM /* Try to perform an operation */ DLTF FILE(MYLIB/MYFILE) MONMSG MSGID(CPF2105) EXEC(DO) /* If file not found, send a message */ SNDPGMMSG MSG('File not found, cannot delete') TOPGMQ(*EXT) ENDDO /* Continue with further operations */ ENDPGM
In this example, the program attempts to delete a file (DLTF), and if the file is not found (message ID CPF2105), the program handles the error by sending a message to the external message queue using SNDPGMMSG. MONMSG is critical in CLP programs to ensure smooth error handling.
Practical Example: Combining Commands in a CLP Program
Let’s now combine all these commands into a single, simple CLP program. This program checks for an object, runs an SQL statement, handles errors, and sends appropriate messages to both the job log and users.
PGM DCL VAR(&OBJEXISTS) TYPE(*CHAR) LEN(10) /* Check if the object exists */ CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE) MONMSG MSGID(CPF9801) EXEC(DO) /* Object not found, send message */ SNDPGMMSG MSG('File MYFILE not found') TOPGMQ(*EXT) RETURN ENDDO /* If object exists, run SQL statement */ RUNSQLSTM SRCFILE(MYLIB/QSQLSRC) SRCMBR(UPDREC) MONMSG MSGID(SQLxxxx) EXEC(DO) /* Handle SQL errors */ SNDPGMMSG MSG('SQL execution failed') TOPGMQ(*EXT) RETURN ENDDO /* Notify user of successful completion */ SNDMSG MSG('MYLIB processing complete') TOUSR(SYSADMIN) ENDPGM
Explanation:
- CHKOBJ checks whether the file
MYFILEexists in the libraryMYLIB. - RUNSQLSTM executes an SQL statement stored in the source member
UPDREC. - MONMSG captures any errors from the commands, sending appropriate messages.
- SNDPGMMSG sends feedback to the job log, and SNDMSG notifies the system administrator when the process is completed.
Conclusion
The commands discussed—CHKOBJ, RUNSQLSTM, SNDPGMMSG, SNDMSG, and MONMSG—are fundamental to CL programming within IBM i. These commands allow for robust error handling, database manipulation, and user communication, all within a CLP program. Mastering these basic commands will enable you to write effective, efficient, and error-tolerant CL programs that interact with the system and users in meaningful ways.
In the next article, we will explore more advanced commands and techniques to expand your CL programming toolkit. Stay tuned!
