AS/400-iSeries Starter Kit

There is certainly nothing mysterious about printing on your AS/400; however, you must understand a few basic concepts about print files to make printing operations run more smoothly. In this chapter, I cover two items concerning print files: modifying attributes of print files and handling a specific type of print file -- the system-generated job log. This basic understanding of how to define print files and job logs and of the functions they provide will increase your power to customize your system by controlling output. These tips are especially helpful if you have migrated from the S/36 or equipment other than the S/38.

How Do You Make It Print Like This?

The AS/400 does support direct printing (i.e., output directly to the printer, which ties up a workstation or job while the printer device completes the task); however, almost 100 percent of the time you will use OS/400 print files to format and direct output. IBM ships the system with many print files, such as QSYSPRT, which the system uses when you compile a CL program; QSUPPRT, which the system uses when you print a listing from the source file; and QQRYPRT, which the system uses when you run a query. These print files have predefined attributes that control such features as lines per inch (LPI), characters per inch (CPI), form size, overflow line number, and output queue.

In addition to the print files IBM provides, you can create two types of print files within your applications. The first type uses the CRTPRTF (Create Print File) command to define a print file that has no external definition (i.e., the print file has a set of defined attributes from the CRTPRTF command but only one record format). Any program using this type of print file must contain output specifications that describe the fields, positions, and edit codes used for printing.

