This guide is written primarily for use by those persons who need an in depth understanding of the programs generated by MAGEC. Copies of this guide should be distributed to:
This guide is to be used as a reference book. You will usually use this chapter in conjunction with one of the other chapters, such as:
This book contains a complete example of an online Cobol program generated using MAGEC's MMPCREAT process. The sample MMP (MMP stands for MAGEC Message Processor) was produced without any Customization. To produce this MMP the Developer did the following things:
In most cases when you are developing new applications like this the first two steps above will already have been done, possibly by the Database Administrator.
You can review the specifications for Mask 600 and for the two Data Classes to see all of the input used to create this MMP. The keys to both files are the Employee number (9 digits). This MMP is the one generated as the first tutorial project in the "Application Developer" tutorial.
Feel free to experiment with the VAC . . . Functions since they are there for you to "play" with.
If you would like to see all the specifications used to create this sample application you may see them online. Enter:
To see the database definitions and Element copybook enter:
You could do similar commands to the above ones for the SIF Data Class, if you wished.
The example MMP will process nine Functions to provide file update, inquiry, browse, and search as well as data entry to the VAC file. It will access the SIF file read-only, since it merely wishes to join it in order to get the employee's name for display on the screen. Through Customization the Developer might add any number of additional Functions, modify any of the "standard set of nine" Functions, or even delete some of them. This book will concentrate on how the standard, un-customized MMP's work. In the analysis of the generated Cobol code we will see, however, the pre-determined Customization "insertion points" and we will give a brief explanation of each of them as we go.
The standard nine Functions are named using six-character Function Codes. The standard prefix (first three characters) of the Function Codes is the primary Data Class Name, in this example: VAC. The Function Codes for this example depict the standard suffixes, they are:
Most of these Functions are two-phase Functions, that means that the Operator must do at least two transmissions in order to complete a given operation. For instance; in order to change a record the Operator must:
The two phases described above for the "CHG Function" are called:
The generated MMP contains a one-byte indicator named MMP-NEW-TRANSACTION which is set near the beginning of processing for all of the standard Functions to indicate whether it is in New Transaction Mode or in Continuation Mode. The status of this indicator, along with the Function Code, controls all the logic of the MMP thereafter.
The determination of whether the MMP is in New Transaction Mode or Continuation Mode is made based upon comparisons between the Function Code and Key Value which is sent from the Operator to the MMP versus the Function Code and Key Value which was last sent from the MMP to the Operator, to see whether they have been changed by him/her.
These comparisons are made between:
NOTE:
The MMP includes a standard routine for Normalizing the Operator's Key entry. That means that the Operator may enter the Key Value into the SKEY field on the top line of the screen in an abbreviated format and the MMP will transform it into the "Normalized" format necessary for accessing the file(s). File keys can be made up of up to five component fields which may be alphanumeric, numeric, packed, binary, and any combinations.
For instance, the Operator might enter a command of:
The Normalize Key routine in the MMP accepts the Operator's input and produces the Normalized Key value from it. It also does editing to verify that numeric data is in fact numeric and that the Operator did not enter too few or too many characters or digits. The Normalize Key routine is controlled by parameters from the KYF file.
The nine standard Functions are divided into two categories:
The MMP contains two separate "Mainlines" for the two categories of Functions. It determines, at the very top of its logic, which type is being done and goes to the appropriate Mainline for it. Within the Mainline it determines which of the Functions is being done and whether it is in New Transaction Mode or Continuation Mode. Next we will describe briefly the general processing logic of each of the various combinations of Function and Mode.
There is no Continuation Mode for a SEE Function; however, since the New Transaction Mode for a SEE Function is identical to the New Transaction Mode for CHG and DEL, the SEE Function can serve as the first phase for them. If the Operator changes the suffix of the Function Code from SEE to CHG or DEL then the MMP will go into Continuation Mode for the Change or Delete. This is true only if the Operator does not alter the Key Value. If the Key value is changed then the MMP will go into New Transaction Mode for the Change or Delete Function.
The DUP Function has no New Transaction Mode. The SEE Function serves as the New Transaction Mode for the DUP. If the Operator alters the Function Code suffix from SEE to DUP and also does alter the Key Value then the MMP will go into Continuation Mode for the DUP Function.
The NXT Function has no New Transaction Mode either. The SEE Function also serves as its New Transaction Mode. If the Operator alters the Function Code suffix from SEE to NXT and does not change the key value, the MMP will go into the Continuation Mode for the NXT Function. If the key value is altered, the PRIOR FUNCTION WAS NOT A SEE message will be issued.
There is no New Transaction Mode for a NXT Function. The SEE Function serves as its New Transaction Mode. The NXT Function must be preceeded by a successful SEE (not NOT-FOUND). The Operator must alter the Function Code suffix from SEE to NXT and not alter the key value. The MMP will then go into the Continuation Mode for the NXT Function. Pressing PF8 (page forward) or PF7 (page backward) automatically changes the Function Code suffix to NXT.
There is no New Transaction Mode for the DUP Function, the SEE Function serves as its New Transaction phase. The Operator first must do a SEE Function and must have successfully found an item (not NOT-FOUND). Then the Operator changes the Function Code to the DUP Function by altering the last three characters to "DUP" and also alters the key value to the desired new key to be added. He/She may also alter any displayed data on the screen at the same time. Then He/She presses ENTER, the resulting transaction will be a DUP Function in Continuation mode.
Related Chapters
What This Book Will Tell You
Standard Functions
Functions and Modes
Normalizing Keys
ADD Function, New Transaction
ADD Function, Continuation
CHG Function, New Transaction
CHG Function, Continuation
DEL Function, New Transaction
DEL Function, Continuation
SEE Function, New Transaction
SEE Function, Continuation
NXT Function, New Transaction
NXT Function, Continuation
DUP Function, New Transaction
DUP Function, Continuation
LOC Function, New Transaction
LOC Function, Continuation
SCN Function, New Transaction
SCN Function, Continuation
FND Function, New Transaction
FND Function, Continuation
Operating Environment
ID DIVISION. |
The Identification Division of the generated MMP is largely remarks. It gives an audit trail of what parameters were used into the MMPCREAT Job Stream and when the MMP was generated and Compiled. The insertion point %REMARKS is where you may insert your own comments to be generated into the MMP.
ENVIRONMENT DIVISION. |
The Environment Division contains no coding for online MMP's and you may not add any coding of your own since there is no insertion point provided.
DATA DIVISION. |
The Working Storage section is used to contain literal constants only. The MMP never alters the data in Working Storage. Any fields which are used as work areas or as the target fields for MOVE's or COMPUTE's must be in the TWA in the Linkage Section. The exception to this rule is those cases in which the program will MOVE to a field in Working Storage and will then access it without ever exiting (to do an I/O, for example) in between. In a fully reentrant environment the program should assume that Working Storage will be re-initialized when the program receives control back after having exited. If you have trouble understanding this concept, play it safe. Don't MOVE to Working Storage fields.
* * * * * * * * * * * * * * * * * * * * * * * * * * |
The Heading Line is to be used on the Browse screens (LOC, SCN, and FND). It contains the Locate Heading literal provided by the Developer using the SCDLST, SCDCHG Functions online. If the Developer did not give any Locate Headings then MMPCREAT would have generated its own from the Cobol data names of the fields being displayed (with the standard Element-Name prefix stripped off).
The Key Editing Parms were generated from the definition for the key (VACK1) on the KYF file. They control the logic and processing of the Normalize-Key routines which edit and reformat the entered key into proper format to read the file with.
01 WS-SHORT-LIST-PAGE-MSG |
The "Short List" facility of MAGEC is a feature which enhances the power of the browses and queries. Whenever your operator does a LOC, SCN, or FND function the program saves the list of up-to sixteen (16) record id's (keys). If the operator cursor-selects one of the items from the screen display he will be transferred to the SEE or CHG function for that item. S/he can then press PF24 to request a pop-up window listing the saved id's and cursor-select another one of them, and so forth. This saves the operator from having to re-do the query in order to update or see several items which were found to meet the selection criteria. The work areas shown above are used by the pop-up window function which displays the short list.
01 CONSTANT-STORAGE. |
The Sequence Messages above were generated from the KYF description for the key(s). They are displayed at the bottom of the Browse screens to tell the Operator what sequence the data is being displayed in. You can define up to nine (9) keys for a Data Class and have MMPCREAT handle them automatically as above. The VAC Data Class has only one key defined.
**************************************************************** |
The above is an expansion of the Member MAGEC017 which was included into the MMP. It contains all the messages which the MMP might move to the SCOMPL area (on the top line of the screen) and also some literals for some of the Error Numbers which might be used.
03 SCAN-LIMIT PIC S9(9) COMP SYNC VALUE +1000. |
The Scan Limit is the maximum number of records which the MMP will read while searching for a Selection Mask or Search Argument in the SCN and FND Functions. If the MMP reads this many records without finding enough "hits" to fill the screen (NUMBER-OF-RECORDS) then it will exit and display what it has found so far. If the Operator hits ENTER again it will resume from where it left off, etc. The purpose for the Scan Limit is to prevent a transaction from "hogging" the system's resources to process one user's request.
WS-SEE-FUNCT is the Function Code that this MMP will transfer to when the Operator is using a Browse Function and Cursor-Selects a line of display and presses ENTER.
WS-CHG-FUNCT is the Function it will transfer to if the Operator Cursor-Selects and presses PF4 from a Browse screen.
**************************************************************** |
The Member MAGEC003 is -MAGECINC'd into the MMP to provide mnemonic names for all the 3270 Attribute codes in case you want to alter the attribute for a screen field in your Customization. The MMP uses these to initialize all the Attributes at the beginning of processing also.
The table includes the one-byte Attribute codes followed by their six-character "names". The names are used in various MAGEC Development Functions, such as MSKDEF. You will likely never have a need to access the six-character names in this table, you will probably use only the one-byte codes. They have data-names that identify them as to which six-character name they represent.
**************************************************************** |
The MAGEC004 Member defines all the MAGECIO Commands. Remember that some of these are only valid for certain Access Methods. For example, REDPR is not supported for ISAM. Refer to the chapter titled "Database Administration" for more details.
01 LOWER-CASE. |
The above literals define the numbers and upper and lowercase alphabets for reference in various places throughout the program. Also above, the print lines used as report separators when the Operator presses the Hardcopy key (PF13 or Shift-F3).
01 CUSTOM-ALGORITHM-LITERALS. |
The above area is provided so that you may insert some literals and constants of you own for your Customization. The %LOCLITS insertion point should be considered obsolete. It is still supported for compatibility with older releases of MAGEC in which you had to generate two MMP's to do all nine Functions, a Maintenence MMP and a Locate MMP. You should use %LITERAL.
LINKAGE SECTION. |
The example we are using was generated for CICS 1.7 (or later) using the '74 Cobol standard. If your environment uses the '85 Cobol compiler (VS COBOL II) this area would look somewhat different. Above is the required BLL-CELLS entry in the Linkage Section for Command Level Cobol. If you are using another TP Monitor (WESTI or Datacom DC) then your MMP will look slightly different at this point. That should not concern you though, these areas are referenced only in the "addressibility" code which is automatically generated into the MMP at the start of the Procedure Division and you should never have to modify it.
The source listing we are examining is what is produced out of the MMPCRE utility and then passed to the DFHECP1$ CICS Command Level Translator program. The output from that would go into the standard Cobol Compiler. The CICS Translator would insert a considerable amount of additional source code into this program, that additional code defines areas which you may reference if you wish but which you never need to reference when using MAGEC. You may ignore them also.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * |
The MAGEC TWA (Task Work Area) is 16K in size (16,384 Bytes) for all MMP's. It has a standard format for approximately the first 6K; the copybook TWADSC-C defines it. MMPCREAT adds the definitions for your Element copybook(s) immediately behind the standard 6K portion and you may add additional definitions for work areas or additional Elements beyond that.
MAGEC saves the TWA at the time a task ends and then restores it when the next task from the same terminal begins; thus the TWA may be used to pass data from transaction to transaction for a given terminal. This is important since the MMP must know what happened last at this terminal in order to set the MMP-NEW-TRANSACTION indicator. You will also find uses for this feature often in your development.
TWA-FILE-KEY identifies this Terminal and User-View. You may interrogate this area but must not MOVE TO it.
TWA-SIGN-IN contains the Security Authorizations for this Operator at this Terminal. The 50 TWA-APPLICATIONS codes contain the Authorization Levels corresponding to the 50 Logical Applications. You may interrogate this area but MUST NOT alter it or your task will be aborted and the Operator Logged Off automatically. TWA-TIME-OUT is the number of minutes which may elapse between transactions before the Operator will be automatically Logged Off. Again look, but don't touch!
03 TWA-TSKLST-MSK-NO PIC X(4). |
TWA-TSKLST-MSK-NO is used by the MAGEC Development Functions to allow them to return you to the TSKLST for the appropriate Mask# when you press PF12. It is unlikely that you will find much use for this field of the TWA. The FILLER is reserved for MAGEC systems programs.
TWA-GROUP-ID is the 10-character identifier which associates this Operator with some arbitrary group, i.e. applications programmer, or system programmer, or contract person, etc.
TWA-BROWSE-DIRECTION may be set by your MMP to tell MAGECIO to read forward or backward on the REDNX command. TWA-MSG-FOR-YOU is the indicator that the Operator needs to use the MSGSEE Function to read the "Broadcast Message", MSGSEE resets this to N.
TWA-OPER-LOC is the Location Authorization code for this Operator. It is set when he/she Logs on. Leave it alone. The TWA-SESSION-OPTION controls the meanings of the CLEAR key (Esc, on a PC) and PA1 (Ctrl-F1, on a PC) key for this Operator. The valid codes are A thru E, refer to "Session Option" in the "Security" chapter. You may alter this field if you wish, it is normally only set by the OPTION Function or when the Operator Logs On.
The TWA-LAP field indicates the Logical Application of the Function Code being done at this time. If used as a subscript for the arrayed field, TWA-APPLICATIONS, it can tell you the Authorization Level of this Operator/Terminal in that Logical Application, i.e.:
You might want to do some of your own Custom Security checking in addition to the standard MAGEC Security system's. You can also use the Operator #, TWA-EMP-NO, (see prior page) to see who is Logged On.
TWA-MODE tells you whether you are in a test or production UserView (TS01-TS08 or PR01-PR08). TWA-COLOR-SW, TWA-NBR-ROWS, and TWA-NBR-COLS indicate the terminal options for MAGEC Extended 3270 support. TWA-ELAPSED-SECONDS tells the number of seconds between this transaction and the prior one for Automatic Time-Out; you may interrogate it.
03 TWA-IPL-DATE-CC. |
The time and date are available for you to interrogate, don't alter them. Use these instead of using CURRENT-DATE or TIME-OF-DAY because it is more efficient and some versions of CICS or your Cobol compiler don't allow you to use those Cobol features.
03 TWA-MSK-AREA. |
The first 10 bytes of TWA-MSK-AREA are the Mask Header. It contains the Mask ID for the MAGEC 3270 Screen Management Mask you are now using (an MMP may use multiple Masks) and data fields to communicate to and from MAGEC Screen Management.
TWA-MSK-ID and TWA-MSK-TEST-PROD are the Mask identity, never alter them.
TWA-MSK-CUR-AD-IN contains the relative Cursor position when the Operator pressed the transmit key. It is a numeric value starting at 0000 (Row 1, Column 1) and incrementing to 1919 (Row 24, Column 80). If the Cursor was at Row 2, Column 1 then it would contain 0080. You may interrogate this field.
TWA-MSK-CUR-AD-OT is a similar field which is used by the MMP to tell MAGEC where it wants the Cursor to be placed when the message is sent back to the terminal. To set the Cursor to Row 1, Column 10 you would move 0009 to this field. To set the Cursor onto a given screen field (named SFIELD) you would:
TWA-MSK-WRT-CMD may be used to tell MAGEC to either Erase the screen and then send the message, or to just send the message. It is automatically set to Erase-Write (E) whenever the MMP requests a new Mask # since the screen format will change. It is automatically set to (F) after the first time that Mask was sent since the screen is already formatted correctly. MAGEC will suppress transmitting the screen headings and literals (protected, unreferenced fields) when this is not E in order to reduce transmission overhead. Regardless what the value of this field MAGEC will compress repeated characters in the message. It is not likely that you will ever have to alter this code in your Customization but you may.
TWA-MSK-AID tells you which key the Operator hit. You will find much use for this, it enables you to use any PF key available on your terminals; remember though, MAGEC intercepts the CLEAR, PF15, PF9, PA1, and PA2 keys and you will never see them in your MMP's.
05 TWA-MSK-DETAIL PIC X(3460).
|
TWA-MSK-DETAIL contains the actual screen format Mask. It includes all the screen fields, Attribute codes, positions, and 3270 Order codes. This area is redefined by the Mask Copybooks which are included into the MMP below.
TWA-MSK-EDIT-WORDS is the area in which the Automatic Editing codes are kept for the Mask currently being pocessed. It also is redefined in the Mask Copybooks. It includes the numeric values for data entered by the Operator, if the fields are either Numeric or Date Edit Types. It has an Error Flag for every field which is edited by the Automatic Edit.
03 FILLER REDEFINES TWA-MSK-EDIT-WORDS. |
TWA-LINE-TYPE indicates the type of connection this terminal uses. You may interrogate this. You might want some extra Custom security on Dial-Up terminals, etc. TWA-BIG-INDICATOR indicates whether this MMP uses a "small" or "large" amount of the TWA space. Small means 8K or less, Large means more than 8K. MAGEC will save and restore either 8K or 12K of the TWA depending on how much is needed. This field is set by the MMP in the standard exit logic which is generated into it. You may interrogate it (if you can think of a reason to).
TWA-REG-SAVE-AREA and TWA-IOMOD-WORK-AREA are used by MAGEC and should be left alone by you. Same is true for TWA-PARM-LIST except that the field TWA-DB-AREA-A is used by you to tell MAGECIO where to Read into or Write from. You use the MAGECSET subroutine to do that. Refer to the MAGEC "Database Administration" chapter.
TWA-TP-REQUEST is used by the MMP to call for a Mask to be initialized by MAGECIO. MAGECIO reads the Mask Initialization record from the MSK file when the "MSK" command is set here. The Mask record is read into the TWA-MSK-AREA above. TWA-PROGRAM is used to indicate the program name currently being executed, "MMPnnn".
TWA-SUB-MMP is used to indicate the program name for "subroutine" calls to the Monitor (CICS, WESTI, etc.). The most common such subroutine call is for the I/O module, done in AA840-CALL-MAGEC-IO thru AA899-EXIT.
TWA-NONTP-REQUEST redefines TWA-SUB-MMP, it is used for passing a command to the MAGEC Control Program, such as the FTH-FUNCT command to tell MAGEC to "fetch" another Function when this MMP exits instead of just sending the message to the terminal and terminating the task. In a WESTI environment the "RELEASE" command may be set here to tell MAGEC to release all resources upon terminating this task, MAGEC will do a "SignOff Leave" after sending the message. The "TRANSFER" command allows you to transfer to a non-MAGEC Program or TranID.
03 TWA-LAST-FUNCT. |
The TWA-LAST-FUNCT area is where the MMP saves the Function Code that it is sending to the terminal just before it exits to send the message. On entry it compares this to the Function Code sent back from the terminal to see if the Operator has changed it. In TWA-LAST-KEY it saves the SKEY (key value) field before exiting. It also compares this to the key value returned from the Operator to see if it was changed.
TWA-DB-REQ-SAV is an area where the MMP saves the MAGECIO Request Area. TWA-ELT00 is where MAGECIO places the Element Name (xxx00) of the Audit Stamp Element if your request was for access to a Data Class with Audit Stamping specified.
03 TWA-ELT-LIST. |
You may want to refer to the MAGEC "Database Administration" chapter for more information regarding the use of the MAGEC I/O module. These areas are discussed there.
TWA-ELT-LIST is where the MMP (and your Customization) sets the Element Names of the Elements it wants to read or write. Since the list is terminated by an Element Name of spaces you may read or write up to 15 Elements in a single request, the 16th being reserved for the dummy "stopper" of spaces. The TWA-ELT-SECURITY fields should be left blank (space).
TWA-ERR-CODES is where the MMP, or MAGEC Automatic Editing, sets the list of up to six (6) Error numbers to be displayed to the Operator. These are normally set in the CA100-LOAD-ERR-CODE-TBL routine which is PERFORMed by your Custom Editing when errors are detected in the Operator's entries.
TWA-KEY-VALUE is where the MMP sets the actual file key to be used to read the file. MAGECIO expects it to be here when it is called.
TWA-DB-REQUEST is the area in which the MMP "builds" its request to be passed to MAGECIO. Some areas within it are used by MAGECIO or the Access Method software to save information between requests. You should use this area as described in the "Database Administration" chapter.
|
TWA-IO-REC is a 36-byte area used to hold the Audit Stamp data if the Data Class accessed is specified for Audit Stamping. The copybook ELT00-C is automatically included into it to define the Audit Stamp. You may interrogate the Audit Stamp but are not allowed to modify it. You are also not allowed to update the Audit Stamp Element of any Data Class, MAGECIO handles all maintenance of Audit Stamps.
TWA-LONG-KEY is an obsolete field which was used to hold keys longer than 36 bytes in previous versions of MAGEC. TWA-KEY-VALUE now supports keys up to 256 bytes long.
TWA-DB-DATA is the area in which the MMPCREAT process inserts the copybook "includes" for your Elements specified in the SHD definition and in the Automatic Logical Join process. The size of this area depends on the sizes of the Elements defined here.
Next you will see the VAC01 Element definition expanded in TWA-DB-DATA and the insertion point defined for you to add your own additional definitions or -MAGECINC's.
* * * THIS COPYBOOK GENERATED BY "DITGEN" |
The %DATADEF insertion point allows you to add any of your own additional data definitions behind the ones automatically generated. The most common way to insert additional data definitions is simply to put -MAGECINC statements in %DATADEF to include more copybooks from the MAGEC Library.
The automatic screen painter and automatic logical join facilities generate the first page of %DATADEF with whatever -MAGECINC statements are necessary for them. They fill the remainder of that first page with comments telling you not to modify it since that page will be re-generated if you re-do the automatic process. You can add subsequent pages as you desire.
It is permissible for you to insert a Cobol 03 level into %DATADEF so that your additional data definitions are not actually within the TWA-DB-DATA area. One reason for doing this is because the standard code in the generated MMP will MOVE SPACES TO TWA-DB-DATA to initialize the area before building the Elements to be Added on an ADD Function. You may not want your data definitions initialized. For example:
This area is just behind the Element data definition area and they are used to hold data which will be passed from transaction to transaction. These areas are not initialized by the MMP like the VARIABLE-STORAGE areas below are.
****** VS-MARKER IS TO DETECT CLOBBERING OF TWA SAVED DATA |
VS-MARKER is set to the time (HHMMSS) before any I/O is done and then is compared after the I/O is complete to see if it has been wiped out by reading data that is too large for the area it was read into. This can happen when you have an incorrect copybook for an Element.
TWA-SAVE-MST-KEYS-AREA is used by Browse Functions. They save the Master (Primary) key values for the records listed on the screen . If the Operator Cursor Selects one to SEE or CHG it the MMP finds the key value in this saved area.
TWA-NR-LINES-SENT is set by the Browses to indicate how many lines of data were sent to the screen. TWA-JERK-CTR is used to count the number of times the Operator continues to tap the ENTER key after reaching end-of-data, at the count of three he/she will get a "nastygram".
CUMULATIVE-SCAN-CTR, CUMULTIVE-DSPLY-CTR, and PAGE-CTR are used by the Browses to build the "page number" line at the bottom of the Browse displays and to check whether the SCAN-LIMIT has been reached.
SAVE-AUDIT-STAMP is used to save the Audit Stamp when a record is read so that the MMP can compare it to the Audit Stamp when the record is read-for-update to see if it has been updated by another task.
STD-CUR-AD-OT is the "default" Cursor position to be used if the MMP does not otherwise set it. It is set when the Mask is initialized to position to the first enterable field on the screen.
There are several work fields here which are used by the pop-up window facility. You can control the width, color, and position of the pop-up window by setting values into them.
The D-LIMITER is the character used to separate component fields within a key value when it is entered into the SKEY screen field. It defaults to a slash (/) but can be set to another value in %PREINIT.
**************************************************************** |
The VARIABLE-STORAGE area is where all program "variables" should be placed. This area is used instead of the WORKING-STORAGE for work fields which are not to be passed from transaction to transaction. It is initialized at the start of the MMP processing by moving LOW-VALUES to it, any fields within it which are to be initialized to some other value must be initialized in the BA100-INIT-STORAGE routine - an insertion point is provided for such initializations.
From VARIABLE-STORAGE on down, MAGEC does not save and restore the TWA. When the MMP is entered this area has random contents, often described better as "garbage", that is why the BA100 routine moves the LOW-VALUES to it immediately, then initializes other fields within it.
KEY-NAME is the area where the Browse Functions build the 5-char. standard key name to use in the MAGECIO Request. KEY-PARM-X is a work area used by the Normalize Key routines in editing the Operators key value entry.
NUMBER-OF-RECORDS is set in the BA100 routine to a default of 16 to control the number of lines of data which can be displayed for browses, you can set it differently if you wish.
PROCESS-INDICATOR is checked in the CA700 routine to determine if a given record is to be listed in the Browse screens or not. It is used in the standard logic generated for SCN and FND Functions and there is an insertion point provided for you to code selection logic and set this indicator if you wish. You can process, bypass, or force end of list on any given record.
TEST-FUNCT is where the MMP saves the Function Code from the screen and where it checks to see what type of Function is to be done. It is referenced throughout the MMP, if you alter it you had better review the complete logic of the MMP to understand the implications.
The insertion point %FUNCT is provided to permit you to override defaults generated for defining the valid Functions for this MMP. In this example you see that the default values are taken. You could code a Custom Algorithm to be used instead.
05 TEST-KEY. |
The above areas are all used in the Editing and Normalization of the key value. The "raw" input key value is placed into TEST-KEY and the Normalize Key routine places the formatted and edited results into NORMALIZED-KEY where the MMP gets it to move to TWA-KEY-VALUE to read the file.
The FILE-KEY area is generated with proper Cobol PICtures to define the component key fields. You might sometimes want to reference these component fields in your Customization logic. Do not alter the area named NORMALIZED-KEY because it is used later in the MMP logic to move to the key portion of the record on updates.
05 WS-ITEM-KEY PIC X(64). |
Above are miscellaneous subscripts and work areas used in the standard logic for Normalizing the key, for supporting the SCN and FND Functions, and for other utilitarian routines throughout the MMP. The MMP-NEW-TRANSACTION indicator and work fields for the Pattern editing logic are also here.
*************************************************** |
The above WS-ITEM area was generated to display the fields which were selected to appear on the Browse (Locate) screen. The names generated into this area were made up by MMPCREAT by adding the WS- prefix to the names given for the screen fields when the Developer painted the screen using MSKDEF.
The fields which appear in the WS-ITEM detail "print line" are the ones which will be shown on the LOC, SCN, and FND functions. They are designated by a non-zero "locate position". The locate position is the last specification at the bottom right corner of the window when you select a screen field (in MSKDEF) by pointing to it with the cursor and pressing PF18. It appears with the descriptor: LOC.
05 MSK-DOT-LINE. |
Above are more work fields used in the SCN and FND Functions.
05 LOC-ACCUMS. |
The above work fields are for the browses when they are routed to hardcopy as a result of the Operator's having pressed PF13 (or Shift-F3). They are accumulators and total lines. There are also work fields used by the pop-up Short-List feature.
Also, here is another insertion point for you. The %VARSTOR insertion point is provided so that you can add your own work fields to VARIABLE-STORAGE. The %LOCVARS is supported only for compatibility with older releases, you should use %VARSTOR. Your work fields should begin with a Cobol 05 level in order to become part of the 03 VARIABLE-STORAGE area. If you code a Cobol 03 level here then your work fields will not be automatically initialized to LOW-VALUES and you will have to be sure to do whatever initialization is necessary in the BA100 routine.
Sometimes you might want to place data definitions for database Elements here and read into them using MAGECIO.
03 BUS-RULE-WORK-AREA. |
The above area is where the Business Rule code for RULWORK is inserted. It is used to define data areas needed by the logic in the Business Rule. In this example the -IFUNIQUE option was used - since the copybook SIF01-C is already included into this program once, the -IFUNIQUE causes this -MAGECINC to be bypassed.
* * * REQUEST AREA FOR SPOOLER |
The above area is used to communicate to the MAGEC TP Spooler. It is used whenever the Operator uses the Hardcopy key (PF13 or Shift-F3), or when your customization desires to spool report data. Refer to the "TP Spooler" chapter for more information.
03 FILLER REDEFINES SPOOL-REQUEST-AREA. |
The above fields are used to support the VERZUN function which allows you to determine the status and version numbers and statistics for your application. To do that for this application you would enter the online command:
02 MSK652 REDEFINES TWA-STRT. |
All the standard Browse Functions use the same Mask, MSK652. Above is the portion of the MSK652 copybook which actually redefines TWA-MSK-DETAIL. It has all the data fields and control fields for the LOC, SCN, and FND Functions screens. Notice that, just like in all other Masks, the standard screen fields SERRMSG, SFUNCT, SKEY, and SCOMPL are defined at the beginning. They always occupy the same place on the screen and the same place in the TWA. The rest of the data fields are organized in order of their data names, not in the order they occupy on the screen.
02 MSK652-PARMS REDEFINES TWA-STRT. |
Here we see the portion of the MSK652 copybook which redefines the TWA-EDIT-WORDS area of the TWA.
NOTE:
***** CURRENT VERSION NUMBER IS 04 04 10 03 0
|
The above description of MSK6PU is used by the pop-up window feature. This is the common pop-up mask which you can also use for your own custom pop-up windows if you wish. The default logic generates a pop-up Short-List (see the AP100 paragraph).
***** CURRENT VERSION NUMBER IS 09 06 22 00 1 |
The preceeding was the first half of the Copybook of the Mask that the Developer painted using the automatic Screen Painter and MSKDEF. Notice the Cobol edit patterns and Date-field definitions generated. Notice the fields generated with the screen field data name plus a suffix of -POSN, these contain the screen position of the field. If you wanted the Cursor to be placed on the field named SEARNED you would code:
Notice the fields generated with the suffix A. These are the 3270 Attribute bytes. If you wanted to change the Attribute of SEARNED to be Protected (etc.) you would code:
To move data into the screen field SEARNED you might code:
The following code is the second half of the Mask Copybook. It redefines TWA-MSK-EDIT-WORDS.
02 MSK600-PARMS REDEFINES TWA-STRT. |
This (preceding) part of the MSK600 Copy Book redefines the TWA-MSK-EDIT-WORDS area of the TWA. Notice that the fields having data names like those of the screen fields but with a suffix of E added are the Error Indicators for the respective screen fields. When the Automatic Editing detects an error in a screen field it sets the Error Indicator for that field to "E". You should do the same in your Customization Editing. MAGEC will automatically Highlight the Attributes for the fields having an E in their Error Indicators and will position the Cursor to the first Error field on the screen.
Notice also the fields named with a -N suffix. These will have the numeric value of the data entered on the screen (if it was a numeric Edit Type field) set by the Automatic Editing. It is what we use to update the database fields with since you could not very well move the display format data to the record. Notice also the special JULIAN-DATE and DAY-OF-WEEK fields generated for all dates. These also are set by Automatic Editing before the MMP is entered. The DAY-OF-WEEK codes are 1 = Sunday, 2 = Monday, etc., 7 = Saturday.
* * * DEFAULT ALGORITHM %USRAREA STARTS HERE |
The above area is provided with an insertion point (%USRAREA) to allow you to add Linkage section items as needed. The most usual reason to add code here is to insert DBMS areas (i.e. IMS PCB's) which must be Cobol level 01 items in the Linkage section. If you add them here, you must remember to load their corresponding BLL-CELLS (USER-BLL-1 thru USER-BLL-9) in order to have addressibility to them. Failure to do so will result in Storage Violations!
PROCEDURE DIVISION USING DFHEIBLK DFHCOMMAREA. |
The beginning of the PROCEDURE DIVISION will look slightly different depending on which TP Monitor and Cobol compiler you are using. This example is for CICS. Regardless, the logic here is for the sole purpose of getting "addressibility" to the TWA and, possibly, other Linkage Section areas. If you alter this logic and thereby cause Storage Violations, you will be in grave danger of being lynched by your peers.
The CICS abend handler program name is defined on the MMP header definition screen. It is specified by the developer. If it is left blank, no abend handler program will be used and normal CICS abends (i.e. ASRA's) will result from data exceptions, addressing exceptions, etc.
*************************************************************** |
The AA100 routine tests for the special AID code which indicates that the program was invoked by the VERZUN function, rather than one of its standard application functions (VACSEE, VACLOC, etc.). It then sets the default value into the D-LIMITER field. The D-LIMITER is the character used to separate (delimit) key components. For example, using the default delimiter of slash ( / ), a compound key could be entered as:
where the first component field's value is 123 and the second component field's value is 45. The Normalize Key routine in the MMP would pad the appropriate number of leading zeros to each component in order to build a proper file key. If you alter the D-LIMITER to, say, comma ( , ), then that same key would be entered as:
The %PREINIT insertion point allows you to place code near the very beginning of the MMP's logic. One use for it is to modify the D-LIMITER. Another use is to schedule the PCB (for IMS or DL/1) and load BLL-CELLS.
The PF24 key is used to invoke the pop-up window for the Short-List feature.
Next, the AA100 routine tests whether the incoming Function Code in the SFUNCT screen field is:
and goes to the appropriate Mainline or issues an error message. Note that to issue this message it "fetches" the general-purpose CLEARS Function. You might want to use this technique in your Customization also sometimes. Moving the FTH-FUNCT command to TWA-NONTP-REQUEST and moving a Function Code to SFUNCT before going to AA900-GOBACK is how you can automatically transfer to any other Function. MAGEC will treat it as if the Operator had actually keyed that Function Code into SFUNCT and will do all the same Security checking before transfering control.
**************************************************************** |
The AAL200 routine is the beginning of the Mainline logic for the LOC, SCN, and FND Functions (Browses). It first makes sure that the screen is formatted with the correct Mask (MSK652) for Browses, if needed it will initialize the TWA-MSK-AREA by reading the MSK record. It then sets the MMP-NEW-TRANSACTION indicator depending on whether the Operator has altered the Function or Key on the screen. Refer to Appendix B at the back of this section.
The default logic for the insertion point %PFKEYL supports the standard help key (PF1), the standard copy key (PF16), the standard help index key (PF11), and the standard browse keys (PF8=forward, PF7=backward)
If in Continuation Mode then it checks the Cursor position to see if the Operator has Cursor-Selected an item, if so then it performs the CA500 routine to convert the saved Master Key value for the selected record into the proper screen format with slashes (/) separating the component fields, etc.. It uses the "ATTACH" technique to invoke the designated Function depending on whether the ENTER or PF4 key was hit.
The insertion point provided here named %PFKEYL is you so that you can enter Customization logic to intercept the incoming transaction very early in the processing. One of the primary uses for PFKEYL is to test for the Operator's having used a certain PF key to indicate that he/she wishes to transfer to some other Function. You could also use this point to intercept and modify the Key Value entered before the Normalize Key routine gets to it, perhaps to prefix it with the proper Company number or Department number, etc. so that an Operator can only access records for his/her own Company or Department.
**************************************************************** |
The AAL250 routine checks for users who continue tapping the ENTER key after reaching end-of-data or without entering a key value. Without a key value the Operator is "going nowhere", if he/she transmits three times in a row without entering a key value then the MMP issues a message via the FTH-FUNCT command as above.
AAL300-INITIALIZE. |
The AAL300 routine initializes the screen attributes and parses the SCN Function's Selection Mask line or the FND Function's Search Arguments. It forces the MMP into New Transaction Mode if the Operator hit PF5, this will return the screen's display to the first "page" instead of "paging forward". If in New Transaction Mode it performs the Normalize Key routine to edit and format the entered Key Value in preparation for reading the file. It tests the TWA-BROWSE-DIRECTION indicator to see whether the REDNX command will read forward or backwards and moves an appropriate message into the last line of the screen.
**************************************************************** |
The AAL400 routines are the database I/O routines for the Browses. In here you see the logic to call the MAGECIO I/O module to position to the first record on the file having a key value equal to or greater than that entered by the Operator and then to read the first record and then to read the "next" record(s). The MAGECIO command REDNX will read either forward or backward on the file depending on the setting of the TWA-BROWSE-DIRECTION.
Notice the three insertion points which allow you to provide your own Customization logic instead of the Default logic shown. If your application is using the MAGECIO I/O module (most of them will be) then your Customization logic would likely be very similar to the Default logic, possibly with a few lines of code added. If your application is accessing some file or type of file not supported by MAGECIO then you could code your own "reads" here to completely replace the calls to MAGECIO. You could even be accessing a "database back-end machine".
Notice that the Default logic performs JA100-LOGICAL-JOIN after reading the "primary" record. The JA100 routine is where you can insert the "reads" for as many other files as you like. The "Logical Join" philosophy means that all the data read can be looked upon by the remaining logic of the program as if it were all one large record. We have logically joined many records from many files to construct one larger "logical record" in TWA-DB-DATA. This sample program accesses the SIF file in the JA100 routine.
The AAL440 routine checks the MAGECIO return code and performs the CA700 routine. The CA700 routine builds a display line from the data which was read, for SCN and FND Functions it tests to see if this item meets the selection criteria, then it moves the display line to the screen (if appropriate). AAL440 tests the PROCESS-INDICATOR to see how CA700 has set it and; as appropriate, loops back to read the next record, or falls through to send the screen.
**************************************************************** |
The AAL500 routine saves the Function Code and Key Value in the TWA-LAST-FUNCT and TWA-LAST-KEY fields and exits to MAGEC to send the screen.
**************************************************************** |
This AAM200 routine starts off the Maintenance Functions' Mainline. The %PFKEYM insertion point is for you to allow you to intercept the transaction early. The Default code provides for transfer to the LOC Function if the Operator hits PF4 and for not overlaying the Operator's entry when he/she tries to update in a SEE Function, forgetting to alter the Function Code to ...CHG. You may add code to test for other PF keys here or to intercept the Key Value before Normalize Key gets it.
If the screen is not already formatted into the proper Mask for this MMP's Maintenence Functions then the MSK record is read now to initialize the screen. The MMP-NEW-TRANSACTION indicator is set here depending on whether the Operator changed the Function Code or Key. Refer to Appendix A at the back of this section.
**************************************************************** |
The AAM300 routine does initializations. It performs the BA200 routine to initialize all the screen field Attributes after verifying that the Mask Copy Book is the same version number as the MSK initialization record which was read. This traps the common Developer's error of altering the Mask and forgetting to recompile the MMP to get the new Mask Copy Book included.
The Normalize Key routine is performed from here to convert the Key Value entered by the Operator into proper format for reading the file. Then the AAM300 routine determines whether it is time to do a read-for-update or just a plain read, the type of Function and the Mode are both factors in the determination.
**************************************************************** |
The AAM400 routine does the MAGECIO calls to read the file. Notice the insertion points %REDKY, %RDUKY, and %REDNX which all have Default code which calls MAGECIO. You might provide your own Customization code to replace the Defaults to allow you to access types of files not supported by MAGECIO or to add a little of your own logic before or after calling MAGECIO.
Notice that the %REDKY Default logic saves the Audit Stamp and the RDUKY Default logic checks to see if it has been altered by another task since it was read in %REDKY. If you are familiar with the philosophy of Pseudo Conversational programming then you will see that this solves the classic problem in which one terminal's update could overlay the record just updated by another terminal, undoing its changes. The %RDUKY logic is executed only for CHG Functions and DEL Functions in Continuation Mode. AAM440 checks for bad MAGECIO return codes or for database data overlaying the areas beyond TWA-DB-DATA. For bad return codes an error message is placed in SCOMPL and we exit to send the screen.
**************************************************************** |
If we are in New Transaction Mode then we do not want to continue on down to the updating routines. We perform either the BB100 routine (to fill the screen with Underscores), or the BB200 routine to move the record data to the screen and then we exit to send the screen. The CA800 routine transforms the record's Master Key into proper screen key format (SKEY) with slashes ( / ) separating component fields, etc.
**************************************************************** |
The AAM600 routine performs the appropriate screen edit routine for ADD, CHG, or DEL Functions in Continuation Mode. Remember, nothing else would get this far in the logic after AAM500 above. If errors are found in either of the edits, or if they were found in the Automatic Editing then the FATAL-ERR flag will be set to F. This condition (ERROR-FOUND) will prevent any database updating below.
**************************************************************** |
The AAM700 routines do the file updating calls to MAGECIO. Notice the insertion points %ADDIT, %UPDAT, %DELET, and %RELES which are shown with their Default logic. You could provide Customization logic here to be done in addition to or instead of the Default logic.
The BB600 routine is performed to move the screen fields to the record fields. Within the BB600 routine is the Business Rule processing for the Element, VAC01. If it sets the ERROR-FOUND condition, the update or add will not be done - an error message will be issued instead.
**************************************************************** |
The AAM750 routines check the return code from MAGECIO and handle all possible conditions. Notice the insertion points %UPDERR, %GOODADD, %GOODCHG, and %GOODDEL provided for you. The Default logic is shown, it usually just moves a message into SCOMPL and exits to send the screen. For an ADD Function, on successful completion, it alters the Function Code to the SEE Function so the the Operator cdfoan press ENTER to display the record just added and then use the NXT Function if desired.
You might find many reasons to want to add Customization logic into any of these insertion points. One common use is to FTH-FUNCT to another Function after a successful ADD, etc.
AAP100-POP-UP-SHORT-LIST.
|
The above logic produces the Short List pop-up window. The Short List is a list of record ID's which is saved when the operator does a LOC, SCN, or FND function. The Short List contains the ID's of the items which were displayed on the screen. In the case of a SCN or FND function that means that the Short List is a list of those items which matched the search criteria.
The logic in the AAP100 routine is invoked when the operator presses PF24 while in a MAINT function. That means that he/she could have done a query and then cursor-selected an item and been transferred to the maintenance screen for that item. Then he/she can press PF24 and a pop-up window will display the Short List. He/She can cursor-select from the Short List pop-up display and be transferred to the maintenance display for the selected item, and so forth.
If you desired to add your own pop-up displays to a program you might study this routine and model yours after it. All pop-up displays can use the same screen mask (MSK6PU). You can set the position and width of the pop-up window and you can set the color of it.
You can control the color, position, and width of the pop-up window using the data fields: WINDOW-COLOR, TOP-LEFT-POSN, and WINDOW-WIDTH.
The AA760-ATTACH routine is branched to by the program logic when the program is to Attach down to the next level, as in going from a LOC function to a MAINT function.
The AA770-DETACH routine is branched to by the program logic when the program is to Detach back up to the next level, such as going from a MAINT function back to a LOC function.
The AA780 routine is used to exit back to the low-level menu from this application. It is normally branched to when the Operator presses the PF3 key.
AA800-SEND-SCREEN. |
The AA800 and AA900 routines are the exit routines which are used to terminate processing for this MMP and return to the MAGEC Control Program to send the message or FTH-FUNCT another Function, etc.
The actual coding in this area will vary slightly from one TP Monitor to another, this example is for CICS. The differences are of no concern to you, though. When you perform AA840-CALL-MAGEC-IO or go to AA900-GOBACK you will get the same results regardless what environment you are operating in.
**************************************************************** |
This is the initialization routine which is always performed at the start of processing. Notice the insertion points %LOCINIT and %INIT. If you want to add some additional logic to the initialization for the Browse Functions you would use %LOCINIT, for the Maintenance Functions use %INIT. In this sample MMP there was no Customization for either.
*********************************************************************** |
The BA200 routine sets all the screen field Atrributes to their initial values. The initial values are the ones the Developer specified when he/she painted the Mask (via Automatic Screen Painting or MSKDEF). This routine is performed for the Browse as well as the Maintenance Functions but the insertion point named %INITATB only allows you to add Customization logic for the Maintenance Functions.
**************************************************************** |
The Normalize Key routines are performed from the Mainlines at the appropriate times. There are two insertion points, %NKLOC and %NORMKEY provided. If you wished to write your own Normalize Key logic for the Browse Functions then you could use %NKLOC to replace the entire routine. It is not likely that you will often want to do that. The %NORMKEY insertion point is positioned immediately before the Maintenance Normalize Key routine moves the key value from FILE-KEY to NORMALIZED-KEY and then exits.
FILE-KEY contains the completely formatted key, ready to use for reading the file. You might want to insert some of your own additional editing here to be sure the key value is within certain ranges, etc.. If there were any errors found in the key value entered then your Customization in %NORMKEY will not be executed since the routine will exit immediately with the error flag set. Remember, you have an opportunity to intercept the key value before it gets to the Normalize Key routine at the %PFKEYM and %PFKEYL insertion points.
**************************************************************** |
The BA500 routine is performed from the browse and maintenance mainlines to test whether the file is available and open. The FSTAT command tests File Status.
**************************************************************** |
The BB100 routine initializes all the Unprotected (Enterable) fields on the screen to Underscores. It is performed in the New Transaction phase of the ADD Function and when the MMP gets a NOT-FOUND return code for the key value entered by the Operator.
The %BLNKSCR insertion point is provided so that you might initialize some of your screen fields other than with the default Underscores.
**************************************************************** |
The BB200 routine moves all the database "source" fields from the record to the screen in preparation to be displayed. It is performed in the SEE and NXT Functions and in the New Transaction phase for the CHG and DEL Functions and when a duplicate record is found for the ADD Function. The coding in this routine is generated by the MMPCREAT process from the Developer's specifications in MSKDEF for "Source/Target" fields for the corresponding screen fields. Notice that dates are automatically "rearranged" and do not need to be in the same format (MMDDYY, YYMMDD, etc.) on the file as on the screen. Notice also that numeric fields are moved to the Cobol edit pattern fields having the -ED suffix. Also, notice that the Pattern Edited field is "moved" by performing the CB200 routine to insert the pattern.
The %COMP insertion point allows you to add your own Customization to move data to the screen for display. You can compute values or move literals or variables from the TWA, etc. You can perform the CB200 routine to insert a pattern, if you like. This allows you to dynamically establish the pattern. A handy example of how this might be used is in U.S. and foreign postal (zip) codes. You could set the pattern according to which country the address was in. Notice the Default logic for %COMP. The default code moves the "PF Key" message to the bottom of the screen. If you overrode the default in %PFKEYM you should probably also override this message.
**************************************************************** |
The BB400 routine is performed in the Continuation Mode for DEL Functions only. The insertion point %DELEDIT is here, it allows you to insert any type of logic you desire to validate that it is okay for this record to be deleted. The most common use is to read a subordinate file to see if there are records on it; ie: reading the Invoice file before deleting the Customer Master record.
This is also where the RULDELT logic (deletion rule) is inserted. This logic was stored in the dictionary by the database administrator and is "triggered" just before the specified element is to be deleted. Refer to the "Database Administration" chapter of this manual for more about Business Rules and Deletion Rules.
If you detect a condition which should prevent the deletion then you must set the FATAL-ERR flag to F, just as in all other edits.
**************************************************************** |
The BB500 routine is performed to edit and validate screen data before any update or add to the database. In it you will notice some code has been inserted to edit the Pattern edited employee number and time-of-day fields. You can insert your own edit routines here using the %EDIT insertion point. The %EDIT2 insertion point is also found here. It is for edits which you wish to do only if all prior edits have been passed successfully. That allows you to bypass expensive, I/O intensive validations when errors have already been detected which will prevent the update.
**************************************************************** |
The BB600 routine is performed for ADD and CHG Functions in the Continuation Mode and if no errors were found in either the Custom or the Automatic Editing. It moves the fields from the screen to the record. Notice that it uses the numeric fields with the -N suffix where appropriate and rearranges the dates if they are not in the same format on the file as on the screen. These moves were gnereated from the Developer's specifications in MSKDEF for database "Source/Target" fields for the screen fields.
The %ADDINIT insertion point allows you to override the Default logic for initializing the record for an ADD.
The %CALC insertion point allows you to override the Default which moves NORMALIZED-KEY to the record key field and to add your own calculations or MOVEs to build the record fields.
Notice that the BB680 routine is where the Business Rules are inserted. The one in this example is the Rule associated with the VAC01 Element. It is executed after all MOVE's to the database fields have been completed. It references fields in the database Element copybook, rather than fields in the screen since this code might be inserted into many applications. If it sets the ERROR-FOUND condition (by performing the CA100 routine), the update or add operation will not carry through the database update, it will issue an error message instead.
**************************************************************** |
The BB800 routine is performed when the MMP gets a bad return code trying to read the MSK initialization record. It issues an error message via FTH-FUNCT to the Clear-Screen Function.
**************************************************************** |
The CA100 routine is performed by your Customization Editing logic to set the ERROR-NUMBER into TWA-ERR-CODES and to set the FATAL-ERR flag to F (ERROR-FOUND) indicating a "fatal error".
To use this routine you would code:
**************************************************************** |
The CA200 routine is a dummy EXIT which is used by many other routines to vary subscripts, as:
PERFORM CA200-SERIAL-SEARCH
VARYING SUB FROM ONE BY ONE
UNTIL (SUB GREATER THAN TEN)
OR (WIDGET (SUB) = 'X').
***************************************************************** |
The CA300 routine is performed from the Normalize Key logic and may be used by you in your routines, as well. It does the job of an EXAMINE or INSPECT verb. Since MAGEC programs are transportable to many environments, and since those verbs are not always supported on various versions of the Cobol compiler, we have provided this routine.
**************************************************************** |
The CA400 routine is used just like the CA100 routine above but it sets the FATAL-ERR flag to W instead of F. W indicates a "warning level error" which will not prevent file updating but will issue an error message to the screen in SERRMSG.
**************************************************************** |
The CA500 routine is performed when the Browse Functions are transferring to a SEE or CHG Function because the Operator has Cursor Selected an item. This routine converts the record's Master Key value into the screen format with slashes ( / ) separating component fields.
**************************************************************** |
The CA700 routine is performed by the Browse Functions to build a display line from the record and determine whether it should be shown or not. The moves generated here are to the WS-ITEM area in the TWA which will be moved to a screen line in the Browse Mask (MSK652) if the
PROCESS-INDICATOR contains the value P, see below.
The insertion point %SELECT allows you to insert Customization code to inspect the record before it is processed and to set the PROCESSINDICATOR to control the logic below. You can tell it to process this record (P), bypass it (B), or to simulate that it is at end-of-file (E). If you have files with multiple record types of different format records this insertion point will be invaluable to you, you can bypass the records which are in the wrong format. You might also want to show only records for the Operator's Company or Department.
The other insertion point you have in this routine is %LOCMOV. It allows you to add your own additional MOVE's or COMPUTE's to finish the building of the display line.
For the SCN and FND Functions the checking for whether this item meets the selection criteria is done immediately behind the %LOCMOV insertion point.
* * * DEFAULT ALGORITHM %SKEYBLD STARTS HERE
|
The entire CA800 routine is a Default for the insertion point named %SKEYBLD. Its purpose is to build the key value in screen format from the Master key field in the record. It is performed from the NXT Functions. In most cases you would not want to touch this routine. In the unlikely event that you need to display the key somehow other than it would be built by this routine then you can override the entire CA800 routine with your own.
JA100-LOGICAL-JOIN. |
This is the JA100 routine which is performed from every "read" routine immediately after reading the primary file record. It is where you can code the reads for as many other files as you like to construct a "logical record" for the MMP to process against.
The insertion point named %JOIN is an extremely important one and you will find it very useful. You can not only read other files but also compute values into VARIABLE-STORAGE fields which may be specified as "Source/Target" fields to be displayed on the screen.
Using this insertion point wisely can greatly simplify your MMP's logic and your work. The code shown in this example was generated in the Automatic Logical Join process during the development of this application.
The coding found in the %JOIN insertion point could be placed there in any of several ways. It could be manually coded by the developer as ordinary customization coding, it could be generated via the semi-automated development process which requires some programmer input, or it could be generated using the fully-automated development process which requires no programmer input. Regardless how it got there, it can be altered or added to online via the standard customization processes.
*************************************************** |
Above are two insertion points which are provided so that you can insert as much Customization logic as you like to be performed from anywhere else in the MMP. Here you might insert a routine to do a special edit on, let us say, dates. You might have several date fields on the screen and wish to edit each of them using this subroutine. The code you place here may be PERFORMed as many times as you wish from the edit routine (%EDIT) or anywhere else that is needed. The insertion point named %SUBRTNL is obsolete and supported for compatibility with older versions of MAGEC. You should use %SUBRTNM.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * |
This routine is generated at the physical end of the program. It catches "runaway" logic which might attempt to "fall thru" the end of the program. Falling thru the end will always give bad results. In some environments it will execute the default GOBACK or STOP RUN which the Cobol compiler puts there - that will usually terminate the whole TP Monitor. This "safety net" catches the error before the damage is done.
One way you might create such an error would be to PERFORM a subroutine THRU the EXIT and, within the subroutine, GO around the EXIT. With very little effort you can discover other ways.
The logic in the generated MMP which sets the MMP-NEW-TRANSACTION switch is depicted in the following flowchart.This switch has significant impact on the operation of the program. It indicates either that the program is in NEW-TRANSACTION-MODE or in CONTINUATION-MODE.
Appendix A -- Maintenance Mode Setting
