CL programming essentials: jobs, commands, and error handling

Control Language (CL) is how you drive the system from code: set up the job, point files at the right library, call programs, submit batch work, and react when something fails. I have seen RPG programs bloated with logic that belonged in a 20-line CL wrapper. This article covers the CL you need to write that wrapper properly.

  1. Program shape and variables: PGM, DCL and ENDPGM
  2. Control flow: IF, DOFOR, DOWHILE, SELECT
  3. Calling programs: CALL and parameter types
  4. Overriding files: OVRDBF and DLTOVR
  5. Batch work: RTVJOBA and SBMJOB
  6. Error handling: MONMSG and SNDPGMMSG
  7. Compile: CRTBNDCL

What CL is for (and what RPG is for)

Use CL for orchestration: library lists, overrides, job attributes, calling programs, submitting jobs, sending messages, and monitoring errors. Use RPG (or SQL) for business logic, record processing, and calculations. CL can read files and do arithmetic, but it is clumsy at both. If you are writing a loop with ten CHGVARs over a file, it belongs in RPG.

Every CL command you type at a command line works inside a CL program. That is the whole appeal: what you learn interactively is what you automate.

Program shape and variables

A CL program starts with PGM and ends with ENDPGM. All DCL statements must come before any executable statement.

PGM PARM(&LIB) DCL VAR(&LIB) TYPE(*CHAR) LEN(10) DCL VAR(&COUNT) TYPE(*DEC) LEN(5 0) VALUE(0) DCL VAR(&OK) TYPE(*LGL) VALUE('0') CHGVAR VAR(&COUNT) VALUE(&COUNT + 1) ENDPGM 

Variables start with &. Types are *CHAR, *DEC, *LGL ('1'/'0') and a few others. Parameters passed in must be declared with matching type and length, or the values arrive garbled.

Control flow

Source type is CLLE, which has no column rules, so you can indent, use one command per line, and write keywords in lowercase if you prefer. Modern CL is just disciplined layout.

IF COND(&COUNT *GT 10) THEN(DO) CHGVAR VAR(&COUNT) VALUE(0) ENDDO ELSE CMD(CHGVAR VAR(&COUNT) VALUE(&COUNT + 1)) DOFOR VAR(&I) FROM(1) TO(5) /* runs five times */ ENDDO DOWHILE COND(&COUNT *LT 3) CHGVAR VAR(&COUNT) VALUE(&COUNT + 1) ENDDO SELECT WHEN COND(&LIB *EQ 'PRODLIB') THEN(CHGVAR VAR(&OK) VALUE('1')) WHEN COND(&LIB *EQ 'TESTLIB') THEN(DO) CHGVAR VAR(&OK) VALUE('1') ENDDO OTHERWISE CMD(CHGVAR VAR(&OK) VALUE('0')) ENDSELECT 

Declare the DOFOR counter first, for example DCL VAR(&I) TYPE(*INT). Comparisons use *EQ, *NE, *GT, *LT (symbols like = also work). SELECT/WHEN replaced the old nested-IF-with-GOTO style; use it.

Calling programs and passing parameters

CALL PGM(MYLIB/CUSTRPT) PARM(&LIB &RC) 

CALL passes parameters by reference, with no type checking. A character literal is passed at its exact length ('TESTLIB' is 7 bytes, not 10), and a numeric literal arrives as packed 15,5. Both are classic reasons RPG sees garbage: the program reads 10 bytes where only 7 were passed, or gets a packed 15,5 where it expected something else. Declare variables and pass those instead. RPG side: dcl-pi *n; lib char(10); rc char(1); end-pi;.

Overriding files

OVRDBF redirects a program's file reference without recompiling.

OVRDBF FILE(CUSTPF) TOFILE(&LIB/CUSTPF) MBR(*FIRST) CALL PGM(CUSTRPT) DLTOVR FILE(CUSTPF) 

In a program running in the default activation group (what CRTBNDCL gives you unless you change it), an override lasts for the call level that issued it, so it disappears when the CL ends. From any other activation group the default scope is the activation group. OVRSCOPE(*JOB) extends it to the whole job; avoid that unless you mean it. Embedded SQL only honours a short list of OVRDBF parameters (see IBM's "Running a program with embedded SQL: Override considerations"), so do not count on OVRDBF to redirect SQL; use a qualified name or an alias. Overrides are reliable for RPG file I/O.

Job information and batch work

RTVJOBA reads the job's own attributes.

DCL VAR(&JOB) TYPE(*CHAR) LEN(10) DCL VAR(&USER) TYPE(*CHAR) LEN(10) DCL VAR(&NBR) TYPE(*CHAR) LEN(6) DCL VAR(&TYPE) TYPE(*CHAR) LEN(1) RTVJOBA JOB(&JOB) USER(&USER) NBR(&NBR) TYPE(&TYPE) 

&TYPE is '0' for batch and '1' for interactive, so you can branch on how you were started. SBMJOB runs a command in a separate batch job:

SBMJOB CMD(CALL PGM(MYLIB/CUSTRPT) PARM('TESTLIB ' ' ')) JOB(CUSTRPT) JOBQ(QBATCH) 

The CMD text is stored as a string and run later, so literals work, but the character-literal rule above still applies: the example pads 'TESTLIB' to 10 characters because CUSTRPT declares char(10). Variables are not resolved at run time, they are substituted when you submit. With the defaults (INLLIBL(*CURRENT)) the submitted job gets a copy of your current library list. If you want the library list from the job description instead, say INLLIBL(*JOBD). A job that depends on libraries that only exist in your interactive session is the usual reason a batch job works when you run it by hand but fails when submitted.

Error handling: MONMSG

When a command fails it sends an escape message to your program. If you do not monitor it, the job posts an inquiry message and waits, which means an inquiry message in interactive jobs and a job waiting for a reply in batch. MONMSG catches it.

MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(ERROR)) 

