02
Sat, Nov
2 New Articles

The CL Corner: Understanding the CHKKILL Program

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

Register and validate the Command Analyzer Change exit point.

 

This article is the third in a series that discusses how to use proxy commands and the Command Analyzer Change exit point. Before reading this article, you may find it beneficial to review the two prior articles:

 

 

In the last article, you saw the source for the Check for KILL exit program CHKKILL, but we had not had the opportunity to examine the program in detail. We'll start doing so now. The approach we'll take is to step through the processing flow of the program, explaining any new data definitions as we encounter them. For space reasons, the source for program CHKKILL is not being repeated in this article, so you may want to refer to the previous article.

 

To best understand some of the initial checks being done by the CHKKILL program, let's see how you tell the operating system that you want the CHKKILL program to be called whenever the ENDJOB command might be run.

To register CHKKILL with the Command Analyzer Change exit point, you use the following command:

 

ADDEXITPGM EXITPNT(QIBM_QCA_CHG_COMMAND) FORMAT(CHGC0100) PGMNBR(*LOW)

     PGM(VINING/CHKKILL) PGMDTA(*JOB 20 'ENDJOB    QSYS      ')

 

Running this Add Exit Program (ADDEXITPGM) command  will cause the system to immediately start calling the exit program VINING/CHKKILL whenever the IBM-provided ENDJOB command is about to be run.

 

The exit point QIBM_QCA_CHG_COMMAND is a system-provided exit point that allows a user exit program to change a command prior to the running of the command. The PGMDTA parameter defines which command you are registering for. In your case, it's the ENDJOB command, which is entered as a 10-byte, blank padded value. The library where the ENDJOB command is located is also entered as a 10-byte, blank padded value immediately following the command name. Incidentally, there is also the exit point QIBM_QCA_RTV_COMMAND, which you can use to have a user exit program be called when a command might be run, but it doesn't provide the capability to change the command. A very handy capability for selective command auditing!

 

The above ADDEXITPGM command also tells the exit point QIBM_QCA_CHG_COMMAND that the information passed to the CHKKILL program should conform to format CHGC0100, the format we discussed in the previous article.

 

With that out of the way, now let's look at the flow of the CHKKILL program.

 

Upon entry to the program, CHKKILL first attempts to verify that it is being called correctly. This is done by first checking to see if the exit point name, &EP_Name of the &Chg_Info parameter, is QIBM_QCA_CHG_COMMAND. If it isn't, CHKKILL sends the escape message PRX1001 to the caller of CHKKILL. The PRX1001 message was created in the last article and has three replacement variables. One variable, &ErrEP_Name, is used to indicate what exit point called CHKKILL in error. The actual sending of the escape message (which is identified by the variable &MsgID) and the setting of the other two replacement variables is done by the SndErrMsg subroutine.

 

Now the first thing that might go wrong with CHKKILL is that it might be called incorrectly with no parameters at all. This could happen if someone simply went to the command line and entered CALL CHKKILL. In this situation, the "If" check for &EP_Name would fail with the escape message MCH3601 - Pointer not set for location referenced. In this case, the location referenced is variable &EP_Name as the &Chg_Info parameter was not passed, and the variable &EP_Name is defined as a subfield of the &Chg_Info parameter. To prevent CHKKILL from ending abnormally due to the MCH3601 message, we have a global MonMsg declared, monitoring for any CPF or MCH escape message. If this monitor gets control, then control is passed to the label CatchAll, which in turn sends the message PRX1099 using the SndErrMsg subroutine. This message simply tells the user that CHKKILL ended unexpectedly and directs the user to see previous messages in the job log for the reason.

 

The SndErrMsg subroutine represents shared logic related to the sending of PRXxxxx escape messages. All of the PRXxxxx messages have replacement variables &1 and &2, which represent the sending program name and program library name, respectively. So the first objective of the SndErrMsg subroutine is to get this program-related information. It does this by using the Materialize Program Name machine interface (MI) instruction MATPGMNM, which is documented here. The MATPGMNM instruction returns the bound program name, bound service program, or Java program in which the current procedure is running. Note that while there are other ways to obtain the currently running program name (sending a message, receiving the message, and determining who originally sent the message--which would be your program; retrieving the call stack and finding your entry; etc.), MATPGMNM will by far be the fastest.

 

