# Introduction

### Librarian Reference Manual

## Who Should Read This Guide

This guide is written primarily for use by those persons who will be using the MAGEC Librarian software to maintain programs, customization algorithms, and other types of library members.

Copies of this guide should be distributed to:

- Application developers

- Security officers

- Database administrators

- System programmers

- Auditors

This book is not intended to replace the online documentation but to augment it. Though there is some overlap, this book takes a grander, more general perspective while the online documentation is usually aimed at the particular function the operator is dealing with at a given time.

## Supplemental Reading

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

# Overview

## Purpose

The MAGEC Librarian is used to store and maintain "books" of source code or other data. The books, usually called "library members" or just "members", may be programs, copybooks, customization algorithms or default algorithms as well as any other data desired by the users. The MAGEC Library actually consists of a single dictionary file named the ALG file. There are five types of members on the ALG file. When you are using the librarian functions, either online or offline, you could easily get the impression that there are five separate files. However, the different member types are all stored on the one file with the high-order portions of their key values denoting the type.

The five types of members are:

- Ordinary library members

- Customization algorithms

- Default algorithms

- Named proformas

- Business Rules

Any of these may be displayed, updated, added, deleted, printed, or "punched" from the file using the online functions and utilities provided in MAGEC. The MAGEC Librarian is primarily designed for online maintenance, the offline utility functions are provided primarily to accommodate the migration of pre-existing members to and from other source librarian systems. The name of the batch utility program is MAGECLBR. You may refer to the "Offline Utilities" chapter for more information on the use of MAGECLBR.

Ordinary members on the MAGEC Library may be compiled or assembled (if they are programs) or may be "included" into other programs as "copybooks". Customization algorithms are used in the generation of MMP's (online programs) and MBP's (batch programs). They are created by application developers in the development process and are inserted into predetermined "insertion points" in the standard generated program logic. Default algorithms are also used in the program generation process, they are inserted into the predetermined insertion points if the developer has not created any customization algorithm for that insertion point. Named proformas are used to help minimize keystrokes when entering coding online. Business Rules are coded by the database administrators and are inserted automatically into any generated MMP's which are updating the associated data elements.

The inclusion and expansion of copybooks from the library is done by the program generator utility named MMPCRE (for online programs) and MBPCRE (for batch programs) which are used in the job streams MMPCREAT, MBPCREAT, and others. The "control statement" which is used to indicate that a copybook is to be included is:

`-MAGECINC mmmmmmmm`

where: mmmmmmmm = member name

It may be embedded anywhere in the program being compiled or assembled and any number of times. MAGECINC's may also be "nested"; a copybook being included may contain MAGECINC statements. The number of "nesting levels" allowed is determined at the time MAGEC is installed at your site, it is usually set to ten.

## Conditional MAGECINC's

In most cases it would cause difficulties to include the same copybook twice into the same program. Though there are exceptions, you would usually cause duplicate datanames and paragraph names and resulting compiler errors.

When one person is doing the coding for one program this is normally not a problem. S/he can easily control whether a copybook is -MAGECINC'd more than once. When several persons are involved in the coding for one program, however, it becomes more difficult to ensure that copybooks are not used multiple times.

A handy example of how this situation can occur is when Business Rule coding is inserted into programs. The Business Rules are coded by the DBA's. They are perfectly free to use -MAGECINC statements within their coding; in fact, it is very likely that they will do some I/O in some Business Rule logic and would therefore wish to include the appropriate element copybooks to read into. They have no way of knowing whether or not the programs into which these Rules will be inserted will also do I/O to the same elements and thus also include those same copybooks. Since multiple Rules can be inserted into one program, there is even the possibility for such a conflict between the Rules themselves.

MAGEC provides a facility to solve this problem: conditional MAGECINC's. You can use conditional MAGECINC's anywhere that you can use MAGECINC's; they are especially valuable in coding Business Rules and other routines which will be used in multiple programs. The facility enables you to specify that a member is to be included only if it has not been included elsewhere in this same program. In other words, only if it is unique within the program.

You code conditional MAGECINC's as follows:

`-IFUNIQUE
-MAGECINC member/modifier`

The -IFUNIQUE statement applies only to the -MAGECINC immediately following it. It must, therefore, immediately precede the -MAGECINC. It sets a "flag" associated with the specified member name to keep it unique (within this program); therefore, it works equally well even when another MAGECINC statement for this member appears physically after this one in the program. It works regardless of the nesting level of each MAGECINC.

## Mask Copybooks

The copybooks defining MAGEC masks (online screen formats) must be on the MAGEC Library in order for the generated MMP's (online programs) to properly include them. The utility job stream, MSKCREAT, or PF10 from MSKDEF, automatically places the mask copybook onto the library with the proper standard member name ( MSKnnn-C , where nnn = mask number).

## Element Copybooks

The copybooks defining data elements on the database must also be on the MAGEC Library in order for the MMP's and MBP's (batch programs) to include them. They are automatically placed onto the library when you use the dictionary to generate them from the DIT file definitions ( using the online DITGEN function). You may alternately use the batch utility (MAGECLBR) to catalogue your pre-existing copybooks to the MAGEC Library or you may also simply key them in using the online library maintenance functions (LBRADD, LBRCHG, etc.). You may also use the MAGECLBR batch utility to create the dictionary definitions (on the DIT file) from your pre-existing copybooks and then use the DITGEN function online to generate a new copybook. This last technique is the preferred one. In any case the data element definition copybooks must be named using the MAGEC standard member name (i.e. eeeee-C , where eeeee = element name). For more about this topic refer to the MAGEC "Database Administration" chapter.

## The ALG File

The MAGEC Library (ALG file) consists of records which each hold up to 15 "cards" of code. Since the librarian is online-oriented we usually call them "lines" rather than cards. The online maintenance screens also contain 15 lines of data, thus each record on the file is actually a "page" of display. This arrangement may be somewhat different from what you may have been accustomed to with other librarian systems where each "card" is actually a record. The page-oriented structure is intended to reduce online overhead, giving quicker response on inquiries, scans, and updates in high-activity or limited-resource environments.

The record key for the ALG file consists of:

Key prefix 4-characters

Member name 8-characters
(or insertion point name)

Modifier 8-characters

Page number 3-digits (000 - 999)

Any member may therefore consist of up to 1000 pages of code, 15 lines per page. As mentioned earlier, the key prefix is used to denote the type of member. The valid prefixes for library members are:

Prefix Member type

Description

LIB... Ordinary library member

May be a complete program or a copybook, etc., member name plus modifier make up the complete identity for the member.

DEF... Default algorithm

The key for this type of member consists of the insertion point for which it applies, plus the modifier, which is always "DEFAULT".

0xx...-9xx.. Custom algorithm

0xx - 9xx is the mask number (SHD number) for which it applies, the insertion point name must be specified, and the modifier may be any value.

0xxB..-9xxB.. Custom algorithm

Used for batch programs (MBP). 0xxB - 9xxB is the MBP number for which it applies, specify the insertion point name, and the modifier may be any value.

RUL... Business Rule

Defined by Database Administrator - associated with an element - inserted into MMP's and invoked when the element is updated

PRO... Named proforma

Frequently used code which you can have MAGEC place onto your screen to reduce coding effort. Member name plus modifier make up the complete identifier for the member.

# Offline Maintenance

## The MAGECLBR Utility Program

The MAGECLBR batch utility program provides numerous facilities for cataloguing, updating, printing, and punching members. It is not only used for members on the MAGEC Library (ALG file), it also may be used to access the documentation (DOC) and data item (DIT) dictionary files. In this book we are concerned only with those facilities which apply to the library.

You may refer to the "Offline Utilities" chapter for complete instructions as to the use of all the MAGECLBR facilities. Here we will simply try to direct you to the proper facility to do the tasks most commonly needed in day-to-day operations.

## Cataloguing to Library

Perhaps the most basic function of the MAGECLBR utility is to catalogue new members to the library. You may often find the need to add a "copybook" to the library or to add an entire program. It may well be that you are moving these members from some other source library to the MAGEC Library. To add a new member use the MAGECLBR control card:

`-MAGECADD ppppnnnnnnn/mmmmmmmm` where: pppp = key prefix

nnnnnnnn = member (or insertion point) name

mmmmmmmm = the modifier (optional)

You may add any type of member: ordinary library member, custom algorithm, default algorithm, business rule, or named proforma. It should be noted that the default algorithms are loaded to the library with the initial MAGEC installation and it is highly unlikely that you will ever have to alter them.

## Replacing a Member

If you wish to replace an existing member you may use MAGECLBR to do that also. The "replace" operation is equivalent to a "delete" followed by an "add". To replace a member (any type) use:

`-MAGECREP ppppnnnnnnn/mmmmmmmm`

where: pppp = key prefix

nnnnnnnn = member (or insertion point) name

mmmmmmmm = the modifier (optional)

If the old member which is to be replaced is on the library then it will be deleted and the new member (cards which follow the -MAGECREP control card) will be added. If the old member is not found on the library then the new member will be added just as though it were a -MAGECADD operation.

## Deleting a Member

To delete a member from the library (any type of member) you may use the MAGECLBR utility also. If you wish to delete a member then you should use the control card:

`-MAGECDEL ppppnnnnnnnn/mmmmmmmm` where: pppp = key prefix

nnnnnnnn = member (or insertion point) name

mmmmmmmm = the modifier (optional)

## Printing a Member

To produce a hardcopy listing of a member from the library use the MAGECLBR utility with a control card of:

`-MAGECPRT ppppnnnnnnnn/mmmmmmmm` where: pppp = key prefix

nnnnnnnn = member (or insertion point) name

mmmmmmmm = the modifier (optional)

## Punching a Member

You may use MAGECLBR to "punch" any type of member to the punch queue (DOS) or to any data set or PDS (OS). Of course, you could also actually punch to cards (whatever they are) if you wished. To punch a member use the control card:

`-MAGECPCH ppppnnnnnnnn/mmmmmmmm`

or

`-MAGECPUN ppppnnnnnnnn/mmmmmmmm`

where: pppp = key prefix

nnnnnnnn = member (or insertion point) name

mmmmmmmm = the modifier (optional)

## Punching Customization Algorithms

You may use MAGECLBR to punch individual customization algorithms or to punch all the algorithms for an application, as shown below:

`-MAGECPUN ppppnnnnnnnn/mmmmmmmm (individual)`

`-MAGECPUN pppp (all customization for mask# nnn)`

where: pppp = key prefix (mask #)

nnnnnnnn = member (or insertion point) name

mmmmmmmm = the modifier (optional)

MAGECLBR will insert -MAGECREP control cards in front of each of the punched algorithms so they may be "turned around" as input into MAGECLBR if desired.

The key prefix is a four character identifier in the format 9xx (for a mask #), or 9xxB (for a report); where 9 is a numeric digit, x is an alpha-numeric character, and B is the constant character 'B'.

NOTE:

- -MAGECPUN and -MAGECPCH are similar, but not identical. -MAGECPCH will not insert control cards in front of each member as -MAGECPUN will. For additional information refer to the Punching Members section of the "Offline Utilities" chapter.

## Re-sequencing a Member

When members are added (or replaced) MAGECLBR assigns the page number portion of the record keys. Although you may specify the increment to be used in assigning page numbers, it is most common to allow MAGECLBR to use its default increment of 02. This means that the first page will be page 002 and the next will be 004, etc. The reason that we usually increment by 02 (or some other value greater than 01) is to gain a further performance advantage when doing online library updating functions. The online library maintenance will operate more efficiently when lines are being inserted into pages if the pages are numbered with "gaps" which may be used for "overflow".

As you do online updating to members you may feel that you would like to re-sequence them occasionally to compress out blank lines and to re-number the pages into neat, even increments. To do this you may first punch, and then replace the member.

## Compressing a Member

When MAGECLBR punches a member it drops all blank lines and pages. When it replaces the member (using the punched output as its input) it will delete the old member and add the new one with page numbers evenly incremented. This can effectively reduce the file space taken up and optimize online maintenance to the member.

You are never required to re-sequence members, but if you wish to for efficiency reasons, you could use MAGECLBR with the control card:

`-MAGECPUN ppppnnnnnnn/mmmmmmmm`

where: pppp = key prefix

nnnnnnnn = member (or insertion point) name

mmmmmmmm = the modifier (optional)

The punched output will have a -MAGECREP card inserted in front of each member. Multiple members may be punched in one run. Then you could run MAGECLBR with the punched output as its input stream. This two-step process could be set up as one job-stream.

## Hardcopy Index of Library

To print a hardcopy index of the library, including information as to who "owns" each member and how many pages (records) can be recovered by compressing each member, execute MAGECLBR with the control card:

`-MAGECIDX LIB`

The index report also shows date and time last updated, and by whom.

## Where-Used Report

By using the MAGEC Where-Used Report you can obtain a hardcopy report of every reference to a library member. This is handy when you are contemplating making a change to an included member and you would like to know how many and which programs will be affected. To produce this report, you execute MAGECLBR with a control card as follows:

`-MAGECUSE LIB nnnnnnnn/mmmmmmmm`

where: nnnnnnnn = member (or insertion point) name

mmmmmmmm = the modifier (optional)

You can also produce a Where-Used report for a Data Item (field). To produce this report, you execute MAGECLBR with a control card as follows:

`-MAGECUSE DIT xxxxxxxxxxxx`

xxxxxxxxxxx = Data Item dataname

The dataname may be exact (complete) or it may be generic (partial) by using the "wild card" character, dot (.). Thus, a search for CUS01-Z . .-CODE would find matches on CUS01-ZIP-CODE and on CUS01-ZOO-CODE, et cetera.

You can also use the asterisk character (*) to render your search argument generic. The asterisk may be either trailing or leading to denote that you wish the matching logic to ignore either trailing or leading characters. Thus a search argument of: CUS01-ZIP* would find references to CUS01-ZIP, CUS01-ZIP-CODE, CUS01-ZIPPER, etc.

You can use both leading and trailing asterisks in the same argument. Thus a search argument of *ZIP* would find all datanames which contain the string "ZIP" regardless how many characters precede or follow it.

You can use asterisks and dots in the same argument.

NOTE:

- If you like to follow neat naming standards (i.e. all zip codes in any element will be named eeeee-ZIP-CODE, where eeeee is the element name prefix), you can easily find all references to any zip code by searching for: . . . . . -ZIP-CODE.

The -MAGECUSE DIT searches will search through all customization coding, ordinary library members, Business Rules, screen field and report field source/target designations, and default code. The report produced will clearly indicate where any references were found.

As a default, it does not search through "comment" lines. If the line of code has an asterisk in column 7 then it is bypassed. If you wish for it to search comment lines as well, then you must code a "N" in column 47 of the -MAGECUSE DIT control card to tell MAGECLBR to not bypass comments.

## Sample JCL for MAGECLBR

`` `---------------------------- D O S -----------------------------------
* $$ JOB JNM=MAGECLBR,CLASS=F
* $$ PRT CLASS=V
// JOB MAGECLBR
// EXEC PROC=MAGECLIB -pvt. libs. and DLBL's for dictionary files
// ASSGN SYS006,READER
// ASSGN SYS005,PUNCH
// ASSGN SYS007,SYSLST
// EXEC MAGECLBR,SIZE=(AUTO,10K)
-MAGEC... -----Control Card------`

`--------Data Cards------`

`(optional)`

`/*
/&
* $$ EOJ`

`` `---------------------------- O S ----------------------------------
//MAGECLBR JOB CLASS=0,MSGCLASS=0
//STEP1 EXEC PGM=MAGECLBR
//STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
* * * * * * * * DD's for dictionary files
//SYSOUT DD SYSOUT=W
//SYS007 DD SYSOUT=W
//SYS005 DD DSN=.......,DCB=(BLKSIZE=....) -- "punch" output
//SYS006 DD *
-MAGEC... ------Control Card------`

`--------Data Cards------`

`(optional)`

`/*
//`

# Online Maintenance

## The LBRxxx Functions

To do online maintenance and display against ordinary library members you may use the LBRSEE, LBRCHG, functions, etc. If you wish to access custom algorithms online use the ALGxxx functions, to access the default algorithms use the DEFxxx functions, to access the Business Rules use the RULxxx functions, to access named proforma members use the PROxxx functions. In this topic we will discuss the LBRxxx functions.

All of the LBRxxx functions include full online documentation so that you can press the HELP key (PF1) to get detailed instructions at any time you are using them.

## Online Index of Members

If you would like to see a list of all the member names (including their modifiers, of course) which are on the library you may use the command:

`LBRLST 1`

If you would like the list to begin at somewhere other than the first member on the library then enter instead:

`LBRLST nnnnnnnn`

where: nnnnnnnn = starting member name

The "index list" will begin at the member entered ( nnnnnnnn ) or, if there is no such member on the library, at the next higher member name. You may cursor select any listed member to request to SEE it.

## Online List of Records

If you would like to see a list of all the library records (pages) which are on file you may use the LBRLOC function. It is used just as the LBRLST function was, the only difference is that you will be shown one line for every page of every member. You may also cursor select any page shown to SEE it. This allows you to begin looking at a member somewhere other than at the beginning. The LBRLOC function might also help you to see how many pages are on the library for a member and whether you might wish to re-sequence it.

## LBRSEE Function

If you wish to look at a library member you might use the above LBRLST or LBRLOC functions and then cursor select the one you want to see, or, if you already know the correct member name, you might just use the LBRSEE function. When you cursor select (as described above) MAGEC automatically transfers you to the LBRSEE function. To save time you could just enter:

`LBRSEE nnnnnnnn/mmmmmmmm/ppp`

where: nnnnnnnn = member name

mmmmmmmm = the modifier (optional)

ppp = page number

You must spell the member name exactly as it is on the library, you may omit or abbreviate the modifier and you may omit the page number. LBRSEE will default to the first page for that member.

If you had two library members on file named PROGRAM1/TEST and PROGRAM1/PROD, if you entered:

`LBRSEE PROGRAM1`

you would be shown PROGRAM1/PROD (since PROD is before TEST in collating order).

If you entered:

`LBRSEE PROGRAM1/T`

you would be shown PROGRAM1/TEST.

If you entered:

`LBRSEE PROGRAM1/W`

you would receive the message "NO DATA FOUND for key".

When the screen is displayed to you with the first (or any other) page of data showing the function code will no longer say LBRSEE. Instead it will automatically be changed to LBRNXT. The LBRNXT function will "page forward" allowing you to browse through the entire member if you like.

When in the LBRNXT function you may page forward by pressing the ENTER (or PF8) key or you may page backward by pressing the PF7 key. If you see the place in the member where you want to make changes then you may just immediately overkey your changes or use the PF20 key to insert lines.

To delete a line from a member, simply blenk it out. To blank it out you could type spaces over the text on that line, or you could place the cursor left of the text and use the Erase EOF key. On a PC, the Erase EOF key is Ctrl-End.

## Updating a Member

The easiest way to update a member is to use the LBRSEE/LBRNXT functions to browse through it and then to begin keying your changes when you find the right spot. If you happen to know the exact record key, including page number, which you wish to update then you might alternately use the command:

`LBRCHG nnnnnnnn/mmmmmmmm/ppp`

where: nnnnnnnn = member name

mmmmmmmm = the modifier (optional)

ppp = page number

You must correctly key the member name, modifier, and page number. The specified page will be shown and you may then begin to key your changes, using PF20 and ERASE-EOF to insert and delete as above.

## Underscores

MAGEC automatically converts any underscore characters ( _ ) received from a CRT screen to spaces. That is because MAGEC uses underscores as the "fill" character to show the operator where the unprotected screen fields are and how large they are when doing certain functions. This presents a difficulty when you wish to enter underscores as part of your data on the screen (i.e. for some database languages).

In order to solve this problem, MAGEC's online librarian accepts a substitute character. You can key the substitute character onto the screen and it will be stored on the file as an underscore. The substitute character varies depending on whether you are using a mainframe computer or a micro (PC) computer. It is:

`Field-Mark on a mainframe 3270`

`Alt-196 on a PC`

The field-mark character is usually keyed on a mainframe 3270 by depressing Shift and pressing PA2, your keyboard may be different from that. The Alt-196 is keyed by depressing (and holding) the Alt key, then keying 1 9 6 (on the numeric keypad), then releasing the Alt key. The Alt-196 character has a similar appearance to the underscore when displayed on the screen.

## Tab Option

When you are keying your changes you might want to use the built-in tab controls to simplify your work. The "ruler line" at the top of the screen indicates columnar positions and also shows a semicolon ( ; ) at the pre-set tab positions. You may key a semicolon into the screen to indicate that you wish to automatically "tab over" to the next tab position. Continue keying your data behind the tab character (semicolon) and when you press ENTER to update the record you will see your entries align to the tab positions.

The tab positions are preset but you can alter them. You may key semicolons onto the ruler line where you wish new tabs set and dots (.) over the preset semicolons to "unset" the tabs you do not want.

When you are doing the updating (LBRCHG) function you will notice a field shown at the top of the screen titled TAB OPTION. It will have either ON or OFF showing in it. Usually it will be ON. Sometimes, however, you might have a need to enter data which contains semicolons and will wish to set the tab option OFF. You may do that by pressing the PF14 key which toggles the tab option ON and OFF.

When you are browsing through a member and then decide to immediately begin keying changes to the page shown, MAGEC will scan the page to see if there are any semicolons in the data. If some are found then it will automatically set the tab option OFF so that you do not accidentally and unknowingly alter data.

## Lower-case and Non-display Characters

The MAGEC Librarian functions transform lower-case characters to upper-case characters by default. The transform feature can be turned off on a line-by-line basis by entering an asterisk (*) in column 1 of any of the lines in the text.

Non-display characters will appear on the screen as a vertical bar (|) with an error message displayed at the bottom of the screen. Pressing PF5 with this message on the screen, will allow you to update the librarian member. However, the various non-display characters on the screen will each be replaced by a vertical bar on the file.

## Adding New Member Online

To add a new member using the online library maintenance facilities, you would enter:

`LBRADD nnnnnnnn/mmmmmmmm/ppp`

where: nnnnnnnn = member name

mmmmmmmm = the modifier (optional)

ppp = page number

You could use this command to add each page of the new member. You can also use this command to add a new page to an existing member.

Once you have added the new page you can use the LBRCHG function to update it. Since LBRCHG has some added features (such as PF20) that the LBRADD function does not have you may find it handiest to add the new page with little data (mostly blank lines) and then use LBRCHG to key the data in. Note, however, that you cannot add a page consisting of only fifteen blank lines.

The tab option works in LBRADD the same as in LBRCHG.

## Deleting a Page

You may sometimes wish to delete an entire page from a member. To do so you would enter:

`LBRDEL nnnnnnnn/mmmmmmmm/ppp`

where: nnnnnnnn = member name

mmmmmmmm = the modifier

ppp = page number

You may sometimes wish to delete a range of pages in a member. To do that enter:

`LBRDEL nnnnnnnn/mmmmmmmm/ppp/eee`

where: nnnnnnnn = member name

mmmmmmmm = the modifier

ppp = page number

eee = ending page number

NOTE:

- If ppp = the first page number of the member and eee = 999 , then the entire member will be deleted.

## Deleting (Purging) a Member

To delete an entire member you may either delete all the pages for that member as described above, or you could purge it by entering:

`LBRPUR nnnnnnnn/mmmmmmmm`

where: nnnnnnnn = member name

mmmmmmmm = the modifier

## Copying and Renaming a Member

To copy a member and give the copied member a new name, you would make the following entries:

`LBRCPY nnnnnnnn/mmmmmmmm`

where: nnnnnnnn = member name (source to be copied)

mmmmmmmm = the modifier (optional)

You then press ENTER. MAGEC returns a screen asking you to enter the name and optional modifier to be used for the member to be created (target member). After entering the key for the new member and pressing PF5, MAGEC will return a screen with LBRSEE in the function code (SFUNCT), the key for the newly copied member in the key area (SKEY), and a completion message in the upper-right corner of the screen (SCOMPL) telling you that the copy was successful. Press ENTER and the first page of the new member will be displayed.

## Copying Lines

The MAGEC PF16 and PF17 (Shift-F6 and Shift-F7, on a PC), Copy and Paste facility, which is provided with all MAGEC screens, also works in the online librarian screens. Since the librarian functions are "line oriented" rather than being "field oriented" the operation of PF16 and PF17 is slightly different, however. Also, there is a facility for copying a "block" of lines which does not exist in ordinary screens.

PF16 is used to Copy from the screen to the Copy/Paste buffer. You can position the cursor to any line of code (the lines are numbered from 01 through 15 down the right side of the screen) , and press PF16 that line (72 bytes long) will be saved in the buffer. Then you can position the cursor to a line and press PF17 the data from the buffer will be copied (Pasted) into that line on the screen.

NOTE:

- If you paste the data over an existing line, the old data in that line will be overlaid. If you first use the PF20 key to "open up" the screen for inserts you can paste the data into the opened lines, thereby inserting it into the existing code.

To copy a block of lines (several consecutive lines), you can overkey the line numbers (01 through 15 down the right side of the screen) with a "CC" to indicate the first and last lines to be copied, then press PF16. The lines starting with the first "CC" and up to and including the next "CC" will be copied to the buffer. Subsequently using the PF17 (Paste) key will copy those lines into your text. When you have keyed "CC" over the line numbers the Copy operation will ignore the cursor position, giving precedence to the "CC" block markers.

The block of lines copied in one operation must all be from one screenful of text since the PF16 (Copy) key copies data from the screen to the buffer.

You can copy from any screen of data, or from any member, to any screen. This enables you to copy a few lines from one routine or program into another without re-keying them. Once you have copied data into the buffer you can paste it multiple times the paste operation does not clear the buffer.

NOTE:

- the PF17 (Paste) key merely places the data from the buffer onto the screen, you must press ENTER to actually update the data on file. This also means that it is possible to try to paste more data than will fit onto the screen (i.e. if you Copy 6 lines then Paste it to line 14, there are only two lines left on the screen), in which case the data will be truncated.

- It is a good idea to pay attention to the messages presented in SCOMPL (right half of top line of screen) which tell you how many characters or lines were copied or pasted.

## Valid LBRxxx Functions

Below is a list of all valid LBRxxx functions:

LBRADD -- add a page to an ordinary library member

LBRCHG -- change (update) an ordinary library member

LBRCPY -- copy and rename an ordinary library member

LBRDEL -- delete a page from an ordinary library member

LBRDUP -- duplicate from an ordinary library member

LBRLOC -- locate/list all ordinary library member pages
beginning with the key entered

LBRLST -- list all ordinary library member names
beginning with the key entered

LBRNXT -- display the next page of an ordinary library member

LBRPRT -- print a librarian member

LBRPUR -- purge (delete) an entire ordinary library member

LBRSEE -- see/display a page of an ordinary library member

## Password Protection

The MAGEC Librarian provides the facility to protect a member with a password. This allows you to limit updating capabilities to only yourself and those to whom you give the password you have assigned. Not all members need such protection, so the password protection is optional by member. This feature should not be relied upon to defend against malicious attack, but, rather, to reduce the probability of accidental modifications being made. If no password is assigned to a member then anyone authorized to use the librarian functions (by the MAGEC Security System) will be able to access and update that member.

If you wish to assign or change a password for a member, use the LBRADD or LBRCHG function on it. Enter the special code "$NEW" into the PASSWORD field on the screen and press ENTER. You will see a new field appear on the screen labeled NEW PASSWORD. You may enter the password you would like to assign to this member into the NEW PASSWORD field and press ENTER. When the update or add takes place MAGEC will also record the new password. From that time on anyone wishing to update that member (ADD, CHG, or DEL) will be required to enter that password into the PASSWORD field near the top of the screen -- anyone, that is, except for you and persons having a "level 9" authorization in development functions (supervisors, security officers).

When you assign a password to any custom algorithm that password applies to all the custom algorithms for that mask number.

If you wish to see a password for a member, enter the special code "$SEE" into the PASSWORD field on the screen and press ENTER. If you are the owner of the member or if you have a "level 9" authorization in development functions, the PASSWORD will be displayed in the field where you entered $SEE, and a message will be displayed at the bottom of the screen.

To remove the password, simply change it to four asterisks (****).

## Member Scans

If you wish to scan for a character sequence (search argument) on any library member, you can do so using the LBRNXT function.

To scan for a search argument first enter the LBRSEE function to begin browsing. Remember that the function code will automatically be changed to the LBRNXT function. Next you must key the search argument into the area near the top of the screen labeled SEARCH ARG.

MAGEC will search each page of the member beginning with the one after the one shown on the screen looking for that search argument. It will stop at the first page in which it finds a "hit" and will display that page with each line in which there is a "hit" highlighted in either high intensity or red (depends on terminal type).

If the page shown is not the one you are looking for then press ENTER (or PF8) again and it will continue its search and will stop at the next "hit". If you see the page you are looking for and if you wish to make some changes to it then you may just immediately key your changes onto the screen and press ENTER. You may also use the PF20 key.

If you wish to scan "backwards" in a member you may do so. Just as you could page backwards using the PF7 key instead of the PF8 key you may have MAGEC scan for your search argument backwards by pressing PF7.

Searches are not case sensitive, that is: a search for "AbCd" will find matches of "abcd" or "ABCD" or "abCD", and so forth.

## Search Zone

You can limit the search zone (columns) to be scanned by typing parentheses on the ruler line (just above your text). If you do not type any parentheses, the entire line (columns 1 - 72) will be searched.

For example, if you enter a left parenthesis " ( " in column 11 and a right parenthesis " ) " in column 45, then MAGEC will scan columns 12 through 44 only. If you enter a left parenthesis " ( " in column 11 only, then MAGEC will scan columns 12 through 72. If you enter a right parenthesis " ) " in column 45 only, then MAGEC will scan columns 1 through 44.

## Global Scans

If you would like to do a global scan you can do it using the online LBRNXT functions if you are sufficiently authorized. Only those with a level 9 authorization for development functions may do global scans.

A global scan is done exactly the same as a member scan, except that you must enter the special code $GBL into the PASSWORD field. You may begin the scan at any record (any page of any member) on the library by first doing the LBRSEE function to position to where you wish to begin.

Global scans may be done backwards as well as forwards according to the same rules as for member scans. Press PF7 to scan backwards.

## Generic Scans

You may also do generic scans, either globally or against a member. To do a generic scan use the dot ( . ) in your search argument to indicate that any character is to be accepted as a match in that relative position. For instance, a search argument of:

`PERF..M`

would position you to "hits" on the character strings:

`PERFORM`

`PERFROM`

`PERF M`

and so forth. The search argument positions in which a dot appears are "masked out" of the comparison for a match. The dot ( . ) is a "wild card" character in scans, here and many other places in MAGEC.

## The MAGECINC Statement

The batch utility program, MMPCRE, is used to generate online MMP's and to expand "copybook" code. It is the first step in the MMPCREAT job stream and it produces complete, expanded source code ready for input into the compiler (or translator).

NOTE:

- MAGECINC statements are also discussed in the Overview at the beginning of this chapter.

If you wish to compile your own programs, batch or online, which need copybooks expanded from the MAGEC library then MMPCRE must be the first step in the compile job stream for them also.

The MAGEC "Offline Utilities" chapter includes sample JCL illustrating this. Refer to the MMPCREAT, and MAGECCOB & MAGECASM sections.

The control statement which is used to indicate that a copybook is to be expanded is:

`-MAGECINC nnnnnnnn/mmmmmmmm`

where: nnnnnnnn = member name

mmmmmmmm = the modifier

NOTE:

- The -MAGECINC must begin in column 1 of the control statement.

When MMPCRE encounters this statement it accesses the library to find the specified member and inserts that member in place of the -MAGECINC control statement. If the member is not found an error message results.

The member being included may itself contain another -MAGECINC statement, this is called a "nested include". Nesting is suported up to the pre-set limit (usually ten levels), if you exceed that limit the run will be aborted with an error message.

There are no restrictions on where in your program these includes may be done. They may be in the Data Division, Procedure Division, or anywhere else. There is also no limit on the number of includes you may have in one program. If a member (or program) includes itself it will create a "nesting loop" which will exceed the maximum nesting level and result in an aborted run and an error message.

## Conditional MAGECINC's

It is usually true that you will not want the same copybook included twice in one program. There are exceptions, however most of the time including a copybook twice would result in duplicate datanames or paragraph names and resulting compiler errors. When one person is doing all the coding for one program s/he has little difficulty controlling that each copybook is included only once in a given program. When a program is composed of portions developed by several persons, the problem arises of potential multiple -MAGECINC's for the same copybook in one program.

A prime example of how this can occur is when Business Rules include -MAGECINC's (usually to include an element copybook to read into) and they are inserted into a program which also includes -MAGECINC's for the same copybooks (because it needed to read the same element).

To solve this potential problem, MAGEC provides the means for you to make your -MAGECINC's conditional. A conditional -MAGECINC is one which will be expanded only if it is not included elsewhere in the same program. To code a conditional MAGECINC, code:

`-IFUNIQUE
-MAGECINC membername`

The -IFUNIQUE statement must immediately precede the -MAGECINC. Both statements begin in column 1.

## Printing a Member

To produce a hardcopy printed list of a librarian member you could do either of two things. You could execute the batch MAGECLBR utility program using a control card:

`-MAGECPRT LIB nnnnnnnn/mmmmmmmm`

or you could use the online function:

`LBRPRT nnnnnnnn/mmmmmmmm`

In both examples nnnnnnnn is the member name and mmmmmmmm is its modifier.

## Custom Algorithms

The same rules apply to doing online library maintenance and access against custom algorithms as for ordinary library members except that the function codes used begin with ALG... instead of LBR... and the key value must include the mask# (Screen Header number).

## ALGxxx Functions

If you wanted to see a listing of all the custom algorithms on the library for a given screenheader number or batch report number, you would enter either of the following:

`ALGLST sss
ALGLST rrrB`

where: sss = screen header number

rrr = batch report number

You may cursor select any item shown on the list and be immediately transferred to the ALGSEE function for that page of custom algorithm.

If you wanted to see a specific page of a specific custom algorithm for a specific screen or report and you knew the exact key, you might enter either of the following:

`ALGSEE sss/nnnnnnnn/mmmmmmmm/ppp
ALGSEE rrrB/nnnnnnnn/mmmmmmmm/ppp`

where: sss = screen header number

rrr = batch report number

nnnnnnnn = insertion point name

mmmmmmmm = the modifier

ppp = page number

The specified page will be shown and the function code will be automatically changed to ALGNXT to permit you to page forward or backward using the PF8 or PF7 keys respectively.

The ability to do scans, both member and global, is also provided and is done in exactly the same manner as discussed earlier for Librarian Members. The ability to assign passwords to the customization algorithms is also included. The password assigned applies to all the custom algorithms for that screen header or report.

If you wanted to duplicate all of the custom algorithms for one screen header or report to another, you would enter either of the following:

`ALGCPY sss/ttt
ALGCPY rrrB/qqqB` where: sss = original (source) screen number

ttt = new (target) screen number

rrr = original (source) report number

qqq = new (target) report number

You can delete a range of page numbers, as well as one page at a time, for a given insertion point's custom code using the ALGDEL function as:

`ALGDEL sss/nnnnnnnn/mmmmmmmm/ppp/eee`

where eee= ending page number

ppp= starting page number

If you wish to delete (purge) all of a report's or screen 's custom algorithms, you would enter:

`ALGPUR sss
ALGPUR rrrB`

where: sss = mask (screen header) number

rrr = report number

## Valid ALGxxx functions

All valid ALGxxx functions are listed below:

ALGADD -- add a page of custom algorithm code

ALGCHG -- change/update a page of custom algorithm code

ALGCPY -- copy all custom algorithms for one screen or report to
another screen or report

ALGDEL -- delete a page of custom algorithm code

ALGDUP -- duplicate a page of custom algorithm code

ALGLOC -- locate a specific page of custom algorithm code
beginning with the key entered

ALGLST -- list custom algorithm members for a mask or report number
ALGNXT -- display the next page of a custom algorithm member

ALGPUR -- purge/delete all custom algorithms for a screen or report

ALGSEE -- see/display a specific page of a custom algorithm

## DEFxxx Functions

The same rules and features apply to online maintenance and access to default algorithms as to ordinary library members except that the function codes used begin with DEF... instead of LBR... and the modifier is always "DEFAULT" and may be omitted from all DEF... commands.

To see the default algorithm for the insertion point named "EDIT" you would enter:

`DEFSEE EDIT`

The key prefix (DEF) and the modifier (DEFAULT) are not entered. If there is more than one page for the default algorithm then you may page forward and backward using the PF8 and PF7 keys. You may assign passwords and do scans just as for other types of members.

## Valid DEFxxx Functions

All valid DEFxxx functions are listed below:

DEFADD -- add a page of default algorithm code

DEFCHG -- change/update a page of default algorithm code

DEFDEL -- delete a page of default algorithm code

DEFDUP -- duplicate a page of a default algorithm member

DEFLOC -- locate a specific page of default algorithm code
beginning with the key entered

DEFNXT -- display the next page of a default algorithm member

DEFSEE -- see/display a specific page of a default algorithm

# Business Rules

Business Rules are routines which are usually coded by Database Administrators to ensure complete validity and verification of data before it is updated to the database. They are associated with an element, which must be defined in the dictionary (via ELTxxx functions) and are triggered (invoked) whenever a program is updating or adding data to that element. There are also rules which are triggered by deletes, they are called Deletion Rules. The only difference is where they are inserted into the generated program's logic. Whether the rules are for add/update or for deletion, they consist of Cobol coding which is inserted into the programs when they are generated.

You use the RULxxx functions to maintain Business Rules.

## Valid RULxxx Functions

All valid RULxxx functions are listed below:

RULADD -- add a page of a business rule

RULCHG -- change/update a page of a business rule

RULCPY -- copy all pages of a business rule

RULDEL -- delete a page of a business rule

RULDUP -- duplicate a page of a business rule

RULLOC -- locate a specific page of a business rule
beginning with the key entered

RULLST -- list names of business rules

RULNXT -- display the next page of a business rule

RULPUR -- purge all pages of RULWORK, RULDELT, and
RULPROC for a business rule

RULSEE -- see/display a specific page of a business rule

RULUSE -- see uses of a business rule

## Deletion Rules

Deletion Rules are similar to Business Rules and utilize the same set of Functions shown above. These two facilities enable the database administrator to protect the data integrity and referential integrity of the database.

# Named Proforma Members

A named proforma member is up to 15 lines of sample code which you can have MAGEC present on the screen to save keystrokes. Most proforma's can be used in a fill-in-the-blanks mode. Typical uses for proforma code might be for a data base management system's "data language" (such as SQL, DL/I, SUPRA, TOTAL, or IDMS) or for any other commonly used logic routines.

Some proforma members are provided with MAGEC. Proforma code for SQL,DL/I and SUPRA are available at installation time. Your shop can add other proforma code, such as check-digit or date routines, to suit your needs.

## How to use Named Proformas

You can insert named proforma code when adding a custom algorithm with the ALGADD function. For example, you can enter:

`ALGADD sss/nnnnnnnn`

where: sss =vr mask (screen header) number

nnnnnnnn = insertion point name

The returned screen contains the standard MAGEC proforma code for the nnnnnnnn insertion point, with a message at the lower-right of the screen to "Press PF4 for menu of NAMED PROFORMAs".

Pressing PF4 will take you to a 4-up menu of the named proforma members available. Place the cursor on the name of the proforma member you wish to copy in and press ENTER. You will be returned to the ALGADD screen with the key unchanged, but the text of the screen now contains the proforma member you selected. If the proforma member selected is not the one you want, press PF4 to return to the proforma menu to repeat the selection process.

In the example we used above with the ALGADD function, when you pressed PF4, the sequence of the named proforma menu was by modifier within insertion point name. For a more specific proforma retrieval, follow the example below:

`ALGADD sss/nnnnnnnn/SQL` where: sss = any valid mask (screen header) number

nnnnnnnn = insertion point

When the standard MAGEC proforma is displayed on the screen, press PF4. You will now notice a difference in the sequencing of the member names on the menu. All named proforma members with "SQL" in the first characters of the modifier appear at the front of the menu, in member name order. This technique will work when the modifier portion of the custom algorithm's key begins with DLI, SQL, SUPRA, or DATACOM.

Once you have selected the desired member from the proforma menu and returned to the ALGADD screen, you may over-key any portion, if needed, and press ENTER to add the code to the custom algorithm shown in SKEY. You can then make more changes, if desired, to the custom algorithm code. The original named proforma member remains unchanged.

## PROxxx Functions

The same rules and features apply to online maintenance and access to named proforma members as to ordinary library members, except that the function codes used begin with PRO... instead of LBR... and the only valid page number is 000 (blank defaults to 000). For example, to see the named proforma code used to insert a segment into a DL/I database, enter:

`PROSEE INSERT/DLI`

Since all named proforma members contain only one page, some restrictions apply to the PRONXT function code. PRONXT is used only when "$GBL" is entered in the PASSWORD field (with sufficient authority) during a global scan. For additional information refer to the global scan section of the online maintenance chapter.

## Valid PROxxx Functions

All valid PROxxx functions are listed below:

PROADD -- add a page of named proforma code

PROCHG -- change/update a page of named proforma code

PRODEL -- delete a page of named proforma code

PRODUP -- duplicate a named proforma member

PROLOC -- locate a specific page of named proforma code

beginning with the key entered

PRONXT -- used only for global scans

PROSEE -- see/display a specific page of named proforma code

# Using Other Text Editors

You can use your own shop's text editor (ICCF, ISPF, VOLLIE, CONDOR, etc.) rather than the one that comes with MAGEC, if you prefer. Code on the MAGEC Librarian can be transferred to your text editor for changes, and back to MAGEC using the MAGEC utilities provided. You can use the MAGECLBR utility program with the following control card to copy a member from the MAGEC Librarian to the DOS punch queue or to an OS data set or PDS:

`-MAGECPUN ttttnnnnnnnn/mmmmmmmm`

where: tttt = mask (screen header) number or member type

("LIB ", "DEF ", "PRO ", nnn, or nnnB)

nnnnnnnn = insertion point name

mmmmmmmm = the modifier

The "punched" member will have a -MAGECREP control card in front of it so that, after you have finished editing it, you can use MAGECLBR to return (replace) it to the MAGEC Library.

For additional details see the Offline Utilities section in this chapter and also the MAGECLBR section in the "Offline Utilities" chapter (Chapter 9).

# Appendix A -- Library Functions

## LBRxxx Functions

LBRADD -- add a page to an ordinary library member

LBRCHG -- change (update) an ordinary library member

LBRCPY -- copy and rename an ordinary library member

LBRDEL -- delete a page from an ordinary library member

LBRDUP -- duplicate from an ordinary library member

LBRLOC -- locate/list all ordinary library member pages
beginning with the key entered

LBRLST -- list all ordinary library member names
beginning with the key entered

LBRNXT -- display the next page of an ordinary library member

LBRPRT -- print a librarian member

LBRPUR -- purge (delete) an entire ordinary library member

LBRSEE -- see/display a page of an ordinary library member

## ALGxxx Functions

ALGADD -- add a page of custom algorithm code

ALGCHG -- change/update a page of custom algorithm code

ALGCPY -- copy all custom algorithms for one screen header
number to another

ALGDEL -- delete a page of custom algorithm code

ALGDUP -- duplicate a page of custom algorithm code

ALGLOC -- locate a specific page of custom algorithm code
beginning with the key entered

ALGLST -- list custom algorithm members by screen number
beginning with the screen number entered

ALGNXT -- display the next page of a custom algorithm member

ALGPUR -- purge/delete all custom algorithms for a screen

ALGSEE -- see/display a specific page of a custom algorithm

## RULxxx Functions

RULADD -- add a page of business rule code

RULCHG -- change/update a page of business rule code

RULCPY -- copy all pages of business rule code to
another element

RULDEL -- delete a page of business rule code

RULDUP -- duplicate a page of business rule code

RULLOC -- locate a specific page of business rule code
beginning with the key entered

RULLST -- list names of business rules

RULNXT -- display the next page of business rule code

RULPUR -- purge/delete all pages of code for RULWORK, RULDELT,
and RULPROC for a business rule

RULSEE -- see/display a specific page a business rule

RULUSE -- see uses of a business rule

## DEFxxx Functions

DEFADD -- add a page of default algorithm code

DEFCHG -- change/update a page of default algorithm code

DEFDEL -- delete a page of default algorithm code

DEFDUP -- duplicate a page of a default algorithm member

DEFLOC -- locate a specific page of default algorithm code
beginning with the key entered

DEFNXT -- display the next page of a default algorithm member

DEFSEE -- see/display a specific page of a default algorithm

## PROxxx Functions

PROADD -- add a page of named proforma code

PROCHG -- change/update a page of named proforma code

PRODEL -- delete a page of named proforma code

PRODUP -- duplicate a named proforma member

PROLOC -- locate a specific page of named proforma code
beginning with the key entered

PRONXT -- used only for global scans

PROSEE -- see/display a specific page of named proforma code

# Appendix B -- MAGECLBR Control Cards

The MAGECLBR control card specifies which operation is to be performed and provides the parameters necessary for the desired operation. The control card format is:

Col 1-10:

Operation (required).

`-MAGECADD` Add a member.

`-MAGECREP` Replace a member.

`-MAGECPCH` Punch and print a member.

`-MAGECPUN` Punch and print a member.

`-MAGECPRT` Print a member.

`-MAGECLST` Print a member.

`-MAGECDEL` Delete a member.

`-MAGECIDX` Print an index list.

`-MAGECUSE` Print "Where-used" report.

Col 11-14:

Key prefix (required).

`LIB` Ordinary library member.

`DEF` Default algorithm.

`nnn` 0xx 9xx for MMP custom algorithm.

`nnnB` 0xxB 9xxB for MBP custom algorithm.

`DOC` Documentation on DOC file.

`DIT` Data items in dictionary.

`PRO` Named proforma member.

`DEF` Default algorithm code

`RUL` Business rule code

Col 15-22:

Member name (ALG file only).

`xxxxxxxx` ALG member name.

Col 23-23:

Separator (ALG file only).

`/`

`,`

`b (blank)`

Col 24-31:

Name modifier (ALG file only).

`xxxxxxxx` Optional suffix for member name, 1-8 characters.

Col 15-44:

Topic name (DOC file only -- required).

`xxxxxxxx` Topic name of the documentation member on the DOC file.

Col 15-19:

Element name (DIT file only -- required).

`xxxxx` Name of element having data items defined on DIT file.

Col 24-25:

Mode (DIT file only).

`T` Default -- test mode.

`P` Production mode.

Col 45-45:

Suppress heading and page number reset.

For MAGECPRT and MAGECLST of multiple members when resetting to page 01 at the start of each member is not desired.

`C` Continue (do not reset).

`blank` Default -- reset to page 01.

Col 46-46:

Uppercase flag (for MAGECPRT and MAGECLST only).

`U` Mixed text (upper- and lowercase) wll be converted to all uppercase for output.

`L` Default -- Text remains in upper- and lowercase on output.

Col 47-48:

Page increment (only for MAGECADD and MAGECREP).

`nn` This controls the increment value MAGECLBR will use in generating "page" numbers as the member is being added to the file. Page number is the low-order portion of the key. The increment value will also be the page number of the first record added. If this value is 02 then the first page will be page 002, the next will be 004, etc.
Default is 01 for DOC file, else 02.

Col 47-48:

Sequence column (only for MAGECPUN and MAGECPCH on ALG members).

`nn` Starting card column into which MAGECLBR will insert sequence numbers. The sequence numbers are actually the page number and line number within the page on the ALG file.
Default is 73 for -MAGECPUN and -MAGECPCH.

`NO` Suppresses sequence numbers.

Col 49-50:

Lines per page (only for MAGECLST and MAGECPRT).

`nn` 01 thru 90 -- The maximum number of lines per page to print before forcing a "top of form". Default is 59.

`NO` Suppresses forced breaks.

Col 51-54:

Entity type (DOC file only).

`tttt` Entity type used to add "prime reference" to REF file. Required only for MAGECADD DOC operations, ignored otherwise.

NOTE:

- 1. Only the MAGECADD and MAGECDEL operations are allowed to the DIT file. The input for the MAGECADD is a Cobol data definition, the dictionary definitions will be generated and added to the DIT file.

- 2. When new documentation is added via the MAGECADD DOC operation, MAGECLBR also adds the "prime reference" entry to the REF file for the new topic. A prime reference is one in which the key word (or key phrase) is the same as the topic name and is generated to ensure that there is at least one reference to every topic since the usual path to documentation on the DOC file is via the references from the REF file. When a topic is deleted from the DOC file all references to it are deleted from the REF file.

- 3. Refer to the "Offline Utilities" chapter for JCL examples and more detailed information on the use of the MAGECLBR batch utility program.

# Appendix C -- Custom Models

## Model Programs

When you use MAGEC to generate applications (programs), MAGEC uses one of several model programs as the basis for the generated program. There are several model programs provided with MAGEC to enable you to generate the most common types of programs. You can create your own custom model programs to suit your exact needs if you possess a sufficient understanding of how a model program works.

Included with MAGEC are the model programs:

MODELMMP full-screen online multi-function program

MODELWIN pop-up window multi-function program

MODELRPT multi-file input, sorted report with control breaks

Additional models may also be included in your implementation of MAGEC. These model programs are stored as ordinary library members on the ALG-file. You can view any of these using the online command:

`LBRSEE MODELxxx`

It is strongly recommended that you not modify any of the standard model programs since they will be overlaid by the current version each time you apply a new release of MAGEC. If you feel the need for a customized model program, you should create a separate one having a different member name from the standard MAGEC models. That way it will not be overlaid when you upgrade your MAGEC system.

## Naming Standard

In order to be recognized as a model program for use in generating applications, your model must be catalogued on the MAGEC ALG-file with a name such as:

`MODELxxx/xxxxxxxx`

where: "MODEL" is a constant, and each x is any alpha-numeric character. Thus: MODELMMP/SPECIAL, MODELINQ, MODELINQ/READONLY, are all potentially valid model names.

In addition to being on the ALG-file, each model must also be defined to one of two MAGEC Lookup Tables.

Table #205 for online models

Table #207 for batch models

The maximum number of characters for a model, or for any other member on the ALG-file, is sixteen (16). That includes an 8-character member name plus an 8-character modifier. When defining your new model program to the appropriate Lookup Table, you will find that the model name is entered into the code value (key field) which is limited to sixteen (16) characters; therefore, you should omit the slash (/) from the name and concatenate the modifier immediately behind the 8-character member name (MODELxxx). For example: "MODELINQREADONLY".

If you do not define your model to the appropriate Lookup Table you will not be able to specify/select that model in the application development process since both the development process for batch and for online programs reference these tables to obtain a list of valid model names.

To define your new model to one of the Lookup Tables, enter:

TBLADD 20n/MODELxxxxxxxxxxx

where: n is either 5 or 7, and each x is an alphanumeric character.

You can enter a description into the table record to help identify your model as well.

## Using a Model Model

While it is theoretically possible for you to create your own model program from scratch, it will probably be very difficult to do. Those who have successfully created custom models have normally done so by copying one of the standard MAGEC models and making alterations as desired.

The standard models contain a number of substitution parameters which are resolved by the MMPCRE, or MBPCRE programs when an application is being generated. It will be helpful to know of these parameters when creating a new model. The list below shows the substitution parameters (all of them start with the ampersand (&) character), with a brief description and a sample of the value which might be substituted for each parameter.

Following appear only in online models:

"&COB" cobol level

____________sample___________________"COBOL85" or "COBOL74"

"&MOD" mode of display

____________sample___________________"TXT" or "GUI"

"&REL" MAGEC release number

____________sample___________________"3" for MAGEC release 3.0

"&SDT" size of mask detail area

____________sample___________________"3460" for MAGEC relase 3.0 and later

"&SEW" size of mask edit words

____________sample___________________"2400" for MAGEC 3.0 and later

"&SLP" size of applications authorization list

____________sample___________________"100" for MAGEC 3.0 and later

"&MMP" MMP# to be generated

____________sample___________________"xnn" any valid MMP#

"&PFX" function code prefix from SHD profile

____________sample___________________"xxx" any 3-character prefix

Following appear in both online and batch models:

"&PGM" programmer name

____________sample___________________"AL.LEE.&.ASSOC." 15-char pgmr from SHD profile

"&INS" installation name

____________sample___________________"MAGEC.GENERATED.MMP" preset at installation time

"&DAT" date and time program generated

____________sample___________________"MM/DD/YY-HH:MM:SS"

"&MSK" mask number

____________sample___________________"xnn"

"&MON" TP monitor or environment

____________sample___________________"MICRMD" or "CICSMD", etc.

"&LIB" librarian include command

____________sample___________________"-MAGECINC"

"&OP$" operating system type

____________sample___________________"DOS" or "OSS"

"&TYP" type of model program

____________sample___________________"ELMMP" for MODELMMP

"&DBM" database system for repository

____________sample___________________"VSAM"

"&MDL" name of model program

____________sample___________________"MODELMMP "

"&FIL" primary data class

____________sample___________________"xxx" any valid data class ID

Following appear only in batch models:

"&RDS" 30-char report title

____________sample___________________"xxx--xxx" from Batch Pgm header

"&DTL" number of detail lines

____________sample___________________"999" 001 thru 999

"&WTH" report width

____________sample___________________"(999)" 001 thru 256

"&HF1" heading filler 1 for centering title

____________sample___________________"(999) VALUE SPACES"

"&HF2" heading filler 2 for centering title

____________sample___________________"(999) VALUE SPACES"

"&SPC" report spacing

____________sample___________________"999" 001 thru 009

"&MXL" maximum lines per page

____________sample___________________"999" 001 thru 999

"&RPW" report width

____________sample___________________"999" 001 thru 256

"&RID" 8-character report ID

____________sample___________________"xxxxxxxx" from batch program header

"&LVL" number of break levels

____________sample___________________"999" 000 thru 009

"&OCR" number of accumulator levels (&LVL + 1)

____________sample___________________"999" 001 thru 010

"&MBP" INDENT =

____________sample___________________"9xx" MBP number (without B suffix)

"&KEY" primary data class' key name

____________sample___________________"xxxKn" any valid key ID

Additionally, the models include markers to denote where each insertion point for customization is. These markers are identified by a leading percent (%) sign. For example:

`%EDIT`

`%SNDSCRN`

`et cetera`

You can refer to your Programmer's Reference Manual, sections: Insertion Points and Logic Diagrams for detailed discussion of the defined insertion points.