7.13 Questions and Answers
Q: How is LANSA Documentor turned on or off?
Documentor is turned off or on at the LANSA partition level.
It is recommended that you only enable Documentor in development partitions and do not enable it in other partitions.
Q: Will using Documentor use up more disk space?
Yes. Once documentor is enabled every compile will build up and store more information (e.g.: screen panel layouts). The storage of this information of course requires more disk space. However you should find that the storage of, for example, screen panel layouts does not require a lot more disk space than the storage of the screen panel layouts in some other facility (e.g.: OFFICE/400 folders).
Q: Can I estimate how much more disk space will be used?
This is very difficult because it is so application dependent. For instance 100 online functions have many screen panels, and thus use up more space than 100 batch functions.
As an example, consider the PSLSYS demonstration process shipped with LANSA. It consists of 8 functions which are heavily biased to online transactions and have many screen panels. The storage of the compiled objects (i.e. RPG programs) resulting from this system requires around 800K of disk space (in non-GUI mode). The storage of Documentor details for this system requires about 300K of disk space. So in this type of environment you could generalize that we need around 100K for each program object and around 40K to store complete documentation, so using documentor increases the storage required for program objects by about 40%.
Note that this increase is for program objects only. So if you allow 20Mb to store all the programs in your application, you should allow 28Mb if full documentation details are also required. This of course is a simple generalization and may not be applicable to all sites, particularly those that have a higher mix of batch functions, thus significantly reducing the figure down from 40%.
The use of documentor has no impact on the size required to store data objects, which is where, in most applications, the majority of disk space is utilized.
Q: Will using Documentor increase compile times?
Yes, but only by very slight amounts. Even this affect can be removed by submitting non-final compiles with a request that Documentor details should not be updated.
Note that when a compile is submitted like this all existing documentor details for the function are deleted, but not replaced with the new details. This prevents you from producing documents with details that are out of date.
Q: How should I approach using Documentor for the first time?
This is a recommended way of approaching Documentor for the first time:
Choose (or create) a very small application consisting of less than five database files and three RDML functions. Enable Documentor and then (re)compile the entire application to ensure that all details are stored.
- Create User and Technical help text for the processes and functions involved. Note: help text enhancements such as reverse image/underline/blinking etc will not be carried into documentor due to the difficulty in consistently representing these features when the document may be a spool file, a PC document or an RFTDCA document.
- Create 2 documents. One that is to document a "test case" for end users and the other for technical people. Initially include all subjects in the Table of Contents for both documents.
Produce one of the documents and examine it. Do not worry if a very large amount of documentation is produced. This is the approach of Documentor - very large amounts of information may be produced - but you can be selective about what you actually want to produce.
- Put aside time to experiment with adding and removing subjects, page sizes, page layouts, output formats, etc, etc, as well as the effect of how details input into LANSA such as RDML functions, User Help Text, Developer Help Text, etc have on the final output document.
- When all experiments are complete, define a site standard for what should be included in various types of documents (e.g.: and ) and for the layout and format of the guides.
This site standard may go as far as copying the completed document into a word processing or document handling system on a PC for final "polishing" into a format that makes the best use of the level of publishing facilities that your site has available.
The site standard may even include "post production" manipulation with specific site developed software to (re)format into a site specific format, replace special site "triggers" in the document, etc, etc.
Q: How and when are screen and report layouts captured?
Process Menu or Action Bar Layouts are captured and stored at the time that a process is compiled.
RDML Function panel layouts are captured and stored at the time that a function is compiled.
Report layouts, by their variable nature, cannot be created and stored automatically to produce a "sensible" image. You will find that every time that you exit from the report painter you will be given an option to save the image as a Documentor "sample" of the report layout. So to store a report layout for use by Documentor you should use the report painter to paint a sensible "sample" of the report, and then when exiting, request that the "sample" be saved as a report image for use with Documentor.
Q: What are some guidelines for getting the best from Documentor?
These guidelines are recommended for getting the best results from Documentor:
- It is a good idea to try to include all the objects to be documented prior to reviewing the Table of Contents (which always must be done at least once). The included objects will then appear with their subjects in the standard pre-set order of subjects the first time that the Table of Contents is reviewed. Once the Table of Contents has been reviewed, any further objects being included into the document will be added to the start of the Table of Contents.
- Use modular design techniques to create small RDML functions of less than 200 lines. Whenever possible use "smart" solutions such as virtual fields or system variables in preference to RDML function defined logic.
- Define all fields in the data dictionary whenever possible. Where this rule cannot be followed, function level field definitions should always carry a DESC parameter. For example:
DEFINE FIELD(#LPRODUCT) REFFLD(#PRODUCT)
DESC('Last Product Number Processed')
Q: What are "MSL diagrams"?
MSL Diagrams are "Major Structure and Logic" Diagrams that are meant to represent the major/significant flow of an RDML function in a style that does not require specific RDML skills or knowledge.
For instance RDML skills usually require some knowledge of the English language (e.g.: the words SELECT, DISPLAY or CHANGE), but an MSL diagram can represent RDML logic in other languages.
MSL diagrams work best in highly modular systems that make use of "smart" facilities like virtual fields and system variables, rather than in systems that heavily rely on RDML function level definitions of complex logic.
Q: What should MSL Diagrams be used for?
MSL diagrams are intended to demonstrate the "intent" of a function to someone working at the analyst or designer level, rather than the "detail" of a function to an application builder.
For example, a system analyst/designer may use an MSL diagram to work out how a whole new category of products should be introduced into an existing order entry system. This is the correct level of detail at which MSL diagrams should be used because the designer is trying to understand (for extension) the "intent" of the function at a business or end user level, rather than the detail of the function at the RDML level.
Q: What should I do if I want Documentor changed or enhanced?
More than any other thing, the production of documentation varies enormously from organization to organization. The variation is most likely to be found in the way that the "final form" of the document is produced, and the printing hardware that is being used to produce it.
Should you feel that a change to what Documentor does could be beneficial to your organization please forward your comments and suggestions to your product vendor.
Q: What is the difference between User and Developer Help Text?
The delivery of Documentor coincides with an extension to the existing help text facilities. Formerly only help text for display to "end users" could be defined for fields, processes or functions. However, the help text facilities also now support help text for technical people (i.e. developers).
This new help text facility is designed to allow help or descriptive text for technical people to be associated with fields, processes or functions. This help text is only displayed to users who enter LANSA with the DEVELOPER(*YES) option.
However, its intended use goes beyond displaying it to technical people. It is intended to form the basis upon which technical "free format" documentation for fields, processes and functions is produced by Documentor.
Note: Help text enhancements, such as reverse image/underline/ blinking etc., will not be carried into documentor due to the difficulty in consistently representing these features when the document may be a spool file, a PC document or an RFTDCA document.
Q: How are User and Developer Help text input?
Both types of help text are input by using the existing help text facilities. They are simply separated from one another by the special $$TECH keyword. This allows the User and Technical help text details to be reviewed and changed together.
Note: Help text enhancements, such as reverse image/underline/ blinking etc., will not be carried into documentor due to the difficulty in consistently representing these features when the document may be a spool file, a PC document or an RFTDCA document.
Q: When I export information, are the Documentor details also exported?
Only if you request that they should be.
Q: Are Documentor Details imported even if the target system does not have documentor turned on?
Yes, if the exporting system requested that they should be exported.
Q: Can I export LANSA Document definitions?
No, the current version of Documentor does not allow the definition of a document to be exported.