CCAPrint Newsletter for Model 204 and System 1032 Users

Let the Games Begin!
By Chris Ramsdale
Director of Strategic Product Planning

Whether you are a Model 204 or System 1032 customer, I am sure you will all agree, you are running the best DBMS in the business –- and here is your chance to prove it.

The Winter Corp. TopTen Program is a global campaign that identifies the largest and fastest growing databases in the world. Participating in the program gives you the chance to show your success at building, managing, or using the world’s largest databases. If you are a program winner, Winter Corp. will highlight your achievement by featuring your name and database on its web site, in company publications, at a webinar, or special conference presentation.

Both Centrelink and Roadway Express have been TopTen winners in the past. This year we would like to see more customers join them.

To join the program, all you need to do is fill out a two-page survey. For details about the program and directions for accessing the questionnaire, go to the Winter Corp. web site

After you submit your survey, you will be asked to validate some answers. If you have any questions, send an email message to me.

Winter Corp. will send you a complimentary gift just for completing a survey. In addition, you’ll also be eligible for awards (over 100 in the last campaign) such as gourmet chocolate and a personalized display plaque.

Surveys will be accepted until July 31st, so fill out yours today. Do not miss this opportunity to show the world that you have one of the top databases in the world!

The entry qualification is a 1TB database. The term database in this contest represents all the data used by your business unit. The data need not be only Model 204 or System 1032 data, but can include other data sources.

For Model 204 sites
When you are filling out the survey, remember that, with the exception of preallocated fields, ALL Model 204 data is compressed. Consequently, when you are calculating the size of your database, for each field the size is max-field-length times number-of-records. This applies to both visible and invisible data.

Also, for Model 204 OLTP applications a FIND statement constitutes a transaction.

For System 1032 sites
Remember all attributes with ranges are stored compressed. If you are interested in participating in the TopTen contest, contact System 1032 Support for assistance in determining dataset sizing and transaction counts.

My article this month, about the lesser known features of System 1032, looks at features available within PL1032 programming that are essentially programming tips.

The classic admonition, given while you create any program, be it System 1032 or another, is: “Be sure to comment the program.” This reminder is partly so you can remember just what the program is doing and why, and partly as an explanation to the next programmer, who must maintain the code.

System 1032 offers the OpenVMS-standard exclamation point as an in-line or line comment and the exclamation-asterisk (!*) and asterisk-exclamation (*!) character pairs to enclose a block comment, as shown in Figure 1.

PROCEDURE Anything
!*
    This is a block comment. ANY text following
    the exclamation-asterisk is considered part of the
    Comment text. Watch out for demarcation lines

    Consisting of exclamation-asterisk- asterisk - asterisk 

…
*!
. . . 
END_PROCEDURE

However, code with good comments is larger than code without. To reduce library or procedure overhead, you can reset the $COMMENTS system variable to exclude comments from compiled source. As there is an upper limit of 32K characters in any one procedure, eliminating comments may reduce the source code to an acceptable length.

To enable this feature, before you compile a library or procedure reset $COMMENTS to FALSE; the default value, TRUE, saves comments in the compiled objects.

While a notable percentage of System 1032 work is done using COM-driven DMC files, the bulk of System 1032 batch and interactive applications are executed as compiled procedures. Three types of procedures were introduced in more recent versions of System 1032, so they have not gotten the usage they deserve, as early programmers had worked around their absence. These features are:

Error Handling Then and Now
In the earliest versions of System 1032 error handling trapped errors at the DCL-level in the controlling COM file. Next, methods to encapsulate a procedure call into an EXECUTE statement and check the returning $STATUS were developed. And now you can code error handling directly into a procedure itself to handle all errors and other conditions, with the exception of fatal events.

Using an ON ERROR block
You define an ON ERROR block immediately after the parameter list in a procedure, prior to any other statements. An error block can do any of the following:

Alter the status of an error
Pass the error event to the calling procedure for handling
Ignore an error event and continue execution
Clean up after an event and exit the application

Within an ON ERROR command block, you can test the value of the current $STATUS and take specific action on predetermined events. The CONTINUE command lets you direct PL1032 to skip the error signaling command and proceed with the execution of the procedure, or optionally to retry the error signaling command.

