You are on page 1of 8

1

Journaling and Commitment Control What journaling is and how it works Journaling, generally speaking, is a process of recording activity. In accounting, it is the process of recording financial activity -- monies in and monies out. On the iSeries, journaling refers to the process of recording object activity. Journaling on the iSeries typically involves the recording of the activity related to files, namely, physical files. When a file is being journaled, activity such as file-opens, file-closes and data updates are recorded. For example, when a program writes out a new record or updates an existing one, the system makes an entry in the associated journal. The entry contains such information as the job name and program name that made the change(s) to the file, as well as a copy of the record that was changed. (Note: Journaling can be configured to record a copy of the record before it is changed and/or to record a copy of the record after it is changed.) How to set up journaling in three easy steps

1. Create one or more journal receivers. Use the Create Journal Receiver
(CRTJRNRCV) command to create a journal receiver. Think of the journal as a notebook binder and the journal receiver as the pages (i.e., the notebook paper where information is written). The journal receiver is where the journal entries are actually recorded. The journal "connects" the receiver to the file. It's a good habit to name the journal receiver the same as the journal, plus a numeric suffix such as 0 or 1. (See the next step on what to name the journal.) Also, you should put journal receivers in the same library as the file. (This is very important in order to simplify recovery procedures, which we will discuss in Part III.) For maximum protection, consider storing the journal receiver in a different ASP than the file so that their storage will not be on the same disk unit. 2. Create a journal. Use the Create Journal (CRTJRN) command to create a journal and specify the receiver created in step 1. Although you can journal multiple files to the same journal (and, in some cases, that is actually preferable), you will generally want to have a journal "serving" a single file. A good practice is to name the journal the same as the file and put it in the same library as the file, but store it in the same ASP as the journal receiver. 3. Start journaling the file. This is done by using the Start Journal Physical File (STRJRNPF) command. This is how you associate a file to a journal. Once the association is made, the system will record in the journal receiver a copy of any record added, updated or deleted from the file. Other activity, such as when the file is opened and closed, can also be recorded in the journal receiver if you choose by selecting the appropriate options on the STRJRNPF command. For more information on the journal commands mentioned above and other journal-related commands, please see the subsequent section Four basic journal entry categories ( J F R C) The most common journal entries fall into four basic categories. Each category is represented by a one-character code (shown in parenthesis in the following list). Within each category are a number of different journal entry types. Each journal entry type is represented by a two-character entry code (also shown in parenthesis within the category descriptions below).

2 1. Journal and journal receiver operations (J). These include such things as references to
the previous receiver (PR) or the next receiver (NR) in a chain. Also, at IPL-time, an entry is made (e.g., an IN entry for IPL after normal end) marking a critical chronological boundary in the file activity. 2. File operations (F). This category includes file opens (OP) and file closes (CL). 3. Record operations (R). Record updates (UP), deletes (DL), and new records written (PT and PX) all fall into this category. 4. Commitment control (C). Anything related to commitment control falls into this category. Some examples are begin commitment control (BC), start a commit cycle (SC), commit operation (CM) and rollback operation (RB). There are other categories and entry types in addition to those listed above. However, those are what you will come across most often. For a complete listing, see the documentation or online help. Quick reference to journaling commands APYJRNCHG. Uses the journal entries to apply changes that have occurred since a database file was saved or some other specified time. CHGJRN. Use this command to change the attributes of a journal or to attach new journal receivers to a journal. CMPJRNIMG. This command compares and lists the difference between the before-image and after-image of a record, or between the current after-image of a record and the previous afterimage of the record. CRTJRN. Use this command to create a journal. CRTJRNRCV. Use this command to create a journal receiver. DLTJRN. Use this command to delete a journal. DLTJRNRCV. Use this command to delete a journal receiver. DSPJRN. This command displays or prints the journal entries that are in the journal receivers associated with the specified journal. This command has outfile support so you can list the journal entries to a database output file for further processing or analysis. DSPJRNRCVA. Use this command to display the attributes of a journal receiver. ENDJRNPF. This command ends journaling for the specified physical file. RCVJRNE. This command allows a specified user program to continuously receive journal entries one at a time as they are written to the journal. The behavior is similar to an exit program. RMVJRNCHG. Use this command to remove changes that have occurred to a database file from a specified point in time to some previous point in time (allowed only if before-images were recorded during the time).

3
RTVJRNE. Use this command to retrieve a journal entry and place it in CL program variables. SNDJRNE. Use this command to write user-defined entries to a journal (i.e., journal receiver). STRJRNPF. Use this command to start journaling for the physical file. WRKJRN. This command displays a menu from which you can perform many journal-related functions, such as system-assisted recovery of journaled files. WRKJRNA. This command displays the attributes of a journal and the associated receivers. Steps to Journaling and Commitment

Lock level (LCKLVL) : Specifies the default level of record locking that occurs for the commitment definition to be started. This is a required parameter. *CHG Every record read for update (for a file opened under commitment control) is locked. If a record is changed, added, or deleted, that record remains locked until the transaction is committed or rolled back. Records that are accessed for update operations but are released without being changed are unlocked. *CS Every record accessed for files opened under commitment control is locked. A record that is read, but not changed or deleted, is unlocked when a different record is read. Records that are changed, added, or deleted are locked until the transaction is committed or rolled back. *ALL Every record accessed for files opened under commitment control is locked until the transaction is committed or rolled back.

