24
Sun, Nov
1 New Articles

Update Your Data with Peace of Mind Using Commitment Control

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

Learn how to use commitment control in your RPG programs to ensure a complete transaction and how to roll back the changes when unable to complete.

 

I'm usually talking about powerful IBM i resources that can do great things with minimal work. Commands such as those need to be treated with respect and tested well to ensure that you'll get the expected results. In this article, I'll be taking a step back to talk about some safety measures that you could take to protect the integrity of your data by using commitment control within your code.

 

Commitment control isn't something I've always used, the reason being that I didn't always use journaling on our files until we got a redundant IBM i that was synchronizing the servers using journaling. But, now that we're journaling without a choice, why not use it to its full potential?  Not that I'm saying journaling is a bad thing! It's a great thing!

Journaling

In order to utilize commitment control, you need to journal your file. If you don't journal your file, you won't be able to use any other commitment than *NONE.

 

So how do you know if your file is being journaled?  You could display the object description with the DSPOBJD command as follows:

 

DSPOBJD OBJ(MYFILE) OBJTYPE(*FILE) DETAIL(*FULL) 

 

Page down a few times and you will find the journaling information that could look similar to Figure 1:

 

032112Snyderfigure01 

Figure 1: Find journaling information with DSPOBJD. (Click images to enlarge.)

 

If your file isn't journaled, you could make it be journaled by following these steps:

  1. Create a journal with the CRTJRN command.
  2. Create a journal receiver with the CRTJRNRCV command.
  3. Assign the journal to the file with the STRJRNPF command.

 

You could also create journals using the System i Navigator. The graphical interface changes frequently, but as of the V7R1 client software, I was able to open the Database Navigator by opening the Databases option, right-clicking on the database name and selecting Database Navigator. From the Map menu bar option, go to Create > Journal, as shown in Figure 2.

 

032112Snyderfigure02

Figure 2: Create a journal.

 

Fortunately for me, journaling is handled automatically. Otherwise, it would be an article in itself. If you need more information on setting up journaling, refer to the IBM i 7.1 Information Center.

Starting and Stopping Commitment Control

To use commitment control within your program, you need to start commitment control prior to opening your file, so if you are going to start commitment control within your RPG programs, you will need to manually open them after you start commitment control. You start commitment control with the STRCMTCTL command.

 

When using STRCMTCTL, there are some settings you can change. For the purposes of this article, we'll be using the following settings:

 

  • LCKLVL(*CHG) will lock each record that is opened under commitment control and changed, until the transaction is committed or rolled back.
  • CMTSCOPE(*ACTGRP) specifies that the commitment control is applicable for the current activation group. Once the activation group is ended, all uncommitted records will automatically be rolled back. You could also set the scope to be by the *JOB level.

 

After you have completed all of your transactions, you need to end commitment control to release your files. You end commitment control with the ENDCMTCTL command.

Commit and Roll Back

Commitment control uses the journal to record every record that is changed, added, or deleted. When a file is under commitment control, the changes will not become permanent until it is committed. If a complete series of expected transactions is not as you expect them to be, you can roll back the changes (up to the last commit or rollback), and the changes will be put back to the way they were before. If you have commitment control set at a specific level that ends, either deliberately or unexpectedly, the changes will automatically be rolled back.

 

Suppose you had a process that moved records from one file to another during the billing process to save for historical purposes. Such a process could possibly update several files. For our example, we'll look at a simple one-to-one record move from a WORKING file to a HISTORY file.

 

This could be a two-step process:

  1. Delete from the WORKING file.
  2. Write to the HISTORY file.

 

If your program were to crash during the write to your HISTORY file, the billing record could be lost.

 

Another option would be to switch the order:

  1. Write to the HISTORY file.
  2. Delete from the WORKING file.

 

If your program were to crash during the delete and you ran the process again, you could now accidentally duplicate the record and bill your customer twice.

 

The best option is to ensure that both actions are always performed completely or not at all, which is the purpose of how we'll be using commitment control.

 

I like to start and end commitment control in a CL program that will call the RPG program as follows:

 

             PGM

/* **************************************************************** */

/* CRTBNDCL PGM(MYLIB/MCP050CL) SRCFILE(MYLIB/QCLSRC)               */

/*   DFTACTGRP(*NO) ACTGRP(*NEW)                                    */

/* **************************************************************** */

/* IF YOU DON'T START COMMITMENT CONTROL PRIOR TO OPENING THE FILES */

/* IN THE RPG PROGRAM, YOU WILL GET AN ERROR OPENING THE FILES.  */

/* **************************************************************** */

             STRCMTCTL  LCKLVL(*CHG) CMTSCOPE(*ACTGRP)

             CALL       PGM(MCP050RPG)

             ENDCMTCTL

