The portion of any MAGEC screen in which miscellaneous messages may be displayed, it is the rightmost half of the top line.<br />Secondary Key<br />A key for a record that is other than the Master (Primary) key and that needs not uniquely identify the record since it is used only in browse Functions in MAGEC MMP's. Alternate Index.<br />SERRMSG<br />The last three lines of any MAGEC screen. The area in which Error messages are usually displayed.<br />SFUNCT<br />The portion of the top line of any MAGEC screen in which the Function Code is entered/displayed.<br />SKEY<br />The portion of the top line of any MAGEC screen in which the key value is entered/displayed for the Function being done.<br />SQL<br />Structured Query Language. A database access language for relational databases.<br />Subordinate Key<br />See Secondary Key.<br />Supra<br />Cincom's relational database system.<br />TCP/IP<br />Transmission Control Protocol/Internet Protocol. A protocol used to communicate between networks of computers<br />TeraData<br />A database "back end machine" that is a relational SQL database system.<br />TP monitor<br />Any of the software products that is designed to support online processing against 3270-type devices and from Cobol (cont.)<br />applications programs in a multi-tasking environment. CICS, WESTI, or Datacom DC, etc.<br />TWA<br />Task Work Area. Main memory used by an MMP as work space and for passing data to other modules and for reading data (cont.)<br />into and writing from. Also used for saving data from task to task in a "pseudo-conversational" processing mode since (cont.)<br />it is saved and restored by the MAGEC Control Program as a service to the MMP's.<br />Undelete<br />To restore a pseudodeleted record to "undeleted" status by setting the Delete Flag in the Audit Stamp from X'FF' to blank.<br />Version Validation<br />The process of researching and comparing version numbers and creation/modification dates for all entities of an (cont.)<br />application to find possible sources of errors. Done using the VERZUN function of MAGEC.<br />VSAM<br />IBM's Virtual Sequential Access Method, including all its variations.<br />WESTI<br />A TP monitor that is a product of Westinghouse. No longer supported by MAGEC as of release 3.0<br />Workstation<br />A standalone computer, usually a PC, PS/2, or 9370 type machine, that is a functional replica of the main production (cont.)<br />system and that serves as a testing and development environment for analysts, designers, and programmers. Provides (cont.)<br />absolute separation of testing and production. MAGEC supports all of the workstation machines listed (cont.)<br />above.<br /># <br />Appendix C -- Networks<br />Distributed Databases<br />MAGEC allows for installation on a network with the ability to distribute database files across multiple servers, (cont.)<br />physical disk drives, and logical disk drives. When MAGEC is installed you must determine on which drive the MAGEC (cont.)<br />reposittory files and executable (.EXE, .DLL, .BAT, .CMD, etc.) modules are to reside. Then, for each of your (cont.)<br />applications' database files, you must decide where they are to reside. MAGEC provides an easy way for you to specify (cont.)<br />where each file resides by entering the drive ID on the KYF (Key Format) panel (refer to page 11 in this (cont.)<br />section).<br />MAGEC Software suggests the following configuration for LAN installations:<br />1. all of the MAGEC repository files (.DAT) should be installed on the same drive on the same server.<br />2. all nodes should refer to that drive using the same symbolic drive letter (i.e. G:).<br />3. all nodes should include the SET LANDRV=G statement in their AUTOEXEC.BAT files (assuming that G: is the correct drive ID).<br />4. each developer's node should have a local disk drive (usually C:) that has several megabytes available for work space and has the Cobol compiler installed in the \COBOL (MicroFocus) directory.<br />5. the SET LCLDRV=C (assuming that C: is the corrcet drive ID) statement should be included in each node's AUTOEXEC.BAT file.<br />6. as new application database files are added: if they reside on the same drive as is specified in the SET LANDRV= (cont.)<br />parameter, the KYF definition should leave the Drive ID specification blank. If they reside elsewhere, the Drive ID (cont.)<br />should be specified on the KYF panel.<br />7. end users must have authorization via the LAN operating system to access the servers and drives on which their applications' files reside.<br />8. If accessing via Windows, the SET statements must be done prior to entering Windows in order to apply to sessions within Windows.<br />9. It is permissable for any user to have multiple MAGEC sessions via Windows concurrently. A unique "terminal ID" is (cont.)<br />assigned to each session. Clipboard may be used to copy data from one window to another.<br />Also refer to the Networks section of your *Application User's Guide* for more about networks.<br /># <br />Appendix D -- Datacom DB<br />NonStandard Key & Element Names<br />MAGEC employs a standard for naming Data Classes, Keys, and Elements. Many of the features of MAGEC depend upon that (cont.)<br />standard. For Datacom DB users who have installed MAGEC at the time that they installed Datacom DB the MAGEC standard (cont.)<br />is a very useful one to follow when creating definitions into the Datacom dictionary; thus, the name Datacom knows each (cont.)<br />entity by is the same as the name MAGEC knows it by. This is the ideal configuration; however, for some users it is not (cont.)<br />possible.<br />MAGEC users who already had been using Datacom DB for some time prior to installing MAGEC will already have many Data (cont.)<br />Classes (Tables), Keys, and Elements defined to Datacom. These may not abide by the MAGEC standard. In order to provide (cont.)<br />compatibiliity for such situations, MAGEC allows you to specify the true Datacom name, if it is different from the (cont.)<br />MAGEC name, for each Key and Element.<br />Standard Names<br />The Data Class is given a 3-character name in MAGEC. Datacom DB requires that you define each table with a 3-character name. These names should be the same in MAGEC and Datacom.<br />The MAGEC standard requires that the Master key be named xxxK1(where xxx = the Data Class name). Subordinate Keys are (cont.)<br />named xxxK2, xxxK3, etc. Datacom permits you to give any 5-character name to your keys.<br />MAGEC requires that your Elements be named xxxnn (where xxx = the Data Class name, nn is any two characters, usually (cont.)<br />numerics). Further, special meaning is assigned to the Element names xxx00 and xxx99. The xxx00 name indicates a (cont.)<br />36-byte audit stamp Element. The xxx99 name indicates a 4-byte record descriptor word for variable-length (cont.)<br />records.<br />To handle situations in which your Datacom names do not match the MAGEC standard, you must define the Keys and Elements (cont.)<br />using the MAGEC standard names, but specify the true Datacom names in special fields within the MAGEC (cont.)<br />definitions.<br />If you have specified Datacom as the access method for a Data Class, there will appear on your KYFxxx screen and ELTxxx (cont.)<br />screen, special entry fields in which you can enter the true Datacom names. If you leave any of these entries blank, (cont.)<br />MAGEC assumes that the Datacom name is the same as the MAGEC name. These special entry fields have a prompt such as "CA (cont.)<br />DD Name".<br />Database ID's<br />Datacom DB permits you to define up to 999 Databases identified by 3-digit Database ID numbers. It also allows you to (cont.)<br />define tables with the same names in several Database numbers. For instance, you might have a CUS table in Database (cont.)<br />#101 and another CUS table in Database #367, et cetera.<br />The MAGEC DCLxxx definition provides for you to specify a test Database number and a production database number for (cont.)<br />each Data Class. If you do so, MAGEC's I/O module will automatically insert the appropriate Database ID into the I/O (cont.)<br />request based upon whether you are a test user or a production user (according to the User View you used to access (cont.)<br />MAGEC).<br />If you set the test and/or production Database number to 000 on the DCLxxx definition for a Data Class having the (cont.)<br />access method of Datacom, MAGEC's I/O module will not insert any Database number; rather, it will expect your (cont.)<br />application program to have set it (in TWA-DB-ID) as needed.<br />Datacom DB I/O accesses only require the Database ID to be set if SYNONYM=YES is specified in the User Requirement (cont.)<br />Table (URT) enabling your program to access more than one table of the same name. If not, Datacom will ingore the (cont.)<br />Database ID.<br /># <br />Appendix E -- MAGECSET<br />Setting addresses into pointers<br />There are numerous occasions when a programmer must load the address of some area of memeory into a pointer. One (cont.)<br />example of such occasion is when calling MAGEC's I/O module, refer to examples shown in "Sample Code" earlier in this (cont.)<br />*Database Administration* section.<br />If you are using Cobol II, or Cobol/370, or any other ANSI 85 standard Cobol compiler, you can set addresses into pointers using the SET verb, as:<br />SET MY-POINTER TO ADDRESS OF MY-DATA.<br />In this example, the data item named MY-POINTER must be defined as USAGE IS POINTER, though it may be redefined as PIC (cont.)<br />X(4) or PIC 9(9) COMP if necessary. The address of the data item named MY-DATA will be set into the 4-byte field named (cont.)<br />MY-POINTER.<br />Since not all MAGEC users are using ANSI 85 Cobol compilers, MAGEC provides a subroutine to accomplish the identical (cont.)<br />results as the SET statement shown above. The subroutine is named "MAGECSET", and it is used as (cont.)<br />follows:<br />CALL "MAGECSET" USING MY-POINTER MY-DATA.<br />In this case it does not matter whether MY-POINTER is defined as PIC X(4), PIC S9(9) COMP, or any other format. (cont.)<br />MAGECSET assumes that MY-POINTER is 4 bytes long and sets the address of MY-DATA into it. The above statement will work (cont.)<br />identically whether you are using Cobol II, Cobol/370, VS Cobol (ANSI 74), or any other Cobol compiler. It works on the (cont.)<br />mainframe, PC, or Unix systems identically. It is therefore more portable than the Cobol SET verb.<br /># <br />Appendix F -- Read-Ahead<br />TWA-DB-RETURN-CODE<br />The primary use for the field named TWA-DB-RETURN-CODE in the request area passed to MAGECIO is for the I/O module to (cont.)<br />pass a return code back to your program indicating the success or failure of your request. However, it is also possible (cont.)<br />for your program to pass commands to MAGECIO using TWA-DB-RETURN-CODE. One of the commands you can pass here is "RQ", (cont.)<br />indicating that you would like the I/O module to queue records for you since you intend to do a number of sequential (cont.)<br />reads (REDNX, REDPR, or REDBR commands).<br />If you are accessing a file that is local to you (not accessed via a Gateway), this command will be ignored by MAGECIO. (cont.)<br />If you are accessing a file that is remote using MAGEC's intrinsic TCP/IP networking capabilities, then MAGECIO will (cont.)<br />attempt to build a queue of records at the host machine and pass them as a block to the local I/O module. As your (cont.)<br />program requests subsequent read-nex or read-previous commands MAGECIO will satisfy them from the buffer of queued (cont.)<br />records until that buffer-load of records is expired, then will request another block of records from the Gateway (cont.)<br />machine. This reduces the number of messages transmitted between the client and host machines, and can also enhance the (cont.)<br />benefits of MAGEC's built-in compression of those transmissions.<br />Read-Ahead processing can greatly improve performance for sequential processing agains a remote file; however, its (cont.)<br />mis-use can impose a performance penalty. It is best to understand how read-ahead processing works in order to ensure (cont.)<br />optimum performance.<br />When your application program calls MAGECIO to access a remote file, MAGECIO in turn calls MGCLIENT. MGCLIENT formats a (cont.)<br />Remote I/O Command message and sends it to the appropriate Gateway (using the IP address defined for that Gateway in (cont.)<br />MAGEC Table #248). The message is received by the MAGEC Host program (we will assume a name of "MGHOST") which calls (cont.)<br />the MAGECIO module at its location to access the requested data. MAGECIO (at the remote site) returns the data to (cont.)<br />MGHOST which formats a Remote I/O Response message and then sends it back to the requesting MGCLIENT in your computer. (cont.)<br />MGCLIENT formats the data returned into your TWA and returns control back to your local MAGECIO, which returns control (cont.)<br />back to your program. All transmissions are compressed for improved performance.<br />The MGHOST running at the remote site checks whether you have set the "RQ" command into TWA-DB-RETURN-CODE, and are (cont.)<br />also doing one of the sequential read comamnds: REDNX, REDPR, or REDBR. If so, MGHOST will attempt to read several (cont.)<br />records and build a queue of records to send back to MGCLIENT, rather than sending only one record back. The number of (cont.)<br />records it will queue up is limited to either 16 records, or 16 KBytes of data, whichever is less.<br />MGCLIENT receives this transmission containing a record queue and formats the TWA using the first record from the (cont.)<br />queue. It holds the entire queue of records in memory, in the area into which it was received, anticipating that your (cont.)<br />program's next request will be for the next record from the queue. For these purposes, reqeusts to files that are not (cont.)<br />remote do not count; therefore, your program may read several local files in between doing REDNX's (or REDPR's, or (cont.)<br />REDBR's) against the remote file. If the next request is the anticipated command, MGCLIENT will simply format the TWA (cont.)<br />with the next record from the queue, eliminating all overhead associated with the two-way communication with MGHOST. If (cont.)<br />the next command is not the anticipated command, MGCLIENT will destroy the queue of records and satisfy the request by (cont.)<br />sending a message to MGHOST, as it normally does.<br />This means that any unused records in the queue are wasted. If your program then issues the next read-next request for (cont.)<br />the first file, it will have to be satisfied using the normal two-way communication.<br />As you can see, improper use of read-ahead can cause your application to do unnecessarily large transmissions and (cont.)<br />wasted I/O at the host site. Used properly it can greatly reduce both the number of messages sent over the network and (cont.)<br />the number of bytes sent (compression is more effective for the larger blocks).<br />It should be noted that for the read-ahead processing to work it is necessary that the TWA-DB-REQUEST area and the (cont.)<br />TWA-KEY-VALUE area be undisturbed from one request to the next. MAGECIO stores positioning information within these (cont.)<br />areas and checks for it on subsequent requests. If they have been altered MGCLIENT assumes that it cannot satisfy the (cont.)<br />request from its record queue and must pass the request on to MGHOST for processing. For this reason, your program (cont.)<br />should save both these areas after returning from MAGECIO, and restore them before the next request. This allows you to (cont.)<br />access other files in between. The default logic generated into your programs does the proper saving and restoring for (cont.)<br />your primary data class' data. The only exception to this is that the TWA-DB-RETURN-CODE will be returned to your (cont.)<br />program with the proper value to indicate the success of your request (usually spaces) and you will be (re)setting it (cont.)<br />to "RQ" prior to each call to MAGECIO.<br />Also refer to the Networks section of your *Application User's Guide* .<br /># <br />Appendix G -- File Opens & Closes<br />## <br />Implicit vs. Explicit Opens<br />When your programs access files using MAGECIO, whether in batch or online environemnts, they need never explicitly open (cont.)<br />the files unless they require a particular type of open different from the default which MAGECIO will use. For online (cont.)<br />program operating on a mainframe using CICS, your programs never issue explicit open commands and, if they do, the (cont.)<br />commands are ignored by MAGECIO and treated as a "no operation", exactly like the NOOPS command. For other (cont.)<br />environments. explicit open commands are honored, but if your program accesses a file using another command, such as a (cont.)<br />REDKY, prior to opening the file, an implicit open is automatically issued. SInce the file is then open, you must issue (cont.)<br />a close to the file before you can successfully re-open it differently. Therefore, it is usually easiest to issue your (cont.)<br />explicit open commands prior to your first file access to ensure that the file is opened properly.<br />The implicit open is done in all environments unless you explicitly issue an open command; however, in the CICS (cont.)<br />environment file open and close capabilities are restricted by the CICS DFHFCT parameters. Files used by MAGEC are (cont.)<br />normally defined to CICS to be either opened initially as CICS is started up, or enabled to open as they are accessed. (cont.)<br />In online programs in any environment, it is unusual for you to ever issue any open commands. Most online programs (cont.)<br />simply use the implicit opens. If you do need to issue explicit opens in online programs, remember that each (cont.)<br />transaction constitutes a complete process and all files are closed as the screen is sent back to the operator. If you (cont.)<br />need to use an explicit open, it will have to be repeated for every transaction, i.e. do the open command in the (cont.)<br />%PREINIT insertion point.<br />## <br />Default Opens<br />When your batch programs access files and invoke the implicit opens, a default open type is used by MAGECIO. The (cont.)<br />default open type is OPENU (open for input-output). This default open type is set when your program is initiated. You (cont.)<br />can alter the setting of the default open type, if you wish. If you alter the setting, the new setting will apply to (cont.)<br /><br />next: db12.md.txt