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 Printers (WRKLANPRT) 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.
Articles on Apis 