DITGEN's Role<br />In order to efficiently and accurately accomplish the ASCII / EBCDIC translations, MAGEC must have current definitions (cont.)<br />for the data. Those definitions are taken from the ELT file records which define Elements. As a normal part of the data (cont.)<br />definition process the Database Administrator executes the DITGEN function. Refer to your *Programmer's Reference* (cont.)<br />manual, Database Administration section for more detailed information regarding data definition, or access the online (cont.)<br />help tutorials from GUI MAGEC.<br />The principal duty of the DITGEN function is to generate the Cobol copybook defining an Element. As of MAGEC release (cont.)<br />3.0, the DITGEN function has an added task: it generates a highly compressed table of conversion parameters which (cont.)<br />control the ASCII / EBCDIC (and vice-versa) translation. This table of parameters is stored in the ELT record for each (cont.)<br />Element. When required, the MAGEC I/O module passes this information to the MGCLIENT subroutine so that it can (cont.)<br />accomplish the translations.<br />Users of older versions of MAGEC likely have numerous definitions of Elements for which DITGEN was not recently (cont.)<br />executed. These Element definitions do not include the table of translation parameters. If MAGEC were to do the (cont.)<br />translation for the data defined by these Elements it would default to assuming that the entire Element is alphanumeric (cont.)<br />data and translate it accordingly. This will likely be less than perfect.<br />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.<br />## <br />KYF's Role<br />Since MAGEC supports a set of I/O commands which return only a found key value (the LOCxx commands), it is necessary to (cont.)<br />also be able to intelligently translate the key value returned. This is accomplished via the definitions found on the (cont.)<br />KYF file for each key and its component fields. From this definition MAGEC discerns which bytes of the key are (cont.)<br />alphanumeric, packed, binary, or signed zoned-decimal. Obviously this means that accurate definitions on the KYF file (cont.)<br />are important to achieving best results.<br />## <br />Remote Execution<br />With MAGEC's TCP/IP networking facility installed, a Client machine can invoke a jobstream or program to be executed at (cont.)<br />another (Host) machine. This facility works simarly to the "API Call" facility included with MAGEC's GUI option, except (cont.)<br />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 (cont.)<br />discussion of the special considerations regarding executing a process on a MVS or VSE mainframe, read this topic and (cont.)<br />also the topic Mainframe Sub-Tasks later in this chapter.<br />One possible use for this feature is to establish one or more Host machines which are configured optimally to perform (cont.)<br />some particular set of tasks, such as generating and compiling programs (i.e. MMPCREAT and MBPCREAT). Development (cont.)<br />personnel could submit their MMPCREAT requests to be run on the Host(s) while they continue doing other work on their (cont.)<br />workstations without suffering any degradation caused by having many large tasks concurrently (cont.)<br />active.<br />Since this facility uses the standard Windows API feature, any program or jobstream which can be executed from Windows (cont.)<br />could be executed from a remote Client. To execute a DOS batch file you would set up a .PIF file which executes the (cont.)<br />.BAT. You would execute the .PIF by specifying as the program name "xxxxxxxx.PIF", just as with the GUI API Call (cont.)<br />feature.<br />Programs generated using the standard MAGEC MODELMMP will automatically include the proper request area for executing a remote job. It is:<br />03 REMOTE-XQT-REQUEST...<br />05 RXQT-MSG-TYPE PIC X(8).<br />88 RXQT-REQUEST VALUE '$XQT'.<br />05 RXQT-GATEWAY-NAME PIC X(16).<br />05 RXQT-GATEWAY-ADDR PIC X(16).<br />05 RXQT-PORT PIC 9(5).<br />05 RXQT-MAGEC-RELEASE PIC X(3).<br />05 RXQT-NR-OF-BYTES PIC S9(4) COMP.<br />05 RXQT-COMMAND PIC X(128).<br />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:<br />MOVE '$XQT' TO RXQT-MSG-TYPE<br />MOVE 'xxxxxxxxxxxxxxxx' TO RXQT-GATEWAY-NAME<br />MOVE 'nnn.nnn.nnn.nnn' TO RXQT-GATEWQY-ADDR<br />MOVE nnnnn TO RXQT-PORT<br />MOVE '&REL' TO RXQT-MAGEC-RELEASE<br />MOVE 'xxxxxxxx.EXE parms '<br />TO RXQT-COMMAND<br />CALL 'MGCLIENT' USING TWA REMOTE-XQT-REQUEST.<br />In this request, the literal $XQT identifies this as a remote execution request to MGCLIENT. The Gateway Address is (cont.)<br />given in its "dotted" format which MGCLIENT will convert into the actual 4-byte address used by TCP/IP. This is the (cont.)<br />address of the Host at which the task is to be executed.<br />You can determine the address of any Host by accessing MAGEC Table #248. The Gateway Name is the code value, the (cont.)<br />address is in the description. You can view Table #248 online using the function code: 248LOC. No key value is needed (cont.)<br />for this function. You can also access Table #248 from within your program. As with all MAGEC LookupTables, the actual (cont.)<br />file key is 19 bytes long and consists of the 3-digit Table# (248) followed by the 16-character code value. The (cont.)<br />copybook TBL01-C defines the contents of all tables. Table #248 contains, for each Gateway Name, a one-character Port (cont.)<br />ID, as well as the IP Address. Refer to the topic Gateways & PortIDs later in this chapter.<br />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.<br />The symbolic '&REL' will be resolved at program generation time. It will contain the MAGEC release number. This helps (cont.)<br />MAGEC to verify that a version mismatch between the MGCLIENT program and your program is avoided.<br />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.<br />## <br />Remote File Access<br />In order to access a file which is located on a different computer from the one on which the application is executing, (cont.)<br />you must tell MAGEC on which machine that file is located. The computer which contains, or controls access to, the file (cont.)<br />is called the Host machine. The computer on which the application is executing is called the Client (cont.)<br />machine.<br />**<br />NOTE:<br />**<br />Remember, any computer in the network can be both a Host and Client at the same time, if you wish. This means that (cont.)<br />Machine A can be accessing a file located on Machine B while Machine B is accessing a file on Machine A. This permits (cont.)<br />you to distribute database accesses across many machines to balance workload and to better utilize disk capacity in (cont.)<br />your network.<br />Every computer which will ever serve as a Host machine must be defined to Table #248, which is used to associate a (cont.)<br />mnemonic, unique name (up to 16 characters long) with the unique IP address of that machine. Refer to Defining a Host (cont.)<br />earlier in this section.<br />Terminals, or nodes of the network are defined to MAGEC's repository via the DVC (Device) definitions which include a "Home" Gateway name.<br />Data files are defined to MAGEC's repository using the DCL, KYF, ELT, and DIT entities. The DCL definition specifies (cont.)<br />high-level parameters for the Data Class (file), including its "Gateway" machine name. The Gateway machine is the Host (cont.)<br />machine which contains and "owns" this file. This is how MAGEC's I/O module knows whether this file is local (accessed (cont.)<br />using ordinary read's and write's) or remote (accessed by passing the request to the Gateway machine for (cont.)<br />servicing).<br />Since all applications in MAGEC call the MAGEC I/O module for all their file accesses, the I/O module automatically (cont.)<br />determines whether the file to be accessed is local or remote by comparing the Gateway name specified on the DCL (cont.)<br />definition to several values.<br />First, if the Gateway name from the DCL definition is "LOCAL", or is blank, MAGECIO assumes that the file is local and (cont.)<br />therefore issues ordinary read/write commands to access it. If the Gateway name from the DCL definition matches the (cont.)<br />name specified in the MAGHOST environment variable, MAGECIO also assumes the file is local. If the Gateway name from (cont.)<br />the DCL definition matches the Home Gateway name from this terminal/node's DVC definition, MAGECIO also assumes that (cont.)<br />the file is local. If the Gateway name specified on the DCL does not match any of the above, MAGECIO assumes that the (cont.)<br />file is remote and passes the request on to the address associated (in Table #248) with that Gateway (cont.)<br />name.<br />To illustrate how this works, let us take an example using a network consisting of two users (JOHN and MARY), each (cont.)<br />having one computer, plus one NOS server which is accessed by both users. Most of the files used by both users are on (cont.)<br />the server's disks; however, there is one file on MARY's computer (the MRY Data Class) which is accessed by both JOHN (cont.)<br />and by MARY, and one file on JOHN's computer (the JON Data Class) which is accessed by both of them as (cont.)<br />well.<br />The two users' computers will be called (in Table #248) MARYS-COMPUTER and JOHNS-COMPUTER. Since the NOS makes all (cont.)<br />files on the server accessible to either of the users, it is not necessary to define it to Table #248--but it is all (cont.)<br />right to do so, if you wish. Let's define it to Table #248 with the name NETWORK-SERVER, for this (cont.)<br />illustration.<br />The MAGEC DVC file is located on the NOS server's disk and is shared by both users. As each user logs onto MAGEC, (cont.)<br />he/she is assigned a terminal ID. There is a record on the DVC file for each terminal ID used. Each DVC record (cont.)<br />specifies "NETWORK-SERVER" as its Home Gateway. This tells MAGECIO that any Data Class (file) whose Gateway Name (cont.)<br />specifies "NETWORK-SERVER" is actually local to this terminal/node.<br />The DCL, KYF, and other repository entities associated with data definition also reside on the shared NOS server.<br />Most of the DCL definitions specify either "LOCAL", or "NETWORK-SERVER", or blanks for their Gateway Names. All of (cont.)<br />these are accessed as local files by both the user computers since the NOS makes them virtually (cont.)<br />local.<br />The MRY Data Class specifies "MARYS-COMPUTER" as the Gateway Name in its DCL definition, and the JON Data Class specifies "JOHNS-COMPUTER".<br />Both of the users' computers must serve as Client machines for their respective users, and as Host machines for each (cont.)<br />other. Therefore, both computers are running MGHOST as well as MAGEC's applications. Each machine must also have a (cont.)<br />WinSock-compatible "stack", as well.<br />MARY's computer has the environment setting: MAGHOST=MARYS-COMPUTER. JOHN's computer has the environment setting: MAGHOST=JOHNS-COMPUTER.<br />Whenever MARY executes an application which accesses the MRY Data Class, it treats it as a local file (which it is) (cont.)<br />because the Gateway Name of the MRY Data Class matches her MAGHOST environment setting. Similarly, whenever JOHN (cont.)<br />accesses the JON Data Class it is recognized as a local file.<br />Whenever MARY accesses the JON Data Class, it is treated as a remote file and the request is passed to JOHNS-COMPUTER, (cont.)<br />since that is the Gateway Name specified in the DCL definition for the JON Data Class. Whenever JOHN accesses the MRY (cont.)<br />Data Class MAGECIO similarly knows to pass the request to MARYS-COMPUTER.<br />When either of them accesses any other Data Class which is specified with a Gateway name of "LOCAL", or blanks, MAGECIO (cont.)<br />uses normal local file accesses. Also, if the Data Class' Gateway Name specifies "NETWORK-SERVER", it will be treated (cont.)<br />as local since that matches the Home Gateway Name specified on their DVC profiles.<br />*<br />Next, let's add another node to our network. This time it will be a mainframe computer running MVS/CICS with MAGEC (cont.)<br />installed. All of the necessary hardware and software for TCP/IP is installed and generated on the mainframe, so it can (cont.)<br />be plugged into your Token Ring or Ethernet network. The mainframe has an IP address just like any other computer and (cont.)<br />it is defined in Table #248 with the Gatetway Name of "BIG-IRON".<br />There are several large VSAM and Datacom/DB data files on the mainframe's disks which are used by mainframe programs (cont.)<br />(both MAGEC-generated, and older legacy systems). MARY and JOHN would like to be able to access those files from their (cont.)<br />applications running in a Windows environment.<br />For each of these files to be so shared, the DCL definition specifies "BIG-IRON" as the Gateway Name. The DCL (cont.)<br />definitions on the mainframe's repository and on the NOS server MAGEC repository are identical, since the Database (cont.)<br />Administrator has used the APUNLOAD/APLOAD utilities to synchronize the repositories.<br />Now, when either MARY or JOHN accesses these Data Classes, MAGECIO recognizes them as being remote and passes the (cont.)<br />request to the IP address specified for "BIG-IRON" in Table #248. The MAGEC I/O module executing on the mainframe (cont.)<br />processes the request and sends the results back to the requesting computer.<br />Since MAGEC-generated applications are portable, the applications being executed in the Windows environment can also be (cont.)<br />migrated to the mainframe MAGEC system and executed there. They can access the same files without requiring any (cont.)<br />duplication of data. Thus, the same application programs can be executed on the mainframe or PC / LAN and can (cont.)<br />concurrently be accessing the same set of files, some of which reside on the mainframe, some on the NOS server, and (cont.)<br />some on individual nodes' disk drives throughout the network.<br />If the Database Administrator decides, for whatever reason, to migrate one or more of the files from one computer to (cont.)<br />another, no programming changes need be made and no re-compiles need be done. The specification of where each file (cont.)<br />resides is contained solely in the MAGEC repository definitions which can be updated by the Administrator (cont.)<br />online.<br />When the application running in Windows accesses data from a Data Class which resides on the mainframe, an EBCDIC to (cont.)<br />ASCII (and vice-versa) conversion automatically is done as appropriate so that the data always appears in the expected (cont.)<br />format. This conversion is, as we have said before, controlled by the actual field-level data definition from the DIT (cont.)<br />file (part of the MAGEC repository).<br />The Database Administration section of your Programmer's Reference* manual discusses the importance of current data definitions as regards proper ASCII / EBCDIC conversions.<br />*<br />## <br />SHUTHOST<br />To "manually" shut down a MAGEC host, you execute the SHUTHOST program. SHUTHOST.EXE is a Windows application which (cont.)<br />issues a TCP/IP message to any running host (machine on which MGHOST is executing). The message is a command to MGHOST (cont.)<br />to shut down and clean up all open connections and/or VTAM logical units.<br />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:<br />SHUTHOST iii.iii.iii.iii//ppppp<br />&nbsp;<br />-or-<br />&nbsp;<br />SHUTHOST nnnnnnnnnnnnnnnn<br />&nbsp;<br />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 (cont.)<br />down, preceded by two slashes. In the second format, nnnnnnnnnnnnnnnn is the Gateway Name as specified in MAGEC Table (cont.)<br />#248. In that case SHUTHOST will interrogate Table #248 to get the IP address and Port ID, then Table #243 to get the (cont.)<br />range of Port numbers.<br />SHUTHOST.EXE is a Windows program and cannot be run from a DOS prompt. The computer on which SHUTHOST is executed must (cont.)<br />be configured as any MAGEC client machine would be, indeed, it normally will be a client machine in the (cont.)<br />network.<br />From within MAGEC's online system you can execute the **HOST function code which lists all the host machines defined to (cont.)<br />the system. It does not distinguish between those which are currently active and those which are not. To invoke (cont.)<br />SHUTHOST from this screen simply point the cursor to the host you wish to shut down and press PF4. The **HOST function (cont.)<br />will issue an API call to execute SHUTHOST with the IP address of the selected host machine as its command-line (cont.)<br />parameter. SHUTHOST can be used to shut down a Host whether it is a mainframe or PC Host.<br />## <br />CICS Hosts<br />MAGEC supports TCP/IP connectivity to IBM mainframes in conjunction with either of two connectivity providers, (cont.)<br />Interlink Computer Sciences, or OpenConnect. Interlink's solution is restricted to the MVS enviroments while (cont.)<br />OpenConnect's connectivity supports both MVS and VSE.<br />The mainframe programs involved in MAGEC interfaces are:<br />MMP6H1 Interlink Listen pgm<br />**MMP6H2 Interlink message processor<br />MMP6H3 OpenConnect supervisor pgm<br />MMP6H4 OpenConnect Listen & message processor<br />MMP6H5 OpenConnect dynamic system monitor<br />A CICS PCT entry must be provided to invoke either MMP6H1 or MMP6H3, as appropriate, to start MAGEC's TCP/IP Host (cont.)<br />processing on the mainframe, or if desired, a CICS PLT entry can invoke MMP6H1 or MMP6H3 at CICS startup time. A PCT (cont.)<br /><br />next: network03.md.txt