/*------------------------------------------------------------------*/

 END:        ENDPGM

 

This is a nice, simple CL program with a call to an RPG program for the purpose of starting and ending commitment control. From the comments, you can see that I've created the CL program to be within a *NEW activation group every time it is called, and the commitment scope is at the *ACTGRP level, so all commits and/or rollbacks will be guaranteed to be completed when the CL program exits. Even if the program dies or the job gets ended, you can still be assured that all transactions will be committed or rolled back. There are other ways of using commitment control, but this is the case that we're discussing in this article.

 

Now that the CL is taking care of starting and ending commitment control, we'll write the RPG program that we'll use to read through all of the records in the WORKING file and safely push them into the HISTORY file. Typically, in a situation like this, there would be numerous files involved that could all be under commitment control to ensure every transaction is guaranteed to be complete. And it would also be typical to perform computations on the data prior to writing it into the HISTORY file that would change it from its original value in the WORKING file. But, to keep the program simple, I am merely pushing the data from one file to the other.

 

     H DFTACTGRP(*NO) ACTGRP(*CALLER)

     H INDENT('.') OPTION(*NODEBUGIO: *SRCSTMT) DATFMT(*ISO)

     H Text('Commitment Control - Tom Snyder, MCPressOnline.com')

      ******************************************************************

      * How To Compile:

      * 1) Create the Program

      *     CRTBNDRPG MODULE(MYLIB/MCP050RPG) SRCFILE(MYLIB/QRPGLESRC)

      ******************************************************************

     FWORKING   UF   E           K DISK    commit

     FHISTORY   IF A E           K DISK    commit

     D*

      /free

       setll *START WORKING;

       read WORKING;

       dow NOT %eof(WORKING);

         // Copy Fields, Delete Work, Write Hist

         monitor;

           HISTORNO = WORKORNO;

           HISTITEM = WORKITEM;

           HISTPRIC = WORKPRIC;

           HISTQTY  = WORKQTY;

           delete WORKREC;

           write  HISTREC;

           commit;

         on-error;

           rolbk;

           leave;

         endmon;

         read WORKING;

       enddo;

       *inlr = *ON;

      /end-free

 

The logic in this program is extremely simple, on purpose, to demonstrate the usefulness of commitment control. The program reads through the WORKING file, from the beginning to the end. During each read, it attempts to delete from the WORKING file and write to the HISTORY file.

 

If both operations are successful, the commit command will be executed after the operations and it will continue reading to the end of the file.

 

If a problem were to occur prior to executing the commit command, the monitor block would exit to the on-error section and the code would be rolled back.

 

If the job ends abnormally, or is forced to end prior to the execution of the commit, then the uncommitted transactions would automatically be rolled back, even though the rollback command was not executed.

Commit or Rollback All Records at Once

If you were to remove the commit and rollback commands from the RPG code completely in the example above, then all of the transactions would remain uncommitted until the ENDCMTCTL command was executed in the CL command. If you were to do it this way, you would be presented with options to Commit, Rollback, or Cancel.

  • Cancel keeps the records uncommitted and locked.
  • Rollback resets the records to before you started.
  • Commit applies the updates to the files.

Embedded SQL

The above example is not using embedded SQL, but if you were to use embedded SQL, then you would specify the commitment control information during compile time.

Download the Code

You can download the code used in this article by clicking here.

References

ILE Programmer's Guide—Commitment control concepts

IBM i 7.1 Information Center—Setting up journaling

 

Thomas Snyder

Thomas Snyder has a diverse spectrum of programming experience encompassing IBM technologies, open source, Apple, and Microsoft and using these technologies with applications on the server, on the web, or on mobile devices.

Tom has more than 20 years' experience as a software developer in various environments, primarily in RPG, Java, C#, and PHP. He holds certifications in Java from Sun and PHP from Zend. Prior to software development, Tom worked as a hardware engineer at Intel. He is a proud United States Naval Veteran Submariner who served aboard the USS Whale SSN638 submarine.

Tom is the bestselling author of Advanced, Integrated RPG, which covers the latest programming techniques for RPG ILE and Java to use open-source technologies. His latest book, co-written with Vedish Shah, is Extract, Transform, and Load with SQL Server Integration Services.

Originally from and currently residing in Scranton, Pennsylvania, Tom is currently involved in a mobile application startup company, JoltRabbit LLC.


MC Press books written by Thomas Snyder available now on the MC Press Bookstore.

Advanced, Integrated RPG Advanced, Integrated RPG
See how to take advantage of the latest technologies from within existing RPG applications.
List Price $79.95

Now On Sale

Extract, Transform, and Load with SQL Server Integration Services Extract, Transform, and Load with SQL Server Integration Services
Learn how to implement Microsoft’s SQL Server Integration Services for business applications.
List Price $79.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: