Comments are used to store lengthy descriptions of entities. For each entity type (except LOAD MODULE), IDD permits an unlimited number of user-supplied comment entries. The user can associate any number of lines of text with each entry; no restrictions apply.
Comment Text Is Identified by Comment Keys
Comment text is identified by predefined or user-defined comment keys, which can be associated with any entity occurrence to separately document design, operational, or usage considerations for the named entity. For example, the user might associate the user-defined comment key RECOVERY PROCEDURE with a program; text associated with that comment key contains instructions directed to the operator for use if the program terminates abnormally.
Predefined Comment Keys
The DDDL compiler supports the predefined comment keys shown in the following table.
|
Comment key |
Identifies |
|---|---|
|
COMMENTS |
General comments |
|
DEFINITION |
A full description of the use or purpose of the entity occurrence |
|
CULPRIT HEADER |
An alternative column header for use in CA Culprit reports. The length and number of these headers are governed by CA Culprit conventions, as described in the CA Culprit User Guide. This comment key is valid only with RECORD statements and RECORD ELEMENT substatements. |
|
OLQ HEADER |
An alternative column header for use in CA OLQ reports. This comment key is valid only with RECORD statements and RECORD ELEMENT substatements. |
|
REMARKS |
Descriptive text for programs. This comment key can appear in PROGRAM statements only. |
User-defined Comment Keys
You can define additional comment keys.
To define a new comment key, you must issue a MODIFY ENTITY statement to modify the standard ENTITY definition established during IDD installation. You must be assigned ATTRIBUTE authority to define comment keys (see AUTHORITY Clause).
Note: Do not use the MODIFY ENTITY statement to add user-defined entities to the dictionary; the result of such use is unpredictable.
Syntax: MODIFY ENTITY Statement (for user-defined comments)
►►─── MODify ENTIty type name is entity-type-name ────────────────────────────► ►─┬─────────────────────────────────────────────────────────┬────────────────► └─┬─ PREpared ─┬─ by user-id ─┬─────────────────────────┬─┘ └─ REVised ──┘ └─ PASsword is password ──┘ ┌────────────────────────────────────────────────────────────────────────┐ ►─▼─┬ INClude ◄ ┬ USER DEFINED COMMENT is comment-key ┬───────────────────┬┴─►◄ └ EXClude ──┘ └ TEXt is user-text ┘
Parameters
Specifies the entity type that is the object of the modification. Entity-type-name can be any standard IDD entity-type name; however, several entity types cannot appear in this clause. A list of the substitute names to be used for these entity types follows:
|
Entity type |
Substitute name |
|---|---|
|
ENTRY POINT |
PROGRAM |
|
PROCESS |
MODULE |
|
QFILE |
MODULE |
|
REPORT |
RECORD |
|
SCREEN |
PANEL |
|
SUBSYSTEM |
SYSTEM |
|
TABLE |
MODULE |
|
TRANSACTION |
RECORD |
|
User-defined entity |
ATTRIBUTE |
Identifies the user requesting the operation. PREPARED BY can be used when a new comment key definition is added to the dictionary; REVISED BY can be used when a comment key is changed. If the named user has been assigned a password, the PASSWORD parameter must be specified. See Securing the Dictionary earlier in this chapter for the rules pertaining to the PREPARED/REVISED BY clause.
Specifies the password of the user named in the PREPARED/REVISED BY clause. If password contains embedded blanks or delimiters, it must be enclosed in site-standard quote characters.
Identifies the comment key to be associated with (INCLUDE) or dissociated from (EXCLUDE) the requested entity type; INCLUDE is the default. Comment-key must be a unique 1- through 40-character value. Values that contain embedded blanks or special characters or that duplicate a keyword from the DDDL syntax must be enclosed in site-standard quote characters. Note that a keyword defined as a relational key (see Associating Entity Occurrences, later in this chapter) for the requested entity cannot be defined as a comment key for the same entity. This clause can be repeated to add any number of comment keys.
Note: Use the EXCLUDE option with care. When a comment key is excluded from an entity type, relationships between occurrences of the entity that are based on the excluded comment key cannot be deleted, reported on, or reestablished with the INCLUDE option. First, delete the comment text from all entity occurrences with which it is associated; then exclude the comment key.
Associates documentation text with the comment key. Text must be 1 through 40 characters in length and, if it includes delimiters or embedded blanks, must be enclosed in site-standard quote characters.
Syntax: COMMENTS Clause
►►─┬─ COMments ───────┬─ is ─┬─ NULl ─────────┬───────────────────────────────►◄ ├─ DEFinition ─────┤ └─ comment-text ─┘ ├─ OLQ header ─────┤ ├─ CULprit header ─┤ ├─ REMarks ────────┤ └─ comment-key ────┘
Parameters
Identifies the predefined (COM/DEF/OLQ/CUL/REM) or user-defined (comment-key) comment key to which the comment text applies. Comment-key must be a user-defined key previously established in the dictionary through the MODIFY ENTITY statement. If comment-key includes delimiters or embedded blanks, or if it duplicates a DDDL keyword, it must be enclosed in site-standard quote characters. Because the DDDL compiler recognizes comment keys as keywords, the specified comment key can be abbreviated.
Removes existing text from the comment key.
Specifies the comment text to be associated with the comment key. Comment-text can consist of multiple input lines. Each line following the first line must begin with the continuation character (-) followed by the site-standard quote character; the closing quotation mark is optional. Once defined, comment text can be edited (see EDIT Clause, later in this chapter).
Usage
Associating text with a comment key
After using the MODIFY ENTITY statement to include a comment key for an entity type, you can use the COMMENTS clause to associate text with a predefined or user-defined comment key.
Include a COMMENTS clause in the applicable entity-type statement. If a comments clause appears in a MODIFY or REPLACE statement, the DDDL compiler edits, replaces, or removes existing comment text.
Disassociating comment text from a comment key
To delete a comment key, remove the comment text associated with a specified entity (using the NULL parameter of the COMMENTS clause). If the comment is user-defined, issue the MODIFY ENTITY statement specifying the EXCLUDE USER DEFINED COMMENT option.
Examples
The following statement establishes the comment key SPECIAL CONSIDERATIONS for the SYSTEM entity type.
modify entity system
revised by j-user
include user defined comment is 'special considerations'.
The following statement associates the comment text VACATION PAY INCLUDED IN JUNE 30 CHECKS with the comment key SPECIAL CONSIDERATIONS for the system PAYROLL.
modify system payroll
'special considerations' is 'vacation pay included'
-'in june 30 checks'.
The following statement deletes the comment key from the system PAYROLL.
modify system payroll
'special considerations' is null.
The following statement excludes the comment key from the entity type.
modify entity system
revised by j-user
exclude user defined comment is 'special considerations'.
|
Copyright © 2014 CA.
All rights reserved.
|
|