Computer Corporation of America
|
 Feedback
Search CCA:
   
USA CCA
CCA Products
CCA Customer Support
CCA Resources
CCA - Company
CCAPRINT: A Newsletter for Model 204® and System 1032® Users
January 10, 2006
     
System 1032: System 1032 Forms Feature, Part 3 Printer-friendly version
Model 204: Increasing System Availability and Performance with REFRESH SUBSYSPROC Printer-friendly version

 


System 1032
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.

System 1032 Forms Feature, Part 3
By Tym Stegner

Tym

In the first two installments of this article, we created a simple form application, STORES_LIB, using the FORMGEN utility to demonstrate the methodology and ease of adapting a System 1032 Forms application. We removed a field, added two new fields, and rearranged the layout of the form. We also dealt with the processes and tools available to manipulate System 1032 forms.

In this third installment, I will introduce the procedures that process the application. And, I will demonstrate deleting the procedures that reference the deleted DIVISION_ID field.

Overview of Forms Application Operations
The purpose of a form application is to drive the user interface of a form and manage the data flow between the application’s form(s) and the dataset(s) records. A majority of form applications set one or more forms as the interface to a single dataset. More complex form applications may have a single form whose data is drawn from two or more datasets, and/or may have many forms and menus, depending upon the requirements of the business processes represented.

In the case of the STORES_LIB form application, a single form represents the dataset interface. The FORMGEN utility, in addition to this data form, created menu forms that list the operating action choices of the application. The main interface menu is presented in Figure A.

Figure A. Invoking the STORES_LIB main menu

1032> OPEN LIBRARY STORES_LIB
1032> CALL MAIN_STORES
     +---STORES MENU---+
     |Enter selection  |
     | A Add to STORES |
     | D Display STORES|
     | U Update STORES |
     | M Mail Utility  |
     | P Push          |
     | E Exit          |
     +-----------------+

This form has a single interactive data field: the prompt for the action the form is to process. Available actions include:

I will enter an A into the data field, and press Return. On the next form the message line at the base of the form is a prompt to enter data into the form.

Figure B. The STORES_LIB data entey form

+----------------------------- S T O R E S ------------------------------+
|Store Name     _________________________ Store ID      __               |
|Division ID    __                        City          _______________  |
|State/Province _______________           Country       _______________  |
|Budget         ____________________      Gross to date _________________|
+------------------------------------------------------------------------+
Enter data for record or for defaults

Once I enter data and press the Return, the option menu opens displaying the default A Add Rec option:

Figure C. Option menu for Add record processing

+---------------------------- O P T I O N S -----------------------------+
|A Add Rec    C Correct    D Defaults   R Retry      E Exit             A|
+------------------------------------------------------------------------+
Select operation to perform

After I enter data in the STORES form and press Return, the OPTIONS menu in Figure C is displayed listing your possible the actions:

Examining the STORES_LIB Procedures
To understand how these interactive operations are accomplished, we will look at the System 1032 procedures that underlie and drive the interactive form processing.

To see the procedures, you could use the SHOW PROCEDURE DEFINITION command from within System 1032 to display each procedure’s source code in turn. However, because the entire library definition for our example is only about 450 lines, it is easier to examine the library definition itself.

If you do not have a STORES_LIB.DMD file, you can create it using the following command:

1032> OPEN LIBRARY STORES_LIB
1032> SHOW ON STORES_LIB.DMD LIBRARY STORES_LIB DEFINITION

Figure D lists the major elements defined in the STORES_LIB library. Figure D shows a variable that mirrors the form layout, the procedures, and form headers—including DIVISION_ID, but not LATITUDE and LONGITUDE. (We will add these in the next installment).

Figure D. Part of the STORES_LIB code

Library STORES_LIB
  Variable STORES_CRITERIA Group of
    STORE_NAME Text 25
    STORE_ID Integer
    DIVISION_ID Integer
    CITY Text 15
    STATE Text 15
    COUNTRY Text 15
    STORE_BUDGET Decimal
    GROSS_TO_DATE Decimal
  End_Group;
  Form STORES_FORM Message Shared Prompts Bold Values Reverse Comment -
    "Form for Dataset STORES" -
  Procedure MOVE_STORES_REC Comment -
    "Move a record from dataset STORES to form STORES_FORM"
  Procedure ADD_STORES_REC Comment -
    "Add a record to dataset STORES using form STORES_FORM"
  Procedure CHANGE_STORES_REC Comment -
    "Change record in dataset STORES using form STORES_FORM"
  Procedure FIND_STORES Comment -
    "Create and execute FIND/SEARCH commands for user's criteria"
  Procedure CORRECT_STORES Comment -
    "Accept Corrections to current record in STORES"
  Procedure ADD_STORES Comment "Data entry procedure for STORES"
  Procedure UPDATE_STORES Comment -
    "Accept updates to STORES records one at a time"
  Procedure DISPLAY_STORES Comment "Display STORES records one at a time"
  Procedure SELECT_STORES Comment -
    "Get selection criteria from terminal for STORES"
  Form STORES_MENU Message Shared Prompts Bold Values Reverse Comment -
    "Main Menu for STORES application" -
  Procedure MAIN_STORES Comment -
    "Top-level procedure for STORES application - call this"

