Practice problem for commitment control

 

This practice problem might help you understand commitment control and its requirements. These steps assume that you are familiar with the i5/OS® licensed program, the data file utility (DFU), and this topic collection.

By using the code examples, you agree to the terms of the Code license and disclaimer information. Before beginning this problem, follow these prerequisite steps:

  1. Create a special library for this practice problem. In the instructions, the library is called CMTLIB. Substitute the name of your library where you see CMTLIB.

  2. Create source files and a job description.

To use commitment control, follow these steps:

  1. Create a physical file named ITMP (item master file). The data description specification (DDS) for this file is as follows: 
    10    A    R ITMR 20    A      ITEM     2
30    A      ONHAND   5   0
40    A    K ITEM

  2. Create a physical file named TRNP (transaction file). This file is used as a transaction log file. The DDS for this file is as follows: 
    10    A    R TRNR 20    A      QTY     5  0
30    A      ITEM    2
40    A      USER    10

  3. Create a logical file named TRNL (transaction logical). This file is used to assist in starting the application again. The USER field is the type LIFO sequence. The DDS for this file is as follows: 
    10                        LIFO 20    A     R TRNR        PFILE (TRNP)
30    A     K USER

  4. Enter the STRDFU command, and create a DFU application named ITMU for the ITMP file. Accept the defaults offered by DFU during the application definition.

  5. Type the command CHGDTA ITMU and enter the following records for the ITMP file:

    Item On hand
    AA 450
    BB 375
    CC 4000

  6. End the program using F3. This entry provides some data against which the program will operate.

  7. Create the CL program Item Process (ITMPCSC) as follows: 
    PGM DCL &USER *CHAR LEN(10)
