Sun, Mar
0 New Articles

The API Corner: Getting Directions Using Inquiry Messages

  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times


Use APIs to send and receive messages.

Last month, in Trying to Allocate an Object?, we enhanced the program AllocObj, which was first introduced in Problems Allocating an Object?. The enhancement was that the program, if run in an interactive job, would build a subfile listing those jobs with locks on the object. From this list, the user could decide to contact someone about one or more of these jobs, end one of more of these jobs, and/or cancel the current running of AllocObj.

This month, we are going to look at the batch side of AllocObj. As batch programs in general do not have access to a workstation in order to present a subfile, AllocObj will now send an inquiry message and then perform processing based on the reply provided to the message. The options provided to the user will be the same types as we supported last month.

Last month, we needed to create the display file AllocObjFM. This month, we will be creating a message file, named PLAYMSGS, and a message description, identified as ALC0001. The following two commands, Create Message File (CRTMSGF) and Add Message Description (ADDMSGD), will create the message file and define our new message, respectively.

CrtMsgF MsgF(PlayMsgs)

AddMsgD MsgID(ALC0001) MsgF(PlayMsgs)

Msg('Object &1 locked by job &4/&3/&2 (R – Retry, F – End job *Immed,

       E – End job *Cntrld, C – Cancel lock checks)')