Trigger Procedures Spring into Action
A trigger procedure automatically responds to a dataset event. Trigger procedures let the programmer perform specific actions at the open of a specific dataset and before and/or after any update commands performed against that dataset. A trigger procedure is normally stored within the dataset for which its actions are intended.

A trigger procedure application can provide referential integrity for a group of datasets or create an audit trail of updates that access a dataset. Another common use of a trigger procedure is to control access to a dataset by determining by whom or when the access is occurring.

As shown in Figure 3, trigger options are part of the procedure header and follow the procedure name, prior to any ON ERROR command block. Trigger procedures do not have parameters. (There is no way to pass any parameters!)

PROCEDURE procname TRIGGER commands BEFORE | AFTER –
     [ commands BEFORE | AFTER ] COMMAND 
…                               ! Procedure body
END_PROCEDURE

Figure 3. Trigger procedure syntax

For the commands argument in Figure 3, you can substitute an individual command, a series of commands, or a group of commands specified by keyword, such as OPEN, ADD_GROUP, CHANGE_GROUP, or UPDATE. Add and change commands include the API-level updating commands.

Using Trigger Procedures and Related Features
With the exception of the OPEN trigger, the other command triggers are command-level triggers, not selection set or record-level triggers. This means that you must preserve the current selection set in a dataset, if you manually modify the dataset during your trigger operations.

A trigger can be executed either before or after an event, where the event is the execution of the specified command. However, the OPEN trigger is always before the event. An OPEN trigger can deny opening the dataset, if the procedure-level conditions warrant it. You can also create OPEN triggers for implicit opens of the dataset.

By using the system variable $TRIG_CMD, you can determine the specific command being used to update the dataset and take steps from there. The $TRIG_TIMING system variable tells you if the trigger is a before or after trigger. You cannot, however, capture the actual command line being used to perform the update.

Complete documentation of trigger procedures is available in the System 1032 Installation & Maintenance Guide for V9.70-0 and in the System 1032 Features and Enhancements consolidated manual.

In Summary
Although it is hard to find time to retro-fit applications, it is worth the effort to simplify code by adding condition handling and triggers. These features certainly make any new development easier than the older methods.

Coming Attractions
In the coming issues of this series, we will present tips on reliability using dataset journaling, a number of tips for reporting, and in-depth examinations of System 1032 security, Record Descriptors, the TRANGEN utility, and the System 1032 debugger.

Thread signaling is the capability of one thread to signal or indicate to another thread, which may be running or simply waiting for the signal, that an event has occurred. This capability was introduced in V5R1 to support the NonStop/204 feature described in the V5R1 Release Notes, but it has applicability beyond that feature. For NonStop/204, the signal event in question is the quiescence of all updates in the Online environment. When this event occurs, you can back up files using third-party backup utilities without:

The quiescence of all updates in the Online is a special event. However, an event can be anything agreed upon by the signaling thread and the waiting thread(s). In a Model 204 environment, other typical events might include:

The completion of an update
The completion of a particular job
The start of a subsystem
The logon or logoff of a particular user in a subsystem

The completion or occurrence of an event, which can be detected by a User Language thread, can be communicated to another thread that might be waiting for that event. This facility is implemented through the use of event control blocks (ECBs) and the following $functions that manipulate and test those ECBs.

The parameter NECBS sets the number of ECBs available during the run. It is set in CCAIN and you cannot reset it after Model 204 is initialized. Each ECB requires four bytes for status information and 256 bytes for data which may be set and interrogated through the previously listed $functions. Virtual storage for NECBS is acquired during Model 204 initialization and is allocated below the 16-megabyte line.

An event is considered to have occurred or to have completed when its associated ECB is posted. In User Language, posting an ECB is accomplished through the $POST function, which simply sets the posted bit in the associated ECB to one.

Multiple programs running on multiple threads may wait on an ECB by calling the $WAIT function. These programs are designed with the assumption that they require the associated event to occur or complete before they can resume processing past a specific point. Those programs will wait indefinitely or, optionally, for some predetermined amount of time for the event to occur. When the desired event occurs and the associated ECB is posted, all such programs resume evaluation with the statement immediately following the call to $WAIT.

