Receive messages from the job log.
For the last few months, we've been looking at various considerations related to the running of CL commands using the QCMDEXC, QCAPCMD, and system APIs. As part of that discussion, we've explored some of the ways your RPG program can remove error-related messages from the job log. Due to several notes that I have received on the topic of message retrieval and removal, this article (and a following one) will go into more detail concerning some of the points I briefly discussed last month.
In the scenario we'll be using, our application program attempts to clear a member of file SOMEFILE using the Clear Physical File Member (CLRPFM) command, the CLRPFM fails due to CPF3141 (Member not found), the application attempts to add the member using the Add Physical File Member (ADDPFM) command, and the ADDPFM fails with message CPF7306 (Member not added and to see previous messages for the reason of the failure). At this point, the application program needs to determine the cause of the CPF7306 and, depending on the cause, take action to correct the situation.
Below is the initial version of the application program that we will be reviewing today. I have restructured the program from previous articles in order to consolidate the various calls to the Send Program Message API (I was getting tired of the duplication in sending messages) and to allow a discussion of how call level can impact the parameter values you pass to various message-handler APIs (a discussion deferred to next month).
h dftactgrp(*no)
dRunCmd pr extpgm('QCAPCMD')
d SourceCmd 65535 const options(*varsize)
d LenSrcCmd 10i 0 const
d CtlBlk 65535 const options(*varsize)
d LenCtlBlk 10i 0 const
d CtlBlkFmt 8 const
d ChgCmd 1 options(*varsize)
d LenAvlChgCmd 10i 0 const
d LenRtnChgCmd 10i 0
d QUSEC likeds(QUSEC)
dSndMsg pr extpgm('QSYS/QMHSNDPM')
d MsgID 7 const
d QualMsgF 20 const
d MsgDta 65535 const options(*varsize)
d LenMsgDta 10i 0 const
d MsgType 10 const
d CSE 65535 const options(*varsize)
d CSECtr 10i 0 const
d MsgKey 4
d QUSEC likeds(QUSEC)
d LenCSE 10i 0 const options(*nopass)
d CSEQual 20 const options(*nopass)
d DSPWaitTime 10i 0 const options(*nopass)
d CSEType 10 const options(*nopass)
d CCSID 10i 0 const options(*nopass)
dRcvMsg pr extpgm('QSYS/QMHRCVPM')
d MessageInfo 1 options(*varsize)
d LenMsgInfo 10i 0 const
d FmtMsgInfo 8 const
d CSE 65535 const options(*varsize)
d CSECtr 10i 0 const
d MsgType 10 const
d MsgKey 4
d WaitTime 10i 0 const
d MsgAction 10 const
d QUSEC likeds(QUSEC)
d LenCSE 10i 0 const options(*nopass)
d CSEQual 20 const options(*nopass)
d CSEType 10 const options(*nopass)
d CCSID 10i 0 const options(*nopass)
d AlwDftRpyRej 10 const options(*nopass)
dSndHardError pr
dHdlCPF3213 pr
dMaxInt pr 10i 0
d Input1 10i 0 const
d Input2 10i 0 const
/copy qsysinc/qrpglesrc,qcapcmd
/copy qsysinc/qrpglesrc,qmhrcvpm
/copy qsysinc/qrpglesrc,qusec
dPSDS sds 429 qualified
d JobUsr 254 263
dErrCde ds qualified
d Common likeds(QUSEC)
d ErrMsgDta 512
dMessageInfo ds qualified
d Common likeds(QMHM010001)
d ErrMsgDta 512
dCmd s 512
dMsgKey s 4
dNotUsedChr s 1
dNotUsedInt s 10i 0
/free
QUSBPRV = 0;
ErrCde.Common.QUSBPRV = %size(ErrCde);
QCAP0100 = *loval; // initialize input structure to nulls
QCACMDPT = 0; // Run command
QCABCSDH = '0'; // Ignore DBCS
QCAPA = '0'; // Do not prompt command
QCACMDSS = '0'; // User i5/OS syntax
Cmd = 'CLRPFM FILE(SOMEFILE) MBR(' + PSDS.JobUsr + ')';
RunCmd(Cmd :%len(%trim(Cmd)) :QCAP0100 :%size(QCAP0100)
:'CPOP0100' :NotUsedChr :0 :NotUsedInt :ErrCde);
if ErrCde.Common.QUSBAVL > 0;
select;
when ErrCde.Common.QUSEI = 'CPF3141';
Cmd = 'ADDPFM FILE(SOMEFILE) MBR(' + PSDS.JobUsr + ')';
RunCmd(Cmd :%len(%trim(Cmd)) :QCAP0100 :%size(QCAP0100)
:'CPOP0100' :NotUsedChr :0 :NotUsedInt :ErrCde);
if ErrCde.Common.QUSBAVL > 0;
select;
when ErrCde.Common.QUSEI = 'CPF7306';
RcvMsg(MessageInfo :%size(MessageInfo)
:'RCVM0100' :'*' :0 :'*DIAG' :MsgKey
:0 :'*OLD' :ErrCde);
if ErrCde.Common.QUSBAVL > 0;
SndHardError();
endif;
select;
when MessageInfo.Common.QMHMI03 = 'CPF3213';
HdlCPF3213();
other;
SndHardError();
endsl;
other;
SndHardError();
endsl;
endif;
when ErrCde.Common.QUSEI = 'CPF3142';
Cmd = 'CRTPF FILE(SOMEFILE) MBR(' + PSDS.JobUsr +
') MAXMBRS(*NOMAX) OPTION(*NOSRC *NOLIST)';
RunCmd(Cmd :%len(%trim(Cmd)) :QCAP0100 :%size(QCAP0100)
:'CPOP0100' :NotUsedChr :0 :NotUsedInt :ErrCde);
if ErrCde.Common.QUSBAVL > 0;
SndHardError();
endif;
other;
SndHardError();
endsl;
endif;
// Do further processing
*inlr = *on;
return;
/end-free
pSndHardError b
/free
SndMsg(ErrCde.Common.QUSEI :'QCPFMSG *LIBL'
:ErrCde.ErrMsgDta
:MaxInt(0 :ErrCde.Common.QUSBAVL - %size(QUSEC))
:'*DIAG' :'*PGMBDY' :1 :MsgKey :QUSEC);
SndMsg('ESC0001' :'OURMSGS *LIBL' :' ' :0
:'*ESCAPE' :'*PGMBDY' :1 :MsgKey :QUSEC);
/end-free
pSndHardError e
*****************************************************
pHdlCPF3213 b
/free
Cmd = 'CHGPF FILE(SOMEFILE) MAXMBRS(*NOMAX)';
RunCmd(Cmd :%len(%trimr(Cmd)) :QCAP0100 :%size(QCAP0100)
:'CPOP0100' :NotUsedChr :0 :NotUsedInt :QUSEC);
Cmd = 'ADDPFM FILE(SOMEFILE) MBR(' + PSDS.JobUsr + ')';
RunCmd(Cmd :%len(%trimr(Cmd)) :QCAP0100 :%size(QCAP0100)
:'CPOP0100' :NotUsedChr :0 :NotUsedInt :ErrCde);
if ErrCde.Common.QUSBAVL > 0;
SndHardError();
endif;
/end-free
pHdlCPF3213 e
*****************************************************
pMaxInt b
dMaxInt pi 10i 0
d Input1 10i 0 const
d Input2 10i 0 const
/free
if Input1 > Input2;
return Input1;
else;
return Input2;
endif;
/end-free
pMaxInt e
The program should look familiar to you if you have previously read the article "Automating Recovery, Part II." These are the differences:
- Adding a prototype for the Receive Program Message (QMHRCVPM) API
- Adding a prototype for the procedure SndHardError (Send Hard Error)
- Adding a prototype for the procedure HdlCPF3213 (Handle message CPF3213 – Members for file more than maximum allowed)
- Copying the QMHRCVPM QSYSINC header file for the QMHRCVPM API
- Defining the data structure MessageInfo, which is defined the same as the data structure QMHM010001 of the QMHRCVPM QSYSINC member with an additional 512 bytes allocated for message replacement data
- Adding additional error-recovery logic for when the ADDPFM command fails, which we will be reviewing shortly
- Replacing, at several locations within the program, two calls to the QMHSNDPM API with a call to the new SndHardError procedure
- Adding a call to the SndHardError procedure
- Adding the HdlCPF3213 procedure, which we will also be reviewing shortly
In the original program utilizing the QCAPCMD API, if the ADDPFM command failed, the application would send the user escape message ESC0001 (ending the program). The current program, on the other hand, interrogates the QCAPCMD API ErrCde parameter to further analyze why the ADDPFM command failed. If the error is not CPF7306 (the Other operation of the Select group), the program calls the SndHardError procedure to log the failure message.
If the cause of the failure is CPF7306 (Member not added), the program calls the QMHRCVPM API to receive the diagnostic message associated with the CPF7306 escape message. As was mentioned in last month's article, CPF7306 does not tell you why the ADDPFM failed, only that it did. Diagnostic messages, sent to you prior to the escape message, provide the details behind the failure.
The parameters used with the QMHRCVPM API are very similar to some of the parameters used with the Remove Program Message (QMHRMVPM) API first introduced in "Automating Recovery (or Keeping the Help Desk Out of the Loop)" and the Send Program Message (QMHSNDPM) API. The API documentation for QMHRCVPM can be found here. Basically the API receives a message from either a call message queue or an external message queue, and returns information describing the message.
The first three parameters, as is true with most retrieve type APIs, define what data we want returned about the message. Format RCVM0100 returns basic message information such as the message ID, the message severity, the message key (which will be utilized in a later enhancement of the example program), and optionally the message replacement data associated with the message. Quite a bit more information is available with format RCVM0200, but the current application has no need for this additional data.
The other parameters describe how the message is to be accessed. As the message was sent to the current procedure (the procedure running the ADDPFM command), the '*' value is used as the fourth parameter to indicate that the message is to be found relative to the current call-stack entry (that is, the caller of the API). The fifth parameter, call stack counter, identifies the call stack to be used relative to the call-stack entry identified by the fourth parameter. The value 0 indicates to use the base call-stack entry. The message type parameter value is '*DIAG' as we're looking for the diagnostic message associated with the CPF7306 escape message, and the message key parameter is a value of blanks, indicating we want the first available new message. The message action parameter is set to the value '*OLD', indicating that the received message should be marked as old and retained in the job log. The program could have the message removed as a part of receiving the message, but I prefer to remove the message only after I know it's no longer needed or relevant.
Having received the message, the program determines if the message is CPF3213 (Members for file more than maximum allowed). If it is, then procedure HdlCPF3213 is run; otherwise, the SndHardError procedure is run to send the original CPF7306 message, followed by the user escape message ESC0001.
The HdlCPF3213 procedure attempts to run the Change Physical File (CHGPF) command to change the maximum number of members to *NOMAX. When running the CHGPF command, the QCAPCMD API error code parameter is specified as QUSEC. This, due to the QUSEC setting of Bytes provided to 0, indicates that any error found with the CHGPF command should result in an escape message being sent. The program does this as there's no recovery logic associated with an error on the CHGPF command. The application could use the ErrCde parameter, rather than QUSEC, followed by a call to SndHardError if the returned ErrCde Bytes available is non-zero, but you've already seen several examples of using this approach.
If the CHGPF command is successful—that is, control is returned to the application program as opposed to an escape message being sent by the API—then the ADDPFM command is run again. The odds are good that this add will be successful, though the program does once again check the ErrCde Bytes available field just in case.
Calling this level of the program, and running the scenario described above, will result in the successful addition of a new member to file SOMEFILE. In the job log, you will find the three messages:
- CPF3213 – Members for file SOMEFILE more than maximum allowed.
- CPC7303 – File SOMEFILE in library xxxxxx changed.
- CPC7305 – Member yyyyyy added to file SOMEFILE in xxxxxx.
Depending on personal (or corporate) preference, you may or may not want these messages in the job log. Personally, I tend to look at job logs only when something has gone wrong, and I prefer to only have to look at messages related to the failure. These messages, however, are not describing a failure in the application. Rather, they document the successful handling of an environmental problem (namely, the lack of a necessary member). In particular, the CPF3213 message is the type of message that might cause me to spend a few minutes determining if it's a problem, only to find that it's not. So how might we remove this message?
Next month, we'll look at how various parameters of the QMHRMVPM API can be used to remove the CPF3213 message, the two CPC messages, and other messages that you might find to be a nuisance in your job logs.
Questions?
If you have any API questions, send them to me at
as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7,
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
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
|
More 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.
TRY 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.
Forms 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.
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:
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.
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:
LATEST COMMENTS
MC Press Online