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:
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:
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.
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:
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:
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:
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:
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:
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:
Col 1-10:
Operation (required).
Col 11-14:
Key prefix (required).
Col 15-22:
Member name (ALG file only).
Col 23-23:
Separator (ALG file only).
Col 24-31:
Name modifier (ALG file only).
Col 15-44:
Topic name (DOC file only -- required).
Col 15-19:
Element name (DIT file only -- required).
Col 24-25:
Mode (DIT file only).
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.
Col 46-46:
Uppercase flag (for
MAGECPRT and
MAGECLST only).
Col 47-48:
Page increment (only for
MAGECADD and
MAGECREP).
Col 47-48:
Sequence column (only for
MAGECPUN and
MAGECPCH on ALG members).
Col 49-50:
Lines per page (only for
MAGECLST and
MAGECPRT).
Col 51-54:
Entity type (DOC file only).
NOTE:
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.
Supplemental Reading
Overview
Purpose
Conditional MAGECINC's
-IFUNIQUE
-MAGECINC member/modifier
Mask Copybooks
Element Copybooks
The ALG File
(or insertion point name)
Offline Maintenance
The MAGECLBR Utility Program
Cataloguing to Library
-MAGECADD ppppnnnnnnn/mmmmmmmm
Replacing a Member
-MAGECREP ppppnnnnnnn/mmmmmmmm
Deleting a Member
-MAGECDEL ppppnnnnnnnn/mmmmmmmm
Printing a Member
-MAGECPRT ppppnnnnnnnn/mmmmmmmm
Punching a Member
-MAGECPCH ppppnnnnnnnn/mmmmmmmm
-MAGECPUN ppppnnnnnnnn/mmmmmmmm
Punching Customization Algorithms
-MAGECPUN ppppnnnnnnnn/mmmmmmmm
(individual)
-MAGECPUN pppp
(all customization for mask# nnn)
Re-sequencing a Member
Compressing a Member
-MAGECPUN ppppnnnnnnn/mmmmmmmm
Hardcopy Index of Library
-MAGECIDX LIB
Where-Used Report
-MAGECUSE LIB nnnnnnnn/mmmmmmmm
-MAGECUSE DIT xxxxxxxxxxxx
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
Online Index of Members
LBRLST 1
LBRLST nnnnnnnn
Online List of Records
LBRSEE Function
LBRSEE nnnnnnnn/mmmmmmmm/ppp
LBRSEE PROGRAM1
LBRSEE PROGRAM1/T
LBRSEE PROGRAM1/W
Updating a Member
LBRCHG nnnnnnnn/mmmmmmmm/ppp
Underscores
Field-Mark
on a mainframe 3270
Alt-196
on a PC
Tab Option
Lower-case and Non-display Characters
Adding New Member Online
LBRADD nnnnnnnn/mmmmmmmm/ppp
Deleting a Page
LBRDEL nnnnnnnn/mmmmmmmm/ppp
LBRDEL nnnnnnnn/mmmmmmmm/ppp/eee
Deleting (Purging) a Member
LBRPUR nnnnnnnn/mmmmmmmm
Copying and Renaming a Member
LBRCPY nnnnnnnn/mmmmmmmm
Copying Lines
Valid LBRxxx Functions
beginning with the key entered
beginning with the key entered
Password Protection
Member Scans
Search Zone
Global Scans
Generic Scans
PERF..M
PERFORM
PERFROM
PERF M
The MAGECINC Statement
-MAGECINC nnnnnnnn/mmmmmmmm
Conditional MAGECINC's
-IFUNIQUE
-MAGECINC membername
Printing a Member
-MAGECPRT LIB nnnnnnnn/mmmmmmmm
LBRPRT nnnnnnnn/mmmmmmmm
Custom Algorithms
ALGxxx Functions
ALGLST sss
ALGLST rrrB
ALGSEE sss/nnnnnnnn/mmmmmmmm/ppp
ALGSEE rrrB/nnnnnnnn/mmmmmmmm/ppp
ALGCPY sss/ttt
ALGCPY rrrB/qqqB
ALGDEL sss/nnnnnnnn/mmmmmmmm/ppp/eee
ALGPUR sss
ALGPUR rrrB
Valid ALGxxx functions
another screen or report
beginning with the key entered
ALGNXT -- display the next page of a custom algorithm member
DEFxxx Functions
DEFSEE EDIT
Valid DEFxxx Functions
beginning with the key entered
Business Rules
Valid RULxxx Functions
beginning with the key entered
RULPROC for a business rule
Deletion Rules
Named Proforma Members
How to use Named Proformas
ALGADD sss/nnnnnnnn
ALGADD sss/nnnnnnnn/SQL
PROxxx Functions
PROSEE INSERT/DLI
Valid PROxxx Functions
Using Other Text Editors
-MAGECPUN ttttnnnnnnnn/mmmmmmmm
Appendix A -- Library Functions
LBRxxx Functions
beginning with the key entered
beginning with the key entered
ALGxxx Functions
number to another
beginning with the key entered
beginning with the screen number entered
RULxxx Functions
another element
beginning with the key entered
and RULPROC for a business rule
DEFxxx Functions
beginning with the key entered
PROxxx Functions
beginning with the key entered
Appendix B -- MAGECLBR Control Cards
-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.
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
xxxxxxxx
ALG member name.
/
,
b (blank)
xxxxxxxx
Optional suffix for member name, 1-8 characters.
xxxxxxxx
Topic name of the documentation member on the DOC file.
xxxxx
Name of element having data items defined on DIT file.
T
Default -- test mode.
P
Production mode.
C
Continue (do not reset).
blank
Default -- reset to page 01.
U
Mixed text (upper- and lowercase) wll be converted to all uppercase for output.
L
Default -- Text remains in upper- and lowercase on output.
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.
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.
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.
tttt
Entity type used to add "prime reference" to REF file. Required only for
MAGECADD DOC operations, ignored otherwise.
Appendix C -- Custom Models
Model Programs
LBRSEE MODELxxx