02
Sat, Nov
2 New Articles

The API Corner: One Approach to System Automation

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

Learn how to use watch support to automate system operations.

 

Over the last several months, I've received many notes from readers, including these:

 

  • I have some custom routines that need to run when a Daylight Saving Time change goes into effect. How can I have these programs run automatically?
  • There is one user profile that the system operator is always re-enabling.... Is there a way to automate this?
  • We have a program that periodically reads QHST files to see what files need to be reorganized...maintain record sequence...based on CPF4653.... Is there a way to avoid scanning QHST?

These notes may initially appear to be unrelated, but all of these questions, and more that I haven't listed above, can be addressed by one common facility that is provided with the i operating system. That facility is the watch support introduced with V5R4. Watch support essentially allows you to tell the system that if a particular message (or list of messages) is sent to a specific message queue (or a list of message queues), then the system should call a user exit program. In the case of the three items listed above, the messages that we would be interested in are these, respectively:

  • CPD1689--Local system time has been adjusted.
  • CPF1393--Subsystem &1 disabled user profile &2 on device &3.
  • CPF4653--DLTPCT parameter value for member &1 exceeded.

In this series of articles, you will see how to use watch support to automate system operations that are related to these specific messages. The three messages I have selected to use provide us with the ability to learn about various aspects of watch support. When this series of articles completes, you should be able to review the messages that are being sent on your system and determine what automation you might apply to those messages in order to streamline the running of your system. Note that there are alternative solutions available for all three questions. A watch is simply one of the tools that can be used in addressing these user requirements--a tool that I believe is currently underutilized.

 

To start watching for a message, you use the Start Watch (STRWCH) command. If you are currently running V5R4, refer to the STRWCH documentation found here. For V6R1, IBM enhanced the STRWCH command; the appropriate documentation for that release can be found here. The sample programs I will be developing in this series of articles will be based on the V5R4 level of support, though I will, when appropriate, make mention of V6R1 enhancements that would have made life easier for us!

 

The STRWCH command has several parameters. The first parameter, Session ID (SSNID), is required and allows you to name a watch session. You can use the special value *GEN to have the system generate a name, but I recommend that you provide a meaningful name based on either the message being watched or the function being performed. For instance, if CPD1689 ("Local system time has been adjusted.") is the watched-for message, then it may make sense to name the watch session something such as CPD1689 or TIME_CHG. Jumping ahead a bit, I will point out that I selected TIME_CHG rather than DST_CHG as message CPD1689 can be sent for reasons other than a Daylight Saving Time (DST) adjustment. The Cause text for CPD1689 mentions for instance that a change in the QTIMZON system value can also cause a local system time adjustment. Later, I'll show you how to distinguish between a DST-initiated time adjustment and a QTIMZON system value-initiated time adjustment.

 

The session name will show up in several areas of the system. When you start a watch session, the system actually starts a new job for each watch session. The session name is used for the job name portion of the new qualified job name, so it will appear on commands such as WRKACTJOB and WRKSBMJOB. There are also watch-related commands, such as End Watch (ENDWCH) and Work with Watches (WRKWCH), that use the Session ID to identify a watch session. Using a meaningful session name can simplify your life when working with jobs on the system. While each started watch is a separate job on your system, you should not be too concerned. The watch exit program will not consume any CPU unless a watched-for message is sent. From a limits point of view, you can have up to 10,000 watches concurrently started on a system.

 

A second required parameter of the STRWCH command is the Watch program (WCHPGM). This parameter identifies the user exit program to call when a watch condition is met. We will look at how to develop these user exit programs in great detail throughout this series of articles.

 

The other parameters of the STRWCH command are optional. Below, I call out those optional parameters that we will be using in our review of the watch support.

 

One optional parameter that we will be using is Watch for message (WCHMSG). This parameter allows you to specify up to five watched-for message identifiers. If you need more than five messages in one session, the Start Watch (QSCSWCH) API documented here for V5R4 allows you to specify up to 100 messages.

 

In addition to specifying what message(s) to watch for, the WCHMSG parameter also allows you to provide comparison data for further filtering on when the exit program should be called. Comparison data allows you to tell the system to not just call the exit program when a particular message is sent, but to only call the exit program when a particular message is sent and when replacement data associated with the message being sent contains a specific text string. We will not be using this comparison data feature in the watch session for CPD1689 but will revisit this capability when watching for the message CPF1393 in the third article of this series.

 

You might have been surprised to see that the watched-for messaged IDs are optional when starting a watch. The reason is that you can start a watch for system activity other than just messages. You can, for instance, start a watch for a particular Licensed Internal Code (LIC) log entry or, using one of the V6R1 enhancements, for a Product Activity Log (PAL) entry. We will not be looking any further at LIC log entries or PAL entries as most users will never start a watch for these types of activities on the system, but I do want to point them out as a few users may want to take advantage of this support. It is this generalized nature of watch support that causes the system exit point to be named "Watch for Event" rather than "Watch for Message."

 

 

For the same reason WCHMSG is optional, the Watch message queue (QCHMSGQ) parameter of STRWCH is also optional. This parameter, when watching for a message, allows you to indicate where to watch for the message. There are special values such as *SYSOPR for the system operator message queue QSYSOPR in library QSYS, *HSTLOG for the QHST message queue, and *JOBLOG for messages sent to jobs on the system. Additionally, you can provide the name of a specific message queue.

 

 

