Figure 1 Refer to the "Insertion Points" reference table for a compact list. 'X' indicates the insertion point 'fires' (eXecutes). 'D' (Data) indicates insertion point is not in the PROCEDURE DIVISION. Cursor Select name to link to full description, then use back button to return (←).
Figure 2 'X' indicates the insertion point is in that section of the SORT (Input Procedure or Output Procedure). 'D' (Data) indicates the insertion point is not in the PROCEDURE DIVISION. Cursor Select name to link to full description, then use back button to return (←).
Online Insertion Point %ADDINIT
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- BB600-BUILD-REC
Description:
Only used for ADD functions. This logic will be used to initialize the Record's Elements just before the individual Data Items are MOVE'd from the screen to the Elements. The default logic will just MOVE SPACES to the Elements. NOTE: it moves SPACES to all the Elements in TWA-DB-DATA, both from the primary and from joined Data Classes.
Suggested Uses:
Initializing numeric Data Items in the Elements to zero or to some other value. Setting default values into selected database fields which will NOT be MOVE'd to otherwise; i.e. they are not used as a Source/Target for any of the screen fields.
You may use this insertion point to set the "Date & Time Added" into the record, if you desire.
You may wish to override the default logic by moving SPACES (or other initialization value) to only the primary Data Class's Elements.
Cautions:
This logic will only be done for an ADD function; usually this means xxxADD or xxxDUP, unless you have added other ADD functions through customization in the %FUNCT insertion point.
If you MOVE a value to a Data Item which is specified as a Source/Target for a screen field; it will be overlaid when the generated MOVE's are done, immediately below in the BB600-BUILD-REC logic.
Do not attempt to MOVE to the Audit-Stamp. Anything you move there will be overlaid by the MAGEC I/O module since it handles all Audit-Stamp maintenance.
Your custom coding will replace the default MOVE SPACES. If you want the Element(s) initialized to SPACES first, you must code it in your logic.
Online Insertion Point %ADDIT
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AAM710-ADD-TO-DATABASE
Description:
This is the logic used to add a record to the Primary Data Class (file). The default logic CALL's the MAGEC I/O module. The command used when calling the MAGEC I/O module is: "ADDIT".
Suggested Uses:
When you add customization for %ADDIT MAGEC presents you with Proforma code which resembles the default logic. You may modify or add to it as needed. You can also entirely replace the Proforma by overkeying it. This enables you to code the necessary commands to access a file directly instead of using the MAGEC I/O module.
You could code the database commands for a non-MAGEC file.
You could add code to update a control record just before the add to the Primary file.
You could access a control record to determine the next available key (such as P.O. number, Invoice number, etc.) so as to assign the key for the record you are about to add.
Cautions:
If you want to do something after the add is completed, this is not the best place to do it. The %GOODADD insertion point is a better place since the MMP will test for a good return code before going to %GOODADD.
If you do other I/O before the add, be sure to save and restore TWA-DB-REQUEST (in TWA-DB-REQ-SAV) and TWA-ELT-LIST if you "step on" them.
Be sure not to "step on" the Elements (in TWA-DB-DATA) for the Primary Data Class before they are added to the file.
Be sure the file is open and authorized for adds.
Online Insertion Point %BLNKSCR
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- BB100-BLANK-SCREEN
Description:
Logic inserted at the very end of the "blank screen" routine, after all the standard generated MOVE's of ALL '_' to all screen variables. This is executed on the "NEW-TRANSACTION" phase of the xxxADD function and also whenever the "INVALID KEY FORMAT" message is displayed.
Suggested Uses:
You could initialize selected screen fields to some value other than underscores, if you wish.
You could move values to the screen based on the key value the operator entered. For instance, if the key value in SKEY is a Customer Number, you might read the Customer file to get the Name and Address, then move them to the screen. Actually, the read might have been done in the %NORMKEY insertion point as a custom key edit.
You could test for an edit failure in the key normalization (IF SCOMPLE = E) and move your own message to the screen to help the operator correct the error.
Cautions:
This logic is only executed in the NEW-TRANSACTION phase of the xxxADD function (and on INVALID KEY). If you want something to be done at other times also, you should probably place the logic in a PERFORM'd routine (in %SUBRTNM) and then PERFORM it from here as well as from anywhere else it may be desired (such as %CALC and %COMP).
This logic may, of course, not reference any screen fields in MSK652 (the Browse Mask) since it is executed only for Maint functions.
Online Insertion Point %CALC
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- BB610-MOVE-SCREEN-TO-DB
Description:
Logic inserted at the very end of the BB600-BUILD-REC routine which MOVE's data from the screen to the database Element(s). This logic will be after all the generated MOVE's from the screen fields to the record fields, but before the MOVE of NORMALIZED-KEY to the record key and before the business rule processing.
BB600-BUILD-REC is executed for all database updating functions, typically xxxADD, xxxCHG, xxxDUP. It is executed only in the CONTINUATION-MODE, not in the NEW-TRANSACTION-MODE -- and only if there were no fatal errors flagged in the editing (NOT ERROR-FOUND).
Suggested Uses:
You can override any of the generated MOVE's here.
You can move to database fields which are not the Source/Target for any screen field.
You can do calculations or conversions to store computed values, instead of "raw" screen data, on the file. For example, converting a date to Julian (or binary) using a conversion subroutine to save file space. There is such a date conversion subroutine, named MAGDATE, available with MAGEC.
You can override the value in NORMALIZED-KEY which will be moved into the record's key. NORMALIZED-KEY is moved in order to prevent the possibility of your adding records without setting the key value. In some cases the value in NORMALIZED-KEY may not be what you want as the key, especially on an ADD-FUNCTION where you may wish to automatically assign part or all of the key. You can bypass the MOVE of NORMALIZED-KEY by branching around it to the business rule logic; to do so you should GO TO BB680-DATA-RULES.
Cautions:
On an ADD function, the data in the Element's fields will be unreliable unless you have initialized it in %ADDINIT. This is not a good place to do I/O. If you do you will have to be careful not to "step on" the TWA-DB-REQUEST area (or, at least, save and restore it). Of course, you should also be careful not to corrupt the data just MOVE'd into the Element area.
If you want to update another file, such as a control record, you would be better off doing so in the %GOODADD and %GOODCHG insertion points, which will be executed only if the update I/O completes successfully.
Remember, %CALC logic will NOT be executed for any of the Browse functions (xxxLOC, xxxSCN, xxxFND). Do not GO TO BB699-EXIT unless you intend to bypass the MOVE of the record key coded just behind %CALC and also bypass the business rule processing.
Online Insertion Point %COMP
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- BB200-FILL-SCREEN
Description:
This logic is inserted at the end of BB200-FILL-SCREEN. It is inserted after all of the generated MOVE's from the database fields to the screen, just before BB299-EXIT.
This code is executed in NEW-TRANSACTION-MODE of Maint functions to MOVE data to the screen for display. It is not executed in the CONTINUATION-MODE of any function, unless you PERFORM it in customization code of your own.
Suggested Uses:
You can MOVE literals or COMPUTE'd values to the screen here.
You can "translate" codes from the file into more readable descriptions and move them to the screen, if you wish.
You can alter screen field 3270 Attributes based on the data being displayed; especially useful when MAGEC's Extended Color support and 7-Color terminals are being used.
You can MOVE data or messages to the last three lines of the screen (SERRMSG), increasing the usable display capacity of the screen.
Cautions:
Data displayed in SERRMSG is Display-Only. If MAGEC needs to place error messages or other notifications there, your data will be overlaid.
This logic is executed only for Maint functions, you may not reference screen fields in MSK652, the Browse Mask.
If you are moving to a numeric screen field you should:
1) MOVE (or COMPUTE) into the "numeric equivalent" field, named S_____-N. -AND-
2) MOVE to the "edit pattern" field, named S_____-ED. This will maintain the standard set by MAGEC in its generated MOVE's and will ensure agreement.
You should check numeric database fields (IF NUMERIC . . .) before trying to MOVE them if you are not sure of their validity. The generated MOVE's will do that if you have specified the VERIFY option.
Online Insertion Point %DATADEF
Found in Model:
MODELMMP MODELWIN MODLOCAT
Location:
LINKAGE SECTION -- TWA-DB-DATA
Description:
This insertion point is immediately after the generated data definitions for the Elements specified in the Screen Header definition (SHDxxx screen). The Element definitions for any Logically Joined data will be automatically inserted in %DATADEF in the form of -MAGECINC statements. A Cobol 03-level item (TWA-DB-DATA) is the group item which includes all these Element definitions below it.
Suggested Uses:
You can add more data definitions for the MMP here. They may be -MAGECINC statements or straight Cobol coding. Since this area follows TWA-DB-DATA, which is a Cobol level 03, you must avoid using Cobol level 02 and 01 here.
TWA-DB-DATA is initialized to SPACES on ADD functions (unless you have coded logic in %ADDINIT to do otherwise). If you insert an 03 level here then all definitions below will NOT be part of TWA-DB-DATA and will NOT be initialized.
You may define areas here which are NOT read into; one common reason to do so would be to define Data Items which are to be COMPUTED or otherwise derived in the Logical Join process. This allows Logically Joining of non-database data.
Cautions:
Be careful not to use Cobol level 02 or 01 here. Also, the Cobol VALUE clause is illegal here.
This area is NOT initialized in BA100-INIT-STORAGE unless you code customization in %INIT and %LOCINIT to do so.
This area is within the 12K portion of the TWA which is saved and restored to the TWA-file. Defining a very large area here will possibly "push" other data beyond the 12K boundary, causing it NOT to be saved and restored. In that case you could move some of the areas defined here down to the %VARSTOR insertion point since this data usually does not need to be saved.
It is usually important that everything down to, not including, VARIABLE-STORAGE be within the 12K boundary.
Online Insertion Point %DELEDIT
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- BB400-EDIT-FOR-DELETE
Description:
The logic in %DELEDIT will be inserted after the paragraph BB400-EDIT-FOR-DELETE and before the paragraph BB499-EXIT. It will make up the entire edit-for-delete routine.
Since there is no default logic for %DELEDIT, unless you provide a %DELEDIT routine the edit-for-delete will effectively be "null".
This logic will be performed before doing the delete in the xxxDEL function. If you set FATAL-ERR = E here, the delete will not be done, an error message will be issued instead.
Logic will be executed only in CONTINUATION-MODE for DEL functions.
Suggested Uses:
You might want to read other files to check for the existence of subordinate or related records before allowing the deletion to occur. For example, be sure there are no invoices on file for a customer before deleting the customer master record.
You might want to be sure that certain values in the record to be deleted are zero before allowing a deletion. For example, customer balance.
To set the ERROR-FOUND condition with an error message you can MOVE an error number to ERROR-NUMBER and then PERFORM CA100-LOAD-ERR-CODE-TBL THRU CA199-EXIT.
You might want to require that some PF key be used to do a delete. You could test:
IF (NOT TWA-MSK-PFx-HIT) ..
. and set an error condition.
Cautions:
Do not corrupt the TWA-DB-REQ-SAV area; that is where the TWA-DB-REQUEST area has been automatically saved just prior to executing the edit-for-delete routine.
If you are requiring some PF key to allow a delete, you should inform the operator. You could do that easily by MOVE'ing a message TO ENTER-TO-DEL-MSG, overlaying the default message "Press ENTER to Delete" with something like "Press PFx to Delete". This should be done in the %REDKY insertion point, after the I/O module call and after the PERFORM of JA100-LOGICAL-JOIN.
Avoid using PF1, PF15, PF13 or other PF keys already being used by MAGEC or your MMP.
Online Insertion Point %DELET
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AAM730-DELETE-FROM-DATABASE
Description:
This logic will be used to accomplish the actual delete of the Primary Data Class' record. The default logic will call to the MAGEC I/O module using the "DELET" command. This logic will be executed only for xxxDEL functions and only if the ERROR-FOUND condition is not set by the edit-for-delete coding (see %DELEDIT).
Suggested Uses:
You could override the default coding completely to do an I/O command directly, bypassing the MAGEC I/O module. It might even be for a DBMS not directly supported by MAGEC.
A Proforma routine is presented when you are adding new %DELET customization coding, it is very similar to the default logic. You might wish to simply add a few lines of coding to the Proforma; perhaps to update a control record before actually doing the delete.
Cautions:
Be sure not to clobber TWA-DB-REQUEST, or be sure to save it in TWA-DB-REQ-SAV and then restore it if you need to do any other I/O in your customization.
If you wish to exit from this routine, remember that you must GO TO AAM750-TEST-RETURN-CODE, which is where the delete logic normally exits to.
Online Insertion Point %EDIT
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- BB500-SCREEN-EDIT
Description:
Logic to validate data in any screen fields and set error number(s) as appropriate. This will be executed on database updating functions (xxxADD, xxxCHG, xxxDUP). Virtually any type of editing and validation may be done here, including any type and amount of I/O.
If you set the ERROR-FOUND condition here, then the MMP will not do the database update. Instead, it will return to the MAGEC Control Program to have the error message(s) sent.
There is no default logic for %EDIT.
Suggested Uses:
You can do any type of screen data validation here. You can do any type of "cross-field" validations or those involving I/O.
Remember, the Automatic Editing can handle most of the mundane chores for you; such as date validation, numeric editing, and table lookups. You should take advantage of the Automatic Editing to its fullest -- then code any additional edits here, as %EDIT customization. You may refer to Data Items (fields) in the "before image" record(s) (except on xxxADD functions) to compare them to screen data, if you wish. This enables you to determine which items were changed by the operator, or to do crossfield edits using Data Items which were not displayed to the screen.
You can set either fatal error or warning messages. Fatal errors prevent any updating to the database, warnings do not. To set a fatal error condition you PERFORM CA100-LOAD-ERR-CODE-TBL THRU CA199-EXIT; to set a warning message you PERFORM CA400-LOAD-WARNING-TO-TBL THRU CA499-EXIT.
Cautions:
To exit the BB500-SCREEN-EDIT routine you must GO TO BB599-EXIT. This bypasses both the %EDIT and %EDIT2 coding.
The editing logic you insert in %EDIT is in addition to whatever Automatic Editing has already done, it is a possibility that some error conditions have already been flagged by Automatic Editing prior to the Cobol MMP even receiving control.
You should adhere to the convention of setting the ERROR-FOUND condition (by PERFORM'ing CA100-LOAD-ERR-CODE-TBL THRU CA199-EXIT) and setting the error number (by MOVE'ing it to ERROR-NUMBER) and indicating the screen field in error (by MOVE'ing E to S_____E) -- as is shown in the Proforma when you are adding %EDIT logic.
Online Insertion Point %EDIT2
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- BB500-SCREEN-EDIT
Description:
This logic is similar to the %EDIT logic, except that it is for edits which might be "costly" (in terms of I/O, usually). These edits are preceded by a test for the ERROR-FOUND condition. If any errors have already been found, then the %EDIT2 logic simply bypasses further checks and GO's to BB599-EXIT.
The value of using %EDIT2 is that it avoids unnecessarily consuming system resources by ceasing to look for more errors once a fatal error is detected.
This logic will be after BB500-SCREEN-EDIT and before BB599-EXIT. There is no default logic for %EDIT2.
Suggested Uses:
Any edits which involve heavy I/O burden. Any edits which would be illogical to do after other errors have been found.
It is permissible to update a file(s) here based on the fact that errors were (or were not) found above. This might be useful for gathering statistics regarding error rates, etc.
You need not worry about saving and restoring TWA-DB-REQUEST since the MMP's mainline logic saves it before PERFORM'ing BB500-SCREEN-EDIT THRU BB599-EXIT.
Editing and validation routines should adhere to the same conventions here as in %EDIT regarding setting the error number and setting the ERROR-FOUND condition, etc.
Cautions:
The %EDIT2 insertion point should be used instead of %EDIT only for those edits which will indeed be very costly to do unnecessarily. The disadvantage is that the operator may correct all the errors shown on the screen and then press ENTER only to be shown another error which was not detected earlier.
The normal logic, unless you have overridden it, will test for ERROR-FOUND in order to bypass further editing once an error is detected. You must be aware of this when planning the sequence of your edits. The first one to detect an error will bypass all following edits. For instance, you might wish to test for the most likely errors first.
Remember, all the %EDIT logic will be inserted before the %EDIT2 logic.
You should review the discussion for the %EDIT insertion point as well as this one.
Online Insertion Point %FUNCT
Found in Model:
MODELMMP MODELWIN
Location:
LINKAGE-SECTION -- VARIABLE-STORAGE
Description:
These are the "88-level" definitions of the various function codes for this MMP. They are inserted immediately following the 6-byte field named TEST-FUNCT. The logic of the MMP is very heavily controlled by these definitions.
This defines which functions are valid for this MMP, which are "Maintenance functions" and which are "Browse functions", and which are ADD, CHG, etc. These 88-level condition names are refered to throughout the MMP.
Default coding defines the standard nine functions, xxxADD, xxxCHG, xxxDEL, xxxSEE, xxxNXT, xxxDUP, xxxSCN, xxxFND, and xxxLOC.
Suggested Uses:
You can add your own custom functions to an MMP. Any six-character code which can be keyed into a 3270 screen will be valid, so long as it does not contain any blanks and it is not already defined for another MMP.
You might want two similar inquiry displays for different departments, one showing all the data and one showing only "non-sensitive" fields (or records). An easy and efficient way to do that would be to allow the xxxSEE function to show all data and define a new function (perhaps xxxINQ) which has different security requirements and uses the same screen and MMP, but "hides" the sensitive data by setting non-display 3270 attributes for them. You could set the attributes in %INITATB based on which function was being done.
You could also defeat a function that you absolutely do not want (such as the xxxDEL function) by setting the value of DEL-FUNCTION to blanks from 'DEL' (for instance).
Cautions:
All the standard 88-level condition names must be present in order for the MMP to compile clean. You may add some more of your own, but do not delete the standard ones.
The Automatic Editing routine in MAGEC's Control Program looks at the function codes to determine whether or not to do the editing. Essentially, it assumes that xxxADD, xxxCHG, and xxxDUP functions will update the database and thus should receive Automatic Editing. Other functions are assumed to NOT require Automatic Editing unless you have specifically told MAGEC that they do (on the FCDxxx screen). If you want to add a new updating function (similar to xxxCHG) which might be xxxUPD (for example), you will need to specify Auto Editing on the FCD definition (when you do FCDADD) as well as specifying it as another CHG-FUNCTION here in %FUNCT.
Online Insertion Point %GOBACK
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AA900-GOBACK
Description:
Absolutely the last opportunity to insert code in the logical flow of the online processes for all functions, both MAINT-FUNCTIONS and BROWS-FUNCTIONS.
Suggested Uses:
This may be a good place to insert the TERMINATE for a PCB if you are using IMS
Cautions:
This is the logical end of the processing for all functions. If you desire to reference screen data you should first interrogate which mask is initialized.
Online Insertion Point %GOODADD
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AAM753-GOODADD
Description:
This logic will be executed only on the xxxADD function after the return code has been checked to ensure that the I/O for an "add" completed successfully. If the add did not complete successfully then the %UPDERR logic will be executed instead of this logic.
The default logic for %GOODADD merely moves the DATA ADDED message to SCOMPL and fetches to the SEE function to re-display the added data.
Suggested Uses:
You may wish to issue a different message from the standard DATA ADDED message. You may wish to automatically transfer to another screen and function after a successful add. You would use the FTH-FUNCT command to do that. For example, after a successful CUSADD (Customer add) you might want the Invoice add (IVCADD) screen to immediately appear. You could do that by coding:
MOVE 'IVCADD' TO SFUNCT.
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
GO TO AA900-GOBACK.
You may wish to update some other files after a successful add, perhaps a control record or a transaction log file.
Cautions:
Remember, this logic is executed only if the "Primary" add was successful.
Depending on the Access Method, you may or may not be able to re-read the record just added using the RDUID command. RDUKY should work for any Access Method, however.
This logic should end with GO TO AA800-SEND-SCREEN (or optionally, GO TO AA900-GOBACK) to avoid falling thru irrelevant logic below.
Online Insertion Point %GOODCHG
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AAM755-GOODCHG
Description:
This logic will be executed only on a xxxCHG function and only after a successful database update to the Primary Data Class. If the return code from the I/O indicates an error then the %UPDERR logic will be executed instead.
The default logic simply MOVE's the UPDATED-MSG to the screen field, SCOMPL, then fetches to the SEE function to re-display the updated data.
Suggested Uses:
You may want to update another record/file after a successful update of the Primary Data Class, perhaps some of the files which were Logically Joined in the %JOIN routines.
The Primary Data Class' data is still available to you in the TWA-DB-DATA area, you may reference it.
This would be a good place to "post" to a control record.
You might wish to transfer to another screen, function, or program after a successful update. You can do so by coding:
MOVE 'xxxxxx' TO SFUNCT.
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
GO TO AA900-GOBACK.
where xxxxxx is the desired "next function" you wish to transfer to.
An example of this might be a case where, after an update to an Invoice on the Invoice file (function IVCCHG, perhaps), you wish to transfer immediately to the Customer display screen to show the effect on the Customer's status. Assume that the function code is CUSSEE, and that the Customer number from the Invoice record is to be used as a key to read the Customer file with.
In the IVCCHG program (MMP), in the insertion point %GOODCHG, you could code:
MOVE 'CUSSEE' TO SFUNCT.
MOVE FTH-FUNCT TO TO TWA-NONTP-REQUEST.
MOVE IVC01-CUSTOMER-NO TO SKEY.
GO TO AA900-GOBACK.
Cautions:
To exit this routine be sure you GO TO AA800-SEND-SCREEN or to AA900-GOBACK to avoid falling through to the irrelevant logic below.
Online Insertion Point %GOODDEL
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AAM757-GOODDEL
Description:
This logic will be executed only in xxxDEL functions and only after a successful delete of the Primary Data. If a bad return code is sensed (the delete failed) then the %UPDERR logic will be executed instead.
The default logic simply MOVE's the DELETED-MSG to the screen field, SCOMPL.
Suggested Uses:
You may want to update a control record, or any other file, after a successful delete.
You may want to transfer to another function, screen, or program. For example, after the deletion of an Invoice from the Invoice file you might want to automatically present the Customer display (function CUSSEE, perhaps) to show the effect on the Customer's status. To do that you might code:
MOVE 'CUSSEE' TO SFUNCT.
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
MOVE ------- TO SKEY. (customer number)
GO TO AA900-GOBACK.
Cautions:
To exit this routine you should GO TO AA800-SEND-SCREEN or AA900-GOBACK to avoid falling through to the irrelevant coding below.
Online Insertion Point %INIT
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION BA150-MAINT-INIT
Description:
This logic is executed in the initialization for all MAINT-FUNCTIONs (xxxADD, xxxCHG, xxxSEE, etc.) very early in execution of the program. VARIABLE-STORAGE is always set to LOW-VALUES just before the %INIT code is executed.
Suggested Uses:
You can initialize any data and work fields in VARIABLE-STORAGE (or elsewhere) here. This is useful when you have defined some of your own custom variables in %VARSTOR or in %DATADEF, particularly if they are COMP-3 and need to be set to ZERO to avoid Data Exception errors. In some environments it is permissible to MOVE to WORKING-STORAGE items also. Be careful of doing this in any environment in which your program might be "swapped" in and out, such as WESTI. It is best to reserve WORKING-STORAGE for constants, that is why the insertion point in WORKING-STORAGE is named %LITERAL.
Cautions:
Do not reference any screen fields except for the standard MAGEC fields (SFUNCT, SKEY, SCOMPL, and SERRMSG) here since this logic is executed before the MMP has made sure that the proper Mask format is in effect; it is possible that the screen is still formatted with some other MMP's Mask.
If you wish to check whether the Mask area is properly formatted, you may do so by coding:
This logic will be executed only for Maint functions (xxxADD, xxxSEE, etc.) and not for Browse functions. It is inserted at the very end of the Attribute Initialization routine, immediately before BA299-EXIT.
Suggested Uses:
You can override the default Attribute values which are set in BA210-MAINT-SCREEN, perhaps based on the Function Code or even on the Operator ID (TWA-EMP-NO), or any other criteria.
All the valid 3270 attribute codes are defined in the MMP in an included "copy book" for your convenience. They are named ATxxxxxx (xxxxxx is the six-character code, exactly like you specify online in MSKDEF). They are documented in your Developer's Reference Summary and in the appendices of your Developer's Tutorials.
You can also alter the contents of any screen fields here. This is handy for setting a variable screen heading based on the Function Code or any other criteria.
Cautions:
Do not reference Data Items from the file here since the I/O has not yet been done.
To exit the routine be sure to GO TO BA299-EXIT, or just fall through to it.
Do not reference fields in the Browse screen (MSK652) since this routine is only executed for Maint functions, and after the Maint Mask has been formatted (read in).
Online Insertion Point %JOIN
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- JA100-LOGICAL-JOIN
Description:
This logic is executed after each of the standard READ's of the Primary Data Class. It is used to READ other files or to do calculations of "derived fields" which are to be Logically Joined to the Primary data. The result is that the MMP has a "Logical Record" made up of data from one or more physical files (and records) plus, possibly, some computed fields.
This logic is executed for both Maint and Browse functions.
Suggested Uses:
If you use the Automatic Screen Painting and Logical Join then the READ's for your "Secondary" files will be automatically generated here. You may modify them, if you wish.
You may code your own READ's here, or your own calculations for "derived fields". An example might be computing the gross pay by multiplying hours times rate, where hours and rate are in the file data and gross pay is not. More complex algorithms are, of course, possible. This allows you to treat gross pay (a field you have defined in %VARSTOR) as if it were an ordinary Data Item, it may even be the Source/Target for a screen field.
You need not worry about saving and restoring the TWA-DB-REQUEST area, the MMP does it before PERFORM'ing the JA100-LOGICAL-JOIN routine.
Cautions:
If you must reference screen fields then you will have to be certain that the Mask is formatted as you expect. This logic is executed for both Maint and Browse functions. Therefore, it is possible that either the Maint Mask or the Browse Mask (MSK652) is formatted.
To be sure, you can code:
IF (MAINT-FUNCTION)
-or-
IF (BROWS-FUNCTION)
before trying to access screen fields.
To exit the routine:
GO TO JA900-RETURN
-- not JA999-EXIT!
Online Insertion Point %LITERAL
Found in Model:
MODELMMP MODELWIN
Location:
WORKING-STORAGE -- 01 CUSTOM-ALGORITHM-LITERALS
Description:
This insertion point is at the end of WORKING-STORAGE, it allows you to add your own custom literals and constants to the MMP.
Any valid Data Division definitions are allowed. You may use any Cobol level numbers (except 77) and any clauses (VALUE, OCCURS DEPENDING, etc.).
This area is not initialized by the MMP unless you code some MOVE's to it, it is intended to be constant data.
Suggested Uses:
You may define literals, constants, message text, and so forth here. There is no particular size restriction on this area, except that WORKING-STORAGE is physically a part of your program and your environment may impose a size limit for programs.
Cautions:
In some environments (notably WESTI) you must not MOVE to data fields in WORKING-STORAGE since your MMP might be "rolled in and out" at any time and these areas might revert to their initial values unexpectedly.
It is good "form" to avoid MOVE'ing to WORKING-STORAGE in all but exceptional cases, regardless of environment.
If you do not code the VALUE clause the contents of any fields you define here will be unpredictable.
Data in WORKING-STORAGE is not saved and passed from execution to execution, it is intended to be constant data which never is altered.
This logic will be executed only for Browse (xxxLOC, xxxSCN, and xxxFND) functions. It will be executed very early in the processing to initailize VARIABLE-STORAGE and other work fields.
All the standard initializations are done just prior to the %LOCINIT coding; therefore, you may use %LOCINIT to override or supplement the standard logic.
There is no default logic for %LOCINIT, if you do not provide any custom logic then only the standard initialization logic will be done.
Suggested Uses:
You can initialize any work fields you may have added to the %VARSTOR or %LOCVARS definitions.
You can alter the value of UPPERCASE-SW from Y to N to tell the xxxSCN and xxxFND functions that you do not wish for upper and lowercase alphabetics to be compared as equal in its searches. A value of Y causes them to be compared as equal (i.e. "Alan" will match "ALAN" or "alan", etc.).
Cautions:
This logic must never reference screen fields in the Maint Mask (THIS-PGMS-MASK), only those in the COMMON-LOC-MSK (MSK652).
Since this logic is executed prior to the logic which checks that the screen is formatted with the COMMON-LOC-MSK, it is possible that the screen format is neither THIS-PGMS-MSK nor MSK652. You really should not refer to screen fields other than the four standard MAGEC fields which are on all Masks. They are SFUNCT, SKEY, SCOMPL, and SERRMSG.
This logic is executed only for Browse functions. It is executed in the NEW-TRANSACTION-MODE to "position" into the Primary file (using a generic key value in NORMALIZED-KEY).
The default logic calls the MAGEC I/O module to access the file. It uses the FSTAT command to test the file's status (open or closed), then uses the LOCKY command to set the position for subsequent reads.
Suggested Uses:
You might wish to code the logic to access a non-MAGEC type of file (or database). Or you might wish to make minor modifications to the default logic which does the calls.
When you are adding custom coding for %LOCKY you will be presented with a Proforma which resembles the default logic very closely. You may overkey all, or any portion, of it to create whatever coding you desire. The purpose for the Proforma is simply to reduce your keystrokes since most of the time you will probably want to make only minor alterations to the default logic.
You may wish to alter the key value in NORMALIZED-KEY (by forcing a certain prefix, perhaps) just before the LOCKY is done. If you did this based on Operator ID or Location you could effectively restrict users' access on Browses. The fields TWA-EMP-NO and TWA-LOCATION tell you who is logged on and where.
Cautions:
If you code your own non-MAGEC I/O you might want to set the TWA-DB-RETURN-CODE to indicate whether your I/O was successful or not. That will allow the remainder of the logic of the MMP to flow naturally, as if the I/O were a standard MAGEC I/O.
To exit this routine either GO TO AAL440-TEST-RETURN-CODE or just fall through to the "GO TO" which is immediately following the %LOCKY insertion point.
Online Insertion Point %LOCLITS
Found in Model:
MODELMMP MODLOCAT
Location:
WORKING-STORAGE
Description:
This insertion point is obsolete. Use %LITERAL.
Online Insertion Point %LOCMOV
Found in Model:
MODELMMP MODLOCAT MODELWIN
Location:
PROCEDURE DIVISION -- CA700-MOVE-TO-WORK-AREA
Description:
This logic is executed immediately following the standard MOVE's from the MMP's Logical Record to the WS-ITEM area. It is only executed for Browse functions.
The Logical Record is made up of the Elements read from the Primary Data Class plus any Elements read from "Logically Joined" Data Classes plus any "derived fields" you may have calculated in the %JOIN routine. WS-ITEM is the "print line" which is moved to the screen, one line per item.
The xxxSCN and xxxFND functions do their comparisons to determine whether or not to display this item after the %LOCMOV logic is done.
Suggested Uses:
You can modify the "print line" before it is displayed.
You can make your own determination as to whether or not you want this item displayed, to bypass this item you can code:
MOVE B TO PROCESS-INDICATOR.
You might want to have several functions which are variations of the xxxLOC function, each of which displays different data from the Logical Record. In %LOCMOV you could build the alternate print lines and overlay WS-ITEM by moving the appropriate one to it based on the value of TEST-FUNCT.
Cautions:
Do not try to reference screen fields, except in MSK652.
Be careful not to corrupt LIN-CTR, which is used as a subscript into the screen lines, or as a line-per-page counter if PF13 was hit (hardcopy report key).
Do not MOVE to the screen using LIN-CTR if PF13 was hit.
The changes you make to WS-ITEM will affect the comparisons made by the SCN or FND tests.
Online Insertion Point %LOCVARS
Found in Model:
MODELMMP MODLOCAT MODELWIN
Location:
VARIABLE-STORAGE
Description:
This insertion point is obsolete. Use %VARSTOR.
Online Insertion Point %NKLOC
Found in Model:
MODELMMP MODLOCAT MODELWIN
Location:
PROCEDURE DIVISION -- BA300-NORMALIZE-KEY
Description:
The default logic for this insertion point is the entire BA300-NORMALIZE-KEY THRU BA399-EXIT routine. It is executed for Browse functions (xxxLOC, xxxSCN, xxxFND) to convert the operator's entry into SKEY into the format used as a key to read the Primary Data Class. See Diagram 📰
Suggested Uses:
It is very unlikely that you will ever need to use this insertion point. If you do you must replace the entire routine, including the BA300-NORMALIZE-KEY and BA399-EXIT paragraph names.
If you have a size problem with your MMP (it's too big), and you have a simple key format, then you might want to save space by writing a simpler, smaller, less versatile routine to replace the standard one.
Cautions:
Do not forget those paragraph names.
The standard routine is very powerful and flexible. It handles multi-key files with compound keys with mixed data representations (COMP, COMP-3, ALPHANUMERIC, etc.). If you replace it, you are on your own!
Take a good look at the standard routine first. It is generated based on your KYF definitions for the Primary Data Class.
See if you can intercept the key value (in TEST-KEY) in the %PFKEYL insertion point and "massage" it there rather than using %NKLOC, if at all possible.
Online Insertion Point %NORMKEY
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- BA400-NORMALIZE-MAINT-KEY
Description:
This logic is within the Maintenance functions' Normalize Key routine. It is positioned after the standard logic has done all of its editing and reformatting of the key value (from the screen field: SKEY). If any errors were found then the %NORMKEY logic will not be executed since the routines above exit with an error message when they detect an error. See Diagram 📰
The complete formatted key value, presumably ready for use to read the Primary Data Class, will be in FILE-KEY, ready to be MOVE'd to NORMALIZED-KEY, where the I/O routines will be looking for it later. The MOVE FILE-KEY TO NORMALIZED-KEY is coded immediately following the %NORMKEY insertion point.
Suggested Uses:
You may code some additional edits of the key data. If you detect an error you can GO TO BA480-BAD-KEY to properly set the error indicators. You may MOVE an error message to the screen field: SERRMSG, if you like.
You may "massage" the key value here. You may add a prefix or suffix based on the Terminal ID, Operator ID, Location, or any other criteria. This might be valuable to help you assure that operators only access their own data.
Make your alterations in the FILE-KEY area, it will be MOVE'd to NORMALIZED-KEY when you fall-through to the following code unless you have exited with an error (to BA480-BAD-KEY).
Cautions:
Either GO TO BA480-BAD-KEY or fall through to the following MOVE to NORMALIZED-KEY. Do not GO TO BA499-EXIT without the NORMALIZED-KEY area being properly set.
If you do I/O here you should save TWA-DB-REQUEST in TWA-DB-REQ-SAV and restore it when you are done.
This logic applies only to the MAINT-FUNCTION's. Do not confuse this insertion point with the %NKLOC insertion point which is for BROWS-FUNCTION's.
Online Insertion Point %PFKEYL
Found in Model:
MODELMMP MODLOCAT MODELWIN
Location:
PROCEDURE DIVISION -- AAL200-BROWSE-MAINLINE
Description:
This logic is executed for every Browse function, in NEW-TRANSACTION-MODE and in CONTINUATION-MODE. It is at the very top of the mainline logic and is the earliest point at which you can intercept the transaction, except that you can intercept it earlier in the %PREINIT insertion point which is before the logic has even determined whether this is a MAINT-FUNCTION or a BROWS-FUNCTION.
This logic is executed prior to the verification that the COMMON-LOC-MSK is formatted.
There is default logic for this insertion point. It tests for the standard SAA compliant PF keys (PF7=browse backward, PF8=browse forward, PF11=help index, PF16=copy data to buffer, PF1=help).
Suggested Uses:
You can intercept the Browse logic at the very beginning and "massage" the SKEY or SFUNCT values, if you like.
You can, conditionally or unconditionally, bypass the entire remainder of the standard logic by "doing your own thing" and then GO'ing to AA800-SEND-SCREEN or AA900-GOBACK.
You may also have some custom logic in the %SNDSCRN insertion point, at the very end of the processing logic.
You can, in %PFKEYL test for which transmit key (ENTER or PF key) was hit, and take any actions accordingly. The 88-level tests for which key was hit (TWA-MSK-PFn-HIT, etc.) will work correctly even if the COMMON-LOC-MSK has not yet been formatted.
You MAY simulate any valid key having been hit by MOVE'ing the appropriate value to TWA-MSK-AID, to "fool" the MMP.
Cautions:
You should not refer to screen fields, except for the four standard MAGEC fields which are present on any Mask (SKEY, SFUNCT, SCOMPL, SERRMSG).
Remember that the MMP might initialize (format) the TWA-MSK-AREA (overlaying anything you have MOVE'd there) immediately following the %PFKEYL logic.
If you wish to alter the contents of SKEY and/or SFUNCT then you should MOVE the new value(s) to TEST-KEY and TEST-FUNCT as well.
Do not use TEST-KEY or TEST-FUNCT as work areas, they contain the current function and key value from the screen.
Remember, PF13, PF15, PA1, CLEAR, and PA2 have predefined meanings in MAGEC!
Online Insertion Point %PFKEYM
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AAM200-MAINTENANCE-MAINLINE
Description:
This logic is executed at the very beginning of the mainline for all MAINT-FUNCTION's (xxxADD, xxxCHG, xxxSEE, etc.). It is done for every transaction, whether in NEW-TRANSACTION-MODE or in CONTINUATION-MODE.
The default coding tests for the PF7 or PF8 keys being hit and sets TWA-BROWSE-DIRECTION to B (backwards browse if PF7) or F (forward browse if PF8) and transfers to the xxxNXT function, or for PF4 on any other MAINT-FUNCTION to transfer to the xxxLOC function. It tests for PF1 and PF2, the high-level and low-level help keys, and for PF11, the help index key, and for PF16 and PF17, the copy and paste keys. It also checks for a movement of the cursor to denote that the operator may have intended to do a xxxCHG but forgot to alter the function code (in SFUNCT).
Suggested Uses:
You can test for any PF key here before the standard mainline logic. You can alter the key value (in SKEY and TEST-KEY) and/or the function code (in SFUNCT and TEST-FUNCT). You can also bypass the entire standard mainline by coding your own logic and then GO'ing to AA800-SEND-SCREEN or to AA900-GOBACK. You may want to "fool" the standard logic of the MMP by altering the value in TWA-MSK-AID to indicate which key was hit (ENTER or a PF key).
If you wish to automatically generate the key value on an ADD function, then you might want to intercept the operator's key entry (in SKEY and TEST-KEY) here so as to allow it to pass the Normalize-Key editing even though the actual key value will not be determined until just prior to adding the record in the %ADDIT insertion point. This will allow the operator to omit the key value when entering the xxxADD command without receiving the INVALID-KEY message.
Some installations prefer to have the operator enter a key value of "NEW" or some other such phrase rather than just leaving the SKEY field blank.
Cautions:
Remember, PA1, PA2, CLEAR, PF15, and PF13 have predefined meanings in MAGEC. SKEY has already been MOVE'd to TEST-KEY so you must make any changes to both fields!
Since the screen may not yet have been formatted with THIS-PGMS-MSK you should avoid referencing screen fields except for the standard MAGEC fields, SFUNCT, SKEY, SCOMPL, and SERRMSG.
If you want to alter SFUNCT and/or SKEY you should also MOVE them to TEST-FUNCT and TEST-KEY.
If the access method for your Primary file is one which does not support backwards browses, you should override the MOVE B TO TWA-BROWSE-DIRECTION and also overlay the NXT-OR-PREV-MSG by MOVE'ing your own message to it.
Online Insertion Point %PREINIT
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AA100-CHECK-FUNCTION
Description:
This logic is executed at the very beginning of the mainline for all BROWS-FUNCTION's and MAINT-FUNCTION's. It is done for every transaction, whether in NEW-TRANSACTION-MODE or in CONTINUATION-MODE.
There is no default code. If you do not provide any customization coding then only a comment line will be inserted into the program.
Suggested Uses:
You can intercept the logic of the program at the very beginning. This is a handy place for accomplishing some necessary database "binding", i.e. for DL/1 scheduling the PCB, or for SQL issuing the CONNECT.
You can alter the delimiter character used for the free-form data in SKEY. For example: MOVE COMMA TO D-LIMITER. D-LIMITER has a default value of slash (/), which is normally the key field separator for MAGEC screens. Moving a different character to D-LIMITER changes the key delimiter so that the Normalize-Key routines now expect a key of, say: 123,xyz instead of 123/xyz.
You can alter the color of the pop-up window which appears for the Short-List feature. To do so, you set the desired color value into the WINDOW-COLOR variable. For example: MOVE TURQUOISE TO WINDOW-COLOR. The color codes are discussed in the "Color 3270" chapter of this Programmer's Reference manual. The default color for the pop-up window is PINK.
Cautions:
This insertion point is prior to the initialization of the VARIABLE-STORAGE area and prior to the setting of the function and key values into TEST-KEY and TEST-FUNCT. You must not code references to the 88-levels which define the valid conditions for those areas, i.e. ADD-FUNCTION, BROWS-FUNCTION, et cetera. unless you first MOVE SFUNCT TO TEST-FUNCT.
It is possible that the Mask for this program has not yet been initialized at this point in the logic. Do not reference screen fields without first interrogating which Mask is initialized, i.e: IF TWA-MSK-ID = THIS-PGMS-MSK (or COMMON-LOC-MSK) . . .
This logic is executed in the CONTINUATION-MODE of the xxxDEL and xxxCHG functions. It reads the Primary Data Class' record (Elements) with Exclusive Control in preparation for the update or delete operation. The standard default logic calls the MAGEC I/O module to do the read and then PERFORM's the JA100-LOGICAL-JOIN routine to read any Secondary data.
The default code also compares the Audit-Stamp for the record (if it has one) against the Audit-Stamp it saved when the record was read (in %REDKY) in the NEW-TRANSACTION-MODE to see if another task has updated it while the operator was mulling over the screen.
Suggested Uses:
You could override the entire default routine with your own to access a non-MAGEC file or database.
When you begin to enter customization coding for %RDUKY you will be presented a Proforma routine which very much resembles the default code. This is to allow you to make alterations or additions to the default logic without having to rekey the entire routine.
Cautions:
To exit this routine GO TO AAM440-TEST-RETURN-CODE or just fall through to the GO TO which is coded immediately following the %RDUKY insertion point.
If you substitute the call to the MAGEC I/O module with your own read of a non-MAGEC file or database, you should set an appropriate value in TWA-DB-RETURN-CODE so that the standard MMP logic can work as usual.
Do not forget JA100-LOGICAL-JOIN!
Online Insertion Point %REDKY
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AAM410-READ-BY-KEY
Description:
This logic is executed in the NEW-TRANSACTION-MODE of the MAINT-FUNCTION's. It is executed only if the Normalize Key routine has found no errors in the key value given (in SKEY). The default logic for %REDKY tests the file's status (open or closed) using the FSTAT command to the MAGEC I/O module, then uses the REDKY command to read the Primary Data Class using the key value from NORMALIZED-KEY. It then PERFORM's the JA100-LOGICAL-JOIN routine to execute your %JOIN code to Logically Join data from other files or from calculations. The result is the Logical Record for this function.
The default also saves the Audit-Stamp so it can be compared later in the %RDUKY logic.
Suggested Uses:
You may read a non-MAGEC file or database by replacing the default code with your own. Or you may make minor modifications or additions to the default logic.
When you begin to add your custom code for %REDKY you will be presented a Proforma which is very similar to the default logic. You may overkey it entirely or in part to make any changes you wish.
You may wish to check the record for non-numerics in numeric fields and set them to zero. This is sometimes useful when new fields are added to a record (Element) definition where a FILLER used to be.
Cautions:
Be sure you exit this routine by GO'ing to AAM440-TEST-RETURN-CODE or by falling through to the GO TO which is immediately behind the %REDKY insertion point.
If you do not call the MAGEC I/O module then you should be sure to set the TWA-DB-RETURN-CODE appropriately so that the subsequent logic of the MMP will properly recognize the REC-FOUND or NOT-FOUND conditions.
Online Insertion Point %REDLE
Found in Model:
MODELMMP MODLOCAT MODELWIN
Location:
PROCEDURE DIVISION -- AAL420-READ-FIRST-RECORD
Description:
This logic is executed for BROWS-FUNCTION's only, and only in the NEW-TRANSACTION-MODE. It is executed after the %LOCKY logic and only if the LOCKY was successful. This logic is to read the record you have positioned to in %LOCKY.
The default code merely GO's to AAL430-READ-NEXT-RECORD to do the read.
Suggested Uses:
You may want to code your own read to a non-MAGEC file or database.
Cautions:
To exit the routine be sure you GO TO AAL440-TEST-RETURN-CODE. Be sure you alter the TWA-DB-CMD from LOCKY to another command since LOCKY will cause the AAL440 routine to loop back to the AAL420 routine endlessly.
If you do your own I/O be sure to set the TWA-DB-RETURN-CODE appropriately so the subsequent MMP logic will work properly.
This logic is executed in both BROWS-FUNCTION's and in MAINT-FUNCTION's. It is the logic to read "pseudo-sequentially", either forward or backward. The direction is controlled in the MAGEC I/O module based on the value of TWA-BROWSE-DIRECTION (F or B).
The default logic for %REDNX calls the MAGEC I/O module, then it PERFORM's JA100-LOGICAL-JOIN.
It is executed for xxxLOC, xxxSCN, xxxFND, and xxxNXT functions.
Suggested Uses:
You might want to do I/O to non-MAGEC files or databases instead of using the MAGEC I/O module.
You might want to check some data in the record (Elements) just read so you can bypass some (such as wrong record type or wrong company).
You may want to skip over entire groups of records based on the high-order position of the key value. You could do a LOCKY followed by REDLE to reposition past them.
You can simulate end-of-file by MOVE'ing '14' to TWA-DB-RETURN-CODE and allowing the logic to fall through to the test-return-code routine (see Cautions).
Cautions:
This logic will be used in both the Browse and Maintenance mainlines. If you insert code which needs to exit the routine (or reference any paragraph names in the mainline then you must check which mainline you are in. For example:
IF (MAINT-FUNCTION)
GO TO AAM440-TEST-RETURN-CODE
ELSE
GO TO AAL440-TEST-RETURN-CODE.
Also, since this logic will be inserted twice (once in each mainline) you must avoid coding any paragraph names, they would be duplicated. It might simplify your work to place your logic in a routine which is PERFORM'd from %REDNX. The PERFORM'd routine should be in the %SUBRTNM insertion point (%SUBRTNL for MODLOCAT).
If you code non-MAGEC I/O, set TWA-DB-RETURN-CODE.
Online Insertion Point %RELES
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AAM740-RELEASE-EXCL-CONTROL
Description:
This logic is executed only for MAINT-FUNCTION's in the CONTINUATION-MODE, and only when the ERROR-FOUND condition has been set (usually by either MAGEC Automatic Editing or by your coding in %EDIT). It drops the Exclusive Control which was obtained in the read-for-update logic earlier (%RDUKY).
The default logic for %RELES calls the MAGEC I/O module using the RELES command. It then exits to the AAM750-TEST-RETURN-CODE routine.
Suggested Uses:
If you coded a non-MAGEC I/O in %RDUKY to read-for-update then you should probably code an appropriate Release of the Exclusive Control here, in %RELES.
Since the fact that %RELES is executed indicates that some type of error has been detected, you could update some sort of a log file here.
Cautions:
Be sure to exit to AAM750-TEST-RETURN-CODE. You may just fall through to the GO TO which is immediately following the %RELES insertion point.
Online Insertion Point %REMARKS
Found in Model:
MODELMMP MODELWIN MODLOCAT
Location:
IDENTIFICATION DIVISION -- REMARKS SECTION
Description:
The text you code in the %REMARKS insertion point will be inserted in the front of the generated MMP in the REMARKS section. It is for comments only, it does not execute.
Suggested Uses:
Describe what this MMP does, omit the standard things which all MMP's do, that is documented in the Application User's Guide which is provided with MAGEC.
Cautions:
Don't get too wordy, it gets boring.
Put an asterisk (*) in column 7 so that your remarks will be compatible with all versions of Cobol, including the '85 standard and PC MAGEC.
Online Insertion Point %SCHEMA
Found in Model:
MODELMMP MODELWIN
Location:
DATA DIVISION
Description:
The %SCHEMA insertion point is in the data division immediately before the WORKING-STORAGE SECTION.
Suggested Uses:
You can insert database SCHEMA coding here. For instance, for IDMS.
Cautions Check the rules and restrictions for your DBMS regarding this coding. Online Insertion Point %SELECT Found in Model:
MODELMMP MODLOCAT MODELWIN
Location:
PROCEDURE DIVISION -- CA700-MOVE-TO-WORK-AREA
Description:
This logic is near the top of the CA700 routine. It is a handy place to intercept each record that was read to determine whether or not you want to show it on the LOC, SCN, or FND screen display. The CA700 routine is PERFORM'd from the Browse Mainline only. It formats a "print line" in WS-ITEM to be MOVE'd to a screen line for the browses.
A one-byte switch, PROCESS-INDICATOR, is used to control the subsequent processing. A value of P (the default) indicates that this record is to be processed, a value of B indicates that this record is to be bypassed, a value of E indicates that the program is to simulate End-Of-File (and not process this record).
Suggested Uses:
You might test for record type on a multi-record-type file to bypass the inappropriate records for this browse. You might also test for some other logical subdivision, such as Company code to bypass records for all companies other than the one to which this operator belongs. Remember that the "Logical Record" you are looking at is made up of the combined data from the Primary Data Class plus any other Data Classes read in the %JOIN routine plus any Derived Fields which you may have COMPUTE'd in %JOIN.
The SCAN-CTR is incremented just prior to your %SELECT logic. It tells how many records have been read so far to try to fill the screen lines (this transaction). CUMULATIVE-SCAN-CTR tells how many have been read since the first screen of this browse. On the first "page" these two will be the same.
The SCAN-CTR is compared to SCAN-LIMIT (VALUE'd at 1000) to determine if the program should continue reading or just send what has been found so far and ask the operator to press the ENTER key to continue. You could alter the contents of SCAN-LIMIT by simply MOVE'ing some other value to it here. You could even do so based on which operator was at the terminal or which terminal or which location, etc.
CUMULATIVE-SCAN-CTR is displayed to the screen after the last line of each browse display, do not mess with it! You may, however, alter SCAN-CTR to affect the comparison with SCAN-LIMIT (i.e. MOVE 1000 TO SCAN-CTR) in order to "force" the transaction to stop reading and send the screen. This may be preferrable to altering SCAN-LIMIT in a truly reentrant environment since SCAN-LIMIT is in WORKING-STORAGE.
Cautions:
Remember, this logic is used only in BROWS-FUNCTION's, do not refer to any screen fields except those in MSK652.
Be careful not to corrupt the value in LIN-CTR as it is the subscript used to indicate which line on the screen (or, if PF13 was hit, on the hardcopy page) was last used.
The WS-ITEM print line has not yet been built, do not try to test for values in it here. You can do that in %LOCMOV, if necessary.
Online Insertion Point %SKEYBLD
Found in Model:
MODELMM MODELWIN
Location:
PROCEDURE DIVISION -- CA800-BUILD-SKEY
Description:
This logic is PERFORM'd from the CA700-END paragraph for the BROWS-FUNCTION's. It is also PERFORM'd from the Maintenance mainline for the NXT function. The function of this routine is to construct the Master (Primary) key, in the format that an operator would enter it (including any slashes, etc.) from the record data and then to MOVE the results to the screen in SKEY (also to TWA-LAST-KEY).
This is done to simulate an operator's entry of the full key when using the cursor selection features of BROWS-FUNCTION's or the forward or backward reading of NXT functions.
The default code for %SKEYBLD is the entire routine, including the CA800-BUILD-SKEY and CA899-EXIT paragraph names.
Suggested Uses:
In the unlikely event that you need to entirely replace the CA800 routine's logic you would use this insertion point.
To make more minor alterations to the output of the CA800 routine you might consider using the %SNDSCRN insertion point to intercept the screen just before it is sent. An example of some of the types of "minor" alterations you may want to make is adding a standard prefix or suffix for the Browse functions' cursor selection feature.
Cautions:
The logic of the CA800 routine (the default code) is somewhat complex and is based upon the definition of the Master key (xxxK1) for your MMP's Primary Data Class. It handles multi-component keys, mixed upper and lower case alphabetics within the key value, and mixed data representations (binary, packed, zoned decimal, signed, unsigned, alphanumeric). You may want to think twice before replacing your own routine for it.
The output of this routine is MOVE'd to both SKEY and TWA-LAST-KEY.
The input to this routine comes from the Cobol data-name you specified in the KYF file definition for the Primary Data Class' Master key (xxxK1)
Online Insertion Point %SNDSCRN
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AA800-SEND-SCREEN
Description:
This logic is executed just before the MMP exits, returning to MAGECCP. Most of the time the MMP is exiting to allow MAGECCP to send the screen and then terminate the task, sometimes it may be exiting with a command in TWA-NONTP-REQUEST to invoke (fetch) another function (program).
There is no default logic for %SNDSCRN, if you do not provide any customization coding then it will simply be a comment.
Suggested Uses:
This is a handy place to intercept the screen just prior to its being sent back to the operator. You might wish to put some finishing touches on it, like blanking out a field if its value is zero, or setting the highlight (or color) attribute if its value is higher (or lower) than a certain level, and so forth.
You may wish to "massage" the SKEY value set by the cursor select feature (in CA800-BUILD-SKEY) on a BROWS-FUNCTION. For example, you might want to add some prefix or suffix to the key.
This logic is executed both for MAINT-FUNCTION's and for BROWS-FUNCTION's
Cautions:
To exit you should GO TO AA900-GOBACK, or allow the logic to fall through to the GO TO which is coded just below the %SNDSCRN insertion point.
If you reference any screen fields other than the four MAGEC standard fields (SFUNCT, SKEY, SCOMPL, and SERRMSG) then you must first test whether your Maintenance Mask or the Common Browse Mask (MSK652) is formatted. This logic is executed for both MAINT-FUNCTION's and BROWS-FUNCTION's!
If you alter the contents of SKEY you will probably also want to set the new contents into TWA-LAST-KEY so that the MMP and MAGECCP will know what the key value was when it compares against it on the next transaction. That is how they know whether the operator has changed it.
Online Insertion Point %SPOOL
Found in Model:
MODELMMP
Location:
PROCEDURE DIVISION -- CB900-SPOOL
Description:
This insertion point is used to contain the logic to spool print data from your MMP.
Suggested Uses:
The default coding for this insertion point is contained in a -MAGECINC'd member named SPOOLIT. It is the standard logic for spooling a report from the MAINT or BROWSE screens. You can override the default logic by coding your own custom logic, perhaps to spool to a spooler other than MAGEC's intrinsic TP Spooler.
Cautions:
Be sure you understand the protocols for using the MAGEC spooler or any other spooler software you are trying to use. Misuse can cause serious abend difficulties.
Online Insertion Point %SUBRTNL
Found in Model:
MODELMMP MODLOCAT MODELWIN
Location:
PROCEDURE DIVISION -- before JA999-STOP-RUNAWAY
Description:
This insertion point is positioned near the very end of the program to allow you to insert entire routines to be PERFORM'd from elsewhere.
Suggested Uses:
Entire routines, including all paragraph names and exits can be inserted here and PERFORM'd from anywhere else.
This is handy when converting to MAGEC from "native" programs which contain sections of coding which you wish to retain. One example might be a complex cross-field edit routine, another might be a large calculation routine.
You can insert virtually the entire PROCEDURE DIVISION for a program here, then in the %PFKEYM (or %PFKEYL) insertion point you could PERFORM it and GO TO AA900-GOBACK. This would effectively override the entire logic of the MMP with your own. You would most likely do something like that for a special function code which you might have added to the MMP in the %FUNCT insertion point in addition to the standard nine functions MAGEC generates.
%SUBRTNM and %SUBRTNL are functionally equivalent in MODELMMP
Cautions:
If your coding contains an error which causes it to bypass the EXIT (or implied EXIT) of a routine, then you might very well receive the FALL-THRU-ERROR message when you execute the MMP. This is to prevent more serious consequences, such as causing the TP Monitor to abend, or go to EOJ.
Online Insertion Point %SUBRTNM
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- before ZZ999-STOP-RUNAWAY
Description:
This insertion point is positioned near the very end of the MMP. It is a convenient place to insert miscellaneous subroutines which can be PERFORM'd from any other point in the program.
Suggested Uses:
Entire routines, including all paragraph names and exits can be inserted here and PERFORM'd from anywhere else.
This is handy when converting to MAGEC from "native" programs which contain sections of coding which you wish to retain. One example might be a complex cross-field edit routine, another might be a large calculation routine. You can insert virtually an entire program here, then in the %PFKEYM (or %PFKEYL) insertion point you could PERFORM it and GO TO AA900-GOBACK. This would effectively override the entire logic of the MMP with your own. You would most likely do something like that for a special function code which you might have added to the MMP in the %FUNCT insertion point in addition to the standard nine functions MAGEC generates.
%SUBRTNM and %SUBRTNL are functionally equivalent in MODELMMP
Cautions:
If your coding contains an error which causes it to bypass the EXIT (or implied EXIT) of a routine, then you might very well receive the FALL-THRU-ERROR message when you execute the MMP. This is to prevent more serious consequences, such as causing the TP Monitor to abend, or go to EOJ.
Online Insertion Point %UPDAT
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AAM720-UPDATE-DATABASE
Description:
This logic is executed only for CHG-FUNCTION's and only in the CONTINUATION-MODE and only if the ERROR-FOUND condition has not been set. The ERROR-FOUND condition is ordinarily set by either MAGEC Automatic Editing or by your logic in the %EDIT insertion point if screen data fails validity tests or for other reasons.
The purpose for %UPDAT logic is to do the actual I/O to update the database for the Primary Data Class' Elements.
The default logic calls the MAGEC I/O module with the command "UPDAT" and then exits to AAM750-TEST-RETURN-CODE.
Suggested Uses:
You may need, sometime, to override the default logic entirely with your own coding to access a non-MAGEC file or database.
You may wish to merely modify the default logic so as to post to some log or control record just before or after the UPDAT occurs.
You may wish to make some last second (micro-second) alterations to the record (Elements) being updated, such as posting to some fields to indicate the exact date and time that certain values were updated in the record (if they were altered in this update).
Cautions:
Be sure you exit to AAM750-TEST-RETURN-CODE. If you access a non-MAGEC file then you should set the field TWA-DB-RETURN-CODE appropriately to indicate the success or failure of your update: a value of SPACES indicates success, a value of '14' indicates failure. This allows the subsequent MMP logic to flow normally.
The data in AUDIT-STAMP will be filled in by the MAGEC I/O module when it is called. The contents are unreliable before the call. They are also unreliable if the Primary Data Class does not have Audit-Stamp support or if you do non-MAGEC I/O.
Online Insertion Point %UPDERR
Found in Model:
MODELMMP MODELWIN
Location:
PROCEDURE DIVISION -- AAM751-UPDERR
Description:
This logic is executed when a serious error is encountered while attempting to do an update, add, or delete operation to the database or file.
It is executed only for ADD, CHG, DEL, and DUP type functions and only in CONTINUATION-MODE.
The default logic for %UPDERR simply MOVE's the DB-ERR-MSG to the screen in SCOMPL and GO's to AA800-SEND-SCREEN.
Suggested Uses:
You might (not likely) want to try your own recovery procedure for failed updates.
Cautions:
Update failures are more often than not the result of errors in your program rather than actual file errors. True file errors are normally handled by the MAGEC I/O module which aborts the task without even passing control back to your program.
Online Insertion Point %USRAREA
Found in Model:
MODELMMP MODELWIN
Location:
LINKAGE SECTION -- after TWA
Description:
This insertion point is provided so that you can add your own Cobol '01-levels' into the LINKAGE SECTION.
The default logic for %USRAREA is a comment line.
Suggested Uses:
If you are using IMS or DLI (low-level), then you will need to define PCB's here. You must also initialize the USER-BLL cells accordingly.
If you would like to access the CICS TCTUA area, then this is where you would place your definition. Initializing the BLL CELL is your responsibility.
Cautions:
Referencing an '01-level' in the LINKAGE SECTION without properly establishing adressability (loading the BLL CELLs) will cause unpredictable results, including, sometimes, unexplained crashes of the TP Monitor which are nearly impossible to debug.
Online Insertion Point %VARSTOR
Found in Model:
MODELMMP MODELWIN
Location:
LINKAGE SECTION -- VARIABLE-STORAGE
Description:
This insertion point is located at the very end of VARIABLE-STORAGE. It enables you to insert your own work fields and variables.
VARIABLE-STORAGE is a Cobol 03 level group item. The MMP MOVE's LOW-VALUES to it in the initialization routine for every transaction.
Suggested Uses:
You can add Cobol data definitions to the VARIABLE-STORAGE area by using Cobol levels 04 and higher. They will then be initialized to LOW-VALUES for you.
You can add an item with a Cobol level 03 here. It will not be a part of VARIABLE-STORAGE. It and all that follows it will not be initialized. They will not be passed from transaction to transaction either, their contents will be entirely random each time the MMP is entered. It is up to you to initialize these areas (in %INIT) if necessary.
Cautions:
Packed or zoned-decimal numerics should be initialized by you to avoid data exception abends.
This area is part of the TWA. There is a maximum size for the TWA specified by your installation, it is something between 16K and 32K, check with your Systems Programmers if in doubt.
Batch Insertion Point %ACCUMS
Found in Model:
MODELRPT
Location:
WORKING-STORAGE -- under ACCUMULATORS-AREA
Description:
This insertion point allows you to add your own custom coding into the array of accumulators, after the generated "buckets".
Suggested Uses:
You could define some of your own accumulator buckets which you could add into in the %ADDTOT and %ROLLAC insertion points.
You could insert an "01-level" to redefine the entire accumulator table. The table contains all the accumulator buckets plus the control fields to specify whether each level of breaks is to have totals printed for, page ejects before and after, and the heading to appear on the report at each break level.
Since this is at the end of WORKING-STORAGE, you can add as many of your own areas (starting with an 01-level) as you like.
Cautions:
Watch out for corrupting the numeric accumulators with non-numeric data if you redefine the table. The VERIFY option does not check for bad data in the accumulators, it assumes that all data will always be valid. Bad data in the table will likely cause the program to abend with a "data exception".
The number of accumulator levels (occurrences) will vary from program to program, depending on the number of control breaks specified. Changing the number of control breaks for a given program will alter the number of occurrences generated. The major break level is always (001); the lowest break level can be referenced symbolically as (&LVL). The grand total accumulators can be referenced symbolically as (&OCR). These symbolic occurrence numbers will be resolved by MBPCRE as the program is being generated.
Be careful not to reference an occurrence greater than (&OCR) since that will likely access the beginning of your PROCEDURE DIVISION!
Batch Insertion Point %ADDTOT
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- CA130-ADD-TOTALS
Description:
This logic will be inserted after the generated code which adds to the low-level ("minor" control break level) accumulators from the sorted logical record. The logical record is the result of joining selected data items from all the input files. The code you insert in %ADDTOT is before the data is moved to the detail print line.
Suggested Uses:
You could accumulate your own special totals here in addition to the ones MAGEC will provide.
You could alter the data in the logical record. Since this insertion point is before the MOVE's to the detail print line, that would alter the data shown on the report.
Since this insertion point is just after the standard generated detail-level accumulators, you could also alter the accumulated figures here.
Cautions:
Watch out for clobbering numeric data items (in the sorted logical record) with non-numeric data. If you did not use the VERIFY option, non-numeric data will cause a "data exception" abend.
Do not try to MOVE into the print line (WS-DETAIL-LINE) since the generated logic will MOVE SPACES to it immediately after your %ADDTOT logic, before it MOVE's the data items to it.
Batch Insertion Point %BREAKS
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- CA115-CHECK-FOR-BREAKS
Description:
This logic is inserted immediately before the generated logic which tests for control breaks.
Suggested Uses:
You could test for special conditions and force (or suppress) a control break.
The sorted logical record is available to you at this point. This insertion point is before the accumulation into the detail level accumulators and before the detail print line (WS-DETAIL-LINE) has been built.
Cautions:
The control break logic varies from program to program depending on the number of control breaks and sort fields specified. If you "hard-code" some logic based on a certain number of control breaks, then change the specs to result in a different number of breaks or sort fields, you could have a problem. Refer to the discussion about the insertion point %ACCUMS, also.
Batch Insertion Point %BRKPRT
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- DC200-BREAK-PRINT
Description:
This logic is near the top of the routine which is PERFORM'ed at each control break (if ACCUM-PRINT-SW for this level = Y) to print the total line WS-TOTAL-LINE and, if requested, the average line (WS-AVRAG-LINE). The "total heading line" (WS-TOT-HDG-LINE) has not yet been built.
Suggested Uses:
You could override the entire break total printing routine by coding your own logic and GO'ing to DC299-EXIT.
You can dynamically control forced page breaks before or after each break by setting ACCUM-HOF-BEFORE and ACCUM-HOF-AFTER to Y or N, based on any criteria your desire.
Cautions:
This routine is PERFORM'ed for each level of break. The subscript, THIS-LVL, determines which break level is being processed. If you corrupt the value in THIS-LVL results will be unpredictable (or predictably wrong!).
If you wish to exit this routine you must GO TO DC299-EXIT. It is a very good idea to study the standard generated code before attempting to customize it.
Batch Insertion Point %DATADEF
Found in Model:
MODELRPT
Location:
WORKING-STORAGE -- DB-DATA-AREA
Description:
This code is inserted immediately behind the generated includes (-MAGECINC's) for the program's primary and secondary Elements.
Suggested Uses:
You can code additional data definitions here. These may consist of more -MAGECINC statements or of standard Cobol definitions.
This is a good place to define any non-database (non-file) data, sometimes called "derived data". You could define items here which will be filled in via calculations you will provide in the %JOIN insertion point. This allows you to logically join non-file data to create a logical record. Data fields you have defined here could be referenced as the Source field for a report field (in RPTDEF).
Cautions:
If you define numeric fields in %DATADEF, be sure that they are always initialized with valid numeric data in %JOIN (or elsewhere). If the VERIFY option is off and you leave bad data in a numeric field which is referenced as a Source field, you will abend with a "data exception".
Batch Insertion Point %EOJ
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- ZZ900-EOJ
Description:
This logic is inserted immediately before the GOBACK in ZZ999-GOBACK.
Suggested Uses:
This is a place where you can insert your own special end of job processing. You may need to close some files you have added. You may wish to DISPLAY or print special end of job messages.
Cautions:
The print file may have been closed in the %RPTEND logic.
You must exit the program using a GOBACK, not a STOP RUN, since your program is actually running as a subroutine to the MAGEC batch I/O module (and possibly another database I/O module, as well). When your program executes a GOBACK control returns to the I/O module(s) so that they can close files and clean house. This is especially important when your program is accessing an IMS/DL1 database or a Datacom/DB database as well as standard VSAM files.
Batch Insertion Point %FILEFD
Found in Model:
MODELRPT
Location:
DATA DIVISION -- below PRINT-REC
Description:
This insertion point is in the FILE SECTION, just below the definition of the print file.
Suggested Uses:
You could add definitions for additional files here. You could also redefine the PRINT-REC here if necessary.
Cautions:
The length of the PRINT-REC is variable, depending on the specifications for this program (on the BCHPGM screen).
Batch Insertion Point %FILES
Found in Model:
MODELRPT
Location:
ENVIRONMENT DIVISION -- FILE-CONTROL
Description:
This insertion point is immediately after the generated SELECT statements for the SORT-FILE and PRINTR file.
Suggested Uses:
You could code SELECT statements for your own additional files here.
Cautions:
Do not forget to code the OPEN (in %INITWS or %PREINIT) and the CLOSE (in %EOJ) for your files.
Batch Insertion Point %HDGPRT
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- DA200-HDG
Description:
This logic is performed at all page breaks. It prints the report headings.
Suggested Uses:
You could code your own heading routine to be used in lieu of the default logic which MAGEC will insert here if you do not provide customization for %HDGPRT. This will enable you to produce reports with headings vastly different from the standard headings MAGEC generates.
You could catalogue a standard heading routine on the MAGEC library which produces headings in compliance with your own installation's standards. You could then merely code a -MAGECINC statement in %HDGPRT to include it.
Cautions:
To exit this routine you must GO TO DA299-EXIT.
Batch Insertion Point %INITWS
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- AA000-BEGIN
Description:
This insertion point is near the top of the program logic, just after the standard generated initialization logic. It is the last point before the SORT begins.
Suggested Uses:
You could initialize any variables you have added to the program (in %DATADEF or %ACCUMS).
You could override the settings which control break printing and so forth. These are set in generated code just before the %INITWS insertion point.
You could actually code your own SORT, overriding the generated SORT statement, and then GO TO ZZ900-EOJ.
Cautions:
You are not yet in the SORT, so the SORT-FILE is not yet open.
You have not yet executed the CALL to MAGDBMS with the '*READ' command. This command tells MAGDBMS (the I/O module) that this program does not intend to update any of the files which are accessed, therefore, the I/O module simply opens the files "read-only". If you access a file via MAGDBMS in the %INITWS insertion point, MAGDBMS will open the file for update (the default), unless you first code a CALL using the '*READ' command. It is okay to CALL MAGDBMS with '*READ' multiple times.
Batch Insertion Point %JOIN
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- BB100-LOGICAL-JOIN
Description:
This logic is PERFORM'ed after each read of the primary data. It is where you logically join data from other files or other databases or from calculations. The result of the logical join process is this program's "logical record".
Suggested Uses:
If you use the Automatic Logical Join facilities in creating your program (via BCHPGM, etc.) online, then there will likely already be customization coding generated for you in %JOIN. This generated customization coding will read up-to fifteen (15) secondary files, as specified on your BCHPGM screen definition.
You can read any type of additional file(s) here, MAGEC files or non-MAGEC files.
You can fill in non-file (derived) fields which you have defined in the %DATADEF insertion point.
Cautions:
Do not "clobber" the data which is in DB-DATA-AREA which has been filled in via the preceding reads. If you have defined numeric fields in %DATADEF, be sure to set them to valid numeric values here.
To exit this routine you must GO TO BB900-RETURN or just allow the logic to "fall thru" to BB900-RETURN.
Batch Insertion Point %MGLOCKY
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- BA102-START-BROWSE
Description:
This logic starts (positions) the reading into the primary file. The default logic will CALL the I/O module (MAGDBMS) using the LOCKY command with a key value of LOW-VALUES. This starts reading at the beginning of the file.
Suggested Uses:
You could override the default logic to start reading somewhere other than the beginning of the file by setting a starting key value other than LOW-VALUES into DB-KEY-VALUE.
You may wish to do some special routine just before (or just after) positioning into the file -- for instance, OPEN one of your own files.
After the LOCKY command is processed the key value of the first record to be read is returned in DB-KEY-VALUE, you might want to interrogate it.
Cautions:
If you bypass the LOCKY CALL altogether, the subsequent REDLE and REDNX CALLs will not work correctly -- you should override them with customization also.
Batch Insertion Point %MGREDLE
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- BA102-START-BROWSE
Description:
This insertion point immediately follows the %MGLOCKY insertion point. The default logic for %MGREDLE will CALL the I/O module (MAGDBMS) with the REDLE command to read the record which you just positioned to via the LOCKY command.
Suggested Uses:
You may wish to read a non-MAGEC file, rather than use the standard generated code to CALL MAGDBMS.
You may wish to do something special for the first record read, you could do that here.
Cautions:
It is a good practice to test the return code (IF REC-FOUND) and to handle an error condition if one arises. You could simply GO TO BZ190-END to terminate the input procedure of the sort and proceed to the output procedure. Some sort software does not handle "zero records sorted" very well, therefore you might want to issue a message and terminate the program.
If you do not choose to terminate the program in this insertion point then you should GO TO BA112-GET-JOINED-DATA, or just fall thru to the generated statement below %MGREDLE which will GO TO that routine.
If you read a non-MAGEC file, you should be sure to set the values in DB-REQUEST-AREA accordingly so that subsequent program logic operates correctly. Particularly, be sure to set DB-RETURN-CODE correctly.
Batch Insertion Point %MGREDNX
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- BA110-READ-NEXT
Description:
This insertion point is used to sequentially read through the primary file. The default code will CALL the I/O module (MAGDBMS) using the REDNX command.
Suggested Uses:
You could override the standard MAGEC reads with your own reads of a non-MAGEC file.
You might wish to place code here to bypass certain records. An example of that would be when reading a file which has multiple record types, you may wish to process only one type. You can bypass records by coding GO TO BA110-READ-NEXT.
Cautions:
If you read a non-MAGEC file here, it is best to set appropriate values into the DB-REQUEST-AREA so that subsequent processing will work correctly. Be especially sure to set the DB-RETURN-CODE.
To exit this routine you should GO TO BA112-GET-JOINED-DATA, or just fall thru to that paragraph.
When you are bypassing records (as described above) do not forget to test the return code (IF NOT-FOUND) so as to stop at end-of-file.
Batch Insertion Point %MVTOPRT
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- CA130-ADD-TOTALS
Description:
This insertion point is immediately after the generated logic which MOVE's from the sorted logical record to the detail print line (WS-DETAIL-LINE).
Suggested Uses:
You could modify the print-line here before it is actually written to the printer. If you wish to add some fields to the print line which were not defined in the specifications (from RPTDEF, online), you will need to MOVE WS-DETAIL-LINE to a work area which you have defined in %DATADEF, then make any alterations you wish, then MOVE it back to WS-DETAIL-LINE.
Cautions:
The maximum length of a print line is determined by your specifications in BCHPGM and by the hardware limitations of your printers.
To exit this routine you must fall thru to the generated code which immediately follows %MVTOPRT. That code will PERFORM DA100-PRINT and will then GO TO CA110-RETURN. If you wish, you could code your own print routine in %MVTOPRT to replace DA100-PRINT; just be sure to GO TO CA110-RETURN when you are done.
Batch Insertion Point %MVTOSRT
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- BA150-RELEASE
Description:
This insertion point is immediately after the generated MOVE's which build the sort record from the logically joined data in DB-DATA-AREA.
Suggested Uses:
You can code your own additional MOVE's to override some of the values MOVE'd by the generated code.
You could code MOVE's to fill in fields in the sort record which were created as a result of your defining additional fields on the online RPTDEF screen, whether those fields were specified as displayable or non-displayable and whether they had a Source field specified or not.
You could accumulate some of your own statistics of records about to be released to the sort.
You could cause this record not to be released to the sort by coding a GO TO BA110-READ-NEXT.
Cautions:
If you wish to bypass some records (not release them to the sort), it is better to do that in %SELECT, if at all possible.
To exit this routine either fall thru to the RELEASE statement generated below it, or GO TO BA110-READ-NEXT.
Batch Insertion Point %PREINIT
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- at the very top
Description:
This insertion point allows you to intercept the logic at the very beginning.
Suggested Uses:
If you are accessing IMS/DLI or other DBMS's, you may need to insert an ENTRY statement here.
Cautions:
The initialization has not been done yet, contents of work fields may be unpredictable. Initialization of the report break controls and page-break controls into the ACCUMULATORS-AREA has not been done yet.
The '*READ' CALL to MAGDBMS has not been done yet. Refer to discussion about the %INITWS insertion point regarding the `*READ` as well.
Batch Insertion Point %REMARKS
Found in Model:
MODELRPT
Location:
ID DIVISION -- REMARKS
Description:
This insertion point allows you to insert comments into the beginning of the program.
Suggested Uses:
You could make your program easier to maintain by someone else.
Cautions:
The 1985 standard for Cobol removes the REMARKS section. You should code an asterisk (*) in column 7 of your comments so that MAGEC can maintain portability should you upgrade to the '85 compiler. All MAGEC-generated comments follow that convention.
Batch Insertion Point %ROLLAC
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- DC100-ROLL-ACCUMULATORS
Description:
This insertion point is immediately behind the generated logic to "roll" the accumulated totals to the next break level and to zero them for this level.
Suggested Uses:
You could code logic to roll some accumulators which you have added to the ACCUMULATORS-AREA, via the %ACCUMS insertion point.
Cautions:
The subscripts THIS-LVL and NEXT-LVL control the operation of this routine. Be sure not to corrupt them.
To exit this routine GO TO DC199-EXIT.
Batch Insertion Point %RPTEND
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- CA190-END
Description:
This insertion point is at the logical end of the output procedure of the sort. The default logic displays standard end-of-job counts and falls thru to the CA199-EXIT paragraph.
Suggested Uses:
If you do not want the end-of-job counts, of if you want others -- this is the place to DISPLAY/PRINT them. You should close the print file when you are done, unless you will close it in the %EOJ routine.
Cautions:
Remember, you have reached end-of-file on the sort file. Do not try to reference fields in the sort record.
To exit this routine you must GO TO CA199-EXIT, or fall thru to it.
Batch Insertion Point %SELECT
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- BA115-SELECT
Description:
This logic is immediately before the RELEASE to the sort. It is in the input procedure of the sort.
Suggested Uses:
You can interrogate any fields in the input data since all reads and joins should already be done. You can cause this logical record to be processed, to be bypassed, or to simulate end-of-file by setting the appropriate value into PROCESS-INDICATOR.
Setting PROCESS-INDICATOR to P causes this record to be processed; setting it to B causes this record to be bypassed; setting it to E causes the program to act as if it has reached end-of-file on the input (no more records will be read, control passes to the output procedure).
PROCESS-INDICATOR is set to P (the default) just prior to the %SELECT insertion point.
Cautions:
Some sorts cannot handle "zero records sorted" very gracefully.
You should always exit this routine by coding GO TO BA150-RELEASE, or falling thru to it.
The sort record has not been built yet. You must interrogate the data in DB-DATA-AREA since it has not yet been MOVE'd to the sort record.
If you feel the need to do I/O using the MAGEC I/O module (MAGDBMS), be sure to save and restore DB-REQUEST-AREA. It would usually be much better to do the I/O's in %JOIN, rather than here.
Batch Insertion Point %SUBRTNM
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- near physical end of program
Description:
This insertion point is provided so that you can insert entire routines which you can PERFORM from elsewhere. It is neither in the input section nor the output section of the sort, therefore, routines added here can be performed from either or both.
Suggested Uses:
You can insert virtually any type of routine here. There is no limit as to size or content.
Cautions:
Be aware of Cobol rules for using RELEASE and RETURN verbs from routines in, or PERFORMED from, the input/output procedures of a sort.
You should not use STOP RUN to terminate the program, use GOBACK or GO TO ZZ999-GOBACK.
To prevent errors resulting from accidentally falling through to an implied STOP RUN, the ZZ999-GOBACK routine is generated behind the %SUBRTNM insertion point.
Batch Insertion Point %SVPREV
Found in Model:
MODELRPT
Location:
PROCEDURE DIVISION -- CA120-SAVE-KEYS
Description:
This insertion point is immediately before the generated logic to MOVE the key (sort) fields from the sorted record to the hold area which is used to compare against for controlling report breaks.
Suggested Uses:
You can alter what will be MOVE'd in order to force or prevent a control break. If you have added some of your own fields and wish to save them for later comparison, you can do that here.
You can cause certain report breaks to be suppressed by altering what is to be MOVE'd to the hold area, resulting in consolidations (i.e. Departments 0101, 0102, 0103 consolidated as Dept. 0100).
Cautions:
Report break and control logic is complex -- you should study it thoroughly before attempting to fool it by altering key values.
To exit this routine you must GO TO CA130-ADD-TOTALS, or just fall thru to that paragraph.