Introduction

---

Copies of this guide should be distributed to:

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

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.

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:

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:

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.

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:

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

NOTE:

• DLI, DB2 and SQL files are accessed via the DLI or SQL support intrinsic to your environment and not via the MAGEC I/O module.

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.

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.

NOTE:

• In the PC MAGEC environment MAGINIT will also create the new file, serving the function of the IDCAMS or AMSERV DEFINE operation.

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.

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.

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

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.

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.

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.

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

• recover accidentally deleted data

• detect fraudulent file updates

• identify which program puts "bad data" on file

• identify which operator puts wrong data on file

• identify during what time period (date and time)
  records are being updated (incorrectly?)

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

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

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

Code MeaningNE =

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.

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.

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

is up to 30 characters and may not be blank.

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.

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

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

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.

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.

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:

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.

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.

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

NOTE:

• MAGEC's I/O module will attempt to properly resolve many of the problems ordinarily associated with duplicate key values on alternate indices; however, it is not possible to correct every potential situation.

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.

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:

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

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

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

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.

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:

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.

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:

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

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:

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:

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

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:

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.

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.

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:

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

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:

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.

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:

06 eeeee-xxxxxxxxxxxxxxxxxxxxx-YY PIC XX.

06 eeeee-xxxxxxxxxxxxxxxxxxxxx-MM PIC XX.

06 eeeee-xxxxxxxxxxxxxxxxxxxxx-DD PIC XX.

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.

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.

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:

06 eeeee-xxxxxxx PIC .....

06 eeeee-yyyyyyy PIC .....

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.

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:

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:

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:

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.

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.

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

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.

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.

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.

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

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.

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.

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:

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:

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.

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.

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.

Suppose you defined three Data Items as:

seq # level name PIC

When you generate the copybook you will see:

06 eeeee-SECTIONAL PIC 9(3).

06 eeeee-SUFFIX PIC 9(2).

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

seq # level name PIC VALUE

When you generate the copybook you will see:

88 eeeee-OUR-TOWN VALUE 75252.

06 eeeee-SECTIONAL PIC 9(3).

06 eeeee-SUFFIX PIC 9(2).

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.

To generate the copybook for an Element you must enter:

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.

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

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.

DON'T MODIFY THE 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.

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.

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

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.

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

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.

NOTE:

• The entry point "MAGECIO" uses a 76-byte DB-REQUEST-AREA, in older versions of MAGEC a 56-byte DB-REQUEST-AREA was used. The entry point "MAGDBMS" uses the old 56-byte request area for compatibility with older programs.

To fill in the MAGECIO Request Area the MBP must:

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.

The valid MAGECIO commands are:

The following commands are valid only in batch programs:

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 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 Working Storage field named DB-KEY-VALUE is 256-bytes long and can therefore contain a file key up to that size.

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:

The Program would also contain, in its Data Division:

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.

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.

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.

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.

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:

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:

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:

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.

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.

NEXT SENTENCE

GO TO NO-INVOICE-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.

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.

NEXT SENTENCE

GO TO NO-INVOICE-FOUND.

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

NOTE:

• As of MAGEC release 3.0, batch programs (MBP's) include provisions to accept the same coding as is shown for MMP's on the previous page, as well as the coding shown above. This enables you to use the same Proformas and included routines in both online and batch programs. The MBP's include a redefinition of the request area so that, for example, moving a command to TWA-DB-CMD is identical to moving to DB-CMD, and so forth. The AA840-CALL-MAGEC-IO paragraph is also included in the MBP's, as is the pointer field TWA-DB-AREA-A.

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.

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.

Audit Stamps

---

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:

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:

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:

You may refer to the MAGEC "Data Definition" tutorial for additional instructions on the use of DBDITO.

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:

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:

To add a new Table to the system enter:

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.

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

To add a new entry to a given Table enter:

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.

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:

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.

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.

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:

MVS MAGINIT JCL

DOS MAGINIT JCL

PC MAGEC MAGINIT command

NOTE:

• With MAGEC on the PC or PS/2 you also have the MAGLOAD and MAGUNLD commands which are useful. They are described in the Installation Guide.

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.

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:

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

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

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.

RULWORK

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:

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.

RULPROC and RULDELT

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:

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:

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.

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.

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.

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:

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.

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.

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

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.

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

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

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.

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

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

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

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:

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:

MOVE ATUADHNF TO @CUS01-AMOUNT-DUE JCL = MOVE @CUS01-AMOUNT-DUE@-POSN TO TWA-MSK-CUR-AD-OT.

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:

MOVE ATUADHNF TO SFIELDA.

MOVE SFIELD-POSN TO TWA-MSK-CUR-AD-OT.

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:

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:

MOVE E TO EXXX99-FIELDNAME@

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:

-IFEXIST

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:

MOVE ATUADHNF TO SAMTA.

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

* MOVE ATUADHNF TO @CUS01-AMT JCL = MOVE SPACE TO SPACE-CHAR.

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.

NOTE:

• We strongly recommend that you make every symbolic reference conditional within your Rules. To do so you must place an -IFEXIST statement before each and every symbolic reference.

• The symbolic screen field referencing and -IFEXIST features are available to Application Developers as well as to Database Administrators. They are not limited to use only within Rules, but can be used anywhere in the Cobol customization for online programs.

• The spelling for -IFEXIST may be either -IFEXIST or -IFEXISTS, they are equivalent.

An example of the coding of multiple conditional symbolic references:

IF CUS01-CITY EQUAL SPACES

-IFEXIST

MOVE @CUS01-STATE CUS01-CITY JCL = -IFEXIST

MOVE ALL '?' TO @CUS01-CITY@

-IFEXISTS

MOVE E TO @CUS01-CITY JCL = MOVE '123' TO ERROR-NUMBER

- et cetera -

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:

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.

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.

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.

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.

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:

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:

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:

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:

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:

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

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:

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:

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.

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:

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:

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.

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:

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:

• Term ID valid terminal ID

• Split Code 0 or W

• User-view 1 thru 8

• User-modes T or P

• REC-NUMBERS 1 thru 4

//U2MSI1TX JOB (MSI),TWAUTIL,CLASS=M,MSGCLASS=X,
// MSGLEVEL=(1,1),NOTIFY=U2MSI2,REGION=4M
//TWADELET EXEC PGM=TWAUTIL,REGION=4096K
//* STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
//STEPLIB DD DSN=MAGEC.LOADLB74,DISP=SHR
// DD DSN=MAGEC.LOADLIB,DISP=SHR
//ALGK1 DD DSN=MAGEC.ALG.CLUSTER,DISP=SHR,
// AMP=('BUFND=11,BUFNI=3,STRNO=1')
//DCLK1 DD DSN=MAGEC.DCL.CLUSTER,DISP=SHR
//DITK1 DD DSN=MAGEC.DIT.CLUSTER,DISP=SHR,
// AMP=('BUFND=11,BUFNI=3,STRNO=1')
//DOCK1 DD DSN=MAGEC.DOC.CLUSTER,DISP=SHR
//ELTK1 DD DSN=MAGEC.ELT.CLUSTER,DISP=SHR
//ERRK1 DD DSN=MAGEC.ERR.CLUSTER,DISP=SHR
//FCDK1 DD DSN=MAGEC.FCD.CLUSTER,DISP=SHR
//KYFK1 DD DSN=MAGEC.KYF.CLUSTER,DISP=SHR
//LAPK1 DD DSN=MAGEC.LAP.CLUSTER,DISP=SHR
//MMPK1 DD DSN=MAGEC.MMP.CLUSTER,DISP=SHR
//PRMK1 DD DSN=MAGEC.PRM.CLUSTER,DISP=SHR
//REFK1 DD DSN=MAGEC.REF.CLUSTER,DISP=SHR
//SCFK1 DD DSN=MAGEC.SCF.CLUSTER,DISP=SHR
//SHDK1 DD DSN=MAGEC.SHD.CLUSTER,DISP=SHR
//SIFK1 DD DSN=MAGEC.SIF.CLUSTER,DISP=SHR
//TBLK1 DD DSN=MAGEC.TBL.CLUSTER,DISP=SHR
//TWAK1 DD DSN=MAGEC.TWA.CLUSTER,DISP=SHR
//DVCK1 DD DSN=MAGEC.DVC.CLUSTER,DISP=SHR
//SYS005 DD DUMMY,DCB=(LRECL=80,BLKSIZE=80,RECFM=FB)
//SYS007 DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*

c:
CD\MAGEC
SET SYS006=TWAUTIL.RDR[N]
SET SYS007=CON[N]
TWAUTIL
RE_SET

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.

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.

NOTE:

• The Tutorials manual contains further explanation regarding Domains in the "Data Definition" chapter under the section, Domains.

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.

NOTE:

• The definitions of all the Data Items belonging to a given Domain need not be identical, they must simply be compatible. As a rule-of-thumb, you should be able to do a Cobol MOVE from any one Data Item to any other Data Item belonging to the same Domain and the resulting value should remain intact. It is permissible for some of the Data Items to be numeric binary (COMP) while others are zoned decimal or packed (COMP-3). Certain other differences will be permitted, but with a warning message. For example: having some of the Data Items signed numeric while some are unsigned numeric would be accepted, but you would be given a warning that a sign could be lost.

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.

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 :

• specify MAGCMPRS access method.

• specify fixed-length (F) mode.

• read and write the records as if they were fixed-length.

• use MAGINIT to initialize the file before loading records

• use either an online program, or a batch program you have written which calls the MAGEC I/O module.

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.

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:

DBGM

DBVS

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.

DB01

DB02

DB03

DB04

DB05

DB06

DB07

DB08

DB09

DB10

DB11

DB12

DB13

DB14

DB16

DB17

DB22

DB23

DB24

DB30

DB35

DB36

DB81

DB82

DB83

DB8E

DB8F

DB90

DB92

DB93

DB94

DB95

DB96

DB97

DB98

DB99

DB9G

DB9H

DB9I

DBCE

DBCL

DBCM

DBDC

DBDK

DBET

DBNS

DBPK

DBTO

DBTS

DB1S

DBRL

MUxx

Note

• The CICS abend codes are normally constructed using the standard MAGECIO return codes prefixed by "DB".

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.

WARNING - MAL LOG FILE IS FULL

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.

WARNING - LOGGING ERRnn - MAL FILE

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.

DATA UPDATED BY ANOTHER TASK

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.

PROG NOT FOUND or DISABLED ===> MMPnnn

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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: