04
Mon, Nov
1 New Articles

Message Queue Housekeeper

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

Message queues tend to become cluttered. Often, you find they have so many messages that it's difficult to locate the messages that need your attention. Many of the messages are obsolete because the jobs that issued them are no longer active. If one of these obsolete messages requires a response (message type inquiry), another problem arises. An operator may spend time discerning an appropriate response when a response isn't necessary.

Suppose a batch job runs into a problem that causes an inquiry message to be sent to the QSYSOPR message queue. A programmer happens to be monitoring this job. He evaluates the job and decides to cancel it with the End Job (ENDJOB) command. The inquiry message remains in the QSYSOPR message queue, unanswered. An operator monitoring QSYSOPR encounters the message and attempts to respond to it. He may even call a programmer or his manager for assistance in determining an appropriate response. Since the message is obsolete, a response is meaningless. The system has tricked the operator and wasted at least one person's time.

This problem has always bothered me, especially because the S/34 and S/36 cleared inquiry messages when their associated jobs were cancelled. Of course, you can display the message queue and remove selected or unanswered messages, or even all messages. However, selectively removing messages is time-consuming; and removing all messages, although quick, may be overkill. The best solution would require IBM to change the operating system. Until that happens, the Clear Obsolete Messages (CLROBSMSG) command presented here can solve the problem.

How to Use CLROBSMSG

The CLROBSMSG utility clears a message queue of any inquiry messages issued by a job that is no longer active. If an operator runs CLROBSMSG for a message queue before he displays the message queue, he can be sure he won't waste time responding to obsolete inquiry messages. You'll probably find the command most useful with the QSYSOPR message queue, but there may be other candidates-for example, message queues assigned to printers.

To use the command, just key CLROBSMSG and press the F4 (Prompt) key. A panel is displayed with the only parameter required by CLROBSMSG-the qualified message queue (MSGQ) name.

The message queue and library must have valid object names and they must exist on your system. In addition, the command must be able to allocate the message queue. Suppose your system operator has the QSYSOPR message queue allocated at the console. If he submits the command to batch, the job will abort. However, he can run it interactively at any time.

How to Install

To install the utility, create the command source member (CLROBSMSG) listed in 1, the CL program (OBS001CL) in 2 and the RPG program OBS001RG in 3. Compile the source members according to the instructions at the beginning of each figure.

To install the utility, create the command source member (CLROBSMSG) listed in Figure 1, the CL program (OBS001CL) in Figure 2 and the RPG program OBS001RG in Figure 3. Compile the source members according to the instructions at the beginning of each figure.

An Overview of How It Works

If you like to read source code to interpret how an application works, you may be able to skip this section and reference the source code presented in Figures 1-3. For some assistance in deciphering how the utility works, read on.

CLROBSMSG first performs an implicit call to validity-checking program OBS001CL, reproduced in 2. This call happens automatically because OBS001CL is specified in the validity-checking program (VLDCKR) parameter of the Create Command (CRTCMD) command when the CLROBSMSG command is created. For more information on validity-checking programs (VCPs), see the accompanying sidebar.

CLROBSMSG first performs an implicit call to validity-checking program OBS001CL, reproduced in Figure 2. This call happens automatically because OBS001CL is specified in the validity-checking program (VLDCKR) parameter of the Create Command (CRTCMD) command when the CLROBSMSG command is created. For more information on validity-checking programs (VCPs), see the accompanying sidebar.

OBS001CL validates the message queue and its library with the Check Object (CHKOBJ) command. If the CHKOBJ command doesn't execute successfully, the program-level Monitor Message (MONMSG) command causes OBS001CL to go to the ABORT label. From here, the error message is sent using the Send Program Message (SNDPGMMSG) command.

OBS001CL determines if the message queue is allocated by executing the Allocate Object (ALCOBJ) command. If message CPF1002 (Cannot allocate objects) is received, the program-level MONMSG command causes a branch to the ABORT label where the message is forwarded to the user. A successful execution of the ALCOBJ command locks the message queue, so the Deallocate Object (DLCOBJ) command is used to remove the lock.

Once the validation program executes successfully, command-processing program OBS001RG (3) executes. It would be easier to write the command- processing program (CPP) as a CL program, using common message commands. However, I chose to use an RPG program and the message application program interfaces (APIs) instead, because this design allows the command to execute much faster. In fact, executing the command interactively without the APIs would be impractical. (A CL version, which I ran against a message queue with 1,000 messages, took about two minutes. The API version took less than 15 seconds.)

Once the validation program executes successfully, command-processing program OBS001RG (Figure 3) executes. It would be easier to write the command- processing program (CPP) as a CL program, using common message commands. However, I chose to use an RPG program and the message application program interfaces (APIs) instead, because this design allows the command to execute much faster. In fact, executing the command interactively without the APIs would be impractical. (A CL version, which I ran against a message queue with 1,000 messages, took about two minutes. The API version took less than 15 seconds.)

The CPP reads each message in a message queue, starting from the top, and determines if the message type is inquiry. If it is, the program determines the status of the message. Obsolete messages are deleted after the next message is read. The basic logic is pretty simple:

o Read message. o Conditionally remove previous message. o Check message type and status.

Let's take a closer look.

Implementation Details: First Message

OBS001RG uses special logic for the first message in the message queue. The details of how a message is processed are the same for the first message and all subsequent messages, but the first message requires a different sequence.

The first message is read by initializing the message key (MSGKEY) with the special value *TOP and using the special value *NEXT for the message type (MTYPE). The message key and type are used as input parameters in the Receive Nonprogram Message (QMHRCVM) API which is called in subroutine RCVMSG. The QMHRCVM API returns the key of the current message through subfield CURKEY. CURKEY is moved to MSGKEY so the next message can be retrieved. (The current key provides a link to the next message.)

Next, subroutine CHKMSG executes to determine if the message type is inquiry. If it is, the program saves the message key into the INQKEY field and the CHKMSG subroutine executes the RTVJOB subroutine to determine whether the job is still active.

Subroutine RTVJOB calls the Retrieve Job Information (QUSRJOBI) API to obtain the message sender's job information and returns the job status in the JOBSTS subfield of the JOBBUF output parameter. If the job is found (indicator 50 off) and the job status is equal to *ACTIVE, blanks are moved to the INQKEY field. INQKEY is used later to determine whether or not to remove the message.

Implementation Details: Subsequent Messages

The program enters a read loop where all messages except the first are processed. Each read retrieves the next message by using the message key (MSGKEY) field of the previous message and specifying *NEXT in the message type (MTYPE) field.

If the previous message is an inquiry message issued by a job that is no longer active, the previous message is removed. (The next message must be read before deleting the previous message because the read operation uses the message key of the current message to retrieve the next message.)

Immediately after the next message is read, the INQKEY field is checked. If the field is not blank, the previous message was an obsolete inquiry message; the message is removed with the Remove Nonprogram Message (QMHRMVM) API in the RMV- MSG subroutine.

The read loop is iterated until no more messages are found.

Better Days

If old inquiry messages cause you or your operators grief, CLROBSMSG may be the key to a more hassle-free day.

Richard Shaler is a senior technical editor for Midrange Computing.

References CL Programmer's Guide (SC41-8077, CD-ROM QBKA7102). System Programmer's Interface Reference (SC41-8223, CD-ROM QBKA8402).

Validity-Checking Programs

Validity-checking programs (VCPs) are automatically executed before the command-processing program (CPP). Any errors encountered in the validity program are sent to the user and prevent the CPP from starting. The VCP accomplishes this by sending two special program messages with the Send Program Message (SNDPGMMSG) command as follows:

o The error information is sent as a diagnostic message through a special message, CPD0006, found in the QCPFMSG message file in library QSYS. The error message is sent through the message data (MSGDTA) parameter of the SNDPGMMSG command. You must prefix the message text with a string of four zeros (0000) followed by a blank.

o The command is aborted by sending a special message, CPF0002, as an escape message.

You can see this process in VCP program OBS001CL (2) at the ABORT label.

You can see this process in VCP program OBS001CL (Figure 2) at the ABORT label.

Programmers often ignore VCPs. I believe it's mostly because when CPPs are written in CL (a common occurrence), it's so easy to combine the validity- checking code with the processing code and not have another source member to manage. However, VCPs are worth considering for several reasons.

1. VCPs provide a better user interface than CPPs. If the user prompts the command, a VCP presents error messages to the command-prompt screen. This leaves the screen and its offending parameter displayed for the user to modify. When validity code is placed in the CPP, the command-prompt screen disappears.

2. When you submit a command to batch using the Submit Job (SBMJOB) command, the VCP executes before the batch job is placed on the job queue. This eliminates an aborted batch job and the need to consult a job log. When the job becomes active, the VCP executes a second time. If the command is waiting on the job queue or the job queue is held, and conditions change before the job starts, the system checks the conditions again through the VCP.

3. The VCP and the CPP can be written in different languages. For example, it is often true that the CPP is not written in CL, and you need to use CL commands to perform your validity checking. The VCP can be written in CL to provide an easier interface to command execution than an RPG or other non-CL program.

4. VCPs modularize your application design.

All of the benefits listed above help make the CLROBSMSG utility better- designed and easier to use than if I had not used a VCP.

The only argument against VCPs (that I can think of) is that the VCP requires you to pass and declare the parameters from the command in two places: the VCP and the CPP.

Think about using a VCP the next time you create a command. For more information on VCPs, see "Writing AS/400 Commands," MC, March 1993, or the CL Programmer's Guide.


Message Queue Housekeeper

Figure 1 CLROBSMSG Command Specifications

 /*==================================================================*/ /* To compile: */ /* */ /* CRTCMD CMD(XXX/CLROBSMSG) PGM(XXX/OBS001RG) + */ /* SRCFILE(XXX/QCMDSRC) VLDCKR(XXX/OBS001CL) */ /* */ /*==================================================================*/ CLROBSMSG: CMD PROMPT('Clear Obsolete Messages') PARM KWD(MSGQ) TYPE(QUAL1) MIN(1) PROMPT('Message + queue') QUAL1: QUAL TYPE(*NAME) LEN(10) QUAL TYPE(*NAME) LEN(10) DFT(*LIBL) + SPCVAL((*LIBL)) PROMPT('Library') 
Message Queue Housekeeper

Figure 2 Validity Checking Program OBS001CL

 /*==================================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/OBS001CL) SRCFILE(XXX/QCLSRC) */ /* */ /*==================================================================*/ OBS001CL: + PGM PARM(&QUALMSGQ) DCL VAR(&MSGQ) TYPE(*CHAR) LEN(10) DCL VAR(&MSGQLIB) TYPE(*CHAR) LEN(10) DCL VAR(&QUALMSGQ) TYPE(*CHAR) LEN(20) DCL VAR(&MSGTXT) TYPE(*CHAR) LEN(132) DCL VAR(&MSGTEXT) TYPE(*CHAR) LEN(137) MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(ABORT)) CHGVAR VAR(&MSGQ) VALUE(%SST(&QUALMSGQ 1 10)) CHGVAR VAR(&MSGQLIB) VALUE(%SST(&QUALMSGQ 11 10)) CHKOBJ OBJ(&MSGQLIB/&MSGQ) OBJTYPE(*MSGQ) ALCOBJ OBJ((&MSGQLIB/&MSGQ *MSGQ *EXCL)) WAIT(0) DLCOBJ OBJ((&MSGQLIB/&MSGQ *MSGQ *EXCL)) GOTO CMDLBL(ENDPGM) ABORT: + RCVMSG MSGTYPE(*EXCP) MSG(&MSGTXT) CHGVAR VAR(&MSGTEXT) VALUE('0000' *BCAT &MSGTXT) SNDPGMMSG MSGID(CPD0006) MSGF(QCPFMSG) MSGDTA(&MSGTEXT) + MSGTYPE(*DIAG) SNDPGMMSG MSGID(CPF0002) MSGF(QCPFMSG) MSGTYPE(*ESCAPE) ENDPGM: + ENDPGM 
Message Queue Housekeeper

Figure 3 Command Processing Program OBS001RG

 *=============================================================== * To compile: * * CRTRPGPGM PGM(XXX/OBS001RG) SRCFILE(XXX/QRPGSRC) * *=============================================================== *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 IMSGBUF DS I B 1 40BYTRTN I B 5 80BYTAVL I 20 21 MSGTYP I 22 25 CURKEY I 56 81 QJOBNM IJOBBUF DS I 51 60 JOBSTS IERROR DS I I 0 B 1 40BYTPRV I DS I I 81 B 1 40MILEN I I 60 B 5 80JILEN I I 0 B 9 120MWT C *ENTRY PLIST C PARM QMSGQ 20 C MOVEL'*TOP' MSGKEY 4 C EXSR RCVMSG C EXSR CHKMSG * C BYTRTN DOWNE8 C BYTAVL ANDNE0 C EXSR RCVMSG C INQKEY IFNE *BLANKS C EXSR RMVMSG C ENDIF C EXSR CHKMSG C ENDDO * C MOVEL*ON *INLR *================================================================ C RCVMSG BEGSR *================================================================ C CALL 'QMHRCVM' 50 C PARM MSGBUF C PARM MILEN C PARM 'RCVM0200'FMT 8 C PARM QMSGQ C PARM '*NEXT' MTYPE 10 C PARM MSGKEY C PARM MWT C PARM '*SAME' MSGACT 10 C PARM ERROR C MOVELCURKEY MSGKEY C ENDSR *================================================================ C CHKMSG BEGSR *================================================================ C MSGTYP IFEQ '05' C MOVELMSGKEY INQKEY C EXSR RTVJOB C ENDIF C ENDSR *================================================================ C RTVJOB BEGSR *================================================================ C CALL 'QUSRJOBI' 50 C PARM JOBBUF C PARM JILEN C PARM 'JOBI0100'FORMAT 8 C PARM QJOBNM C PARM *BLANKS INTJID 16 C *IN50 IFEQ *OFF C JOBSTS ANDEQ'*ACTIVE' C MOVEL*BLANKS INQKEY C ENDIF C ENDSR *================================================================ C RMVMSG BEGSR *================================================================ C CALL 'QMHRMVM' 50 C PARM QMSGQ C PARM INQKEY 4 C PARM '*BYKEY' MSGTRM 10 C PARM ERROR C MOVEL*BLANKS INQKEY C ENDSR *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 
BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

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: