In the October 22, 2009, APIs by Example column, I present a homegrown version of the Additional Message Information panel. This panel lets you display and optionally reply to a message residing in a message queue, based on the qualified name of the message queue and the message key identifying the specific message to display. The usefulness of such a facility is prompted by the ability of some jobs and print APIs that return the name of the message queue assigned to a job or printer as well as the message key when the job or printer is currently waiting for a reply to a message.

Today, I present an example of how to use one of the aforementioned APIs in collaboration with my Additional Message Information panel, thereby providing a functionality similar to the one offered by many native IBM Job and Writer CL commands' list panels, including an option 7=Display message. Because I currently have no access to a system at release 6.1, which is required to take advantage of the Message wait message key information added to some of the Job APIs at that release, I decided to create a utility based on one of the Writer APIs, which for some time now has included this information. Say hello to the Work with LAN Writer (WRKLANWTR) command.

If you're familiar with the native writer commands' list panels and their behavior, you know that when you specify option 7 for writer job that is currently waiting for a reply to message in order to continue processing, you're taken directly to the Additional Message Information display. If you specify option 7 and the writer job is not waiting for a message to be replied, the message queue assigned to the writer job will instead be displayed. Once you know the writer job currently associated with the LAN printer device, it's quite simple to establish which of the message wait states currently applies to the writer job.

The Retrieve Writer Information (QSPRWTRI) API tells you when you inspect the API's receiver format WTRI0100 at decimal offset 19, defined by the API documentation as the Waiting for message status 1-byte character field. When the writer is waiting for a reply to an inquiry message, the value Y is returned in this field, otherwise, the value N is present. If waiting for a message reply, a 4-byte message key to the message is provided in the receiver format at decimal offset 284. The name of the message queue and the library in which it is located are found at decimal offset 148 and 158, respectively. This is all straightforward. But how to locate all or a subset of LAN printer devices currently configured on a system?

One good place to start looking for an API is by trying to identify a CL command counterpart. In this case, the Work with Device Descriptions (WRKDEVD) as well as the Work with Configuration Status (WRKCFGSTS) commands are qualified candidates. Both support a *LANPRT special value limiting the returned list to printer devices of type Local Area Network (LAN) printer devices. While the Configuration APIs do include both a Retrieve Device Description (QDCRDEVD) API and a List Configuration Descriptions (QDCLCFGD) API, the former returns information only for a single device description, while the latter, as suggested by its name, returns a list of device descriptions as well as supports the special value *LANPRT for the Object qualifier API input parameter. Specifying the aforementioned parameter together with a primary selection criterion Configuration description type of *DEVD ensures that only LAN printer device descriptions are returned by the QDCLCFGD API.

A closer look at the QDCLCFGD API documentation further reveals that the API returns the selected configuration list to a user space. Following a successful API call, you have to process the user space to access the configuration object list. I've previously covered this type of API and user space list processing a number of times in the APIs by Example column, for example in the article titled "APIs by Example: Retrieve Subsystem Entries API." Please refer to this article for the details and specifics on processing list API output in a user space. Apart from device attributes, the list returned by the QDCLCFGD API also includes information on the device status as well as the qualified job name of the associated writer job, if any.

At this point, I can concentrate on retrieving further information for my WRKLANPRT command's list panel. The information returned by the QDCLCFGD API in turn provides the key parameters to employ the Retrieve Device Description (QDCRDEVD), the Retrieve Output Queue Information (QSPROUTQ) and the QSPRWTRI APIs in the process of gathering the remaining data required to build a list of the LAN printer devices currently configured on a system. Following a careful investigation of the impressive amount of information accessible through the mentioned APIs, I settle on the following extract to be included in the LAN printer list panel:

  Information                 API
  Printer device name         QDCLCFGD
  Printer device status       QDCLCFGD
  Device text                 QDCLCFGD
  Writer job name             QDCLCFGD
  Writer job user profile     QDCLCFGD
  Writer job number           QDCLCFGD
  Message queue name          QDCRDEVD/QSPRWTRI 
  Message queue library       QDCRDEVD/QSPRWTRI
  Remote address              QDCRDEVD
  Output queue name           QDCLCFGD/QSPRWTRI
  Output queue library        QSPRWTRI
  Writer started by           QSPRWTRI
  Writer status               QSPRWTRI
  Output queue status         QSPRWTRI/QSPROUTQ
  Form type                   QSPRWTRI
  Message option              QSPRWTRI
  Message wait status         QSPRWTRI
  Message key                 QSPRWTRI

