Installation Guide

Resource Requirements

Before the MAGEC installer arrives to install MAGEC on your mainframe computer, there are several things that can be done to help ensure a problem-free installation. The most important of these things is to allocate the needed resources.

Library

One of the first steps in installing MAGEC will be to create and load an executable library. In the MVS environment you will use whatever facility you normally use (i.e. ISPF) to create the library with a BLKSIZE=23,476, then use IEBCOPY to load it from the MAGEC.BACKUP tape. In a VSE environment, you will use RESTORE or LIBR to create and load the library.

NOTE:

The library takes approximately 10 cylinders of space, they need directory entries sufficient for approximately 100 library members. You can save time by allocating that space before the installer arrives.

VSAM Space

The MAGEC repository consists of 24 VSAM KSDS files. They are all single key, fixed-length. The largest record length is 4K bytes, largest key length is 64 bytes. They normally use LSR in a CICS environment. The installer will punch out the IDCAMS (or AMSERV) DELETE and DEFINE control cards for all these files. You can prepare for the creation of the files by allocating (DEFINE SPACE) enough space (approximately 250 3380 cylinders) in a VSAM catalogue (create a new user catalogue, if desired). The space need not be contiguous and may be divided across several VOLUME ID's; however, excessive fragmentation may degrade performance. You may also choose to load the VSAM files into UNIQUE space, if you prefer.

The creation of the files is done using the IDCAMS control cards. The files are then initialized by executing a utility program provided by MAGEC (ALALDNUL). They are then loaded by executing another utility program (ALALDFIL) which reads the installation tape as input.

You could accomplish several tasks prior to the installer's arrival:

1. Create the catalogue (if desired).

2. Define the space.

3. Have the JCL handy to execute IDCAMS, including appropriate user catalogue specs.

CICS

The MAGEC installer will punch, from the tape, the necessary PCT, PPT, FCT, and (optional) PLT entries for MAGEC. These are standard CICS macro specifications. You should be prepared to assemble these tables using the jobstreams you use for any other applications. If you are using RDO, you will want to assemble the tables and then import them since they would be tedious to enter manually. The PLT entry is to auto-start the MAGEC Spooler, you can omit it and then manually start it using an online transaction if you prefer.

The DD or DLBL statements for the MAGEC dictionary files must be included into your CICS start-up or (VSE-only) into standard labels, or (MVS-only) as a filespec to the FCT entries (if you wish to alter them before assembling them). The DD or DLBL statements are also punched by the installer.

The new MAGEC library (discussed earlier) must also be concatenated into the CICS library search.

Training

The MAGEC Startup Program, a separately priced item which is usually purchased with the initial installation of MAGEC, consists of the following classroom courses:

  • Developing online applications using MAGEC
  • Customizing MAGEC-generated applications
  • Also, included with the standard MAGEC documentation is a full set of tutorials which illustrate actual development, customization, data definition, and security definition and control.

    These tutorials and courses are of interest to application developers, database administrators, and security officers.

    Professional Services

    MAGEC Software can provide additional services ranging from basic consulting in the use of MAGEC through complete project direction and execution. MAGEC Software's professional consultants are experienced in the development of projects of any size. Many users feel that employing one or more of our professionals on their first large project adds a level of comfort and assurance and helps them to take advantage of the experience of others in similar efforts.

    Support Calls

    If you or your technical support personnel have any questions, please feel free to call us at one of the numbers below. The toll-free 800 numbers are valid in all of the contiguous United States.

    1-214-202-4965

    Execute-Only or Limited Versions

    Some MAGEC users having multiple CPU's prefer to do all development on one CPU and to run production on the other(s). In some Corporate Licensing arrangements development functions might be contractually restricted to one (or several) CPU's. In those cases it is sometimes useful to install only a partial MAGEC system on the non-development CPU's. The central active dictionary is necessary at execution time for such features as the interactive help keys, security verification, automatic menu generation, and message handling and compression; however, many entities contained in the complete dictionary are unnecessary in an execute-only environment.

    The disk space requirements are reduced (below the 200 cylinders recommended on the first page) if you are only installing a subset of the complete MAGEC system.

    If you will not be doing any application development, you can greatly reduce the space requirement for the portion of the MAGEC dictionary used to store source code (the ALG file). This would represent a reduction of approximately 30 Megabytes.

    If the above is true, you could also eliminate the freespace and over-allocation of most of the MAGEC files, since your environment will be more static and you will not be adding new specifications to the dictionary. The files involved are the SHD, SCF, MMP, MSK, DCL, ELT, DIT, and KYF.

    In addition, if no development will be done using MAGEC, you might delete all the unused PPT entries. They are normally disabled by CICS at startup, anyhow. This saves only a few bytes each, but is neater than having unused (and never-to-be-used) PPT entries.

    If you will not be using the MAGEC TP Spooling facility, you can eliminate the two files used by the Spooler (the SPL file and the RPH file). This would result in a further reduction of approximately 40 Megabytes.

    In any case, you should initially allocate the full 200 cylinders in order to simplify the installation; then begin trimming the files after installation is complete.

    Some MAGEC users may wish to create smaller, execute-only versions of MAGEC for the PC's. This can be done by removing all but the necessary run-time programs and by reducing the size of the ALG-file to its minimum size.

    The fastest way to reduce the size of the ALG-file is to execute MAGINIT against it, thereby initializing the file to contain no records. This is done as:

    MAGINIT ALG  

    The minimum list of executable (program) files needed for an execute-only system is:

    APLOAD APUNLOAD MAGINIT DDAUDIT
    MMP650 MMP652 MMP653 MMP654
    MMP661 MMP663 MMP636 MMP670
    MMP675 MMP682 MMP684 MMP685 All of these files, of course, have an extension of .EXE and/or .DLL and are found in the MAGEC directory. You can delete (erase) any other of MAGEC's .EXE files, leaving only the above list plus your own application MMP's, etc.. It might also be a good idea to execute the CLEANLIB procedure (.BAT file) on the PC to erase any temporary files which may be left in the MAGEC directory.
     


    MVS Initial Installation

    The MAGEC system is normally installed initially by one of MAGEC Software's technical representatives, this topic is provided to enable you (in the event it becomes necessary) to install MAGEC without having such a technician available, and to help you to prepare for what will be done when the installation commences. You should read the Mainframe Pre-Installation topic before this topic. The components required to initially install your MAGEC system include:

    1. MAGEC.BACKUP tape containing IEBCOPY of complete MAGEC Load library.

    2. MAGEC.DATABASE tape containing upgraded source and dictionary data for MAGEC.

    3. Documentation manuals.

    NOTE:

    NOTE:

    The steps to do in order to install MAGEC are:

    1. Create a 10-cylinder loadlibrary, BLKSIZE=23,476, with sufficient directory entry space for approximately 100 members.

    2. Load the loadlibrary using IEBCOPY with the MAGEC.BACKUP tape as input. If you wish to alter the BLKSIZE, you can use the COPYMOD option of IEBCOPY, otherwise use the COPY option.

    3. Create the JCL named ALGTPCHX (see exhibit 1.1.5.1). Be sure to set the STEPLIB pointing to the newly created loadlibrary.

    4. Execute ALGTPCHX using the control cards (see exhibit 1.1.5.2.a), the output file (SYS005) should require about 20 tracks (or less). It will be a sequential file containing bootstrap members to eliminate the need for you to do much typing for the file definitions and CICS table entries.

    5. Use ISPF (or another editor) to separate the punched members (from SYS005, above). There will be a separator card indicating the name of each member. The separator cards start with -MAGECREP LIB (beginning in column 1). Save the individual split-out members in a PDS or other online librarian file for later use, use the 8-character name which is specified in the separator cards immediately following -MAGECREP LIB.

    6. Modify the IDCAMS control cards (member name: DEFFILES) to suit your environment. At minimum you must provide the VOLUME name. It is permissible to alter CI sizes, change the REUSE to SPEED, or make other desired changes.

    7. Execute IDCAMS using the DELETE/DEFINE control cards from above. Highest return code should be 8 (the DELETE commands should get a not found the first time you run this). The SPL file (MAGEC-SPL-CLUSTER) is rather large (approx 775 tracks). The total space requirement for all files, including the SPL and RPH files, will be almost 200 cylinders for 3380 drives.

    8. Create ALANULEX JCL (see exhibit 1.2.2), be sure to include the DD statements (see exhibit 1.1.6.2.2) for all the MAGEC files, also set the STEPLIB pointing to the new loadlibrary. The DD statements are in the member named VSAMDD from step 5.

    9. Execute ALANULEX. This job initializes all the files. It runs for 30-45 minutes or longer since it populates the spooler files as well. The SYSOUT will show the VSAM file statuses for the files.

    10. Execute ALGTPCHX (from step 3) once more, this time with only one control card (see exhibit 1.1.5.2.c). You may wish to delete and uncatalog the SYS005 output file created earlier or just use a different DSN, this time. The output will contain a host of sample jobstreams for various MAGEC batch processes.

    11. Create ALALDEX JCL (see exhibit 2.3). Include the DD statements and STEPLIB.

    12. Execute ALALDEX. This job reads the MAGEC.DATABASE tape (SYS010) and populates the MAGEC VSAM files. It will run approximately 1-2 hours, depending on contention with other regions, etc.

    13. While step 12 is running, use ISPF (or another editor) to separate and tailor the jobstreams. They will have separator cards preceding each member, as before. In order to facilitate your tailoring, there are symbolic parameters coded in the sample jobstreams. You can use the global change facility of your editor to alter all occurrences of each symbolic to the appropriate value for your shop. If these do not accomplish 100% of what you desire, you can then use your editor to finish up the modifications.

    14. Assemble the PCT, FCT, and PPT tables using the DFHPCT, DFHFCT, and DFHPPT members created in step 5.

    15. Add the DD statements (VSAMDD) to your CICS startup deck, unless you have altered the DFHFCT entries to include the DSNAME's. Add the MAGEC loadlibrary to the DFHRPL DD statement. Refer to exhibit 1.1.6.2.2.

    16. Migrate the PPT and PCT tables using RDO, if desired.

    17. Cycle CICS and test that MAGEC comes up by entering the trans-id of TS01. You should receive the logon screen. You may log onto MAGEC using the employee number of 18 and a password of ALEE. Pressing PF15 at any time exits MAGEC completely, returning to CICS.

    18. If you wish to use the MAGEC TP Spooler, you must initialize the two spooler files, the RPHK1 file and the SPLK1 file. To do this you must execute the RPHINIT and SPLINIT jobstreams. Refer to exhibit 1.2.2.a. The files must be closed to CICS when these are run.


    MVS Upgrade

    The upgrade will take 1-3 hours, normally. You should schedule to do it while all the MAGEC files are closed to CICS and to any other region. The components required to upgrade your MAGEC system include:

    1. MAGEC.BACKUP tape containing IEBCOPY of complete MAGEC Load library.

    2. MAGEC.DATABASE tape containing upgraded "source" and dictionary data for MAGEC.

    3. New documentation manuals.

    The steps to do in order to apply the upgrade are:

    A. Back Up your MAGEC dictionary files and libraries!!!

    B. Use IEBCOPY to restore the MAGEC.BACKUP tape to the MAGEC loadlibrary.
    (BLKSIZE = 23,476 , size approximately 10 cylinders). If you wish to load into a library with a blocksize other than 23,476 you must use the COPYMOD option of IEBCOPY, instead of the COPY option.

    C. If you currently have MAGEC 2.x installed and are upgrading to MAGEC 3.x, refer to Appendix A.

    D. Execute the ALALDFIL program (from new library) using the MAGEC.DATABASE tape as input. The JCL should be on your online editor file named: ALALDEX. The MAGEC.DATABASE tape is UNLABELED. You should run this while your online system is down to avoid potential problems, it should run from one hour to three hours in duration. You may wish to run MAGECLBR with a -MAGECIDX FCD control card before running ALALDFIL if you have modified any of the FCD (Security) profiles for MAGEC system functions.

    E. Modify your PPT entries as required. The new version of MAGEC has several new online programs which were not in the earlier releases. You can use MAGECLBR to punch off the member named DFHPPT, if you wish. It contains all the entries needed for MAGEC plus dummy entries for future expansion. Refer to the Offline Utilities chapter of your Programmer's Reference Guide for a detailed discussion of MAGECLBR. The control card to punch DFHPPT is:

    -MAGECPCH LIB DFHPPT  

    NOTE:

    Please call MAGEC Support at (214) 488-3000 or (800) 336-2432 if you have any problems.


    VSE Initial Installation

    The MAGEC system is normally installed initially by one of MAGEC Software's technical representatives, this topic is provided to enable you (in the event it becomes necessary) to install MAGEC without having such a technician available, and to help you to prepare for what will be done when the installation commences. You should read the Mainframe Pre-Installation topic before this topic. The components required to initially install your MAGEC system include:

    1. MAGEC.BACKUP tape containing VSE library backup of complete MAGEC PHASE and OBJECT library.

    2. MAGEC.DATABASE tape containing upgraded "source" and dictionary data for MAGEC.

    3. Documentation manuals.

    NOTE:

    If MAGEC is already installed on your computer you should probably not be reading this topic, you should be reading the VSE Upgrade topic.

    NOTE:

    The steps to do in order to install MAGEC are:

    1. Create a 20,000 block VSE library, with sufficient space for approximately 100 members.

    2. Load the library using LIBR with the MAGEC.BACKUP tape as input. The tape is in "old" VSE format with IJSYSRL and IJSYSCL files (may be named MAGECRL and MAGECCL) included.

    3. Create the JCL named "ALGTPCHX" (see exhibit 1.1.5.1). Be sure to set the LIBDEF pointing to the newly created loadlibrary.

    4. Execute ALGTPCHX using the control cards (see exhibit 1.1.5.2.a), the output file (SYS005) should require about 20 tracks (or less). It will be a sequential file containing "bootstrap" members to eliminate the need for you to do much typing for the file definitions and CICS table entries.

    5. Use ICCF (or another editor) to separate the punched members (from SYS005, above). There will be a separator card indicating the name of each member. The separator cards start with -MAGECREP LIB (beginning in column 1). Save the individual split-out members in a PDS or other online librarian file for later use, use the 8-character name which is specified in the separator cards immediately following "-MAGECREP LIB ".

    6. Modify the IDCAMS control cards (member name: DEFFILES) to suit your environment. At minimum you must provide the VOLUME name. It is permissible to alter CI sizes, change the REUSE to SPEED, or make other desired changes.

    7. Execute IDCAMS using the DELETE/DEFINE control cards from above. Highest return code should be 8 (the DELETE commands should get a not found" the first time you run this). The SPL file (MAGEC-SPL-CLUSTER) is rather large (approx 775 tracks). The total space requirement for all files, including the SPL and RPH files, will be almost 200 cylinders for 3380 drives.

    8. Create ALANULEX JCL (see exhibit 1.2.2), be sure to include the DD statements (see exhibit 1.1.6.2.2) for all the MAGEC files, also set the LIBDEF pointing to the new library. The DLBL statements are in the member named VSAMDLBL from step 5.

    9. Execute ALANULEX. This job initializes all the files. It runs for 30-45 minutes or longer since it populates the spooler files as well. The print ourput will show the VSAM file statuses for the files.

    10. Execute ALGTPCHX (from step 3) once more, this time with only one control card (see exhibit 1.1.5.2.c). The output will contain a host of sample jobstreams for various MAGEC batch processes.

    11. Create ALALDEX JCL (see exhibit 2.3). Include the DLBL statements and LIBDEF.

    12. Execute ALALDEX. This job reads the MAGEC.DATABASE tape (SYS010) and populates the MAGEC VSAM files. It will run approximately 1-2 hours, depending on contention with other regions, etc.

    13. While step 12 is running, use ICCF (or another editor) to separate and tailor the jobstreams. They will have separator cards preceding each member, as before.

    14. Assemble the PCT, FCT, and PPT tables using the DFHPCT, DFHFCT, and DFHPPT members created in step 5.

    15. Add the DLBL statements (VSAMDLBL) to your CICS startup deck, add the MAGEC library to the DFHRPL DLBL. Refer to exhibit 1.1.6.2.2.

    16. Migrate the PPT and PCT tables using RDO, if desired.

    17. Cycle CICS and test that MAGEC comes up by entering the trans-id of "TS01". You should receive the logon screen. You may log onto MAGEC using the employee number of 18 and a password of ALEE. Pressing PF15 at any time exits MAGEC completely, returning to CICS.

    18. If you wish to use the MAGEC TP Spooler, you must initialize the two spooler files, the RPHK1 file and the SPLK1 file. To do this you must execute the RPHINIT and SPLINIT jobstreams. Refer to exhibit 1.2.2.a. The files must be closed to CICS when these are run.


    VSE Upgrade

    The components required to upgrade your MAGEC system include:

    1. MAGEC.BACKUP tape containing VSE format backup of complete MAGEC core-image, and relocatable libraries.

    2. MAGEC.DATABASE tape containing upgraded "source" and dictionary data for MAGEC.

    3. New documentation manuals.

    The steps to do in order to apply the upgrade are:

    A. Back Up your MAGEC dictionary files and libraries!!!

    B. For VSE/SP, use LIBR to restore the MAGEC.BACKUP tape to the MAGEC library. (OLDLIB=IJSYSCL and OLDLIB=IJSYSRL). For VSE (pre-SP) use the RESTORE utility.

    C. Execute the ALALDFIL program (from new library) using the MAGEC.DATABASE tape as input. The JCL should be on your online editor file named: ALALDEX.

    You may wish to run MAGECLBR with a -MAGECIDX FCD control card before running ALALDFIL if you have modified any of the FCD (Security) profiles for MAGEC system functions.

    The MAGEC.DATABASE tape is UNLABELED. You should run this while your online system is down to avoid potential problems, it should run from one hour to three hours in duration.

    D. Modify your PPT entries as required. The new version of MAGEC has several new online programs which were not in the earlier releases. It has been the standard of MAGEC Software to populate the PPT table with dummy entries to accommodate adding new modules from time to time. Some users choose to delete these unused, disabled PPT entries in order to clean up their tables. This means that you might need to add a few new entries. The I/O modules (MMP653, and MMP698) have been re-written in Command-Level Cobol (as of version 2.1); the control programs (MMP670 and MMP699) have also been re-written in Cobol (as of version 2.4); this requires a different PPT definition from earlier versions. You can use MAGECLBR to punch off the member named DFHPPT, if you wish. It contains all the entries needed for MAGEC plus dummy entries for future expansion. Refer to the Offline Utilities chapter of your Programmer's Reference Guide for a detailed discussion of MAGECLBR. The control card to punch DFHPPT is:

    -MAGECPCH LIB DFHPPT  

    Please call MAGEC Support at (214) 488-3000 or (800) 336-2432 if you have any problems.


    PC-MAGEC Installation - Realia

    MAGEC no longer supports the Realia COBOL compiler.


    PC MAGEC Upgrades - Realia

    MAGEC no longer supports the Realia COBOL compiler.


    PC-MAGEC Installation - Micro Focus Cobol

    The system is delivered on 3.5" diskettes. The diskettes are labeled Workstation or Server Installation.

    After completing the installation your system should contain the following directories for MAGEC.

    \MAGMF  

    \MAGMF\JCL  

    MAGEC needs approximately 20Mbytes of hard disk space. It will run on 286, 386, or 486, or Pentiuim machines with at least 640Kbytes of memory plus 2Mbytes extended memory (8Mbytes minimum recommended if using Windows.

    There are two installations you must accomplish, first for the Server, second for the Workstation. MicroFocus Professional Cobol (v3.2 or later) should be installed prior to installing MAGEC since it adds statements to your CONFIG.SYS and/or AUTOEXEC.BAT which MAGEC's installation searches for and modifies. If installing the Windows, or GUI Windows versions the installation will create a Windows group and icons for you.

    NOTE:

    a: \INSTALIT  

    If you did not choose to allow the install program to modify your AUTOEXEC.BAT and CONFIG.SYS files you should also add the MAGMF and Cobol directories to your PATH or MAP):

     c:\MAGMF\JCL;\COBOL\EXEDLL  

    And, you should include the following settings for environment variables.

    SET LANDRV=G  

    SET LCLDRV=C  

    SET EXEDRV=G  

    SET XM=+R (if on a LAN)  

    SET COBDIR=x:\COBOL\EXEDLL;x:\COBOL\LBR;G:\MAGMF;  

    SET LIB=x:\COBOL\LIB;  

    SET LPT=LPTn  

    SET ALTLPT=LPTn  

    SET COM=COM1  

    LANDRV is the drive on which the \MAGMF directory resides. LCLDRV is the local disk drive to be used for work files, etc, EXEDRV is the drive on which the MAGEC executables reside. The above example assumes that your C: drive is the local drive and that the \MAGMF directory is on drive G: (perhaps, a LAN server drive).MicroFocus Cobol is on drive x:. If other drive ID's are desired, adjust the above statements accordingly.

    LPT is the printer port, you can set LPT to any valid port, or to a file name. ALTLPT is set to indicate an alternate printer port used when a program issues MAGEC Spooler print output to location 'ALT'; it may be the same as LPT, or different. COM1 is the serial port to which a modem is attached (for phone dialing), you may set this to any other valid serial port, or to a file name, or to NUL.

    If you are using MAGEC's TCP/IP inter-network communication facility, you should also add some other settings into your environment. For each computer which is acting as a "host", or "gateway", you should include:

    SET MAGPORT=nnnnn  

    SET MAGHOST=xxxxxxxxxxxxxxxx  

    MAGPORT is the IP port number to be used for communication between the MGCLIENT and MGHOST service modules. This port number is also defined in MAGEC's TBL file in Table # 243 (system configuration parameters) under the name of TCPIP-PORT. The setting for MAGPORT should be the same as for TCPIP-PORT, the default in both cases is 05998. The MAGPORT setting tells MGHOST which port number to "listen" on, the Table #243 TCPIP-PORT setting tells MGCLIENT which port number to "send" on.

    MGHOST is the name of this computer. This name (up to 16 characters long) must match the entry specified for this IP address in Table # 248. The MAGHOST setting is only actually required if this computer will be used as both a host and as a client for MAGEC applications. It lets MAGEC's I/O module know that files which specify a gateway name matching the MAGHOST setting are really local files to this computer.

    NOTE:

    \MAGMF

    \MAGMF\JCL

    \COBOL (and associated sub-directories)

    DEVICE=C:\DOS\HIMEM.SYS  

    DEVICE=C:\DOS\EMM386.EXE 2048 RAM  

    DEVICEHIGH=C:\DOS\ANSI.SYS  

    FILES=128  

    BUFFERS=24  

    SHELL=C:\DOS\COMMAND.COM /P/E:1024  

    NOTE:

    If you have any questions call us at:

    214 202-4965


    PC MAGEC Upgrades - Micro Focus Cobol

    If you are upgrading your MAGEC system on the PC, you follow the same procedure as for the initial installation.

    Call MAGEC support if you encounter any difficulties.


    Keyboard

    This topic applies only to RealiaCobol users.

    MAGEC no longer supports the Realia COBOL compiler.


    Large + Key / ENTER Key

    Avoiding Confusion

    You will notice that within MAGEC's online environment, in text mode on a PC, the large plus key is used as an ENTER key. This is also true in some other software products which emulate a mainframe 3270 environment. The reason for this is because the PC is an ASCII machine and, like other ASCII machines and terminals, it uses the RETURN key to signal the end of an entry. This is an ASCII standard which dates back to the days when most terminals were oriented to entering lines of data, rather than formatted screensful of data. In days gone by most of these devices were keyboard/printers (like teletype machines), rather than video devices.

    In the mainframe 3270 environment the RETURN key moves the cursor down and left to the first unprotected field on the next lower line which has an unprotected field. In order to emulate the mainframe environment accurately MAGEC makes the RETURN key work just as it does on a 3270. This means that we must find another key to use as an ENTER key. In order to be compatible with certain other PC software which emulates the mainframe environment, we adopted the standard of using the large plus key at the right end of your keyboard.

    This standard works well with one exception. When you are not in MAGEC (or any other package compliant with our standard), the large plus key simply types a plus sign (+) on the screen. You must use the RETURN key to terminate your entries, particularly when entering MS-DOS/PC-DOS commands. This causes some confusion among many users since their fingers become trained to reach for the large plus key. There is, however, a solution to the problem.

    You can tell MS-DOS or PC-DOS to recognize the large plus key as an ENTER key. This avoids a lot of frustration. It has only one drawback. If you do that, you will not be able to actually type the plus sign (+) in any DOS command unless you first tell DOS not to recognize the large plus key as ENTER. Fortunately, it is only very rarely that you need to use a plus sign in DOS commands.

    To tell DOS to recognize the plus sign as an ENTER key, execute the command:

    TYPE x:\MAGxx\MAGENTER.ON  

    The RETURN key will still also be recognized as an ENTER key.

    To tell DOS to recognize the plus sign as a plus sign, execute the command:

    TYPE x:\MAGxx\MAGENTER.OFF  

    NOTE:

    A convenient place to turn this feature on is in your AUTOEXEC.BAT file. Another place you might do it is in a RE_SET.BAT file in your root (or \BATCH) directory. All of MAGEC's processes are executed via .BAT files and they all are setup to execute your RE_SET.BAT file when they are completed (if your RE_SET.BAT file exists). You must specify DEVICE=ANSI.SYS in your CONFIG.SYS file for these commands to work properly.

    If, for some reason, MAGENTER.ON conflicts with some other piece of software you may wish to use, simply do the MAGENTER.OFF before executing the other software, then do MAGENTER.ON when you are finished. This is easily done if you execute all your software via .BAT files.


    Mouse Support-Micro Focus Cobol

    MAGEC for Micro Focus Cobol includes mouse support under MS-DOS, Windows, OS/2, and Unix operating environments. If your MAGEC-generated application is being executed in GUI (Graphical User Interface) mode (as opposed to text mode), a mouse is an integral part of the application's user interface. If your application is being executed in text mode, the mouse is a nice-to-have accessory which takes advantage of the high degree of standardization of MAGEC applications to provide very handy features with no additional programming required of your developers. This topic discusses the mouse in text mode execution under DOS, Windows, or OS/2.

    In text mode, only the mouse cursor position and the left mouse button can be sensed. The right button (and center button, if installed) are ignored. All mouse sensing is handled in MAGEC's Control Program and no code need be added to your applications to operate with a mouse. Any application can be used either with, or without, a mouse.

    PF Keys using Mouse

    The first mouse service we will discuss here is the simulation of Program Function keys (PF-keys, or F-keys) using the mouse. It is customary, and consistent with MAGEC's standards, to display PF key instructions on the screen telling the operator which keys provide which functions for every screen. The structure of these instrucdtions may vary, but should follow one of several formats which will be discussed below. If the operator points the mouse cursor onto a screen message indicating the meaning for a PF key, MAGEC will automatically simulate that that key was pressed when the left mouse button is clicked. In order for MAGEC to recognize PF key instructions from miscellaneous text displayed, certain rules of form should be followed,. Below is a list of samples which will be recognized by MAGEC's mouse handler:

    PF nn =blah-blah

    F nn =blah-blah

    nn =blah-blah

    nn =blah-blah/ mm =this-n-that/ pp =something-else

    The key numbers may be one- or two-digit numbers. They may be preceded by "F", "PF", or by nothing (a space or a separator character). The recognized separators are: "/" "," ";" "(" or space.

    The PF key instructions may be anywhere on the screen, including in SERRMSG (last three lines of screen), and SCOMPL (right half of the top line of the screen), but must be in a protected field on the screen. No PF key instructions will be recognized in a screen field which is unprotected (enterable by the application user). The mouse may be pointed to any character position within the message for the desired key, MAGEC will scan leftward until reaching a space or a separator, then will test for a valid key number. If the message contains embedded spaces and if the user points to the right of a space character, MAGEC will not recognize the key number as being part of the selected message and will ignore it, assuming that the operator merely wished to position the text cursor where the mouse cursor was pointing when the left button was clicked.

    Pop-Up Error Help

    It is another MAGEC standard that error messages be presented in the SERRMSG field (last three lines of the screen). Without a mouse, the operator can press PF1 any time such error messages are shown and will receive an expanded explanation for each error message on the screen. With a mouse, the operator can also point the mouse cursor to any such error message, click the left mouse button, and receive a pop-up window with an expanded explanation for the chosen error message. The pop-up window contains a push button saying "OK". pointing to the push button and clicking the left mouse button will remove the pop-up window. Pressing the CLEAR (Escape) key will also remove the pop-up window, any other keystroke will be ingored. While the pop-up window is being displayed, the error number at the front of the error message chosen will blink to indicate which error message the expanded explanation applies to. The operator can select another error message to get an explanation of it, if desired, after removing the pop-up window for the prior error message.

    Positioning Text Cursor with Mouse

    The final function of the mouse in text mode is to re-position the text cursor. If the operator moves the mouse cursor to any screen position (not recognized as either a PF key message or an error message number) MAGEC will re-position the text cursor there when the left mouse button is clicked. Notice that nothing happens until the left mouse button is clicked. Just moving the mouse merely moves the mouse cursor around the screen display, but has no effect on where the operator is typing. The text cursor always controls where the operator's typed data is being entered into the screen.

    Cursor Appearance

    The mouse cursor can easily be distinguished from the text cursor by its appearance. Its appearance changes depending on the environment you are operating in. The text cursor is always the blinking underscore character.

    You can execute MAGEC under OS/2 (a product of IBM) in either full-screen, or window mode. In OS/2 full-screen display mode, the mouse cursor appears as a rectangular block which has the inverse color scheme of the surrounding screen. In OS/2 window mode, the mouse cursor is a black diagonal arrow pointing toward the upper left. This is the standard OS/2 mouse cursor shape.

    In MS/DOS (a product of Microsoft), the mouse cursor is the inverse-colored rectangular block.

    In Windows (a product of Microsoft), the mouse cursor is the outlined white Windows cursor arrow pointing (more-or-less) toward the upper left.

    If the mouse cursor is the rectangular block, moving the mouse moves the mouse cursor in increments of one screen character at a time. If the mouse cursor appears as an arrow, moving the mouse moves the mouse cursor in increments of one pixel at a time. All other functionality is identical, as the pixel coordinates are converted into screen character coordinates automatically before being processed.


    Mouse Support-Realia Cobol

    MAGEC 3.0 no longer supports Realia COBOL.


    PC Video Types

    This topic applies only to RealiaCOBOL users.

    MAGEC 3.0 no longer supports the Realia COBOL compiler.


    PC Batch Files

    All of MAGEC's programs are designed to be executed via .BAT files, rather than standalone. All of the .BAT files provided with MAGEC are in the \MAGMF\JCL directory. You should include \MAGMF\JCL in your path in order to have access to them. All of the programs themselves are in the \MAGMF directory, as are all of MAGEC's data files. It is wise to not include \MAGMF in your path; this eliminates the possibility of accidentally typing in a program name instead of a .BAT file name and executing the program without the proper setup normally provided by the .BAT files.

    Many of the .BAT files replicate jobstreams used with MAGEC on the mainframe. They are documented in the Offline Utilities chapter of the Programmer's Reference Guide . Some others which are useful are listed below.

    REORG

    MAGEC utilizes indexed files on the PC, emulating a VSAM or Datacom/DB environment on the mainframe. These files should be reorganized from time to time, just as on the mainframe. To simplify reorganizing the files MAGEC includes a .BAT file named REORG.BAT. It will reorganize one file at a time. It is invoked from the DOS prompt as:

    REORG xxx  

    where xxx is a Data Class name defined to MAGEC. For example: REORG ALG would reorganize the MAGEC ALG file. The DOS file name for the ALG file is: ALGK1.DAT, according to MAGEC's standards. You can reorganize any of MAGEC's repository files or any of your own files this way.

    NOTE:

    FILESTAT

    You can display the statistics and specifications for an indexed file using the FILESTAT command. At the DOS prompt, enter:

    FILESTAT xxx  

    where xxx is the Data Class name of the file. The filespec is assumed to be xxxK1.DAT, according to the MAGEC standard.

    CLEANLIB

    As you compile programs on your MAGEC PC, you will be creating more and more miscellaneous text files in your \MAGMF directory. These files are not indexed files, they are merely sequential data files used in the program generation, compilation, and link processes. In order to recapture space on your disk you should periodically execute the CLEANLIB.BAT routine. It deletes those files.

    The files in question include the Cobol listings from the compiler, the object modules from the compiler, the Cobol source file from the program generator, and the map file generated by the compiler for use in the debugger. There are certain .OBJ files which should never be deleted from your \MAGMF directory; therefore, you should not attempt to erase files manually. You shoud use the CLEANLIB routine to erase unneeded files. There are no parameters for CLEANLIB, from the DOS prompt, enter:

    CLEANLIB  

    TRACE

    When you are using the online facilities of MAGEC, you will ordinarily invoke MAGEC using the trans id of TS01. There is a TS01.BAT file in the \MAGMF\JCL directory. If you wish to invoke MAGEC and place it in debug mode, which enables you to trace your Cobol MMP's, you should execute the TRACE.BAT file, instead. To do so, from the DOS prompt, enter:

    TRACE  

    There are no parameters for TRACE. You will invoke the online MAGEC simulator with the debugger activated. Everything will be a bit slower, but will execute the same as it does ordinarily. When you execute an MMP which has been compiled for ANIMATE, the debugger will display the source code and you can control execution step-by-step.

    If you are using Micro Focus Cobol, you must have compiled your program using the ANIMATE option of MMPCREAT, i.e.: MMPCREAT nnn ANIMATE

    TS01

    The online CICS trans id for MAGEC is TS01 (also TS02 thru TS08, and PR01 thru PR08). On the PC you execute the TS01.BAT file by typing "TS01" at the DOS prompt. This simulates the CICS trans id. The TS01.BAT file executes the MAGEC control program, MMP670. MMP670 accepts parameters on the command line which specify execution options. These parameters are positional, they must be given in the proper sequence. They are fixed-length and are separated by a single space between them.

    The parameters are:

    MMP670 TTTT/KKKKK/D/L/999999999  

    where TTTT is a 4-character MAGEC User View (i.e. TS01), KKKKK is a 5-character keyboard type (i.e. STDKB), D is a display mode (i.e. M), and L is a LAN drive ID (i.e. G), and 999999999 is the operator's MAGEC Employee# (optional). The LAN Drive ID is normally set using the LANDRV environment parameter, i.e.: %LANDRV%. It tells MAGEC where to look for database files if the file's definition does not explicitly specify a drive (refer to the KYFxxx screen).

    EXEC

    When you execute generated batch programs (MBP's) normally, you do so by invoking the EXEC.BAT file. To do so, from the DOS prompt, enter:

    EXEC xxxxxxxx  

    where xxxxxxxx is the actual program name to be executed (i.e. EXEC MBP600B).

    DBUG

    When you execute generated batch programs (MBP's) in debug mode, you do so by invoking the DBUG.BAT file. To do so, from the DOS prompt, enter:

    DBUG xxxxxxxx  

    where xxxxxxxx is the actual program name to be executed (i.e. DBUG MBP600B). The program will execute with the debugger activated. If you have the necessary files (which were generated by the compiler) present in the \MAGxx directory, you will be displayed the Cobol source and will be able to control execution step-by-step.

    If you are using Micro Focus Cobol, you must have compiled your program using the ANIMATE option of the MBPCREAT, i.e.: MBPCREAT nnnB ANIMATE.

    MAGL

    For network installations using Novell Netware, a special command is provided to invoke the online MAGEC system and to automatically log the user onto MAGEC without requiring the usual SYSLOG ON command. The MAGL.BAT file accesses Novell's security to obtain the user's ID, then accesses MAGEC's "SSS" Table to convert the Novell ID into the user's MAGEC Employee#, then it automatically logs the user onto MAGEC (subject to all the usual security restrictions which would appy if that same user had done the SYSLOG ON command).

    Maintenance to the SSS table can be done online using the SSSADD, SSSCHG, et cetera, functions. The table supports an external ID (in this case Novell user ID) of up to 16 characters and defines the corresponding MAGEC Employee# for that user. If your Novell ID's are longer than 16 characters and you wish to utilize the MAGL facility, you should be sure all Novell ID's are unique within the first 16 characters to avoid possible ambiguity.

    The format for the MAGL command is:

    MAGL uuuu  

    where "uuuu" is any valid MAGEC User-View (TS01, PR02, etc.). If the User-View is omitted, TS01 is assumed.

    MAGINIT

    When you are creating new files to be used by MAGEC, you must initialize them before they can be accessed from the online processes, very much like in the mainframe environment. To initialize a file you use the MAGINIT.BAT file, as:

    MAGINIT xxx  

    where xxx is the data class name as defined to MAGEC's dictionary. MAGINIT will prompt you for verification that you really wish to initialize the file specified. Initializing a file, if it already existed, will lose all records on that file. The result will be an empty file.

    NOTE:

    MAGLOAD

    When you wish to load an indexed file using, as input, another file (perhaps a sequential file downloaded from a mainframe), you can do so using the MAGLOAD.BAT file. The file to be loaded must be defined to the MAGEC dictionary. You type the command:

    MAGLOAD xxx  

    where xxx is the data class name of the file to be loaded. The record length and block size are taken from the MAGEC repository definition for that Data Class (DCL).

    MAGLOAD will prompt you for the name of the input file. If the input file is not in the \MAGxx directory you must include the path with the name. It will also ask whether the input file is in key sequence. A load operation will be faster if the input is in sequence since MAGLOAD must use random, rather than sequential adds if it is not in sequence.

    MAGLOAD will also ask if you wish to ignore any duplicate keys found in the input file. This means duplicates of existing records, as well as of other records on the input file. It will abort upon encountering a duplicate key unless you specify to ignore them, in which case it will simply bypass those records and continue.

    It will finally ask you whether you wish to merge (M) the new file's records into the existing records on the output file, or if you wish to clear the output file and initially load (I) it. If you specify I, any pre-existing records on the output file will be lost, the result will be a file containing only the records loaded from the input file.

    MAGLOAD does not convert EBCDIC to ASCII or vice-versa, it is assumed that the input file is already properly translated, if appropriate. Your file transfer facility should accomplish any necessary translations, beware of incorrect translations of packed, binary, and signed numerics.

    MAGLOAD assumes that the input file is an ASCII text file (Realia file type [T]). If using Realia Cobol and your input file is in some other format, you should suffix the input file name with the appropriate Realia file type code (i.e. [F], [V], etc.). There is no reason ever to specify [U] or [N] since the [T] default accepts files in either of those formats as well.

    MAGUNLD

    When you wish to unload a MAGEC indexed file, perhaps to transfer it to a mainframe, you can use the MAGUNLD.BAT file. To execute MAGUNLD, enter the command:

    MAGUNLD xxx  

    where xxx = the name of the data class to be unloaded.

    MAGUNLD will prompt you to verify that you really wish to unload the specified file. If you made an error in entering the data class name, you will be able to correct it via the interactive prompts. It will then prompt you for the name of the output file to be created. The output file name should include its path. If you omit the path, MAGUNLD will place the output file into your \MAGxx directory.

    For Micro Focus, the output will be an ASCII text file.

    For Realia, the default Realia file type is [U], which results in fixed-length records, without truncation of trailing spaces and without tab compression. In most cases that is the best format for file transfer facilities to upload to a mainframe. If you omit the file type, MAGUNLD will apply type [U] to the output file. If you specify [N], then your output file will have trailing spaces truncated. This format works with most file transfer facilities. If you specify a type of [T], the output file will have trailing spaces truncated and will also have tab compression applied. This format is the most economical from a standpoint of space utilization and speed of access, however, it may not work well with your file transfer facilities. A bit of experimentation (or, [ shudder ] reading the manual) should tell you which file type works best for your needs.

    NOTE:

    Some people find that it is convenient to be able to MAGUNLD an indexed file into a sequential file, then use a text editor or word processor to modify or delete records, then to use MAGLOAD to reload the indexed file from the edited sequential file. This is a handy technique for creating test data or for taking advantage of a particularly powerful feature of your external editor to make changes to an indexed file. This procedure has the added advantage of automatically reorganizing your file as you reload it, if you specify an Initial load, rather than a Merge, and you specify that the input file is in key sequence. MAGUNLD unloads the indexed file in key sequence.

    NOTE:


    Repository Files

    When MAGEC is installed it includes a set of 24 VSAM files which make up the dictionary plus miscellaneous work, logging, and test files. Below is a list of those files with a brief description of what each one is. They are listed in alphabetical order for easy reference. The 3-character names correspond to the 3-character prefix on the DD/DLBL names for these files as well as the 3-character second node of the Dataset names. The CI Sizes shown are merely suggested sizes, you may modify them for purposes of system tuning.

    ALG

    This file is called the Algorithm file. It is used to contain customization algorithms as well as other types of library members, such as source code, copybooks, etc.

    Logical Rec. Lgth: 1259  CI Size: 4096  Key Displacement: 36  Key Lgth: 23

    DBN

    This file is the Database Name file. It is unused. It exists for use by a future version of MAGEC.

    Logical Rec. Lgth: 1016  CI Size: 2048  Key Displacement: 36  Key Lgth: 3

    DCL (and its alias: DC$)

    This is the Data Class file. It contains the definitions for each Data Class (application file), including record length, access method, etc.

    Logical Rec. Lgth: 1016  CI Size: 2048  Key Displacement: 36  Key Lgth: 3

    DIT (and its alias: DI$)

    This is the Data Item file. It contains the detailed definitions for each data item (field) of each element.

    Logical Rec. Lgth: 1016  CI Size: 2048  Key Displacement: 36  Key Lgth: 12

    DOC

    This is the Documentation file. It contains the actual text for the function-level help screens plus any other documentation recorded by your staff.

    Logical Rec. Lgth: 1200  CI Size: 4096  Key Displacement: 36  Key Lgth: 32

    DVC

    This is the Device file. It contains the definitions for printers and video terminals. These definitions are optional, they are needed only if you desire to use the TP Spooler, 7-color video, or terminal security features.

    Logical Rec. Lgth: 200  CI Size: 2048  Key Displacement: 0  Key Lgth: 4

    ELT (and its alias: EL$)

    This is the Element file. It contains definitions for data elements, segments of records, and is part of the data definition portion of the dictionary.

    Logical Rec. Lgth: 1016  CI Size: 2048  Key Displacement: 36  Key Lgth: 5

    ERR

    This is the Error file. It contains error messages and associated help text.

    Logical Rec. Lgth: 392  CI Size: 2048  Key Displacement: 36  Key Lgth: 3

    FCD

    This is the Function Code file. It contains definitions and security parameters for each online function code.

    Logical Rec. Lgth: 100  CI Size: 2048  Key Displacement: 36  Key Lgth: 6

    GCO

    This file only exists in a GUI environment. It is used to store the user color preferences for each user.

    Logical Rec. Lgth: 1200  CI Size: 4096  Key Displacement: 0  Key Lgth: 11

    KYF (and its alias: KY$)

    This is the Key Format file. It contains the definitions for the file keys and editing and formatting rules for their component fields.

    Logical Rec. Lgth: 1016  CI Size: 2048  Key Displacement: 36  Key Lgth: 5

    LAP

    This is the Logical Application file. It contains the definitions for each Logical Application (high-level menu item).

    Logical Rec. Lgth: 77  CI Size: 2048  Key Displacement: 36  Key Lgth: 2

    MAL

    This is the MAGEC Activity Log file. It contains the accumulated statistics gathered by the Activity Logging, if it is turned on.

    Logical Rec. Lgth: 36  CI Size: 2048  Key Displacement: 00  Key Lgth: 14

    MMP

    This is the MMP definition file. It contains the high-level definitions for each MAGEC Message Processor (online program).

    Logical Rec. Lgth: 100  CI Size: 2048  Key Displacement: 0  Key Lgth: 3

    MSK or MS3

    This is the Mask Initialization file (replaced by the MS3 file in MAGEC 3.0 and later). It contains the actual initialization record plus edit parameters for each screen format mask.

    MSK Logical Rec. Lgth: 3904  CI Size: 4096  Key Displacement: 0  Key Lgth: 4

    MS3 Logical Rec. Lgth: 5870  CI Size: 5870  Key Displacement: 0  Key Lgth: 4

    MSKPAN.UIB

    This is the Mask Panel file. It contains the actual GUI panels for each screen format mask, plus special panels for MAGEC system functions.

    GUI mode only, accessible only via MAGEC GUI screen painter, other system functions

    PRM

    This is the Insertion Parm file. It contains the definition of each customization insertion point, both for online and batch programs. It also contains the proforma and online help for that insertion point.

    Logical Rec. Lgth: 2236  CI Size: 4096  Key Displacement: 37  Key Lgth: 7

    REF

    This is the documentation Reference file. It contains cross-reference records which associate topics from the DOC file to key words or key phrases. One of the prime purposes for this is to connect documentation topics to online functions for the high-level help key (PF1).

    Logical Rec. Lgth: 100  CI Size: 2048  Key Displacement: 36  Key Lgth: 64

    RPH

    This is the Report Header file. It is used to control the routing and disposition of reports by the TP Spooler feature.

    Logical Rec. Lgth: 100  CI Size: 2048  Key Displacement: 00  Key Lgth: 6

    SCF

    This is the Screen Field file. It contains the definitions and edit rules for each screen field on each mask.

    Logical Rec. Lgth: 320  CI Size: 2048  Key Displacement: 00  Key Lgth: 10

    SHD

    This is the Screen Header file. It contains the high-level parameters and definitions for each screen mask, including responsible programmer.

    Logical Rec. Lgth: 150  CI Size: 2048  Key Displacement: 00  Key Lgth: 4

    SIF

    This is the Security Information file. It contains the security profile for each operator authorized to use the system.

    Logical Rec. Lgth: 300  CI Size: 2048  Key Displacement: 36  Key Lgth: 6

    SPL

    This is the Spool file. It contains the actual report text to be routed by the TP Spooler feature.

    Logical Rec. Lgth: 1940  CI Size: 4096  Key Displacement: 00  Key Lgth: 5

    TBL

    This is the Table file. It contains lookup tables plus the table of contents which defines each table.

    Logical Rec. Lgth: 100  CI Size: 2048  Key Displacement: 36  Key Lgth: 19

    TST

    This is the Test file. It is used in the tutorial projects to contain the Vacation data (VAC), and possibly in other test applications to demonstrate various features of MAGEC.

    Logical Rec. Lgth: 270  CI Size: 2048  Key Displacement: 36  Key Lgth: 18

    TWA or TW3

    This is the Task Work Area file (replaced by the TW3 file in MAGEC 3.0 and later). It is used to save TWA data to provide pseudo-conversational processing and for copy/paste, swap windows, and online help.

    TWA Logical Rec. Lgth: 04088  CI Size: 08192  Key Displacement: 00  Key Lgth: 8

    TW3 Logical Rec. Lgth: 16376  CI Size: 16376  Key Displacement: 00  Key Lgth: 8

    NOTE:


    PC Template


    Global Parameters

    Table #243

    Table #243 is an ordinary MAGEC Lookup Table which is used to contain certain system parameters. These parameters control the operation of the entire MAGEC system. If you are authorized to do so, you can alter any of these parameters' settings and dynamically change the way MAGEC operates without having to re-cycle your online system or re-compile any programs.

    The parameter settings are loaded from Table #243 into main memory at system startup time. This is done for performance efficiency. You can tell MAGEC to re-load its main memory images from Table #243 by issuing the **LOAD command online after you have altered some settings. This is similar to the way that a database administrator or security officer can alter parameters and cause them to be re-loaded dynamically. This scheme gives you the advantages of a central repository without the overhead disadvantages of excessive I/O activity to the repository files.

    Table #243 is, of course, a part of the repository (just like any other Lookup Table) and is saved to disk whenever you make any updates. Therefore, your changes will remain in effect until they are removed or changed again.

    To do maintenance to Table #243 you could use the standard TBLCHG 243/xxx command format, as for any other Table; or you could use the special set of functions provided specifically for maintaining Table #243. They are:

    243ADD
    243CHG
    243LOC
    et cetera
     

    The standard set of nine functions is provided.

    To list the table's entries, you can use the command:

    243LOC  

    no key value is required for the browses. The program will begin at the start of Table #243.

    To update a particular entry, you could use the command:

    243CHG parameter-name  

    where parameter-name is the up-to-16-character name for the desired parameter. These names are pre-set by MAGEC and cannot be altered by you. If you add an entry for a parameter which is not defiend to MAGEC, it will simply be ignored by the system. Likewise, if you were to misspell a parameter name when you added an entry for it. For the most part, you need not ever add any parameter entries since they are already loaded into the table when the system is installed. You will normally only ever have to change the settings for them.

    When you use the 243CHG function, the screen will display a heading indicating that this is the MAGEC Configuration Parms screen, and it will display three data fields:

    Parameter the name of this parameter (same as in SKEY)
    Setting the value the parameter is set to
    Comments a description of this parameter

    The first field, Parameter, is a protected field and cannot be altered by you.

    The second field is the value this parameter is currently set to. You can change it online, if you wish. It is a 10-character field. Most parameter settings are less than 10 characters long, therefore, you should enter your desired setting left-justified with spaces padding the remainder of the setting field.

    The third field is a free-form comments area. It is used simply to document the meaning of this parameter, or, in some cases, the valid values (if there are only a few possibilities). You can alter this field, but there does not seem to be much reason for you to do so. Each parameter is pre-defined with a description which the MAGEC developers felt would be useful to you.

    The parameters, and their valid settings are:

    ALPHA-DATE

    This may be set to either YES or NO. A value of YES indicates that dates which have an Edit Type of D should be displayed in the format DDMMMYY (as: 04JUL91), rather than the default format for Edit Type D (DD/MM/YY).

    CLEAR-MMP

    This indicates the 3-character MMP number of the clear screen MMP. It is set to 652 and should be left that way unless you are directed otherwise by the MAGEC support personnel.

    CPMOD-TEST

    This is the 3-character MMP number of the test MAGEC Control Program, it is set to 670 and should be left that way unless you are directed otherwise by the MAGEC support personnel.

    CPMOD-PROD

    This is the 3-character MMP number of the production MAGEC Control Program, it is set to 699 and should be left that way unless you are directed otherwise by the MAGEC support personnel.

    DKE-LIMIT

    This is a parameter which controls the size of the internal tables which hold the Data Class, Key, and Element definitions. This parameter is not currently implemented and is for future use.

    ERROR-ATTRIBUTE

    This parameter sets the type of error highlighting to be used for error fields at 7-color terminals. The only valid values are 1 (blink), 2 (reverse video), and 4 (underline). Blink is the default.

    FCD-LIMIT

    This parameter sets the maximum number of function codes for the system. It controls the size of an internal table. It is set to 6000, the default setting. This parameter is not yet implemented and should be left at 6000 for documentation purposes.

    HANDLEABEND-xxxx

    This parameter applies only if your MAGEC system is installed on a CICS TP Monitor. It is ignored otherwise. This is actually a series of 16 parameters, the -xxxx is -TS01, -TS01, -PR01, etc. These, of course, correspond to the 16 MAGEC User Views.

    The valid settings for each of these parameters are any 8-character (left-justified and padded with spaces if shorter) program name. The program specified must be defined to the CICS PPT. The default setting for each parameter is NONE. A setting of blanks is equivalent to a setting of NONE. 

    If a setting other than NONE is given, MAGEC will issue an EXEC CICS HANDLE ABEND command specifying the appropriate program name. This means that CICS will transfer control to the specified program instead of using its default error handling routines. The program specified can be written by your staff and can do any legal process as specified in the CICS documentation. If NONE is specified CICS will use its default process; usually issuing a memory dump and an abend code.

    IOMOD-PROD

    This parameter specifies the 3-character MMP number of the production I/O module. It is set to 698 and should be left that way unless you are directed to change it by the MAGEC support personnel.

    IOMOD-TEST

    This parameter specifies the 3-character MMP number of the test I/O module. It is set to 653 and should be left that way unless you are directed to change it by the MAGEC support personnel.

    LOGOFF-ON-EXIT

    This parameter is set to YES or NO to indicate whether or not you want MAGEC to log the operator off (SYSLOG OFF) automatically when the PFKEY-EXIT (usually PF15) is hit.

    MAG-ACT-LOG

    This parameter may be set to either YES or NO. YES specifies that the MAGEC activity logging option is to be on, NO specifies that it is to be off.

    PFKEY-SWAP

    This parameter specifies the PF key used to swap windows. It is set to PF9 and should be left that way unless you have coordinated with the MAGEC support personnel to use a different key throughout the MAGEC system.

    PFKEY-EXIT

    This parameter specifies the PF key used to exit MAGEC. It is set to PF15 and should be left that way unless you have coordinated with the MAGEC support personnel to use a different key throughout the MAGEC system.

    PFKEY-HELP

    This parameter specifies the PF key used to invoke online help. It is set to PF1 and should be left that way unless you have coordinated with the MAGEC support personnel to use a different key throughout the MAGEC system.

    PFKEY-FIELD-HELP

    This parameter specifies the PF key used to invoke online field-level help. It is set to PF2 and should be left that way unless you have coordinated with the MAGEC support personnel to use a different key throughout the MAGEC system.

    PFKEY15-VERIFY

    This parameter is set to YES or NO to indicate whether or not you wish MAGEC to verify that you really want to exit MAGEC when the PFKEY-EXIT (usually PF15) is hit.

    PFKEY15-TRANSID

    This parameter is ignored if your MAGEC system is not installed on a CICS TP Monitor. It specifies the 4-character CICS transID which MAGEC will automatically place into the top-left corner of the screen after exiting MAGEC as a result of the exit PF key (usu. PF15) having been hit. If you wish to tell MAGEC to start (execute) that transID, rather than just place it into the screen, you follow the 4-character transID immediately with a slash followed by the word START, ie.

    CSGM/START  this is the transID to execute after exiting  

    If you do not wish the transID to be automatically executed, then leave the remainder of the 10-character setting field padded with spaces. For example:

    CSGM  this is the transID to prompt the operator with  

    SECURITY-EXIT

    This parameter specifies the 8-character name of a program (which must be defined to the PPT) which MAGEC is to call (via EXEC CICS LINK) to validate security authorization for an operator to do any online function. If MAGEC is using its internal security verification, then the security-exit program will be called after MAGEC security checks have been completed, and only if MAGEC's security shows the operator to be authorized for the function attempted. The security-exit program can then override MAGEC's authorization.

    If MAGEC's internal security checking is being bypassed (via the MAGEC-SECURITY parameter), then the security-exit program will be called for every transaction instead of MAGEC's routines.

    MAGEC-SECURITY

    This parameter may be set to YES or NO. YES indicates that MAGEC's intrinsic security checking is to be executed to validate authorization for operators to do online functions. NO indicates that MAGEC's security checking is to be bypassed, thereby implicitly authorizing all operators to do any functions. Presumably, a SECURITY-EXIT program will be provided by you to verify authorizations, in that case.

    It should be noted that if you specify NO for this parameter certain functions will not be done by MAGEC which are related to security checking. For instance, the operator will not need to log on to MAGEC in order to do any function he/she wishes; it will be up to you to code a SECURITY-EXIT program to check authorization. Further, since the operator will not have to log on, MAGEC has no way of knowing who is at the terminal. Therefore, the MAGEC Activity Logging will not be accurate in this regard unless your SECURITY-EXIT program sets the employee number and location in the TWA appropriately.

    Another side effect of bypassing MAGEC's security is the inability of MAGEC to build custom menu screens for an operator (since MAGEC does not know who the operator is). The result will be that MAGEC's menu screens will show every operator as authorized for any function. The list of functions may be very long and it may include functions for which the operator is/should not be authorized.

    Remember, the MAGEC automated menu system is driven by the security parameters defined for the operator versus for each function code.

    SPLR-PROD-MOD

    This is a 3-character MMP number for the production spooler subroutine used to spool print-type data. It is set to 671 at installation time and should be left that way

    SPLR-TEST-MOD

    This is the 3-character MMP number of the test spooler subroutine used to spool print-like data from online MMP's. It is set to 671 and should be left that way.

    SYSLOG-MMP

    This is the 3-character MMP number of the SYSLOG ON/OFF program. It is set to 652 and should be left that way unless you have written your own program to accomplish the functions of logging operators on and off.tem.

    TCPIP-ACB

    This parameter is set to the FCT name of the file containing the OpenConnect ACB list for MAGEC's mainframe Host processors. It has no meaning on non-mainframe implementations. Default name is MAGACB.

    TCPIP-LU

    This parameter is set to the FCT name of the file containing the OpenConnect LU list for MAGEC's mainframe Host processors. It has no meaning on non-mainframe implementations. Default name is MAGLU.

    TCPIP-PORT

    This is the number (5-digits) of the TCP/IP port (or a range of port numbers entered as nnnnn-nnnnn) to be used for MAGEC inter-network communications. The default number is 05998. Port numbers are ordinarily assigned to various applications in order to avoid conflicts, primarily on the INTERNET. You may change the setting here, but be sure to check for other applications' port assignments first. Certain port numbers are reserved worldwide, for example, 00001 thru 01024 . The maximum is 64535. The TCPIP-PORT setting tells the MGCLIENT routine which port number to send on, and the MGHOST program which port to listen on--they should be the same number.

    If a range of port numbers is given, it is entered as two 5-digit numbers separated by a hyphen. The second number must not be lower than the first. The port number used by MAGEC Host processing on a PC or Unix Host machine will always be the first (lowest) number. On a mainframe MAGEC Host, however, multiple concurrent threads (multiple versions of the MAGEC Host processor) can be supported utilizing port numbers within the range given. The lowest (first) port number will be used for the initial contact between a Client and the mainframe Host, which will respond with a message containing one of the other port numbers from the range to be used for all subsequent communications between that Client and this Host. All this is done automatically by the MAGEC TCP/IP support modules. To increase or decrease the available number of threads supported, increase or decrease the range of numbers in this global parameter setting.

    If the MAGEC Host is to executed on a mainframe, it is recommended that a minimum of two (2) port numbers be provided, i.e.: 05998-05999.

    TCPIP-PORTA (thru ...Z)

    These are alternate port number ranges. The basic TCPIP-PORT entry described above is required for any inter-network communication, these 26 alternates are optional. These alternate ranges enable you to have more than one "listening" host at one IP address. For example you might have one MVS and one VSE, or one production and one test, CICS system on the same mainframe. Unless you had more than one physical connection and gateway machine to the mainframe, there would be only one IP address for the mainframe. Using the alternate port ranges you might have one of the CICS hosts using one range of port numbers while the other uses another range of port numbers. This enables the MAGEC host programs to distinguish which messages sent to the mainframe should be handled by which host. You should be careful that the port numbers associated with these alternate port id's do not overlap one another or the basic TCPIP-PORT specification.

    The specification for each Gateway and its associated IP address allows for you to also specify a port ID. This specification is a single letter, i.e.: "A", which indicates which alternate TCPIP-PORTx port number range to use. For example, You might establish (in TBL #248):

    Gateway Name IP Address Port ID

    MAINFRAMEMVS 130.100.60.20 A

    MAINFRAMEVSE 130.100.60.20 B

    In TBL #243 you might have specified TCPIP-PORTA using port numbers 06001-06005 and TCPIP-PORTB using 06006-06012. This way up to 27 hosts could be listening for messages on a single machine accessed via one physical connection.


    Exhibits

    EXHIBIT 1.1.5.1

    ALGTPCHX (MVS)

    //ALGTCPHX JOB (ACCT),'MAGEC',CLASS=A,MSGCLASS=A

    //STEP1 EXEC PGM=ALGTPCH

    //STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR

    //SYS005  DD  DSN=MAGEC.PCHOUT,

    //  DCB=(LRECL=80,BLKSIZE=80,RECFM=FB),

    //  SPACE=..... etc.

    //SYS010  DD  DSN=MAGEC.DATABASE,DISP=OLD,UNIT=TAPE,

    //  DCB=(RECFM=FB,BLKSIZE=23928,LRECL=5982),

    //  VOL=SER=XXXXXX,LABEL=(1,NL)

    //SYSOUT  DD  SYSOUT=*

    //SYS006  DD  *

    --------------INSERT CONTROL CARDS HERE-------see next page

    /*

    //

    ALGTPCHX (VSE)

    * $$ JOB JNM=ALGTPCHX,CLASS=F,USER='M A G E C'

    * $$ PRT CLASS=V

    * $$ PUN CLASS=V

    // JOB ALGTPCH

    // LIBDEF to point to newly loaded MAGEC library

    // ASSGN SYS006,SYSIPT

    // ASSGN SYS005,PUNCH

    // PAUSE ***MOUNT 'MAGEC.DATABASE' ON CUU (RING-OUT)

    // ASSGN SYS010,CUU

    ****** // TLBL SYS010,'MAGEC.DATABASE' (unlabelled)

    // EXEC ALGTPCH,SIZE=AUTO

    --------------INSERT CONTROL CARDS HERE-------see next page

    /*

    /&

    * $$ EOJ

    The Control Card format for ALGTPCH is:

    Col 01-09: blank

    Col 10-13: the constant 'LIB '

    Col 14-2: member name

    Col 22-29: modifier

    To print an index only of modules on the tape:

    Col 1-5: the constant 'INDEX'

    Col 6-80: leave blank

    NOTE:

    EXHIBIT 1.1.5.2.a

    ALGTPCH Control Cards to punch Bootstrap modules.

    NOTE:

    NOTE:

      LIB DEFFILESVSAM
      LIB DFHFCT  CICS17 (two spaces after "DFHFCT")
      LIB DFHPCT
      LIB DFHPLT
      LIB DFHPPT
      LIB VSAMDD (for MVS)
      LIB VSAMDLBL (for VSE)



    EXHIBIT 1.1.5.2.c


      LIB MAGECJCLOS (for MVS)
      LIB MAGECJCLDOS (for VSE)
      LIB MAGECJCLOSCOB85 (for MVS with Cobol II)
      LIB MAGECJCLDOSCOB85 (for VSE with Cobol II)

    EXHIBIT 1.1.6.2.2

    VSAM DD's (MVS)

    These are sample DD statements for the 24 MAGEC VSAM files which comprise the dictionary plus testing datasets. The RPHK1 and SPLK1 files are used by the TP Spooling facility. They can be deleted from the IDCAMS file definitions, the DFHFCT entries, and from this list of DD statements if the TP Spooler is not going to be used at your installation.

    DD's for VSAM files

    //ALGK1 DD DSN=MAGEC.ALG.CLUSTER,DISP=SHR

    //DBNK1 DD DSN=MAGEC.DBN.CLUSTER,DISP=SHR

    //DCLK1 DD DSN=MAGEC.DCL.CLUSTER,DISP=SHR

    //DITK1 DD DSN=MAGEC.DIT.CLUSTER,DISP=SHR

    //DOCK1 DD DSN=MAGEC.DOC.CLUSTER,DISP=SHR

    //DVCK1 DD DSN=MAGEC.DVC.CLUSTER,DISP=SHR

    //ELTK1 DD DSN=MAGEC.ELT.CLUSTER,DISP=SHR

    //ERRK1 DD DSN=MAGEC.ERR.CLUSTER,DISP=SHR

    //FCDK1 DD DSN=MAGEC.FCD.CLUSTER,DISP=SHR

    //KYFK1 DD DSN=MAGEC.KYF.CLUSTER,DISP=SHR

    //LAPK1 DD DSN=MAGEC.LAP.CLUSTER,DISP=SHR

    //MALK1 DD DSN=MAGEC.MAL.CLUSTER,DISP=SHR

    //MMPK1 DD DSN=MAGEC.MMP.CLUSTER,DISP=SHR

    //MS3K1 DD DSN=MAGEC.MSK.CLUSTER,DISP=SHR

    //PRMK1 DD DSN=MAGEC.PRM.CLUSTER,DISP=SHR

    //REFK1 DD DSN=MAGEC.REF.CLUSTER,DISP=SHR

    //RPHK1 DD DSN=MAGEC.RPH.CLUSTER,DISP=SHR for Spooler

    //SCFK1 DD DSN=MAGEC.SCF.CLUSTER,DISP=SHR

    //SHDK1 DD DSN=MAGEC.SHD.CLUSTER,DISP=SHR

    //SIFK1 DD DSN=MAGEC.SIF.CLUSTER,DISP=SHR

    //SPLK1 DD DSN=MAGEC.SPL.CLUSTER,DISP=SHR for Spooler

    //TBLK1 DD DSN=MAGEC.TBL.CLUSTER,DISP=SHR

    //TSTK1 DD DSN=MAGEC.TST.CLUSTER,DISP=SHR

    //TW3K1 DD DSN=MAGEC.TWA.CLUSTER,DISP=SHR

    Continued on next page for VSE.

    VSAM DLBLs (VSE)

    The following are the VSAM DLBL's which should be included in the PROC "MAGECLIB" along with the appropriate LIBDEF's

    The SYS005, SYS006, and SYS007 assignments may be inluded in the PROC or they may be included into each jobstream, as appropriate. MAGEC's batch programs utilize these SYS numbers for consistency.

    DLBL's for VSAM files

    // ASSGN SYS006,SYSIPT

    // ASSGN SYS005,SYSPCH

    // ASSGN SYS007,SYSLST

    // DLBL ALGK1,'MAGEC.ALG.CLUSTER',,VSAM

    // DLBL DBNK1,'MAGEC.DBN.CLUSTER',,VSAM

    // DLBL DCLK1,'MAGEC.DCL.CLUSTER',,VSAM

    // DLBL DITK1,'MAGEC.DIT.CLUSTER',,VSAM

    // DLBL DVCK1,'MAGEC.DVC.CLUSTER',,VSAM

    // DLBL DOCK1,'MAGEC.DOC.CLUSTER',,VSAM

    // DLBL ELTK1,'MAGEC.ELT.CLUSTER',,VSAM

    // DLBL ERRK1,'MAGEC.ERR.CLUSTER',,VSAM

    // DLBL FCDK1,'MAGEC.FCD.CLUSTER',,VSAM

    // DLBL KYFK1,'MAGEC.KYF.CLUSTER',,VSAM

    // DLBL LAPK1,'MAGEC.LAP.CLUSTER',,VSAM

    // DLBL MALK1,'MAGEC.MAL.CLUSTER',,VSAM

    // DLBL MMPK1,'MAGEC.MMP.CLUSTER',,VSAM

    // DLBL MS3K1,'MAGEC.MSK.CLUSTER',,VSAM

    // DLBL PRMK1,'MAGEC.PRM.CLUSTER',,VSAM

    // DLBL REFK1,'MAGEC.REF.CLUSTER',,VSAM

    // DLBL RPHK1,'MAGEC.RPH.CLUSTER',,VSAM for SPOOLER only

    // DLBL SCFK1,'MAGEC.SCF.CLUSTER',,VSAM

    // DLBL SHDK1,'MAGEC.SHD.CLUSTER',,VSAM

    // DLBL SIFK1,'MAGEC.SIF.CLUSTER',,VSAM

    // DLBL SPLK1,'MAGEC.SPL.CLUSTER',,VSAM for SPOOLER only

    // DLBL TBLK1,'MAGEC.TBL.CLUSTER',,VSAM

    // DLBL TSTK1,'MAGEC.TST.CLUSTER',,VSAM

    // DLBL TW3K1,'MAGEC.TWA.CLUSTER',,VSAM

    EXHIBIT 1.2.2

    ALANULEX (MVS)

    This jobstream initializes the MAGEC VSAM dictionary files.

    //ALANULEX JOB (ACCT.),'MAGEC',CLASS=A,
    // MSGCLASS=A
    //STEP1 EXEC PGM=ALALDNUL
    //STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
    * * * * * insert VSAMDD statements here
    //SYSOUT DD SYSOUT=W
    //SYSUDUMP DD SYSOUT=W
    //SYSPRINT DD SYSOUT=W
    //

    ALANULEX (VSE)

    * $$ JOB JNM=ALALDNUL,CLASS=0,USER='M A G E C'

    * $$ LST CLASS=Q

    // JOB ALALDNUL

    // EXEC PROC MAGECLIB  -pvt. libs. (and DLBL's for VSAM)

    // EXEC ALALDNUL,SIZE=AUTO

    /*

    /&

    * $$ EOJ

    EXHIBIT 1.2.2.a

    RPHINIT & SPLINIT (VSE)

    * $$ JOB JNM=RPHINIT,CLASS=0,USER='M A G E C'

    * $$ LST CLASS=Q

    // JOB RPHINIT

    // EXEC PROC MAGECLIB -libs.and DLBL's for VSAM

    // DLBL RPHVSAM,'MAGEC.RPH.CLUSTER',,VSAM
    // EXEC RPHINIT,SIZE=AUTO

    /*

    /&

    * $$ JOB JNM=SPLINIT,CLASS=0,USER='M A G E C'

    * $$ LST CLASS=Q

    // JOB SPLINIT

    // EXEC PROC MAGECLIB  -libs.and DLBL's for VSAM

    // DLBL SPLVSAM,'MAGEC.SPL.CLUSTER',,VSAM
    // EXEC SPLINIT,SIZE=AUTO

    /*

    /&

    RPHINIT & SPLINIT (MVS)

    //RPHINIT JOB (ACCT.),'MAGEC',CLASS=A,
    // MSGCLASS=A
    //STEP1 EXEC PGM=RPHINIT
    //STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
    * * * * * insert VSAMDD here (see exhibit 1.1.6.2.2)
    //RPHVSAM DD DSN='MAGEC.RPH.CLUSTER'
    //SYSOUT DD SYSOUT=W
    //SYSUDUMP DD SYSOUT=W
    //SYSPRINT DD SYSOUT=W
    //

    //SPLINIT JOB (ACCT.),'MAGEC',CLASS=A,
    // MSGCLASS=A
    //STEP1 EXEC PGM=SPLINIT
    //STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
    * * * * * insert VSAMDD here (see exhibit 1.1.6.2.2)
    //SPLVSAM DD DSN='MAGEC.SPL.CLUSTER'
    //SYSOUT DD SYSOUT=W
    //SYSUDUMP DD SYSOUT=W
    //SYSPRINT DD SYSOUT=W
    //

    EXHIBIT 2.3

    ALALDEX (MVS)

    This jobstream populates (loads) the MAGEC VSAM dictionary files.

    //ALALDEX  JOB (ACCT.),'MAGEC',CLASS=A,
    // MSGCLASS=A
    //STEP1  EXEC PGM=ALALDFIL,REGION=1024K
    //STEPLIB  DD DSN=MAGEC.LOADLIB,DISP=SHR
    * * * * * insert VSAMDD here (see exhibit 1.1.6.2.2)
    //SYS010  DD DSN=MAGEC.DATABASE,UNIT=TAPE,DISP=OLD,
    //  VOL=SER=MAGnnn,
    //  DCB=(RECFM=FB,LRECL=5982,BLKSIZE=23928),
    //  LABEL=(1,NL)
    //SYSOUT  DD  SYSOUT=W
    //SYSUDUMP DD  SYSOUT=W
    //SYSPRINT DD  SYSOUT=W
    //SYS006  DD  *
    ALALDFIL RALL
    //

    See next page for control card format.

    ALALDEX (VSE)

    This jobstream populates (loads) the MAGEC VSAM dictionary files.

    * $$ JOB JNM=ALALDFIL,CLASS=0,USER='M A G E C'

    * $$ PRT CLASS=V

    // JOB ALALDFIL LOAD MAGEC FILES

    // EXEC PROC=MAGECLIB -libs.and DLBL'S for VSAM

    // PAUSE - MOUNT & READY "MAGEC.DATABASE" TAPE

    // ASSGN SYS006,SYSIPT

    // ASSGN SYS010,CUU

    * // TLBL SYS010,'MAGEC.DATABASE' (unlabelled.tape)

    // EXEC ALALDFIL,SIZE=(AUTO,20K)

    ALALDFIL RALL 

    /*

    /&

    * $$ EOJ

    See next page for control card format.

    NOTE:

    Col 1-9: the constant "ALALDFIL"

    Col 10: Add or Replace option, "A" or "R"

    Col 11-13: Data Class name, or "ALL" for all Data Classes

    Up to 100 control cards may be input to one run, they must be in alphabetical sequence by Data Class name.

    Appendix A -- Upgrading from Release 2.x

    If you currently have MAGEC relase 2.x installed on your mainframe and are upgrading to MAGEC release 3.x, you will have a few extra steps added to your upgrade procedure because of several configuration changes which have been made.

    1) the TWA size for all MAGEC trans-id's (TS01-TS08, PR01-PR08) has been increased from 16,384 to 20,480.

    2) The TWA file is no longer used, it has been replaced by the new TW3 file.

    3) The MSK file is no longer used, it has been replaced by the new MS3 file.

    4) Several new programs have been added, requiring additional PPT entries.

    5) A PC diskette labelled "MAGEC pre-installation" contains PCT, PPT, FCT, and IDCAMS Delete/Define members to help you in your upgrade.

    A) From all JCL members you should replace the TWA and MSK file entries with the TW3 and MS3 file entries. This includes your CICS startup JCL, if appropriate.

    B) Add the TW3K1 and MS3K1entries to the CICS FCT table. Remove the TWAK1 and MSKK1entries.

    C) Create the new TW3 and MS3 files using IDCAMS. Initialize them using MAGINIT. The pre-installation diskette provided with your upgrade includes text files which were downloaded from members on your MAGEC ALG file. Among these text files is the VSAM definitions used to create all of the MAGEC files. extract only the TW3 and MS3 file definitions from there.

    D) Alter your PCT table entries for the new TWA size.

    E) After installation is complete, you must execute MSKCRE (online function) for each mask. This generates a mask initialization record on the MS3 file and a matching Cobol copybook definition for each mask. Then, execute MMPCREAT for each MMP to re-generate the programs using the release 3 TWA format and size.

    NOTE:

    Appendix B -- xx$ Alias DCL Names