RTVJOBA USER(&USER)
CALL ITMPCS PARM(&USER)
ENDPGM

    This is the control program that calls the ITMPCS program. It retrieves the user name and passes it to the processing program. This application assumes that unique user names are used.

  8. Create a display file named ITMPCSD from the DDS as follows.

    There are two formats, the first for the basic prompt display and the second to allow the operator to review the last transaction entered. This display file is used by the ITMPCS program. 

    SEQNBR *... ... 1 ... ... 2 ... ... 3 ... ... 4 ... ... 5 ... ... 6 ... ... 7 ..
 
  1.00      A          R PROMPT   2.00      A                                      CA03(93 'End of program')
  3.00      A                                      CA04(94 'Review last')
  4.00      A                                      SETOFF(64 'No rcd to rvw')
  5.00      A                                  1  2'INVENTORY TRANSACTIONS'
  6.00      A                                  3  2'Quantity'
  7.00      A            QTY            5  0I    +1
  8.00      A  61                                  ERRMSG('Invalid +
  9.00      A                                      quantity' 61)
 10.00      A                                    +5'ITEM'
 11.00      A            ITEM           2    I   +1
 12.00      A  62                                  ERRMSG('Invalid +
 13.00      A                                      Item number' 62)
 14.00      A  63                                  ERRMSG('Rollback +
 15.00      A                                      occurred' 63)
 16.00      A  64                             24  2'CF4 was pressed and +
 17.00      A                                      there are no +
 18.00      A                                      transactions for +
 19.00      A                                      this user'
 20.00      A                                      DSPATR(HI)
 21.00      A                                 23  2'CF4 Review last +
 22.00      A                                      transaction'
 23.00      A          R REVW  24.00      A                                  1  2'INVENTORY TRANSACTIONS'
 25.00      A                                    +5'REVIEW LAST TRANSACTION'
 26.00      A                                  3  2'Quantity'
 27.00      A            QTY            5  0     +1EDTCDE(Z)
 28.00      A                                    +5'Item'
 29.00      A            ITEM           2        +1

  9. Study the logic flow provided in Logic flow for the practice program for commitment control.

  10. Enter the STRSEU command and type the source as follows: 
    SEQNBR *... ... 1 ... ... 2 ... ... 3 ... ... 4 ... ... 5 ... ... 6 ... ... 7 ..
 
  1.00      FITMP    UF  E           K        DISK   2.00      F*                                             KCOMIT   3.00      FTRNP    O   E                    DISK   4.00      F*                                             KCOMIT   5.00      FTRNL    IF  E           K        DISK   6.00      F            TRNR                              KRENAMETRNR1
  7.00      FITMPCSD  CF E                    WORKSTN   8.00      C* Enter parameter with User name for -TRNP- file   9.00      C           *ENTRY    PLIST  10.00      C                     PARM           USER   10
 11.00      C           LOOP      TAG  12.00      C                     EXFMTPROMPT  13.00      C* Check for CF3 for end of program  14.00      C   93                DO                              End of Pgm  15.00      C                     SETON                     LR  16.00      C                     RETRN  17.00      C                     END  18.00      C* Check for CF4 for review last transaction  19.00      C   94                DO                              Review last  20.00      C* Check for existence of a record for this user in -TRNL- file  21.00      C           USER      CHAINTRNR1                64    Not found  22.00      C   64                GOTO LOOP  23.00      C                     EXFMTREVW  24.00      C                     GOTO LOOP  25.00      C                     END  26.00      C* Access Item record  27.00      C           ITEM      CHAINITMR                 62    Not found  28.00      C* Handle -not found- Condition  29.00      C   62                GOTO LOOP  30.00      C* Does sufficient quantity exist  31.00      C           ONHAND    SUB  QTY       TEST    50   61  Minus  32.00      C* Handle insufficient quantity  33.00      C    61               DO  34.00      C* Release Item record which was locked by the CHAIN for update  35.00      C                     EXCPTRLSITM  36.00      C                     GOTO LOOP  37.00      C                     END  38.00      C* Change ONHAND and update the Item record  39.00      C                     Z-ADDTEST      ONHAND  40.00      C                     UPDATITMR  41.00      C* Test for Special Simulation Conditions  42.00      C           ITEM      IFEQ 'CC'
 43.00      C*      Simulate program need for rollback  44.00      C           QTY       IFEQ 100
 45.00      C                     SETON                     63    Simult Rlbck  46.00      C*                    ROLBK  47.00      C                     GOTO LOOP  48.00      C                     END  49.00      C*      Simulate an abnormal program cancellation by Div by zero  50.00      C*        Operator Should respond -C- to inquiry message  51.00      C           QTY       IFEQ 101
 52.00      C                     Z-ADD0         ZERO    30
 53.00      C           TESTZ     DIV  ZERO      TESTZ   30       Msg occurs  54.00      C                     END  55.00      C*      Simulate an abnormal job cancellation by DSPLY.
 56.00      C*        Operator Should System Request to another job  57.00      C*         and cancel this one with OPTION(*IMMED)
 58.00      C           QTY       IFEQ 102
 59.00      C           'CC=102'  DSPLY                           Msg occurs  60.00      C                     END  61 00      C                     END                             ITEM=CC  62.00      C* Write the -TRNP- file  63 00      C                     WRITETRNR  64.00      C* Commit the update to -ITMP- and write to -TRNP-
 65.00      C*                    COMIT  66.00      C                     GOTO LOOP  67.00      OITMR    E                RLSITM

  11. Enter the CRTRPGPGM command to create program ITMPCS from the source entered in the previous step.

  12. Type the command CALL ITMPCSC, press Enter, and press F4. A message states that there are no entries for this operator.

  13. Enter the following data to see if the program operates correctly:

    Quantity Item
    3 AA
    4 BB

  14. Press F4. The review display shows the BB item last entered. Enter the following data:

    Quantity Item
    5 FF (Invalid item number message occurs.)
    9000 BB (Insufficient quantity error message occurs.)
    100 CC (Rollback message occurs.)
    102 CC (RPG DSPLY operation must occur. Press the Enter key.)
    101 CC (The program must display an inquiry message stating that a divide by zero condition has occurred or end, depending on the setting of job attribute INQMSGRPY. If the inquiry message appears, enter C to cancel the RPG program and then C to cancel the CL program on the subsequent inquiry. This simulates an unexpected error condition.)

  15. Type the Display Data command DSPDTA ITMP.

    See if the records AA and BB have been updated correctly. The values must be AA = 447, BB = 371, and CC = 3697. Note that the quantities subtracted from CC occurred, but the transaction records were not written.

  16. Create a journal receiver for commitment control. Use the Create Journal Receiver (CRTJRNRCV) command to create a journal receiver called RCVR1 in the CMRLIB library. Specify a threshold of at least 5000KB. A larger threshold is recommended if your system has sufficient space in order to maximize the time between generation of new journal receivers to minimize the performance impacts of too frequent change journals.

  17. Create a journal for commitment control. Use the Create Journal (CRTJRN) command to create a journal called JRNTEST in the CMTLIB library. Because this journal is used only for commitment control, specify MNGRCV(*SYSTEM) DLTRCV(*YES). For the JRNRCV parameter, specify the journal receiver that you created in step 16.

  18. Use the Start Journal Physical File (STRJRNPF) command with the parameters FILE(CMTLIB/ITMP CMTLIB/TRNP) JRN(CMTLIB/JRNTEST) to journal the files to be used for commitment control.

    The IMAGES parameter uses a default of *AFTER, meaning that only after-image changes of the records appear in the journal. The files ITMP and TRNP have now started journaling.

    Normally, you save the files after starting journaling. You cannot apply journaled changes to a restored file that does not have the same JID as the journal entries. Because this practice problem does not require you to apply journaled changes, you can skip saving the journaled files.

  19. Type the command CALL ITMPCSC and enter the following transactions:

    Quantity Item
    5 AA
    6 BB

    End the program by pressing F3.

  20. Type the Display Journal command: DSPJRN CMTLIB/JRNTEST.

    Note the entries appearing in the journal. The same sequence of entries (R UP = update of ITMP followed by R PT = record added to TRNP) occurs in the journal as was performed by the program. This is because a logical file is defined over the physical file TRNP and the system overrides the RPG default. If no logical file existed, the RPG assumption of SEQONLY(*YES) is used, and a block of PT entries appear because the records are kept in the RPG buffer until the block is full.

  21. Change the CL program ITMPCSC as follows (the new statements are shown with an asterisk). 
         PGM      DCL &USER *CHAR LEN(10)
     RTVJOBA USER(&USER)
*    STRCMTCTL LCKLVL(*CHG)
     CALL ITMPCS PARM(&USER)
*    MONMSG MSGID(RPG9001) EXEC(ROLLBACK)
*    ENDCMTCTL      ENDPGM

    The STRCMTCTL command sets up the commitment control environment. The LCKLVL word specifies that records read for update but not updated can be released during the transaction. The MONMSG command handles any RPG escape messages and performs a ROLLBACK in case the RPG program abnormally ends. The ENDCMTCTL command ends the commitment control environment.

  22. Delete the existing ITMPCSC program and create it again.

  23. Change the RPG program to remove the comment symbols at statements 2.00, 4.00, 46.00, and 65.00. The source is now ready for use with commitment control.

  24. Delete the existing ITMPCS program and create it again. The program is now ready to operate under commitment control.

  25. Type the command CALL ITMPCSC and the following transactions:

    Quantity Item
    7 AA
    8 BB

  26. Use System Request and request the option to display the current job. When the Display Job display appears, select option 16 to request the display of the commitment control status.

    Note the values on the display. There must be two commits because two commit statements were run in the program.

  27. Press F9 to see a list of the files under commitment control and the amount of activity for each file.

  28. Return to the program and end it by pressing F3.

  29. Type DSPJRN CMTLIB/JRNTEST and note the entries for the files and the special journal entries for commitment control:

    Entry Meaning
    C BC STRCMTCTL command occurred.
    C SC Start commit cycle. This occurs whenever the first database operation in the transaction causes a record to be inserted, updated, or deleted as part of commitment control.
    C CM Commit operation has occurred.
    C EC ENDCMTCTL command occurred.

    The commitment control before-images and after-images (R UB and R UP types) automatically occur even though you had originally requested IMAGES(*AFTER) for the journal.

  30. Type the command CALL ITMPCSC and the following transactions:

    Quantity Item
    12 AA
    100 CC (This is the condition to simulate the need for an application use of rollback. The CC record in the ITMP file, which was updated by RPG statement 40.00 is rolled back.)

  31. Press F4 to determine the last transaction entered.

    The last committed transaction is the entry for item AA.

  32. Use System Request and request the Display Current Job option. When the Display Job display appears, request the display of the commitment control status.

    Note the values on the display and how they have been changed by the rollback.

  33. Return to the program.

  34. Return to the basic prompt display and end the program by pressing F3.

  35. Type the command DSPJRN CMTLIB/JRNTEST.

    Note the additional entries that appear in the journal for the use of the rollback entry (C RB entry). When the ITMP record is rolled back, three entries are placed in the journal. This is because any change to the database file under commitment control produces a before (R BR) and after (R UR) entry.

  36. Display the entries with journal code R and these entry types: UB, UP, BR, and UR. Use option 5 to display the full entries. Because the Quantity field is in packed decimal, use F11 to request a hex display. Note the following conditions:

    • The on-hand value of the ITMP record in the UB record

    • How the on-hand value is reduced by the UP record

    • How the BR record is the same as the UP record

    • How the UR record returns the value as originally displayed for the UB record

    The last entry is the RB entry for the end of the rollback.

  37. Type the command CALL ITMPCSC; press Enter; and press F4. Note the last transaction entered.

  38. Type the following transactions:

    Quantity Item
    13 AA
    101 CC (This is the condition to simulate an unexpected error condition, which causes the program to end. The simulation occurs by dividing a field by 0. The program will display an inquiry message or end, depending on the setting of the job attribute INQMSGRPY. If the inquiry message appears, enter C to end the program. Because the CL program was changed to monitor for RPG program errors, the second inquiry which occurred does not occur.)

  39. Type the command DSPJRN CMTLIB/JRNTEST.

    The same type of rollback handling has occurred, but this time the rollback was caused by the EXEC parameter of the MONMSG command in the CL program instead of the RPG program. Display the two RB entries to see which program caused them.

  40. Type the command WRKJOB and write down the fully qualified job name to be used later.

  41. Type the command CALL ITMPCSC and enter the following transaction:

    Quantity Item
    14 AA
    102 CC (The RPG DSPLY operation must occur to the external message queue. Use the System Request key and select option 1 on the system request menu to transfer to a secondary job.)

  42. Sign on to the second job and reestablish your environment.

  43. Type the command ENDJOB and specify the fully qualified job name identified earlier and OPTION(*IMMED). This simulates an abnormal job or system end.

  44. Wait about 30 seconds, type the command CALL ITMPCSC and press F4.

    Note the last committed transaction. It must be the AA item entered earlier.

  45. Return to the basic prompt display and end the program by pressing F3.

  46. Type the command DSPJRN CMTLIB/JRNTEST.

    The same type of rollback handling has occurred, but this time the rollback was caused by the system instead of one of the programs. The RB entry was written by the program QWTPITPP, which is the work management abnormal end program.

You have now used the basic functions of commitment control. You can proceed with commitment control on your applications or try some of the other functions such as:

 

Parent topic:

Scenarios and examples: Commitment control