Introduction

---

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:

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.

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.

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:

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:

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.

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:

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.

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

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

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:

              Description

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

              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 is the mask number (SHD number) for which it applies, the insertion point name must be specified, and the modifier may be any value.

              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.

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

              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.

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.

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:

              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.

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:

              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.

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:

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

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:

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

              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.

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.

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:

              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.

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:

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

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:

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:

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.

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

/*
/&
* $$ 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------

/*
//

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.

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:

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

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.

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.

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:

              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:

If you entered:

If you entered:

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.

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:

              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.

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:

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.

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.

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.

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

              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.

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

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

              NOTE:

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

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:

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

              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.

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.

Below is a list of all valid LBRxxx functions:

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

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.

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.

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.

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:

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

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

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.

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:

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

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:

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

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

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:

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:

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:

              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:

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

All valid ALGxxx functions are listed below:

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:

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.

All valid DEFxxx functions are listed below:

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.

All valid RULxxx functions are listed below:

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.

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

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

              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 profroma retrieval, follow the example below:

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.

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:

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.

All valid PROxxx functions are listed below:

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:

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

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

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:

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.

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:

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:

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.

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:

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.

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:

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.

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:

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