• The Four Hundred
  • Subscribe
  • Media Kit
  • Contributors
  • About Us
  • Contact
Menu
  • The Four Hundred
  • Subscribe
  • Media Kit
  • Contributors
  • About Us
  • Contact
  • Listing Spool Files

    August 11, 2004 Bruce Guetzkow

    The code for this article is available for download.

    Changing spool file attributes can be a tedious chore. IBM provides the Change Spooled File Attributes (CHGSPLFA) command to simplify this task, allowing you to select a collection of spool files based on several characteristics, but, curiously, output queue is not one of the selection criteria. The solution is the List Spooled Files API (QUSLSPL), used as a front-end to CHGSPLFA. With this API you can select spool files by any combination of user name, output queue, form type, or user data.

    CREATING THE LIST

    The List Spooled Files API has six required parameters, as well as another 10 that are optional. I will only describe the required parameters and the first optional parameter:

    • Qualified user space name (input, 20 bytes, character). Like most IBM list APIs, the results of this API are sent to a user space. The first 10 bytes contain the user space name; the last 10 contain the library name (or *CURLIB or *LIBL).

    • Format name (input, 8 bytes, character). There are three options: SPLF0100, SPLF0200, and SPLF0300. I am using the last option, as it is the fastest.

    • User name (input, 10 bytes, character). This is the name of the user whose spool files are being selected (or *CURRENT or *ALL).

    • Qualified output queue name (input, 20 bytes, character). Specify the name of the output queue containing the spool files you are selecting. The first 10 bytes contain the name of the output queue (or *ALL); the last 10 is the library name (or *CURLIB or *LIBL).

    • Form type (input, 10 bytes, character). Specify the form type of the spool files you are selecting (or *ALL).

    • User-specified data (input, 10 bytes, character). Specify the user data of the spool files you are selecting (or *ALL).

    • Error code (input/output, variable size, character). The standard API error data structure.

    I’ve placed the call to this API in a service program as procedure #lstsplf in RPGLE source member SPLFLAPIRM to simplify how it is accessed. The parameter list for the procedure is as follows:

    • User space name (input, 10 bytes, character)

    • User space library (input, 10 bytes, character)

    • User name (input, 10 bytes, character)

    • Output queue name (input, 10 bytes, character)

    • Output queue library (input, 10 bytes, character)

    • Form type (input, 10 bytes, character)

    • User data (input, 10 bytes, character)

    Procedure #lstsplf returns the message ID from the standard API error data structure, along with 100 bytes of message data. The message ID can be checked in the calling program to determine the success of the call. The prototype for this procedure is found in RPGLE source member SPLFLAPIPR, which I have placed in source file QCPYSRC. If you use a different source file for your copy books, you will need to change the source member accordingly.

    To compile, execute the following commands:

              CRTRPGMOD MODULE(library/SPLFLAPIRM)
                                        SRCFILE(library/QRPGLESRC)
                                        SRCMBR(SPLFLAPIRM)
    
              CRTSRVPGM SRVPGM(library/SPLFLAPISV)
                                       MODULE(SPLFLAPIRM)
                                       EXPORT(*ALL)
    

    A NEW COMMAND

    To demonstrate how to use this API, I’ve created a program and command as an alternative to the CHGSPLFA command. I’ve named this new command CHGSPLFATR and given it the following parameters:

    • From User Name (input, 10 bytes, character). Specify the name of the user whose spooled files are being selected (or *CURRENT or *ALL).

    • From Output Queue (input, 20 bytes, character). Specify the name of the output queue containing the spool files you are selecting (or *ALL). The library may be *CURLIB or *LIBL.

    • From Form Type (input, 10 bytes, character). Specify the form type of the spool files you are selecting (or *ALL).

    • From User Data (input, 10 bytes, character). Specify the user data of the spool files you are selecting (or *ALL).

    • To Copies (input, 5 bytes, character). Specify the number of copies to change the selected spool files to.

    • To Output Queue (input, 20 bytes, character). Specify the output queue to move the selected spool files to.

    • To Save File (input, 5 bytes, character). Indicate whether the selected spool files should be saved after printing.

    RPGLE source member CHGSPLFATR receives the above parameters, selects spool files based on the “from” parameters, then executes command CHGSPLFA for each, changing the attributes specified on the “to” parameters. I intentionally made this command quite simple, only allowing three attributes to be changed. You can easily change my example to allow additional attributes to be changed if you wish. Let’s review the RPGLE source to see how this is done.

    Before any processing can be done, you must first create a user space to place the spool file selections into by executing procedure #crtusrspc. (See “Putting User Spaces in Your Toolbox” for more information on user spaces; the code for this article is available for download here.) I’ve specified user space CHGSPLFATR, in library QTEMP, though any valid name and library will do. The message ID is checked, and if there are any problems, an error message is sent to the user. Since this command is only for demonstration purposes, I’ve chosen to use the DSPLY op code.

    Next the program uses the “from” parameters to execute procedure #lstsplf (and API QUSLSPL), to load the user space with a list of spool files matching the selection values. The user space header is then retrieved to get information on how to read the entries from the user space. The “for” loop processes the list of entries from the user space. Data from the receiver variable (rtnds02.rcvvar) is placed in data structure splf0300ds, which identifies the current attributes of each spool file. For this program, I am using attributes that uniquely identify the spool file: spool file name, job name, user name, job number, and spool file number.

    Three parameters need special consideration before they can be used with the CHGSPLFA command. The FromOutQ Library parameter must be blanks if the FromOutQ is *ALL. The command definition for the ToCopies parameter indicates that if *SAME is specified, a value of -1 is passed to the program. If this value is received, it must be changed back to *SAME to be used with the CHGSPLFA command. The ToOutputQueue parameter must be formatted to pass either :library/outq or *SAME (no library).

    Now that everything is properly formatted, the CHGSPLFA command is constructed by concatenating the command name, keywords, and requested values. When the “for” loop is finished, the user space is deleted and the program ends.

    This program uses four copy books, again in QCPYSRC:

    • splf0300ds–layout of spool file information returned from QUSLSPL API.

    • usrspchdds–layout of user space header.

    • splflapipr–prototype of procedure #lstsplf (also used in service program).

    • usrspapipr–prototype of user space procedures.

    To compile, execute the following commands:

              CRTRPGMOD MODULE(library/ CHGSPLFATR)
                                        SRCFILE(library/QRPGLESRC)
                                        SRCMBR(CHGSPLFATR)
    
              CRTPGM PGM(library/CHGSPLFATR)           
                                BNDSRVPGM(SPLFLAPISV USRSPAPISV)
    
              CRTCMD CMD(library/CHGSPLFATR) 
                                PGM(library/CHGSPLFATR) 
                                SRCFILE(library/QCMDSRC)
                                SRCMBR(CHGSPLFATR)    
    

    TRY IT FOR YOURSELF

    Now that you can create and process a list of spool files, you can manipulate them as needed. My favorite method is to select spool files by output queue and form type, and then move those files to an output queue that is attached to a printer. This way I can more accurately control which forms are being printed. I’m sure you’ll find this API and service program equally useful.

    Bruce Guetzkow has programmed on the AS/400 and iSeries since 1990, in manufacturing, distribution, and other industries. He is currently the IS director at United Credit Service in Elkhorn, Wisconsin. E-mail: bguetzkow@itjungle.com

    Share this:

    • Reddit
    • Facebook
    • LinkedIn
    • Twitter
    • Email

    Tags:

    Sponsored by
    DRV Technologies, Inc.

    Get More from Your IBM i

    Many users today struggle to get at the data they need on the IBM i. When users get reports, they look like they were formatted some time last century.

    Some organizations are still printing pre-printed forms and checks on impact printers.

    How often do operators log on to their system to look for messages they hope they don’t find?

    All of these scenarios can affect users’ perception of the IBM platform negatively, but there are simple solutions.

    DRV Technologies Inc. develops innovative solutions that help customers get more from their IBM i systems.

    Solutions include:

    • SpoolFlex spool conversion & distribution
    • FormFlex electronic forms
    • SecureChex MICR laser check printing
    • MessageFlex system monitoring

    FlexTools streamline resources, improve efficiency and enable pro-active system management.

    Better software, better service, DRV Tech.

    Learn how you can get more from your IBM i at www.drvtech.com

    Call 866 378-3366 for a Free Demonstration

    Share this:

    • Reddit
    • Facebook
    • LinkedIn
    • Twitter
    • Email

    Califon Systems Ships New Release of OS/400 Security Module Fast400 Founder Sues Big Blue

    Leave a Reply Cancel reply

Volume 4, Number 27 -- August 11, 2004
THIS ISSUE
SPONSORED BY:

T.L. Ashford
WorksRight Software
Damon Technologies

Table of Contents

  • Listing Spool Files
  • Optional Parameters and CL Procedures
  • Control Break Programs, Version 3

Content archive

  • The Four Hundred
  • Four Hundred Stuff
  • Four Hundred Guru

Recent Posts

  • IBM Tweaks Some Power Systems Prices Down, Others Up
  • Disaster Recovery: From OS/400 V5R3 To IBM i 7.4 In 36 Hours
  • The Disconnect In Modernization Planning And Execution
  • Superior Support: One Of The Reasons You Pay The Power Systems Premium
  • IBM i PTF Guide, Volume 25, Number 13
  • IBM i Has a Future ‘If Kept Up To Date,’ IDC Says
  • When You Need Us, We Are Ready To Do Grunt Work
  • Generative AI: Coming to an ERP Near You
  • Four Hundred Monitor, March 22
  • IBM i PTF Guide, Volume 25, Number 12

Subscribe

To get news from IT Jungle sent to your inbox every week, subscribe to our newsletter.

Pages

  • About Us
  • Contact
  • Contributors
  • Four Hundred Monitor
  • IBM i PTF Guide
  • Media Kit
  • Subscribe

Search

Copyright © 2023 IT Jungle