Element (Segment) is a display-only field which contains the Element name, in the format described above. Data-class is a protected field used to display the Data Class description associated with the Data Class name that is the first three characters of the Element name. Description is the 30-character description for this Element, and is a required field. Displacement occurs twice, once each for test and production. This is the starting position of this Element in the record (relative to zero). Length occurs twice, for test and production. This field contains the length of the Element in bytes. DEVELOPER AUTH. - BATCH contains the authority level required for a developer to create applications which access this Element from batch programs (MBP's). DEVELOPER AUTH. - ONLINE contains the authority level required for a developer to create applications which access this Element from online programs (MMP's). Employee having temporary Exclusive Control is the employee number (name displayed on the line below) of the employee who currently has exclusive control over this Element definition and its associated Data Items (DIT's). An Element is simply any portion of a record. It is defined as being an area, one or more bytes long, which begins at a (cont.) specified displacement into the record and continues for the specified length. If you had a fixed-length record 100 (cont.) bytes long and wanted to define it as one single Element then that Element would begin at displacement 0000 and have a (cont.) length of 0100. If, however, you wanted to define the record as two Elements you might define one Element as starting (cont.) at displacement 0000 for a length of 0045 and the second Element as starting at displacement 0045 for a length of 0055. (cont.) The term "displacement" means the position in the record relative to zero (the first byte is at displacement 0000). (cont.) Another way of expressing that is "the number of bytes preceding this". ``` ** ELTxxx yyynn M A G E C Data Element Definition Data Dictionary Maintenance Element (Segment)= yyynn data-class ............................... Description: ............................. test production Displacement: ..... ..... Length: ..... ..... DEVELOPER AUTH. - BATCH : . DEVELOPER AUTH. - ONLINE: . Employee having temporary Exclusive Control: ......... ............................... ** ``` Figure 03 — Element Definition Screen An Element is the "unit of transfer" between MAGECIO and your programs. By intelligently dividing your records into (cont.) Elements you can gain a degree of "data independence" for your applications. For instance, if a program uses only the (cont.) first 45 bytes of data (let us say that is the demographic portion) then it should only "read" that much. If you (cont.) discover that you must change the record format because you must add more data fields, lengthening the record and (cont.) lengthening the second Element described in the above paragraph, then it is likely that you will not even have to (cont.) 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. (cont.) That program would be affected by changes made to either of the two Elements. MAGEC allows you to define up to 99 (cont.) Elements for a Data Class plus the special Element number 00. Remember, also, that a given physical file may be (cont.) "redefined" by multiple Data Class definitions, each of which may have its own KYF and ELT definitions. Element number (cont.) 00 is the name of the Audit Stamp element which must be 36 characters long. If the Data Class does not have an Audit (cont.) Stamp (as specified on the DCL definition screen) then there should not be an Element 00 at all. If the Data Class does (cont.) have an Audit Stamp then Element yyy00 must be specified (where yyy = Data Class name) as a 36-character element, it (cont.) 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 (cont.) starting with 01 (00 for the Audit Stamp) and starting at the beginning of the record proceeding toward the end leaving (cont.) 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 (cont.) will not permit overlapping Elements, for now they are just "advised against". If a file is "redefined" as multiple (cont.) Data Classes then, of course, the Element definitions for one Data Class will be allowed to overlap those for the (cont.) other(s). The rule against overlapping Elements applies only within a Data Class. In order to minimize the impact of file changes it may also be a good idea to leave a little FILLER space in each Element to accommodate minor changes without having to reformat the files. ## Variable Length MAGEC supports variable-length records for access methods which allow them, normally that means VSAM KSDS and PC (cont.) MAGEC's simulated VSAM. When MAGEC's I/O module accesses a variable-length record it places a 4-byte prefix in front of (cont.) the actual record data. For all intents and purposes those four bytes are a part of the record. The four-byte prefix (cont.) contains the record length of the record just read. If you are updating records on a variable-length file then you can (cont.) set the length by moving it into this area, that will determine the number of bytes written or rewritten to the file. (cont.) In most cases it is useful to know the length of the record even when the file is only being accessed read-only. We (cont.) 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 (cont.) and a name of "yyy99". That also means that the first "real" Element would have a displacement of 0004. If the file has (cont.) an Audit-Stamp that is the first thirty-six bytes of the actual record then Element "yyy00" would have a displacement (cont.) 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 (cont.) the actual largest possible data record to accommodate the addition of the length prefix. It is also necessary to (cont.) specify the key(s) (in the KYF definitions) with displacement(s) four greater than you would if the records were (cont.) fixed-length. For example, if your variable-length record has a 36-byte Audit-Stamp followed by the key field, the KYF (cont.) 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 (cont.) to be taken "down" and back "up" you must use the **LOAD Function to tell MAGEC to reload its main memory images of the (cont.) Dictionary definitions. For example; to define a variable-length, audit-stamped record with a length of from 20 to 100 bytes, with a 5-byte key immediately following the audit-stamp: Max Length (on DCL definition) = 104 Element xxx99, displacement=0000, length=0004 Element xxx00, displacement=0004, length=36 Element xxx01, displacement=0040, length=64 Key xxxK1, displacement=0040, length=0005 ## Element 99 Format For variable-length records the 4-byte record prefix should be defined as a separate Element (number 99). This special (cont.) Element should have a displacement of 0000 and a length of 0004; it should also be defined as containing three Data (cont.) Items (DIT's). The first one is the standard group item defining the entire 4-byte Element, the other two are the (cont.) component (elementary) fields which make up the Element. One of them is the 2-byte binary field containing the record (cont.) 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 (cont.) length before any add or update operation. Setting the length properly is the responsibility of the application (cont.) developer. When a program, either an online MMP or a batch program, accesses data from a variable-length file it should specify (cont.) the 99 element as part of its Element List. If the program reads data and does not include element 99 then the record (cont.) length will not be returned to it. If that program updates without setting the length (which it cannot do if it has not (cont.) read element 99) then the MAGEC I/O module will set the new length equal to the old length -- which may or may not (cont.) truncate some data from the record. # Cobol Copybook ## Copybook for use in MMP's In order for the generated MMP's to properly access data from the database or files they must have a Cobol copybook (cont.) which defines the Element(s) being read. In the case of preexisting files it is likely that a copybook already exists (cont.) on some library, however, it is unlikely that it will be ready for use by the MMP's without a few minor (cont.) adjustments. Most of your existing data definition copybooks probably start with a Cobol level of 01. In MAGEC these data (cont.) definitions need to be included into an area called the TWA, actually they need to be included into an area within the (cont.) TWA called TWA-DB-DATA that is a level 03 item in the TWA. It stands to reason then that the copybooks for MAGEC must (cont.) 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 (cont.) libraries (or others) but we recommend that they be stored, instead, on the built-in MAGEC library. The MAGEC library (cont.) is accessible via MAGEC in the normal online development process and when the program generator (MMPCREAT) generates (cont.) the MMP's it assumes that the copybooks are on the MAGEC library and inserts -MAGECINC statements (cont.) accordingly. There is a utility program (batch) provided which may be used to catalog a copybook (or any other member) to the MAGEC (cont.) 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. (cont.) In either case the copybooks must be named according to the MAGEC standards. There must be a copybook for each Element. (cont.) In the case of a preexisting file you likely have a copybook for the entire record and you will likely also define the (cont.) entire record as one Element. For new files you may wish to take better advantage of the Element (cont.) concept. The name of the copybook for an Element must be: eeeee-C where: eeeee** — = Element name **-C** — = the constant "-C" To use the MAGECLBR utility program to add a copybook you might code a control card (for MAGECLBR) as: -MAGECADD LIB eeeee-C followed by the actual data "cards" to be added. To add a copybook via keying it directly into the MAGEC library online you would use the Function Code LBRADD (and LBRCHG, etc.) as: LBRADD eeeee-C//ppp where: **eeeee-C** — = member name **ppp** — = page number A page is one screenful of data (15 lines) and a member may consist of up to 999 pages. Each page is actually one record on the MAGEC Dictionary file named the ALG file. Just as in any other environment it is important that the copybook is correct and that it defines the data accurately. (cont.) One of the common errors made is to define a copybook that is not as long (in bytes defined) as the data actually is. (cont.) When a program (MMP) reads an Element (or Elements) MAGECIO returns data for the length specified in the ELT file (cont.) definition for that Element(s). If the copybook defines a smaller area than the ELT file it is possible that you will (cont.) overlay whatever is below. In most cases the MAGEC-generated MMP's will detect this circumstance and will issue an (cont.) error message and abort. The message is: ++ TWA CLOBBERED BY I/O ++ In cases where the MMP's do not detect the error unpredictable results will occur. Check your definitions carefully. An example of the Cobol copybook to define an Invoice file with one Element and having a key of Customer number and Invoice number concatenated is: ``` 04 IVC01-ELEMENT. ``` ``` 05 IVC01-MASTER-KEY. ``` ``` 06 IVC01-CUSTOMER PIC 9(5). ``` ``` 06 IVC01-INVOICE PIC 9(6). ``` ``` 05 IVC01-DATE .... ``` - etc. This would be on the MAGEC library as a member named IVC01-C and could be viewed or altered online via: LBRSEE IVC01-C. (cont.) Notice that the Master key is defined as a group level item and broken down into its components. The group name (cont.) IVC01-MASTER-KEY would be specified on the KYF file definition for IVCK1 and could be seen via the online (cont.) Function: KYFSEE IVCK1 ## Recommended Standards The following topics set forth recommended standards for your data definitions and copybooks. We recommend that you use (cont.) 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 (cont.) recommended standards and to enter the definitions into the Dictionary; therefore, we have provided a facility in the (cont.) 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 (cont.) variety of services for you. The online access to the definitions is very useful for database administrators to (cont.) maintain central control of the database. The online application development processes access the DIT file to validate (cont.) developer's specifications and to provide intelligent default values. The DIT definitions help MAGEC to determine how (cont.) to properly translate from ASCII to EBCDIC and vice-versa when your program is accessing data from foreign files via (cont.) MAGEC's TCP/IP networking feature. # Defining Data Items ## Cobol Datanames In order for MAGEC to be of the greatest value to you we strongly recommend that you adhere to some special naming (cont.) conventions for your Data Items (fields within an Element). Remember, the Record of a Data Class (DCL) may be broken (cont.) down into one or more Elements. Each Element (ELT) may be broken down into one or more Data Items (DIT's). An Element, therefore, may be looked upon as a contiguous group of Data Items within the Record. ## Name Prefix As you might have guessed from examples shown earlier in this book we have established a standard that all Cobol (cont.) datanames for Data Items are prefixed by the name of the Element in which they appear. The name of a field (Data Item) (cont.) that is to contain the Customer's balance and that is within the Element named CUS02 might be: CUS02-BALANCE Next: https://magec.com/DOC/markdown/db04.md.txt