We might recall the initial phases of the development process (refer to the "Application Developer" chapter of this (cont.)
*Tutorial* manual) wherein we were automatically transferred from one panel to the next in order to capture the complex (cont.)
set of specifications needed to create our screen and application. The entire process consists of MAGEC-generated, (cont.)
Cobol applications programs, not much different from ones any programmer using MAGEC might have produced. They use the (cont.)
same standard facilities which are available to all MAGEC-generated programs.
For the purposes of our discussion, let us assume that we need to develop an application which accomplishes the (cont.)
standard functions to maintain a file which has records which contain more data than will fit on one screen. For (cont.)
simplicity, we will assume that two screens will suffice; though there is really no limit on the number of screens (cont.)
possible.
## 
Two Approaches
There are basically two philosophies which can be applied to solve this problem. First, we could build a multi-screen (cont.)
application which captures all the needed data, edits it all, then adds/updates it to the database. Second, we could (cont.)
build an application which contains a "first" screen which captures some of the data, edits it, and adds/updates the (cont.)
database with what it has, then links to a "second" screen which captures the remainder of the data, edits it, and (cont.)
updates the database with that data.
The advantage of the first approach is that no incomplete data ever reaches the database. All fields are fully edited (cont.)
and validated, both individually and in context with one another, before any of the data is accepted and (cont.)
recorded.
The advantage of the second approach is that, in the event of an interruption, the sequence can be resumed at the point (cont.)
where it was left off. Examples of interruptions would be: power failure, operator error which exits the sequence, (cont.)
software abend, etc. With the first half of the data safely recorded to the database, it is a relatively simple matter (cont.)
to restart from that point forward. The only data which will be lost is that which was typed onto the screen but not (cont.)
yet updated to the database.
The disadvantage of this second approach is that it adds the responsibility of writing an audit program which searches (cont.)
for and reports any incomplete data on the database. This disadvantage is not nearly as great as it might sound, (cont.)
however, since any thorough design for an online system which manages important data will include a database audit (cont.)
program, anyhow. It should be recognized that no amount of diligence in any online system can prevent every possible (cont.)
database integrity error condition from occurring. Physical disk errors, human errors while using offline utility (cont.)
programs (backups, restores, reorganizations, etc.), software bugs (perhaps in system software), and many other types (cont.)
of problems can, and do, still occur. It might be helpful to know the error codes you may encounter. Refer to the (cont.)
["Abend Codes"](/DOC/magref_main.htm#MAGREF009002) reference table for a full list of abend code issued from (cont.)
MAGEC.
## 
First Approach
To implement the first approach is not very complicated at all. First we would create two applications, one to process (cont.)
the first half of the data, one to process the second half. Each would have its own screen Mask and its own MMP. Each (cont.)
would also have its own full set of function codes. The function codes must be unique, therefore we would specify a (cont.)
different function code prefix on the Screen Header for each of these two applications, even though both would have the (cont.)
same primary Data Class.
If we assume that the file we are accessing/maintaining is a customer file with a Data Class ID of CUS, we might (cont.)
specify the function code prefix of CUS for the first application and a function code prefix of CS2 for the second. (cont.)
Both would specify CUS as their primary Data Class. They would also both have the same list of Elements from that Data (cont.)
Class, even though each might only need a portion of the complete set of customer data.
In the first MMP we would wish to customize the logic so that it:
1. does not update the database
2. fetches to the second MMP, passing all the data captured and edited
3. lets the second MMP know that we are coming from the first MMP, with data passed
To do this is quite simple. There are insertion points provided to allow developers to override the default database (cont.)
update, or add processing. What we wish to do is to override them with a fetch to the second MMP, with the appropriate (cont.)
function code set. For example, if we were adding customer data in the first screen (function code CUSADD), we would (cont.)
want to fetch to the second MMP with a function code of CS2ADD. If we were updating in the first MMP (function code (cont.)
CUSCHG), we would want to fetch to the second with a function code of CS2CHG, and so forth.
The two insertion points involved are:
%ADDIT      add a record
%UPDAT      update a record
The code you could provide into each of these insertion points to accomplish all of the above objectives might be:
MOVE 'CS2' TO TEST-FUNCT-KEY.
 
MOVE TEST-FUNCT TO SFUNCT.
 
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
 
GO TO AA900-GOBACK.
 
TEST-FUNCT-KEY is the first three bytes of TEST-FUNCT, which contains the same value as SFUNCT. By setting the first (cont.)
three characters to CS2, leaving the last three characters alone, we have built the appropriate function code to fetch (cont.)
to. The remainder of the above code is the standard FTH-FUNCT logic (refer to "Appendix B in this (cont.)
chapter).
Notice that is was not necessary to do anything at all to pass data to the fetched MMP. MAGEC automatically passes the (cont.)
entire TWA. All the data which was captured from the first screen has already been moved into the appropriate record (cont.)
fields in the Element copybook(s) in the TWA. Upon entry of the second MMP, the entire TWA will contain all the data (cont.)
placed in it by the first MMP. *Since the programs have the same list of primary Elements, their TWA-DB-DATA areas are (cont.)
defined the same.*
It should be noted that the standard logic on an ADD function includes initializing the Element copybook areas to (cont.)
spaces before moving data from the screen to the Element copybook fields. This means that any unreferenced fields will (cont.)
have a predictable value, spaces. If another value is desired, the developer should provide customization for the (cont.)
insertion point %ADDINIT.
The second MMP will need to know that it is being entered from the first. It is not unusual in these situations for the (cont.)
developer to specify that it is illegal to access the second MMP without having come from the first. To ensure this, (cont.)
the developer could add customization into the %PREINIT insertion point, as follows.
MOVE SFUNCT TO TEST-FUNCT
 
MOVE SKEY TO TEST-KEY  
 
IF (TWA-LAST-KEY NOT = TEST-KEY)
 
    OR (TEST-FUNCT-KEY NOT = 'CUS' AND 'CS2')
 
    MOVE 'CUS' TO TEST-FUNCT-KEY
 
    MOVE TEST-FUNCT TO SFUNCT
 
    MOVE FTH-FUNCT TO TWA-NONTP-REQUEST
 
    GO TO AA900-GOBACK.
 
The above code will ensure that we have come from the first screen, and for the same key value. If not, it will fetch (cont.)
back to the first screen to try to initiate the sequence at the beginning, on the assumption that that is what the (cont.)
operator should have done (meant to do) anyhow.
The second MMP will also need to refrain from re-reading (or trying to read) the record being processed. This is (cont.)
because the first MMP has already read it and the entire record (or, at least, all the Elements we are interested in) (cont.)
are already in TWA-DB-DATA; reading on top of them is both unnecessary and destructive. To suppress those reads we (cont.)
might simply comment out the perform of the I/O call in the insertion points: %REDKY and %RDUKY, as:
****PERFORM AA840-CALL-MAGECIO THRU AA899-EXIT
 
We also must prevent the default %ADDINIT logic in the second MMP from trying to initialize the Element copybook (cont.)
fields. To do this we would simply add customization into the %ADDINIT insertion point commenting out the MOVE (cont.)
SPACES... code.
The second MMP will follow its natural flow and, if all edits are passed, add or update the database record with all the data from the first and second screens.
## 
Second Approach
In the second approach we allow the standard logic of the first MMP to do its normal update or add, then we have it (cont.)
fetch to the second MMP. Since, on an ADD function, the record will be added in the first MMP, we will transfer to the (cont.)
second using a CHG function whether we were doing an ADD or a CHG in the first MMP.
Because we will be adding an incomplete set of data to the database in the first MMP, we should be careful to set (cont.)
appropriate default values into all the fields of the Element copybook(s) being updated. That means that we might need (cont.)
to put some customization code into the %ADDINIT insertion point. The customization would move default values to those (cont.)
fields not updated/added from the first MMP. Some developers will choose to set default values which identify this (cont.)
record as "incomplete" in order to facilitate auditing the database and/or restarting the multi-screen transaction from (cont.)
the point it was aborted.
The first MMP should fetch to the second from the %GOODADD and %GOODCHG insertion points. These insertion points occur (cont.)
after a successful add or update, respectively. The coding to fetch to the second MMP would be:
MOVE 'CS2CHG' TO SFUNCT.
 
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
 
GO TO AA900-GOBACK.
 
In this case, we are always fetching to the CHG function for the second MMP since the record is already on the (cont.)
database, having been just added or updated by the first MMP. It is not necessary to suppress the normal reading in the (cont.)
second MMP, for the same reason.
What should be done, though, is suppression of the ADD function in the second MMP. This is done by simply de-selecting (cont.)
the ADD function from the list of available functions for this MMP. Refer to the MMP header screen discussion and (cont.)
Figure 02 inthe Application Developer section of this book. The Application Developer section is the first index tab in (cont.)
this Tutorials manual. Removing the ADD function in this manner prior to generating the MMP causes MAGEC not to (cont.)
generate a FCD (Function Code) definition record for an ADD function and also suppresses the generation of code into (cont.)
the MMP to support an ADD function.
It is possible to use the same coding in %PREINIT to ensure that the operator begins on the first screen before getting (cont.)
to the second screen; however, it is not necessary. Using this approach there is not a real reason why an operator (cont.)
should not directly access the second screen, if desired. An ADD function, of course, must begin from the first screen. (cont.)
That is ensured by the fact that the second screen has no ADD function at all.
## 
Toggling Between Screens
In either approach it might also be appropriate to provide a PF key in both MMP's to "swap" from screen one to screen (cont.)
two, and vice-versa for SEE functions. It would be acceptable (maybe preferrable) to use the same key in both such that (cont.)
it "toggles" between the two screens. Such coding could be done in the insertion point %PFKEYM. It would use the (cont.)
standard FTH-FUNCT logic as described in "Appendix B and the PF key logic as described in "Appendix G, both of this (cont.)
same chapter. It might also be advisable to restrict this toggling only to SEE and NXT functions via the condition name (cont.)
provided, i.e.:
IF (SEE-FUNCTION)...
 
## 
Sets of Masks
Some developers are accustomed to creating one program which utilizes several screens, rather than creating separate (cont.)
programs as described above. MAGEC supports the use of multiple screen Masks in any MMP; however, it is not (cont.)
recommended.
When a program, whether it is a MAGEC-generated program or not, utilizes multiple screen masks, the definitions for (cont.)
those masks must redefine one another. The CICS "map set" facility is a good example of screen definitions redefining (cont.)
one another. This redefinition opens up the possibility for many types of programming errors and greatly complicates (cont.)
both coding and debugging of the programs.
The program which utilizes multiple screens must constantly be aware of which screen format is active at any given time (cont.)
and must not make any references to screen fields not contained in the active screen mask.
At first glance it might seem that the technique of creating separate MMP's for each screen in a multiple screen (cont.)
sequence is less efficient; however, because of the architecture of MAGEC, it is approximately as efficient as a single (cont.)
program using multiple screens. The simpler, more modular, structure of the separate programs also eliminates the need (cont.)
for procedural logic to distinguish between the various screen formats in order to prevent references to an inactive (cont.)
screen from common routines.
Maintainability of the simpler programs is as good as for any ordinary MAGEC-generated program, since there is very (cont.)
little customization involved. It is even possible to add additional screens into the sequence with very little (cont.)
difficulty.
# 
Appendix T -- Accessing Global Parms
## 
Table #243
For various reasons, you may occasionally wish to interrogate the Global Parameters table of MAGEC from your (cont.)
application programs. That enables you to see exactly what settings have been specified for your MAGEC installation, (cont.)
and to take action accordingly. One example of why you may wish to access this information would be to learn what (cont.)
highlighting option has been specified for error fields on a screen (for 7-color terminals). We will use that example (cont.)
to illustrate accessing the table. Of course, any of the other parameters could be accessed (cont.)
similarly.
It is possible, but not recommended, to update the table from your programs. The reason it is not recommended is (cont.)
because the intrinsic functions provided with MAGEC to maintain the table include appropriate editing and formatting (cont.)
which your program might not adhere to; thereby creating an error condition. The intrinsic functions (cont.)
are:
243ADD
243CHG
et cetera
 
There is a discussion about Table #243, Global Parameters, in the *Installation Guide*.
Table #243 is merely a standard MAGEC Lookup table. It can be accessed just as any other table can be accessed, by (cont.)
reading the TBL file. To properly access this table, you should include the standard copybook into your program to (cont.)
define the TBL file records. To do that, code:
-MAGECINC TBL01-C
 
This would usually be in the %DATADEF, or %VARSTOR, insertion points.
In your Procedure Division, you should place code to read the file. For example, in an MMP:
MOVE '243'            TO TBL01-TBL-NBR.
 
MOVE 'ERROR-HIGHLIGHT'      TO TBL01-CODE-VALUE.

Next: <a href="https://magec.com/DOC/markdown/cstm19.md.txt">https://magec.com/DOC/markdown/cstm19.md.txt</a>