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 larger—that 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;                       
                                                            
            select;                                         
               when Answer = 'R';                     
                    // Retry/refresh list             
                                                      
               when Answer = 'E';                     
                    // Controlled end                 
                                                      
                    EndCntrld(JobEnt.QWCJNbr + '/' +  
                              %trimr(JobEnt.QWCJUN) + '/' +  
                              %trimr(JobEnt.QWCJN01));      
                                                            
               when Answer = 'F';                           
                    // Immediate end                        
                                                            
                    EndImmed(JobEnt.QWCJNbr + '/' +         
                             %trimr(JobEnt.QWCJUN) + '/' +  
                             %trimr(JobEnt.QWCJN01));       
                                                            
               when Answer = 'C';                           
                    // Just return to caller                
                                                            
                    Exit = *on;                             
            endsl;  

           leave;

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 list—possibly missing new lock holders and finding previous lock holders in the list that no longer hold a lock—I 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 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 Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale

Also Read

The API Corner: Moving Jobs Within and Across Job Queues

The API Corner: What Time Zone Do You Want That Date and Time In?

The API Corner: How Do You Want That Date and Time?