SecLvl('The job &4/&3/&2 currently holds a lock on the object &1.

         The current job cannot continue until this lock is released.

         Your options are to end job &4/&3/&2 and then use option R to

         retry; have this job end the job in a controlled fashion using

         option E; have this job end the job immediately using option F;

         or cancel lock checking using option C.')

Fmt((*Char 10) (*Char 10) (*Char 10) (*Char 6))

Len(1) Values(R E F C)

SpcVal(('r' R) ('e' E) ('f' F) ('c' C))

The ALC0001 message defines both first- and second-level text with the second-level text accessible using F1 from the inquiry message display. There are four replacement variables defined (&1 for the 10-byte object name, &2 for the 10-byte job name, &3 for the 10-byte job user name, and &4 for the 6-byte job number) and four possible responses (R for retry the allocation request, E to end the identified job in a controlled fashion, F to end the identified job immediately, and C to cancel the current job's attempt to allocate the object). If the provided response by the user is not R, E, F, or C (or their lowercase equivalents), the system will reject the response with CPF2445 – Reply not allowed for inquiry message (unless the user answers with a blank in which case the message will be left as unanswered).

Rather than repeating the program source from last month, this article will look at what needs to be added (or replaced) relative to last month's AllocObj program in order to work with inquiry messages. As we will be using one API to send the inquiry message, Send Nonprogram Message (QMHSNDM), and another to receive the response, Receive Program Message (QMHRCVPM), we will start with the prototypes for these APIs.

d SndNPgmMsg      pr                  extpgm('QMHSNDM')       
d  MsgID                         7a   const                   
d  QualMsgF                     20a   const                   
d  MsgDta                      256a   const options(*varsize) 
d  LenMsgDta                    10i 0 const                   
d  MsgType                      10a   const                   
d  QualMsgQ                     20a   const                   
d  NbrMsgQs                     10i 0 const                   
d  RplyQ                        20a   const                   
d  MsgKey                        4a                           
d  ErrCde                             likeds(QUSEC)           
d  CCSID                        10i 0 const options(*nopass) 

The Send Nonprogram Message API QMHSNDM, prototyped as SndNPgmMsg, has quite a few parameters but is very easy to use (as you will see shortly):


  • The first parameter identifies the message description we want to send (which will be the ALC0001 message we created earlier). You can also use blanks for this parameter if you want to send impromptu text (the text of which would be provided in the third parameter).
  • The second parameter is the qualified name of the message file containing the message description (PLAYMSGS in our case). As with the first parameter, this parameter can also be set to blanks if you want to send an impromptu message.
  • The third parameter is the replacement data we want to use for message substitution variables (that is, the variables &1, &2, &3, and &4 we defined and referenced in message ALC0001). In the case of sending an impromptu message, this is the text to be sent.
  • The fourth parameter is the length of the replacement data and/or impromptu message we are supplying in the third parameter.
  • The fifth parameter is the type of message being sent. The API can be used to send several types of messages. The types supported are completion (*COMP), diagnostic (*DIAG), informational (*INFO), and inquiry (*INQ). As mentioned before, AllocObj will be sending an inquiry message.
  • The sixth parameter is a list of one or more message queues to send the message to. Special values such as *ALLACT for all active users, *REQUESTER for the current user's message queue when run in an interactive job or QSYSOPR if run in a batch job, and *HSTLOG to send the message to QHST are also supported. AllocObj will be using the *REQUESTER support.
  • The seventh parameter is the number of message queues and/or special values passed using the sixth parameter. AllocObj will be using a value of 1.
  • The eighth parameter identifies, for inquiry messages, the message queue that is to receive the response (known as a reply message) to the inquiry message. For all other message types, (*COMP, *DIAG, and *INFO), this parameter is set to blanks. AllocObj will be using the special value *PGMQ to indicate that the reply should be sent to the call stack entry calling the QMHSNDM API.
  • The ninth parameter is the only output parameter of the QMHSNDM API and is used only for inquiry messages. The returned value is a 4-byte character value known as a message key. This message key can be used, in conjunction with the QMHRCVPM API, to access the reply to the inquiry message being sent.
  • The tenth parameter is the standard API error code data structure.
  • The optional eleventh parameter allows you to associate a CCSID with the character data being passed in the third parameter.


As message description ALC0001 defines four substitution variables and we need to pass these four values in the third parameter of QMHSNDM, AllocObj defines the data structure ALC0001 as shown below.

d ALC0001         ds                  qualified          
d  Object                       10a                      
d  JobName                      10a                      
d  JobUsrName                   10a                      
d  JobNbr                        6a                      
The data structure can be named anything you want, but I find using a data structure name that is the same as the message description identifier to be rather handy. As you can see, the data structure subfields of ALC0001 are assigned names corresponding to how they are used within the message text of message ALC0001 and are defined with the same attributes that were used when adding the message description (the FMT parameter of the ADDMSGD command).

As QMHSNDM will also be returning the message key (the ninth parameter of the API), we also define the field MsgKey as shown below.

MsgKey          s              4a                     

The Receive Program Message API QMHRCVPM, prototyped as RcvPgmMsg, also has quite a few parameters.

d RcvPgmMsg       pr                  extpgm('QMHRCVPM')     
d  RcvVar                        8a   options(*varsize)      
d  LenRcvVar                    10i 0 const                  
d  FmtRcvVar                     8a   const                  
d  CSE                          10a   const                  
d  CSECtr                       10i 0 const                  
d  MsgType                      10a   const                  
d  MsgKey                        4a   const                  
d  WaitTime                     10i 0 const                  
d  MsgAction                    10a   const                  
d  ErrCde                             likeds(QUSEC)          
d  LenCSE                       10i 0 const options(*nopass) 
d  CSEQual                      20a   const options(*nopass) 
d  CSEType                      10a   const options(*nopass) 
d  CCSID                        10i 0 const options(*nopass) 
d  AlwDftRplyRej                10a   const options(*nopass)  
Like most APIs that retrieve information, the first parameter identifies the receiver variable to receive the information, the second parameter the allocated size of the receiver variable, and the third parameter the format of the information to be returned.

The QMHRCVPM API defines three possible formats that can be used when returning information about a message. Reviewing the API documentation, we see that all three formats (RCVM0100, RCVM0200, and RCVM0300) can return the reply to an inquiry message and as, in general, lower numbered formats provide better performance than higher numbered formats, AllocObj will use format RCVM0100.

Format RCVM0100 returns several pieces of information about the message received. This includes the standard API receiver variable fields of bytes returned and bytes available with also message-specific information such as the message identifier, the type of message, the severity of the message, and so on. A definition of these fixed fields in format RCVM0100 can be found in QSYSINC/QRPGLESRC source member QMHRCVPM, so we also add the following /copy directive to AllocObj.

 /copy qsysinc/qrpglesrc,qmhrcvpm                       

The definition of the fixed fields in format RCVM0100 are found in data structure QMHM010001. To access the reply to the ALC0001, message AllocObj defines the data structure RcvPMDta using the IBM-provided definition (QMHM010001) and a 1-byte field (Answer) to accommodate the returned reply. The full definition for RcvPMDta is:

d RcvPMDta        ds                  qualified          
d  Hdr                                likeds(QMHM010001) 
d  Answer                        1a                      

This definition is very specific to AllocObj as it only supports message replies of one byte. This works for AllocObj as the program only sends inquiry messages using ALC0001, which only defines valid responses that are 1 byte in length. A more general solution, though, would be to define RcvPMDta.Answer as being, for instance, 132 bytes in length. This length would then accommodate a variety of replies, to different messages, such as 'C', 'GoAhead', and 'NeverMind'. To enable this type of flexibility format, RCVM0100 also returns an integer value telling you the actual length of the reply data returned in RcvPMDta. This field, RcvPMDta.Hdr.QMHDRtn00, could then be used to substring out the relevant reply found in the 132-byte RcvPMDta.Answer variable. Just in case the reply is actually longer than the allocated size of RcvPMDta.Answer, the API will also, using field RcvPMDta.Hdr.QMHDAvl00, tell you the size of the reply that could have been returned if RcvPMDta were largerthat is, warn you that some of the reply value is truncated when RcvPMDta.Hdr.QMHDAvl00 is greater than RcvPMDta.Hdr.QMHDRtn00.

The remaining parameters of QMHRCVPM are:


  • The fourth parameter identifies the base call stack entry from which the message is to be received. The special value '*' identifies the current call stack entry, which corresponds to our use of *PGMQ for the eighth parameter of the QMHSNDM API when sending the inquiry message.
  • The fifth parameter can be used to identify a call stack entry relative to the call stack entry identified by the fourth parameter. For AllocObj, we will be using a value of 0 as the value used for the fourth parameter ('*') needs no adjustment.
  • The sixth parameter identifies the type of message to be received. As AllocObj wants the reply to the ALC0001 inquiry message previously sent, the value we'll use is *RPY. Other special values include *ANY, *FIRST, *NEXT, and *DIAG to mention a few.
  • The seventh parameter identifies the message key of the message to be received. This will be the value of the message key returned by QMHSNDM when sending message ALC0001 (the ninth parameter of QMHSNDM).
  • The eighth parameter specifies how long the program will wait for the message to be received. In the case of an inquiry message, this represents how long the program will wait for a reply. A positive number represents the number of seconds the program will wait, a value of 0 indicates the program should not wait at all, and a value of -1 indicates that the program should wait however long it takes for the message (in our case, the reply) to be received. AllocObj uses the special value -1.
  • The ninth parameter indicates what action should be taken on the received message. The special values supported are *OLD to mark the message as being old, *REMOVE to remove the message from the message queue (and invalidate the message key of the message), and *SAME to receive the message without changing the status of the message. 
  • The tenth parameter is the standard API error code data structure. 
  • Following the error code parameter are several optional parameters that we will not be using today.


With the prototype and definition changes to AllocObj taken care of, let's make some changes to the logic found in the function PrcLcksB. Last month, PrcLckB() contained, among other things, the following two operations:

            Dsply ('Lock held by ' +

                 %trimr(JobEnt.QWCJN01) + '/' +         
                   %trimr(JobEnt.QWCJUN) + '/' +  
                   JobEnt.QWCJNbr) ' ' Answer;       
                                                                                         Exit = *on;                             

This month, replace the two preceding statements with the following:

            ALC0001.Object = Obj_In;                     
            ALC0001.JobName = JobEnt.QWCJN01;               
            ALC0001.JobUsrName = JobEnt.QWCJUN;             
            ALC0001.JobNbr = JobEnt.QWCJNbr;                
            SndNPgmMsg('ALC0001' :('PLAYMSGS  *LIBL')       
                       :ALC0001 :%size(ALC0001)             
                       :'*INQ' :'*REQUESTER' :1 :'*PGMQ'    
                       :MsgKey :QUSEC);                     
            RcvPgmMsg(RcvPMDta :%size(RcvPMDta) :'RCVM0100' 
                      :'*' :0 :'*RPY' :MsgKey               
                      :-1 :'*OLD' :QUSEC);                  
            Answer = RcvPMDta.Answer;                       
               when Answer = 'R';                     
                    // Retry/refresh list             
               when Answer = 'E';                     
                    // Controlled end                 
                    EndCntrld(JobEnt.QWCJNbr + '/' +  
                              %trimr(JobEnt.QWCJUN) + '/' +  
               when Answer = 'F';                           
                    // Immediate end                        
                    EndImmed(JobEnt.QWCJNbr + '/' +         
                             %trimr(JobEnt.QWCJUN) + '/' +  
               when Answer = 'C';                           
                    // Just return to caller                
                    Exit = *on;                             


With the above changes, AllocObj now sends inquiry message ALC0001, identifying the first job found with a lock on the specified object (and that is not the current job), asking what to do. The processing is fairly straightforward.

  • As message ALC0001 has four substitution variables defined, AllocObj first sets the subfields of the ALC0001 data structure to the appropriate values.

  • Inquiry message ALC0001 is sent using the QMHSNDM API, passing the substitution variables set in the previous step.

  • The reply to the inquiry message is received using the QMHRCVPM API.

  • The reply (RcvPMDta.Answer) is moved to the variable Answer.

  • A Select group is entered, which processes the Answer using the same approach as we used in PrcLcksI() of last month.


The DoFor, after processing one job and the reply to message ALC0001, is left.

As provided in this article, each iteration of PrcLcksB() will send only one inquiry message and then return to try and again get a lock on the desired object. If the allocation attempt is unsuccessful, then PrcLcksB() will again identify the first job found to be holding a lock using message ALC0001. The reason I chose to send only one inquiry message per iteration is due to the processing delay inherent in waiting for a reply to the sent message. During the time the operator is responding to (or, more likely, even noticing) the message, the system environment might change quite a bit. Rather than processing the remainder of the listpossibly missing new lock holders and finding previous lock holders in the list that no longer hold a lockI would prefer to attempt again to allocate the object (requesting the release of locks for new lock holders) and then process the then-current list of lock holders.

We could implement a few more features in AllocObj, but they would be variations on what we have previously looked at. PrcLcksB() could, for instance, test to see if the job holding the lock is currently in the process of ending and, if so, continue in the DoFor loop looking for another job to identify in the ALC0001 message as there is no need to prompt the user for a job already ending. This type of check, however, was covered last month in the UpdSFL subroutine of PrcLcksI(), where we tested field QUSES00 after calling the QUSRJOBI API. Likewise, PrcLcksB() could check if the same job has been in an ending status for longer than 10 minutes and, if so, replace the EndJob command being run with an EndJobAbn command. This would just be a refinement of how AllocObj is using the QCAPCMD API, however. So we'll consider AllocObj "done" for our purposes today.

As usual, if you have any API questions, send them to me at This email address is being protected from spambots. You need JavaScript enabled to view it..


Bruce Vining

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

IBM System i APIs at Work IBM System i APIs at Work
Leverage the power of APIs with this definitive resource.
List Price $89.95

Now On Sale



Support MC Press Online

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: