HP 3000 Manuals HP 3000 Manuals
#for/#endfor
Retrieves all entities or relationships of a specified type from the
System Dictionary.
Syntax
#for entity-type1="entity-name1" [entity-type2="entity-name2"...]&
# [relclass="relationship-class"] [attr=(attr1 attr2...)] &
# [alias="alias-type"]
.
.
statements
.
.
#endfor
Keywords
entity-type1 is either the first entity type of the
relationship type to be retrieved from the
System Dictionary, or the entity type of all
entities to be retrieved.
entity-name1 is the name of the entity of the first entity
type in the entity or relationship that is to
be retrieved from System Dictionary. A "?" can
be used to indicate all entity names.
entity-type2,3,... are the other entity types of the relationship
type to be retrieved from System Dictionary.
Up to six entities are allowed per relationship
in the #for construct. These keywords are
optional. If only one entity-type is specified
in the #for statement, entities are retrieved.
entity-name2,3,... is the name of the entity of the other entity
types in the relationship that is to be
retrieved from System Dictionary. When only
one entity-name is entered without the RELCLASS
keyword, all entities of an entity-type are
retrieved. The keyword NUMRELS contains the
number of entities retrieved.
relationship-class is the name of a relationship class of the
relationship which is to be retrieved from
System Dictionary. The relationship class can
be any valid System Dictionary relationship
class. This parameter should only be used when
retrieving relationships.
attr1 ... are the attributes of the entity or
relationship being retrieved from the
dictionary. This can be a single attribute or
an attribute list. By default, no attributes
for the entity or relationship are retrieved.
Use blanks or commas to separate attributes.
alias-type is the type of alias that will be retrieved for
the relationship. The value for this option
can be the name of any alias-type attribute.
Remember that an alias in a relationship's list
of attributes is information about the second
entity in the relationship.
statements are statements or user text lines.
Description
This construct retrieves all of the relationships of a particular
relationship type from the System Dictionary The #for construct is a
looping construct that generates a sequence of text for each relationship
retrieved. On each iteration of the loop, a relationship is retrieved
and the text that appears between the #for and the #endfor is generated.
The loop can contain any type of statement, including calls to macros.
The #for can also be nested and can be included as a construct in the
loop.
The loop is terminated when an end of list condition is detected from the
System Dictionary. If there are no occurrences of the relationship
specified the loop is not executed and no text is generated. The #for
construct has the same execution sequence as that of a WHILE loop in
COBOL. Both check the loop condition at the beginning of the loop and
execute only if the condition is true. If true, the #for construct
retrieves entities or relationships until an end-of-list condition is
detected.
The construct allows the flexibility of specifying a "?" to reference all
entity names. Attributes are retrieved from the System Dictionary only
when a list is specified. When the attr clause is omitted from the
statement, no attributes for the relationship are retrieved. If you want
all attributes of the relationship to be retrieved, use attr=(ALL). Note
that this can significantly lengthen generation time. It is recommended
that you retrieve only those attributes that are needed.
On each iteration of the #for construct, the entity-names of the current
relationship, as well as any specified attributes of the relationship,
are retrieved and stored as keyword-value pairs. The entity names are
accessible by referencing the entity type as the keyword name and
preceding it with the substitution character. The attributes of the
relationship are also accessible in the same manner. Precede the
attribute name with the substitution character. Note that the
#for/#endfor construct creates a new scope. Thus, the values introduced
into the module in the scope of the #for are not accessible outside of
the #for/#endfor. Use the #returnvalue construct to return information
to the outer scope.
Identical Entity Types. When retrieving relationships that involve
identical entity types, the entity names are accessible by referencing
the entity-type followed by a colon (:), followed by a number. For
example:
#for element="ADDRESS" element=? relclass="contains"
In the above example, the relationship contains two entity types that are
the same (ELEMENT). The values for the keywords are accessed by using
!ELEMENT:1 for the first element and !ELEMENT:2 for the second element.
The numbers refer to the order in which the entity types appear in the
#for construct. In the example above, ELEMENT:1 has the value "ADDRESS".
Aliases. The alias-type parameter lets you specify an alias attribute to
be retrieved for the relationship occurrence. The alias retrieved
applies to the second entity in the relationship. The keyword for that
entity is assigned the value of the alias attribute. If no alias is
present on the relationship, it is retrieved from the entity. In the
case where the alias is not present in either place, the value of the
keyword is the primary entity name.
Other Keywords. There are two system-supplied keywords which you can use
with the #for construct. The keyword loopcounter contains the number of
times the #for loop has been executed. This keyword is accessible only
within the loop.
The keyword numrels contains the number of relationship occurrences
retrieved during the #for/#endfor loop. This keyword can be accessed
only after all relationships have been retrieved (after #endfor). If the
#for statement does not retrieve any relationships, numrels contains a
value of zero.
Limitations.
1. The maximum number of retrievable entities in a relationship is
six. In other words, a 6-way relationship is the largest
relationship that can be retrieved.
2. The maximum number of attributes that can be retrieved is as
follow
* 64 - if attr = (ALL)
* 20 - if the attributes are listed individually, i.e., ATTR=
(attr1,attr2,...)
When retrieving a variable length attribute, the maximum length of the
attribute is restricted to 1023 bytes. If the attribute value is longer
than this limit, truncation occurs and you receive a warning message.
Nesting of #for/#endfor constructs is allowed, but remember that the
nesting limit is 40. That is, there cannot be more than 40 nesting
levels in existence at one time. This includes nesting of #for/#endfor,
#if/#endif, #include, #block/#endblock, #entry/#endentry and macro calls.
Examples
EXAMPLE 1
#let module="MAIN1"
#for module="!main-program" image-database=? relclass="processes"
01 !image-database!-DATA.
05 !image-database!-BASE-ID PIC X(02).
05 !image-database!-BASE-NAME PIC X(08).
#endfor
System Dictionary Definitions for this Example:
MODULE processes IMAGE-DATABASE
MAIN1 processes SALES
MAIN1 processes ORDERS
Output generated:
01 SALES-DATA.
05 SALES-BASE-ID PIC X(02).
05 SALES-BASE-NAME PIC X(08).
01 ORDERS-DATA.
05 ORDERS-BASE-ID PIC X(02).
05 ORDERS-BASE-NAME PIC X(08).
This example retrieves all databases used in the module defined by MAIN1
and generates COBOL code for each database name. The #for loop
terminates after retrieving all relationships where an image-database is
processed by the module main-program.
EXAMPLE 2
#let module="Update-Sales"
The Module !module uses the following scripts:
#for module="!module" hpscript=? relclass="references"
o !hpscript
#endfor
EXAMPLE 3
#FOR image-database="MAILDB" image-dataset="?" relclass="contains"
.
.
#ENDFOR
The above example is for a #for construct where at least one entity name
needs to be specified. All relationships that include at least some
entities specified in the search pattern are retrieved.
EXAMPLE 4
#FOR image-database="?" image-dataset="?" relclass="contains"
.
.
.
#ENDFOR
The above example retrieves all relationships of the specified
relationship type that are owned by the current scope.
EXAMPLE 5
#FOR image-database="?"
.
.
.
#ENDFOR
The above example retrieves all entities of the specified entity type
that are owned by the current scope.
System Dictionary Definitions for this Example:
MODULE references HPSCRIPT
UPDATE-SALES references ORDER-INFO
UPDATE-SALES references ORDER-HEADER
UPDATE-SALES references ORDER-TRAILER
UPDATE-SALES references ORDER-SUMMARY
This documentation example illustrates the retrieval of a relationship
and then the generation of a list of values in the documentation. A line
of documentation is generated for each script referenced by !module.
Output from the #for statement is shown below:
The module UPDATE-SALES uses the following scripts:
o ORDER-INFO
o ORDER-HEADER
o ORDER-TRAILER
o ORDER-SUMMARY