---
title: "libr_main"
original_file: "libr_main"
generated: "2026-06-12 10:24:22"
---
**
#
Introduction### Librarian Reference Manual
##
Who Should Read This Guide
This guide is written primarily for use by those persons who will be using the MAGEC Librarian software to maintain programs, customization algorithms, and other types of library members.
Copies of this guide should be distributed to:
Application developers
Security officers
Database administrators
System programmers
Auditors
This book is not intended to replace the online documentation but to augment it. Though there is some overlap, this (cont.)
book takes a grander, more general perspective while the online documentation is usually aimed at the particular (cont.)
function the operator is dealing with at a given time.
##
Supplemental Reading
This guide is written assuming that the reader is familiar with the overall MAGEC philosophy. It presumes that you (cont.)
understand how the "standard set of nine" functions work and that you are familiar with the standard screen formats of (cont.)
MAGEC. We suggest that you first read the MAGEC *Application User's Guide*, if you have not already.
#
Overview
##
Purpose
The MAGEC Librarian is used to store and maintain "books" of source code or other data. The books, usually called (cont.)
"library members" or just "members", may be programs, copybooks, customization algorithms or default algorithms as well (cont.)
as any other data desired by the users. The MAGEC Library actually consists of a single dictionary file named the ALG (cont.)
file. There are five types of members on the ALG file. When you are using the librarian functions, either online or (cont.)
offline, you could easily get the impression that there are five separate files. However, the different member types (cont.)
are all stored on the one file with the high-order portions of their key values denoting the type.
The five types of members are:
Ordinary library members
Customization algorithms
Default algorithms
Named proformas
Business Rules
Any of these may be displayed, updated, added, deleted, printed, or "punched" from the file using the online functions (cont.)
and utilities provided in MAGEC. The MAGEC Librarian is primarily designed for online maintenance, the offline utility (cont.)
functions are provided primarily to accommodate the migration of pre-existing members to and from other source (cont.)
librarian systems. The name of the batch utility program is MAGECLBR. You may refer to the "Offline Utilities" chapter (cont.)
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 (cont.)
other programs as "copybooks". Customization algorithms are used in the generation of MMP's (online programs) and MBP's (cont.)
(batch programs). They are created by application developers in the development process and are inserted into (cont.)
predetermined "insertion points" in the standard generated program logic. Default algorithms are also used in the (cont.)
program generation process, they are inserted into the predetermined insertion points if the developer *has not* (cont.)
created any customization algorithm for that insertion point. Named proformas are used to help minimize keystrokes when (cont.)
entering coding online. Business Rules are coded by the database administrators and are inserted automatically into any (cont.)
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 (cont.)
online programs) and MBPCRE (for batch programs) which are used in the job streams MMPCREAT, MBPCREAT, and others. The (cont.)
"control statement" which is used to indicate that a copybook is to be included is:
-MAGECINC mmmmmmmm
where:
mmmmmmmm =
member name
It may be embedded anywhere in the program being compiled or assembled and any number of times. MAGECINC statements may (cont.)
also be "nested"; a copybook being included may contain MAGECINC statements. The number of "nesting levels" allowed is (cont.)
determined at the time MAGEC is installed at your site, it is usually set to ten (10).
##
Conditional MAGECINC statements
In most cases it would cause difficulties to include the same copybook twice into the same program. Though there are (cont.)
exceptions, you would usually cause duplicate datanames and paragraph names and resulting compiler (cont.)
errors.
When one person is doing the coding for one program this is normally not a problem. S/he can easily control whether a (cont.)
copybook is -MAGECINC'd more than once. When several persons are involved in the coding for one program, however, it (cont.)
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 (cont.)
Rules are coded by the DBA's. They are perfectly free to use -MAGECINC statements within their coding; in fact, it is (cont.)
very likely that they will do some I/O in some Business Rule logic and would therefore wish to include the appropriate (cont.)
element copybooks to read into. They have no way of knowing whether or not the programs into which these Rules will be (cont.)
inserted will also do I/O to the same elements and thus also include those same copybooks. Since multiple Rules can be (cont.)
inserted into one program, there is even the possibility for such a conflict between the Rules (cont.)
themselves.
MAGEC provides a facility to solve this problem: conditional MAGECINC statements. You can use conditional MAGECINC (cont.)
statements anywhere that you can use MAGECINC statements; they are especially valuable in coding Business Rules and (cont.)
other routines which will be used in multiple programs. The facility enables you to specify that a member is to be (cont.)
included only if it has not been included elsewhere in this same program. In other words, only if it is unique within (cont.)
the program.
You code conditional MAGECINC statements as follows:
-IFUNIQUE
-MAGECINC member/modifier
The -IFUNIQUE statement applies only to the -MAGECINC immediately following it. It must, therefore, immediately precede (cont.)
the -MAGECINC. It sets a "flag" associated with the specified member name to keep it unique (within this program); (cont.)
therefore, it works equally well even when another MAGECINC statement for this member appears physically after this one (cont.)
in the program. It works regardless of the nesting level of each MAGECINC.
##
Mask Copybooks
The copybooks defining MAGEC masks (online screen formats) must be on the MAGEC Library in order for the generated (cont.)
MMP's (online programs) to properly include them. The utility job stream, MSKCREAT, or PF10 from MSKDEF, automatically (cont.)
places the mask copybook onto the library with the proper standard member name (
MSKnnn-C
, where
nnn
= mask number).
##
Element Copybooks
The copybooks defining data elements on the database must also be on the MAGEC Library in order for the MMP's and MBP's (cont.)
(batch programs) to include them. They are automatically placed onto the library when you use the dictionary to (cont.)
generate them from the DIT file definitions ( using the online DITGEN function). You may alternately use the batch (cont.)
utility (MAGECLBR) to catalogue your pre-existing copybooks to the MAGEC Library or you may also simply key them in (cont.)
using the online library maintenance functions (LBRADD, LBRCHG, etc.). You may also use the MAGECLBR batch utility to (cont.)
create the dictionary definitions (on the DIT file) from your pre-existing copybooks and then use the DITGEN function (cont.)
online to generate a new copybook. This last technique is the preferred one. In any case the data element definition (cont.)
copybooks must be named using the MAGEC standard member name (i.e.
eeeee-C
, where
eeeee
= element name). For more about this topic refer to the MAGEC "Database Administration" chapter.
##
The ALG File
The MAGEC Library (ALG file) consists of records which each hold up to 15 "cards" of code. Since the librarian is (cont.)
online-oriented we usually call them "lines" rather than cards. The online maintenance screens also contain 15 lines of (cont.)
data, thus each record on the file is actually a "page" of display. This arrangement may be somewhat different from (cont.)
what you may have been accustomed to with other librarian systems where each "card" is actually a record. The (cont.)
page-oriented structure is intended to reduce online overhead, giving quicker response on inquiries, scans, and updates (cont.)
in high-activity or limited-resource environments.
The record key for the ALG file consists of:
Key prefix 4-characters
Member name 8-characters
(or insertion point name)
Modifier 8-characters
Page number 3-digits (000 - 999)
Any member may therefore consist of up to 1000 pages of code, 15 lines per page. As mentioned earlier, the key prefix is used to denote the type of member. The valid prefixes for library members are:
Prefix
Member type
Description
LIB...
Ordinary library member
May be a complete program or a copybook, etc., member name plus modifier make up the complete identity for the member.
DEF...
Default algorithm
The key for this type of member consists of the insertion point for which it applies, plus the modifier, which is always "DEFAULT".
0xx...-9xx..
Custom algorithm
0xx - 9xx is the mask number (SHD number) for which it applies, the insertion point name must be specified, and the modifier may be any value.
0xxB..-9xxB..
Custom algorithm
Used for batch programs (MBP). 0xxB - 9xxB is the MBP number for which it applies, specify the insertion point name, and the modifier may be any value.
RUL...
Business Rule
Defined by Database Administrator - associated with an element - inserted into MMP's and invoked when the element is updated
PRO...
Named proforma
Frequently used code which you can have MAGEC place onto your screen to reduce coding effort. Member name plus modifier make up the complete identifier for the member.
#
Offline Maintenance
##
The MAGECLBR Utility Program
The MAGECLBR batch utility program provides numerous facilities for cataloguing, updating, printing, and punching (cont.)
members. It is not only used for members on the MAGEC Library (ALG file), it also may be used to access the (cont.)
documentation (DOC) and data item (DIT) dictionary files. In this book we are concerned only with those facilities (cont.)
which apply to the library.
You may refer to the "Offline Utilities" chapter for complete instructions as to the use of all the MAGECLBR (cont.)
facilities. Here we will simply try to direct you to the proper facility to do the tasks most commonly needed in (cont.)
day-to-day operations.
##
Cataloguing to Library
Perhaps the most basic function of the MAGECLBR utility is to catalogue new members to the library. You may often find (cont.)
the need to add a "copybook" to the library or to add an entire program. It may well be that you are moving these (cont.)
members from some other source library to the MAGEC Library. To add a new member use the MAGECLBR control (cont.)
card:
-MAGECADD ppppnnnnnnn/mmmmmmmm
where:
pppp =
key prefix
nnnnnnnn =
member (or insertion point) name
mmmmmmmm =
the modifier (optional)
You may add any type of member: ordinary library member, custom algorithm, default algorithm, business rule, or named (cont.)
proforma. It should be noted that the default algorithms are loaded to the library with the initial MAGEC installation (cont.)
and it is highly unlikely that you will ever have to alter them.
next: libr02.md.txt