The two forms listed in Figure D are the data form (previously described in Parts I and II of this article) and a menu form used for the options choices under the data form. Also present are the series of procedures to do the work of the form application. In true modular programming style, the procedures become more complex the further down the library they are defined.

The first three procedures, MOVE_…, ADD_…, and CHANGE_STORE_REC, are designed to move the data between the dataset and the form. The next procedure, FIND_STORES, is the query module for locating records based on form-supplied values. The next five procedures drive the form interactions supporting the major options of the form application, and the last is the main procedure that drives the application.

Coordinating the Form Fields with the Procedures
In the two previous parts of this article, we adjusted both the dataset and the data form by eliminating the DIVISION_ID field and adding the LATITUDE and LONGITUDE fields, and we rearranged the fields within the form to produce Figure E.

Figure E. The revised STORES_FORM

+------------------------------ S T O R E S ------------------------------+
|Store Name _________________________             City _______________   |
|  Store ID __                          State/Province _______________   |
|                                              Country _______________   |
|       Budget ____________________           Latitude _________         |
|Gross to date ____________________          Longitude _________         |
+------------------------------------------------------------------------+

To have the procedures operate upon the revised dataset, the application procedures must be modified to eliminate the DIVISION_ID field and add the LATITUDE and LONGITUDE fields, so that the underlying procedures correspond to the form in Figure E.

First, Deleting DIVISION_ID
For the FORM element, we have already modified the STORES_FORM outside of the library definition. It will be integrated into the library in a later installment.

Searching within the text editor locates the first occurrence of DIVISION_ID within the Variable STORES_CRITERIA element. You must eliminate that line either by deletion or by commenting, as shown in Figure F.

Figure F. STORES_CRITERIA variable

Variable STORES_CRITERIA Group of
    STORE_NAME Text 25
    STORE_ID Integer
!    DIVISION_ID Integer
    STORE_BUDGET Decimal Precision 12
    GROSS_TO_DATE Decimal Precision 12
    CITY Text 15
    STATE Text 15
    COUNTRY Text 15
  End_Group

The next occurrences to be considered are in the three record-transfer procedures: MOVE_STORES_REC, ADD_STORES_REC, and CHANGE_STORES_REC. While the command is different in each case, the required action is the same, to delete or comment out the DIVISION_ID line, as shown in Figure G.

Figure G.

  Procedure MOVE_STORES_REC No_Source Comment -
    "Move a record from dataset STORES to form STORES_FORM";
    Let STORES_FORM.STORE_NAME = STORES.STORE_NAME, -
      STORES_FORM.STORE_ID = STORES.STORE_ID, -
-!      STORES_FORM.DIVISION_ID = STORES.DIVISION_ID, -
      STORES_FORM.CITY = STORES.CITY, -
      STORES_FORM.STATE = STORES.STATE, -
      STORES_FORM.COUNTRY = STORES.COUNTRY, -
      STORES_FORM.STORE_BUDGET = STORES.STORE_BUDGET, -
      STORES_FORM.GROSS_TO_DATE = STORES.GROSS_TO_DATE;
  End_Procedure;

(Note that the continuation mark must be used for continuity of the command.)

Figure H shows the final occurrence within the FIND_STORES procedure. The commands here differ in that you must remove additional lines.

Figure H. Removing DIVISION_ID from the FIND_STORES procedure

  Procedure FIND_STORES No_Source Comment -
    "Create and execute FIND/SEARCH commands for user's criteria";
    Variable FCMD, SCMD Text Varying Initially "";
    Set Dataset STORES;
    If STORES_FORM.STORE_NAME ne Missing Then;
      Let FCMD = FCMD & " and STORE_NAME beg STORES_FORM.STORE_NAME";
    End_If;
    If STORES_FORM.STORE_ID ne Missing Then;
      Let FCMD = FCMD & " and STORE_ID STORES_FORM.STORE_ID";
    End_If;
!    If STORES_FORM.DIVISION_ID ne Missing Then;
!      Let FCMD = FCMD & " and DIVISION_ID STORES_FORM.DIVISION_ID";
!    End_If;
    If STORES_FORM.CITY ne Missing Then;
      Let FCMD = FCMD & " and CITY beg STORES_FORM.CITY";
    End_If;
    …