The MATPGMNM instruction has one parameter. In the CHKKILL program, we have defined the relevant fields of this parameter with the structure &Pgm_Struct. If you look at the &Pgm_Struct structure, you may notice a few things that seem to be wrong--namely, the program and library name are defined as being 30 bytes long! This is the correct definition. At the MI, object names can indeed be 30 bytes. It is the operating system that, for the most part, only allows you to use 10-byte names. In addition, if you look at the MI instruction documentation, you will see several uses of the word "context." At the MI, "context" is essentially the same as what we normally think of as a library.

 

The structure &Pgm_Struct is used for both input and output to the MATPGMNM instruction. On input, you provide the size of the structure in the field &BytPrv (Bytes provided), and MATPGMNM returns to you those fields of &Pgm_Struct that will fit within the number of bytes you provided. As an input to the instruction, &Pgm_Struct also has some reserved fields, and these fields need to be initialized to x'00'. Rather than typing in initial values (the VALUE keyword on the DCL CL statement) of x'00' for the various fields, I prefer to simply set the entire structure to x'00'. CHKKILL does this using the Propagate Byte MI instruction PROPB, which is documented here. PROPB will propagate a given character value across as many bytes as you want. In the case of CHKKILL, the statement below moves &Size_MatPG x'00's to the variable &Pgm_Struct.

 

             CallPrc    Prc('_PROPB') Parm((&Pgm_Struct) +         

                          (x'00' *ByVal) (&Size_MatPG *ByVal))     

And just what is the value of &Size_MatPG? It is set to the allocated size (80 bytes) of &Pgm_Struct due to the immediately preceding RtvVarSiz (Retrieve Variable Size) command:

 

             RtvVarSiz  Var(&Pgm_Struct) Size(&Size_MatPG) 

 

As a reminder, if you do not have the RtvVarSiz command on your system, refer to the article "Just How Big Is That Variable?" for the command definition and command processing source.

 

As a tip, you can use PROPB anytime you need to move the same character repetitively into a variable. For instance, if you wanted to move asterisks ('*') into the first 20 bytes of variable &TextLine, you could do this:

 

             CallPrc    Prc('_PROPB') Parm((&TextLine) +         

                          ('*' *ByVal) (&Size_TL *ByVal))     

 

 

Here, &Size_TL is defined as a 4-byte integer with a value of 20. This certainly beats having to type in 20 asterisks and then count them umpteen times to make sure you have exactly 20! Likewise, if you wanted to move asterisks into the 20 bytes of variable &TextLine starting at position 30, you could do this:

 

             CallPrc    Prc('_PROPB') Parm((&Ptr_TL *ByVal) +         

                          ('*' *ByVal) (&Size_TL *ByVal))     

 

Here, &Ptr_TL is a pointer whose value addresses the 30th position (an offset value of 29) of &TextLine. You can also use a variable for the second parameter of PROPB rather than a literal value such as '*'. In this case, the variable would be defined as a *CHAR field with a length of 1.

 

Having initialized &Pgm_Struct to x'00's, SndErrMsg then sets the &BytPrv field to the allocated size of &Pgm_Struct and runs the MATPGMNM instruction. SndErrMsg then sets the PRXxxxx &1 and &2 message replacement variables to the first 10 bytes of the returned program and program library name, respectively, and sends the escape message identified by the variable &MsgID. Being an escape message, CHKKILL will not regain control after the Send Program Message (SNDPGMMSG) command runs. The program will have ended.

 

When sending the escape message, SndErrMsg passes the structure &ErrMsgDta for replacement data associated with each message. In looking at &ErrMsgDta, you will notice that all of the unique replacement variables for the PRXxxxx messages start at position 21 of the structure. CHKKILL is using the V5R4 STG(*DEFINED) support to redefine positions 21 through 40 to the appropriate data type for unique replacement values that are associated with each error message.

 

Having looked at SndErrMsg, we will now return to the mainline of CHKKILL.

 

After verifying that CHKKILL was called by the exit point QIBM_QCA_CHG_COMMAND, CHKKILL then also validates that the Change command exit information parameter does conform to format CHGC0100 and that the command being processed is ENDJOB. If either validation fails, an appropriate error message is sent, again using the SndErrMsg subroutine.

 

At this point, we are ready to start processing the Change command exit information data associated with the ENDJOB command to be run. This processing will be the focus of the next article as I'm already about 1000 words over the suggested size of an article.... 

More CL Questions?              

Wondering how to accomplish a function in CL? Send your CL-related questions to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll try to answer 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: