Using a NOS
Configuring MAGEC to operate in an environment including a NOS is quite simple. The installation procedure uses two sets of installation diskettes, one for a "server" and one for a "workstation"; by following the on-screen instructions for each you will properly install MAGEC, ready to run.
These installations both presume that the MicroFocus Cobol compiler is installed before MAGEC is installed. The reason for this is because the MicroFocus installation generates certain settings into your AUTOEXEC.BAT and/or CONFIG.SYS file(s) and the MAGEC installation finds and modifies those settings. The Installation Guide booklet gives more information about those settings.
Essentially, those configurations of MAGEC on a NOS-based network consists of the MAGEC repository files being installed on a commonly accessed, shareable server drive (or drives), the MAGEC executable modules (EXE's and DLL's) being similarly installed on the same, or another shareable drive, and a "workspace" directory being installed on the local disk (if available) for each workstation. This last specification is optional, but for workstations which have disk drives can improve overall performance and reduce network traffic to the server.
The MAGEC installation automatically generates several environment settings needed by MAGEC on every workstation. They include: LANDRV, EXEDRV, and LCLDRV, which tell MAGEC where to look for certain files, directories, or work space.
MAGEC's repository files are ordinary data files, just like your own applications' files. They may reside in one, or several, directories on one or several drives. You may wish to refer to the Installation Guide for a list of all the files and a brief description of each. Most of the files can be placed anywhere you may desire so long as they are accessible to all MAGEC users. A few of the files, however, must be located in the \MAGMF directory on the drive specified in the LANDRV environmental setting; this is because those files are needed by MAGEC as it is starting up. The \MAGMF directory on the drive specified in LANDRV is considered MAGEC's default directory in which it will look for any file(s) not specifically designated as being elsewhere. The files which must be in the default directory are:
All other files may be in any directory on any drive. If a file is not in the default directory, its definition must include the drive on which it is located, and, if the directory name is not \MAGMF, its path, and, if its name is not standard, its complete path and name. Files having standard names in the default directory need none of these specified. This is true for both MAGEC's repository files and for your own data files.
Executable files (EXE's and DLL's) must be in the \MAGMF directory on the drive specified in the EXEDRV setting of your environment. The installallation procedure will automatically install the MAGEC system programs there, and the MMPCREAT and MBPCREAT jobstreams will automatically catalog generated executables there.
In order to reduce network traffic and achieve lower overhead, MAGEC will utilize the drive specified in the LCLDRV environment setting for temporary work space used when generating programs, compiling, sorting, et cetera. One of MAGEC's data files is actually a kind of work file as well. The TWA (Transaction Work Area) file can be specifield as residing on the local drives of each workstation to further reduce network overhead. To do this you would simply specify "C:" in the PC Drive/Path specification for TW3K1 on the KYF definition. In other words, use the online command:
and type "C:" into the PC file/path specification on the screen.
Any of your own data files which will be used by only one user can also reside on that user's local disk, if desired.
MAGEC assumes that you will have a directory named \MAGMF on the drive specified in LCLDRV and places temporary work files there. If you do not have such a directory, you can expect fatal errros whcn you attempt to generate or compile programs, or when you execute other batch programs provided with MAGEC. If your workstation does not include a disk drive then you must set LCLDRV to a drive on a server. It is permissible for LCLDRV, LANDRV, and/or EXEDRV to all be the same drive, if desired.
Files located on a NOS server drive which is accessible using the ordinary mapping provided by the NOS are accessed as if they were local (on the local disk drive) and normal record-level locking prevents conflicting updates by multiple users. It is not necessary to install MAGEC's intrinsic networking facility, or TCP/IP, to access such files.
Whether or not you are using a NOS, you can create a networked environment with MAGEC using the intrinsic networking facility which is based upon peer-to-peer TCP/IP communication, assuming that each workstation includes certain necessary components. The necessary components are:
There are many choices among most of these components and almost all of them should work well. If you need help in choosing, call MAGEC Technical Support for suggestions.
It is also possible to include your mainframe computer as a node of your network. This enables you to access mainframe files transparently from MAGEC applications running in a Windows, GUI (or Text, if preferred) environment. It also will enable you to access files on your PC's or PC servers from applications running on the mainframe--or to invoke programs or jobstreams on the mainframe from a PC, or vice-versa.
The MAGEC intrinsic networking facility enables you to establish Client-Host relationships between any two computers on the network, whether they are similar or dissimilar kinds of computers, EBCDIC or ASCII, etc. A Client is a machine which is requesting some service of another computer, a Host is a machine which is providing a service. The most common type of service is file access, but other types are also possible.
In order to serve as a Host, a computer must be defined properly to MAGEC. You should note that it is perfectly legitimate for any computer on the network to be either a Host or a Client, or both at the same time. No particular definition is necessary for a computer to be a Client, but MAGEC TCP/IP networking support must be installed--it will be invoked automatically, when requested by an application. For example, when an application tries to access a file which is specified as being located on another computer.
Each Host machine must be defined by an entry in MAGEC Lookup Table #248. This table is called the Gateway table (for this discussion, the term Gateway is usually interchangeable with Host). In this table you must specify a unique Gateway Name, up to sixteen characters long, plus the actual Internet Protocol (IP) Address of that machine. The name is merely for convenience and is used to identify that machine. Suitable names might be:
and so forth. The names should help a human to know which machine is being described. The IP Address, however, is somewhat less meaningful to a human, but necessary for the TCP/IP message handler and router.
An IP Address is a code which must be unique among all the computers in your network. If you will be accessing the Internet using this same TCP/IP, the address may need to be unique among all the computers in the world, but that is a different subject. It is entered and stored as a series of four 3-digit numbers (each of which may be in the range 0 to 255), separated by dots. For example:
The two above representations are equivalent since leading zeros may be omitted. MAGEC automatically translates these into the form actually recognized by TCP/IP whenever a message is sent.
In addition to being defined on Table #248, each Host machine should also have a setting added to its environment. It is:
The MAGHOST setting should specify the Gateway Name (same as was specified in Table #248 for this machine) of this machine. This setting is needed only if this machine will be used as both a Client and as as a Host, either concurrently or at different times. Its purpose is to advise the MAGEC system (when it is being used as a Client) of the fact that this same machine is also used as a Host and is known by this Gateway name, when so used. This tells MAGEC not to attempt to issue a remote command or message to that Gateway name, since it is this same machine. Instead, MAGEC knows that it can service any such request locally. For example, if the Client application wishes to access a file which is specified as being at Gateway "JOE'S-COMPUTER" and the MAGHOST setting tells us that this is "JOE'S-COMPUTER", we can read the file locally without issuing a remote request to "JOE'S-COMPUTER".
The port number on which a Host will listen for messages is the first port number specified in MAGEC Table #243, the Global Parameters table, in the specification for TCPIP-PORT. Refer to the Installation Guide for more about the Table #243 specifications.
To initiate Host processing on any Host PC computer, start the MGHOST program. To start MGHOST from within Windows, simply double-click the icon for MGHOST. A small window will appear indicating that MGHOST is up and running and listening for messages, or "accepting traffic". MGHOST can be left running while other tasks are being done on that same computer, including standard MAGEC execution. MGHOST.EXE can also be started automatically from the Windows Startup group, if desired.
As MGHOST is initializing itself it will attempt to determine if the recommended environmental settings and stack are present. If not, it will issue an error or warning message. If the condition is non-fatal, MGHOST will initialize and run once you have responded to the message.
To terminate MGHOST, double-click the icon titled ShutHost (see the SHUTHOST topic later in this section). MGHOST can be executed without the small window being displayed by using the command "SHUTHOST.EXE Blind". This eliminates conflicts which might arise from MGHOST and other MAGEC sessions sharing the MAGEC graphical display engine.
MGCLIENT is a "subroutine" which is dynamically called when appropriate. In the case of an application accessing a "foreign" file (one located at a Gateway machine as opposed to one which is accessed locally), MAGEC's I/O module automatically calls MGCLIENT with a request to be sent to the specified Gateway machine (the Host) to accomplish the desired I/O command. There is no special programming in the application for such access.
It is possible, however, for an application program to call MGCLIENT directly to request various operations. One example would be to invoke a jobstream at the Host machine.
Since some of the computers in your network might be EBCDIC machines (i.e. an MVS mainframe) and others might be ASCII machines (i.e. a Windows PC), it may be necessary that data transferred from one machine to another be converted into the proper coding scheme. Such data transformations are relatively simple for alphanumeric character data, but become very complex for records which contain some alphanumeric fields, some packed decimal fields, some binary fields, and some zoned-decimal fields with signs. All of these require different treatment on a byte-by-byte basis in order for a program in one environment to properly use data from another. Unfortunately, this complex scenario applies to most of the application data files in most installations.
Since this has always presented a difficult problem to organizations attempting to distribute both processing and data, MAGEC includes an intelligent, automatic data transformation feature which properly converts data as it is transferred. The conversion is driven by the actual MAGEC repository data definitions and therefore is aware of the data type of every byte of every record. It applies the proper conversions accordingly. This means that your applications can be completely unaware of the actual location, or coding-scheme, of any files they access and the proper data will be presented in the expected format automatically.
It also means that if the data file is moved from one type machine to another, no reprogramming or recompile will be needed; and the need for redundant replication of data files in different environments is eliminated.
Note:
In order to efficiently and accurately accomplish the ASCII / EBCDIC translations, MAGEC must have current definitions for the data. Those definitions are taken from the ELT file records which define Elements. As a normal part of the data definition process the Database Administrator executes the DITGEN function. Refer to your Programmer's Reference manual, Database Administration section for more detailed information regarding data definition, or access the online help tutorials from GUI MAGEC.
The principal duty of the DITGEN function is to generate the Cobol copybook defining an Element. As of MAGEC release 3.0, the DITGEN function has an added task: it generates a highly compressed table of conversion parameters which control the ASCII / EBCDIC (and vice-versa) translation. This table of parameters is stored in the ELT record for each Element. When required, the MAGEC I/O module passes this information to the MGCLIENT subroutine so that it can accomplish the translations.
Users of older versions of MAGEC likely have numerous definitions of Elements for which DITGEN was not recently executed. These Element definitions do not include the table of translation parameters. If MAGEC were to do the translation for the data defined by these Elements it would default to assuming that the entire Element is alphanumeric data and translate it accordingly. This will likely be less than perfect.
In order to obtain best results you should execute the DITGEN function (using MAGEC 3.0 or later) for every Element of every Data Class which might need ASCII / EBCDIC translation services.
Since MAGEC supports a set of I/O commands which return only a found key value (the LOCxx commands), it is necessary to also be able to intelligently translate the key value returned. This is accomplished via the definitions found on the KYF file for each key and its component fields. From this definition MAGEC discerns which bytes of the key are alphanumeric, packed, binary, or signed zoned-decimal. Obviously this means that accurate definitions on the KYF file are important to achieving best results.
With MAGEC's TCP/IP networking facility installed, a Client machine can invoke a jobstream or program to be executed at another (Host) machine. This facility works simarly to the "API Call" facility included with MAGEC's GUI option, except that the request is passed to a Host and the API call is done from MAGEC's Host processor on the Host machine. For a discussion of the special considerations regarding executing a process on a MVS or VSE mainframe, read this topic and also the topic Mainframe Sub-Tasks later in this chapter.
One possible use for this feature is to establish one or more Host machines which are configured optimally to perform some particular set of tasks, such as generating and compiling programs (i.e. MMPCREAT and MBPCREAT). Development personnel could submit their MMPCREAT requests to be run on the Host(s) while they continue doing other work on their workstations without suffering any degradation caused by having many large tasks concurrently active.
Since this facility uses the standard Windows API feature, any program or jobstream which can be executed from Windows could be executed from a remote Client. To execute a DOS batch file you would set up a .PIF file which executes the .BAT. You would execute the .PIF by specifying as the program name "xxxxxxxx.PIF", just as with the GUI API Call feature.
Programs generated using the standard MAGEC MODELMMP will automatically include the proper request area for executing a remote job. It is:
A Named Proforma is provided with MAGEC to help you to properly fill in and use this request area. The Proforma is named: REMOTE/XQT. It looks like this:
In this request, the literal $XQT identifies this as a remote execution request to MGCLIENT. The Gateway Address is given in its "dotted" format which MGCLIENT will convert into the actual 4-byte address used by TCP/IP. This is the address of the Host at which the task is to be executed.
You can determine the address of any Host by accessing MAGEC Table #248. The Gateway Name is the code value, the address is in the description. You can view Table #248 online using the function code: 248LOC. No key value is needed for this function. You can also access Table #248 from within your program. As with all MAGEC LookupTables, the actual file key is 19 bytes long and consists of the 3-digit Table# (248) followed by the 16-character code value. The copybook TBL01-C defines the contents of all tables. Table #248 contains, for each Gateway Name, a one-character Port ID, as well as the IP Address. Refer to the topic Gateways & PortIDs later in this chapter.
The 5-digit TCP/IP port number used by a given Gateway can be determined by accessing Table #243 using a key value or: 243TCPIP-PORTn where N = the one-character Port ID.
The symbolic '&REL' will be resolved at program generation time. It will contain the MAGEC release number. This helps MAGEC to verify that a version mismatch between the MGCLIENT program and your program is avoided.
The command is the actual executable (path and) file name, followed by any desired parameters. For example, 'MMPCREAT.PIF 600' or 'C:\WINDOWS\PBRUSH.EXE POLICE.BMP', et cetera.
In order to access a file which is located on a different computer from the one on which the application is executing, you must tell MAGEC on which machine that file is located. The computer which contains, or controls access to, the file is called the Host machine. The computer on which the application is executing is called the Client machine.
NOTE:
Every computer which will ever serve as a Host machine must be defined to Table #248, which is used to associate a mnemonic, unique name (up to 16 characters long) with the unique IP address of that machine. Refer to Defining a Host earlier in this section.
Terminals, or nodes of the network are defined to MAGEC's repository via the DVC (Device) definitions which include a "Home" Gateway name.
Data files are defined to MAGEC's repository using the DCL, KYF, ELT, and DIT entities. The DCL definition specifies high-level parameters for the Data Class (file), including its "Gateway" machine name. The Gateway machine is the Host machine which contains and "owns" this file. This is how MAGEC's I/O module knows whether this file is local (accessed using ordinary read's and write's) or remote (accessed by passing the request to the Gateway machine for servicing).
Since all applications in MAGEC call the MAGEC I/O module for all their file accesses, the I/O module automatically determines whether the file to be accessed is local or remote by comparing the Gateway name specified on the DCL definition to several values.
First, if the Gateway name from the DCL definition is "LOCAL", or is blank, MAGECIO assumes that the file is local and therefore issues ordinary read/write commands to access it. If the Gateway name from the DCL definition matches the name specified in the MAGHOST environment variable, MAGECIO also assumes the file is local. If the Gateway name from the DCL definition matches the Home Gateway name from this terminal/node's DVC definition, MAGECIO also assumes that the file is local. If the Gateway name specified on the DCL does not match any of the above, MAGECIO assumes that the file is remote and passes the request on to the address associated (in Table #248) with that Gateway name.
To illustrate how this works, let us take an example using a network consisting of two users (JOHN and MARY), each having one computer, plus one NOS server which is accessed by both users. Most of the files used by both users are on the server's disks; however, there is one file on MARY's computer (the MRY Data Class) which is accessed by both JOHN and by MARY, and one file on JOHN's computer (the JON Data Class) which is accessed by both of them as well.
The two users' computers will be called (in Table #248) MARYS-COMPUTER and JOHNS-COMPUTER. Since the NOS makes all files on the server accessible to either of the users, it is not necessary to define it to Table #248--but it is all right to do so, if you wish. Let's define it to Table #248 with the name NETWORK-SERVER, for this illustration.
The MAGEC DVC file is located on the NOS server's disk and is shared by both users. As each user logs onto MAGEC, he/she is assigned a terminal ID. There is a record on the DVC file for each terminal ID used. Each DVC record specifies "NETWORK-SERVER" as its Home Gateway. This tells MAGECIO that any Data Class (file) whose Gateway Name specifies "NETWORK-SERVER" is actually local to this terminal/node.
The DCL, KYF, and other repository entities associated with data definition also reside on the shared NOS server.
Most of the DCL definitions specify either "LOCAL", or "NETWORK-SERVER", or blanks for their Gateway Names. All of these are accessed as local files by both the user computers since the NOS makes them virtually local.
The MRY Data Class specifies "MARYS-COMPUTER" as the Gateway Name in its DCL definition, and the JON Data Class specifies "JOHNS-COMPUTER".
Both of the users' computers must serve as Client machines for their respective users, and as Host machines for each other. Therefore, both computers are running MGHOST as well as MAGEC's applications. Each machine must also have a WinSock-compatible "stack", as well.
MARY's computer has the environment setting: MAGHOST=MARYS-COMPUTER. JOHN's computer has the environment setting: MAGHOST=JOHNS-COMPUTER.
Whenever MARY executes an application which accesses the MRY Data Class, it treats it as a local file (which it is) because the Gateway Name of the MRY Data Class matches her MAGHOST environment setting. Similarly, whenever JOHN accesses the JON Data Class it is recognized as a local file.
Whenever MARY accesses the JON Data Class, it is treated as a remote file and the request is passed to JOHNS-COMPUTER, since that is the Gateway Name specified in the DCL definition for the JON Data Class. Whenever JOHN accesses the MRY Data Class MAGECIO similarly knows to pass the request to MARYS-COMPUTER.
When either of them accesses any other Data Class which is specified with a Gateway name of "LOCAL", or blanks, MAGECIO uses normal local file accesses. Also, if the Data Class' Gateway Name specifies "NETWORK-SERVER", it will be treated as local since that matches the Home Gateway Name specified on their DVC profiles.
Next, let's add another node to our network. This time it will be a mainframe computer running MVS/CICS with MAGEC installed. All of the necessary hardware and software for TCP/IP is installed and generated on the mainframe, so it can be plugged into your Token Ring or Ethernet network. The mainframe has an IP address just like any other computer and it is defined in Table #248 with the Gatetway Name of "BIG-IRON".
There are several large VSAM and Datacom/DB data files on the mainframe's disks which are used by mainframe programs (both MAGEC-generated, and older legacy systems). MARY and JOHN would like to be able to access those files from their applications running in a Windows environment.
For each of these files to be so shared, the DCL definition specifies "BIG-IRON" as the Gateway Name. The DCL definitions on the mainframe's repository and on the NOS server MAGEC repository are identical, since the Database Administrator has used the APUNLOAD/APLOAD utilities to synchronize the repositories.
Now, when either MARY or JOHN accesses these Data Classes, MAGECIO recognizes them as being remote and passes the request to the IP address specified for "BIG-IRON" in Table #248. The MAGEC I/O module executing on the mainframe processes the request and sends the results back to the requesting computer.
Since MAGEC-generated applications are portable, the applications being executed in the Windows environment can also be migrated to the mainframe MAGEC system and executed there. They can access the same files without requiring any duplication of data. Thus, the same application programs can be executed on the mainframe or PC / LAN and can concurrently be accessing the same set of files, some of which reside on the mainframe, some on the NOS server, and some on individual nodes' disk drives throughout the network.
If the Database Administrator decides, for whatever reason, to migrate one or more of the files from one computer to another, no programming changes need be made and no re-compiles need be done. The specification of where each file resides is contained solely in the MAGEC repository definitions which can be updated by the Administrator online.
When the application running in Windows accesses data from a Data Class which resides on the mainframe, an EBCDIC to ASCII (and vice-versa) conversion automatically is done as appropriate so that the data always appears in the expected format. This conversion is, as we have said before, controlled by the actual field-level data definition from the DIT file (part of the MAGEC repository).
The Database Administration section of your Programmer's Reference manual discusses the importance of current data definitions as regards proper ASCII / EBCDIC conversions.
To "manually" shut down a MAGEC host, you execute the SHUTHOST program. SHUTHOST.EXE is a Windows application which issues a TCP/IP message to any running host (machine on which MGHOST is executing). The message is a command to MGHOST to shut down and clean up all open connections and/or VTAM logical units.
SHUTHOST is normally executed in either of two ways, 1) directly from a Windows icon, or 2) via an API call from the MAGEC online function, **HOST. In either case the command is:
where iii.iii.iii.iii is the IP address of the host you wish to shut down, and ppppp is the desired port# to be shut down, preceded by two slashes. In the second format, nnnnnnnnnnnnnnnn is the Gateway Name as specified in MAGEC Table #248. In that case SHUTHOST will interrogate Table #248 to get the IP address and Port ID, then Table #243 to get the range of Port numbers.
SHUTHOST.EXE is a Windows program and cannot be run from a DOS prompt. The computer on which SHUTHOST is executed must be configured as any MAGEC client machine would be, indeed, it normally will be a client machine in the network.
From within MAGEC's online system you can execute the **HOST function code which lists all the host machines defined to the system. It does not distinguish between those which are currently active and those which are not. To invoke SHUTHOST from this screen simply point the cursor to the host you wish to shut down and press PF4. The **HOST function will issue an API call to execute SHUTHOST with the IP address of the selected host machine as its command-line parameter. SHUTHOST can be used to shut down a Host whether it is a mainframe or PC Host.
MAGEC supports TCP/IP connectivity to IBM mainframes in conjunction with either of two connectivity providers, Interlink Computer Sciences, or OpenConnect. Interlink's solution is restricted to the MVS enviroments while OpenConnect's connectivity supports both MVS and VSE.
The mainframe programs involved in MAGEC interfaces are:
MMP6H1 Interlink Listen pgm
A CICS PCT entry must be provided to invoke either MMP6H1 or MMP6H3, as appropriate, to start MAGEC's TCP/IP Host processing on the mainframe, or if desired, a CICS PLT entry can invoke MMP6H1 or MMP6H3 at CICS startup time. A PCT entry is also required for MMP6H2 or MMP6H4, as appropriate.
The PCT entries are:
for Interlink: =
for OpenConnect:
Multi tasking and multi-thread operation are supported in either implementation; however, they are handled differently. The Interlink version of MAGEC's TCP/IP includes built-in multi-thread capabilities. The OpenConnect solution is inherently multi-tasking, but accommodates multi-thread processing through a mechanism which allows you to control and monitor performance.
The MGH4 transid is associated with the MMP6H4 program. It is the actual host processor for the mainframe. There may be one or more instances of MGH4 executing concurrently. The MGH3 transid is associated with the MMP6H3 program. It acts as a supervisor to manage traffic to the mainframe. There may be only one MGH3 executing at a time.
It is not necessary to have multiple MGH4's executing in order to support multiple clients; each will support an unlimited number of clients. The purpose for having multiple MGH4's executing is to share the workload and to permit several clients to be serviced at the same time. On a large network this can result in a significant increase in throughput. With only one MGH4 executing, client requests will be serviced serially. Because overhead is kept to a minimum, each request will be processed and completed very quickly, so several clients can easily be handled without any noticeable delay. This is called a single-thread operation since each request must wait for the preceding request to finish.
With several MGH4's executing concurrently, each can be processing a request for a different client at the same time. In order to have several MGH4's active, each must be "listening" on a different TCP/IP port.
On a TCP/IP network, messages are sent to a specific port# at a specific IP address. There will usually be only one IP address for a given computer (i.e. your mainframe), but different applications can distinguish which messages are for them by the port#. The port# might be imagined as analogous to an apartment number within an apartment building, the building address being the IP address.
The entry in Table #243 for TCPIP-PORT specifies the port# or range of port#'s to be used by MAGEC. Port#'s are 5-digit numbers not greater tha 65535. The specification in Table# 243 may be a single port# (i.e. 05998), or a range of port#'s (i.e. 05998-06008). The first (or only) port# specified is the primary port#, the remainder of numbers in the range (if given) are secondary port#'s.
If only one instance of MGH4 is desired, it can be started directly from a PLT entry, or by entering the transid MGH4 from any CICS terminal. In this case it will automatically listen on the primary port# from MAGEC Table #243's TCPIP-PORT specification.
If multiple instances are desired in order to support higher traffic levels, then you should not directly start MGH4 either from a PLT entry or from a terminal. Instead, you should start MMP6H3 (MGH3) (preferrably from a PLT entry). MMP6H3 is the MAGEC "Host Scheduler".
All client requests initially are addressed to the primary port#. If only one MGH4 is executing, it will receive and process those requests. If, instead, MGH3 is running, it will receive each client's initial request and will respond to the client with a message telling that client to use another port (a specific port# selected from the range of secondary port#'s) for all subsequent communications. If necessary, MGH3 will issue the start command to ensure that an MGH4 is actively listening on the assigned port#.
Through internal algorithms MGH3 balances the workload among all the active MGH4's and maintains statistics for each one. It dynamically re-tunes the network based upon current activity.
To control the maximum number of active MGH4's which MGH3 will initiate, simply increase or decrease the range of port#'s in Table #243's entry for TCPIP-PORT.
The third transid associated with MAGEC's OpenConnect solution is MGH5. It is a dynamic system monitor and tuner which executes periodically (perhaps every few minutes) to check on the several MGH4's which are executing and to gather statistics from each one. It compiles these statistics and reports them to the supervisor (MGH3). It also compares the recent workloads of all the MGH4's to determine whether some clients should be switched from a busy host processor to a less-busy one.
MGH5 occasionally issues commands to the busier MGH4's telling them to handoff clients to other MGH4's which have excess capacity. These handoffs occur without any interruption to the client's processing.
MGH5 is invoked by the supervisor, MGH3, periodically. If you are running a single-thread configuration, neither MGH3, nor MGH5 is needed, and only one port#(the primary port#) needs to be specified in Table #243's TCPIP-PORT entry. When MGH3 is used, there must be at least two ports, one primary and one secondary, provided in the Table #243 TCPIP-PORT entry.
In order to provide faster response and enable greater throughput over any network topology, MAGEC automatically compresses the TCP/IP messages it sends between the client and host. This compression is completely transparent to your applications as it is handled internally. The compression results in fewer bytes and fewer packets transmitted over the network; hence, lower overhead.
Typical application processing usually involves numerous browse operations. The MAGEC standard LOC..., SCN..., and FND... functions are examples of browse operations. A browse operation can also be called a pseudo-sequential read operation. That means that the program will be reading records in the sequence of a key, which may or may not be the physical sequence of records on the disk. These operations involve successive read-next accesses after having positioned to some point in the index using LOCKY, REDLE. Refer to the Database Administration section of your Programmer's Reference for more about file accesses.
When an MMP is accessing a file which is remote, these read-next accesses would normally each involve a two-way communication between the client and the host. SInce the MMP can reasonably anticipate that it will do several succesive accesses, it would save much overhead if the MMP could signal the I/O module to try to read several records at a time, passing them back to the client in one larger message, into a buffer in anticipation of the MMP's future requests. The local I/O module would then hold the records in a buffer and return them to the MMP one at a time as they are requested.
That is exactly what MAGEC's read-ahead buffering capability does. The combination of the read-ahead buffering and message compression can make browses of remote files extremely fast and can reduce the number of bytes, number of packets, and number of messages sent across the network.
In order for your network to support cross-system data access, it is necessary that the data definitions on the client systems and host systems be kept synchronized. That simply means that the DCL, KYF, ELT, and DIT definitions for any files you wish to access remotely should be the same on your system and on the gateway (host machine) on which those files reside.
The batch APUNLOAD / APLOAD processes could be used to copy the definitions from one system to another, or an online synchronize program called DCLSYNC can be used.
DCLSYNC is a program which can be executed from a Windows client machine. It can copy any Data Class' complete definition either to the host gateway you specify, of from the host to your local system.
You can execute DCLSYNC from an icon. It first asks you to specify the gateway you wish to copy from or to, and whether you wish to UPLOAD (copy to the fgateway), or DOWNLOAD (copy from the gateway to you local repository.
Next it dynamically builds a list box showing the DCL names defined on the source system and asks you to select the one you wish to copy.
If the Data Class you have selected is currently defined on the target system, you will be asked if you wish to overlay it or cancel the process. If you select OVERLAY, DCLSYNC will first copy all of the DCL, KYF, ELT, and DIT records from the target system to an UNDO file, then delete them all from the target system, then copy them from the source system and add them to the target system.
Also refer to the discussions about alias Data Class names (DC$, KY$, EL$, and DI$) in your MAGEC Installation Guide.
In some installations it may be desirable to have more than one MAGEC host listening for messages on different CICS systems running on the same mainframe. This might be done to enable accessing both a test and production CICS system concurrently, or perhaps an MVS and a VSE system.
If your installation includes multiple physical connections to the mainframe, then each connection will have a distinct IP address and there is no practical limit as to the number of connections you may have. If, however, you have only one physical connection to the mainframe, then there will be only one IP address and you must distinguish between multiple MAGEC hosts (at the same IP address) by using different Port numbers. Refer to the MAGEC Installation Guide discussion of TBL #243 parameters for TCPIP-PORT, etc.
MAGEC supports up to 27 MAGEC Host Schedulers (MMP6H3) listening on different ports on the same IP address. This means that at one mainframe, using one IP address (single connection), you could have 27 CICS regions (or partitions) concurrently being accessed through the network.
The basic TBL #243 parameter, TCPIP-PORT, defines a range of port numbers to be used by one instance of MMP6H3, the Host Scheduler. Additional ranges of port numbers can be specified using the TCPIP-PORTA thru TCPIP-PORTZ specifications in TBL #243. This gives you up to 26 ranges in addition to the basic range specified in TCPIP-PORT.
To tell each instance of MMP6H3 which range it should use, there are 26 CICS transid's defined which are synonyms for the basic MGH3 transid. The synonym transid's are MGHA thru MGHZ. MMP6H3 interrogates the transid used to invoke it and uses the corresponding range of port numbers--MGHA causes MMP6H3 to use the TCPIP-PORTA specification, etc. If you wish to manually initiate MMP6H3 from a CICS terminal, enter one of these transid's with no parameters following it and press ENTER. The program will sense that it has been invoked from a terminal and will automatically restart itself as an asynchronous task, freeing your terminal.
If you invoke MMP6H3 from the DFHPLT, you cannot associate any transid with it (a limitation of executing from the PLT); therefore, it is equivalent to executing using the transid MGH3. If the program is not initiated using ome of the MGHA thru MGHZ transid's it will serach for a PortID (A thru Z) to use by interrogating a special control record which is stored on the MAGEC MAL file. If the control record is not found, MMP6H3 will default to the setting given in the basic TCPIP-PORT (with no suffix) specification. If the control record is on the MAL file, MMP6H3 will use the PortID specified there (unless it is invalid, in which case it reverts to the basic PortID).
The range of actual port numbers associated with a PortID is defined on MAGEC Table #243 in the 27 TCPIP-PORT (thru TCPIP-PORTZ) settings. The assignment of a PortID to a Gateway name is made in MAGEC Table #248 (Gateway Name Table), which contains the IP address and PortID for each Gateway name.
Each machine which is to serve as a MAGEC Host should be associated with one Gateway name. From that it can determine the PortID, and range of actual port numbers, it is to listen on. The control record on the MAL file tells the Host its Gateway name. It uses the Gateway name to access Table #248 to obtain the Port ID setting, then uses the PortID setting to access Table #243 to get the actual numeric port numbers to use. If the control record is not on file it will use the default port numbers specified in TCPIP-PORT in Table #243.
To record the setting inthe MAL file control record you should use the GW#LOC function, which lists all the Gateway names defined in Table #248, then select the one which applies to this Host. To select one, point the cursor at it and press ENTER. A screen will be displayed showing you the result of having made this selection (the Gateway name, PortID, and acutal port numbers to be used)
Note that it is possible to have more than one Host on one physical machine (i.e.: a test and production region, etc.)with each of them known by a different Gateway name. Indeed, if they are to be running simultaneously, they must use different Gateway names so that they can be listening on different ports.
There should be no two Gateway names having the same IP address and the same PortID setting; but, there may well be several Gateway names having the same IP address with different PortID settings.
The MAL file (MAGEC Activity Logging file) must not be shared between two MAGEC systems. This is not only a requirement for the TCP/IP networking, it is a basic requirement of MAGEC. This means that the control record on the MAL file applies to only one MAGEC system, as it should.
MAGEC cannot determine if you have specified the same Gateway name for two Host systems. There may even be situations in which you intentionally do so; but those two systems' Host processors cannot be running at the same time. You should be careful to assign Gateway names to Host systems appropriately.
The Gateway name is used by the Client processor to communicate with the Host, therefore the same definitions should be made on the Client systems and on the Host. Since thses definitions are made on the MAGEC Tables (TBL file), you may wish to use either the batch APUNLOAD/APLOAD jobs or the interactive Windows TBLSYNC program from a workstation to synchronize the definitions.
The TBLSYNC program can be executed from Windows and enables you to copy Tables from the local system to a remote Host system, or vice-versa. It also enables you to merge any missing entries from one ssytem to the other, leaving entries which are already present on the target system intact and undisturbed.
Any records whichare deleted or overlaid in any TBLSYNC process can be recovered from the archive where they were saved before being deleted/overlaid in the event of an error. To recover data from the archive you use the UNDOSYNC program.
Data Files
Executables
Work Space
Virtual Local Drives
MAGEC's Intrinsic Facility
Clients and Hosts
Defining a Host
Port #
MGHOST
MGCLIENT
ASCII vs. EBCDIC
DITGEN's Role
KYF's Role
Remote Execution
Remote File Access
SHUTHOST
CICS Hosts
MMP6H2 Interlink message processor
MMP6H3 OpenConnect supervisor pgm
MMP6H4 OpenConnect Listen & message processor
MMP6H5 OpenConnect dynamic system monitor
OpenConnect Multi-threading
Dynamic Tuning
Message Compression
Read-Ahead Buffering
Synchronizing Data Definitions
Alternate Ports
Gateways and PortID's
Synchronizing Definitions