HP 3000 Manuals HP 3000 Manuals
#description
Generates a comment block.
Syntax
#description comment="string" [start=startnum] &
# [end=endnum] &
# [continue=continuenum]
Keywords
string is the literal string value that should be placed in the
comment block. The string can be a keyword value, a
combination of text and keyword values, or just text,
but must be enclosed in quotes. The literal string may
have a maximum length of 1023 characters.
startnum is the starting column for the first line of generated
output.
endnum is the ending column for generated output. The output
line will not extend beyond this column.
continuenum specifies the beginning column for subsequent lines of
output. If an input line or comment string (after
parameter replacement) is too long to fit within the
constraints of startnum and endnum, the output will be
wrapped to additional lines. The value of continuenum
can be less than, greater than or equal to the value of
startnum.
Description
The #description construct generates a block of comments, depending upon
the textmode parameter specified using the #option construct or the INFO
string.
If textmode = COBOL, the string is formatted into one or more lines of
standard COBOL comments where each comment line begins with an asterisk
in column 7. The comment text begins in the column specified by the
start parameter (default is column 12). Subsequent lines begin in the
column specified by the continue parameter (default is column 12).
Blanks are preserved, and the output does not exceed the column specified
by the end parameter (default is column 72).
If textmode = TEXT or OVERLAY, the string is formatted into one or more
lines of text. The lines are formatted based upon the values of the
start, continue, and end parameters. The defaults are 1, 1, and 80
respectively. Blanks are preserved.
The #description construct preserves paragraph breaks and blank lines and
performs line fill. Thus, if you enter text in the System Dictionary
using SDMAIN, the text will not retain its format in the resulting
generated documentation. Text will be generated in a single paragraph.
The following pages present examples of generated text using the
#description construct.
Note that if the body of the comment contains double quotes, the comment
itself must be enclosed in single quotes, as in this example:
#description comment='This module uses the "ORDERS" database.'
This construct is typically used when generating COBOL source code to
document the module. It can also be used when generating paragraphs of
documentation if textmode is TEXT. See the #option construct in this
chapter or the :RUN string parameters in Chapter 5 for further
information on the textmode parameter.
Examples
EXAMPLE 1
Generator Input:
#getent module="!module" attr=(description)
IDENTIFICATION DIVISION.
PROGRAM-ID. !module.
#description comment="!description"
The above example shows the use of #description to assign a value to the
comment keyword. Since the default language is COBOL it generates a
COBOL comment block based on a description that was retrieved from the
System Dictionary. Knowledge of the description length is not necessary.
Whatever number of COBOL comment lines are needed will be generated. The
statements that are generated are shown below.
Generated Output:
IDENTIFICATION DIVISION.
PROGRAM-ID. SALEUPDT.
* Transaction to perform an update to the orders database.
* Two screens are displayed which allow a data entry
* operator to first enter the information about
* departmental information, then enter division level
* sales data.
Note that the default values were used for the start, continue, and end
parameters.
EXAMPLE 2
The following example illustrates the use of a literal string that is to
be generated into a COBOL comment. Notice the use of the replacement
parameters that are used to build the string.
Generator Input:
#description comment="!MODULE performs the following: !DESCRIPTION" &
# end=65
The generator processes the statement by first replacing all parameters
in the literal string. Then, the string is formatted as COBOL comments.
The generated output of the statement is shown below using the default
values for the start and continue parameters and a value of 65 for the
end parameter.
Generated Output:
* SALEUPDT performs the following: The transaction
* provides an interactive interface for updating the
* the CUSTOMER master dataset. The user enters an order
* number and the order is displayed. The user may then
* change the order information and press f1 to
* perform the update to the database.
EXAMPLE 3
The example that follows illustrates the formatting of the same comment
as the above example. However, the textmode is TEXT instead of COBOL.
Generator Input:
#option textmode = "TEXT"
#description comment="!MODULE performs the following: !DESCRIPTION &
# start=5 end=75 continue=1
Notice that continue specifies the starting position for the second
through the nth lines of the comment. The following is the resulting
generated text.
Generated Output:
SALEUPDT performs the following: The transaction provides an
interactive interface for updating the CUSTOMER master dataset. The use
enters an order number and the order is displayed. The user may then
change the order information and press f1 to perform the update
to the database.
Limitations. The maximum string length the generator can handle is 1023
characters. Variable length attributes have a limit of 7280 bytes in the
System Dictionary; however, the #description construct uses only the
first 1023 characters. A warning results if this limitation is exceeded.
The following example illustrates the text input in the System Dictionary
and the resulting generated text using the #description construct.
EXAMPLE
This module provides update capability to the customer mailing
address dataset.
The capability to add a new customer is provided by entering
the appropriate information into the fields on the data entry
screen and pressing function key <f1>.
The capability to change an existing customer is provided by
entering in the name of the customer to change and then
pressing function key <f2>. The current information for the
customer is then presented. The user changes any of the fields and then
presses function key <f1> to confirm the change. Function key
<f8> cancels the change transaction, if it pressed instead of
the confirm function key <f1>.
Generated Output:
This module provides update capability to the customer mailing
address dataset.
The capability to add a new customer is provided by entering
the appropriate information into the fields on the data entry
screen and pressing function key <f1>.
The capability to change an existing customer is provided by
entering in the name of the customer to change and then
pressing function key
<f2>. The current information for the
customer is then presented. The user changes any of the fields and then
presses function key <f1> to confirm the change. Function key
<f8>
As you can see in the above example, the text is truncated due to the
1023 character limit. Also note that the blank spaces between paragraphs
of the description in the System Dictionary are preserved in the
generated output.