# 
Appendix I -- Using SERRMSG & SCOMPL
## 
Using Top and Bottom Rows of the Screen
The top row of every screen in MAGEC is defined in a standard way and contains the SFUNCT, SKEY, and SCOMPL screen (cont.)
fields. The bottom three rows are always defined as one 240-byte field named SERRMSG. Although these areas of the (cont.)
screen are used by MAGEC for specific purposes there are occasions when you may wish to display data or messages in (cont.)
SCOMPL or SERRMSG. You may do so with the understanding that MAGEC will, under certain conditions, overlay what you (cont.)
have placed there with error messages or other system messages.
If you wish to display data in the last three rows of the screen you could define a work area in VARIABLE-STORAGE, move (cont.)
the desired literals and data fields into the work area to build your display, and then move the entire work area to (cont.)
the last three lines as:
MOVE work-area TO SERRMSG
 
The SERRMSG area is also "broken-down" into six 40-byte fields. You can, therefore, also move to the 40-byte fields individually as:
MOVE message TO TWA-SERRMSG-MSG (n)
 
where
n
= a numeric subscript value from 1 to 6.
If you wish to move a message to the SCOMPL screen field on the top line of the screen you may code:
MOVE message TO SCOMPL
 
NOTE:
**
You may only use the SERRMSG and SCOMPL areas for display-only purposes. If screen field editing errors are detected by (cont.)
the MAGEC Automatic Editing feature or by your customization coding then SERRMSG and SCOMPL will be cleared and error (cont.)
messages will be placed there, overlaying your display.
# 
Appendix J --Transferring to non-MAGEC Programs
## 
Why Transfer to non-MAGEC Program
Occasionally it will be desirable to provide a "seamless" connection between a new application you have created in (cont.)
MAGEC an an existing application. For example, suppose that you wanted to enhance your old online Inventory system by (cont.)
adding browse, inquiry, and update facilities for your Vendor data. Further, suppose that you wanted the new functions (cont.)
to be "embedded" into a sequence of screens which already exists (and was not developed using (cont.)
MAGEC).
This can be done easily using the built-in facilities of MAGEC for passing control between MAGEC and non-MAGEC (cont.)
applications. The operator could see a sequence of screens consisting of your old non-MAGEC screen(s), followed by new (cont.)
MAGEC-generated screens, followed by more old screens. The operator need not log onto and off of MAGEC repeatedly in (cont.)
order to do this. The applications can pass data back and forth, as well.
## 
From MAGEC to non-MAGEC
To transfer from your MAGEC MMP to a non-MAGEC application, you have two alternatives: you can transfer to a Tran-ID or to a program name. To transfer to a Tran-ID, code:
MOVE 'TRANSFER' TO TWA-NONTP-REQUEST.
**MOVE 'tttt----dd...dd' TO SERRMSG.
GO TO AA900-GOBACK.
Where: "tttt" is the desired Tran-ID (followed by four dashes), and "dd...dd" is up to 232 bytes of data to be passed. (cont.)
The non-MAGEC application will be invoked via a CICS "START". The four dashes signal MAGEC to use the START technique, (cont.)
rather than the XCTL technique (discussed below). The data area length will always be 232 when passed to the START'ed (cont.)
transaction - unless you specify that you do not want to pass any data.
If you *do not* wish to pass any data to the Tran-ID you are transferring to, then SERRMSG should be set to 'tttt----' followed by 232 bytes of LOW-VALUES
To transfer to a program by name, code:
MOVE 'TRANSFER' TO TWA-NONTP-REQUEST.
MOVE 'ppppppppdd...dd' TO SERRMSG.
GO TO AA900-GOBACK.
Where: "pppppppp" is the desired program name, and "dd...dd" is up to 232 bytes of data to be passed. The non-MAGEC (cont.)
application will be invoked via a CICS "XCTL". The data will be passed to the XCTL'ed program as a 232-byte COMMAREA. (cont.)
The XCTL'ed program may ignore the COMMAREA if it does not need any data passed. The absence of the four dashes (see (cont.)
above) signals MAGEC to use the XCTL technique, rather than the START technique.
NOTE:
**
MAGEC will either save the TWA to the TW3K1 file or not save it based upon the setting of XFROT-TWA-SAVE in Table 243. A setting of YES will tell it to save the TWA.
## 
From non-MAGEC to MAGEC
To transfer to a MAGEC application, your non-MAGEC program has two options: to use the CICS START to invoke the special (cont.)
Tran-ID "MAGX", or to use the CICS XCTL to invoke the program "MAGXFRIN". Either way you must pass a parameter (or (cont.)
COMMAREA) containing 41 bytes of data (plus optionally, up to 240 bytes of additional data) which (cont.)
includes:
User-View      4-bytes (a valid MAGEC Tran-ID)
**MAGEC function code      6 bytes
key      31 bytes
user data      240 bytes
NOTE: if the operator is *not* already logged onto MAGEC, the SYSLOG ON screen will automatically be presented, ignoring the function and key you have passed.
To transfer into MAGEC via the START technique, code:
EXEC CICS START
    TRANSID('MAGX')
    TERMID(WS-TERMID)
    FROM(PARMS-TO-MAGEC)
    LENGTH(41)    *[thru 281]*
    INTERVAL(000001)
