Deferred Reporting Using a Snapshot Technique By Tym Stegner What would you do if you needed to preserve a set of records for a routine report, but you also had to update the records as new information arrived? This article explores just such a situation taken from a case study in our support files.
“LOCK Does Not Seem to Be Working…” This message left in the support mailbox was from a CCA customer who was unable to get the LOCK command to cooperate with his reporting responsibilities. The CCA customer uses System 1032 to bill his own customers. Billing was usually done on a monthly basis until recently, when certain customers asked for preliminary bills. This request was honored and presented no problems, until the month when the final bill did not match the preliminary bill. The recipient communicated great consternation to our CCA customer. Accounting research revealed that the recipient’s company data had been updated between the time the preliminary and final bills were generated.
For the preliminary and final bills to match, the records for the preliminary bill must not be updated until the final bill is issued. Some method had to be devised to prevent updates to those records used for the preliminary bill, at the same time continuing to collect update information on those very records. The CCA customer had once used the LOCK command for an application and thought perhaps using this command would solve his problem.
LOCK Command Is Working Properly He wrote an application that selected the proper records and stepped through them one at a time, issuing a LOCK ON RECORD command for each, then closed out the application. To his dismay, this did not prevent other colleagues from updating the records.
Although you might think the LOCK command could solve his problem, it cannot because it is not persistent across sessions. The LOCK command restricts only inter-process access. When the working session ends, the locks are lifted. Furthermore, the LOCK ON RECORD command handles only a single record per dataset at a time. The act of stepping through the dataset removes the lock on the previous record.
Clarifying the Objective and Considering Solutions At least we clarified a mission goal: We needed a way to restrict update access to multiple discontinuous records in a dataset for periods of thirty days, perhaps longer. At the same time, we had to find a way to buffer updates to those same restricted records.
We brainstormed possible solutions. One of my first solutions was to use a variation on a selection set lock mechanism I have used in the past, but that idea fell to the wayside because of the need to make every program and user correctly process lock tokens. (I plan to write more about the selection set lock mechanism in a future article.)
Using a CHANGE Trigger procedure was our next solution idea. The advantage of this idea was that all access to the data would be controlled by the trigger procedure. The disadvantage was that the existing applications still needed to be modified to correctly process lock errors. We decided to reserve this as a back up plan while we tried to think of an easier way. (For more information on using CHANGE trigger procedures, see the phone house webmailCCAPRINT System1032 Developing a trigger-based auditing system August 2000.)
Creating Snapshots Fortunately the CCA customer was not against minor updates to his applications. My third idea appeared to completely address the mission goal requirements, while at the same time requiring no modification to updating applications, and only a minor change to the program used to create the bills themselves. This solution takes the idea of a flag attribute to mark the pre-billed records in conjunction with introducing a program to create a snapshot of the records that have been pre-billed.
We created a Date attribute named PRE_BILL_DATE. As a preliminary bill is generated, the PRE_BILL_DATE attribute is set to the current date in the affected records. In the other records the PRE_BILL_DATE attribute remains Missing. This accommodates different companies to have different preliminary billing lead times.
In addition to the new attribute, we created a PRE_BILLED dataset using the same record layout as the original dataset, now referred to as the master dataset.
Keeping the Snapshots When a preliminary bill is created, those billing records are copied via DUMP DATASET_OUTPUT to the PRE_BILLED dataset. Then the original billing records are updated with the current date in the PRE_BILL_DATE attribute. Subsequent updates to the billing records are applied in the master dataset, as necessary. Before the final bill is generated, there are two sets of records for a company: the copied records used for the preliminary billing stored in the PRE_BILLED dataset and the current master records in the master dataset. Viewing and updating records is unchanged, and the master dataset always contains the most up-to-date data.
To create the final billing run, the only changed application is now the reporting program used to create the bills themselves. Both the master and the PRE_BILLED datasets are opened. A COLLECT command is issued to logically append the PRE_BILLED dataset records to the master dataset. After the necessary selection set is created in the combined virtual dataset, a SEARCH or FILTER command excludes any records having the PRE_BILL_DATE not set appropriately. The so-tagged master records are thus filtered out, and the bills are generated using the original records: snapshots at the time of the preliminary billing.
After the final bills are generated, the PRE_BILL_DATE attribute in the master dataset is changed to MISSING, and the snapshot records in the PRE_BILLED dataset are deleted or archived. This snapshot technique solution neatly addresses all the requirements of the mission goal. It required the fewest changes to existing applications with only a change in the OPEN command and the addition of the COLLECT and SEARCH/FILTER commands to the existing billing generation application.
In Summary This article began with a customer attempt to extend the use of the System 1032 LOCK command into realms to which it was unable to reach. However, working together CCA Customer Support and the CCA customer proposed and discarded a couple of inadequate solutions before arriving at the snapshot technique solution that accomplished all the customer needed and required less programming work to implement. A double win.
Model 204 USE OF AND ACCESS TO PRODUCTS AND FEATURES ARE IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE USER’S SOFTWARE LICENSE. THE PRESENTATION OF MATERIAL HEREIN DOES NOT, IN ANY MANNER, MODIFY SUCH TERMS AND CONDITIONS.
Why and How – Writing $Functions By James Damon
In the December 2008 issue of CCAPRINT, I noted that there are almost 200 CCA-written $functions linked into the Model 204 nucleus. You might think that 200 $functions would cover every conceivable requirement an organization could possibly envision. In reality however, the ways that customers must verify, validate, manipulate, rearrange and calculate data are nearly infinite. Each organization has special requirements that may require processing that:
1. Strips certain characters from data 2. Inserts characters at specific column locations or after the occurrence of certain character strings 3. Verifies that certain characters exist or do not exist in incoming data 4. Rearranges or converts data in specific ways 5. Manipulates date/time fields in various ways 6. Performs mathematical calculations beyond the ability of the available math functions
While much of this can be done with various combinations of existing $functions, the steps required in terms of application development, code maintenance and understanding, and performance considerations may argue for writing your own $functions.
How to Write a $Function The Model 204 System Manager’s Guide has a section titled, “Customizing Functions and Translation Tables” that is devoted to the coding conventions, requirements and restrictions that you must observe when writing a User Language $function. These functions must be written in IBM Assembly Language, assembled as part of the FUNU control section, and then linked into the ONLINE or BATCH204 load module.
The example, $INSCHAR, that I have included in this newsletter represents a relatively simple $function. The intent of the function is to insert a separator in a telephone number between the area code, exchange and local number.
$INSCHAR has two arguments. The first argument is assumed to be a variable length string, 10-255 bytes: the telephone number. The second argument is a single character separator. The default separator is the underscore ’_’. Processing puts the second argument at column 4 and column 7 of the first argument.
Adding a $Function Name The first step in writing a $function is to add its name to the User Function Table (FUNUTAB) at the beginning of the FUNU source listing using the FN macro:
FUNUTAB DS 0F USER FUNCTION TABLE FN SEP,S,(S) FN ASCII,S,(S),MP=OK TRANSLATE STRING TO ASCII FN EBCDIC,S,(S),MP=OK TRANSLATE STRING TO EBCDIC FN INSCHAR,S,(S,S),MP=OK INSERT CHARACTER IN COL 4 & 7 ← DC X'FFFF'
Writing the Code Code for a $function is written in IBM assembly language, beginning with the name and a description of the expected processing. Then the two arguments are defined.
**$INSCHAR RECEIVES A CHARACTER STRING (ARG1) OF LENGTH 10-255 AND* RETURNS THAT CHARACTER STRING WITH THE SINGLE CHARACTER* (ARG2) INSERTED IN COL 4 AND 7 OF ARG1.* 4 7* | |* v v* ARG1: ABCDEFGHIJKL...* ARG2: _ (DEFAULT)* RETURN: ABC_DEF_GHIJKL...$INSCHAR ENTER MVC BUF2(1),DEFCHAR Get default character for insert ARG 2,NOARG=DFLT If ARG2 not provided, use default L R2,4(X1) Type of ARG - required for RTSTRL CCALL RTSTRL Call ReTurn STRing with Length* Returns A(ARG2)-1 in R1 and len in R2 MVC BUF2(1),1(R1) Move ARG2 (char for insert) to BUF2DFLT ARG 1,NOARG=INSDONE If ARG1 not provided, return null L R2,4(X1) Type of ARG - required for RTSTRL CCALL RTSTRL Returns A(ARG1)-1 in R1 and len in R2 MVC BUF1(3),1(R1) Move 1st 3 chars of ARG1 to BUF1 MVC BUF1+3(1),BUF2 Insert ARG2 MVC BUF1+4(3),4(R1) Move next 3 chars of ARG1 to BUF1 MVC BUF1+7(1),BUF2 Insert ARG2 S R2,=F'6' Subtract (3+3) bytes from ARG1 length EX R2,$INSMVC Move rest of ARG1 to BUF1 A R2,=F'8' Get new len of ARG1(6+2+rest of ARG1) LA R1,BUF1-1 Get A(BUF1) minus 1 B RETRNINSDONE SR R2,R2 No ARG1, set return string len to 0RETRN LEAVESTR Return the new string or nullDEFCHAR DC C'_' Default character for insert$INSMVC MVC BUF1+8(0),7(R1) Remainder of ARG1 starting column 7 LTORG EJECT
Inserting the $Function into the FUNU Control Section Now you must insert the code for $INSCHAR into the FUNU source listing after the code for the previously listed $function. In our example, we would put the $INSCHAR code after these lines which follow the code for $EBCDIC:
* ALL OTHER USER FUNCTION ROUTINES SHOULD BE CODED HERE.*
and before the following lines:
END204 , housekeeping (POOL, module length, and so on) END
Assembly and Link-Edit If you have updated the FUNU source listing in the Model 204 macro library, M204.RLSE.MACLIB, then you can use the FUNUASM job in the JCLLIB dataset to reassemble FUNU and place the new FUNU object deck in M204.RLSE.OBJLIB.
Following successful assembly, the M204RLNK or similar job can be used to link the new FUNU object deck from M204.RLSE.OBJLIB into the ONLINE and BATCH204 load modules.
Testing $INSCHAR The following tests show how the function might be used. Notice that the input arguments to the $function may be any character string: %variable, fieldname, literal, screen or image item variable, and so on.
BEGINPRINT $INSCHAR('7814666601','.')END I781.466.6601
BEGINFR WHERE TELNO IS LIKE *PRINTPRINT TELNOPRINT $INSCHAR(TELNO,'-')ENDI 8007554222800-755-4222 7814666601781-466-6601
This simple function does not verify that the first argument is 10 bytes in length or greater, nor does it verify that the first argument is numeric. As it is written $INSCHAR will insert the separator at those column locations in any character string as shown in the following example.
BEGINFOR 2 RECORDS BY 10000PRINTPRINT DSNPRINT $INSCHAR(DSN)ENDI SYS1.VTOCIX.OS8SYSSYS_1.V_TOCIX.OS8SYSSASC.R550.EXECSAS_C.R_550.EXEC
Coming Attactions As you can see, it is not too difficult to write a simple $function and link it into the Model 204 ONLINE and BATCH204 load modules. A slightly more sophisticated function might verify that ARG1 is numeric, at least 10 bytes in length and print a user defined error message if those requirements are not met.
In the next issue of CCAPRINT, I will discuss including error messages in your $function, adding those messages to the MSGU control section, and printing the error messages using the ERROR macro. You can use this facility to enforce rules you’ve established regarding arguments passed to your $function and to notify users when those rules have been violated.
Model 204 Register TODAY for Insight 204!
We are excited to invite you to this year’s Insight 204 Symposium being held June 7-10 in Boston. With a new version of Model 204 being released this year and a new product planning cycle underway, this event is clearly not-to-be missed if you are involved with Model 204 applications.
Symposium registration is FREE! Because we want to make sure that you are using Model 204 to its fullest, there is NO CHARGE for the symposium itself. You’ll pay only for your travel and lodging expenses, and for meals not included with the symposium. To register for Insight 204, visit http://www.cca-int.com/resources/usergroups/insight/forms/register09.html.
Stay tuned for more information! Over the next few months, we will be providing detailed information on the specific presentations, partner participation, product demonstrations, and other special events you can expect to see at Insight 204. So bookmark the Insight 204 Web site and stay tuned for future updates!
Copyright © 2009 Computer Corporation of America. All right reserved. Published in the United States of America.
