is the number of occurrences of this Item, if it is an arrayed Item. A value of 0 will indicate that this is not arrayed. A value of 1 is illegal. If you leave it blank, 0 will be assumed.
Depending On
is the Cobol data name of the control Data Item which contains the number of occurrences of an arrayed Item if there (cont.)
are a variable number of occurrences. If this entry is non-blank, then the Occurs value above is interpreted to be the (cont.)
maximum number of occurrences, the minimum being 0.
Redefines
is the data name of the Item which this Item redefines.
88-Val/Pattern
is the pattern for Pattern Edited fields (Edit Type "P" or "#"). For 88-level items, it is the value which this (cont.)
Condition Name defines. You can enter the actual literal here (such as 900 or X) and the DITGEN function will generate (cont.)
the surrounding quotes if needed. You can also enter the name of a library member which contains the value or list of (cont.)
values. This enables you to use value clauses that are far larger than would fit in the 20-character screen field. To (cont.)
enter a member name, just prefix it with an ampersand (i.e. &member/modifier) and the DITGEN function will generate an (cont.)
include statement in the Cobol copybook.
**Prompt**
is the column heading to be generated above this Item on columnar lists (such as the LOC, SCN, and FND screens) or (cont.)
batch reports, and also as a screen prompt when MAGEC automatically generates maintenance screen (cont.)
layout.
Domain
is the name (up-to 20 characters) of the Domain to which this Data Item belongs. MAGEC will enforce consistency in the definitions of all Data Items within a given Domain.
DataBase Identifier
is the up-to 20-character name used to identify this field to an SQL database. Used also to construct a Host Variable (cont.)
name. SInce an SQL identifier may not contain embedded spaces or hyphens, MAGEC automatically converts them to (cont.)
underscores. This is convenient since you cannot directly type an underscore into MAGEC screens because it is the (cont.)
universal fill character. SInce some SQL databases limit the identifier to 18 characters in length, you should limit (cont.)
your entries to 18 characters. In generating host variable names, MAGEC attempts to create unique names by prefixing (cont.)
them with the 5-character element name, if space permits, or with just the 3-character data class name -- or with (cont.)
nothing, if you have used more than 15 characters for your identifier. To ensure unique host variable names across (cont.)
multiple tables having identical database identifiers for some of their columns, limit your identifiers to 13 (cont.)
characters or fewer.The database identifier has no meaning for non-SQL data, it will be ignored. It is required only (cont.)
when the access method is SQL or DB2 (as specified on the DCL definition for the Data Class).
Data Item Narrative
is the 8-line free-form text field which contains the explanation and any other comments to describe this Data Item. (cont.)
When an online application user invokes the field-level HELP by pointing to a screen field with the cursor and pressing (cont.)
PF2, this text will be presented along with a textual description that is generated from the specifications (cont.)
above.
Offset / Length
is the calculated offset (within the Element) of this field, and its length in bytes. This is displayed for (cont.)
informational purposes only and is calculated by the DITGEN function described in Generating the Copybook, below. Until (cont.)
DITGEN has been executed these values are unreliable.
## 88-levels
You can specify Cobol 88-level items (Condition Names) below any Data Item. The 88-levels are defined as separate Data (cont.)
Items which may only have the VALUE parameter specified and no others, exactly as in the compiler. For numeric items (cont.)
you just enter the numeric value as: 99, or 23, etc. You may also enter ranges as: 101 THRU 199. In order to support (cont.)
lists of values too large to be entered into the 88-Val/Pattern screen field (above), MAGEC allows you to enter the (cont.)
name of a library member which contains the values. Refer to description above.
## Exclusive Control of ELT
You must have exclusive control of the Element (and all its Data Items) before you will be able to do any form of (cont.)
database updating Function to the DIT file (DITADD, CHG, DEL, GEN, or SEQ). Exclusive Control means that only you are (cont.)
allowed to do any form of updating and all other persons will be prevented from updating that Element's Data Items (cont.)
until you are finished. This prevents the confusion which might result from more than one person making changes to the (cont.)
same Element. If you wish to see who has control of it, use the Function:
ELTSEE eeeee
where:
**eeeee** — = Element Name
To get Exclusive Control of an Element, use the ELTCHG Function and then enter your Employee Number (same as you use to SYSLOG ON) into the screen field labeled:
Employee Number Having Temporary Exclusive Control:
If there is already another person's Employee Number in that field you should check that he/she no longer needs to (cont.)
retain Control of that Element. On the other hand, when you are finished you can save someone else a bit of aggravation (cont.)
if you remember to remove your Employee Number from the ELT-record field by changing it to zeros.
## Allowing Multiple Persons Access
In some cases you may want more than one person to be able to do updating Functions to the DIT records of an Element at (cont.)
the same time. An example would be to speed up the entry of the Data Item definitions for a large Element by dividing (cont.)
the work among several persons. To do that you might have all of them SYSLOG on using the Employee Number of the person (cont.)
having exclusive control. The employee would have to have multi-terminal logon capability specified on his/her SIF file (cont.)
profile in order to do this.
## Group Items
All Data Items (except 88-levels) have either a numeric or an alphanumeric PICture specified, even if they are to be a (cont.)
"Group Item". A Group Item is one that is to be "broken down" into one or more other Items having higher Cobol level (cont.)
numbers. The Items which break down the Group Item may, themselves, be Group Items and be further broken down by other (cont.)
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 (cont.)
Item (because the next Item has a higher level number) and generates a FILLER REDEFINES Item into the generated (cont.)
copybook. This allows for maximum flexibility for you while conforming with all the rules of the (cont.)
compiler.
## Examples of Group Items
Suppose you defined three Data Items as:
seq # level name PIC
000100 05 ZIP-CODE 9(5)
000200 06 SECTIONAL 9(3)
000300 06 SUFFIX 9(2)
**When you generate the copybook you will see:
05 eeeee-ZIP-CODE PIC 9(5).
05 FILLER REDEFINES eeeee-ZIP-CODE.
```
06 eeeee-SECTIONAL PIC 9(3).
```
```
06 eeeee-SUFFIX PIC 9(2).
```
where:
eeeee** — = Element Name
Now, suppose you added an 88-level Item "below" the ZIP-CODE, as:
seq # level name PIC VALUE
000150 88 OUR-TOWN 75252
When you generate the copybook you will see:
05 eeeee-ZIP-CODE PIC 9(5).
```
88 eeeee-OUR-TOWN VALUE 75252.
```
05 FILLER REDEFINES eeeee-ZIP-CODE.
```
06 eeeee-SECTIONAL PIC 9(3).
```
```
06 eeeee-SUFFIX PIC 9(2).
```
## Moving DIT's
You may at some time accidentally define Data Items in the wrong sequence and need to correct the error by moving one (cont.)
or more Item(s) either before or after another. Since the order of the Items is controlled by their assigned sequence (cont.)
numbers and since the sequence number is a part of the actual record key you must use a two-step process to accomplish (cont.)
the move.
First, you must use the DITDUP Function to duplicate the Item to be moved. Duplicate it to a sequence number which places it where you want it to be.
Next, you must use the DITDEL Function to delete the old record. If you like you may then use the DITSEQ Function to renumber into nice neat increments of 10 or 100.
## Generating the Copybook
To generate the copybook for an Element you must enter:
DITGEN eeeee/m
where:
**eeeee** — = Element Name
**m** — = Mode (defaults to "T")
If no one else currently has Exclusive Control of the Element then you will automatically be given Control. It is up to (cont.)
you to reset the Control when you are finished working with that Element by using the ELTCHG Function and zeroing the (cont.)
"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 (cont.)
error message; otherwise the copybook will be generated and added to the MAGEC Library (ALG file) with the correct (cont.)
standard member name (eeeee-C) and it will be displayed to you immediately via the standard "LBRSEE eeeee-C" (cont.)
screen.
To protect against your accidentally generating a copybook for the wrong Element MAGEC will present a screen to you (cont.)
with instructions to press PF14 to generate the book. On that screen it will tell you the name of the Element and the (cont.)
Member Name of the book to be generated and will remind you that the new book will overlay/replace any preexisting (cont.)
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 (cont.)
any were found. For instance, if the key field (as specified in the KYF definition "Cobol Name") is the wrong length, (cont.)
or a numeric type field, you will be told that a potential problem exists. DITGEN will go ahead and create the copybook (cont.)
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 (cont.)
function which will generate the SQL Host Variable definitions and store them in a member named:
eeeee-C/SQL
As of MAGEC release 3.0, the DITGEN function also parses the DIT definitions to construct a highly compressed table of (cont.)
translation parameters to be used by MAGECIO when an application accesses data from another machine (a Host machine) (cont.)
which uses a different coding scheme (ASCII vs. EBCDIC) from the machine on which the application is executing. In (cont.)
order to produce accurate parameters DITGEN accomplishes more extensive validations than in earlier releases of MAGEC. (cont.)
If discrepencies are encountered, DITGEN will stop and display an error message. If you wish to ignore these more (cont.)
thorough validations, you can press PF5 in lieu of PF14 (a message on the screen tells you this, as well). We recommend (cont.)
that you use PF5 here only in exceptional cases. It is best to go back to the DIT definitions and correct the errors (cont.)
noted, then redo DITGEN. The PF5 feature is there only to enable you to revert to the earlier, lower standard in an (cont.)
emergency situation. The hope is that at some future time you will return and correct any errors you have ignored to (cont.)
bring your data definitions up to current standards. Using the PF5 feature causes DITGEN to insert a warning message (cont.)
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 (cont.)
length (bytes) of each Data Item. These are displayed on the DIT screen for informational purposes only. The offset is (cont.)
relative to zero, with the first field in an Element having an offset of zero.
## Resequencing DIT's
To re-sequence (renumber) the Data Items for an Element use the command:
DITSEQ eeeee/m/iii
where:
**eeeee** — = Element Name
**m** — = Mode (defaults to "T")
**iii** — = Increment Value of 10 or 100 (default is 100)
Since the Mode defaults to T and the Increment also defaults, you may usually enter only the Element Name.
If an error is detected you will receive an appropriate message; otherwise the Data Items will be re-sequenced and the message:
PRESS ENTER TO SEE DATA ITEM LIST
will appear. Just press the ENTER key and the DITLST screen will be shown so you can verify the results if you like.
## Modifying Generated Copybook
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 (cont.)
regenerates the copybook then your modifications will be lost. Make your changes to the DIT file definitions and (cont.)
regenerate whenever changes need to be made.
Also, remember, planned features of MAGEC will use these DIT file definitions more and more. It is important that they be current and correct.
## Field-Level HELP
The DIT definitions, including the 8-line text narrative, are used in the field-level HELP facility of all MAGEC online (cont.)
applications. By pointing to a screen field with the cursor and pressing PF2, a user can invoke field-level HELP. The (cont.)
help text will consist of a combination of 1) the Data Item Narrative that is on the DIT definition, plus 2) technical (cont.)
specifications for the screen field that are translated into common English language. The specifications for screen (cont.)
fields are ordinarily inherited from the DIT that is given as its Source/Target database field.
# Accessing Files from Programs
## MAGECIO Requests -- Online
Application MMP's access database and VSAM files via MAGECIO. In order to use MAGECIO the MMP's must do the following things:
1. fill-in the MAGECIO Request Area in the TWA (it is named TWA-DB-REQUEST)
2. fill-in the key value (for some commands) (it is named TWA-KEY-VALUE)
3. fill-in the Element list in the TWA (it is named TWA-ELT-LIST)
4. set a pointer to tell MAGECIO where to read into or write from (it is named TWA-DB-AREA-A)
5. perform the built-in MAGECIO CALL routine (it is named AA840-CALL-MAGEC-IO THRU AA899-EXIT)
The program generator (MMPCREAT jobstream) automatically generates the necessary code for all the accesses to the (cont.)
"Primary Data Class" for the application (the one specified on the SHD Record for it). The developer may add some (cont.)
additional code to access other Data Classes. In either case the sequence of events will be the (cont.)
same.
## MAGECIO Requests -- Batch
Application MBP's access database and VSAM files via MAGECIO. In order to use MAGECIO the MBP's must do the following things:
1. fill-in the MAGECIO Request Area in the Data Division (it is named DB-REQUEST-AREA)
2. fill-in the key value (for some commands) (it is named DB-KEY-VALUE)
3. fill-in the Element list in the TWA (it is named DB-ELT-LIST)
4. CALL MAGECIO using the request area, work area, and element list as parameters. The work area is the area to read into or write from
The program generator (MBPCREAT jobstream) automatically generates the necessary code for all the accesses to the (cont.)
"Primary Data Class" for the application and for the "joined" Data Classes. You can code additional accesses via (cont.)
customization.
**Note:** The entry point "MAGECIO" uses a 76-byte DB-REQUEST-AREA, in older versions of MAGEC a 56-byte (cont.)
DB-REQUEST-AREA was used. The entry point "MAGDBMS" uses the old 56-byte request area for compatibility with older (cont.)
programs.
To fill in the MAGECIO Request Area the MBP must:

Next: <a href="https://magec.com/DOC/markdown/db06.md.txt">https://magec.com/DOC/markdown/db06.md.txt</a>