Who Should Read This Guide

  • This guide is written primarily for use by those persons who will be responsible for defining and maintaining the definitions of database, VSAM, ISAM, or BDAM files which are to be accessed via MAGEC applications. Since MAGEC is a "dictionary-driven" system and since the components of MAGEC are thoroughly integrated it is also advisable that application developers and security officers be familiar with the material covered in this guide.
  • Copies of this guide should be distributed to:

  • Application developers
  • Security officers
  • Database administrators
  • System programmers
  • Auditors
  • This book is not intended to replace the online documentation but to augment it. Though there is some overlap, this book takes a grander, more general perspective while the online documentation is usually aimed at the particular Function the operator is dealing with at a given time. You can invoke the online HELP facility from any online screen shown in this book by pressing the HELP key (PF1); field-level HELP is also available by positioning the cursor to the field in question and pressing the field-level HELP key (PF2).

    Prerequisite Reading

    This guide is written assuming that the reader is familiar with the overall MAGEC philosophy. It presumes that you understand how the "standard set of nine" Functions work and that you are familiar with the standard screen formats of MAGEC. We suggest that you first read the MAGEC Application User's Guide, if you have not already.

    Types of Files Supported

    MAGEC applications normally do all their file I/O via the I/O module (MAGECIO). They tell MAGECIO what they want to do and to what Data Class (usually means "file") by moving parameters into a Request Area and PERFORMing the CALL routine:

    from any MAGEC program:


    MAGDBMS is an old entry point into MAGECIO used for compatibility with older releases of MAGEC. MAGECIO provides a variety of services for the application programs (MMP's). It, of course, issues the appropriate TP monitor command to accomplish the requested I/O. It checks for bad return codes from the Access Method or Database Management System (DBMS). If a return code indicates that an error occurred which could not be corrected by the application MMP or user then it issues an appropriate error message and aborts the task with a dump. An example of this type of error is a hardware failure. In another section of this chapter, Appendix A, Error Codes and Messages, there is a list of possible errors.

    If the file being accessed is defined according to recommended MAGEC standards then it will probably have an Audit Stamp. An Audit Stamp is a 36-byte portion of the record (defined as a separate Element) which is used by MAGECIO to record Who, Where, and When this record was last updated/added. MAGECIO maintains the Audit Stamp data on every file update. It has proven a valuable aid for security and debugging.

    MAGECIO provides the application programs a high degree of "transparency" or "portability" from any one of the supported access methods or DBMS's to any other. For example, an application may be developed to access a file which is VSAM KSDS at the time of development but which is later converted to Datacom DB. The program need not be changed or even recompiled when the file is converted. Simply altering the appropriate parameter in the MAGEC Dictionary via the online Functions provided will indicate that MAGECIO is to now access the file using the new "access method". In the rare case where an application MMP must access a file type which is not supported by MAGECIO, then it (the Cobol MMP) may use the standard TP monitor facilities (such as: EXEC CICS ...) to do so. In that case the file need not even be defined to MAGEC's Repository.

    The valid access methods to use with MAGEC applications are:

    KSDS Key Sequenced VSAM
    VSAM Key Sequenced VSAM
    KSDSU Unblocked KSDS
    ESDS Entry Sequenced VSAM
    RRDS Relative Record VSAM
    DATACOM Datacom DB
    MAGCMPRS Compressed VSAM files (PC)
    ISAM Indexed Sequential
    BDAM Basic Direct Access Method
    BDAMB Blocked BDAM
    DLI IMS or DLI databases
    SQL -or- DB2 DB2 or SQL/DS or Oracle, etc.
    SEQDS -or- SEQCMPR Sequential file -or- Compressed sequential file
    SEQCRLF Text file using CR/LF

    Defining File to TP Monitor


    In an IBM PC (or compatible) environment MAGECIO supports VSAM and Datacom DB files. Actually both are a simulation of the mainframe access methods and both work identically to one another and to the mainframe. One major difference is in how you create and initialize new files on the PC. The MAGINIT jobstream both creates and initializes new files, eliminating the need for the IDCAMS or DDCFMNT utilities used on the mainframe. PC MAGEC also eliminates the need for the DFHFCT or WESTIFG macros or "access tables" used on the mainframe to define the files to the TP monitor.

    CICS and WESTI

    Under CICS or WESTI, MAGECIO supports VSAM, ISAM, BDAM, and Datacom DB files. The application MMP's need not even be aware of which access method is employed for a given file since MAGECIO will interrogate the Dictionary definitions to determine how to access each file. The Dictionary definitions are loaded into main memory at system start-up time in order to eliminate the run-time overhead of accessing the Dictionary files. A special Function Code is provided for database administrators and security officers to dynamically reload the data into main memory if changes have been made. The Function Code is:

    **LOAD (keyed into SFUNCT)  

    The **LOAD Function requires no key value and any data in SKEY will be ignored and discarded. The data which is loaded includes:

    FCD---Function Code definitions

    KYF---Database Key definitions

    DCL---Database Data-Class definitions

    ELT---Database Element definitions


    When the loading is completed a message will be returned which shows the number of Function Codes (FCD's) in the system. While the loading operation is in progress MAGEC will be "quiesced". If an operator attempts to enter any Function Code he/she will receive the message:


    The operator may wait and re-press the ENTER (or other) key and the transaction will be processed as normal (if the loading operation is now completed).

    Datacom DB files to be accessed via MAGECIO must be defined in a "file table" as described in the DBMS's manuals. They must also be defined to MAGEC's Dictionary. The Data Class definition is always required (on the DCL file), the KYF definition is also required. The ELT definitions are not required since the DBMS's Element definitions will be used; however, the ELT definitions are required in order to permit entry of the Data Item (DIT) definitions which are, in turn, required for a number of other automated features.

    VSAM files to be accessed via MAGECIO must be defined via the standard IDCAMS utility and via the CICS FCT or WESTI WESTIFG file definitions. The online start-up JCL must also include the appropriate DD or DLBL statements for the VSAM files. The DD name (or DLBL name) must be entered into the file's KYF definition, spelled exactly as it is in the FCT or WESTIFG and in the JCL.


    MAGEC supports only VSAM files (KSDS, RRDS, and ESDS) in the VM/CMS environment. The standard AMSERV utility is used to create new files and the MAGINIT utility will initialize them once they are created.

    Initializing VSAM Files

    MAGEC provides a utility program that makes it easy to initialize new VSAM files that are not loaded using the standard IDCAMS REPRO utility. The MAGEC offline utility jobstream MAGINIT allows you to initialize a new VSAM file, once it is defined to a VSAM catalog. This means there is no longer any need for you to write a one-time program to initialize your files before they can be used by your application programs. For additional details on executing MAGINIT, refer to the MAGEC "Offline Utilities" chapter.


    Defining the Data Class

    DCLxxx Functions

    To add new Data Classes or to alter the definitions of existing ones use the DCLxxx Functions and the Data Class Definition Screen. The standard set of nine Functions is provided to allow adding, updating, inquiring, and browsing against the DCL file.

    In most cases a Data Class is actually a "file". It is possible, however, to define more than one Data Class for a given file. One reason for doing this would be to simplify the accessing of a file which really contains multiple record types with different lengths and formats. Each type could be defined as a separate Data Class but all would specify the same DD name on the KYF definitions associated with them. MAGECIO would then access the same physical file for all of them but would use different parameters for each.

    The DCL definition is required for MAGECIO to access the file at all. If the Access Method is not Datacom DB, then the KYF and ELT definitions are also mandatory. If they are missing then MAGEC will issue an Abend Code of DB99 when any MMP attempts to access that file.

    If a new DCL definition is added or an existing one is altered and the changes are to take effect immediately without waiting for the system (CICS, PC, WESTI, etc.) to be taken "down" and restarted, then the **LOAD Function Code should be used to cause MAGEC to immediately reload its main-memory images of the Dictionary data.

    If you successfully add a new DCL (via DCLADD) then MAGEC will assume that the next thing you want to do is to add the KYF definition for the Primary key and will automatically present the KYFADD screen for it.

    You may not delete a DCL definition if there are any KYF or ELT definitions still on file for it. You must first use the KYFDEL and ELTDEL Functions to delete them, then use DCLDEL to delete it.

    In the Data Class Definition Screen shown in Figure 01, the key value in SKEY is always a 3-character Data Class name. The name might be "CUS" for Customer Master file, for instance. In Datacom DB files this is the actual file name.


    is a 30-character field which may be any appropriate description such as "Customer File". It may not be left blank. If the Access Method is SQL or DB2 then this field may be used to contain the SQL table name - also refer to the KYF DDNAME discussion later in this section.

    Critical File (Y or N)

    is a yes or no specification which indicates (Y) that this file is one of MAGEC's critical files. In the event that the MAGEC Control Program and I/O module run out of space to load file specifications, the critical files will be given priority so that they do get their specifications loaded into the in-memory tables used at execution time.

    The remaining technical description(s) for the Data Class are defined as two parallel sets, TEST and PRODUCTION. In the MAGEC User Views TS01 through TS08 the TEST parameters apply, in the User Views PR01 through PR08 the PRODUCTION parameters apply. You may, thus, have similar but different test versions of your database files.

    Recording Mode

    may be F (fixed length records) or V (variable).

    Max Record Length

    is the logical record length (LRECL). The maximum length supported by MAGEC is 32,700. If the file is Variable Length then you must add four (4) to the actual maximum record length in order to accommodate the extra four bytes which CICS will prefix the record with. The extra four bytes contain the length in binary of the record read. Also refer to the topic, Variable Length, found in the Defining Elements section of this chapter.

    Audit-Stamp (Y or N)

    indicates whether or not this DCL is to have a 36-byte Audit Stamp within each record. The Audit Stamp will be automatically updated to show Who, Where, and When each record was last updated or added. MAGECIO does all the work of maintaining the Audit Stamps and does not allow the MMP's to corrupt (update) them. If the file does not have an Audit Stamp enter N. If it is to have one then enter a Y here and remember that you must reserve 36 bytes for the Audit Stamp Element (number 00), usually the first 36 bytes of the record.

    Real Delete (Y or N)

    must be Y if the Data Class does not have an Audit Stamp. This means that when an MMP requests to delete a record it will really be deleted and unrecoverable (without a file restore). If the Data Class does have an Audit Stamp then you may specify either Y or N for Real Delete. If you specify N then MAGECIO will not actually delete the records, it will set a "delete flag" on in the Audit Stamp. This is called "pseudodeleting". Subsequent requests to read that record will be treated as if the record had actually been deleted, but the data will not be physically lost until you execute an offline "purge" program to actually extract the "flagged for delete" records (saving them on a history tape?) and physically delete them. The Audit Stamps will show Who, Where, and When they were "deleted". It is the responsibility of the application designer or developer to write the Purge program since MAGEC does not provide it.

     DCLxxx yyy

    M A G E C Data-Class Definition
    Data Dictionary Maintenance

      Data-Class= YYY
    Description: ..............................
     Critical File (Y or N): N
    Test Prod
    Recording Mode:  . .
    Max Record Length: .... ....
    Audit-Stamp (Y or N): . .
    Real Delete (Y or N): . .
    Data Base ID: ... ...
    Block (CI) Size: ..... .....
    Access Method: ....... .......

    Gateway Name: ....... .......

    Figure 01 --  Data Class Definition Screen

    The combination of the Audit Stamp with the "pseudodelete" (Real Delete = N) option and the maintenance of a history tape might enable you to:

    as well as many other things. Not all data is sensitive and needs such protection but much of your data would likely benefit from it.

    Real Delete (Y or N) continued

    The purge program msut be a batch program, since the online I/O module will not allow you to read, much less delete, the pseudodeleted records. The batch program should use the normal MAGDBMS batch I/O module. Before the first access to the file it must call MAGDBMS using the special command "*PURG", which indicates to the I/O module that this program is to be allowed to read and update or delete pseudodeleted records, as if they were any other record. It is the responsibility of the purge program to interrogate the audit stamp (Element 00) and to take the desired action with the records.

    Data Base ID

    applies to Datacom DB files and should be left as 000 for others.

    Block (CI) Size

    is the physical size specified in the IDCAMS or database creation parameter.

    Access Method

    defines what type of file this is. Valid types include:

    Code MeaningNE =

    BDAMB BDAM Blocked
    DLI DL/I
    SQL DB2, DQL/DS, Oracle, etc.
    DB2 DB2
    KSDSU Unblocked KSDS
    TDP TeraData

    The valid types currently supported by your installation of MAGEC are defined on the MAGEC Lookup Table #200. To see them use the Function Code:TBLLST 200. It is permissible to define TEST and PRODUCTION as having a different Access Method, perhaps to accommodate a conversion.

    Gateway Name

    specifies the name of the gateway (or host) machine which is used to access this Data Class. If this is blank or set to LOCAL, MAGECIO assumes that this data is accessed via ordinary local access. If a gateway name is specified here, all accesses to this Data Class's records is done via issuing a TCP/IP request to the named machine, which will process the I/O command requested and return the results. If MAGEC's TCP/IP networking feature is not installed you should always specify LOCAL (or blanks) here. Gateway Names are defined in MAGEC Lookup Table #248.

    Remember, use the **LOAD Function to tell MAGEC to reload its main-memory images of the Data Class (and other) definitions when you are ready for them to take effect.


    For Data Classes having an access method of Datacom specified on their DCL record, MAGEC supports alias names for keys and elements.

    The screen depictions on the following pages do not include several special screen fields which will appear only if the access method is Datacom. These additional screen fields allow you to specify to MAGEC the actual Datacom/DB names for keys and elements. If the name given to MAGEC is the same as the name used in the Datacom/DB definitions then it is not necessary to enter anything into these special fields; however, if they are different you must enter the actual CA Datacom names into the screen fields when they appear.

    Many MAGEC users who also use Datacom/DB implemented both products simultaneously, or implemented MAGEC first, then Datacom. In these cases they normally will have adopted MAGEC's naming standards universally and will have no need for alias names. Some users; however, already had a large number of Datacom databases in place at the time they implemented MAGEC and may not have adhered to MAGEC's naming conventions. These users will have need for the alias names.

    MAGEC requires that the primary key (master key) be named as: xxxK1 (where xxx = Data Class name.) Alternate keys (subordinate keys) must be named xxxK2, xxxK3, et cetera. If your Datacom key names are different from this standard you must enter the definitions to MAGEC according to MAGEC's standards, but also enter the true Datacom/DB key names into the screen fields which as for "CA DD Name" on the KYFADD/KYFCHG screen.

    If you leave the CA DD Name field blank, MAGEC defaults it to the MAGEC key name.

    Similarly, MAGEC requires that your elements be named xxx00, xxx01, et cetera. Special meaning is attributed to certain element names, i.e. xxx00 is an Audit-Stamp, xxx99 is the Record Descriptor Word for a variable-length record (for those access methods which support variable-length).

    If your Datacom/DB element definitions use names which do not follow MAGEC's standards, you must provide the actual Datacom/DB names into the screen fields asking for the CA Element Name on the ELTADD/ELTCHG screen.

    MAGEC's I/O module will substitute the Datacom/DB names for the MAGEC names just prior to requesting for I/O services from Datacom/DB. Your programs will use only the standard MAGEC names. If you decide to convert one or more of your data files from Datacom to VSAM, or from VSAM to Datacom, no program changes or recompiles need be done.

    Defining Keys

    KYFxxx Functions

    To add or change Dictionary definitions for file keys, use the Key Definition Screen and the KYFxxx Functions. The standard set of nine Functions is provided to support adding, updating, inquiring, and browsing against the KYF file. The key value is always the 5-character key name which is in the format: yyyKn, where: yyy = the Data Class name, K= the constant "K", and n= key number (1 thru 9)

    Key number 1 is always the Master (Primary) key. Keys numbered 2 thru 9 are Subordinate (Secondary) keys. These key definitions are used in the MAGECIO module and they are used by the program generator MMPCREAT to define the rules for "Normalizing the Key". See Figure 02 for a sample KYF screen.

    Key Name

    simply re-displays the 5-character (yyyKn) name.


    is up to 30 characters and may not be blank.

    Cobol Name

    is the actual dataname from the copy-book definition which defines the entire key field(s). It may be a group dataname. IT SHOULD NOT BE A NUMERIC (PIC 9..) FIELD. This entry is required for the Master key (key 1) and optional for Subordinate keys. It is required that the Master key (and all keys in VSAM) be one contiguous area within the record and that it have a single dataname so that MAGEC can generate a single MOVE to it in the MMP's.

    File Specification

    is the alphabetic LAN, UNIX. or PC path and file name (ignored in mainframe environment), which is optional.

    DD Name

    is the actual name (up to 8 characters in MVS, 7 in VSE, 8 in PC/LAN MAGEC) as the file is defined in the DD or DLBL JCL statements for the TP monitor start-up deck. For Datacom DB files this is comments only. It is possible for more than one KYF definition to specify the same DD name, thus allowing multiple definitions for the same "file" which may be used differently by different applications. One purpose for doing this might be to process different kinds of records in different formats on a single file. While we do not necessarily recommend that you design files having multiple record formats, MAGEC can be used to access them if they exist. For SQL or DB2 this is the table name, or if this is specified as an asterisk (*), the table name will be taken from the DCL description discussed earlier.


    is the position in the actual record at which the key area begins. If the key begins at the very start of the record (very common) then this would be 0000. If the file is Variable Length records, then there will always be a 4-byte record prefix appended. If the key field(s) begin in the very first bytes of a Variable Length record then the Displacement should be 0004. If the file has an Audit Stamp, the first 36 bytes will normally be designated as the Audit Stamp element (starting at displacement 0000 or 0004), other elements (and the key) will begin beyond the Audit Stamp.


    is the physical length in bytes of the key in the record. It must agree with the IDCAMS, AMSERV, or Database definition for the file (DD Name, if VSAM, ISAM, or BDAM).

    Dup Key Flag

    is a Y or N option which defines whether or not duplicate key values are allowed. This applies only to alternate (subordinate) keys, not to the primary (key #1). The prompt for this parameter will not appear on the screen for the definition of key number 1.

     KYFxxx yyyKn

    M A G E C Data Dictionary
    Key Definition

      Key Name yyyKn Description: .......................
     Cobol Name: ................................ DD Name ........
     File Specification (PC or UNIX Only)
    Extension after file is processed: ____
     Displacement: .... Length: ....  Dup Key Flag: . (Y = Duplicate keys allowed)

     ---------------------------Component Fields-------------------------------
      Field 1 Field 2 Field 3 Field 4 Field 5
    max min type  max min type  max min type  max min type  max min type
     ... ...  .  ... ...  .  ... ...  .  ... ...  .  ... ...  .
      Field Types A = AlphaNumeric
      N = Zoned Decimal Numeric WITHOUT Sign
      Z = Zoned Decimal Numeric WITH Sign
      F = Packed Numeric WITHOUT Sign
      P = Packed Numeric WITH Sign
    B = Binary Numeric
    Press PF4 for browse (LOC) screen  Press PF13 for Hardcopy
    Press PF16 to Copy field to buffer  Press PF17 to Paste data from buffer
    Press PF12 for field-level HELP

    Figure 02 --  Key Definition Screen

    NOTE: In the PC and LAN environments of MAGEC this field enables you to specify the drive (which may be a logical LAN drive) on which the data file and its indices exist. This allows you to have MAGEC installed on one LAN drive and to have your data files distributed across many drives, including having some on your local (C: or D:) drives. In MAGEC release 3.0 and later, this field is expanded to 79 bytes in length, allowing you to specify a complete filespec, including drive, path, and file name. If you specify an asterisk or space as the alphabetic drive ID, MAGEC will replace it with the LANDRV setting from your environment. If you leave the path and file name blank, MAGEC will use the default path and will use the DD Name as the file name. For example: if you specify "MYFILE" in the DD Name, and "J" in the Drive ID, and you are using MicroFocus Cobol, MAGEC will build a filespec of: J:\MAGMF\MYFILE.DAT. The ".DAT" extension is mandatory.

    The Component Fields are the fields (up to 5) which make up the key. Max, min and type must be specified for each key component. At least one key component must be defined for the key. See the Key Normalization section of this chapter for further discussion.


    is the expanded size of this key component in characters (or digits, if numeric).


    is the minimum number of characters the operator may enter for this component.


    is the data type as shown on lower portion of this screen.

    Test & Production Files

    If you would like to have test and production versions of your files then you may use a "symbolic" DD Name. A symbolic name is one which incudes the ampersand character (&) anywhere within it. All Test MAGEC User Views will replace the ampersand(s) with the letter "T"; all Production User Views will replace it with a "P".

    Suppose you had a Production Customer Master file with the DD Name of:

    CUSMASP and a Test version of it with the DD Name of:

    CUSMAST Then you would simply specify the symbolic DD Name of:

    CUSMAS& Your MMP's would access the Test file if executed from any Test User-View (TS01 thru TS08) and would access the Production file when executed from any Production User-View (PR01 thru PR08).

    All the other Dictionary definitions associated with the CUSMAS& file also have provision for Test and Production profiles, as you will see in the following topics. In all cases the Test profiles apply in all Test User Views and the Production profiles apply in the Production User Views.

    Key Normalization

    The definitions of the Component Fields (up to 5 of them) are used by the program generator MMPCREAT to control the key Normalization logic which edits and formats the SKEY data into the proper representation for accessing the file. Max is the number of digits or characters which the component consists of in its DISPLAY form. A 9-digit packed field may be only 4 bytes long on the file but it is 9 digits long when displayed on the screen or entered onto the screen and therefore is defined with Max = 09. Min is the minimum number of digits or characters which you wish to permit the operators to enter when entering this key component. If Min is the same as Max then the operators will be required to enter the entire value, leading zeros and all. Min must not be larger than Max and may be 00. The MMP's will "pad" the entered key value with leading zeros (if numeric) or trailing blanks to the length specified in Max. They will automatically convert the numeric values to packed or binary format if appropriate.

    Type indicates whether this key component is numeric or not and if it is numeric whether it is signed or not and whether it is packed or binary or zoned-decimal. We recommend that file keys be made up of alphanumeric and zoned-decimal data without signs unless particular circumstances do not permit. Experience has shown that packed key fields and ambiguities regarding signs (+ ) can cause difficulties and confusion. MAGEC in no way causes or exacerbates these problems but it does not solve them either. If you do have files with packed and signed key fields they will be handled properly by MAGEC but it is still your responsibility to know whether a given record's key is signed with a C or F for positive or with a D or E for negative.

    If you successfully add a new KYF definition then MAGEC will assume that you will most likely next want to add a new Element definition for the Data Class and will automatically present the ELTADD screen to you.

    You may not add a KYF definition unless the Data Class is already defined (via DCLADD). Remember, if you wish the new definitions to take effect immediately (without waiting for the online system to be brought "down" and "up"), then you must use the **LOAD Function.


    Unless a filespec is specified (refer to Drive ID in Figure 02), all data files must be in the \MAGxx directory and be named following the format:


    where: xxxxxxxx = DD Name specified in the KYF definition. The symbolic ampersand character (&) is not supported in PC MAGEC. The .DAT extension is always required. With MicroFocus Cobol implementations a .IDX file is created automatically. It is the index for the .DAT file of the same name.

    Alternate Indices

    MAGEC supports alternate keys for any access method which permits them (primarily: VSAM, Datacom DB, and simulated VSAM in PC MAGEC). To define an alternate key (also called a Subordinate Key) simply do the KYFADD function for yyyKn (where yyy = Data Class name, n = digit from 2 thru 9). In the event you have more than nine keys for a single file you may use alphabetic "key numbers", but you may need to do some customization in generated programs trying to access that file. MAGEC will automatically generate the logic to support up to nine keys for all browse and query functions. All that you need do is have the KYF definitions on file at the time the MMP is generated. For file maintenance functions MAGEC always generates the logic to process only using the Primary Key (key 1).


    Key HELP

    When an operator is using a MAGEC-generated application and mis-enters the key value (on top line of the screen) and receives the "Invalid Key Format" message, he/she can press the HELP key (PF1) to receive online help text. You can store your own text (unlimited length) associated with any file key, or MAGEC will generate a default key format display to help the operator. Refer to the "Documentation" chapter for more details on Key HELP.

    Defining Elements

    ELTxxx Functions

    To add new Element definitions or to update existing ones use the ELTxxx Functions. The standard set of nine Functions is provided for adding, updating, inquiring, and browsing against the ELT file.

    You may not add an Element definition unless the Data Class definition is already on file (via DCLADD). The key for the Element Definition Screen is the 5-character Element name in the format:


    where: yyy               = Data Class name

    nn               = Element number (00 thru 99)

    A sample Element Definition screen is shown in Figure 03. The data fields used by the screen are described below.

    Element (Segment)

    is a display-only field which contains the Element name, in the format described above.


    is a protected field used to display the Data Class description associated with the Data Class name which is the first three characters of the Element name.


    is the 30-character description for this Element, and is a required field.


    occurs twice, once each for test and production. This is the starting position of this Element in the record (relative to zero).


    occurs twice, for test and production. This field contains the length of the Element in bytes.


    contains the authority level required for a developer to create applications which access this Element from batch programs (MBP's).


    contains the authority level required for a developer to create applications which access this Element from online programs (MMP's).

    Employee having temporary Exclusive Control

    is the employee number (name displayed on the line below) of the employee who currently has exclusive control over this Element definition and its associated Data Items (DIT's).

    An Element is simply any portion of a record. It is defined as being an area, one or more bytes long, which begins at a specified displacement into the record and continues for the specified length. If you had a fixed-length record 100 bytes long and wanted to define it as one single Element then that Element would begin at displacement 0000 and have a length of 0100. If, however, you wanted to define the record as two Elements you might define one Element as starting at displacement 0000 for a length of 0045 and the second Element as starting at displacement 0045 for a length of 0055. The term "displacement" means the position in the record relative to zero (the first byte is at displacement 0000). Another way of expressing that is "the number of bytes preceeding this".

     ELTxxx yyynn

      M A G E C Data Element Definition
    Data Dictionary Maintenance

      Element (Segment)= yyynn data-class

      Description: .............................

      test production
    Displacement: ..... .....
    Length: ..... .....

    Employee having temporary Exclusive Control: .........

    Figure 03 --  Element Definition Screen

    An Element is the "unit of transfer" between MAGECIO and your programs. By intelligently dividing your records into Elements you can gain a degree of "data independence" for your applications. For instance, if a program uses only the first 45 bytes of data (let us say that is the demographic portion) then it should only "read" that much. If you discover that you must change the record format because you must add more data fields, lengthening the record and lengthening the second Element described in the above paragraph, then it is likely that you will not even have to recompile the program which reads only the first Element.

    If another program requires both the first and second Elements it may read both in one CALL with no added overhead. That program would be affected by changes made to either of the two Elements. MAGEC allows you to define up to 99 Elements for a Data Class plus the special Element number 00. Remember, also, that a given physical file may be "redefined" by multiple Data Class definitions, each of which may have its own KYF and ELT definitions. Element number 00 is the name of the Audit Stamp element which must be 36 characters long. If the Data Class does not have an Audit Stamp (as specified on the DCL definition screen) then there should not be an Element 00 at all. If the Data Class does have an Audit Stamp then Element yyy00 must be specified (where yyy = Data Class name) as a 36-character element, it usually begins at displacement 0000 into the record (0004 if variable length).

    When defining the Elements which make up a record we recommend that you assign Element numbers in ascending order starting with 01 (00 for the Audit Stamp) and starting at the beginning of the record proceeding toward the end leaving no gaps in either Element numbers or in bytes of the record left undefined.

    We also recommend that you do not allow any Element to overlap any other. It is possible that a future release of MAGEC will not permit overlapping Elements, for now they are just "advised against". If a file is "redefined" as multiple Data Classes then, of course, the Element definitions for one Data Class will be allowed to overlap those for the other(s). The rule against overlapping Elements applies only within a Data Class.

    In order to minimize the impact of file changes it may also be a good idea to leave a little FILLER space in each Element to accommodate minor changes without having to reformat the files.

    Variable Length

    MAGEC supports variable-length records for access methods which allow them, normally that means VSAM KSDS and PC MAGEC's simulated VSAM. When MAGEC's I/O module accesses a variable-length record it places a 4-byte prefix in front of the actual record data. For all intents and purposes those four bytes are a part of the record. The four-byte prefix contains the record length of the record just read. If you are updating records on a variable-length file then you can set the length by moving it into this area, that will determine the number of bytes written or rewritten to the file. In most cases it is useful to know the length of the record even when the file is only being accessed read-only. We recommend certain standards regarding the definition of Elements for variable-length files.

    We recommend that the 4-byte length prefix be defined as an Element having a displacement of 0000 and a length of 0004 and a name of "yyy99". That also means that the first "real" Element would have a displacement of 0004. If the file has an Audit-Stamp which is the first thirty-six bytes of the actual record then Element "yyy00" would have a displacement of 0004 and a length of 0036; the next data Element would have a displacement of 0040, and so on.

    When defining the Data Class (DCL) it will be necessary to specify a maximum record length of four-bytes greater than the actual largest possible data record to accommodate the addition of the length prefix. It is also necessary to specify the key(s) (in the KYF definitions) with displacement(s) four greater than you would if the records were fixed-length. For example, if your variable-length record has a 36-byte Audit-Stamp followed by the key field, the KYF definition would specify a displacement of 0040, rather than 0036.

    Remember, in order for changes to ELT file definitions to take effect immediately without waiting for the online system to be taken "down" and back "up" you must use the **LOAD Function to tell MAGEC to reload its main memory images of the Dictionary definitions.

    For example; to define a variable-length, audit-stamped record with a length of from 20 to 100 bytes, with a 5-byte key immediately following the audit-stamp:

    Max Length (on DCL definition) = 104

    Element xxx99, displacement=0000, length=0004

    Element xxx00, displacement=0004, length=36

    Element xxx01, displacement=0040, length=64

    Key xxxK1, displacement=0040, length=0005

    Element 99 Format

    For variable-length records the 4-byte record prefix should be defined as a separate Element (number 99). This special Element should have a displacement of 0000 and a length of 0004; it should also be defined as containing three Data Items (DIT's). The first one is the standard group item defining the entire 4-byte Element, the other two are the component (elementary) fields which make up the Element. One of them is the 2-byte binary field containing the record length in bytes, the other is a 2-byte "padding". They should look like:

    04  xxx99-ELEMENT.

    	05  xxx99-LGTH          PIC S9(4) COMP.

    	05  xxx99-PAD           PIC S9(4) COMP.

    It is wise to be sure that the pad field is set to zero (low-values) and the length field is set to the desired record length before any add or update operation. Setting the length properly is the responsibility of the application developer.

    When a program, either an online MMP or a batch program, accesses data from a variable-length file it should specify the 99 element as part of its Element List. If the program reads data and does not include element 99 then the record length will not be returned to it. If that program updates without setting the length (which it cannot do if it has not read element 99) then the MAGEC I/O module will set the new length equal to the old length -- which may or may not truncate some data from the record.

    Cobol Copybook

    Copybook for use in MMP's

    In order for the generated MMP's to properly access data from the database or files they must have a Cobol copybook which defines the Element(s) being read. In the case of preexisting files it is likely that a copybook already exists on some library, however, it is unlikely that it will be ready for use by the MMP's without a few minor adjustments.

    Most of your existing data definition copybooks probably start with a Cobol level of 01. In MAGEC these data definitions need to be included into an area called the TWA, actually they need to be included into an area within the TWA called TWA-DB-DATA which is a level 03 item in the TWA. It stands to reason then that the copybooks for MAGEC must begin with a level number of 04 or higher in order to compile correctly.

    Your preexisting copybooks are probably stored on an IBM PDS or source library. It is possible to COPY them from such libraries (or others) but we recommend that they be stored, instead, on the built-in MAGEC library. The MAGEC library is accessible via MAGEC in the normal online development process and when the program generator (MMPCREAT) generates the MMP's it assumes that the copybooks are on the MAGEC library and inserts -MAGECINC statements accordingly.

    There is a utility program (batch) provided which may be used to catalog a copybook (or any other member) to the MAGEC library. The utility is named MAGECLBR. It is fully documented in the "Offline Utilities" chapter.

    If you do not have a preexisting copybook to load to the MAGEC library then you may use the online Functions to add it. In either case the copybooks must be named according to the MAGEC standards. There must be a copybook for each Element. In the case of a preexisting file you likely have a copybook for the entire record and you will likely also define the entire record as one Element. For new files you may wish to take better advantage of the Element concept.

    The name of the copybook for an Element must be:


    where: eeeee               = Element name

    -C               = the constant "-C"

    To use the MAGECLBR utility program to add a copybook you might code a control card (for MAGECLBR) as:

    -MAGECADD LIB eeeee-C  

    followed by the actual data "cards" to be added. To add a copybook via keying it directly into the MAGEC library online you would use the Function Code LBRADD (and LBRCHG, etc.) as:

    LBRADD eeeee-C//ppp  

    where: eeeee-C               = member name

    ppp               = page number

    A page is one screenful of data (15 lines) and a member may consist of up to 999 pages. Each page is actually one record on the MAGEC Dictionary file named the ALG file.

    Just as in any other environment it is important that the copybook is correct and that it defines the data accurately. One of the common errors made is to define a copybook which is not as long (in bytes defined) as the data actually is. When a program (MMP) reads an Element (or Elements) MAGECIO returns data for the length specified in the ELT file definition for that Element(s). If the copybook defines a smaller area than the ELT file it is possible that you will overlay whatever is below. In most cases the MAGEC-generated MMP's will detect this circumstance and will issue an error message and abort. The message is:

    ++ TWA CLOBBERED BY I/O ++  

    In cases where the MMP's do not detect the error unpredictable results will occur. Check your definitions carefully.

    An example of the Cobol copybook to define an Invoice file with one Element and having a key of Customer number and Invoice number concatenated is:

    04 IVC01-ELEMENT.

    	05 IVC01-MASTER-KEY.

    		06 IVC01-CUSTOMER      PIC 9(5).

    		06 IVC01-INVOICE       PIC 9(6).

    	05 IVC01-DATE             ....

    - etc.

    This would be on the MAGEC library as a member named IVC01-C and could be viewed or altered online via: LBRSEE IVC01-C. Notice that the Master key is defined as a group level item and broken down into its components. The group name IVC01-MASTER-KEY would be specified on the KYF file definition for IVCK1 and could be seen via the online Function:


    Recommended Standards

    The following topics set forth recommended standards for your data definitions and copybooks. We recommend that you use the MAGEC Dictionary's DIT file (Data Item file) to define your data and to generate your copybooks.

    We realized that it may involve some extra effort to convert your preexisting data definitions to conform to the recommended standards and to enter the definitions into the Dictionary; therefore, we have provided a facility in the MAGECLBR utility program to automatically generate DIT file definitions from your old copybooks.

    Your extra effort will be well rewarded since the definitions in the DIT file will enable MAGEC to provide a wide variety of services for you. The online access to the definitions is very useful for database administrators to maintain central control of the database. The online application development processes access the DIT file to validate developer's specifications and to provide intelligent default values. The DIT definitions help MAGEC to determine how to properly translate from ASCII to EBCDIC and vice-versa when your program is accessing data from foreign files via MAGEC's TCP/IP networking feature.

    Defining Data Items

    Cobol Datanames

    In order for MAGEC to be of the greatest value to you we strongly recommend that you adhere to some special naming conventions for your Data Items (fields within an Element). Remember, the Record of a Data Class (DCL) may be broken down into one or more Elements.

    Each Element (ELT) may be broken down into one or more Data Items (DIT's). An Element, therefore, may be looked upon as a contiguous group of Data Items within the Record.

    Name Prefix

    As you might have guessed from examples shown earlier in this book we have established a standard that all Cobol datanames for Data Items are prefixed by the name of the Element in which they appear. The name of a field (Data Item) which is to contain the Customer's balance and which is within the Element named CUS02 might be:


    Similarly, all other fields within Element CUS02 would be named:

    CUS02-something-or-otherBecause of the Cobol limit on length of datanames "something-or-other" must not be longer than 24 characters. Of course, it must also conform to all other Cobol restrictions regarding special characters, etc.  

    ELEMENT Group

    Each Element (ELT) must be defined by a copybook which is named according to the rules described earlier, i.e.:


    where: eeeee               = Element Name

    Furthermore, the first item in the copybook must have a Cobol level number greater than 03 since the copybook will be included in the generated programs under the item named: 03 TWA-DB-DATA. We recommend that the first item in the copybook be a group item which defines the entire Element and that it be defined as:

    04 eeeee-ELEMENT  

    where: eeeee               = Element Name

    We also recommend that it always be a Cobol level 04, as shown above.

    When you are defining the ELEMENT Group Item to the MAGEC Dictionary's DIT file you may let MAGEC automatically fill in the proper length for you. If the Item's Cobol level is 04 and the dataname is ELEMENT then MAGEC will lookup the length specified on the ELT file for that Element and place it into the length "PIC X ( )" automatically.

    Date fields

    In order for the Automatic Editing feature and the MMP generator (MMPCREAT) to properly handle DATE fields we recommend that DATE fields always be defined as follows:

    05 eeeee-xxxxxxxxxxxxxxxxxxxxx.  

    	06 eeeee-xxxxxxxxxxxxxxxxxxxxx-YY    PIC XX.

    	06 eeeee-xxxxxxxxxxxxxxxxxxxxx-MM    PIC XX.

    	06 eeeee-xxxxxxxxxxxxxxxxxxxxx-DD    PIC XX.

    where: eeeee               = Element Name

    xxxxx               = up-to 21-characters of dataname

    -YY               = designation of field containing year

    -MM               = designation of field containing month

    -DD               = designation of field containing day

    For dates with the 4-digit year, another 2-byte item is inserted above the -YY item which is named with the suffix -CC , to contain the century portion of the 4-digit year.

    The generated MMP will automatically move each of the date's components individually so that the screen-image of the date may be in some other format from that of the database field; i.e. MM/DD/YY, or DD/MM/YY. The MMP generator assumes that you will adhere to this standard and will use the suggested suffixes and that each of the component fields will be PIC XX, not PIC 99.

    Date fields on DIT definition

    When defining a Date field to the MAGEC Dictionary's DIT file it is not necessary for you to define the component fields. You should simply specify "M", "D", or "Y" as the Edit Type to indicate that the Item is a Date field. MAGEC will automatically calculate the proper length (either 6 or 8 bytes) for you. When you generate the Cobol copybook it will automatically create the component fields for you. For date fields you use the specification for Significant Digits (SIG) to indicate whether you desire a 2-digit year or a 4-digit year. An entry of 04 in the SIG specification denotes a 4-digit year, and entry of 02 (or any other value) defaults to a 2-digit year.

    Master Key

    MAGEC requires that you include a single Data Item in your copybook which defines the Master Key (Primary Key) for the file. There is no particular rule regarding the name for that Item. If the key is actually made up of multiple fields then the Item defining the Master Key may be a group Item with the key component fields defined below it as:

    05 eeeee-MASTER-KEY.  

    	06 eeeee-xxxxxxx           PIC .....

    	06 eeeee-yyyyyyy           PIC .....

    - etc.

    The data name MASTER-KEY is merely suggested, not enforced. The field should be either a group item or an alphanumeric item, not a numeric (PIC 9) item. The component fields may be any type of data, numeric or alphanumeric.

    When you defined the key definition (see KYFxxx functions) you specified the Cobol dataname of the key field. That name should match the name used in the DIT definition for that key field. The length (in bytes) of the field should match the length specified for the key in the KYF definition. If there is a discrepency, you will be issued a warning message at the time you have MAGEC generate the Cobol copybook for the Element.

    Creating a Copybook

    You may use your preexisting Cobol copybooks in MAGEC-generated applications by simply cataloguing them to the MAGEC library using the MAGECLBR batch utility program as explained earlier; or you may let MAGEC generate a Cobol copybook for you from MAGEC Dictionary data. In order to have MAGEC generate your copybooks you must first define the Data Items (DIT's) to the Dictionary.

    There are two ways you can define Data Items to the Dictionary:

    1) by keying the definitions into the online Dictionary maintenance screens (DITxxx Functions).
    2) by using another special feature of the MAGECLBR utility program to "read" your old copybook and automatically create the Dictionary definitions.If you use the second method you will probably also want to then use the online DITxxx Functions to look at and possibly modify the Data Item definition since default values will have been used for some parameters which could not be determined from the Cobol copybook.We strongly recommend that you use the MAGEC Dictionary to generate your "copybooks" since having the Data Item definitions available to MAGEC (via the Dictionary) is required for a large number of features and facilities which are either already implemented or are planned for future releases of MAGEC. We will continue to support the facility to catalogue books using the
    "-MAGECADD LIB" contol card (as described in an earlier topic); but we intend for it to be used only in those cases in which defining the data to the Dictionary is not appropriate (such as WORKING-STORAGE areas, etc.). To define Data Items to the dictionary using your Cobol definition (old copybook) as input you would use the "-MAGECADD DIT" control card in MAGECLBR. See the "Offline Utilities" chapter for more detailed instructions regarding MAGECLBR.

    DITxxx Functions

    The standard set of nine Functions is provided for the MAGEC DIT file to accommodate adding, updating, inquiring, and browsing. In addition, there are some extra Functions provided which allow you to resequence (renumber) the Data Items of an Element, to list the Data Items of an Element on the screen, and to generate the Cobol copybook of the Element using the DIT file definitions.

    The key format for the DIT file records is:


    where: eeeee               = Element Name, 5 characters

    m               = Mode, T or P, test or production

    999999               = Sequence #, 6-digits

    The Mode defaults to T whenever it is omitted. As you can readily see you may have a Test and a Production set of definitions for any given Element. As you can also see the sequence (order) of the Data Items is controlled by the 6-digit sequence number. We suggest that when you are initially adding definitions for an Element's Items you increment the numbers by 100 to facilitate insertions (a time-proven technique).

    If you reach the point where you have inserted a sufficient number of Items that you feel you are running out of available numbers to be used for further insertions then you may use the DITSEQ Function to renumber the Data Items (for that Element). DITSEQ will renumber in increments of either 10 or 100 (default = 100) allowing you to do more insertions. Detailed instructions for using all the DIT Functions are available online via the HELP key (PF1) at any time to anyone authorized to do the Function. Refer to the MAGEC Application User's Guide for instructions as to how to use the online documentation if you need to.

    The special Functions which are provided in addition to the nine standard ones are:

    DITLST               list Data Items for an Element

    DITSEQ               re-sequence Data Items for an Element

    DITGEN               generate Cobol copybook for an Element

    You will be unable to add a Data Item until the Element to which it belongs has been defined on the ELT file (via ELTADD). Further, you must get "Exclusive Control" of the Element (and all its Data Items) before you will be able to do any form of database updating Function to the DIT file. See the Exclusive Control of ELT section of this chapter.

    DIT Entry Formats

    The DIT Definition Screen is designed to resemble (as much as is possible) standard Cobol data definitions, including the Cobol level number and PICture clauses. Of course; there are some parameters which MAGEC records for which there is no Cobol equivalent, such as PROMPT. PROMPT is the desired column heading (for listings) or data entry prompt for 3270 screen formats, it is used by MAGEC automatic screen painting and offline report generation.

    All of Cobol's data definition features are included except for the ones used by the "Report Writer" compiler option and 66 and 77-levels.

     DITxxx EEEEE/M/999999
    M A G E C Data Item Definition
    Element .............................. Field Seq#: ...... Mode .
    Level: Data Name: Sig Dec Sign:  Usage:
    .. ..... ........................ PIC . 9( .. )V9( .. ) U  D
    EditType: . Tbl: ... Req: . Lgth: PIC X( ..... ) Just: .
      Occurs: ..... Depending On: ........................
    Redefines: ........................ 88-Val/Pattern: ....................
    Prompt: .................... Domain Name: ....................
      DataBase Identifier: ....................
    Data Item Narrative:  Offset / Length: ..... / .....
    Press PF4 for browse (LOC) screen  Press PF13 for Hardcopy
    Press PF16 to Copy field to buffer  Press PF17 to Paste data from buffer
    Press PF2 for field-level HELP 

    Figure 04 --  Data Item Definition Screen


    is a protected field which displays the Element description which comes from the definition on the ELT file.

    Field Seq#

    is a protected field displaying the sequence number portion of the key for this Data Item.


    is a protected field which displays the test or production mode (T or P).


    is a required field which is the Cobol level number to appear in the generated copybook. It must be 04 thru 49 or 88.

    Data Name

    is the desired Cobol data name to be generated in the copybook. Maximum size is 24 characters. MAGEC will prefix this name with the 5-character Element Name, plus a dash (-), giving a Cobol data name of up to 30 characters in the copybook.


    is the number of significant digits to the left of the decimal point (or implied decimal point) for numeric Data Items. For Data Items which are dates (type M, D, or Y) this value specifies either a 02 or 04 to indicate a 2-digit or 4-digit year (such as 88 versus 1988). For other (non-numeric) Items this value must be 00.


    is the number of decimal places (to the right of the decimal point) for numeric Data Items. For dates this value specifies the maximum age (in years) of a date which is to be accepted by the Automatic Editing.


    is a code indicating whether this Data Item is to be defined with a "sign" (PIC S9, etc.) in the generated copybook definition. A value of S indicates signed, a value of U indicates unsigned. For non-numeric Items this must be blank. Numeric SQL data items must be signed.


    is a code which specifies type of numeric data. It is only valid for numeric Data Items (as specified by the Type field described above). A value of P indicates Packed (COMP-3). A value of B indicates Binary (COMP or COMP-4). A value of D indicates Zoned Decimal (DISPLAY). Must be blank for non-numeric Data Items. Zoned Decimal illegal for SQL.


    is the MAGEC Automatic Editing Edit Type (such as N for numeric, or X for alphanumeric, or $ for numeric with "$$,$$$.99" type Cobol editing, etc.) This is used as a default or suggested Edit Type when the developer references this Data Item as a "Source/Target" field on the MSKDEF screen. It does not mean that the database copybook will contain the Cobol edit pattern. The generated database Element copybook will use an appropriate data representation for file data based upon this Type parameter and other parameters such as SIG, DEC, COMP, etc.


    is the Auto Edit Lookup Table number, if this is a type T item.


    is the Requirement code (R or O) to indicate that this Item is a Required entry on the Maintenance screen, or Optional.


    is the length (in bytes) of this Item. For numeric or date items MAGEC will calculate this for you. For alphanumeric items you must enter the length here. If the Level is 04 and the Data Name is "Element" MAGEC will fill in the length from the ELT file definition.


    is a code indicating that this Item is left justified or right justified. A value of L or R is accepted. If left blank L will be assumed.


    is the number of occurrences of this Item, if it is an arrayed Item. A value of 0 will indicate that this is not arrayed. A value of 1 is illegal. If you leave it blank, 0 will be assumed.

    Depending On

    is the Cobol data name of the control Data Item which contains the number of occurrences of an arrayed Item if there are a variable number of occurrences. If this entry is non-blank, then the Occurs value above is interpreted to be the maximum number of occurrences, the minimum being 0.


    is the data name of the Item which this Item redefines.


    is the pattern for Pattern Edited fields (Edit Type "P" or "#"). For 88-level items, it is the value which this Condition Name defines. You can enter the actual literal here (such as 900 or X) and the DITGEN function will generate the surrounding quotes if needed. You can also enter the name of a library member which contains the value or list of values. This enables you to use value clauses which are far larger than would fit in the 20-character screen field. To enter a member name, just prefix it with an ampersand (i.e. &member/modifier) and the DITGEN function will generate an include statement in the Cobol copybook.


    is the column heading to be generated above this Item on columnar lists (such as the LOC, SCN, and FND screens) or batch reports, and also as a screen prompt when MAGEC automatically generates maintenance screen layout.


    is the name (up-to 20 characters) of the Domain to which this Data Item belongs. MAGEC will enforce consistency in the definitions of all Data Items within a given Domain.

    DataBase Identifier

    is the up-to 20-character name used to identify this field to an SQL database. Used also to construct a Host Variable name. SInce an SQL identifier may not contain embedded spaces or hyphens, MAGEC automatically converts them to underscores. This is convenient since you cannot directly type an underscore into MAGEC screens because it is the universal fill character. SInce some SQL databases limit the identifier to 18 characters in length, you should limit your entries to 18 characters. In generating host variable names, MAGEC attempts to create unique names by prefixing them with the 5-character element name, if space permits, or with just the 3-character data class name -- or with nothing, if you have used more than 15 characters for your identifier. To ensure unique host variable names across multiple tables having identical database identifiers for some of their columns, limit your identifiers to 13 characters or fewer.The database identifier has no meaning for non-SQL data, it will be ignored. It is required only when the access method is SQL or DB2 (as specified on the DCL definition for the Data Class).

    Data Item Narrative

    is the 8-line free-form text field which contains the explanation and any other comments to describe this Data Item. When an online application user invokes the field-level HELP by pointing to a screen field with the cursor and pressing PF2, this text will be presented along with a textual description which is generated from the specifications above.

    Offset / Length

    is the calculated offset (within the Element) of this field, and its length in bytes. This is displayed for informational purposes only and is calculated by the DITGEN function described in Generating the Copybook, below. Until DITGEN has been executed these values are unreliable.


    You can specify Cobol 88-level items (Condition Names) below any Data Item. The 88-levels are defined as separate Data Items which may only have the VALUE parameter specified and no others, exactly as in the compiler. For numeric items you just enter the numeric value as: 99, or 23, etc. You may also enter ranges as: 101 THRU 199. In order to support lists of values too large to be entered into the 88-Val/Pattern screen field (above), MAGEC allows you to enter the name of a library member which contains the values. Refer to description above.

    Exclusive Control of ELT

    You must have exclusive control of the Element (and all its Data Items) before you will be able to do any form of database updating Function to the DIT file (DITADD, CHG, DEL, GEN, or SEQ). Exclusive Control means that only you are allowed to do any form of updating and all other persons will be prevented from updating that Element's Data Items until you are finished. This prevents the confusion which might result from more than one person making changes to the same Element. If you wish to see who has control of it, use the Function:

    ELTSEE eeeee  

    where: eeeee               = Element Name

    To get Exclusive Control of an Element, use the ELTCHG Function and then enter your Employee Number (same as you use to SYSLOG ON) into the screen field labeled:

    Employee Number Having Temporary Exclusive Control:  

    If there is already another person's Employee Number in that field you should check that he/she no longer needs to retain Control of that Element. On the other hand, when you are finished you can save someone else a bit of aggravation if you remember to remove your Employee Number from the ELT-record field by changing it to zeros.

    Allowing Multiple Persons Access

    In some cases you may want more than one person to be able to do updating Functions to the DIT records of an Element at the same time. An example would be to speed up the entry of the Data Item definitions for a large Element by dividing the work among several persons. To do that you might have all of them SYSLOG on using the Employee Number of the person having exclusive control. The employee would have to have multi-terminal logon capability specified on his/her SIF file profile in order to do this.

    Group Items

    All Data Items (except 88-levels) have either a numeric or an alphanumeric PICture specified, even if they are to be a "Group Item". A Group Item is one which is to be "broken down" into one or more other Items having higher Cobol level numbers. The Items which break down the Group Item may, themselves, be Group Items and be further broken down by other Items having yet higher level numbers.

    Since IBM Cobol does not allow Group Items to have a PICture clause MAGEC automatically detects that an Item is a Group Item (because the next Item has a higher level number) and generates a FILLER REDEFINES Item into the generated copybook. This allows for maximum flexibility for you while conforming with all the rules of the compiler.

    Examples of Group Items

    Suppose you defined three Data Items as:

    seq # level name PIC

    000100 05 ZIP-CODE 9(5)  

    000200 06 SECTIONAL 9(3)  

    000300 06 SUFFIX 9(2)  

    When you generate the copybook you will see:

    05 eeeee-ZIP-CODE PIC 9(5).  


    	06 eeeee-SECTIONAL          PIC 9(3).

    	06 eeeee-SUFFIX             PIC 9(2).

    where: eeeee               = Element Name

    Now, suppose you added an 88-level Item "below" the ZIP-CODE, as:

    seq # level name PIC VALUE

    000150 88 OUR-TOWN 75252  

    When you generate the copybook you will see:

    05 eeeee-ZIP-CODE PIC 9(5).  

    	88 eeeee-OUR-TOWN VALUE 75252.


    	06 eeeee-SECTIONAL          PIC 9(3).

    	06 eeeee-SUFFIX             PIC 9(2).

    Moving DIT's

    You may at some time accidentally define Data Items in the wrong sequence and need to correct the error by moving one or more Item(s) either before or after another. Since the order of the Items is controlled by their assigned sequence numbers and since the sequence number is a part of the actual record key you must use a two-step process to accomplish the move.

    First, you must use the DITDUP Function to duplicate the Item to be moved. Duplicate it to a sequence number which places it where you want it to be.

    Next, you must use the DITDEL Function to delete the old record. If you like you may then use the DITSEQ Function to renumber into nice neat increments of 10 or 100.

    Generating the Copybook

    To generate the copybook for an Element you must enter:

    DITGEN eeeee/m  

    where: eeeee               = Element Name

    m               = Mode (defaults to "T")

    If no one else currently has Exclusive Control of the Element then you will automatically be given Control. It is up to you to reset the Control when you are finished working with that Element by using the ELTCHG Function and zeroing the "Employee Number Having Control" field.

    If you make an error in the key entry (eeeee/m) or if some other error occurs then you will receive an appropriate error message; otherwise the copybook will be generated and added to the MAGEC Library (ALG file) with the correct standard member name (eeeee-C) and it will be displayed to you immediately via the standard "LBRSEE eeeee-C" screen.

    To protect against your accidentally generating a copybook for the wrong Element MAGEC will present a screen to you with instructions to press PF14 to generate the book. On that screen it will tell you the name of the Element and the Member Name of the book to be generated and will remind you that the new book will overlay/replace any preexisting Member of the same name. If all is correct then just press the PF14 key.

    As DITGEN is generating your Cobol copybook it will scan for possible errors and issue a warning notification to you if any were found. For instance, if the key field (as specified in the KYF definition "Cobol Name") is the wrong length, or a numeric type field, you will be told that a potential problem exists. DITGEN will go ahead and create the copybook regardless of these "soft" errors.

    If the access method of the Data Class is SQL or DB2, the DITGEN function will automatically fetch to the SQLGEN function which will generate the SQL Host Variable definitions and store them in a member named:


    As of MAGEC release 3.0, the DITGEN function also parses the DIT definitions to construct a highly compressed table of translation parameters to be used by MAGECIO when an application accesses data from another machine (a Host machine) which uses a different coding scheme (ASCII vs. EBCDIC) from the machine on which the application is executing. In order to produce accurate parameters DITGEN accomplishes more extensive validations than in earlier releases of MAGEC. If discrepencies are encountered, DITGEN will stop and display an error message. If you wish to ignore these more thorough validations, you can press PF5 in lieu of PF14 (a message on the screen tells you this, as well). We recommend that you use PF5 here only in exceptional cases. It is best to go back to the DIT definitions and correct the errors noted, then redo DITGEN. The PF5 feature is there only to enable you to revert to the earlier, lower standard in an emergency situation. The hope is that at some future time you will return and correct any errors you have ignored to bring your data definitions up to current standards. Using the PF5 feature causes DITGEN to insert a warning message into your generated copybook to remind you that you have ignored some errors.

    As a byproduct of this more thorough validation, DITGEN is able to update each DIT definition with the offset and length (bytes) of each Data Item. These are displayed on the DIT screen for informational purposes only. The offset is relative to zero, with the first field in an Element having an offset of zero.

    Resequencing DIT's

    To re-sequence (renumber) the Data Items for an Element use the command:

    DITSEQ eeeee/m/iii  

    where: eeeee               = Element Name

    m               = Mode (defaults to "T")

    iii               = Increment Value of 10 or 100 (default is 100)

    Since the Mode defaults to T and the Increment also defaults, you may usually enter only the Element Name.

    If an error is detected you will receive an appropriate message; otherwise the Data Items will be re-sequenced and the message:


    will appear. Just press the ENTER key and the DITLST screen will be shown so you can verify the results if you like.

    Modifying Generated Copybook


    If you alter the copybook for any reason and someone else (or even you) later alters the DIT file definition and regenerates the copybook then your modifications will be lost. Make your changes to the DIT file definitions and regenerate whenever changes need to be made.

    Also, remember, planned features of MAGEC will use these DIT file definitions more and more. It is important that they be current and correct.

    Field-Level HELP

    The DIT definitions, including the 8-line text narrative, are used in the field-level HELP facility of all MAGEC online applications. By pointing to a screen field with the cursor and pressing PF2, a user can invoke field-level HELP. The help text will consist of a combination of 1) the Data Item Narrative which is on the DIT definition, plus 2) technical specifications for the screen field which are translated into common English language. The specifications for screen fields are ordinarily inherited from the DIT which is given as its Source/Target database field.

    Accessing Files from Programs

    MAGECIO Requests -- Online

    Application MMP's access database and VSAM files via MAGECIO. In order to use MAGECIO the MMP's must do the following things:

    1. fill-in the MAGECIO Request Area in the TWA
    (it is named TWA-DB-REQUEST)

    2. fill-in the key value (for some commands)
    (it is named TWA-KEY-VALUE)

    3. fill-in the Element list in the TWA
    (it is named TWA-ELT-LIST)

    4. set a pointer to tell MAGECIO where to read into or write from
    (it is named TWA-DB-AREA-A)

    5. perform the built-in MAGECIO CALL routine
    (it is named AA840-CALL-MAGEC-IO THRU AA899-EXIT)

    The program generator (MMPCREAT jobstream) automatically generates the necessary code for all the accesses to the "Primary Data Class" for the application (the one specified on the SHD Record for it). The developer may add some additional code to access other Data Classes. In either case the sequence of events will be the same.

    MAGECIO Requests -- Batch

    Application MBP's access database and VSAM files via MAGECIO. In order to use MAGECIO the MBP's must do the following things:

    1. fill-in the MAGECIO Request Area in the Data Division
    (it is named DB-REQUEST-AREA)

    2. fill-in the key value (for some commands)
    (it is named DB-KEY-VALUE)

    3. fill-in the Element list in the TWA
    (it is named DB-ELT-LIST)

    4. CALL MAGECIO using the request area, work area, and
    element list as parameters. The work area is the area to read into or write from

    The program generator (MBPCREAT jobstream) automatically generates the necessary code for all the accesses to the "Primary Data Class" for the application and for the "joined" Data Classes. You can code additional accesses via customization.


    To fill in the MAGECIO Request Area the MBP must:

    1. MOVE a valid MAGECIO command to DB-CMD  

    2. MOVE a valid Key Name to DB-KEY-NAME  

    These fields are within the DB-REQUEST-AREA area. There are other fields within DB-REQUEST-AREA but they should be left alone except in very exceptional cases.

    MAGECIO Commands

    The valid MAGECIO commands are:

    REDKY--read record for key value

    REDNX--read the next record from the one just read

    REDPR--read the previous record

    REDID--re-read the record just read

    RDUKY--same as REDKY but with intent to update

    RDUID--same as REDID but with intent to update

    RDUNX--same as REDNX but with intent to update

    RDULE--same as REDLE but with intent to update

    LOCKY--locate record with key = or > key value

    LOCKX--locate record with key = key value

    LOCNX--locate next record from one just read or located

    FSTAT--test file status (open or closed, etc.)

    REDLE--read the record just located

    UPDAT--update the record

    DELET--delete the record

    RELES--release the record just read-with-intent

    ADDIT--add a record

    **VER--set TWA-DB-RETURN-CODE (or DB-RETURN-CODE) to MAGEC version#

    The following commands are valid only in batch programs:

    CLSFL--close a file

    *CLSE--close all files

    OPENU--open file for update

    OPENR--open file read-only

    *READ--set default to open read-only (implicit opens)

    *LOAD--set default to open for update (implicit opens)

    *PURG--enable reading and purging pseudodeleted records

    As a rule of thumb: commands ending in "KY" require that a value be filled into TWA-KEY-VALUE or DB-KEY-VALUE, Commands beginning with LOC implicitly read only the key value (as if it were a mini-Element defined). All commands require that the element list contain valid Element name(s) even if they are LOC commands. Commands starting with RDU obtain Exclusive Control of the record (rather than Control Interval), locking out other tasks from reading (or reading-with-intent) that record.

    The Key Name which is moved to TWA-DB-KEY-NAME or DB-KEY-NAME must be defined on the KYF file, i.e.: IVCK1.

    The DELET and UPDAT commands must be preceeded by a successful read-with-intent (RDU..) command for that record. The LOCNX, REDNX and REDPR commands must be preceeded by a successful LOC.. or RED.. command.

    The Key Value -- Online Programs

    The TWA field named TWA-KEY-VALUE is 256-bytes long and can therefore contain a file key up to that size. The generated MMP's include a Normalize Key routine (BA300-Normalize-Key) which transforms the key value entered by the operator on the top line of the screen into the correct format for use in accessing the file. It places the transformed (file format) key value into a field in the TWA filed named NORMALIZED-KEY and the MMP then moves that to TWA-KEY-VALUE for accessing the Primary Data Class. If the developer adds customization code to access other files then it is his/her responsibility to set TWA-KEY-VALUE as needed.

    The Key Value -- Batch Programs

    The Working Storage field named DB-KEY-VALUE is 256-bytes long and can therefore contain a file key up to that size.

    Element List

    The area in the TWA named TWA-ELT-LIST has room for up to 16 Element names. This means that the MMP can read up to 16 Elements from the same Data Class in one CALL. MAGECIO will return the data from the record read for the Element(s) specified and in the order they are specified in the Element list. The data will be concatenated, therefore it is necessary that the copybook definitions for the Elements be in the same order and that they be the correct length(s) and that they be immediately following one another (if there are more than one).

    The Element Names are the 5-character names defined on the ELT file. In the Element list up to sixteen (16) Element Names may be specified, they must be separated by one space and the last Element Name must be followed by a "dummy" Element Name of blanks (unless you have filled all sixteen (16) names). An example of the Element list to access two Elements might be:

    in online MMP's:


    in batch MBP's:


    The Program would also contain, in its Data Division:



    Read Into / Write From -- Online Programs

    To tell MAGECIO where to read into or write from, online MMP's use the MAGECSET subroutine which is provided and included into the Link Edit for all MMP's. The MAGECSET subroutine should be CALLed immediately before every CALL to MAGECIO. To tell MAGECIO to READ INTO the area beginning with IVC01-ELEMENT (Cobol dataname in copybook) the MMP would contain:


    The area you read into or write from is often called the "work area". If the MMP does not point MAGECIO to a work area before CALLing MAGECIO then the default area will be used. The default area is TWA-DB-DATA.

    Read Into / Write From -- Batch Programs

    Batch programs specify where to read into or write from via the standard Cobol parameter list passed with the CALL verb. The second parameter passed to the batch I/O module points to the area to read into or write from.

    CALL'ing MAGECIO -- Online Programs

    To call MAGECIO to service your request, code:


    The mechanism for actually CALLing the MAGECIO module is different for each TP monitor supported by MAGEC and can even be different depending on system options at your site. The code generated in the AA840 routine will be correct for your site. If your generated applications are ever required to operate in a different environment as a result of a conversion or for any other reason then the AA840 routine will automatically be adjusted accordingly by the MMPCREAT process. If, on the other hand, you "hard code" your own code to accomplish the CALL then your application might not work in other environments.

    CALL'ing MAGECIO -- Batch Programs

    Batch programs must be linked to include the MAGDBMS subroutine, which is the batch version of MAGECIO. To call it, enter the following code:


    If the file you are accessing has not been opened yet, MAGECIO will open it for read-only (unless you have set the global default to open for update). You can explicitly open a file using the OPENU (open for update) or OPENR (open read-only) commands. You can alter the default using the *LOAD (default open for update) or *READ (default open read-only). When your program is initially started the default is set to open read-only.

    You can close a file using the CLSFL command, then re-open it if you need to.

    Return Codes

    MAGECIO Intercepts I/O Errors

    Whenever you request database services via MAGECIO you should always check the Return Code to see that your request was successfully handled. There are a large number of things which can go wrong when you attempt to access a file including: I/O errors, invalid requests, missing Dictionary definitions, or hardware failures. Unless you have specified for MAGECIO not to handle errors (see below), MAGECIO tests for these error conditions and handles them for the MMP so that the MMP need not concern itself with them. If a catastrophic error is detected then MAGECIO issues an error message to the offending terminal and then aborts the task with an appropriate Abend Code.

    A two-character Return Code is placed into the request area in a field named TWA-DB-RETURN-CODE (online) or DB-RETURN-CODE (in batch) by MAGECIO on every request. A value of blanks always indicates that the request was successfully handled without errors. There is a Condition-Name (88 level) defined which the programs use to test for successful completion as:

    IF (REC-FOUND)  

    - etc.

    A value of '14' indicates either that no record was found for the key value given or that the end of the list (file) was reached. A Condition Name is provided for this also as:

    IF (NOT-FOUND)  

    - etc.

    A value of '10' indicates that you have attempted to add a record with a key value which is a duplicate of one already on file. A Condition Name for this is also provided as:

    IF (DUP-ERROR)  

    - etc.

    The database accesses generated automatically by MMPCREAT and MBPCREAT always include checking of the Return Code. Yours should also.

    If you do not wish for MAGECIO to abort the task when a serious error condition occurs, you should move "NH" to TWA-DB-RETURN-CODE just prior to calling MAGECIO. The "NH" stands for "No Handle" and directs MAGECIO to simply set the appropriate code into TWA-DB-RETURN-CODE and return to your program. It them becomes your responsibility to deal with any error conditions.

    Sample Code

    A Cobol Example -- Online Programs (MMP's)

    An example of the complete coding to read (using the REDKY command) two Elements from the IVC Data Class for Customer# 37, Invoice# 125 would be:

    - - - - - in TWA data definition area - -(%DATADEF) - - - -

    		  03 INVOICE-DATA.



    - - - - - in PROCEDURE DIVISION - - - - - (%JOIN) - - - - -



    MOVE '00037000125' TO TWA-KEY-VALUE.  




    IF (REC-FOUND)  





    Other database commands (i.e. RDUKY, UPDAT, etc.) are coded in exactly the same format.

    The %DATADEF and %JOIN markers above refer to the Custom Algorithm insertion points of the same names as used by the application developer. They are not the only places where I/O requests may be coded. They are, however, the places where such coding is most often found.

    The %DATADEF is in the TWA-DB-DATA area of the TWA, this is where MMPCREAT will automatically read the Primary Data Class's Elements into and where the copybooks for them will automatically be included. It is sometimes desirable to place the copybooks (and read-into area) for the other Data Classes elsewhere in the TWA, possibly because of size. The other place where copybooks are often included by the developers is the %VARSTOR insertion point. This area is farther down in the TWA in the VARIABLE-STORAGE area which is not saved and restored by MAGECCP and is always cleared to LOW-VALUES on entry to the MMP.

    Remember, if you are only reading the record to determine whether it exists or not (as in some editing routines) then you can save space and some overhead by using the LOCKX command instead of REDKY. Your "read-into" area need only be as large as the record key in that case.

    A Cobol Example -- Batch Programs (MBP's)

    An example of how to code the logic to accomplish exactly the same thing as was done in the above online MMP from a batch program (we call them MBP's) is as follows:

    - - - - - in WORKING-STORAGE - - - - - - (%DATADEF) - - - -

    		  01  INVOICE-DATA.



    - - - - - in PROCEDURE DIVISION - - - - - (%JOIN) - - - - -




    MOVE '00037000125' TO DB-KEY-VALUE.  




    IF (REC-FOUND)  





    Other database commands (i.e. RDUKY, UPDAT, ADDIT, etc.) are coded in exactly the same format.


    Your MBP must be linked to include the MAGDBMS module. The sample jobstreams provided with MAGEC contain the appropriate link coding for your environment (MVS, VSE, MS-DOS, VM, etc.). The jobstream is named MBPCREAT, it is a JCL member for the mainframe and a .BAT or .CMD file for the PC.

    Logical Sequences of Commands

    The following sequence of commands will illustrate how you can control opening and closing files in a batch program. Assume a program accessing the ABC, DEF, and XYZ data classes.

    Command               MAGECIO action taken

    beginning of program               initial default open switch set to "read-only"

    LOCKY XYZ               open XYZ read-only

    REDLE XYZ               read located (first) record from XYZ

    *CLSE               close all open files

    *READ               set default open switch to "read-only"
    (safe and harmless, but unnecessary here because that is the default and is still set from the job initiation)

    REDKY ABC               open ABC read-only, read record by key

    OPENU DEF               open DEF for update

    RDUKY DEF               read DEF record for update by key

    UPDAT DEF               update DEF record

    CLSFL DEF               close DEF

    REDKY DEF               open DEF read-only, read record by key

    *LOAD               set default open switch to "open-for-update"

    REDKY XYZ               open XYZ for-update, read record by key

    end of job               close all files automatically


    Audit Stamps

    Element 00

    An Audit Stamp is a 36-byte portion of a record which is used to record Who, Where, and When the record was last updated or added. It is an optional feature of MAGEC which may be specified for some Data Classes and not for others as needs dictate. If Audit Stamp support is specified for a Data Class then the Audit Stamp must be defined as a separate Element with a name in the format:


    Where: eee = Data Class name, 00 = literal value of '00'

    Whenever a program reads any Element(s) of the Data Class (with Audit Stamp specified) MAGECIO also automatically reads the Audit Stamp Element into the area named AUDIT-STAMP. There is no need for you to provide copybooks to define the Audit Stamp nor is there a need for the programs to include the Audit Stamp Element name (eee00) in the Element list. It is illegal for any program to update an Audit Stamp Element and MAGECIO will abort the task if such an update is attempted, a Return Code of 97 (Abend Code DB97) will be set. There is a standard copybook included into the Audit Stamp area from the MAGEC library, it is named ELT00-C and contains the definition of any Data Class's Audit Stamp. The definition includes:

    AS-FILE-NAME               The Data Class name this record belongs to (3 characters long)

    AS-DATE-UPDATED               The date (YYMMDD) this record was last updated or added (or pseudodeleted)

    AS-TIME-UPDATED               The time (HHMMSS) this record was last updated or added (or pseudodeleted)

    AS-TERM-LAST-UPDATED               The Device (Terminal) ID from which this record was last updated, etc. (4-char.)

    AS-OPER-LAST-UPDATED               The initials of the operator who last updated (etc.) this record (3 char)

    AS-PROGRAM-LAST-UPDATED               The name of the program (MMP) which last updated (etc.) this record (8 char)

    AS-EMPNO               The Employee number of the operator who last updated (etc.) this (4-byte binary, 9-digit)

    AS-FILLER               An unused byte reserved for future use

    AS-INACTIVE-FLAG               A 1-byte flag which is set to HIGH-VALUE (X'FF') to indicate "pseudodeleted" by MAGECIO instead of actually deleting the record (if Real Delete = N on DCL file definition for this Data Class)

    File Utility

    DBDITO Function

    There is a general purpose utility online Function provided with MAGEC which allows you to do any database request via your CRT. It permits you to see and alter any file or database available to MAGEC using an over/under character/hexadecimal display. It may be used to add, change, or delete as well as just look at data on the files.

    To use this utility just enter the Function Code:

    DBDITO (full function)  


    DBUTIL (read only)  

    The MAGEC security system governs who may use each of the above Functions and some additional restrictions also apply because of the dangerous possibilities. DBDITO and DBUTIL are fully documented via the online HELP facility, press PF1 after the screen is returned to you for full instructions.

    Some of the many common uses for the DBDITO utility are:

  • Undeleting pseudodeleted records
  • Correcting bad data on file
  • Creating test data for new programs
  • Verifying that a file is open/available
  • Training the use of the MAGECIO Request & Commands
  • You may refer to the MAGEC "Data Definition" tutorial for additional instructions on the use of DBDITO.

    Logical Join

    Secondary Data Classes

    Very often the application developers will want to produce MMP's and MBP's which access more than one Data Class. For instance, the MMP which is to provide inquiry and update capability for the Invoice data will also need to access the Customer data to display name and address, etc.

    In a "flat file" or "relational" environment there are no physical "pointers" from one record to another; therefore the connection between records is known as a "logical connection" and the process of specifying that connection is known as "logically joining" the records.

    In the hypothetical Invoice MMP we mentioned above, the Invoice data would be the "Primary Data Class" and the Customer data would be a "Secondary Data Class". There could be any number of additional Secondary Data Classes, but only one Primary. In order to access the Secondary Data Class the developer must know: 1) which key (if there are more than one) of that Data Class is to be used, and 2) how to construct the Key Value to be used. In our hypothetical example we might wish to use the Customer-Number key of the Customer Data Class and, as the Key Value we might use the Customer-Number from the Invoice record we are processing.

    A Data Item in the Primary data which is used as a key to access the Secondary data is known as a "Foreign Key". Likewise, a Data Item from the Secondary data which is used to access yet another Secondary Data Class, is also known as a Foreign Key. It is also possible to concatenate Data Items, from one or more Data Classes, in order to construct the key to access another Data Class. It is also possible to access a Data Class by constructing only the high-order portion(s) of the key and using a generic access, known as a "Partial Key Join". This would be appropriate if you were using the Customer file as your Primary data and joining to the Invoice file, where ther may be many invoices for a given customer.

    Specification of Logical Joining rules is done by developers as a part of the normal development process. In the Semi-Automatic development sequence the developer will be prompted for all the necessary information and all the needed coding will be generated for him. Alternatively he may manually do the coding using the Customization insertion points named %JOIN and %DATADEF.

    In the Fully-Automatic development process MAGEC will generate the Logical Join coding with no help from the developer other than to select which Data Classes he/she wishes to have joined. This relies upon the definition of Domains for Data Items which are keys, components of keys, or foreign keys. The Domain definitions enable MAGEC to match-up foreign keys with primary key fields of those Data Classes to which a join is possible. For example, if the Customer-Number field in the Invoice record is defined as belonging to the same Domain as the Customer-Number field of the Customer record, and that field is also the key to the Customer file, then MAGEC knows that it can use the Invoice's Customer-Number to access the Customer file.

    Thus, the developer has three levels of automation to choose from to generate Logical Joins:

    1) manual--do it using Cobol coding him/herself

    2) semi-automated--let MAGEC do most of the work

    3) fully-automated--let MAGEC do it all

    Table Maintenance

    TOCxxx Functions

    MAGEC's Automatic Table Lookup Editing feature is used by both your application developers' generated MMP's and by the MAGEC System MMP's as well. The Lookup Table feature supports up to 999 Tables which are identified by their Table Numbers (001 thru 999). MAGEC reserves the use of Table # 200 thru 255 for "system use". Therefore, you may define up to 744 of your own Tables for your applications.

    Each Table is defined by an entry in the "Table of Contents" (TOC). To list the TOC entries enter:

    TOCLOC 1  

    To add a new Table to the system enter:

    TOCADD ttt  

    where: ttt               = new Table number

    The screen will return to you asking for a DESCRIPTION and an ERROR NUMBER. The description is free-form. The Error Number must be defined on the MAGEC Error file (ERR). It is the Error Number which will be displayed to the application user when he/she mis-enters into a screen field which is being validated against this Table.

    We recommend that you use Error Numbers which correspond to the Table Number for which it applies. For example, Error Number 001 for Table 001. However, remember that MAGEC reserves Error Numbers starting with a '9' for its own use.

    TBLxxx Functions

    To list the entries (codes and descriptions) which make up any given Table, enter:

    TBLLST ttt  

    where: ttt               = Table Number

    To add a new entry to a given Table enter:

    TBLADD ttt/ccccccc  

    where: ttt               = Table Number

    ccccccc               = the new Code (16 char. max.)

    You may similarly change the description for an entry using TBLCHG, or delete an entry entirely using TBLDEL.. You can only display or add to a table number which has been defined via the TOCADD function described above.

    The changes you make to the Tables take effect immediately and do not require you to use the **LOAD Function or to recompile any program. Naturally, the MAGEC Security System governs access to the Table and Table of Contents Functions.

    Where-Used for Tables

    Table Lookup validations are automatically done by MAGEC's reusable routines. They are triggered by the specifications made for screen fields. In many cases it would be useful to know every reference to a given table; i.e. every screen field which is validated against that table. This is especially important when grand changes are planned for that table and you would like to determine the impact of those changes.

    To find every reference to a table you would use the online command:

    SCDTBL nnn  

    where nnn               = the table number in question

    You will receive a list of all screen fields which reference that table. If you press PF13, the list will be "spooled" for hardcopy printing.

    Field-level HELP for Table-edited Fields

    MAGEC's Field-level HELP facility is especially useful for screen fields which are validated against a table. If the operator presses the PF2 key with the cursor pointing to such a field on the screen, MAGEC will display the usual one-screen help text for that field plus a message saying that he/she can press PF8 to list the table's entries.

    If the operator presses PF8 to begin scrolling through the entries of the table, he/she can then use the list on the screen as a "pick list" by pointing with the cursor to a desired value and pressing ENTER. MAGEC will return to the application screen with the selected value filled into the screen field.

    Initializing Files


    Defining a new file to MAGEC consists of doing the DCL, KYF, and ELT definitions described in this chapter. Creating the file in a mainframe environment consists of executing whatever utility (AMSERV, IDCAMS, DDCFMNT, etc.) is appropriate for the type of file. Initilizing the file is merely a process of opening, writing to, and closing it. This can be done using various utilities provided with the access method or database management system; for mainframe VSAM files and for PC MAGEC files initializing can also be done using a special utility named MAGINIT. In the PC MAGEC environment MAGINIT does the functions of both creating and initializing the file in one step. To execute MAGINIT:


    //MAGINIT JOB (acct...)  



    //NEWFILE DD ... DSN for the VSAM file to be initialized ...  



    // JOB MAGINIT  

    // DLBL NEWFILE.'...VSAM file to be initialized..',,VSAM  


    PC MAGEC MAGINIT command

    C:> MAGINIT yyy  

    where: yyy               = Data Class

    You will be asked for the name of the Data Class to be initialized if you fail to provide it in your "command".


    Business Rules

    What is a Business Rule?

    A Business Rule is a routine which is triggered (invoked) whenever an MMP updates or adds data to the database for a specified Element. It consists of Cobol coding which is automatically inserted into the generated MMP by MAGEC. Business Rules are normally coded by the Database Administrators (DBA's), rather than application programmers. This gives the DBA's a much higher level of control over enforcing the integrity of the database and the data that is in the database. It also reduces the work of the application developers since they no longer need to concern themselves with any of the validation, editing, and default valuing which is done by the Business Rules. Since any given Element might be updated by several MMP's, this scheme also eliminates much redundant effort.

    Business Rules can include almost any type of processing, including calling subroutines and doing I/O. They can accomplish complex cross-field or cross-file validations, they can update other files and they can alter the data in the Element before it is updated to the database.

    Defining Business Rules

    Business Rules are actually special library members on the MAGEC source library, the ALG file. You maintain them in much the same way that you maintain any other member, except that you use a special set of online functions designed specifically for Business Rules. They operate similarly to the functions used for ordinary members.

    Whereas you maintain ordinary members using the functions:


    For Business Rules you use the functions:


    Whereas the key format for ordinary members is:


    where: nnnnnnnn               = 8-character member name

    mmmmmmmm               = 8-character modifier (optional)

    For Business Rules the key format is the same, except:

    1) The member name is always the 5-character Element name. 2) The modifier is always either: RULWORK or RULPROC, to designate that the
    member is work field definitions for the Data Division, or processing logic for
    the Procedure Division, respectively. The modifier RULDELT is used in the Deletion
    Rules facility described later in this chapter.

    Hence, to add both Data Division and Procedure Division code as a Business Rule for the Element named CUS01, you would use the commands:

    RULADD CUS01/RULWORK (for Data Division)
    RULADD CUS01/RULPROC (for Procedure Division)

    The online text editor works just like it does for ordinary library members. You could refer to the "MAGEC Librarian" chapter for more detailed descriptions about the source online librarian. You could also refer to the MAGEC "Data Definition" tutorial to review actual screen examples for the entire data definition process, including Business Rules.

    Naming Conventions in Rules


    The DATA DIVISION coding for your Rule will be inserted into the LINKAGE SECTION of online MMP's, within the TWA area. MAGEC will generate a group item above your coding. The group item will be a Cobol level 03; therefore your work fields should be Cobol level 04 and greater.

    Since your Business Rule might very well be inserted into many programs, and since several Business Rules might very well be inserted into any one program, you should abide by certain conventions in naming your work fields. We suggest:

    eeeee--dddddddddd where: eeeee               = the Element name

    --               = two dashes separate the Element name prefix from the remainder of the dataname

    dddddddddd               = up to 23 characters of valid Cobol dataname

    This scheme will avoid conflicts between multiple Business Rules, thanks to the Element name prefix. It will avoid conflicts with the datanames within the generated Element definition copybook, thanks to the two dashes. It will also avoid conflicts with standard datanames generated into all MMP's by MAGEC, and with datanames the programmer is likely to define in normal customization.


    The PROCEDURE DIVISION coding should also conform to certain conventions in order to avoid similar conflicts as were described for Data Division coding. We suggest a naming scheme for paragraph names, as:

    BB6nn-eeeee--pppppppppp where: nn               = any 2-digit sequence number

    eeeee               = the 5-character Element name

    --               = two dashes separate the Element name from the remainder of the procedure name

    pppppppppp               = up to 17 characters of valid Cobol procedure name


    Conditional MAGECINC's

    You will likely find many occasions to code the -MAGECINC command into your Business Rule coding. One of the obvious situations where -MAGECINC's will be needed is when you are doing I/O on your Procedure Division logic. You will need to include the Element definition copybook(s) into the Data Division in order to provide the area to read into and write from.

    This introduces an opportunity for error. Since your Rule will likely be inserted into several MMP's, there is the distinct possibliity that one or more of them will already be including that same copybook, resulting in duplicate datanames and compiler errors. In order to avoid this error we recommend that you always make your -MAGECINC's "conditional", that is: code them so that they will be expanded only if they have not been expanded elsewhere in the same program. That is done using the -IFUNIQUE command, as:

    -MAGECINC member/modifier

    The -IFUNIQUE command must immediately precede the -MAGECINC, as shown above. It applies to the member named in the -MAGECINC which immediately follows it.. You can use as many of the -IFUNIQUE and as many -MAGECINC commands in one Rule, or in one program, as you need.

    The -IFUNIQUE works even if another -MAGECINC for the same member appears physically behind this one in the program. The -IFUNIQUE feature is not limited only to Business Rules, it can be used anywhere, but it is particularly useful in Business Rules.

    Restrictions in Rules

    Since your Rules will be inserted into many programs you should abide by certain restrictions when coding them. This is necessary to avoid tying the Rule to one particular program or screen.

    Never code references to screen fields, except for the four standard fields which MAGEC forces all screens to include. They are:

    SFUNCT function code - 6 characters
    SKEY free-form key - 31 characters
    SCOMPL completion message - 40 characters
    SERRMSG error message area - 240 characters

    This includes all the associated attribute, color, highlighiting, position, and error flag fields for them.

    You can, however, refer to screen fields indirectly using MAGEC's symbolic screen field references.

    Never code references to datanames except those which are either:

    1) defined in the RULWORK code for this Rule.
    2) defined as standard fields in all MMP's.
    3) defined in the Element copybook for the Element this Rule is associated with.
    4) Cobol special registers available to all programs.

    Never code references to paragraph names except those which are either:

    1) defined in this RULPROC logic.
    2) generated into all MMP's by MAGEC.

    Never GO TO paragraph names except those which are both:

    1) within the BB600 through BB699 routine.
    2) defined in either every MMP, or within this RULPROC logic.

    To exit the RULPROC logic you should GO TO BB699-EXIT.

    Setting Default Values

    SInce the RULPROC coding is inserted into the MMP as the last process before the data is actually updated to the database, you will find that this is a handy facility for testing for "null" values in fields and setting default values for them. This gives the DBA control over default values and relieves the application programmers from that chore. The result is more consistent handling of data across many applications.

    Preventing Updates

    The most obvious purpose for Business Rules is to prevent data from being placed onto the database unless it passes stringent validation requirements. These validations can involve cross-field, or even, cross-file, comparisons. The RULPROC logic is inserted just before the actual database update in the generated MMP's; therefore it can set an error flag to cause the MMP to bypass the update and issue an error message instead. You do that by coding:


    where: xxx               = the (alphanumeric) number of the error message you wish to have issued.

    That is exactly how it is done in the customization editing that a programmer does for an MMP, except that s/he would usually also set the screen field's error flag for the screen field being edited. In the Business Rules, you are editing database fields, not screen fields. All of the screen data has been moved to the database before your RULPROC logic was invoked. You can; however, set the attributes for the four standard MAGEC screen fields, and you can make use of MAGEC's symbolic screen field referencing discussed later in this section.

    Creating "Master" Record

    In some instances you might wish to automatically generate a "master record" when a "detail record" is added, if no master record already exists. A possible example: generate an invoice header when the first invoice line item is added, fill in default values into the header. Just as you can do I/O to read the master record, you can do I/O to add it if it does not exist. If you do add a new master record, it might also be helpful for you to alter the function code on the screen (SFUNCT) to the one which will display that new master record; the default logic ot the MMP's will then display the screen with the "data ADDED to database" message in SCOMPL, and the new function code in SFUNCT, ready for the operator to press ENTER to display the master record's data or to update it.

    Assigning Keys

    In some cases, you might wish to control the key value for new records added to a file by accessing a control file to obtain the next available key value. This relieves the application users from having to determine a new key and gives you, the DBA, control of new keys added. The new key values might be check digit'ed numbers.

    The Business Rules are a handy place to accomplish the setting of the new key into the new record. You can access a control file, or record, by coding a standard I/O call. You can also call a subroutine, if you happen to have one which assigns key values.

    If you had a Journal Entry file whose key was Voucher Number, you might have many different programs which could add new Journal Entries. Because of your Business Rule logic to assign Voucher Numbers (perhaps by calling a subroutine), none of the MMP's or their authors had to bother themselves with "how to assign a Voucher Number" and you are assured that all Voucher Numbers are assigned correctly (or, at least, uniformly).

    Referential Integrity

    Deletion Rules

    Another feature, related to Business Rules, is called "Deletion Rules". This enables the DBA to specify logic to be triggered (invoked) whenever a record (containing the specified element) is to be deleted.

    The restrictions which apply to the Procedure Division coding for a Business Rule (RULPROC) also apply to the coding of a Deletion Rule (RULDELT). Please refer to the previous topic in this chapter for full descriptions. The only difference is that the modifier RULDELT is used instead of RULPROC. Any work areas needed for the RULDELT logic are to be defined in the RULWORK coding, just as they are for RULPROC. Do not define the same work field twice since all three of these members (RULWORK, RULPROC, and RULDELT) will be inserted into each MMP which updates the specified element.

    To add a Deletion Rule for the CUS01 element, you would use the command:


    The code that you provide for RULDELT will be inserted into the generated MMP's in the BB400-EDIT-FOR-DELETE paragraph. The exit from that routine is BB499-EXIT. In all other respects the RULDELT coding must follow exactly the same restrictions as apply to RULPROC.

    You can do virtually any type of processing in the RULDELT logic, including I/O and complex field content or value checking. Deletion Rules can serve several very important functions associated with ensuring referential integrity.

    Prevent Deletion (Restrict)

    In the RULDELT code you could, perhaps, test for the existence of subordinate items (i.e. test for existence of invoices on file for a customer you are about to delete) and, if found, set the ERROR-FOUND condition to prevent the deletion from taking place.

    Another reason you might wish to prevent the deletion of an item is because of certain data item contents. For example, if the customer's balance is not zero. You might even wish to prevent deletion of certain cirtical records based on their ID, i.e.: customer numbers 00001 through 00100 may not be deleted, ever.

    You can test for PF keys in this logic. You might even wish to create a Deletion Rule which states that customer numbers 00001 thru 00100 can be deleted if you press PF14 (or some other key).

    Auto Delete (Cascade)

    Another possibility would be to automatically delete any invoices for the customer about to be deleted.

    Alter References (Nullify)

    Another scenario involves not deleting the invoices, but rather, modifying them so that they now reference a different customer. One possibility is to have them reference a "dummy" customer number which is used for miscellaneous "walk-in" business.

    Other Processes

    Many other types of processing are possible in the RULDELT logic. Some examples of them are:

    Control Record Update

    You could update a control record, perhaps the salesman's record to reflect one less customer.

    Master Deletion

    When deleting the last invoice for a customer you might wish to delete the customer's master record.

    Audit Trail Generation

    You might wish to generate a record on a log file whenever certain data is deleted.

    There is virtually no limit to the types of processing you might wish to apply in the Deletion Rules. Remember, it will be invoked just prior to to standard MMP logic to delete a record. If you set the ERROR-FOUND condition (usually by performing CA100-LOAD-ERR-CODE-TBL) then the delete will not be done. As an example:


    where: xxx               = the (alphanumeric) number of the error message you wish to have issued.

    Symbolic Screen Field References

    In Business Rules

    As discussed earlier, you should never directly reference screen fields from within a Business Rule or Referential Integrity Rule. This is because your Rules will likely be inserted into several programs (MMP's) and you have no way of knowing what name the screen field associated with a given database field might have, or even that there is a screen field associated with that database field.

    This restriction presents an inconvenience in that it would be helpful, and more consistent with the way MAGEC screens tend to behave, if you could access the screen fields -- especially the error flags and attribute bytes. This would enable you to use MAGEC's standard error handling features which highlight error fields and home the cursor to them, or to display values in screen fields, or to manipulate attributes and position the cursor.

    Fortunately, there is a way you can do all these things from your Rules. Though you must not refer to any screen fields (except for the four standard fields, as noted earlier) directly by their Screen Field dataname, you can refer to them indirectly using symbolics based upon the database field's dataname. Such symbolic references are coded using the database name enclosed in at-signs (@).

    For example:


    would set the attribute for the screen field associated with the database field "CUS01-AMOUNT-DUE" to high-intensity, unprotected; and it would position the cursor to that screen field. In the application developer's generated MMP, this code would be translated into:



    assuming, of course, that the name of the screen field associated with CUS01-AMOUNT-DUE was SFIELD. That screen field dataname might well be different in several programs which each reference this database field; the translation would, naturally, be adjusted accordingly. This allows you to refer to screen fields without having to know their names.

    If the database field in question happens to be an arrayed field (it has an OCCURS clause), then you must include the occurrence number (maximum of 3 digits) within the at-sign brackets, i.e.:

    MOVE ATSADHNF TO @CUS01-ADDR (2) within the at-sign brackets is converted into the screen field's dataname, without any of the suffixes appended. You can code the desired suffix immediately behind the closing at-sign (no space between them) to reference any of the datanames in the screen definition. You could refer to the "Screen Painting" and "Color 3270" chapters of the Programmer's Reference Guidel for detailed discussions of the datanames in the screen mask copybook. Here is a quick review:

    Assuming that the screen field has a dataname of "SFIELD", the possible datanames found in the copybook would be:

    SFIELD the screen field itself, implied or explicitly PIC X(nn).

    SFIELDA the attribute byte

    SFIELDE the error byte for this field

    SFIELD-ED the Cobol edit picture, redefining SFIELD (if a numeric field)

    SFIELD-POSN the screen position of the start of this field

    SFIELD-COLOR the 7-color code (if a 7-color field)

    SFIELDH the extended highlight code (if a 7-color field)


    the julian equivalent (if a date field)


    the day of week code (if a date field)

    SFIELD-N the numeric value (if a numeric field)

    SFIELD-YY the year (if a date field)

    SFIELD-MM the month (if a date field)

    SFIELD-DD the day (if a date field)

    SFIELD-CC the century (if a date field with 4-digit year)

    You can reference any of these datanames in the mask copybook using symbolic references plus the appropriate suffixes. For example, to set the error flag for a field:


    Conditional References

    The symbolic references allow you to access screen fields without knowing their names. That solves half of the problem we described. The other half of the problem arises when we try to reference a screen field associated with the database field but some applications do not even display this data on the screen. In other words, there is no screen field. Once again, you have no way of knowing or controlling this at the time you define your Rules.

    The solution to this problem would be to make your references "conditional"; to state "if a screen field exists, then do so-and-so". You can do exactly that using MAGEC's conditional reference feature. To use this feature you must precede each symbolic reference with the -IFEXIST control statement. For example:


    MOVE ATUADHNF TO @CUS01-AMT ins in column 1, the Cobol line begins in column 11 (or beyond), just like any other Cobol statement.

    If there is no screen field associated with CUS01-AMT (in this example), the entire Cobol line will be ignored made into a comment line via an asterisk in column 7. If the line ends with a period (.), however, MAGEC will generate a "dummy" statement with a period at the end of it in order to avoid possible logic problems caused by a missing period. As a result, the above coding might be translated differently in two different MMP's. In an MMP having a screen field associated with CUS01-AMT you might see:


    In an MMP not having a screen field associated with CUS01-AMT, you might see:


    Now you have the ability to manipulate screen fields from within your Rules, so long as you use symbolic references and render them conditional.

    If you code two symbolic references on one line of code, and you have preceded the line with an -IFEXIST; if either reference fails the -IFEXIST test then the entire line will become a comment as shown above.

    In MAGEC's screen painter there is nothing to prevent you from defining multiple screen fields with the same database field specified as the source/target for all of them. This may even be a useful technique in some cases. If you code a symbolic reference using a database field name which is associated with more than one screen field, you will receive a warning message (in the generated code) telling you that this is an ambiguous reference; MAGEC will generate the translation using the first match found.


    An example of the coding of multiple conditional symbolic references:




    MOVE ALL '?' TO @CUS01-CITY@



    - et cetera -

    Version Verification

    The VERZUN Function

    The database administrator is often called upon to assist application developers to find and correct errors in their applications. Our experience with MAGEC users since 1981 has taught us that a very large percentage of the problems developers encounter with their (MAGEC, or non-MAGEC) applications are caused by executing an old version of their programs, or accessing an old version of a screen Mask, or executing a program compiled with an obsolete version of a copybook. One of the values of a central, active dictionary is the ability to quickly ascertain which version is the current one and which version is being executed.

    You could, of course, use the online inquiry functions of MAGEC to lookup the current version number (or date) for each entity involved. That would take a few minutes and would depend upon your accurately navigating through the dictionary. In addition you would need to view the actual load module of the program in question to determine (from the "core mark") when it was generated and compiled.

    MAGEC provides a special online facility (for MAGEC online applications only) to enable you to obtain all the necessary information with a single inquiry. It is the VERZUN function.

    To use it online, enter one of the following commands:

    VERZUN MSKxxx  

    VERZUN MMPyyy  

    VERZUN yyy  

    where: xxx               = Mask number

    yyy               = MMP number

    All of the above commands result in the same display. You have the option of giving either the MMP number or the MSK number (usually they are the same, but not necessarily) as a key, either way you will be shown statistics for all entities. You will be presented a display showing version dates and times for the program, screen, data definitions, copybooks, etc. The display will also flag possible problems based upon its comparisons of these version data.

    We feel that this should be one of the first steps a developer or DBA takes in trying to find a problem. A surprisingly large number of "support calls" received at the MAGEC support center involve just such errors as are detected by the VERZUN function. It might be a useful standard to always do the VERZUN function before calling for help since the support technician will likely ask you to do it.

    In order for the VERZUN function to ascertain all of the needed data about an application, that application must have been generated using version 2.0 (or later) of MAGEC. If the application was generated using an earlier version, you will receive a message saying so.

    Batch I/O Module


    MAGEC provides a batch I/O module which accomplishes the same functions as the online I/O module. The entry point which your program calls is MAGECIO, the module is named MAGDBMS.

    When you generate a batch program (an MBP) and use the MBPCREAT jobstream to compile and link it, the MAGDBMS module will automatically be included. This is true in both the mainframe and PC environments. In the mainframe environment another module (DATACOBT) is also included. If you were to write a batch program without MAGEC and wanted to use the MAGDBMS I/O module, you could do that. You would have to include the appropriate module(s) into your link and you would have to abide by certain conventions within your program.

    If you were to examine the Cobol listing of a generated MBP you would notice an area in the Working Storage section which contains the request area, element list, audit stamp area, and element data area. These are always in the same positions relative to one another. For example, the audit stamp area is always present even if none of the Data Classes being accessed has an audit stamp. In your programs which use MAGDBMS you will have to provide the same areas in the same sequence. All of these areas are fixed sizes except for the last one which is defined by your Element copybooks.

           01  DB-REQUEST-AREA.
    03 DB-CMD PIC X(5).
    03 DB-FILE PIC X(3).
    03 DB-KEY-NAME PIC X(5)
    88 NOT-FOUND VALUE '14'.
    88 REC-FOUND VALUE ' '.
    88 DUP-RECORD VALUE '10'.
    03 FILLER PIC X(61).
    03 DB-KEY-VALUE PIC X(256).
    01 FILLER.
    03 DB-ELT-LIST.
    01 DB-DATA-AREA.
    ..... insert -MAGECINC's for element copybooks here .....

    The exhibit shows the standard areas. The ELT00-C copybook expands to define the 36-byte audit stamp.

    File Opens

    When using the batch I/O module you have several options as to the opening of files you will be accessing. Special database commands are provided to give you the flexibility needed for your programs.

    MAGDBMS will automatically open a file the first time you access it, if it is not already opened. This is known as an implicit open. This enables you to easily convert programs which were originally written to access Datacom/DB (which also normally uses the implicit open).

    There are two ways that a file can be opened: open for update and open for read only. Unless you alter the default parameter, an implicit open will be for read only. If you wanted to alter the default so that implicit opens were for update, you would use the *LOAD command. To alter the default back to read only, use the *READ command.

    You can also do an explicit open of a file by using one of two commands: OPENU or OPENR. The OPENU command opens the file for update, the OPENR command opens the file read only.

    You can explicitly close a single file or all open files. The CLSFL command will close a single file, you specify it by the Element names in the element list. The *CLSE command closes all open files.

    Batch Security

    The same rules regarding the audit stamp apply in batch as in online programs. You may interrogate, but not update, the audit stamp. MAGDBMS automatically posts to it when you add or update. Pseudodeletion is also supported from the batch I/O module.

    Where-Used Reporting


    In the course of developing and maintaining applications we often find the need to know where a certain Data Item (field) or a certain Element is being used throughout all systems. This enables us to determine the impact of some proposed change before actually making it. It can also help us to ensure that various items of data are treated uniformly across systems. The MAGECLBR utility program produces a formatted Where-Used report for either an Element or an "include member". The online global search facility incorporated into the LBRSEE function allows a search for all references to a specific Data Item.

    To use MAGECLBR to produce a Where-Used report, execute the jobstream MAGLBREX (described in the "Offline Utilities" chapter) with one of the following control cards:

    -MAGECUSE ELT eeeee  

    where: eeeee               = Element name


    -MAGECUSE LIB nnnnnnnn/mmmmmmmm  

    where: nnnnnnnn               = member name

    mmmmmmmm               = its modifier (as appropriate)


    -MAGECUSE DIT xxxxxxxxxx  

    where: xxxxxxxxxx               = dataname (may be generic using dot or asterisk)


    -MAGECUSE TBL ttt  

    where: ttt               = table number


    -MAGECUSE DOM domainname  

    where: domainname               = domain name (up-to 20 characters)

    MAGECLBR will search for all references in both online MMP's and in batch MBP's, or in any other programs which have their source code catalogued to the MAGEC library. You can catalogue "raw" source code to the library using MAGECLBR with a control card as follows:

    -MAGECADD LIB nnnnnnnn/mmmmmmmm  

    followed by the data to be catalogued. Further information about MAGECLBR can be found in the "Offline Utilities" and "Librarian" chapters.

    To do a global search online for references to a dataname (or other character sequence) enter:

    LBRLST 1 (a list of members will appear)  

    Next, position the cursor down to the first item on the list (or whichever member you would like to begin your search with) and press the ENTER key. Next, key the desired dataname (or character string) into the Search Arg field and key $GBL into the Password field and press the ENTER key. You will be presented every reference to the desired dataname and instructed to press ENTER to continue searching after each one. The member names and their modifiers (if appropriate) will be shown on the top lines of the display. This same facility can be done using the ALGLST 1 command to begin the search, instead of the LBRLST 1 command. In that case you would be scanning Customization Algorithms rather than ordinary Library members.


    There is an online function which you can use to search for references to a MAGEC table. It will display a list of applications which have a given table number specifed as the lookup table for a screen field. The command is:

    SCDTBL nnn  

    where: nnn               = the desired table number (001 through 255)

    In order to limit online overhead the search is subjected to the standard "scan limit" or 1000 I/O's before it is interrupted. You can press ENTER to continue the search; however, if you wish.


    A special batch utility program is provided (MAGEC version 2.1 and later) to produce complete documentation for a Data Class, including where-used reporting. The DCLDOC program accepts a control card (multiple control cards are permitted) specifying the 3-character name of the Data Class for which you wish documentation printed. It reports on all Keys, Elements, Data Items, Business Rules, and references. The where-used reference report shows both primary and joined references for both online MMP's and batch MBP's.

    To invoke the report, execute DCLDOC with a control card as:

    DCLDOC xxx  

    where: xxx               =a Data Class name in columns 8-10 of the control card

    If you wish to have all lowercase alphabetics in the printed oputput converted to uppercase, use a control card as:

    DCLDOC xxx U  

    where: U               = literal "U" in column 12, a "Y" is equivalent to "U".

    Business Rules

    When you are entering or maintaining Business Rules online it is often useful to be able to see a where-used report to indicate which programs will be affected (need to be recompiled) if you alter this rule. From any of the RULxxx or ELTxxx functions' screens you can press PF6 to request such a report. The results wil be displayed to you online. You could also enter the command:

    RULUSE eeeee  

    where: eeeee               = the desired element name

    Domains Global Changes

    An offline facility is provided to help you to make global changes based upon Domain definitions. This enables you, for example, to change all zip codes from five digits to nine digits. That assumes, of course, that all zip code fields in all files are defined as belonging to the same Domain.

    To make such a global change you would first alter the definition of the Domain. This is done online using the DOMCHG function. Next you should run a where-used report to give yourself documentation of all references which are going to be altered. You may skip this step at your own peril! The global change operation will also produce a report of what was changed, but you might prefer to know what will be changed beforehand, then compare it to the report produced after-the-fact.

    Finally you would execute the global change operation. To do so you would execute the MAGECLBR batch utility using a control card of:

    -MAGECGBL DOM dddddddddddddddddddd  


    dddddddddddddddddddd               = the desired Domain name


    This operation will alter the Data Item definitions for all fields affected. It will not alter any Element, Data Class, Key, or file definition (i.e. IDCAMS) parameters. It is up to you to make any needed changes to record lengths, key lengths, element lengths, or displacements. It may also be necessary to unload, reformat, and reload the data from the files. The reports produced should provide you with a checklist of modified Data Items and Elements the rest is up to you.

    File Reorganization

    MAGEC's dictionary files are simple VSAM KSDS (on the mainframe) or standard indexed files (on the PC). They are single key files (no alternate indices). They should be occasionally backed up and reorganized to maintain optimum performance. The method used to reorganize these files is no different from the method used to reorganize other such files in your environment. MAGEC provides some assistance in the form of pre-coded IDCAMS (or AMSERV) control cards (on the mainframe) and a .BAT file (on the PC).


    There are three members on the MAGEC library (ALG file) which will help you to reorganize the dictionary VSAM files. They are:


    The procedure for reorganizing and backing up the files involves:

    1) backup to tape using the IDCAMBKP/REPRO control cards,

    2) deleting and redefining the files to the VSAM catalogue using the DEFFILES/VSAM control cards, and

    3) reloading the files using the IDCAMRST/REPRO control cards with the tape from step 1 as input.

    The control cards provided are merely samples. You may wish to customize them for your particular environment. In the backup and restore control cards you will notice the NOREWIND parameter specified. The MVS version of IDCAMS does not support that option, so you will want to remove it if you are an MVS installation.


    The PC (simulated) VSAM files can be reorganized using a .BAT or .CMD file provided with MAGEC. It is necessary to have enough disk space available on your hard disk drive to hold another copy of the file being reorganized since the process involves copying the file to a new, reorganized file and then erasing the old one and renaming the new one to the proper name. All simulated VSAM files in MAGEC have an extension of .DAT (for your information). The .BAT file is named: REORG.BAT and is in the \MAGMF\JCL directory. To invoke it, at the DOS prompt enter the command:

    REORG xxx  

    where: xxx               = the Data Class name to be reorganized)

    Although this procedure is generally very safe, it is smart to first backup your hard disk to tape (or other medium) before doing any reorganizations.

    TWA File Purge

    The TWA file is used by all online transactions as a place to store data to be passed from transaction to transaction and from program to program. There are several different types of records stored on the file for various purposes. Some of them are simply to provide pseudo-conversational processing for all transactions without imposing the need for the programmer to handle the saving of passed data and so forth. Other types of records are used by the online help facility, window swapping, and other integral features of MAGEC.

    The records on the TWA file have various different keys which identify what they are for; however, in all cases the keys are eight characters long and begin with the four-character terminal ID which makes the keys unique. This scheme also gathers all records for a given terminal in physical proximity to one another.

    Regular reorganizations of the TWA file are highly recommended.

    All of the records on the TWA file are dynamically created (added) whenever they are first needed, then they are reused (updated) as they are subsequently needed. For example, online documentation records will be created the first time that online documentation is used at a given terminal, then merely updated as online documentation is subsequently used at that terminal.

    This scheme works well and reduces overhead significantly; however, it has one drawback. The TWA file can become over-populated with records for terminals which are no longer active. There are three good methods for solving this problem.

    First. You can totally purge the TWA file and re-initialize it. This lets MAGEC dynamically re-add any needed records as the need for them arises. The adding of records is less efficient than updating in place, but the penalty is usually small and this method is a sure-fire way to solve the over-population problem.

    To do this you should execute the IDCAMS DELETE/DEFINE, then execute MAGINIT to initialize the file. This could even be done in the online startup JCL, if desired.

    Second. You can selectively purge the records for inactive (or any other) terminals via an online function. The command to do so is:

    TWAPUR tttt

    where tttt is the desired terminal ID. If you omit the terminal ID, all records for all terminals (except for the terminal where you are) will be purged (deleted). If you subsequently (after the online system is down, or the TWA file closed to it) reorganize the file, performance will benefit greatly.

    Third. You can automatically selectively purge records from the file which seem to be inactive (have not been used in thirty days or more) by executing the TWAUTIL batch utility program. Following that up with a reorganization is not mandatory, but it is a good idea since it will improve online performance. Active records will remain on file and not need to be re-created. Since TWAUTIL also "cleans up" some other types of conditions on the TWA file, some users execute it in either the TP monitor (i.e. CICS) startup or shut down procedure.

    Be sure that CICS is down before running TWAUTIL. If CICS is up a SOC1 will result. TWAUTIL performs the following functions:

  • Deletes TWA records that are more than 30 days old
  • Deletes CUTB, USR, DOC, and POP records
  • Deletes SPLR if no terminal references
  • Deletes any other TWA records not in the following format:
  • OS

    // AMP=('BUFND=11,BUFNI=3,STRNO=1')
    // AMP=('BUFND=11,BUFNI=3,STRNO=1')
    //SYS007 DD SYSOUT=*


    SET SYS007=CON[N]

    If you are using MAGEC on a PC or LAN (using MicroFocus Cobol), and if the TWA file is located on your local disk dirve (as opposed to a LAN server drive), then you can simply delete the TWA file and its index at any time that you are not actually executing MAGEC. To do this, type:


    at the prompt.

    MAGEC will automatically create a new TWA file when it is needed. This is an effective way to eliminate wasted space and cluttered indices. You can also do this same thing if the TWA file is being shared on a LAN server drive if you first determine that all users are off the system when you do it.

    Domain Definition

    What is a Domain?

    A Domain is a global data definition which is not associated with any particular Data Class (file) or Element; rather, it is used as a model for the Data Item definitions (DIT's) within many Elements throughout your systems. A Domain is not itself a Data Item, though its definition very strongly resembles the definition of a Data Item, but it can be used to enforce standardized definition of Data Items. As an example: you could define a Domain named "ZIP-CODE" which specifies five (5) digits numeric and includes a descriptive narrative which explains what a zip code is. Then, in all your Data Item (DIT) definition for a field which is a zip code you could specify "ZIP-CODE" in the Domain Name parameter. This would indicate that each of these fields belongs to the Domain named ZIP-CODE.

    MAGEC will verify that each of the Data Items belonging to ZIP-CODE has a definition compatible with the Domain's definition, i.e.: five-digit numeric. This helps you to ensure uniform definitions for similar data, in this example: zip codes.

    When you are adding new definitions for Data Items which are to belong to an existing Domain, MAGEC can save you some effort. If you fill in the Domain Name and leave all or some of the other specifications on the DITADD screen blank, MAGEC will fill them in automatically from the Domain definition. Refer to the topic DIT Entry Formats earlier in this section.

    If you need to know how many, and which, Data Items belong to any given Domain, you can use the where-used facilities of MAGEC to provide either an online display or a batch report listing all Data Items belonging to any particular Domain. If you wish to alter the definitions of all Data Items belonging to a given Domain, that can be done automatically using MAGEC's batch Global Change facility for Domains. Refer to the section, Where-Used Reporting, and the section, Domains-Global Changes, earlier in this chapter.

    Using the Domain definitions, MAGEC can fully automate the logical joining of data from multiple Data Classes (files), eliminating the need for the application developer to do any coding at all when developing multi-file accessing applications. Refer to the section, Logical Join, earlier in this chapter. This does not mean that the developer cannot code logic to access other files if he/she wishes.

    Domains can help you to save time in documenting your data definitions. If you provide a narrative description with your Domain definition, that description will automatically be applied to any Data Items which belong to that Domain if the narrative description for that Data Item is left blank. This means that for field-level help, if the narrative for the source/target field has been left blank, and if it belongs to a Domain, MAGEC will automatically display the Domain's narrative on the screen.


    DOMxxx Functions

    To add or maintain Domain definitions, use the DOMxxx functions. The screen and functions are very similar to the DITxxx functions and screen. Only the differences will be described in this topic since you can refer to the discussion for the DITxxx Functions earlier in this chapter.

    (DOM)//nnnnnn is the key which uniquely identifies the Domain. The prefix of "(DOM)" is constant. The two slashes indicate that the second component of the key is null. The nnnnnn is the sequence number, which is the actual unique ID of the Domain. The numbers 000000 through 000100 are reserved for figurative constant Domains, which we will discuss later. The remaining numbers are for your use in defining your own Domains.

    Level must be a numeric value from 50 thru 65. These are not valid level numbers to the Cobol compiler; they merely help you to identify this item as a Domain, not a Data Item. In a planned future release of MAGEC you may be allowed to define structures (group items with subordinates) in your Domains--as of the current version, only elementary definitions are supported. You should probably always specify a level number of 50 until such time as structures are supported for Domains.

    Dom. Name is the one-to-twenty character Domain name. It is similar to a Cobol dataname and follows the same rules for format except that you are limited to twenty characters. This is not a Cobol dataname, it is the Domain name. You do not specify a Cobol dataname for a Domain since it is not the definition of any particular Data Item (field), but rather the definition of a category of Data Items.

    Lgth has the same meaning as for a Data Item definition, except that if the Domain is a figurative constant Domain the length will be ignored (may be set to 00001).

    Pattern is the edit pattern associated with Edit Types "P" or "#", just as it is for Data Item definitions. In the Data Item definitions, however, this field on the screen is also used for the value associated with a condition name (88 level item). There can be no 88 level items among your Domain definitions, therefore, the prompt on the screen omits any mention of "88-Val/".

    PF6 is specified on this screen to invoke a Where-used display showing a list of Data Items which belong to this Domain.


     DOMxxx (DOM)//nnnnnn
    M A G E C D o m a i n
    Field Seq#: ...... Mode :.
    Level: Dom. Name:  Sig Dec Sign:  Usage:
      __ ____________________  PIC 9( __ )V9( __ ) _  _
    EditType: _ Tbl: ___ Req: _ Lgth: PIC X( _____ ) Just: _
      Occurs: _____ Depending On: ____________________
    Redefines: ____________________  Pattern: ____________________
    Prompt: ____________________

    Data Item Narrative:

    Press PF4 for browse (LOC) screen  Press PF6 for Where-used Summary
    Press PF16 to Copy field to buffer  Press PF17 to Paste data from buffer
    Press PF2 for field-level HELP 

    Figure 05 --  Domain Definition Screen

    Figurative Constants

    Domains defined with a sequence number less than 000101 are considered to be figurative constant Domains by MAGEC. These have meaning in the fully-automated logical join process. A figurative constant Domain name must be one of the valid Cobol figurative constants (i.e.: ZERO, SPACES, etc.), or a standard MAGEC-defined constant (i.e.: ONE, TWO, etc.) . In the fully-automated logical join matching process MAGEC knows that it does not need to find a matching Domain in order to fill in a Data Item (which is part of the primary key of a target joined Element) if it is specified with a Domain which is a figurative constant.

    This gives your developers the advantage of being able to automatically join to Data Classes whose keys include some constant prefix or suffix. For example, the SIF Data Class (Security Information File) has a key which is composed of two component fields: a key prefix which is always valued ZERO, plus an employee number. MAGEC knows that by moving ZERO to the key prefix and moving an employee number into the employee number portion of the key it can construct a full-key read of the SIF data. Imagine, for example, a purchase order file with the header records having a key prefix of ONE, the detail records having a prefix of TWO, and the trailer records having a prefix of THREE. Each of these record types could be defined as a separate Data Class with individual KYF (key), ELT ( Element), and DIT (Data Item) definitions.

    The length or number of digits (significant or decimal places) have no real meaning for figurative constant Domains. When you define the Domain you can specify any value greater than zero. When you define Data Items belonging to such a Domain, MAGEC will not care whether the length of the Data Item matches the length of the Domain definition.

    Compressed Data

    MAGEC includes the ability to compress data files in order to save disk space. This feature is included in the PC and UNIX versions of MAGEC as of release 2.6; it is planned for inclusion into the mainframe versions in a future release.

    To define and use a compressed file :

    On the DCL definition screen

    In programs

    When loading the file

    The mainframe MAGEC system will accept the MAGCMPRS specification as an access method, but will treat it as equivalent to VSAM--records will be store in their full size, uncompressed.

    Appendix A -- Error Codes and Messages

    CICS Abend Codes

    In testing and using MAGEC applications you might encounter a Transaction Failure with an accompanying Abend Code. If there is an error in the MMP itself or in the MAGEC software then the Abend Code might be one of CICS's standard ones, such as ASRA or AICA. If you have attempted to execute a program which has not yet been installed then you might receive the APCT code. These are standard codes which are documented in IBM manuals.

    MAGEC will, in certain situations, deliberately abort the task with a MAGEC-specified Abend Code. In PC MAGEC these codes are displayed on the top line of the screen, much as they are in CICS. Most of the conditions which will cause MAGEC to do this regard database or related problems. The MAGEC Abend Codes which you might encounter are:


    A Getmain command has failed (MAGECCP)


    A fatal VSAM return code was received (possible incorrect definition to TP monitor)

    The following Abend Codes consist of the prefix "DB" plus a two-digit number. These two-digit numbers are consistent with the error return codes placed into the MAGECIO Request area.


    Invalid I/O request attempted


    No such file defined


    No such key name defined (path)


    Invalid Record ID


    File is Closed (or Open Failure)


    File Opened Read-Only, Update attempted


    File is Full, cannot add records


    Index is Full


    Prerequisite for this command not met


    Attempt to add Duplicate record


    Attempt to alter Primary Key Value in record


    Internal record problem


    Internal record problem


    No Record Found, or End of List


    Exclusive Control Interlock -or- Record updated by another task


    Hardware Failure or File or Index Corrupted


    Element not defined


    Security violation


    Too many exclusive controls


    Bad Command for file


    Open/Close failure


    Database not Open


    Error retrieving repository definitions for file (PC)


    Error retrieving repository definitions for file (PC)


    Error retrieving repository definitions for file (PC)


    No Element record found for Data Class


    Table overflow - internal KYF/ELT table


    Unsupported command


    Commit/Rollback failed


    Inconsistent Element/Key Name


    Unknown access method


    Invalid Element List (not terminated by Spaces)


    Too many Exclusive Control requests


    Attempt to Update an Audit-Stamp


    No Exclusive Control Data (MAGECIO)


    ELT or KYF definition not found (MAGECIO)


    Incorrect Gateway for file (TCP/IP)


    MAGEC Host not responding (TCP/IP)


    MGCLIENT not installed / inaccessible (TCP/IP)


    Critical file Error


    Bad concurrent load


    Critical file missing


    Data Class missing


    Index error on duplicate key of alternate index


    Enqueue table error


    No dynamic storage


    Prime Key missing


    Table Load timeout


    No more table space


    Invalid command against a sequential file


    Incorrect record length (LRECL)


    MAGEC User-requested abend (via ABEND command to MAGEC I/O)


    Error Messages

    MAGEC or the MAGEC-generated MMP's might occasionally issue an error message which is displayed in either SCOMPL (top line of screen) or SERRMSG (bottom lines of screen) because they have detected an error associated with the database or files. This section will list the messages possible and suggested corrective actions where appropriate.

    TWA area clobbered by I/O

    The MMP has probably read (into TWA-DB-DATA) more data than is defined in the copybook(s) or data definition(s). The file data has overlayed the VARIABLE-STORAGE area which is below TWA-DB-DATA in the TWA.

    io ERROR has occurred

    The MMP has issued an UPDAT, or DELET command for a record which it (is supposed to have) read with intent to update and the specified record can not now be found. This might be a coding error in customization logic which destroys the TWA-DB-REQ-SAV area in the TWA or it may be a legitimate I/O error or the specified record may have been deleted from another region/partition/machine.

    DUP RECORD Pending Delete

    The MMP has tried to add a record having a key value which is a duplicate of the key value for a record which has been "pseudodeleted" and has not yet been purged from the file. This error should occur only on Data Classes having Audit Stamps specified. If it occurs on other Data Classes then it might mean that an actual duplicate record was added by another task while the operator was keying onto the screen and therefore this message should be interpreted as meaning the same thing as DUPLICATE RECORD ON FILE in that case.

    Error retrieving MSKnnn -or- MSK652

    The MMP issued a command to read its Mask initialization record from the MSK file and the command failed. The contents of the field TWA-DB-RETURN-CODE will indicate the type of error, see Abend Codes above.

    MMPnnn illegally entered

    The MMP was entered either from the MAGEC Control Program or from another MMP via FTHFUNCT command and it detected that the Function Code in SFUNCT (top line of screen) is not one of its valid Functions. It may be that the wrong MMP number is specified for that Function on the FCD file or that the %FUNCT customization logic is wrong for this MMP.

    MSKnnn Altered - ReCompile MMPnnn

    The MMP has detected that its Mask has been changed (that MSKCREAT has been run for it) and that the version number on the MSK file record for the Mask does not match the version number in the Mask copybook. Recompile (MMPCREAT) the MMP and be sure the TP monitor recognizes that there is a NEW COPY of the program then retry. You may check the version numbers by using the MSKSEE nnn Function and comparing the number shown against the version number shown in the copybook. You may see the copybook using the LBRSEE MSKnnn-C//002 Function.

    ERR91A-Warning - Bad Data on File

    The MMP was generated (MMPCREAT) with the VERIFY option and it has detected non-numeric data in numeric fields of the file. The bad fields will appear as asterisks (*) on the screen and may be corrected using the MMP's ...CHG Function if desired.

    attempt to FALL THRU program

    The MMP contains a coding error in the customization logic which is causing it to "fall through" the end of the program. Most likely cause is an incorrect PERFORM THRU or GO TO. Check the customization algorithms for such coding errors.


    The Activity Logging feature is generated in the MAGEC nucleus (TIMACCT = YES in ALAPARMS) and the MAL file has no more room to add records. Execute the MALUTIL program to extract the statistics to a backup tape and then either increase the file size or "clear" it by deleting all the records from it. This condition will not prevent the online Functions from processing but will cause the Activity Log data to be incomplete.


    An I/O error (other than File Full) was detected in reading, adding to, or updating on the MAL file. The Error Return Code will be in the TWA field and will also be displayed in this message, see Abend Codes above. This condition will not prevent online processing but will cause the statistics to be incomplete.


    The MMP is attempting to update a record(s) of a Data Class which has Audit Stamp support generated (on the DCL file definition). It has detected that the Audit Stamp has been altered between the time the record was read first (and the data displayed on the screen) and the time it was read with intent to update. This probably means that an operator at another terminal (or a batch program) has updated the record and that the displayed data is possibly obsolete. This MMP will not be allowed to update the record without re-initiating the Function in order to re-display the record in its current state. The easiest way to reinitiate it is to alter the Function Code from a ...CHG to a ...SEE to re-display the data then alter it back to ...CHG.


    MAGEC's Control Program (MAGECCP) has tried to allocate an MMP for a Function which was entered and the MMP (name specified in message) was not found on the Core-Image or Load Library or the MMP is marked as being "Disabled" or it is too large for available memory. Try loading a "NEW COPY" of the MMP or recompiling it. It is also possible that the wrong MMP number is specified on the FCD file definition for that Function Code.

    Appendix B -- Glossary of Terms


    A special MAGEC Function Code which causes MAGEC to reload its main-memory "tables" from the Dictionary files in order to reflect any changes which might have been made. Used most often by database administrators and security officers.


    A control command which is used in conjunction with -MAGECINC and renders it "conditional".


    A control command which may be embedded in source code to cause the MMPCREAT or MBPCREAT process to "include" or "expand" another member at that point in the program.

    Activity Log

    A record of online activity by operator, terminal, and function which includes I/O, transaction, and error statistics maintained by MAGEC automatically.

    Audit Stamp

    A 36-byte Element used to record update statistics for a record.

    Business Rule

    A routine which is triggered (invoked) whenever a program updates or adds data for a specified Element. Primary purpose is to control integrity of data, including cross-field and cross-file validations.

    Authorization Level

    A one-digit (0 through 9) code designating a level of access authorization in the MAGEC security system. Operators have an individual authorization level in each of up to fifty Logical Applications, 0 = lowest (none), 9 = highest (deified).


    A TP monitor which is a product of IBM.

    Conditional MAGECINC

    A source inclusion which will be ignored if the same copybook has been included elsewhere in the same program, see MAGECINC and IFUNIQUE.


    A stored source-code definition of data, either a file Element or a Mask. Stored on the MAGEC library for use in the generated MMP's.

    Data Class

    A logical view of a file. A collection of data items which are grouped into Elements which are grouped into a record which resides on a file.

    Data Independence

    A property of application programs which renders them insensitive to changes in the physical structure of their data; i.e. record lengths, access methods. This property is imparted upon MAGEC applications via the dictionary-driven I/O modules.

    Data Item

    The MAGEC (and Cobol) designation for a "field" of a record (Element). Data Items must be defined as belonging to an Element defined on the ELT file.

    Datacom DB

    A database management system which is a product of Applied Data Research.


    Database administrator. A person who is responsible for managing the database resources for an organization. This person is usually a technically oriented individual who deals directly with the actual database control parameters and utilities as opposed to the more administrative person called the data administrator.


    Database Management System. A software or hardware product which is used to manage file data and simplify accesses.


    IBM's relational database which utilizes SQL.


    Standard MAGEC designation for Data Class. The DCL file.

    DD Name

    The "data definition" name used to define a file to the operating system in the TP monitor's start-up JCL. The name specified in the OS "DD" statement or in the DOS "DLBL" statement.


    The starting position (in the record) at which an Element or key begins, relative to 0000.


    Standard MAGEC designation for Data Items. The DIT file.


    A global definition which applies to data items in, potentially, many tables (files). A central definition from which individual data items can inherit specifications.


    Standard MAGEC designation for Element. The ELT file.

    Foreign Key

    A Data Item within one Data Class which is used as a key to access another, i.e: customer-number in an invoice Element used to access customer file.

    HELP Key

    A keyboard key, for online applications, which invokes a display of documentation pertinent to what the user is doing. MAGEC includes function-level, field-level, and error-level HELP automatically for online applications.

    Host Variables

    Data definitions which are included into a program for the purpose of reading into or writing from when using an SQL database management system.


    A control statement in MAGEC which is used in conjunction with the -MAGECINC control statement, rendering it "conditional".


    Keyed Sequenced Data Set. A type of VSAM file which is logically ordered via use of an index (key).


    Standard MAGEC designation for key definition. The KYF file.

    Logical Join

    A technique for logically associating the records of one file or Data Class to the records of another without using "physical" pointers.


    A control statement in MAGEC which causes a copybook to be included (expanded) at the point in a program where the -MAGECINC statement is encountered.


    A module which is part of the MAGEC nucleus. Its primary function is to handle the file and database I/O requests of the MMP's and to handle error conditions in a standard manner. It also makes up a part of the MAGEC Security System since it accomplishes the Audit Stamping.

    Master Key

    The unique key value which identifies a specific record. The key by which MAGEC MMP's access the record for all maintenance Functions.


    MAGEC Batch Program. A batch program generated by MAGEC from dictionary specifications.


    The batch jobstream used to generate MBP's.


    MAGEC Message Processor. An online program generated by MAGEC from dictionary specifications.


    The batch jobstream used to generate MMP's.

    Primary Key

    See Master Key.


    To simulate the deletion of a record by setting a "delete flag" on and then just updating the record. MAGECIO does this for Data Classes which have an Audit Stamp and for which Real Delete is set to N in the DCL file definition. MAGECIO also simulates a NOT-FOUND if a pseudodeleted record is read.

    Referential Integrity

    The property of a database of ensuring that all subordinate entities (i.e. invoices) have a valid controlling entity (i.e. customer) and that those relationships are not violated during ongoing database update, deletion, and addition processes.

    Request Area

    A fixed format area of memory into which the MMP's can move the commands and other parameters to communicate to MAGECIO (or MAGECCP) what operation is requested. TWA-DB-REQUEST, TWA-NONTP-REQUEST, and TWA-TP-REQUEST are examples of request areas.


    The portion of any MAGEC screen in which miscellaneous messages may be displayed, it is the rightmost half of the top line.

    Secondary Key

    A key for a record which is other than the Master (Primary) key and which need not uniquely identify the record since it is used only in browse Functions in MAGEC MMP's. Alternate Index.


    The last three lines of any MAGEC screen. The area in which Error messages are usually displayed.


    The portion of the top line of any MAGEC screen in which the Function Code is entered/displayed.


    The portion of the top line of any MAGEC screen in which the key value is entered/displayed for the Function being done.


    Structured Query Language. A database access language for relational databases.

    Subordinate Key

    See Secondary Key.


    Cincom's relational database system.


    Transmission Control Protocol/Internet Protocol. A protocol used to communicate between networks of computers


    A database "back end machine" which is a relational SQL database system.

    TP monitor

    Any of the software products which is designed to support online processing against 3270-type devices and from Cobol applications programs in a multi-tasking environment. CICS, WESTI, or Datacom DC, etc.


    Task Work Area. Main memory used by an MMP as work space and for passing data to other modules and for reading data into and writing from. Also used for saving data from task to task in a "pseudo-conversational" processing mode since it is saved and restored by the MAGEC Control Program as a service to the MMP's.


    To restore a pseudodeleted record to "undeleted" status by setting the Delete Flag in the Audit Stamp from X'FF' to blank.

    Version Validation

    The process of researching and comparing version numbers and creation/modification dates for all entities of an application to find possible sources of errors. Done using the VERZUN function of MAGEC.


    IBM's Virtual Sequential Access Method, including all its variations.


    A TP monitor which is a product of Westinghouse. No longer supported by MAGEC as of release 3.0


    A standalone computer, usually a PC, PS/2, or 9370 type machine, which is a functional replica of the main production system and which serves as a testing and development environment for analysts, designers, and programmers. Provides absolute separation of testing and production. MAGEC supports all of the workstation machines listed above.

    Appendix C -- Networks

    Distributed Databases

    MAGEC allows for installation on a network with the ability to distribute database files across multiple servers, physical disk drives, and logical disk drives. When MAGEC is installed you must determine on which drive the MAGEC reposittory files and executable (.EXE, .DLL, .BAT, .CMD, etc.) modules are to reside. Then, for each of your applications' database files, you must decide where they are to reside. MAGEC provides an easy way for you to specify where each file resides by entering the drive ID on the KYF (Key Format) panel (refer to page 11 in this section).

    MAGEC Software suggests the following configuration for LAN installations:

    1. all of the MAGEC repository files (.DAT) should be installed on the same drive on the same server.

    2. all nodes should refer to that drive using the same symbolic drive letter (i.e. G:).

    3. all nodes should include the SET LANDRV=G statement in their AUTOEXEC.BAT files (assuming that G: is the correct drive ID).

    4. each developer's node should have a local disk drive (usually C:) which has several megabytes available for work space and has the Cobol compiler installed in the \COBOL (MicroFocus) directory.

    5. the SET LCLDRV=C (assuming that C: is the corrcet drive ID) statement should be included in each node's AUTOEXEC.BAT file.

    6. as new application database files are added: if they reside on the same drive as is specified in the SET LANDRV= parameter, the KYF definition should leave the Drive ID specification blank. If they reside elsewhere, the Drive ID should be specified on the KYF panel.

    7. end users must have authorization via the LAN operating system to access the servers and drives on which their applications' files reside.

    8. If accessing via Windows, the SET statements must be done prior to entering Windows in order to apply to sessions within Windows.

    9. It is permissable for any user to have multiple MAGEC sessions via Windows concurrently. A unique "terminal ID" is assigned to each session. Clipboard may be used to copy data from one window to another.

    Also refer to the Networks section of your Application User's Guide for more about networks.

    Appendix D -- Datacom DB

    NonStandard Key & Element Names

    MAGEC employs a standard for naming Data Classes, Keys, and Elements. Many of the features of MAGEC depend upon that standard. For Datacom DB users who have installed MAGEC at the time that they installed Datacom DB the MAGEC standard is a very useful one to follow when creating definitions into the Datacom dictionary; thus, the name Datacom knows each entity by is the same as the name MAGEC knows it by. This is the ideal configuration; however, for some users it is not possible.

    MAGEC users who already had been using Datacom DB for some time prior to installing MAGEC will already have many Data Classes (Tables), Keys, and Elements defined to Datacom. These may not abide by the MAGEC standard. In order to provide compatibiliity for such situations, MAGEC allows you to specify the true Datacom name, if it is different from the MAGEC name, for each Key and Element.

    Standard Names

    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.

    The MAGEC standard requires that the Master key be named xxxK1(where xxx = the Data Class name). Subordinate Keys are named xxxK2, xxxK3, etc. Datacom permits you to give any 5-character name to your keys.

    MAGEC requires that your Elements be named xxxnn (where xxx = the Data Class name, nn is any two characters, usually numerics). Further, special meaning is assigned to the Element names xxx00 and xxx99. The xxx00 name indicates a 36-byte audit stamp Element. The xxx99 name indicates a 4-byte record descriptor word for variable-length records.

    To handle situations in which your Datacom names do not match the MAGEC standard, you must define the Keys and Elements using the MAGEC standard names, but specify the true Datacom names in special fields within the MAGEC definitions.

    If you have specified Datacom as the access method for a Data Class, there will appear on your KYFxxx screen and ELTxxx screen, special entry fields in which you can enter the true Datacom names. If you leave any of these entries blank, MAGEC assumes that the Datacom name is the same as the MAGEC name. These special entry fields have a prompt such as "CA DD Name".

    Database ID's

    Datacom DB permits you to define up to 999 Databases identified by 3-digit Database ID numbers. It also allows you to define tables with the same names in several Database numbers. For instance, you might have a CUS table in Database #101 and another CUS table in Database #367, et cetera.

    The MAGEC DCLxxx definition provides for you to specify a test Database number and a production database number for each Data Class. If you do so, MAGEC's I/O module will automatically insert the appropriate Database ID into the I/O request based upon whether you are a test user or a production user (according to the User View you used to access MAGEC).

    If you set the test and/or production Database number to 000 on the DCLxxx definition for a Data Class having the access method of Datacom, MAGEC's I/O module will not insert any Database number; rather, it will expect your application program to have set it (in TWA-DB-ID) as needed.

    Datacom DB I/O accesses only require the Database ID to be set if SYNONYM=YES is specified in the User Requirement Table (URT) enabling your program to access more than one table of the same name. If not, Datacom will ingore the Database ID.

    Appendix E -- MAGECSET

    Setting addresses into pointers

    There are numerous occasions when a programmer must load the address of some area of memeory into a pointer. One example of such occasion is when calling MAGEC's I/O module, refer to examples shown in "Sample Code" earlier in this Database Administration section.

    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:


    In this example, the data item named MY-POINTER must be defined as USAGE IS POINTER, though it may be redefined as PIC 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 MY-POINTER.

    Since not all MAGEC users are using ANSI 85 Cobol compilers, MAGEC provides a subroutine to accomplish the identical results as the SET statement shown above. The subroutine is named "MAGECSET", and it is used as follows:


    In this case it does not matter whether MY-POINTER is defined as PIC X(4), PIC S9(9) COMP, or any other format. MAGECSET assumes that MY-POINTER is 4 bytes long and sets the address of MY-DATA into it. The above statement will work identically whether you are using Cobol II, Cobol/370, VS Cobol (ANSI 74), or any other Cobol compiler. It works on the mainframe, PC, or Unix systems identically. It is therefore more portable than the Cobol SET verb.

    Appendix F -- Read-Ahead


    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 pass a return code back to your program indicating the success or failure of your request. However, it is also possible for your program to pass commands to MAGECIO using TWA-DB-RETURN-CODE. One of the commands you can pass here is "RQ", indicating that you would like the I/O module to queue records for you since you intend to do a number of sequential reads (REDNX, REDPR, or REDBR commands).

    If you are accessing a file which is local to you (not accessed via a Gateway), this command will be ignored by MAGECIO. If you are accessing a file which is remote using MAGEC's intrinsic TCP/IP networking capabilities, then MAGECIO will 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 program requests subsequent read-nex or read-previous commands MAGECIO will satisfy them from the buffer of queued records until that buffer-load of records is expired, then will request another block of records from the Gateway machine. This reduces the number of messages transmitted between the client and host machines, and can also enhance the benefits of MAGEC's built-in compression of those transmissions.

    Read-Ahead processing can greatly improve performance for sequential processing agains a remote file; however, its mis-use can impose a performance penalty. It is best to understand how read-ahead processing works in order to ensure optimum performance.

    When your application program calls MAGECIO to access a remote file, MAGECIO in turn calls MGCLIENT. MGCLIENT formats a Remote I/O Command message and sends it to the appropriate Gateway (using the IP address defined for that Gateway in MAGEC Table #248). The message is received by the MAGEC Host program (we will assume a name of "MGHOST") which calls the MAGECIO module at its location to access the requested data. MAGECIO (at the remote site) returns the data to MGHOST which formats a Remote I/O Response message and then sends it back to the requesting MGCLIENT in your computer. MGCLIENT formats the data returned into your TWA and returns control back to your local MAGECIO, which returns control back to your program. All transmissions are compressed for improved performance.

    The MGHOST running at the remote site checks whether you have set the "RQ" command into TWA-DB-RETURN-CODE, and are also doing one of the sequential read comamnds: REDNX, REDPR, or REDBR. If so, MGHOST will attempt to read several records and build a queue of records to send back to MGCLIENT, rather than sending only one record back. The number of records it will queue up is limited to either 16 records, or 16 KBytes of data, whichever is less.

    MGCLIENT receives this transmission containing a record queue and formats the TWA using the first record from the queue. It holds the entire queue of records in memory, in the area into which it was received, anticipating that your program's next request will be for the next record from the queue. For these purposes, reqeusts to files which are not remote do not count; therefore, your program may read several local files in between doing REDNX's (or REDPR's, or REDBR's) against the remote file. If the next request is the anticipated command, MGCLIENT will simply format the TWA with the next record from the queue, eliminating all overhead associated with the two-way communication with MGHOST. If the next command is not the anticipated command, MGCLIENT will destroy the queue of records and satisfy the request by sending a message to MGHOST, as it normally does.

    This means that any unused records in the queue are wasted. If your program then issues the next read-next request for the first file, it will have to be satisfied using the normal two-way communication.

    As you can see, improper use of read-ahead can cause your application to do unnecessarily large transmissions and wasted I/O at the host site. Used properly it can greatly reduce both the number of messages sent over the network and the number of bytes sent (compression is more effective for the larger blocks).

    It should be noted that for the read-ahead processing to work it is necessary that the TWA-DB-REQUEST area and the TWA-KEY-VALUE area be undisturbed from one request to the next. MAGECIO stores positioning information within these areas and checks for it on subsequent requests. If they have been altered MGCLIENT assumes that it cannot satisfy the request from its record queue and must pass the request on to MGHOST for processing. For this reason, your program should save both these areas after returning from MAGECIO, and restore them before the next request. This allows you to access other files in between. The default logic generated into your programs does the proper saving and restoring for your primary data class' data. The only exception to this is that the TWA-DB-RETURN-CODE will be returned to your program with the proper value to indicate the success of your request (usually spaces) and you will be (re)setting it to "RQ" prior to each call to MAGECIO.

    Also refer to the Networks section of your Application User's Guide .

    Appendix G -- File Opens & Closes

    Implicit vs. Explicit Opens

    When your programs access files using MAGECIO, whether in batch or online environemnts, they need never explicitly open the files unless the require a particular type of open different from the default which MAGECIO will use. For online program operating on a mainframe using CICS, your programs never issue explicit open commands and, if they do, the commands are ignored by MAGECIO and treated as a "no operation", exactly like the NOOPS command. For other environments. explicit open commands are honored, but if your program accesses a file using another command, such as a REDKY, prior to opening the file, an implicit open is automatically issued. SInce the file is then open, you must issue a close to the file before you can successfully re-open it differently. Therefore, it is usually easiest to issue your explicit open commands prior to your first file access to ensure that the file is opened properly.

    The implicit open is done in all environments unless you explicitly issue an open command; however, in the CICS environment file open and close capabilities are restricted by the CICS DFHFCT parameters. Files used by MAGEC are normally defined to CICS to be either opened initially as CICS is started up, or enabled to open as they are accessed. In online programs in any environment, it is unusual for you to ever issue any open commands. Most online programs simply use the implicit opens. If you do need to issue explicit opens in online programs, remember that each transaction constitutes a complete process and all files are closed as the screen is sent back to the operator. If you need to use an explicit open, it will have to be repeated for every transaction, i.e. do the open command in the %PREINIT insertion point.

    Default Opens

    When your batch programs access files and invoke the implicit opens, a default open type is used by MAGECIO. The default open type is OPENU (open for input-output). This default open type is set when your program is initiated. You can alter the setting of the default open type, if you wish. If you alter the setting, the new setting will apply to any files open after you have altered it. Files opened prior to your changing the setting will have been opened using the old setting.

    The *READ command can be issued at any time to change the default open type to OPENR (open for read-only). If your program is a report program which never needs to update any records on any files, you should issue the *READ command near the top of your processing logic so that all files will be opened read-only.

    The *LOAD command can be used to reset the default open type to OPENU. Your program can issue the *LOAD and *READ commands any number of times throughout its processing.

    Please not that these commands affect only implicit opens. Also note that explicit opens neither affect the default setting not are affected by it.

    Explicit Opens

    Several commands are provided for your programs to explicitly open a file. In the CICS environment all of these are ignored and treated as a NOOPS (no operation).

    The OPENR command will open a file for read-only.

    The OPENU command will open a file for input-output, allowing updates.

    The OPENO command will open a file for output, intiializing the file.

    The OPENE command will open a file "extended". This is valid only for a sequential file and allows you to add records to the "end" of the file.

    The OPENX command will open a file for exclusive input-output. That means that no other user on the network will be able to access that file until you have closed it or reached end-of-job. This command has meaning only on a LAN/WAN and is equivalent to OPENU if issued on a mainframe. Opening exclusively will greatly speed your processing sicne not sharing logic will be executed.

    Explicit Closes

    When an online program completes a transaction, sneding the screen to the operator, an implicit close is done (except in CICS) on all files that were left open. They will automatically be reopened with any positioning restored for the next transaction if needed. Explicit closes can be done prior to the end of your transaction, if you wish, to minimize resource consumption.

    Batch programs also have their files closed implicitly at end-of-job. You can issue explicit closes to enable reopening the file differently. For example, if you have created a new file by opening for output, you may want to close it and reopen it using OPENU to be able to access and update records on that file.

    The *CLSE command will close all files that are open and will issue a COMMIT to ensure that all data is flushed from file buffers and saved to disk.

    The CLSFL, or CLOSE (they are synonyms) commands will close an individual file.

    Appendix H -- Sequential Files

    To define a sequential file to MAGEC, use the access method SEQDS, SEQCMPR, OR SEQCRLF on the DCL definition. SEQDS specifies a fixed-length, non-compressed file. SEQCMPR specifies a compressed sequential file using the intrinsic compression facilities of the environments file systems (usually, MicroFocus Cobol). SEQCRLF specifies a sequential text file using Carriage Return-Line Feed ASCII characters to denote end-of-record.

    Sequential files can be accessed using MAGECIO, however only certain commands can be issued against them. Obviously, without an index many of the facilities available to VSAM or other indexed access methods cannot be provided.

    All of the explicit open commands are supported for sequential files, including OPENE, but excluding OPENI.

    All of the close commands are supported.

    The only read command supported is REDNX, which, for a sequential file requires no prerequisite except for an open.

    The ADDIT command is used to write to a sequential file.The file must have been opened using OPENE.

    The UPDAT command is used to rewrite a record to a sequential file.

    If you issue a database command which is not supported for sequential files, though it is a valid command for other file types, you will be issued a return code of '1S' in TWA-DB-RETURN-CODE.

    Generic File Names

    MAGEC in the PC environment allows you to define and access files using generic names. A generic name is one which includes one or more (maximum 7) question marks as the trailing characters of the file name. For example: FILE???.TXT.

    At the time that your program first accesses the file using either an explicit or implicit open (REDNX, OPENR, or OPENX) MAGEC's IO module will access the directory of the PC file system (may be either a LAN or local file) to determine whether there are any files whose names match the generic name given, and which file name to use. In the case of an input file that means that there may be several files with matching names, i.e.: FILE001.TXT, FILE002.TXT, FILE003.TXT, etc.

    The IO module will access the directory and will open the first (lowest in collating sequence) file. In this example FILE001.TXT. When you program reads to the physical end of FILE001.TXT, the IO module will again access the directory to obtain the next lowest file name and will open it as if it were concatenated to the first file, and so forth.

    In order to avoid conflicts, the IO module renames the input file using an extension of "_IN" before opening it, and renames it using another extension immediately after it is closed. The extension used for this final rename operation is taken from the KYF description in the "Extension after file is processed" specification. The extension given here should not be the same as the original extension and should not be "_IN". For example, a good choice for Extension after file is processed would be "DUN" (for "done").

    As you can see, using this scheme would mean that the IO module would first find FILE001.TXT, rename it to FILE001._IN, and open it for your program. When you have read through that file, it would rename it as FILE001.DUN and re-access the directory to find the new lowest file name matching the FILE???.TXT generic name. That would probably be ("probably" because of the possibility for multiple workstations to be performing the same process as discussed below) FILE002.TXT. Your program will read through several concatenated files as if they were one.

    Multiple Concurrent Processing

    Using this scheme it is possible for several (unlimited number) of workstations attached to a server to concurrently process a "pool" of transaction files. The same program could be executing on each workstation processing the transactions against the same database or master files. Since the files are renamed before and after processing, other workstations will not recognize them as input files. Therefore, one workstation might process FILE001.TXT, then another might begin processing FILE002.TXT. When the first reaches the physical end of FILE001 it will automatically begin processing FILE003.TXT.

    Generic Output Files

    In the case of generic file names for output files, the IO module will access the directory to determine the highest file name which currently exists matching the generic name. It will add one to the numeric (generic) portion of the file name and will open it for output using a temporary extension of "_OT". When your program closes the file the IO module renames it using the extension specified in the File specification, not the "Extension after file is processed"!

    Multiple workstations could be creating files using the generic name and each will automatically use a unique name. They would likely be creating a pool of transaction files which will later be accessed as described above.

    If you wish to write files using generic names your program must issue an explicit OPENO and an explicit CLOSE command.

    Generic Name Formats

    Only sequential files may be specified using generic file names. Indexed files may not. Sequential files are defined using the access methods: SEQDS, SEQCMPR, or SEQCRLF on the DCL definition.

    A generic name is any name including question mark characters (?) as the last characters of the name (not the extension). The question marks must be contiguous and may not be followed by any other character, except for the dot (.) which separates the name from the extension. There may be from one to seven question marks. The actual file names represented by the generic name must have numeric characters (1 - 9) in the positions held by the question marks. For example:

    A???????.TXT (files: A0000001 thru A9999999)  

    TRANS??.INP (files: TRANS01 thru TRANS99).