---
title: "docu_main"
original_file: "docu_main"
generated: "2026-06-12 10:24:19"
---
**
#
Introduction### Documentation Reference Manual
##
Who Should Read This Guide
This guide is written for those who will be creating and maintaining documentation using the MAGEC Documentation (cont.)
Facility. And those who will be planning the documentaion of applications, especially those developed using (cont.)
MAGEC.
Copies of this guide should be distributed to:
Documentalists
Application Developers
Auditors
##
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 manual titled *Application User's Guide* if you have not (cont.)
already.
#
Overview
##
Purpose
The MAGEC Documentation Facility is used to store, retrieve, and maintain documentation which is to be accessed both in (cont.)
hardcopy format and online via the built-in MAGEC HELP Key feature. Documentation can be loaded via an offline (batch) (cont.)
utility or it can be keyed into the online maintenance screens provided. A special two-file scheme is used to eliminate (cont.)
the need to key redundant explanations or instructions, allowing text for any "topic" to be referenced and included (cont.)
into an unlimited number of hardcopy manuals or online HELP displays.
The MAGEC Documentation Facility may be used to document virtually anything; however, the primary use of it will (cont.)
probably be to document online applications developed using MAGEC. It is the belief of the authors of MAGEC that (cont.)
documentation is an integral part of any development project and that it must be done before any development effort can (cont.)
be considered complete. The intent of the documentation facility is to integrate the documentation effort into the (cont.)
normal application development processes.
Creating or maintaining documentation may be done at the same time and in the same "session" as application developemnt (cont.)
or maintenance is done. The new or updated documentation is made available instantly to the application's users online (cont.)
and may also be printed to hardcopy if desired.
##
What This Book Will Tell You
This book will explain the philosophy of the documentation facility, the "mechanics" of it, and how to use it. It will show you:
the structure of the files
how to load documentation offline (in batch)
how to unload, replace, or delete it offline
how to print it offline
how to enter or modify it online
how to reference it from your online applications
how to find documentation via the built-in menu system
how to reduce effort and simplify maintenance by avoiding redundancy
#
File Structure
##
The DOC & REF Files
The two files involved in the MAGEC Documentation Facility are:
the DOC file (Documentation file)
the REF file (Reference file)
The DOC file is the one which actually contains the documentation text that you key in or load to the system. The REF (cont.)
file is used as an index for the DOC file. Together they make up an extremely flexible and efficient documentation (cont.)
"library".
##
DOC File
The DOC file consists of records having a 32-character key value and one screenful of text per record. Actually we (cont.)
usually perceive of the data on the file as "books" or "topics" of documentation, each made up of from 1 to 99 records. (cont.)
The records are made-up of:
Topic name 30 characters maximum
Page number 2 digits, 01 thru 99
Text 15 lines, 72 characters per line
The actual file key on the DOC file consists of the Topic name plus the Page number. As you can see, you may have up to (cont.)
99 "pages" of text for any given topic. When an application user is viewing the documentation online via the online (cont.)
HELP key, each screenful of display is actually one record from the DOC file.
The topic name may be any name up to 30 characters in length with embedded blanks (spaces) allowed. Examples of acceptable topic names are:
CUSTOMER NUMBERS
Adding a Customer
INQUIRIES & BROWSES
A few special characters are not allowed in topic names. You may not use the special characters slash ( / ) or (cont.)
apostrophe ( ' ) or quote ( " ) in topic names. These characters have special, reserved meanings for all MAGEC (cont.)
applications when used in the screen key (SKEY) area. Aside from those few restrictions you may be as creative as you (cont.)
like with your names.
##
Lowercase Characters
You may make up names which include lowercase alphabetics if you like. The quote ( " ) and apostrophe ( ' ) are used to (cont.)
indicate lowercase alphabetics in the SKEY area according to MAGEC standards. The MAGEC *Application User's Guide* (cont.)
explains the use of quote and apostrophe for entering lowercase key values.
The text is completely free-form and may contain any character that can be displayed at a terminal with the exception (cont.)
of the underscore ( _ ). If you would like your hardcopy documentation to show the underscore character or underlining (cont.)
then you must follow the procedure given in the "Offline Utilities" chapter, MAGECLBR section under *Skip and Space - (cont.)
Overprinting/Underlining.*
##
REF File
The REF file is used to record references to topics on the DOC file. The online HELP displays of documentation use the REF file to control which topics are to be presented for which functions.
The REF file records consist of:
Keyword (or phrase) 30 characters maximum
Entity type 4 characters
Topic name 30 characters maximum
Any keyword may be referenced to any number of topics. Any topic may be referenced by any number of keywords.
The keyword (or phrase) may be made up of any 30 characters with restrictions similar to those for topic name regarding (cont.)
special characters. For the purposes of the online HELP functions we will be concerned only with keywords which are (cont.)
six-character function codes; but some planned enhancements to MAGEC will likely use the REF file with other types of (cont.)
keywords or phrases.
The entity type is a four-character code which must be defined on the MAGEC lookup table # 250 in order to be accepted. (cont.)
This code defines what the keyword is. For instance, some of the entity types which are pre-defined with the MAGEC (cont.)
software are:
FUNC Online function code
BPGM Batch program
FILE File
Therefore, it is possible that you might have an online function code of CUSCHG as well as a batch program named (cont.)
CUSCHG. The Entity type enables you to record references to them and to distinguish between them. The online HELP (cont.)
functions only look at REF file entries with an entity type of FUNC; however, planned enhancements will use other (cont.)
entity types.
You can define your own new entity types for your own purposes by simply defining them on the lookup table # 250 using the standard functions:
TBLADD 250/xxxxx
TBLCHG 250/xxxxx
#
REF File Relates Entities to DOC
*
Figure 01 -- REF File Relates Entities to DOC
#
Offline Maintenance
##
How to Load in Batch
If you wish to load documentation which you have stored somewhere other than the MAGEC documentation files, you can use (cont.)
the MAGECLBR batch utility program. MAGECLBR is used for many operations besides the documentation files, the MAGEC (cont.)
Library, and the Data Dictionary. In this chapter we will only discuss those functions pertinent to documentation. Full (cont.)
explanation and instructions regarding the use of MAGECLBR are included in the chapter titled "Offline Utilities." Here (cont.)
we will simply try to "point" you to the right operation to do what you want to do. If you are not familiar with (cont.)
MAGECLBR then you should refer to the that chapter.
To initially load a "topic" of documentation via MAGECLBR you would use a control card of:
-MAGECADD DOC tttttttttttttttttttttttttttttt eeee
where:
ttttt...ttt
= 30-character topic name, begins in column 15
eeee
= entity type, begins in column 51
Always check the output listing for errors. If there are no errors then it will tell you how many pages were added and (cont.)
also that a "prime reference" was added. This is because there is a requirement that there always be at least one (cont.)
reference on the REF file for every topic on the DOC file. The prime reference will be a record on the REF file with (cont.)
the topic name you specified as both the keyword and as the topic name. The entity type will be what you specified on (cont.)
your control card, it must be valid as defined on the lookup table # 250. As an example: if you specified a topic name (cont.)
of "CUST FILE" and an entity type of "FILE", the prime reference that would be automatically generated on the REF file (cont.)
would be:
Key Phrase Type Topic **
**CUST FILE FILE CUST FILE
Remember, there is a limit of 99 pages for a topic. Very long pieces of documentation must be broken down into multiple (cont.)
topics. You can later concatenate them for printing. One technique is to assign topic names such as:
ORDER OF THE UNIVERSE (1)
ORDER OF THE UNIVERSE (2)
Using the sequence number at the end to create unique, but obvoiusly related, topic names. This naming technique is (cont.)
especially useful to handle extremely large topics which have been split into multiple smaller topics. There is no (cont.)
limit to the number of topics which you can concatenate for printing nor to the number of total pages. You could (cont.)
conceivably print an entire encyclopedia by concatenating many topics.
##
How to Update in Batch
There is no batch facility for updating portions of a topic; you can, however, completely replace a topic in batch. (cont.)
When you replace a topic MAGECLBR will first delete all the pages for it and will then add the new (cont.)
documentation.
You should not see any mention on the output listing of the prime reference since it should already have been on file.
To replace a topic use MAGECLBR with a control card of:
-MAGECREP DOC tttttttttttttttttttttttttttttt
where:
tttt...ttt
= topic name, begins in column 15
Notice that entity type is not given.
##
How to Unload in Batch
If you wanted to "punch" out (export) a topic of documentation you could also use MAGECLBR to do that. It will "punch" out 80-column "cards" to the punch queue (DOS) or to any data set or PDS (OS).
One reason you might want to punch a topic would be to update it using another text editor, such as ISPF, ICCF or (cont.)
CONDOR, possibly merging in some new text you have stored there. You could then take the results and replace the topic (cont.)
on the MAGEC files as described above.
To punch out a topic, use MAGECLBR with a control card of:
-MAGECPUN DOC tttttttttttttttttttttttttttttt
##
How to Delete in Batch
If you want to entirely delete a topic you must do it using the batch MAGECLBR utility. There is no online delete (cont.)
capability for the documentation (DOC) file. This is both to protect the integrity of the files and to avoid (cont.)
potentially inefficient processes online.
To delete an entire topic use MAGECLBR with a control card of:
-MAGECDEL DOC tttttttttttttttttttttttttttttt
MAGECLBR will first look up and delete all references, including the prime reference, on the REF file, then it will (cont.)
delete the topic. Remember, there is no limit to how many references there might be. Now you see why we do not want to (cont.)
to this particular operation online.
##
How to Print Documentation
The thing you will probably do most often offline regarding the documentation is to print it. The MAGECLBR utility is (cont.)
also used to print hardcopy documentation from the DOC file. It does not look at the REF file, instead it allows you to (cont.)
control which topic(s) are to be printed using control cards.
To print a topic from the DOC file use MAGECLBR with a control card of:
-MAGECPRT DOC tttttttttttttttttttttttttttttt
It will print the topic and will produce, automatically, a page index and table of contents for you. You have the (cont.)
ability to control page numbering and headings and many other useful things by inserting the special control statements (cont.)
into your documentation as described fully in the "Offline Utilities" chapter under MAGECLBR.
The printing feature of MAGECLBR is intended to permit you to produce very "finished" looking hardcopy documentation. (cont.)
We suggest that you take the time to study all the capabilities defined in the other chapter in order to fully utilize (cont.)
the feature.
You can concatenate topics to cause them to be printed as if they were all one topic on the file, regardless how many (cont.)
or what size they are. This enables you to print manuals which are much larger than one topic could contain (in 99 (cont.)
next: docu02.md.txt