6
WHAT IS COMMITMENT CONTROL? Commitment control is handled by the operating system, but the programmer still has a final say about whether a record (even with bad data) is written to a database file. But if you change your mind, commitment control will definitely make your life easier. Specifically, iSeries commitment control provides a way to process a group of database changes (updates, inserts, or deletes) as a single unit of work (a transaction). This unit of work is atomic, meaning that it's indivisible. It's all or nothing. Commitment control ensures that all of the changes to the files within that transaction/commitment cycle are applied, or, if processing is interrupted before the COMMIT statement is encountered, that all changes within a transaction are removed. Once you see what commitment control can do for you, I believe you will want develop your applications with commitment control in mind. I had known about commitment control for a long time but always avoided it because I thought it was something that was used only in extreme cases, such as in banking transactions in which one account was debited and another was credited, and unless both were processed, accounts could easily become out of balance. I was completely wrong. So let's create an application and walk through all the steps necessary to take advantage of commitment control. By the end of this article, you will be able to decide whether or not to commit in your shop. EASY AS 1-2-3 First, there is one prerequisite, and that is another nice IBM feature called journaling. To take advantage of commitment control, the files have to be journaled. I won't get into journaling in great detail; basically, you create a journal receiver with the CRTJRNRCV command, then a journal with the CRTJRN command, specifying the journal receiver you just created, and finally you start journaling on the file or files, with the STRJRNPF command. Here is the DDS for the file used in this example followed by the command used to create it and the commands to setup the journaling environment: * File Name............. CCTESTPF * ----------------------------------------------------R FCCTESTPF TEXT('CC Test File') * ================================= CCFLD1 5P 0 COLHDG('CC field1') * ----------------------------------------------------CCFLD2 10A COLHDG('CC field2') * ----------------------------------------------------K CCFLD1 * ----------------------------------------------------CRTPF FILE(YourDestinationLibrary/CCTESTPF) SRCFILE(YourSourceFileLibrary/QDDSSRC) First create the journal receiver: CRTJRNRCV JRNRCV(MYJRNRCLIB/MYJRNRCV) Next, create the journal specifying the journal receiver created above: CRTJRN JRN(MYLIB/MYJRN) JRNRCV(MYJRNRCLIB/MYJRNRCV) And, finally, start journaling on the physical file:

7
STRJRNPF FILE(*LIBL/CCTESTPF) JRN(MYLIB/MYJRN) So my file is being journaled. What's next? I am going to work with a very familiar RPG programmer environment, a CL wrapper around an RPG program. Here's the code for the CL wrapper called CCTEST1: PGM STRCMTCTL LCKLVL(*CHG) CALL PGM(*LIBL/CCTEST2) COMMIT CALL PGM(*LIBL/CCTEST2) ROLLBACK ENDCMTCTL RETURN ENDPGM Here's the code for the RPG program CCTEST2: FCCTESTPF UF A E DCOUNTER C C C C C S K DISK COMMIT 5I 0

DO 7 COUNTER EVAL CCFLD1 = COUNTER EVAL CCFLD2 = 'TESTING CC' WRITE FCCTESTPF ENDDO

C EVAL *INLR = *ON C RETURN The CL program establishes a commitment definition with the Start Commitment Control (STRCMTCTL) command. The most important parameter on this command is the lock level. I found *CHG to be the recommended value. It specifies if a record is changed, added, or deleted, that record remains locked until the transaction is committed or rolled back. Records that are accessed for update operations but are released without being changed are unlocked. This parameter value prevents unnecessary record locking. Next, the CL calls program CCTEST2, which opens our physical file, CCTESTPF, under commitment control and writes seven records to it. In RPG, a file is put under commitment control by specifying the COMMIT keyword on the F-spec. To examine the results first hand, and to see how things work step by step, I suggest running the CL program CCTEST1 in debug mode, using the following command (make sure you compile your program to allow debug): STRDBG PGM(*LIBL/CCTEST1) UPDPROD(*YES) OPMSRC(*YES) After starting debug, stop on the COMMIT statement just after the first call to CCTEST2. Sign on to another session and query the CCTESTPF file. You should see the seven records even before they're committed; this is known as uncommitted data. Go back to the session under commitment control and, before hitting the Commit statement, end the debug session with F3 and sign off. Query the file again on the other session, and the records are gone! Start another session, and again put CCTEST1 into debug, but this time stop at the ROLLBACK statement just after the second call to CCTEST2. Query the file on the other session, and you should see 14 records. Continue with your debug session and process the ROLLBACK. Query the file again, and notice that the last seven records added have been removed. That's because the first seven written with the first call to CCTEST2 were committed with the COMMIT command in the CL program;

8
however, the seven records that were written during the second call to CCTEST2 have not yet been committed and therefore were removed with the ROLLBACK command. Are you starting to see the beauty of commitment control? This is great, but what happens when the application or the iSeries abends? Well, that's where the real beauty of commitment control comes in. When an abnormal termination of the program or the machine occurs, the operating system will perform an implicit rollback of the uncommitted changes for you. How cool is that? Once you see how this works, there is no going back to the old Russian Roulette way of "how often does my application abend, anyway?" With commitment control, you don't have to worry about it. It's all or nothing. You can go to meetings with users and managers and make promises you can actually keep! What a novel concept. The example programs in this article were kept very simple in order to concentrate on the concept of commitment control. In the real world, however, commitment control environments can become quite complex and daunting, but if you start small and get comfortable with it, you can take on more complex scenarios. I hope you decide to commit it and forget it!

Summary: Steps CRTJRNRCV CRTJRN STRJRNPF STRCMTCTL COMMIT / ROLLBACK ENDCMTCTL ENDJRNPF *Note: We can not do any operation(Write/update/delete) on the file up to it is Journaled. If we try to Clear the file which is under Commitment Control, it throws the error.

You might also like