HP 3000 Manuals HP 3000 Manuals
#getrel
Retrieves a relationship of a specified relationship type from the System
Dictionary.
Syntax
#getrel entity-type1="entity-name1" &
# entity-type2="entity-name2"...&
# relclass="relationship-class" [attr=(attr1 attr2...)] &
# [seqno=value] [alias="alias-type"]
Keywords
entity-type1 is the first entity type of the relationship
type to be retrieved from the System
Dictionary.
entity-name1 is the name of the entity of the first entity
type in the relationship to be retrieved from
System Dictionary.
entity-type2 is the second entity type of the relationship
type to be retrieved from the System
Dictionary. There can be up to six entities in
a single relation.
entity-name2 is the name of the entity of the second entity
type in the relationship to be retrieved from
System Dictionary.
relationship-class is the name of the relationship class of the
relationship to be retrieved from the System
Dictionary.
attr1 attr2... are the attributes of the relationship that are
to be retrieved from the System Dictionary.
value is a numeric value indicating the sequence
number of the relationship. The number is
relative to the first relationship that is
retrieved. For example, if the seventh
occurrence of the relationship type is to be
retrieved, the value would be 7. Only one
value can be specified. The default sequence
number is one.
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.
Description
This construct retrieves one relationship of a particular relationship
type from the System Dictionary. Although multiple relationships can
exist for the relationship type, the #getrel construct always retrieves a
single relationship. By default, #getrel retrieves the first occurrence
of the specified relationship type. If a relationship other than the
first is to be retrieved, you can specify a sequence number indicating
which relationship occurrence is retrieved. For example, when the second
relationship occurrence of the specified relationship type is to be
retrieved, include the clause seqno=2.
The construct allows the flexibility of specifying a "?" for those entity
names not known. For example, if a relationship type consists of two
relationships, then by entering a "?" for one of the entity names, the
first occurrence (or specified seqno) of the relationship type is
retrieved where that occurrence involves the specified entity name. All
but one of the entity names can be a "?".
When the attr clause is omitted from the statement, no attributes f the
relationship are retrieved. If you want to retrieve all of the
attributes of the relationship, specify attr=(ALL). Note that this may
significantly increase generation time. It is recommended that you
retrieve only those attributes that are needed.
When #getrel is executed, the values of the relationship retrieved can be
included in the generated source. The entity names are accessible by
referencing the entity type and preceding it with the substitution
character. The attributes of the relationship are also accessible in the
same manner. All of the entity types of the relationship are also
accessible by preceding the entity type with the substitution character.
Identical Entity Types. Relationship types which involve identical
entity types are accessible by referencing the entity type followed by a
colon (:), followed by a number. For example:
#getrel element="ADDRESS" element=? relclass="contains"
The execution of this construct results in the retrieval of a
relationship between two identical entity types. The values for the
keywords are accessed by using !ELEMENT:1 for the first element and
!ELEMENT:2 for the second element.
Aliases. The alias option specifies that an alias attribute is 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. The system-supplied keyword numrels can be accessed
after the #getrel construct has executed. This keyword contains the
number of relationships which were retrieved. If #getrel was successful,
numrels will equal 1. When numrels is zero, no occurrences were found
for the requested relationship.
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.
Examples
EXAMPLE 1
#getrel hp-script="DATA-ENTRY" form=? relclass="contains"
System Dictionary Definitions for this Example:
HP-SCRIPT contains FORM
DATA-ENTRY contains ORDER-ENTRY-FORM
Keyword-Value Pairs Set Up by this Example:
hp-script="DATA-ENTRY"
form="ORDER-ENTRY-FORM"
The #getrel statement retrieves the name of the form used by the script
DATA-ENTRY. The #getrel construct is more appropriate in this context
than the #for construct since only one form was defined for this example,
thus reducing the overhead incurred in retrieving the information. The
name of the form can be referenced later within the current scope using
the keyword form preceded by the substitution character, for example,
!form.
EXAMPLE 2
#let module="TEST1"
#getrel module="!module" hp-script=? relclass="processes" seqno=2
System Dictionary Definitions for this Example:
MODULE processes HP-SCRIPT
TEST1 processes DATA-ENTRY
TEST1 processes ACCOUNT-ENTRY
Keyword-Value Pairs Set Up by this Example:
hp-script="ACCOUNT-ENTRY"
This example illustrates the use of the sequence number. The second
relationship of the relationship type MODULE processes HP-SCRIPT is
retrieved. An example of where this can be useful is when a module uses
a header and trailer screen and the processing for the module requires
the name of the trailer screen.
EXAMPLE 3
#let form="STAR-FORM"
#let element="LAST-NAME"
#getrel form="!form" element="!element" relclass="contains" alias="vplus-alias"
MOVE !element TO ACCOUNT-NAME
System Dictionary Definitions for this Example:
FORM contains ELEMENT
STAR-FORM contains LAST-NAME
Vplus-Alias="LAST_NAME"
This example uses the alias option to retrieve Vplus-Alias for the name
of the field contained in the keyword element. After the exec of the
#getrel, the keyword element has the value of Vplus-Alias. That is,
element has the value "LAST_NAME".
EXAMPLE 4
#getrel module="!module" formsfile=? relclass="processes"
#if numrels <> 0
# OpenForm formsfile="!formsfile"
#endif
This example uses the value of the numrels keyword to determine when the
module processes a forms file. If #getrel successfully retrieves a
relationship between the module and a forms file, then the macro OpenForm
is called to perform the open. That is, the successful retrieval
indicates that the module does process a forms file.