END-EXEC.
Where: PARMS-TO-MAGEC is a 41 byte (through 281 byte) long area containing the MAGEC Tran-ID (i.e. TS01), the (cont.)
6-character function code, the 31-byte key, plus (optionally) the user data to be passed to the MAGEC MMP. For (cont.)
example:
01  PARMS-TO-MAGEC.
    03 PTM-TRAN-ID    PIC X(04)   VALUE 'TS01'.
    03 PTM-FUNCT      PIC X(06)   VALUE 'CUSSEE'.
    03 PTM-KEY        PIC X(31)   VALUE '123'.
    03 PTM-DATA       PIC X(240)  VALUE 'data to the MMP'.
The above would transfer into MAGEC via MAGEC's User-View 'TS01' and immediately present the CUSSEE screen for customer (cont.)
123 (if such exists). The MMP will receive the 240-byte passed data in the SERRMSG field in its TWA. NOTE:** the (cont.)
receiving MMP should be sure to use or save the passed data from SERRMSG *before* the initialization of the (cont.)
TWA-MSK-DETAIL area by either the reading of a Mask or by the BA200-INIT-ATTRIBUTES routine.
To transfer into MAGEC via the XCTL technique, code:
EXEC CICS XCTL
**    PROGRAM('MAGXFRIN')
    COMMAREA(PARMS-TO-MAGEC)
    LENGTH(000041)     *[thru 000281]*
END-EXEC.
Where PARMS-TO-MAGEC is as shown above for the START technique.
## 
Automatic Log On
Some MAGEC users have external security systems, such as RACF, ACF2, or Top Secret, or a home-grown security system. (cont.)
Some would prefer that their end users not have to log onto MAGEC (via the SYSLOG ON command) since they have already (cont.)
logged onto the system through the external security system. This can be accommodated rather easily using the MAGLOGON (cont.)
program provided with MAGEC.
MAGLOGON is a sub program designed to be called (via EXEC CICS LINK) from any ordinary CICS program. It accepts input (cont.)
parameters via the DFHCOMMAREA and it can either log a user on or off of MAGEC. The normal mode of use would be for you (cont.)
to code a simple CICS program which interrogates your external security system to obtain the ID of the operator and (cont.)
then calls MAGLOGON to log him/her onto MAGEC. The sequence of events would be:
1. Obtain operator ID. This may involve calling a subroutine or some other means provided with your external security system.
 
2. Fill in the COMMAREA according to the format defined below.
 
3. LINK to MAGLOGON passing the COMMAREA.
 
4. Test for successful completion (MAGEC-REQUEST-COMPLETE).
 
5. Handle a rejection with a message to the operator -- if rejected.
 
6. Use the standard MAGXFRIN (or MAGX) facility described earlier to transfer into MAGEC automatically. This last step (cont.)
is optional, but it is a common follow-on to automatically logging an operator on.The format of the COMMAREA (cont.)
is:
 