We see that the two references to DIVISION_ID in Figure H within this procedure are part of a sequence of commands that are building FIND and/or SEARCH command(s) to locate and process the proper records. To eliminate the DIVISION_ID field, we must delete the entire IF command block.

In Summary
We have examined the structure of the form application generated by the FORMGEN utility, and we have begun the process of modifying the application library to remove references to the deleted field. In the upcoming two articles, we will complete the application library modification by adding references for the two new fields, then recompile and test the revised library.

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.

Increasing System Availability and Performance with REFRESH SUBSYSPROC
By James Damon



It is not uncommon to discover a need to change the source code of a subsystem procedure while the subsystem is active and hundreds, or even thousands, of users are logged in and actively using the subsystem. Unless a procedure group has been defined for the subsystem, all procedures in that subsystem are locked and unavailable for update. In that case you must stop the subsystem and either wait for all users to log out or bump all users of that subsystem. Also, when you stop a subsystem, all previously saved compilations for that subsystem are discarded, thereby increasing system overhead when the subsystem is subsequently restarted.

In releases prior to V6R1.0, you can make changes to procedures in an active subsystem by using procedure groups. In this case, you modify procedures and store them in any unlocked member of the procedure group. When next invoked, the modified procedures are located in an unlocked member, compiled, and evaluated. The original procedure remains in the locked member of the procedure group and is ignored. However, procedures found in unlocked members of a procedure group are always recompiled; the compilation is never saved. If a procedure is frequently included, the overhead involved in numerous recompilations can be significant.

Introducing the REFRESH SUBSYSPROC command
In V6R1.0 a significant enhancement to the process of refreshing procedures was implemented with the REFRESH SUBSYSPROC command. The syntax of the command is shown in.

Figure 1. Syntax for refreshing procedures

REFRESH SUBSYSPROC procname
        IN [GROUP | FILE] name
        [FROM [{[PERM | TEMP] GROUP} | FILE] name2

The procedure procname is copied from the FROM clause--file or group--to the IN clause--file or group--replacing the existing copy of the procedure with the new copy. The copy affects only locked members of a procedure group. Several events occur as part of REFRESH processing:

1. The current, saved compilation for the procedure is deleted and the compiled pages, either in CCATEMP or in CCAAPSY, are released.
2. The APSY in-memory, procedure dictionary is updated to indicate that the new procedure has not been compiled.
3. If the original procedure had previously been made resident under the Resident Request feature, the storage for those resident request pages is released and the procedure is no longer resident.

When the next user invokes the procedure, under any subsystem, the new copy is compiled, saved, and evaluated for that user. If the Resident Request feature is active and the procedure is eligible, it is made resident--provided sufficient RESSIZE memory is available. Figure 2 is an example.

Figure 2. Refreshing a resident procedure

REFRESH SUBSYSPROC PROC2 IN TESTPROC FROM TESTZ
***  M204.2666: PROC2 REPLACED IN FILE TESTPROC
***  M204.2665: PROC2 REFRESHED IN SUBSYSTEM SUBSYS1
***  M204.1247: PROCEDURE PROC2 IN SUBSYS1 MADE RESIDENT

Note: M204.1247 appears in CCAAUDIT only when the procedure is made resident.

Command Conflicts
If the REFRESH SUBSYSPROC command is issued against a procedure that is currently being evaluated by any user in any subsystem, the messages shown in Figure 3 are issued.

Figure 3. Reporting conflicts with a REFRESH SUBSYSPROC command

REFRESH SUBSYSPROC PROC2 IN TESTPROC FROM TESTZ
***  1  M204.2669: PROCEDURE PROC2 IS IN USE BY SUBSYSTEM SUBSYS1
***  M204.2683: REFRESH SUBSYSPROC COMMAND FAILED

The conflict occurs because you cannot refresh a procedure until all users have finished evaluation. If the message M204.2683 error occurs, you may reissue the command until it succeeds. It is possible that some procedures may remain active for long periods of time and may never be refreshable because they are always in use. This could occur, for example, in a procedure that has READ SCREEN statements. In these cases, having a procedure group defined to the subsystem provides the alternative method of making required changes to procedures in unlocked members of the procedure group and avoiding the M204.2669 message.

In Summary
Whenever the need arises to provide emergency fixes or any other kinds of modifications to procedures in active subsystems and you are looking for a solution that does not require continuous recompilation of the procedure in question, consider the REFRESH SUBSYSPROC command. The command is intended to improve both system availability and performance. System availability is improved by eliminating the need to bump users and stop subsystems. Performance is improved by avoiding repeated recompilations of modified procedures.

 

 


Contact CCA Webmaster
 Copyright 2008