Installation Guide

---

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.

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:

• MVS environments: if you are using disks which do not permit a 23,476 blksize (i.e. 3350's), please notify us immediately so that we can create tapes for a smaller blksize (i.e. 17,600), or you can use the COPYMOD option of IEBCOPY to reblock from the tape to the disk loadlibrary as it is being loaded.

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.

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:

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.

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

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.

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.

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.

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:

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

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:

NOTE:

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

NOTE:

• The exhibits (in the back of this booklet) referenced in these instructions are extracted from a larger internal manual, which accounts for the seemingly strange exhibit numbers. Using the same exhibit numbers in both manuals is an advantage in the event that we need to render telephone assistance to you.

The steps to do in order to install MAGEC are:

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:

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

NOTE:

• Be sure that your concatenation of loadlibraries includes the largest blocksize library first. MVS allocates space to read blocks into based upon the size of the first file in your concatenation. Unlike with data files, MVS will not issue a warning or error message when CICS loads a program from a library which has a blocksize larger than the allocated space"it will merely truncate the portion from each library block which does not fit in the space, leaving gaps of unexecutable binary zeros in the middle of the program. The abends are difficult to debug, so it is wise to check your concatenation before using it. If you cannot, or do not desire to, place the largest library first in the concatenation, you can specify a DCB with a BLKSIZE set to the largest of all the concatenated libraries. The DCB should be on the first DD statement.

Please call MAGEC Support at (214) 202-4965 if you have any problems.

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:

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 exhibits (in the back of this booklet) referenced in these instructions are extracted from a larger internal manual, which accounts for the seemingly strange exhibit numbers. Using the same exhibit numbers in both manuals is an advantage in the event that we need to render telephone assistance to you.

The steps to do in order to install MAGEC are:

The components required to upgrade your MAGEC system include:

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

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.

Please call MAGEC Support at (214) 202-4965 if you have any problems.

MAGEC no longer supports the Realia COBOL compiler.

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.

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:

• The procedures below assume that your removable disk unit is drive A: - if it is another drive then you should adjust the command accordingly. Likewise, they assume that your \MAGMF directory is on your C: drive, if not, adjust accordingly. The \COBOL directory is Micro Focus Professional COBOL. From the DOS prompt, or (for Windows installation) from Windows File / Run, execute:

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):

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

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:

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:

• MAGEC requires your system to include the following directories:

• We suggest that your CONFIG.SYS parameters be set like the ones below, as a minimum.

NOTE:

• The SHELL command may not be supported in earlier versions of DOS, or its format may vary in later versions, contact us at one of the phone numbers below if you need assistance. The primary function of the SHELL command above is to establish a size for the ENVIRONMENT SPACE in your system in order to prevent the  OUT OF ENVIRONMENT error message which could result from too small a space. For Windows 3.x, you should also check your SYSTEM.INI file for the proper setting to assure that there will be at least 1024 bytes available, for example:
  [NonWindowsApp]
  CommandEnvSize=1024

If you have any questions call us at:

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.

This topic applies only to RealiaCobol users.

MAGEC no longer supports the Realia COBOL compiler.

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:

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:

NOTE:

• \MAGxx = either \MAGEC or \MAGMF, depending on which Cobol is used.

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.

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.

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:

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.

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.

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.

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.

MAGEC 3.0 no longer supports Realia COBOL.

This topic applies only to RealiaCOBOL users.

MAGEC 3.0 no longer supports the Realia COBOL compiler.

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.

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:

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:

• The REORG procedure will not reblock your files. If you wish to alter the block size, you can use the MAGUNLD followed by MAGLOAD procedures. MAGLOAD will set the block size based upon the specification on your DCL (Data Class) profile.

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

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

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:

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:

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

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:

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).

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:

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

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:

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.

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:

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

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:

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:

• MAGEC for the PC or PS/2 requires that the indexed files to be accessed conform to a particular naming convention, i.e. xxxK1.DAT (xxx = data class name), and that they be in the \MAGxx directory.

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:

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.

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:

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:

• For Realia: If you enter an output file name of DUMP.FIL, or LPT1 or LPT2, or LPT3, or LPT1:, or LPT2:, or LPT3:, MAGUNLD will produce a hexadecimal/character dump of the indexed file instead of an unload. It will be sent to the specified output port or to the file \MAGEC\DUMP.FIL (which will be a text file accessible via any text editor or word processor), based upon your specification.

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:

• You must never use EDIT, EDLIN, or any other editor or word processor directly on an indexed file. The data and/or index for the file will be corrupted, possibly beyond the realm of recoverability. You can use any editor against the unloaded file if it is a text file (Realia type [U], [N], or [T])and does not contain packed or binary data.

• One additional restriction against using an external editor on the unloaded file is the limitations of your editor for handling long record lengths. Some editors are restricted to 80 character records, some to 4,000 character records, others to other maximums. They will usually notify you if they are unable to handle your text file properly.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

• For system tuning to obtain the best online performance of generated MAGEC applications, it is important that the TWA file be optimized. This means that you may wish to alter the CI Size, move the file to a less-used disk unit, separate the index and data areas, or apply any other tuning techniques dictated by your usage statistics. You should certainly consider frequent re-organizations. Purging old, unneeded records will also help performance. There is a batch utility named TWAUTIL which will automatically do that; there is also an online function: TWAPUR. Another method for recovering space in the TWA file is to completely purge it periodically. This can be done by erasing the file (on mainframe, use IDCAMS DELETE / DEFINE) and re-initializing it using MAGINIT. In a Micro Focus environment it is not necessary to do the MAGINIT since MAGEC's I/O module will re-create the TWA file if it is not found. In a network environment you may find it beneficial to put the TWA file on the local drives of your workstations. To do that simply specify "C:" on the KYF drive-id definition for TW3K1.

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:

The standard set of nine functions is provided.

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

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:

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:

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:

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

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.

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.

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

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.

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.

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.

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.

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.

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):

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.

//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

/*

//

* $$ 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:

To print an index only of modules on the tape:

NOTE:

• The control cards must be in alphabetic order by member-name/modifier.

ALGTPCH Control Cards to punch Bootstrap modules.

NOTE:

• See prior page for card format.

NOTE:

• To speed your installation, MAGEC Software may provide some or all of these members on a PC diskette text file which you can edit using any PC text editor and then upload to your mainframe. The members on the diskette are identical to those you would produce by executing ALGTPCH using the control cards below. The diskette was produced by MAGEC Software by executing ALGTPCH (just as you would do) and then copying the output file(s).

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






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


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.

//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.

// 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

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

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
//

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:

• ALALDEX runs 1-3 hours (approximately). See below for control card format.

• ALALDFIL Control Card:

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

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.

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:

• Upgrading to a new release of MAGEC does not ordinarily involve structural changes or re-compiles of your applications. Changes which would require re-compiles are normally included only in major releases, such as upgrading from release 1.x to 2.x or from 2.x to 3.x. These major releases occur very infrequently; there has been an approximate span of eight years between major releases since the first introduction of MAGEC. The MAGEC Software development team regrets any inconvenience such major upgrades might cause, but we felel that the improvements and added features are well worth the trouble.

• MAGEC 3.0 and later supports remote file access across a TCP/IP network which may include mainframes, PC's, and Unix computers. In order for cross-system access to work properly, MAGEC must be installed on all of the machines involved and the definitions of the data must agree on all of the machines. This means that the DCL, KYF, ELT, and DIT definitions must be kept synchronized across the various platforms.

• In order to simplify the work of the DB Administrator, MAGEC includes a program named DCLSYNC which executes in a Windows environment. DCLSYNC copies data definitions between the local repository and any accessible gateway machine. This means that it can copy the DCL, KYF, ELT, and DIT definitions for any Data Class from the gateway machine (mainframe) to your local repository, or vice-versa.

• In order for DCLSYNC to concurrently access both its local repository files and the remote repository files at the specified gateway, there must be separate definitions for those repository files, i.e. DCL, KYF, ELT, and DIT. Those separate, but otherwise identical, definitions are: DC$, KY$, EL$, and DI$, respectively.

• DCLSYNC dynamically updates these "alias" definitions to point them to the selected gateway, thereby permitting it to read from the DCL (local) and copy to the DC$ (remote), or vice-versa.

• To execute DCLSYNC you must have a level-9 authorization as a developer (LAP 50). If you do have sufficient authorization you will see a SYNCHRONIZE button at the bottom of your MAGEC logo screen (you can type the function code CLEARS, or press Esc to get to the logo screen). Click the button then select the type of synchronize (DCL) from the menu which will pop up.