| ```
01 DFHCOMMAREA.
05 MAGEC-PARAMETERS.
07 MAGEC-REQUEST PIC X(03).
88 MAGEC-REQUEST-LOGON VALUE 'ON ' 'IN '.
88 MAGEC-REQUEST-LOGOFF VALUE 'OFF' 'OUT'.
88 MAGEC-REQUEST-COMPLETE VALUE SPACES.
07 MAGEC-USER-VIEW.
09 MAGEC-T-OR-P PIC X(01).
88 MAGEC-T-OR-P-VALID VALUE 'T' 'P'.
09 FILLER PIC X(02).
09 MAGEC-VIEW-NO PI C X(01).
88 MAGEC-VIEW-NO-VALID VALUE '1' THRU '8'.
07 MAGEC-USER-IDENTIFIER.
09 MAGEC-USER-EMPNUM PIC 9(09).
09 FILLER PIC X(07).
07 MAGEC-EMPLOYEE-NUMBER PIC 9(09).
```** 
When filling in the request area you must set one of the valid request commands into the MAGEC-REQUEST field. It would (cont.)
probably be a good practice to move your command to the group item MAGEC-PARAMETERS in order to ensure clearing the (cont.)
rest of the request area with spaces.
You must also specify one of the MAGEC user-views (TS01 - TS08, or PR01 - PR08) in the field named MAGEC-USER-VIEW. (cont.)
Then you must specify the operator's ID from the external security system in the field named MAGEC-USER-IDENTIFIER. (cont.)
This may be any alpha-numeric ID up to sixteen characters long.
If your logon request is successful, the MAGEC-REQUEST field will be set to spaces and the operator's employee number (cont.)
(from the MAGEC security system) will be returned to you in the MAGEC-EMPLOYEE-NUMBER field. This is just for your (cont.)
information, the operator is already logged onto MAGEC.
If the MAGEC-REQUEST field is returned to you with a value of 'COM', your logon attempt failed because of a badly formatted COMMAREA.
The MAGLOGON program translates the external ID to a MAGEC employee number via a special security ID translation table (cont.)
which is called "Table SSS". You can maintain Table SSS using the online functions: SSSADD, SSSCHG, et (cont.)
cetera.
For example:
SSSADD JOE JONES
 
would return you the screen to enter the MAGEC employee number for Joe Jones (assuming his external security ID is JOE (cont.)
JONES). Then you simply enter his employee number into the screenfield titled "MAGEC Employee (cont.)
Number".
# 
Appendix K -- Data Transformations
## 
Transform, Inspect, and Examine
Cobol programmers often utilize certain Cobol verbs which facilitate conversions or transformations of characters. This (cont.)
is a useful feature of Cobol, expecially when it is necessary to change lowercase alphabetics to uppercase or (cont.)
vice-versa, but is accompanied by some problems. The problems arise because of the differences between Cobol compilers. (cont.)
These differences are apparent when compilers for VSE versus MVS, or ANSI '74 versus ANSI '85 (especially IBM VS Cobol (cont.)
II), or ANSI '68.
MAGEC provides several "subroutines" which can be called to accomplish the functions of some of these verbs.
## 
Transform verb
The Transform verb is used for converting characters in an area using corresponding tables of "from" characters and "to" characters. For example:
TRANSFORM CUS01-NAME FROM LOWER-CASE TO UPPER-CASE.
Where CUS01-NAME is the field to be operated upon, whose characters are to be converted, LOWER-CASE is a table of (cont.)
characters to be converted, UPPER-CASE is a table (the same length as LOWER-CASE) of characters to convert to. The (cont.)
identical function can be accomplished using a MAGEC-provided subroutine, as:
CALL 'MAGXFRM' USING FORTY CUS01-NAME
** TWENTY-SIX LOWER-CASE UPPER-CASE.
Where: FORTY is a PIC S9(4) COMP SYNC data field having a value equal to the length (in bytes) of CUS01-NAME, and (cont.)
TWENTY-SIX is a similar field containing the length of (each of) the two tables. Note: for this example we assume that (cont.)
the length of LOWER-CASE and UPPER-CASE is 26 bytes each.
Another way to do the same thing, with slightly less coding, is:
CALL 'UPCASE' USING FORTY CUS01-NAME.
To convert from uppercase to lowercase, code:
CALL 'LOWCASE' USING FORTY CUS01-NAME.
The first subroutine, MAGXFRM, is more versatile and can be used for other conversions, while the UPCASE and LOWCASE subroutines are specifically for converting to upper- or lower-case alphabetics.
# 
Appendix L -- Reassigning Some PF Keys
## 
PF2 - PF16 - PF17
The default meanings for PF2, PF16, and PF17 are:
PF2       Field-level HELP
PF16      Copy screen data to Copy/Paste Buffer
PF17      Paste data to screen from Copy/Paste Buffer
PF24      Pop-Up window for short list from prior browse
In most cases you will probably leave these key assignments as they default since these three keys are not usually used (cont.)
for other purposes in most environments. Sometimes, however, you may need to assign other key to these functions, (cont.)

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