Appendix R
Dossier Utility
The INFO Dossier is a collection of stand-alone documentation aids producing listings of the application source and where-used cross references.
INFO Dossier is written in INFO The minimum access rights required for a user of INFO Dossier are delete, read and write. If you have any doubts on these, then please ask your system administrator.
=============================
== INFO Dossier MENU ==
=============================
1 - Build Documentation File
2 - Print Documentation
3 - Build Cross Reference Files
4 - Print Files - where used Cross Reference Listing
5 - Print Programs - used Cross Reference Listing
6 - Print Reports - used Cross Reference Listing
7 - Print IPF's - where used Cross Reference Listing
8 - Print SPF's - where used Cross Reference Listing
9 - Print Called Programs Cross Reference Listing
10 - Print Variables used Cross Reference Listing
11 - Print File Item sizes Cross Reference Listing
12 - Print Unreferenced Directory entries
13 - Print 4-12 above Cross Reference Listing
14 - Delete Documentation and Cross Reference files
Enter function (99 TO EXIT INFO)
INFO Reference Manual Appendices A-137
Dossier Utility
Menu
Selection
Options
User Name
WARNING
Pathname
Print files
Appendix R
The utilities described in this section are selectable from the above menu. The system will not inquire into your terminal type for if you are running on more than one terminal type within your installation, we have provided you with a terminal configuration system that is independent of the application. Please check with your system administrator if you have any doubts.
General Notes on using INFO Dossier
enter the desired option number followed by carriage return - invalid selection will result in the re-prompting for a valid option.
when in any option, it is possible to return to the Menu by entering a carriage return instead of pathname or user name this is the three character user name as is used by INFO to set up the operating system prefix to all the entries associated with the user. If you normally enter a user name with more than three characters, then INFO will use the 1st, 2nd and 4th characters to identify you - so user name JOHN will generate an INFO directory called
JON.DR9 and the associated directory entries will be held in the form of:
JONOOO.DAT, JONOOO.NIT, JON001.SRC, JON001.OBJ
etc.
if another user has the same User Name as you or indeed if you have generated documentation before and not deleted it then the Build options (1 and 3) will overwrite the existing documentation files.
this is the operating system pathname where the user directory is held. It must be held in the normal operating system format.
e.g. DUB5:[JOHN.DEVELOPMENT] is a valid pathname all the printed output will be sent to the system printer via the spooler with neither a FORM nor PAPER type specified, but with a print option of F implying imbedded
ANSI defined printer control characters. It is NOT possible to run any of the Print options without running the appropriate Build option first.
A-138 Appendices INFO Reference Manual
Appendix R
Generated
Files
Dossier Utility
the files generated and used by each option are:
=============================
== INFO Dossier MENU ==
=============================
1 - Build Documentation File
generates XXX.DOC
2 - Print Documentation
prints XXX.DOC
3 - Build Cross Reference Files
generates
XXX.FLE files- where-used
XXX.PRG program used
XXX.RPT reports used
XXX.IPF IPF's used
XXX.SF SPF's used
XXX.CP called programs
XXX.VAR variables
XXX.FMT variable formats
XXX.ITM file item sizes
XXX.NON unreferenced entries
4 - Print Files - where used Cross Reference Listing
uses XXX.FLE to Print
XXX.XRF
5 - Print Programs - where used Cross Reference Listing
uses XXX.PRG to print
XXX.XRF
6 - Print Reports - where used Cross Reference Listing
uses XXX.RTT to Print
XXX.XRF
7 - Print IPF's - where used Cross Reference Listing
uses XXX.IPF to print
XXX.XRF
INFO Reference Manual Appendices A-139
Dossier Utility
Appendix R
8 - Print SPF's - where used
9 - Print Called programs
10 - Print Variables used
11 - Print File Items sizes
Cross Reference Listing
uses XXX.SF to Print
XXX.XRF
Cross Reference Listing
uses XXX.CP to print
XXX.XRF
Cross Reference Listing
uses XXX.VAR and XXX.FMT to Print XXX.XRF
Cross Reference Listing
uses XXX.ITM to Print
XXX.XRF
12 - Print Unreferenced Directory entries
uses XXX.NON to Print
XXX.XRF
13 - Print 4-12 above Cross Reference Listings
uses XXX.FIL XXX.PRG
XXX.RPT XXX.IPF XXX.SF
XXX.CP XXX.VAR XXX.FMT
XXX.NON to Print XXX.XRF
14 - Delete Documentation and Cross Reference files deletes XXX.CP XXX.ITM
XXX.DOC XXX.FLE XXX.FMT
XXX.IPF XXX.NON XXX.PRG
XXX.REP XXX.SF XXX.VAR
XXX_XRF.LIS
Enter function( 99 to EXIT INFO )>
A-140 Appendices INFO Reference Manual
Appendix R
Dossier Utility
1 Build Documentation File
The selection of this function by the operator causes the generation of a complete documentation file of an application system including directory listings, file layouts, input screen formats, program source code, and report and special form formats. They are saved in a file (for later output by Function 2) in the order listed above and are sorted alphabetically by name in each of the categories listed.
Enter function( 99 to EXIT INFO )>1
*** Now Building System Documentation ***
Enter Pathname in which system is located
>DUB5:[JOHN.DEVELOPMENT]
Enter 3 Character INFO User Name >JON
Error
Condition
if pathname incorrect or user not found or permissions denied then the following three lines will be displayed :
LU 4 DUB5:[JOHN .DEVELOPMENT]JON.DR9 %RMS-E-FNF, file not found (DBPGET)
Unsuccessful attempt to retrieve your file
Please re-enter your Pathname otherwise the system will continue by displaying:
** please use user name JON to Print your system documentation **
** Please wait for the documentation to be generated **
The operator is requested to Provide the pathname of the directory where the application system to be documented is located. The pathname should be entered in the standard operating system format.
INFO Reference Manual Appendices A-141
Dossier Utility
Appendix R
Subsequent to its entry, the system will prompt the operator for the user name with which to enter INFO in the named user file directory. Only the three letter short user name may be entered. The system will then proceed to create a documentation file for the system requested which may be printed out by later selection of Function 2 on the menu. This generation function may require several minutes to complete depending on the size of the system being documented. During the documentation phase read only access is required on the user directory and its associated entries. It is however unwise to document a system while it is in use particularly if programs are being amended as it is possible for changes to be lost if this option is run on a particular entry during the re-filing of a change. On completion, the menu is redisplayed on the screen. The documentation file created with this option is in print image form and held as "XXX.DOC" and is stored in the INFO.Dossier directory where XXX (3 characters) is the user name that was entered earlier.
A-142 Appendices INFO Reference Manual
Appendix R
Dossier Utility
2 Print Documentation
Enter function (99 to EXIT INFO )> 2
Enter User Name for Documentation > JON
Job JON (queue SYS$PRINT), entry 19) started on SYS$PRINT
This function may be selected after Function 1 has been performed for a particular application system or after the user has copied his own documentation file into
INFO.UTILITIES and named it XXX.DOC (XXX is any 3 character INFO user name).
Upon the selection of this function, the operator is asked for the particular user name for which documentation is to be printed. After one is entered, this function simply
SPOOLs the file to the system printer.
INFO Reference Manual Appendices A-143
Dossier Utility
Appendix R
3 Build Cross Reference Files
Enter function (99 to EXIT INFO )>3
*** Now Building System Cross Reference Documentation ***
Enter pathname in which system is located>DUB5:[JOHN.DEVELOPMENT]
Enter 3 Character INFO User Name >JON
Error
Condition
if pathname incorrect or user not found or permissions denied then the following three lines will be displayed:
LU 4 DUB5:[JOHN.DEVELOPMENT]JON.DR9 %RMSE-FNF, file not found (DBPGET)
Unsuccessful attempt to retrieve your file
Please re-enter your Pathname otherwise the system will continue by displaying:
** now cross referencing programs **
The operator is requested to provide the pathname of the directory where the application system to be documented is located. The pathname should be entered in the standard operating system format.
Subsequent to its entry, the system will prompt the operator for the user name with which to enter INFO in the named user file directory. Only the three letter short user name may be entered. The system will then proceed to create the cross reference files for the system requested which may be printed out by later selection of Functions 4 to 13 on the menu. This generation function may require several minutes to complete depending on the size of the system being cross referenced. During the cross reference phase read only access is required on the user directory and its associated entries. It is however unwise to cross reference a system while it is in use Particularly if programs are being amended as it is possible for changes
A-144 Appendices INFO Reference Manual
Appendix R
Dossier Utility
to be lost if this option is run on a particular entry during the re-filing of a change. The program displays courtesy messages when running such as
** Cross Referencing STOCK.UPDATE.PG ** so the user can see how far the cross referencing has progressed. On completion, the menu is redisplayed on the screen. The cross reference files created with this option are NOT in Print image form. The names of the files have been described in the overview above.
INFO Reference Manual Appendices A-145
Dossier Utility
Appendix R
4 Print Files - where used
(Cross Reference Listing)
Enter function (99 to EXIT INFO )> 4
Enter User Name for Documentation > JON
Job JON (queue SYS$PRINT), entry 19) started on SYS$PRINT
The selection of this function causes the generation of a file cross-reference listing. The report is ordered by file name and lists each program and the line numbers on which each file is called along with the file's relation numbers (0 if selected), relation items, and relation options.
Upon selection of this function, the operator is asked to enter the directory pathname and the user name of the system for which the cross-reference listing is to be printed as in option 1 above.
After the user name has been entered, the system accesses the file cross-reference file for that user and generates the cross-reference report. The file crossreference file generated by Function 3 is saved as a direct-access file with a prefix of the user's name so that multiple users can operate from this directory easily without impacting one another.
A-146 Appendices INFO Reference Manual
Appendix R
Dossier Utility
5 Print Programs - used
(Cross Reference Listing)
Enter function (99 to EXIT INFO )> 5
Enter User Name for Documentation > JON
Job JON (queue SYS$PRINT), entry 19) started on SYS$PRINT
Selecting this option generates a program cross-reference listing. The report is ordered by program and lists all files, reports, input forms, special forms, and other programs called by each program and the line numbers on which they are called. For files, their relation numbers, items, and options are additionally listed and for reports, input forms, and special forms the options selected are also
Printed out.
On selecting this function, the operator is asked to enter the user name of the system for which the cross-reference listing is to be printed. After the user name has been entered, the system accesses the program cross-reference file for that user and generates the cross-reference report.
The program cross-reference file generated by Function 3 is saved as a direct-access file with a prefix of the user's name so that multiple users can operate from this directory easily without impacting one another.
INFO Reference Manual Appendices A-147
Dossier Utility
Appendix R
6 Print Reports - used
(Cross Reference Listing)
Enter function (99 to EXIT INFO )> 6
Enter User Name for Documentation > JON
Job JON (queue SYS$PRINT), entry 19) started on SYS$PRINT
Selecting this function generates a report cross-reference listing. The report is ordered by report name and lists each program and the line numbers on which each report is called, the Print option selected, and the files selected and related when the report is generated.
Note: Only those files selected and related in the same program in which the report is generated are listed.
Upon selection of this function, the operator is asked to enter the user name of the system for which the crossreference listing is to be printed. After the user name has been entered, the system accesses the report crossreference file for that user and generates the crossreference report.
The report cross-reference file generated by Function 3 is saved as a direct access file with a Prefix of the user's name so that multiple users can operate from this directory easily without impacting one another.
A-148 Appendices INFO Reference Manual
Appendix R
Dossier Utility
7 Print Input Forms - where used
(Cross Reference Listing)
Enter function (99 to EXIT INFO )> 7
Enter User Name for Documentation > JON
Job JON (queue SYS$PRINT), entry 19) started on SYS$PRINT
This option generates an input form cross-reference listing. The report is ordered by input form name and lists each program and the line numbers on which each input form is called, the options selected, and the files selected and related when the input form is generated.
Note: Only those files selected and related in the same program in which the input form is generated are listed.
Upon selection of this function, the operator is asked to enter the user name of the system for which the crossreference listing is to be printed. After the user name has been entered, the system accesses the input form crossreference file for that user and generates the crossreference report.
The input form cross-reference file generated by Function
3 is saved as a direct-access file with a prefix of the user's name so that multiple users can operate from this directory easily without impacting one another.
INFO Reference Manual Appendices A-149
Dossier Utility
Appendix R
8 Print Special Forms - where used
(Cross Reference Listing)
Enter function (99 to EXIT INFO )> 8
Enter User Name for Documentation > JON
Job JON (queue SYS$PRINT), entry 19) started on SYS$PRINT
This option generates a special form cross-reference listing. The report is ordered by special form name and lists each program and the line numbers on which each special form is called, the options selected, and the files selected and related when the special form is generated.
Note: Only those files selected and related in the same program in which the special form is generated are listed.
Upon selection of this function, the operator is asked to enter the user name of the system for which the crossreference listing is to be printed. After the user name has been entered, the system accesses the special form crossreference file for that user and generates the crossreference report.
The special form cross-reference file generated by
Function 3 is saved as a direct-access file with a prefix of the user's name so that multiple users can operate from this directory easily without impacting one another.
A-150 Appendices INFO Reference Manual
Appendix R
Dossier Utility
9 Print Called Programs
(Cross Reference Listing)
Enter function (99 to EXIT INFO )> 9
Enter User Name for Documentation > JON
Job JON (queue SYS$PRINT), entry 19) started on SYS$PRINT
This option generates a called program cross-reference listing. The report is ordered by program name that is called and lists the Programs and the line numbers from which each program is called.
Upon selection of this function, the operator is asked to enter the user name of the system for which the crossreference listing is to be printed. After the user name has been entered, the system accesses the called program cross-reference file for that user and generates the crossreference report.
The called program cross-reference file generated by
Function 3 is saved as a direct-access file with a Prefix of the user's name so that multiple users can operate from this directory easily without impacting one another.
INFO Reference Manual Appendices A-151
Dossier Utility
Appendix R
10 Print Variables Used
(Cross Reference Listing)
Enter function (99 to EXIT INFO )> 10
Enter User Name for Documentation > JON
Job JON (queue SYS$PRINT), entry 19) started on SYS$PRINT
The selection of this function causes the generation of an internal variable cross-reference listing and the formats of the internal variables where explicitly formatted by the programs. The cross reference report is ordered by program name and by internal variable number (1-40) within each program and lists the line number, internal variable, and full text of each program line on which every internal variable is used. The variable formats file is ordered by variable number (i.e. 1 through 40), variable prefix ($CHR, $DAT, $NUM) and program.
Upon selection of this function, the operator is asked to enter the user name of the system for which the crossreference listings are to be printed. After the user name has been entered, the system accesses the internal variable cross-reference file for that user and generates the cross-reference report and the unreferenced directory entries file for its associated report.
Both internal variable cross-reference files generated by
Function 3 are saved as direct-access files with a prefix of the user's name so that multiple users can operate from this directory easily without impacting one another.
A-152 Appendices INFO Reference Manual
Appendix R
Dossier Utility
11 Print File Item Sizes
(Cross Reference Listing)
Enter function (99 to EXIT INFO )> 11
Enter User Name for Documentation > JON
Job JON (queue SYS$PRINT), entry 19) started on SYS$PRINT
The selection of this function causes the generation of an items cross-reference listing. The report is ordered by item name and by file in which it is located and lists its defined width, output width, type, and number of decimals in each file.
Upon selection of this function, the operator is asked to enter the user name of the system for which the crossreference listing is to be printed. After the user name has been entered, the system accesses the items crossreference file for that user and generates the crossreference report.
The items cross-reference file generated by Function 3 is saved as a direct-access file with a prefix of the user's name so that multiple users can operate from this directory easily without impacting one another.
INFO Reference Manual Appendices A-153
Dossier Utility
Appendix R
12 Print Uncalled Directory Entries
Enter function (99 to EXIT INFO )> 12
Enter User Name for Documentation > JON
Job JON (queue SYS$PRINT), entry 19) started on SYS$PRINT
The selection of this function causes the generation of a cross-reference listing of the unreferenced entries in the user directory. The report is ordered by entry name but at the current release it may be inaccurate and include entries that are only referenced by the execute command from file based menu-programs.
Upon selection of this function, the operator is asked to enter the user name of the system for which the unreferenced directory listing is to-be printed. After the user name has been entered, the system accesses the unreferenced directory file for that user and generates the unreferenced directory report.
The unreferenced directory file generated by Function 3 is saved as a direct-access file with a prefix of the user's name so that multiple users can operate from this directory easily without impacting one another.
A-154 Appendices INFO Reference Manual
Appendix R
Dossier Utility
13 Print 4-12 Above
(Cross Reference Listing)
Enter function (99 to EXIT INFO )> 13
Enter User Name for Documentation > JON
Job JON (queue SYS$PRINT), entry 19) started on SYS$PRINT
The selection of this function causes the generation of all of the cross-reference listings described in Functions 4 through 12. This function may be used to save the time required to request each listing separately when all are desired. All listings are also SPOOLed at once as one large SPOOL file after all have been formatted.
INFO Reference Manual Appendices A-155
Dossier Utility
Appendix R
14 Delete Documentation and Cross
Reference Files
Enter function (99 to EXIT INFO )> 14
Enter User Name for Documentation > JON
DUB5:[DOSSIER]JON.CP;1
DUB5:[DOSSIER]JON.DOC;1
DUB5:[DOSSIER]JON.FLE;1
DUB5:[DOSSIER]JON.FMT;1
DU85:[DOSSIER]JON.IPF;1
DU85:[DOSSIER]JON.ITM;1
DUB5:[DOSSIER]JON.NON;1
DUB5:[DOSSIER]JON.PRG;1
DUB5:[DOSSIER]JON.REP;1
DUB5:[DOSSIER]JON.SF;1
DUB5:[DOSSIER]JON.VAR;1
DUB5:[DOSSIER]JON_XRF.LIS;1
Total of 12 files
Do you want to delete these files? (Y/N) Y
Files DELETED .. returning to MENU
Error
Condition
if a file is open, user not found or access rights denied then the following line will be displayed:
%DIRECT-W-NOFILES, no files found
The selection of this function causes the display of the cross reference flies generated by Functions 1,3,4 through
12. This function may be used to delete any documentation files generated for a specific user. If the user name is not found then no files will be displayed. Any response other than "Y" to the question, "Do you want to delete these files (Y/N)"
will leave the files intact. The program returns to the menu on completion.
A-156 Appendices INFO Reference Manual