Placed right after PGM/declarations (before any command), this is a global monitor: it covers every command in the program that has no more specific monitor. Placed directly after one command, it is a command-level monitor for just that command, and takes priority.

DLTF FILE(QTEMP/WORK) MONMSG MSGID(CPF2105) /* file not found: ignore */ 

Catch specific ids first where you have a planned reaction, and use CPF0000 as a safety net. CPF0000 is a generic range meaning any CPFxxxx message. MCH0000 covers machine errors, and CPF9999 is the function check you get when an error was not monitored. Keep the ids precise; do not blanket-ignore.

Message Meaning
CPF2105 File not found
CPF2110 Library not found
CPF9801 Object not found
CPF9802 Not authorized to object
CPF9898 Generic text-only message

MONMSG only sees escape, notify and status messages. Completion and diagnostic messages cannot be monitored. Look at the command's help (F1 on the command, or IBM Docs) for the escape messages it can send.

To signal failure to your caller, send a message. SNDPGMMSG with MSGTYPE(*ESCAPE) ends your program with an error that the caller can monitor. To reach your caller, add TOPGMQ(*PRV); the default *SAME sends the message to your own program queue.

SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA('Report failed for ' *CAT &LIB) + TOPGMQ(*PRV) MSGTYPE(*ESCAPE) 

CPF9898 is the generic "text only" message: it displays whatever you put in MSGDTA. Use MSGTYPE(*INFO) for progress notes and *COMP for success.

A complete example

This program overrides a file, calls an RPG program, and handles errors. The RPG program is assumed to return '0' in &RC on success.

PGM PARM(&LIB) DCL VAR(&LIB) TYPE(*CHAR) LEN(10) DCL VAR(&RC) TYPE(*CHAR) LEN(1) VALUE('0') DCL VAR(&MSG) TYPE(*CHAR) LEN(80) MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(ERROR)) OVRDBF FILE(CUSTPF) TOFILE(&LIB/CUSTPF) CALL PGM(MYLIB/CUSTRPT) PARM(&LIB &RC) DLTOVR FILE(CUSTPF) IF COND(&RC *NE '0') THEN(DO) CHGVAR VAR(&MSG) VALUE('CUSTRPT returned code ' *CAT &RC) GOTO CMDLBL(ERROR) ENDDO SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) + MSGDTA('CUSTRPT finished for ' *CAT &LIB) MSGTYPE(*COMP) RETURN ERROR: DLTOVR FILE(CUSTPF) MONMSG MSGID(CPF0000) IF COND(&MSG *EQ ' ') THEN(CHGVAR VAR(&MSG) VALUE('CUSTRPT failed, see job log')) SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA(&MSG) + TOPGMQ(*PRV) MSGTYPE(*ESCAPE) ENDPGM 

Note the + continuation character, RETURN to skip the error block, and cleanup of the override on both paths.

Compiling

Put the source in a source member of type CLLE (for example QCLSRC) and compile:

CRTBNDCL PGM(MYLIB/CUSTCL) SRCFILE(MYLIB/QCLSRC) SRCMBR(CUSTCL) 

CRTBNDCL creates a program in one step. Use SRCSTMF('/home/me/custcl.clle') instead if the source lives in the IFS, which suits VS Code and Git workflows. Compile errors are in the spooled listing or, in VS Code, in the problems panel.

Try it on PUB400

  1. Sign on to PUB400 and create QCLSRC with CRTSRCPF FILE(YOURLIB/QCLSRC) RCDLEN(112).
  2. Add a member HELLOCL of type CLLE with a small program that calls RTVJOBA and sends the result with SNDPGMMSG ... MSGTYPE(*COMP).
  3. Compile with CRTBNDCL, then CALL it and read the message with DSPMSG or DSPJOBLOG.
  4. Break it deliberately: DLTF FILE(NOSUCHFILE) with and without a MONMSG, and watch the difference.

Best resources

Next

Next: SQLRPGLE: embedded SQL done properly

Related

Originally published on rainierio.dev. The full Learn IBM i track, with an Indonesian version, is at rainierio.dev/learn.