The purge program msut be a batch program, since the online I/O module will not allow you to read, much less delete, (cont.)
the pseudodeleted records. The batch program should use the normal MAGDBMS batch I/O module. Before the first access to (cont.)
the file it must call MAGDBMS using the special command "*PURG", which indicates to the I/O module that this program is (cont.)
to be allowed to read and update or delete pseudodeleted records, as if they were any other record. It is the (cont.)
responsibility of the purge program to interrogate the audit stamp (Element 00) and to take the desired action with the (cont.)
records.
Data Base ID
applies to Datacom DB files and should be left as 000 for others.
Block (CI) Size
is the physical size specified in the IDCAMS or database creation parameter.
Access Method
defines what type of file this is. Valid types include:
Code Meaning
BDAM BDAM, BDAMB BDAM Blocked, DATACOM DATACOM DB, DLI DL/I, SQL DB2, DQL/DS, Oracle, etc., DB2 DB2, ESDS ESDS VSAM, (cont.)
ISAM ISAM, KSDS KSDS VSAM, KSDSU Unblocked KSDS, RRDS RRDS VSAM, TDP TeraData VSAM, KSDS VSAM
The valid types currently supported by your installation of MAGEC are defined on the MAGEC Lookup Table #200. To see (cont.)
them use the Function Code:TBLLST 200. It is permissible to define TEST and PRODUCTION as having a different Access (cont.)
Method, perhaps to accommodate a conversion.
Gateway Name
specifies the name of the gateway (or host) machine that is used to access this Data Class. If this is blank or set to (cont.)
LOCAL, MAGECIO assumes that this data is accessed via ordinary local access. If a gateway name is specified here, all (cont.)
accesses to this Data Class's records is done via issuing a TCP/IP request to the named machine, which will process the (cont.)
I/O command requested and return the results. If MAGEC's TCP/IP networking feature is not installed you should always (cont.)
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.
## Datacom/DB
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 (cont.)
access method is Datacom. These additional screen fields allow you to specify to MAGEC the actual Datacom/DB names for (cont.)
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 (cont.)
necessary to enter anything into these special fields; however, if they are different you must enter the actual CA (cont.)
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 (cont.)
Datacom. In these cases they normally will have adopted MAGEC's naming standards universally and will have no need for (cont.)
alias names. Some users; however, already had a large number of Datacom databases in place at the time they implemented (cont.)
MAGEC and may not have adhered to MAGEC's naming conventions. These users will have need for the alias (cont.)
names.
MAGEC requires that the primary key (master key) be named as: xxxK1 (where xxx = Data Class name.) Alternate keys (cont.)
(subordinate keys) must be named xxxK2, xxxK3, et cetera. If your Datacom key names are different from this standard (cont.)
you must enter the definitions to MAGEC according to MAGEC's standards, but also enter the true Datacom/DB key names (cont.)
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 (cont.)
element names, e.g. xxx00 is an Audit-Stamp, xxx99 is the Record Descriptor Word for a variable-length record (for (cont.)
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 (cont.)
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 (cont.)
from Datacom/DB. Your programs will use only the standard MAGEC names. If you decide to convert one or more of your (cont.)
data files from Datacom to VSAM, or from VSAM to Datacom, no program changes or recompiles need be (cont.)
done.
# Defining Keys
## KYFxxx Functions
To add or change Dictionary definitions for file keys, use the Key Definition Screen and the KYFxxx Functions. The (cont.)
standard set of nine Functions is provided to support adding, updating, inquiring, and browsing against the KYF file. (cont.)
The key value is always the 5-character key name that is in the format: **yyyKn**, where: yyy = the Data Class name, K= (cont.)
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 (cont.)
definitions are used in the MAGECIO module and they are used by the program generator MMPCREAT to define the rules for (cont.)
"Normalizing the Key". See Figure 02 for a sample KYF screen.
Key Name
simply re-displays the 5-character (yyyKn) name.
Description
is up to 30 characters and may not be blank.
Cobol Name
is the actual dataname from the copy-book definition which defines the entire key field(s). It may be a group dataname. (cont.)
IT SHOULD NOT BE A NUMERIC (PIC 9..) FIELD. This entry is required for the Master key (key 1) and optional for (cont.)
Subordinate keys. It is required that the Master key (and all keys in VSAM) be one contiguous area within the record (cont.)
and that it have a single dataname so that MAGEC can generate a single MOVE to it in the MMP's.
File Specification
is the alphabetic LAN, UNIX. or PC path and file name (ignored in mainframe environment), that is optional.
DD Name
is the actual name (up to 8 characters in MVS, 7 in VSE, 8 in PC/LAN MAGEC) as the file is defined in the DD or DLBL (cont.)
JCL statements for the TP monitor start-up deck. For Datacom DB files this is comments only. It is possible for more (cont.)
than one KYF definition to specify the same DD name, thus allowing multiple definitions for the same "file" which may (cont.)
be used differently by different applications. One purpose for doing this might be to process different kinds of (cont.)
records in different formats on a single file. While we do not necessarily recommend that you design files having (cont.)
multiple record formats, MAGEC can be used to access them if they exist. For SQL or DB2 this is the table name, or if (cont.)
this is specified as an asterisk (*), the table name will be taken from the DCL description discussed (cont.)
earlier.
Displacement
is the position in the actual record at which the key area begins. If the key begins at the very start of the record (cont.)
(very common) then this would be 0000. If the file is Variable Length records, then there will always be a 4-byte (cont.)
record prefix appended. If the key field(s) begin in the very first bytes of a Variable Length record then the (cont.)
Displacement should be 0004. If the file has an Audit Stamp, the first 36 bytes will normally be designated as the (cont.)
Audit Stamp element (starting at displacement 0000 or 0004), other elements (and the key) will begin beyond the Audit (cont.)
Stamp.
Length
is the physical length in bytes of the key in the record. It must agree with the IDCAMS, AMSERV, or Database definition for the file (DD Name, if VSAM, ISAM, or BDAM).
Dup Key Flag
is a Y or N option which defines whether or not duplicate key values are allowed. This applies only to alternate (cont.)
(subordinate) keys, not to the primary (key #1). The prompt for this parameter will not appear on the screen for the (cont.)
definition of key number 1.
```
** KYFxxx yyyKn
M A G E C Data Dictionary
Key Definition
Key Name yyyKn Description: .......................
Cobol Name: ................................ DD Name ........
File Specification (PC or UNIX Only)
______________________________________________________________________________
Extension after file is processed: ____
Displacement: .... Length: .... Dup Key Flag: . (Y = Duplicate keys allowed)
---------------------------Component Fields-------------------------------
Field 1 Field 2 Field 3 Field 4 Field 5
max min type max min type max min type max min type max min type
... ... . ... ... . ... ... . ... ... . ... ... .
Field Types A = AlphaNumeric
N = Zoned Decimal Numeric WITHOUT Sign
Z = Zoned Decimal Numeric WITH Sign
F = Packed Numeric WITHOUT Sign
P = Packed Numeric WITH Sign
B = Binary Numeric
Press PF4 for browse (LOC) screen Press PF13 for Hardcopy
Press PF16 to Copy field to buffer Press PF17 to Paste data from buffer
Press PF12 for field-level HELP**
```
Figure 02 — Key Definition Screen
* **Note:** In the PC and LAN environments of MAGEC this field enables you to specify the drive (which may be a logical (cont.)
LAN drive) on which the data file and its indices exist. This allows you to have MAGEC installed on one LAN drive and (cont.)
to have your data files distributed across many drives, including having some on your local (C: or D:) drives. In MAGEC (cont.)
release 3.0 and later, this field is expanded to 79 bytes in length, allowing you to specify a complete filespec, (cont.)
including drive, path, and file name. If you specify an asterisk or space as the alphabetic drive ID, MAGEC will (cont.)
replace it with the LANDRV setting from your environment. If you leave the path and file name blank, MAGEC will use the (cont.)
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 (cont.)
the Drive ID, and you are using MicroFocus Cobol, MAGEC will build a filespec of: J:\MAGMF\MYFILE.DAT. The ".DAT" (cont.)
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 (cont.)
key component. At least one key component must be defined for the key. See the Key Normalization section of this (cont.)
chapter for further discussion.
Max
is the expanded size of this key component in characters (or digits, if numeric).
Min
is the minimum number of characters the operator may enter for this component.
Type
is the data type as shown on lower portion of this screen.
## Test & Production Files
If you would like to have test and production versions of your files then you may use a "symbolic" DD Name. A symbolic (cont.)
name is one which incudes the ampersand character (&) anywhere within it. All Test MAGEC User Views will replace the (cont.)
ampersand(s) with the letter "T"; all Production User Views will replace it with a "P".
Suppose you had a Production Customer Master file with the DD Name of:
CUSMASP and a Test version of it with the DD Name of:
CUSMAST Then you would simply specify the symbolic DD Name of:
CUSMAS& Your MMP's would access the Test file if executed from any Test User-View (TS01 thru TS08) and would access the Production file when executed from any Production User-View (PR01 thru PR08).
All the other Dictionary definitions associated with the CUSMAS& file also have provision for Test and Production (cont.)
profiles, as you will see in the following topics. In all cases the Test profiles apply in all Test User Views and the (cont.)
Production profiles apply in the Production User Views.
## Key Normalization
The definitions of the Component Fields (up to 5 of them) are used by the program generator MMPCREAT to control the key (cont.)
Normalization logic which edits and formats the SKEY data into the proper representation for accessing the file. Max is (cont.)
the number of digits or characters which the component consists of in its DISPLAY form. A 9-digit packed field may be (cont.)
only 4 bytes long on the file but it is 9 digits long when displayed on the screen or entered onto the screen and (cont.)
therefore is defined with Max = 09. Min is the minimum number of digits or characters which you wish to permit the (cont.)
operators to enter when entering this key component. If Min is the same as Max then the operators will be required to (cont.)
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 (cont.)
entered key value with leading zeros (if numeric) or trailing blanks to the length specified in Max. They will (cont.)
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 (cont.)
whether it is packed or binary or zoned-decimal. We recommend that file keys be made up of alphanumeric and (cont.)
zoned-decimal data without signs unless particular circumstances do not permit. Experience has shown that packed key (cont.)
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 (cont.)
either. If you do have files with packed and signed key fields they will be handled properly by MAGEC but it is still (cont.)
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 (cont.)
negative.
If you successfully add a new KYF definition then MAGEC will assume that you will most likely next want to add a new (cont.)
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 (cont.)
definitions to take effect immediately (without waiting for the online system to be brought "down" and "up"), then you (cont.)
must use the **LOAD Function.
## PC MAGEC
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:
xxxxxxxx.DAT
where: xxxxxxxx = DD Name specified in the KYF definition. The symbolic ampersand character (&) is not supported in PC (cont.)
MAGEC. The .DAT extension is always required. With MicroFocus Cobol implementations a .IDX file is created (cont.)
automatically. It is the index for the .DAT file of the same name.
## Alternate Indices
MAGEC supports alternate keys for any access method which permits them (primarily: VSAM, Datacom DB, and simulated VSAM (cont.)
in PC MAGEC). To define an alternate key (also called a Subordinate Key) simply do the KYFADD function for yyyKn (where (cont.)
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 (cont.)
use alphabetic "key numbers", but you may need to do some customization in generated programs trying to access that (cont.)
file. MAGEC will automatically generate the logic to support up to nine keys for all browse and query functions. All (cont.)
that you need do is have the KYF definitions on file at the time the MMP is generated. For file maintenance functions (cont.)
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 (cont.)
key values on alternate indices; however, it is not possible to correct every potential situation.
## Key HELP
When an operator is using a MAGEC-generated application and mis-enters the key value (on top line of the screen) and (cont.)
receives the "Invalid Key Format" message, he/she can press the HELP key (PF1) to receive online help text. You can (cont.)
store your own text (unlimited length) associated with any file key, or MAGEC will generate a default key format (cont.)
display to help the operator. Refer to the "Documentation" chapter for more details on Key HELP.
# Defining Elements
## ELTxxx Functions
To add new Element definitions or to update existing ones use the ELTxxx Functions. The standard set of nine Functions is provided for adding, updating, inquiring, and browsing against the ELT file.
You may not add an Element definition unless the Data Class definition is already on file (via DCLADD). The key for the Element Definition Screen is the 5-character Element name in the format:
yyynn
where:
**yyy** — = Data Class name
**nn** — = Element number (00 thru 99)
A sample Element Definition screen is shown in Figure 03. The data fields used by the screen are described below.

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