Where more than one API is mentioned, the source of information is determined by the current status of the writer job. If active, the QSPRWTRI API is used to obtain the information, otherwise the alternative API is employed. Now let me turn your attention to WRKLANPRT command definition. Prompting the WRKLANPRT command reveals the following rather limited offer in terms of input parameter provided:

                       Work with LAN Printers (WRKLANPRT)                  
                                                                           
 Type choices, press Enter.                                                
                                                                           
 Printer device . . . . . . . . .   *ALL          Name, generic*, *ALL     
 Output . . . . . . . . . . . . .   *             *, *PRINT                

You can specify a specific printer device name, a generic printer device name, or the special value *ALL. The latter option causes all LAN printer devices currently configured on your system to be included in the list presented. If you for some reason need the LAN printer information in print, the Output parameter allows you to direct a subset of the LAN printer information to be printed with the current job's spooled output. The WRKLANWTR command and its parameters are fully documented by the online help text panel group. Here's how the command's output looks on my system when directed to a screen:

                             Work with LAN Printers                    WYNDHAMW 
                                                             22-01-10  20:38:22 
 Type options, press Enter.                                                     
   1=Start   2=Change   3=Hold   4=End   5=Work with    6=Release   7=Messages  
   8=Job   9=Ping   10=Output queue   11=Manage queue   12=Device   14=Status   
                                                                                
                                          --------Output queue--------  Writer  
 Opt  Printer     Sts   Device status     Name       Library    Status  status  
      BERP01      STR   ACTIVE/WRITER     ALPB01     QUSRSYS     *RLS    *PND   
      CPHP01      END   VARIED ON         AUPB01     QUSRSYS     *RLS           
      CPHP02      MSGW  ACTIVE/WRITER     BEPB01     QUSRSYS     *RLS    *PND  
      CPHP03      STR   ACTIVE/WRITER     BOPB01     QUSRSYS     *RLS    *PND   
      HAMP01      STR   ACTIVE/WRITER     BJPB01     QUSRSYS     *RLS    *PND   
      HAMP02      END   VARIED ON         BKPB01     QUSRSYS     *RLS           
      OSLP01      STR   ACTIVE/WRITER     BLPB01     QUSRSYS     *RLS    *PND   
      PARP01      END   VARIED ON         BNPB01     QUSRSYS     *RLS           
      STOP01      MSGW  ACTIVE/WRITER     BVPB01     QUSRSYS     *RLS    *PND   
      VENP01      STR   ACTIVE/WRITER     BVPB02     QUSRSYS     *RLS    *PND   
                                                                        More... 
 Parameters or command                                                          
 ===>                                                                           
 F4=Prompt    F5=Refresh   F6=Create LAN Printer      F10=Active writer jobs    
 F11=View 2   F12=Cancel   F22=Display entire field   F24=More keys             

In addition to the above panel, the two other views available using function key F11 include the remaining information such as Remote address, Writer job name, Started by, Form type, Message option and Message queue. Other function keys are included to provide shortcuts to, for example, the Create Device Description (Printer) (CRTDEVPRT) command with the primary LAN printer configuration parameters specified, as well as the Work with Writers (WRKWTR WTR(*ALL)) command producing a list of all currently active writer jobs on the system.

The many list options allow you to perform a number of writer functions (starting, changing, holding, ending, working with, and releasing) against each of the LAN printers listed. The option discussed in particular in this article, the display message detail or message queue depending on the current status of the writer job, is assigned to list option 7, as you would expect. The remaining list options offer an array of practical functions related to each LAN printer:

   8=Work with writer job (and job log)
   9=Ping the printer device remote address
  10=Work with associated output queue
  11=Perform output queue actions against associated output queue
  12=Work with printer device description
  14=Work with printer device configuration status

The Work with LAN Writer list panel, the list columns, and the related options and function keys are all described in detail in the cursor-sensitive online help text.

This APIs by Example includes the following sources:

CBX211   -- RPGLE  -- Work with LAN Printers - CPP             
CBX211E  -- RPGLE  -- Work with LAN Printers - UIM Exit Program
CBX211H  -- PNLGRP -- Work with LAN Printers - Help            
CBX211P  -- PNLGRP -- Work with LAN Printers                   
CBX211V  -- RPGLE  -- Work with LAN Printers - VCP             
CBX211X  -- CMD    -- Work with LAN Printers                   

CBX211M  -- CLP    -- Work with LAN Printers - Build command   

To create all these Work with LAN Printers command objects, compile and run the CBX211M program, following the instructions in the source header. As always, the compilation instructions are also included in the respective source headers. For the WRKLANWTR command's list panel's option 7 to work, you'll need to download and create the Additional Message Information panel included with the APIs by Example article found at the link below.

Related articles:

Additional Message Information Panel

User Space API List Processing

This article demonstrates the following Configuration and Print APIs:

List Configuration Descriptions (QDCLCFGD) API

Retrieve Device Description (QDCRDEVD) API

Retrieve Output Queue Information (QSPROUTQ) API

Retrieve Writer Information (QSPRWTRI) API

Retrieve the source code for this API example