This guide is written for those who will be creating and maintaining documentation using the MAGEC Documentation Facility. And those who will be planning the documentaion of applications, especially those developed using MAGEC.
Copies of this guide should be distributed to:
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 manual titled Application User's Guide if you have not already.
The MAGEC Documentation Facility is used to store, retrieve, and maintain documentation which is to be accessed both in hardcopy format and online via the built-in MAGEC HELP Key feature. Documentation can be loaded via an offline (batch) utility or it can be keyed into the online maintenance screens provided. A special two-file scheme is used to eliminate the need to key redundant explanations or instructions, allowing text for any "topic" to be referenced and included 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 probably be to document online applications developed using MAGEC. It is the belief of the authors of MAGEC that documentation is an integral part of any development project and that it must be done before any development effort can be considered complete. The intent of the documentation facility is to integrate the documentation effort into the normal application development processes.
Creating or maintaining documentation may be done at the same time and in the same "session" as application developemnt or maintenance is done. The new or updated documentation is made available instantly to the application's users online and may also be printed to hardcopy if desired.
This book will explain the philosophy of the documentation facility, the "mechanics" of it, and how to use it. It will show you:
The two files involved in the MAGEC Documentation Facility are:
The DOC file is the one which actually contains the documentation text that you key in or load to the system. The REF file is used as an index for the DOC file. Together they make up an extremely flexible and efficient documentation "library".
The DOC file consists of records having a 32-character key value and one screenful of text per record. Actually we usually perceive of the data on the file as "books" or "topics" of documentation, each made up of from 1 to 99 records. The records are made-up of:
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 99 "pages" of text for any given topic. When an application user is viewing the documentation online via the online 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:
A few special characters are not allowed in topic names. You may not use the special characters slash ( / ) or apostrophe ( ' ) or quote ( " ) in topic names. These characters have special, reserved meanings for all MAGEC applications when used in the screen key (SKEY) area. Aside from those few restrictions you may be as creative as you like with your names.
You may make up names which include lowercase alphabetics if you like. The quote ( " ) and apostrophe ( ' ) are used to indicate lowercase alphabetics in the SKEY area according to MAGEC standards. The MAGEC Application User's Guide 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 of the underscore ( _ ). If you would like your hardcopy documentation to show the underscore character or underlining then you must follow the procedure given in the "Offline Utilities" chapter, MAGECLBR section under Skip and Space - Overprinting/Underlining.
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:
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 special characters. For the purposes of the online HELP functions we will be concerned only with keywords which are six-character function codes; but some planned enhancements to MAGEC will likely use the REF file with other types of 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. This code defines what the keyword is. For instance, some of the entity types which are pre-defined with the MAGEC software are:
Therefore, it is possible that you might have an online function code of CUSCHG as well as a batch program named CUSCHG. The Entity type enables you to record references to them and to distinguish between them. The online HELP functions only look at REF file entries with an entity type of FUNC; however, planned enhancements will use other 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:
If you wish to load documentation which you have stored somewhere other than the MAGEC documentation files, you can use the MAGECLBR batch utility program. MAGECLBR is used for many operations besides the documentation files, the MAGEC Library, and the Data Dictionary. In this chapter we will only discuss those functions pertinent to documentation. Full explanation and instructions regarding the use of MAGECLBR are included in the chapter titled "Offline Utilities." Here we will simply try to "point" you to the right operation to do what you want to do. If you are not familiar with 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:
Always check the output listing for errors. If there are no errors then it will tell you how many pages were added and also that a "prime reference" was added. This is because there is a requirement that there always be at least one reference on the REF file for every topic on the DOC file. The prime reference will be a record on the REF file with the topic name you specified as both the keyword and as the topic name. The entity type will be what you specified on your control card, it must be valid as defined on the lookup table # 250. As an example: if you specified a topic name of "CUST FILE" and an entity type of "FILE", the prime reference that would be automatically generated on the REF file would be:
Remember, there is a limit of 99 pages for a topic. Very long pieces of documentation must be broken down into multiple topics. You can later concatenate them for printing. One technique is to assign topic names such as:
Using the sequence number at the end to create unique, but obvoiusly related, topic names. This naming technique is especially useful to handle extremely large topics which have been split into multiple smaller topics. There is no limit to the number of topics which you can concatenate for printing nor to the number of total pages. You could conceivably print an entire encyclopedia by concatenating many topics.
There is no batch facility for updating portions of a topic; you can, however, completely replace a topic in batch. When you replace a topic MAGECLBR will first delete all the pages for it and will then add the new 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:
Notice that entity type is not given.
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 CONDOR, possibly merging in some new text you have stored there. You could then take the results and replace the topic on the MAGEC files as described above.
To punch out a topic, use MAGECLBR with a control card of:
If you want to entirely delete a topic you must do it using the batch MAGECLBR utility. There is no online delete capability for the documentation (DOC) file. This is both to protect the integrity of the files and to avoid potentially inefficient processes online.
To delete an entire topic use MAGECLBR with a control card of:
MAGECLBR will first look up and delete all references, including the prime reference, on the REF file, then it will delete the topic. Remember, there is no limit to how many references there might be. Now you see why we do not want to to this particular operation online.
The thing you will probably do most often offline regarding the documentation is to print it. The MAGECLBR utility is also used to print hardcopy documentation from the DOC file. It does not look at the REF file, instead it allows you to 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:
It will print the topic and will produce, automatically, a page index and table of contents for you. You have the ability to control page numbering and headings and many other useful things by inserting the special control statements 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. We suggest that you take the time to study all the capabilities defined in the other chapter in order to fully utilize 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 or what size they are. This enables you to print manuals which are much larger than one topic could contain (in 99 records). There is no limit as to how many topics you may concatenate nor to how many records or pages they may consist of.
To print a manual made up of more than one topic from the DOC file use MAGECLBR with a control cards as:
The "C" in column 45 indicates to MAGECLBR that the following topic is to be concatenated or is a continuation of this one.
When you print your documentation using MAGECLBR you can also allow it to automatically generate headings, titles, and page numbers and to automatically create a table of contents and page index for you. To do that you would use the control cards:
You should refer to the "Offline Utilities" chapter for more detailed information about these control cards.
Online maintenance to documentation on the DOC file is accomplished using the DOC . . . functions provided and the documentation maintenance screen.
Supplemental Reading
Overview
Purpose
What This Book Will Tell You
File Structure
The DOC & REF Files
DOC File
Lowercase Characters
REF File
REF File Relates Entities to DOC
Offline Maintenance
How to Load in Batch
Key Phrase Type Topic
CUST FILE FILE CUST FILE
ORDER OF THE UNIVERSE (1)
ORDER OF THE UNIVERSE (2)
How to Update in Batch
-MAGECREP DOC tttttttttttttttttttttttttttttt
How to Unload in Batch
-MAGECPUN DOC tttttttttttttttttttttttttttttt
How to Delete in Batch
-MAGECDEL DOC tttttttttttttttttttttttttttttt
How to Print Documentation
-MAGECPRT DOC tttttttttttttttttttttttttttttt
-MAGECPRT DOC tttttttttttttttttttttttttttttt C
-MAGECPRT DOC ssssssssssssssssssssssssssssss C
|
|
-MAGECPRT DOC llllllllllllllllllllllllllllll
Headings, Index, and Page Numbers
Online Maintenance
DOCxxx Functions
DOCxxx tttttttttttttttttttt |
An online facility is built into MAGEC to enable you to find documentation at your screen. It includes a three-level "menu" to help you to choose among all the many topics stored in the documentation file (the DOC file) by navigating down through the natural heriarchy of the dictionary.
To begin, you enter the function code:
**HELP.
You will be presented a list of Entity Types defined to the MAGEC dictionary (in Table #250). You can choose one by positioning the cursor to the line it is displayed on and pressing ENTER. The list may be more than one page (screenful) long. If you wish to page forward, just press ENTER without cursor-selecting an Entity Type.
When you select an Entity Type you will be presented a list of Keywords (or Key Phrases). They will be the ones associated with the selected Entity Type. For example, if you chose an Entity Type of FUNC (online function codes), you would receive a list of keywords which were online function codes; if you selected an Entity Type of BPGM (batch programs), you would receive a list of keywords which were batch program names, and so forth. Your list could continue for multiple pages, to page forward just press PF8 or ENTER. When you see the Keyword or Phrase you are interested in, point to it with the cursor and press ENTER.
When you cursor-select a Keyword or Phrase, as described above, you will then be presented a list of Topics from the MAGEC documentation file. They will be those topics which are referenced by (associated with) the Keyword or Phrase you have selected. This list may also continue for multiple pages, you can just press PF8 or ENTER to page forward. When you see the Topic you are interested in you can cursor-select it and press ENTER, you will be displayed the first page (screenful) of text for that Topic.
As you browse through the selected Topic you can page forward by pressing ENTER or PF8, or page backward by pressing PF7 (F7, on a PC). When you are through reading it, you can press PF12 (Shift-F2, on a PC) to return to the Topics list.
At each level of the selection menus the PF12 (Shift-F2, on a PC) key will take you back up to the prior menu. If your security authorization permits you to modify documentation, you can do so while you are browsing through the Topic. To do that you would alter the function code (SFUNCT) to DOCCHG, key in your changes, and press ENTER.
Another way you can look for a Topic in the DOC file is by simply browsing through it using the DOCLOC function. The DOCLOC screen is merely a list of Topics, in alphanumeric order, which are on the file. They are not organized by Keyword references. This method is handy when you know the Topic (and how it is spelled, approximately) that you want to view. You do not need to enter the complete Topic Name as a key value in SKEY (though you could), you could enter only the first few characters of it or just enter a "1" to start browsing at the beginning of the file. As with all lists in MAGEC, you can cursor-select the item you are looking for by positioning the cursor to it, when it is shown in the list on the screen, then you can press ENTER and be immediately presented the DOCSEE display of the first page (screenful) of text for the Topic you chose.
You can use the DOCNXT function to search for a sequence of characters in your text also. To do a search, you do exactly the same as you would to display and browse (DOCSEE, DOCNXT) but you also enter the character string you would like to find into the SEARCH ARGument area.
Your search argument may be up to 66 characters in length. DOCNXT will sequentially search each page of text either browsing forward or backwards (depending on PF8 or PF7 key) looking for the character sequence you have given. When it finds a "hit" it stops searching and displays the page to you with the line(s) on which it found the hit highlighted (bright display or colored red, depending on your terminal).
If you would like to continue searching for the same search argument then you may just press ENTER or PF8 or PF7 again, leaving everything else alone on the screen. It is OK to change directions as often as you like by using the PF8 and PF7 keys, therefore you can search forward to find all the hits and then "back up" to the one you are interested in.
You may also change the search argument at any time by simply overkeying it on the screen; thus you might want to "position" forward to the major section of your text in which you are interested and then search for a certain phrase starting at that point, or from that point backwards.
At any time while you are browsing or searching through your text you may decide that you have found the place where you wish to make some changes. To do so you simply alter the function code from DOCNXT to DOCCHG and press ENTER, You will then see the screen returned to you in maintenance mode for the page you were looking at.
Finding Documentation
Finding Documentation
Scans of Text
DOCxxx tttttttttttttttttttt |
The DOCCHG function may be used to insert new lines of text into existing pages even if they are "full" (all 15 lines used). To insert new lines you position the cursor to the line you want to insert after and press PF20. You may then key in your new lines and press ENTER. If an "overflow" condition occurs (more than 15 lines) then DOCCHG will automatically add a new page behind the one you are updating and/or shift all following text down one page to accommodate the added lines.
To delete lines of text you may position the cursor onto the line to be deleted and press PF19, then press ENTER. The selected line will be gone and the following lines will be shifted up to fill in the space.
It is not absolutely necessary to actually delete lines, however. You can accomplish the same thing in most cases by just "blanking" it out (using ERASE EOF key, if desired). If you just blank out a line, then the following lines will not be shifted up. When you print your documentation all blank lines are dropped anyway so it may not matter. The exception is for those topics which are to be displayed online using the HELP key facility. You may not want all those blank lines to appear to the application user for aesthetic reasons.
If you insert lines using the PF20 key it is likely that you will be causing DOCCHG to add pages (records) to the end of the topic in order to contain the overflow (shifed-down lines). Thus, you are actually adding pages by adding lines in many cases. Sometimes you might wish to explicitly add a new page to a topic, usually at the end. You can do that using the command:
Again, you enter the page number into the body of the screen after it is displayed to you and not into the SKEY area.
You can key in a screenful of text and press ENTER. Unless some error is detected you should receive a screen back displaying the new page using the DOCSEE function. The DOCADD function does not support the PF19 and PF20 keys as the DOCCHG function does, it is a "data entry" type of function.
You can use the DOCADD function to add an entirely new topic just as you added a page to an existing topic. You do so in exactly the same manner with one difference -- when you are adding the first page of a new topic, then DOCADD must also add the prime reference to the REF file.
If DOCADD detects that this is the first page (there are no others on file) for the topic then you will see another special item appear on the screen. It is titled: TYPE. In it you must enter the entity type to be used in generating the prime reference. It must be a valid type defined on lookup table # 250.
The REF file is used to define the relationships between any keyword (or key phrase) to any topic (or topics). This technique permits you to reference any number of topics by a keyword and permits you to reference any topic from any number of keywords. Please note that there is no difference between a "keyword" and a "key phrase", they are simply two interchangeable terms. Since MAGEC allows you to make up keywords consisting of up to 30 characters with embedded blanks if you like, it is often likely that the term "key phrase" will be more descriptive than "keyword". From here on in this book we will standardize on the term "keyword". You know that that could also mean an up-to 30-character phrase.
One of the main uses for these stored relationships is for the online HELP facility. When an application user presses the HELP (PF1 or Ctrl-F1) key requesting online documentation, MAGEC determines which topics are to be displayed by looking at the function code on the screen and then looking up that function code as a keyword on the REF file. It does that by building a key value using the function code as the keyword and "FUNC" as the entity type. For instance, if the operator was doing the function code "CUSADD" and pressed HELP, then MAGEC would look on the REF file looking for:
This could be described as looking for the references for the online function code "CUSADD" since FUNC is defined as meaning online function code. There might be none, or one, or even many found.
Let us assume that there were three references on file:
MAGEC would first display to the operator the first page of the first topic, ASSIGNING NEW CUSTOMER NUMBERS. If there was more than one page of text for that topic it would next display (when he/she hits the ENTER key) the second page and so on until it reached the last page for that topic. Then it would display the first page for the next topic, etc., until it reached the last page for the last topic. Of course, the operator could exit the HELP facility at any time by pressing PF3 (F3, on a PC) to return immediately to the application screen. If your online text is too wordy then they will probably use the exit option frequently.
Now, suppose that you also had a batch program named CUSADD and you also had documentation on file for it. You might have some references on the REF file as:
Since the entity type is not FUNC, the online HELP facility will ignore and bypass these references. Notice also that it is perfectly legal to reference the same topic from any other entity types or other keywords. This allows you to document a given topic once and to reference it from many places, simplifying maintenance of your documentation and reducing work for you.
We suggest that you first gain an understanding of the use of the REF file and that you plan your documentation so as to take full advantage of it to minimize your work. When you are documenting an online application which includes functions to add, change, delete, inquire, and browse through a file or database then you will probably find that many of the topics you need to cover will apply to more than one of the functions. It would be wasteful to repeat the same explanations and instructions for, let us say, both the ADD and the CHG functions when you could store it as a single topic and reference it from both functions using the REF file. Then when you find you need to make a change to the topic, your change will automatically be effective for both the ADD and the CHG functions.
An example of how this might look is:
With just a little forethought and planning you can see that your work can be made much easier and the results will be first rate.
There is no batch (offline) facility for adding references to the REF file except that MAGECLBR will automatically add the prime reference when a new topic is added. In most cases you will probably want to add references in addition to the prime reference, you can do that online using the REFxxx function codes provided. To add a reference enter:
The screen will be returned to you with underscores in the TYPE field and in the TOPIC NAME field for you to enter into them. The TYPE must be valid as defined on MAGEC lookup table # 250 and the topic name must exist on the DOC file. The keyword may be anything you like. For use by the online HELP facility the keyword will be six-character function codes.
There is no capability for changing a reference once it is on file since the entire REF record is actually the key to the REF file. If you wish to change a reference you should add the new, corrected reference using REFADD and then delete the old, incorrect one.
When application developers initially generate their new online applications (MMP's) using the MMPCREAT job stream, MAGEC will automatically add default references to the REF file for each of the nine standard functions generated. For instance, if the developer is generating a customer maintenance application with the standard set of nine functions (CUSADD, CUSCHG, etc.) then it would add references as:
There are nine topics on the DOC file which were installed when MAGEC was initially installed. These nine topics explain how to use each of the standard functions. Since MAGEC automatically adds these references when the application is initially generated, an application user who is trying to use a new application will receive at least some help even if the developer has not provided any of his/her own documentation yet.
We do not suggest that the default documentation can take the place of your own explanations and instructions regarding your own applications. We hope that you will use the documentation facility to give your users the most complete and useful documentation that you can. You may feel that the default topics are useful and will thus want to leave these references on file in addition to the ones you add, or you may want to delete the default references and use just your own instructions for your applications.
You may have MAGEC produce hardcopy technical documentation of your applications' specifications at any time using the special offline utility named MSKDOC. To print technical documentation execute MSKDOC with a control card indicating the MSK number for which you wish documentation. Refer to the "Offline Utilities" chapter for details of the execution procedure and control card format.
Training new application users and familiarizing them with the system and environment is a time-consuming chore. You can save much effort and time by taking advantage of the MAGEC Application User's Guide manual which is provided for you with the MAGEC system. It describes all the standard features of MAGEC-generated applications and is written with the non-technical application user in mind. You can give your users that section of this manual in addition to the specific application documentation you yourself produce. Your own manuals need not re-explain those things which are "global" in nature and apply to all MAGEC applications.
Another type of documentation and online HELP key is also provided by MAGEC. It is called Field-Level HELP. Field-Level HELP text is not stored on the DOC file, like other types of documentation. It is stored in the actual dictionary definitions for Data Items (DIT's). When the database administrator defines the database he also has the opportunity to provide free-form textual descriptions and explanation for each database field (DIT). When an online application user wishes to see HELP text for a given screen field, he/she merely points to that field using the cursor and presses the Field-Level HELP key (PF2). MAGEC builds a screenful of text consisting of two parts. The top half of the screen is text generated by MAGEC explaining the technical specifications for the selected screen field. The bottom half of the screen is text provided by the database administrator to describe the database source/target field for the screen field selected.
If you execute the MSKDOC utility program which produces automatic technical documentation, as described earlier, the field-level HELP text will be printed along with other specifications for the application. Refer to the MAGEC "Offline Utilities" chapter for instructions on how to execute MSKDOC.
The free-form text which makes up the lower half of the Field-Level HELP display can be added or updated by a database administrator. The DIT . . . functions are used. Refer to the "Database Administration") chapter for more information.
If the operator points the cursor to a screen field which is a "table edited field" (see: Edit Types, refer to edit type T, table lookups) then the Field-Level HELP provides one additionial facility. When the help screen is displayed, there will be a message telling the operator that he/she can press PF8 to page forward. If PF8 is pressed the screen will then begin to list the table entries and their descriptions appropriate for the selected screen field. The operator may point to one of the displayed entries and press ENTER to select it -- the selected value will automatically be filled into the original screen field. This feature is called a "Pick List".
Function-level online HELP is available to the terminal operator for any MAGEC-generated functions. The operator simply presses the PF1 key (High-level HELP key) to request it. The help text is stored on the DOC file. It may be of unlimited length. The Entity Type of "FUNC" associates Topics with function codes (see Avoid Redundancy and Default References earlier in this chapter). When the operator requests Function-level HELP, the MAGEC HELP facility presents one screenful of text at a time to the operator. He/she can use PF8 to page forward, PF7 to page backward, or PF3 to quit and return to his/her original screen at any time.
Adding Lines
Deleting Lines
Adding Pages
DOCADD tttttttttttttttttttttttttttttt
Adding a New Topic
Defining References
Relating Keywords to Topics
Avoid Redundancy
Adding References
REFADD kkkkkkkkkkkkkkkkkkkkkkkkkkkkkk
Changing a Reference
REFxxx kkkkkkkkkkkkkkkkk
M A G E C
D O C U M E N T A T I O N R E F E R E N C E
KEY PHRASE TYPE TOPIC NAME
kkkkkkkkkkkkkkkkk ____ ________________________________
Press PF4 for browse (LOC) screen Press PF13 for Hardcopy
Press PF16 to Copy field to buffer Press PF17 to Paste data from buffer
Press PF2 for field-level HELP
Default References
Automatic Technical Documentation
Application User's Guide
Field-Level HELP
Function-Level HELP