Consider the following example. A daily update program, which could run at any time during the day, must run before certain report programs can be initiated or before a backup job can be submitted. Prior to V5R1, the update program, upon successful completion, could set a field in a particular record of a particular file to a specific value. Any other program or thread waiting for this event to occur, would constantly wake up, find the record, examine the value of the field and go back to sleep (PAUSE) -- if the required value had not been set.

This can be very wasteful of system resources -- CPU, database I/O, record and resource locking, for example -- depending on the length of the PAUSE and the amount of time remaining until the required value is set. With the thread signaling facility, this overhead is eliminated. Event occurrence or completion is known nearly instantly to all threads in the Online. Figures A, B, and C show how this can be done under V5R1 with $WAIT and $POST.

BEGIN 
* Daily HISTORY file-update program 
%X = $UNPOST(1)       /? ENSURE THAT ECB1 IS UNPOSTED ?/ 
*

* set ECB1 with data string
%X = $ECBDSET(1,'ECB1: HISTORY DAILY UPDATES, RUNNING')  
* 
* code for daily updates to HISTORY file is here 
* 
* signal all threads that updates have completed - 
* post ECB1 with post code=555 and change data string
*
%X=$POST(1,555, 'ECB1: HISTORY DAILY UPDATES, COMPLETED') 
END

BEGIN              
* Daily report from HISTORY file. Can’t run until last update complete
%X = $WAIT(1)                      /? REQUEST WAITS HERE    ?/
                                   /? UNTIL ECB1 IS POSTED. ?/
IF $STATUSD = ‘555’ THEN           /? EXPECTED POST CODE?   ?/
* code for daily HISTORY report here
ELSE 
  STOP                             /? WRONG POST CODE       ?/ 
END IF
END

BEGIN  
* DUMP HISTORY file. Can’t run until last update is complete. 
%X = $SETG(‘DUMPHIST’, ‘NO’)       /? SET GLOBAL TO NOT DUMP  ?/
%X = $WAIT(1)                      /? REQUEST WAITS HERE      ?/
                                   /? UNTIL ECB1 IS POSTED.   ?/
IF $STATUSD=‘555’ THEN             /? EXPECTED POST CODE?     ?/
  %X = $SETG(‘DUMPHIST’, ‘YES’)    /? YES, SET GLOBAL TO DUMP ?/
ELSE 
  STOP                             /? WRONG POST CODE         ?/
END IF 
END
IF DUMPHIST=‘YES’,DUMPPROC /? INCLUDE DUMPPROC TO DUMP HISTORY FILE ?/

In addition to the $POST, $UNPOST and $WAIT functions, additional functionality is provided through the $ECBDGET, $ECBDSET, and $ECBTEST functions. As shown in Figure A, $ECBDSET sets a text string in ECB1. While $ECBDSET is not required prior to waiting on or posting a particular ECB, it is a convenient way to pass data to applications that may be waiting on that ECB. For example, you may want to know the current status of ECB1 and you may want to examine the data string associated with that ECB. The code in Figure D provides that information:

BEGIN 
PRINT 'ECB1 STATUS: ' WITH $ECBTEST(1) 
PRINT 'ECB1 STRING: ' WITH $ECBDGET(1) 
END 
ECB1 STATUS: 0        /? ECB 1 is not posted ?/
ECB1 STRING: ECB1: HISTORY DAILY UPDATES, RUNNING

If it is known that the HISTORY daily-update program will not run today for whatever reason, you may want to post ECB1 with a different post code and set a different text string in the ECB. This will allow all threads waiting on that ECB to resume evaluation and to take alternative action based on the post code or the ECB-text string.

BEGIN 
%X = $POST(1,444, 'ECB1: HISTORY DAILY UPDATES, INCOMPLETE') 
END

The Thread Signaling facility has many powerful applications that should simplify the detection and signaling of events required for subsequent processing. The facility could also implement a trigger mechanism, whereby the occurrence or completion of an event, signals a number of different processes to begin evaluation. A number of IODEV=3 threads could be initiated and then wait on a trigger event before resuming evaluation. The signaling of that event could come from the posting of an ECB by an Online user, a subsystem, a BATCH2 thread, or from an ad hoc request submitted by a system manager, DBA, or applications programmer.

CCAPRINT: A Newsletter for Model 204^® and System 1032^® Users	June 10, 2003