As an aside for those of you who may currently be searching QHST history files for various messages, with watch support the exit program is called when the message is sent to the QHST queue. This provides for a more real-time notification of the message and, from a performance point of view, does not require the system to copy any messages to the QHST log files.

 

Likewise, while we will not be using the *JOBLOG watch support, you should be aware that you can watch for a message being sent to the job log of a specific job, a list of up to five jobs, *ALL jobs, or jobs identified generically based on the job and/or user name. A very powerful real-time monitor for job-related problems...

 

With this brief introduction to the STRWCH command, and due to being out of room for this month's article, the following program WCHCPD1689 is shown and could be used as a watch exit program for message CPD1689.

 

 

dWchCPD1689       pr                  extpgm('WCHCPD1689')        

d Type                          10    const                       

d SsnID                         10    const                       

d Error                         10                                

d MsgDta                              likeds(ESCQWFM)             

                                                                  

dWchCPD1689       pi                                              

d Type                          10    const                       

d SsnID                         10    const                       

d Error                         10                                

d MsgDta                              likeds(ESCQWFM)             

                                                                  

 /copy qsysinc/qrpglesrc,escwcht                                  

                                                                  

dCPD1689          ds                  based(RplDtaPtr)            

d                                     qualified                   

d MinutesAdj                    10i 0                                 

d ReasonCode                     5i 0                                 

                                                                       

dRplDtaPtr        s               *                                   

                                                                      

dRqdNbrParms      c                   4                                

dSessionName      c                   'TIME_CHG  '                    

                                                                      

dSeePrvMsgs       c                   0                               

dDSTChg           c                   1                               

dSysValChg        c                   2                               

                                                                      

 /free                                                                 

  monitor;  

                                                                                   

  // Check to make sure program environment is as expected            

  if %parms < RqdNbrParms;                                             

     dsply ('WCHCPD1689 received only ' +%char(%parms) + ' parms');   

     *inlr = *on;                                                   

     return;                                                        

  endif;                                                             

                                                                    

  if Type <> '*MSGID';                                              

     dsply ('WCHCPD1689 received type ' + Type);                    

     Error = '*ERROR';                                              

     *inlr = *on;                                                   

     return;                                                        

  endif;                                                             

                                                                    

  if SsnID <> SessionName;                                          

     dsply ('WCHCPD1689 received SsnID ' + SsnID);                  

     Error = '*ERROR';                                               

     *inlr = *on;                                                   

     return;                                                        

  endif;                                                            

                                                                

  if MsgDta.ESCMID00 <> 'CPD1689';                              

     dsply ('WCHCPD1689 received message ' + MsgDta.ESCMID00);  

     Error = '*ERROR';                                           

     *inlr = *on;                                               

     return;                                                    

  endif;                                                        

                                                                 

  // Everything looks OK so get message replacement data        

  RplDtaPtr = %addr(MsgDta) + MsgDta.ESCORD;                    

                                                                

  // Take appropriate action based on reason code               

  select;                                                       

     when CPD1689.ReasonCode = SeePrvMsgs;                      

          // Examine previous messages in QSYSOPR               

     when CPD1689.ReasonCode = DSTChg;                          

          // Do processing necessary for DST transition         

     when CPD1689.ReasonCode = SysValChg;                  

          // Do any processing needed for QTIMZON change   

     other;                                                 

          dsply ('WCHCPD1689 Reason code ' +               

                 %char(CPD1689.ReasonCode));               

  endsl;                                                   

                                                            

  // Set normal end of processing                          

  Error = *blanks;                                         

  return;                                                  

  on-error;                  

     Error = '*ERROR';       

     *inlr = *on;            

     return;                 

  endmon;                    

                                                                                         

 /end-free                                                 

 

To compile this program into library VINING, you would use this command:

 

CRTBNDRPG PGM(VINING/WCHCPD1689)

 

To start a watch session named TIME_CHG, specifying WCHCPD1689 as the exit program, for message CPD1689 being sent to QHST, you would use this command:

 

STRWCH SSNID(TIME_CHG) WCHPGM(VINING/WCHCPD1689) WCHMSG((CPD1689))

WCHMSGQ((*HSTLOG))

 

To end the watch session named TIME_CHG, use this command:

 

ENDWCH SSNID(TIME_CHG)

 

In the next article, we'll look at the details behind what program WCHCPD1689 is doing. If you are interested in understanding how the program works prior to that, you can start your research with the V5R4 Watch for Event exit program documentation found here. This documentation is where we'll resume in the next article.

 

Before closing though, I would like to discuss my use of the dsply operation in the WCHCPD1689 program. As this article is attempting to introduce watches, and not the proper way to report errors, I have minimized the amount of code in WCHCPD1689 by the use of dsply. My intent is to simply show where error conditions might appear during the processing of a watch exit program. A production-level program should use predefined messages that document appropriate recovery actions, ensure that the messages get logged where support personnel can be easily made aware of the error situation (right now, the dsply messages will be going to QSYSOPR as the watch exit program is running in a batch job), etc. Come to think of it, a discussion of the message handler APIs would make for a good column (or two) in the future....

 

Meanwhile, if you have other API questions, send them to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.

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

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: