| ```
** DO THIS:
Press PF3.
```**
The VAPSEE pop-up should disappear, returning to the VACSEE screen "as it was before you pressed PF10. If you altered (cont.)
the city, state, zip code data in the pop-up, the altered values will not show on the VACSEE display until you press (cont.)
ENTER to refresh the screen.
#
Appendix A -- How to Call a SubTask
##
Linking to a Subroutine MMP
Since your MAGEC MMP's are Cobol programs you are able to use the standard facility of your TP Monitor to invoke (cont.)
another program as a subtask. This is known as "linking" to another program in some circles. You can code the "native" (cont.)
command in your Customization coding as:
| ```
**
EXEC CICS LINK
. . . etc.
CALL 'WSTCOBOL' USING SIGNOFF, SOLINK
. . . etc.
```**
and so forth, depending on your TP Monitor.
However, *there is a better way*. Your MMP automatically includes a "service routine" which you can perform to (cont.)
accomplish the same thing a lot easier. Using the built-in service routine also keeps your MMP's portable since MAGEC (cont.)
will generate the appropriate code into it if you upgrade or transport to another TP Monitor.
In order to take advantage of this routine your subprogram must be named according to the MAGEC standard (MMPnnn) on the Load Library (OS) or Core Image Library (DOS).
You can use the routine to invoke a subprogram at any time in the MMP. The TWA data is passed to the subprogram and (cont.)
back to the calling MMP. The two programs can communicate with each other using the TWA. The TWA is not saved, (cont.)
initialized, or restored by MAGEC when you invoke subprograms this way. If your MMP moves a value into a field in the (cont.)
TWA before invoking the subprogram, then the subprogram will "see" the value in that field. If the subprogram alters (cont.)
that value before it returns back to your MMP, then your MMP will "see" the altered value.
To invoke a subprogram, code:
MOVE 'nnn' TO TWA-NONTP-MMP.
**PERFORM AA850-SUB-CALL THRU AA899-EXIT.
where:
'nnn'
= the MMP number of the subprogram.
Control will return to the next sequential instruction after the PERFORM.
#
Appendix B -- How to Fetch Another Function
##
Chaining Screens
Often in your development you will find a need to establish a sequence of screens in your applications. For instance, (cont.)
you might decide that whenever an operator completes the screen function to add a new customer to the Customer file (cont.)
(ie. CUSADD function) the next thing that he/she will probably want to do will be to add an invoice for that customer (cont.)
(ie. IVCADD function). You would probably want the IVCADD screen to "pop up" automatically, ready for data to be keyed (cont.)
into it.
Another example might be a case where you want to give the operator the capability to hit a PF key (or to type (cont.)
something onto the screen) to indicate that he/she wishes to transfer immediately to some predetermined screen (cont.)
function. A menu-type screen would be an example of this.
MAGEC has a built-in facility to accommodate "fetching" to another screen function. To do so, just code:
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
MOVE 'xxxxxx' TO SFUNCT.
GO TO AA900-GOBACK.
where:
'xxxxxx'
= the six-character Function Code you wish to
transfer to.
The entire TWA and all Mask data is passed to the "fetched" MMP intact. You can also move a value into the Screen Key (cont.)
field (SKEY) to be passed to the fetched MMP. It is also permissable for the Function Code specified to be one of the (cont.)
functions handled by this same MMP; for instance VACLOC could legally fetch to VACSEE. Indeed, when you use the (cont.)
cursor-selection feature of VACLOC that is exactly what happens.
There is also a way you can fetch by specifying the MMP number instead of a Function Code. This feature exists solely (cont.)
to facilitate conversions from non-MAGEC applications to MAGEC. We recommend that you use the FTH-FUNCT method whenever (cont.)
possible.
To fetch a specific MMP you would code:
MOVE FTH-CMD TO TWA-NONTP-REQUEST.
MOVE 'mmm' TO TWA-NONTP-MMP.
GO TO AA900-GOBACK.
where
'mmm'
is the MMP number of the program to be fetched. It must be named according to the MAGEC standards for Load Library (OS) or Core Image Library (DOS) members.
You must not GO TO AA900-GOBACK from within a PERFORM'ed routine.
NOTE:
**
(This note applies to BOTH of the above types of fetches.)
When the fetched program completes its processing it does not return back to the MMP which fetched it. The fetched MMP (cont.)
has logically "overlaid" your MMP and when it completes it will return to the MAGEC Control Program (just as your MMP's (cont.)
do). The fetched program may fetch another MMP, which may also fetch another MMP, and so on. Excessive use of this (cont.)
facility could have an adverse effect upon online performance.
#
Appendix C -- Reading a Mask
##
How to Initialize TWA-MSK-AREA
The standard logic generated for your MMP includes all the correct coding to initialize the TWA-MSK-AREA with either (cont.)
the common browse Mask (Mask 652) or the Mask you generated (Mask 600) at the proper times. You will most likely never (cont.)
need to add Custom coding to initialize the Mask area; however, there is a facility for you to do so, in case you ever (cont.)
require it.
You might someday want to develop an MMP which uses more than just the two Masks which are automatically handled in the (cont.)
standard logic. In that case you would have to initialize the area with your other Masks at the proper times. There is (cont.)
no limit as to how many Masks an MMP may use.
To initialize the TWA-MSK-AREA code:
MOVE MSK-CMD TO TWA-TP-REQUEST.
**MOVE 'NNN' TO TWA-TP-TRM.
PERFORM AA800-CALL-MONITOR THRU AA899-EXIT.
IF (GET-MSK-ERR)
PERFORM BB800-MSK-ERR-MSG THRU BB899-EXIT
GO TO AA800-SEND-SCREEN.
The initialization of the Mask area actually involves a read of the Mask's initialization record from the MAGEC MSK (cont.)
file. It is done by the I/O module (MAGECIO). The error status (GET-MSK-ERR) is set by MAGECIO if an error of any sort (cont.)
was encountered in trying to read the record. The BB800 routine contains the RECOMMENDED action to be taken when such (cont.)
an error occurs, you may want to deviate from that -- just BE CAREFUL!
##
Mask Copybook
When a Mask is to be read into your appplication you will almost certainly wish to include the copybook which describes (cont.)
that mask. A standard online MMP already used three Masks by default. They are the maintenance screen mask, the common (cont.)
browse mask, and the pop-up window mask for the Short-List feature. The copybooks for these are automatically included (cont.)
into the MMP.
If you need to include a copybook for another Mask, it should be inserted into the %USRAREA insertion point. Remember, (cont.)
these Mask copybooks all redefine the same area, TWA-MSK-DETAIL, and therefore you must be careful not to reference (cont.)
datanames for fields within one Mask while a different Mask is "active". This is true even with the standard default (cont.)
MMP's which use only the basic three Masks. Since the references to these standard Masks are largely generated by (cont.)
MAGEC, they already abide by this restriction. It is only in your customization where you are likely to cause a (cont.)
problem.
#
Appendix D -- Exit to Logo Screen
##
Fetching the Clear Screen
Sometimes you will have occasion to add Customization coding to cause your MMP to just terminate its processing and (cont.)
pass control to the "Logo screen". The Logo screen is also called the "Clear screen", it is the screen on which either (cont.)
the MAGEC logo or your company's logo is displayed. It also has a message on line 2 of the screen saying: "ENTER (cont.)
FUNCTION CODE".
To fetch the Clear (Logo) screen, code:
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
MOVE CLEAR-FUNCT TO SFUNCT.
GO TO AA900-GOBACK.You must not GO TO AA900-GOBACK from within a PERFORM'ed routine.You can also fetch the Clear screen (cont.)
and specify a message to be shown in the SCOMPL screen field (top line, right half), code:
MOVE MSG-LIT TO TWA-TP-OP.
MOVE message TO TWA-MSK-AREA.
MOVE FTH-FUNCT TO TWA-NONTP-REQUEST.
MOVE CLEAR-FUNCT TO SFUNCT.
GO TO AA900-GOBACK.
where:
'message'
= any 40-character literal.
#
Appendix E -- Setting Error Number
##
Editing
When MAGEC does its Automatic Editing for your screen fields it sets standard Error Numbers which cause the (cont.)
corresponding Error Messages to be displayed on the last three lines of the screen. If you do any Custom coding and add (cont.)
some editing of your own you should follow the same convention.
The Automatic Editing also flags which screen fields are in error, so that they will be automatically altered to (cont.)
"highlighted" on the screen. This means that they will appear either double brightness or in a highlight color (red) (cont.)
for easy identification.
To set the Error Number and flag a screen field as being in error, enter coding as follows:
IF Sfield -----error condition---------
MOVE E TO SfieldE
MOVE 'nnn' TO ERROR-NUMBER
PERFORM CA100-LOAD-ERR-CODE-TBL THRU CA199-EXIT.
where :
Sfield
= the name of a screen field
'nnn'
= an Error Number which is defined on the
MAGEC ERR file.
In the %EDIT Insertion Point this code will cause the MMP to bypass updating the file(s) and just return to MAGECCP to have the Error Messages issued.
If you wish to flag a non-fatal (warning level) error, code:
IF Sfield -----error condition---------
MOVE E TO SfieldE
MOVE 'nnn' TO ERROR-NUMBER
PERFORM CA400-LOAD-WARNING-TO-TBL THRU CA499-EXIT.
The above code will allow the MMP's updating to occur, but will tell MAGECCP to also place the specified Error Message into the screen.
#
Appendix F -- Defining Error Numbers
##
Adding & Updating to ERR File
The Error Numbers and Error Messages which MAGEC places into the last three lines of the screen (SERRMSG) are defined (cont.)
on the ERR file. Error Numbers are 3-character, alpha-numeric codes. The "numbers" which start with "9" are reserved (cont.)
for MAGEC system use, you can use any other Error Numbers for your own applications.
To add a new Error Number online, enter the command:
ERRADD nnn
where
nnn
= the 3-character Error Number you wish to add, then press ENTER.
The ERRADD screen will be presented. You must enter two things:
a 33-character Error Message
up to 4-lines (320-character) of narrative "HELP" text
#
Appendix G -- Coding for PF Keys
##
How to Test Which Key Was Hit
The 3270 terminals have (depending on the model) up to 24 PF keys which the operator can press instead of just pressing (cont.)
the ENTER key. The PF keys send the data to the CPU just like the ENTER key does, thus there are 25 keys the operator (cont.)
can use to send the screen data. The CLEAR key, the PA keys and the TEST key do not count since they do not send the (cont.)
screen data, just a one-byte code.
next: cstm15.md.txt