The second type of print file is externally described: When you use the CRTPRTF command, you specify a source member that describes the various record formats your program will use for printing. (For specifications you can make in DDS, refer to IBM's Data Management Guide (SC41-9658).) Whether you create an externally described print file or a print file that must be used with programs that internally describe the printing, you define certain print file attributes (e.g., those controlling LPI, CPI, and form size) as part of the print file object definition.

Let's examine a problem that often occurs when an AS/400 installation is complete. All the IBM-supplied print files are predefined for use with paper that is 11 inches long. If you have been using paper that is shorter (e.g., the 14 1/2-by-8 1/2-inch size) and generate output (using DSPLIB OUTPUT(*PRINT) or a QUERY/400 report) with a system-supplied print file, the system will print the report through the page perforations. On your previous system, the overflow worked just right, but you weren't around when someone set the system up. So how do you instruct the AS/400 to print correctly on the short, wide paper?

First, you need to find out what the default values for printing are. To do so, you type in the DSPFD (Display File Description) command for the print file QSYSPRT:

DSPFD QSYSPRT

When you execute that command, you see the display represented in Figure 9.1. Notice the page size parameter, PAGESIZE(66 132); the LPI parameter, LPI(6); and the overflow parameter, OVRFLW(60). These default parameters combine to determine the number of inches (i.e., 11) the system considers to be a single page on the system-supplied objects.

But in this example, your paper is only 8 1/2 inches long, so you need to modify the form size and overflow of each print file (including all system-supplied print files and those you create yourself) that generates reports on this short-stock paper. You can accomplish this task by identifying each print file that needs to be modified and executing the following command for each:

CHGPRTF FILE(library_name/file_name) PAGESIZE(51 132)  +
        OVRFLW(45)

If you need to change all print files on the system, you can execute the same command, but place the value *ALL in the parameter FILE:

CHGPRTF FILE(*ALL/*ALL) PAGESIZE(51 132) OVRFLW(45)

Another approach is to change the LPI parameter to match a valid number of lines per inch for the configured printer and then calculate the new form size and overflow parameters based on the new LPI you specified. The page size can vary from one form type to the next, but you can easily compensate for differences by modifying the appropriate print files. Remember that changing the LPI, the page length, and the overflow line number does not require programming changes for programs that let the system check for overflow status (i.e., you do not need to have program logic count lines to control page breaks). Such programs use the new attributes of the print file at the next execution.

Once you have set up the page size you want and determined how a given job will print, you can start thinking about controlling when that job will print. The two parameters you can use to ensure that spooled data is printed at the time you designate are SCHEDULE and HOLD.

The SCHEDULE parameter specifies when to make the spooled output file available to a writer for printing. If the system finds the *IMMED value for SCHEDULE, the file is available for a writer to begin printing the data as soon as the records arrive in the spooled file. This approach can be advantageous for short print items, such as invoices, receipts, or other output that is printed quickly. However, when you generate long reports, allocating the writer as soon as data is available can tie up a single writer for a long time.

Entering a *FILEEND value for SCHEDULE specifies that the spooled output file is available to the writer as soon as the print file is closed in the program. Selecting this value can be useful for long reports you want available for printing only after the entire report is generated.

The *JOBEND value for SCHEDULE makes the spooled output file available only after the entire job (not just a program) is completed. One benefit of selecting this value is that you can ensure that all reports one job generates will be available at the same time and therefore will be printed in succession (unless the operator intervenes).

The HOLD parameter works the way the name sounds. Selecting a value of *YES specifies that when the system generates spooled output for a print file, the output file stays on the output queue with a *HLD status until an operator releases the file to a writer.

Selecting the *NO value for HOLD specifies that the system should not hold the spooled print file on the output queue and should make the output available to a writer at the time the SCHEDULE parameter indicates. For example, when a program generates a spooled file with the attributes of SCHEDULE(*FILEEND) and HOLD(*NO), the spooled file is available to the writer as soon as the file is closed.

As with the PAGESIZE and OVRFLW parameters, you can modify the SCHEDULE and HOLD parameters for print files by using the CHGPRTF command. Remember that you can also override these parameters at execution time using the CL OVRPRTF (Override with Print File) command. You can also change some print file attributes at print time using the CHGSPLFA (Change Spool File Attributes) command or option 2 on the Work with Output Queue display. You should examine the various attributes associated with the CRTPRTF (Create Print File), CHGPRTF, and OVRPRTF commands to see whether or not you need to make other changes to customize your printed output needs. For further reading on these parameters, see the discussion of the CRTPRTF command in IBM's Programming: Control Language Reference (SC41-0030).

Where Have All the Job Logs Gone?

After you have your print files under control, the next step in customizing your system can prick a nasty thorn in the flesh of AS/400 newcomers: learning how to manage all those job logs the system generates as jobs are completed. A job log is a record of the job execution and contains informational, completion, diagnostic, and other messages. The reason these potentially useful job logs can be a pain is that the AS/400 generates a job log for each completed job on the system.

But fortunately, you can manage job logs. The three methods for job-log management are controlling where the printed output for the job log is directed, deciding whether to generate a printed job log for jobs that are completed normally or only for jobs that are completed abnormally, and determining how much information to include in the job logs.

Controlling where the printed output is directed. When your system is shipped, it is set up so that every job (interactive sessions as well as batch) generates a job log that records the job's activities and that can vary in content according to the particular job description. You can use the DSPJOB (Display Job) or the DSPJOBLOG (Display Job Log) command to view a job log as the system creates it during the job's execution.

When a job is completed, the system spools the job log to the system printer unless you change print file QUSRSYS/QPJOBLOG (the print file the system uses to generate job logs) to redirect spool files to another output queue where they can stay for review or printing. You can elect to redirect this job log print file in one of two ways.

The most popular method is to utilize the OS/400-supplied Operational Assistant, which will not only redirect your job logs to a single output queue, but also perform automatic cleanup of old job logs based on a number of retention days, which you supply. You can access the system cleanup option panel from the Operational Assistant main menu (type "GO ASSIST"), from the SETUP menu (type "GO SETUP"), or directly by typing "GO CLEANUP," which will present you with the Cleanup Menu panel that you see in Figure 9.2. Before starting cleanup, you need to define the appropriate cleanup options by selecting option 1, "Change cleanup options." Figure 9.3 presents the Change Cleanup Options panel, where you can enter the retention parameters for several automated cleanup functions as well as determine at what time you want the system to perform cleanup each day. You can find a complete discussion of this panel and automated cleanup in Chapter 12, "AS/400 Disk Storage Cleanup."

For now, my only point is this: The first time you activate the automated cleanup function by typing a "Y" in the "Allow automatic cleanup" option on this panel (see Figure 9.3), OS/400 changes the job log print file so that all job logs are directed to the system-supplied output queue QEZJOBLOG. Even if you do not start the actual cleanup process, or if you elect to stop the cleanup function at a later date, the job logs will continue to accumulate in output queue QEZJOBLOG.

The second method for redirecting job logs is to manually create an output queue called QJOBLOGS, JOBLOGS, or QPJOBLOG using the CRTOUTQ (Create Output Queue) command.

After creating an output queue to hold the job logs, you can use the CHGPRTF command (with OUTQ identifying the output queue you created for this purpose) by typing

CHGPRTF FILE(QPJOBLOG) OUTQ(QUSRSYS/output queue_name)

Now the job logs will be redirected to the specified output queue. You might also want to specify HOLD(*YES) to place the spool files on hold in your new output queue. However, if no printer is assigned to that queue, those spool files will not be printed. The job logs can now remain in that queue until you print or delete them.

When you think about managing job logs, you should remember that if you let job logs accumulate, they can reduce the system's performance efficiency because of the overhead for each job on the system. If a job log exists, the system is maintaining information concerning that job. Therefore it is important either to utilize the automated cleanup options available in OS/400's Operational Assistant or to manually use the CLROUTQ (Clear Output Queue) command regularly to clear all the job logs from an output queue.

Deciding whether or not to generate a printed job log for jobs that are completed normally. Another concern related to the overhead involved with job logs is how to control their content (size) and reduce the number of them the system generates. The job description you use for job initiation is the object that controls the creation and contents of the job log. This job description has a parameter with the keyword LOG, which has three elements -- the message level and the message severity, both of which control the number of messages the system writes to a job log; and the message text level, which controls the level (i.e., amount) of message text written to the job log when the first two values create an error message.

Before discussing all three parameters, I should define the term "message severity." Every message generated on the AS/400 has an associated "severity," which you can think of as its priority. Messages that are absolutely essential to the system's operation (e.g., inquiry messages that must be answered) have a severity of 99. Messages that are informational (e.g., messages that tell you a function is in progress) have a severity of 00. (For a detailed description of severity codes, you can refer to IBM's Programming: Control Language Reference, Volume 1, Appendix A, "Expanded Parameter Descriptions.")

The first parameter, message level, specifies one of the following five logging levels (note that a high-level message is one sent to the program message queue of the program that received the request or commands being logged from a CL program):

0 No data is logged.

1 The only information logged is any message sent to the job's external message queue with a severity greater than or equal to the message severity specified in this LOG parameter.

2 In addition to the information logged at level 1 above, the following is logged:

• Any requests or commands logged from a CL program that cause the system to issue a message with a severity level that exceeds or is equal to that specified in the LOG parameter.

• All messages associated with a request or commands being logged from a CL program and that result in a high-level message with a severity greater than or equal to the message severity specified in the LOG parameter.

3 The same as level 2, with the additional logging of any requests or commands being logged from a CL program:

• All requests or commands being logged from a CL program.

• All messages associated with a request or commands being logged from a CL program and that result in a high-level message with a severity greater than or equal to the message severity specified.

4 The following information is logged:

• All requests or commands logged from a CL program and all messages with a severity greater than or equal to the severity specified, including trace messages.

The second element of the LOG parameter, message severity, determines which messages will be logged and which will be ignored. Messages with a severity greater than or equal to the one specified in this parameter will be logged in the job log according to the logging level specified in the previous parameter.

With the third element of the LOG parameter, the message text level, a value of *MSG specifies that the system write only first-level message text to the job log. A value of *SECLVL specifies that the system write both the message and help text of the error message to the job log.

By setting the message text level value to *NOLIST, you ensure that any job initiated using that value in the job description does not generate a job log if the job is completed normally. Jobs that are completed abnormally will generate a job log with both message and help text present. Eliminating job logs for jobs that are completed normally can greatly reduce the number of job logs written into the output queue.

Determining how much information to include in the job logs. You can cause any interactive or batch job initiated with QDFTJOBD to withhold spooling of a job log if the job terminates normally. You simply create your user profiles with the default -- i.e., QDFTJOBD (Default Job Description) -- for the parameter JOBD (Job Description) and enter the command

CHGJOBD JOBD(QDFTJOBD) LOG(*SAME *SAME *NOLIST)

Is this approach wise? Interactive jobs almost always end normally. Therefore, changing the job description for such interactive sessions is effective. Do you need the information in those job logs? If you understand how your workstation sessions run (e.g., which menus are used and which programs called), you probably do not need the information from sessions that end normally. You might need the information when errors occur, but you can generally re-create the errors at a workstation. You can rest assured with this approach that jobs ending abnormally will still generate a job log and provide helpful diagnostic information.

Note that for interactive jobs, the LOG parameter on the SIGNOFF command overrides the value you specify on the job description. For instance, if on the job description you enter the value of *NOLIST in the LOG parameter and use the SIGNOFF LOG(*LIST) command to sign off from the interactive job, the system will generate a job log.

For batch jobs, the question of eliminating job logs is more complex than it is for interactive jobs. It is often helpful to have job logs from batch jobs that end normally as well as those that end abnormally, so someone can re-create events chronologically. When many types of batch jobs (e.g., nightly routines) run unattended, job log information can be useful.

Remember, the job description controls job log generation, so you can use particular job descriptions when you want the system to generate a job log regardless of how the job ends. The job description includes the parameter LOGCLPGM (Log CL Program Commands). This parameter affects the job log in that a value of *YES instructs the system to write to the job log any logable CL commands (which can happen only if you specify LOG(*JOB) or LOG(*YES) as an attribute of the CL program being executed). A value of *NO specifies that commands in a CL program are not logged to the job log.

A basic understanding of AS/400 print files will help you effectively and efficiently operate your system. Handling job logs is a simple, but essential, part of managing system resources. When you neglect to control the number of job logs on the system, the system is forced to maintain information for an excessive number of jobs, which can negatively affect system performance. And job logs are a valuable information source when a job fails to perform. Customize your system to handle job logs and other print files to optimize your operations.