Generating a report from an IBM i CL program isn’t straightforward, because in CL there is no direct way to write to a spool file. This article provides the Print Line (PRTLN) command, which allows simple, direct printing from a CL or CLLE program, including page control and headings.

Sometimes it's just convenient to print directly from CL, and that's where the PRTLN command is handy. The CL language wasn’t designed to create reports—report writing is a strength of RPG. You can, of course, create Query/400 or QMQRY objects and then call them from a CL program to produce a report, but then you have extra objects to manage.

If you Google "ibm i printing from cl" you will find suggested techniques such as:

• Using QSH and rfile
• Writing to a temporary file with SQL followed by a CPYF to a printer
• Using the C language printf function

Not everyone is comfortable with QSH and/or C language functions, and a native IBM i command that you can prompt, like PRTLN, is more desirable.

The PRTLN Command

The PRTLN command allows you to:

• Print a line to a spool file with single, double, or triple spacing, or overprinting.
• Define zero to nine heading lines that print on overflow.
• Print a page number in a heading line.
• Force a new page if you want break-handling.

Fully prompted, the PRTLN command looks like this:

Figure 1: Fully prompted PRTLN command

Line text

Specifies the text to print on this line, or if defining a header line, specifies the text of that header line.

Line spacing

Specifies the spacing of the printed line or the header line. (S1: Space 1 line and print; S2: Space 2 lines and print; S3: Space 3 lines and print; S0: Overprint previous line.)

Defining heading line?

Y means this is a header line definition.

Header line number

Specifies which heading line is being defined, 1 through 9.

• Heading lines can be defined in any sequence. For example, you can define heading 9, then define heading 1, then define heading 3, etc.
• Heading lines always print in ordinal order, not the order in which they were defined.
• A heading line that is not defined does not print.
• A heading line may be defined with blank text and will print a blank heading line.
• Once defined, a heading line cannot be undefined.
• A heading line may be redefined at any time and will take effect at the next page break. Normally, you would force a page break after redefining a heading line.

Include page number

Y to print a page number in the rightmost 8 positions of this header line.

Non-printing control functions

These are operations that are not related to printing a line or defining headings.

• *NEWPAGE forces a new page when the next line prints. (Page overflow and header printing is handled automatically, so you need to use this only if you have break-handling logic in your program or if you want to print totals or a message at the end of the report.)  
• *CLOSE closes the print file. Normally, you do this at the end of the report, but you can use it to create a new spool file.

Formatting the Print Line

In a previous article, I showed how easily RPG can format print line columns using a data structure. CL doesn't have data structures, but they can be simulated using the STG(*DEFINED) and DEFVAR parameters of the DCL command. This is much simpler than building the print line through concatenation.

As an example, you can define a print line with three columns like this:

    DCL (&LINE)  (*CHAR) LEN(132)

    DCL (&LIB)   (*CHAR) STG(*DEFINED) LEN(10) DEFVAR(&LINE)

    DCL (&FILE)  (*CHAR) STG(*DEFINED) LEN(10) DEFVAR(&LINE 12)

    DCL (&MBR)   (*CHAR) STG(*DEFINED) LEN(10) DEFVAR(&LINE 33)

Then you just need to populate the line using the column names.

PRTLN Example

Here's a simple program to demonstrate the concepts. It prints a really simple report.

PGM

DCL   (&LC)    (*DEC) LEN(5 0) VALUE(1)

DCL   (&UNDER) (*CHAR) LEN(20) VALUE('____________________')

/* Define print line and columns */

DCL   (&LINE)  (*CHAR)  LEN(132)

DCL   (&COUNT) (*CHAR) STG(*DEFINED) LEN(5) DEFVAR(&LINE 5)

DCL   (&STAMP) (*CHAR) STG(*DEFINED) LEN(20) DEFVAR(&LINE 20)

/* Define heading 1 */

PRTLN  LINE('Really Simple Report') HEADING(Y) HEAD(1 Y)

/* Define heading 2 */

CHGVAR &COUNT 'COUNT'

CHGVAR &STAMP 'TIMESTAMP'

PRTLN  LINE(&LINE) HEADING(Y) HEAD(2)

/* Define heading 3, underscoring heading 2 */

CHGVAR &COUNT &UNDER

CHGVAR &STAMP &UNDER

PRTLN  LINE(&LINE) SPACE(S0) HEADING(Y) HEAD(3)

/* Print a report showing count and timestamp */

DOWHILE COND(&LC *LT 70)

    CHGVAR &COUNT %CHAR(&LC)

    RTVSYSVAL SYSVAL(QDATETIME) RTNVAR(&STAMP)

     PRTLN   LINE(&LINE)

    CHGVAR   VAR(&LC) VALUE(&LC + 1)

ENDDO

PRTLN CONTROL(*CLOSE)

ENDPGM

It produces a two-page report like this:

Figure 2: The "Really Simple" report

The Code

The code behind the PRTLN command can be downloaded from here, or it can be inspected or downloaded from my GITHUB repository.

Following is an overview of the source members.

PRTLN.CMD

This is the source for the PRTLN command.

PRTLNCV.CLLE

This is the Validity Checking Program (VCP) for the PRTLN command. A VCP is optional and can be used to do parameter validity checking that is difficult or impossible in standard command definition source. When used, it receives the same parameters as the CCP and can pass back error messages to the command. It is used here to ensure that nonprinting CONTOL functions don't also try to print a line or define a heading.

PRTLNC.CLLE

This is the Command Processing Program (CPP). A CPP is called when there are no errors in the command. Here, it reformats the parameter from the command to pass to the PRT program.

PRT.RPGLE

This is an RPG/FREE program that does the heavy lifting. It saves heading lines in an array, takes care of opening and closing the print file, and prints headings on overflow.

It writes to the MYPRINT printer file, which is defined like this:

    CRTPRTF FILE(LENNONS1/MYPRT) DEVTYPE(*SCS)

            PAGESIZE(66 133) LPI(6) CPI(10)

             OVRFLW(60) CTLCHAR(*FCFC) CHLVAL((1 (6)))

             FONT(*CPI)

Adjust the overflow or top of form line to suit your needs.

PRT can also be called directly bypassing the PRTLN command, for example, from an RPG program. Full details of its two parameters and a sample RPG program can be found in my GITHUB repository.

PRTLNP.PNLGRP

This is the UIM help text for the PRTLN command. I created a skeleton using the IBM GENCMDDOC command and then edited it with the Code for IBM i extension to VS Code.

Conclusion

For something complicated, like payroll checks or month-end general ledger, don't do it from CL; use RPG. But for a simple report, the PRTLN command can be used to create it directly from a CL program.

Sam Lennon is an analyst, developer, consultant and IBM i geek. He started his programming career in 360 assembly language on IBM mainframes, but moved to the AS400 platform in 1991 and has been an AS400/iSeries/i5/IBM i advocate ever since.