HP 3000 Manuals HP 3000 Manuals
Introduction to Virtuoso Statements
Virtuoso statements are either constructs (generator commands) or calls
to existing macros. Non-Virtuoso statements are referred to as user
text. User text can be any type of text that is to be generated. For
example, COBOL source statements are user text. User text appears in the
output from the Virtuoso Generator; Virtuoso statements do not.
The "#" sign is used to distinguish Virtuoso statements from user text.
This character must be the first non-blank character beginning at the
left margin of a line. For COBOL, the default left margin is column 7.
For all others, the default is column 1. The ampersand sign (&) is used
at the end of a line to continue a Virtuoso statement on the next line.
The continued lines must also begin with a "#" sign.
The input file used by the generator can contain Virtuoso statements and
user text as shown in the example below. Note that this example depends
on the existence of specific entries in the System Dictionary. These
entries are listed just below the example code. The output from the
Virtuoso Code Generator appears after the System Dictionary entries.
This example is designed to illustrate general features of Virtuoso
statements; don't expect to understand it in detail at this point.
However, by the end of this chapter, you should be able to read it
easily. The purpose of the code in the example is to retrieve all
elements of the record ORDER-MAS-REC with element type "X" and to
generate a COBOL DISPLAY statement for each such element.
The example also illustrates two other aspects of Virtuoso statements.
The "!" indicates a keyword substitution. In !element, the value of the
keyword element is substituted starting with the "!". Keywords and
substitution are discussed in more detail later in this chapter. The
element=? phrase indicates a wildcard retrieval. All relationships of
the type RECORD contains ELEMENT where RECORD="ORDER-MAS-REC" are
retrieved regardless of the value for entity-type element in the
dictionary.
EXAMPLE VIRTUOSO SOURCE PROGRAM
#for record="ORDER-MAS-REC" element=? relclass="contains" # attr=(element-type)
# if element-type="X"
DISPLAY !element.
# endif
#endfor
SYSTEM DICTIONARY DEFINITIONS FOR THIS EXAMPLE:
RECORD contains ELEMENT
ORDER-MAS-REC contains ORDER-NUMBER
element-type="X"
ORDER-MAS-REC contains CUSTOMER
element-type="X"
ORDER-MAS-REC contains AMOUNT
element-type="9"
OUTPUT GENERATED BY EXAMPLE:
DISPLAY ORDER-NUMBER.
DISPLAY CUSTOMER.
When the generator encounters a "#" sign, it interprets the line as a
Virtuoso statement, checks for valid syntax in the line, and performs the
necessary actions. When a line does not begin with a "#", the generator
interprets the line as user text. However, it does perform substitutions
on keywords such as !element. In the above example, the statement
DISPLAY !element is user text, in this case COBOL. In the output it
appears as the two statements shown above. There are two statements
because two elements of ORDER-MAS-REC satisfied the #if construct. These
elements are ORDER-NUMBER and CUSTOMER, and they were substituted for
!element in the COBOL DISPLAY statement.
Note that #if is referred to as a Virtuoso construct. Virtuoso
statements include both constructs and calls to macros. #for, #if,
#endif and #endfor are all Virtuoso constructs. Macros are composed of
Virtuoso statements and user text, just like other Virtuoso text, and are
invoked by name. #DBOpen and #AddEntry are two examples of macros in the
Virtuoso COBOL Sample Library. There are a limited number of Virtuoso
constructs. All constructs are described in detail in Chapter 3 of this
manual. In contrast, the number of potential macros is unlimited. These
include the macros in the Virtuoso COBOL Sample Library as well as all
the custom macros which may be created by users.
It is easy to distinguish macros from constructs. By convention, macros
are normally written with initial caps, while constructs are entirely
lower case letters. Also, since there are only a limited number of
constructs, they are easy to recognize in Virtuoso source code.
Keyword-Value Pairs
Notice the phrases such as relclass="contains" and
record="ORDER-MAS-RECORD" in the previous example Virtuoso source
program. These are examples of keyword-value pairs, the
storage/retrieval structure available in Virtuoso. Keyword/value pairs
can be created in two ways: through the #let construct or through
retrieval from System Dictionary.
Keywords can be assigned a value with the #let construct. A keyword can
also be a System Dictionary entity-type or attribute. Then the entity
occurrence or attribute value becomes the keyword value when retrieved
from the System Dictionary. That is, the keyword-value pair is created
when retrieval occurs. Thus, the keyword-value pair depends on the
existence of a structure-occurrence relation in the System Dictionary.
This relation can then be used for parameter replacement. Parameter
replacement (substitution) is part of what allows you to make Virtuoso
source code generic and reusable.
Keyword-Value Syntax. The general syntax for a keyword-value pair is:
keyword=value
The keyword always appears on the left side of the equals sign, and the
value appears on the right. Keyword values can be of type string or
numeric. String values must be enclosed in quotes ("). If there are
quotes within the string, enclose the string in single quotes (').
Here are some examples of keyword-value pairs:
image-database="ORDERS"
mode="2"
calc-value=15
In the example mode="2", the keyword mode has the string value "2",
whereas in calc-value=15, the numeric value 15 is paired with the keyword
calc-value.
Here are some examples of keyword assignments using the #let construct:
#let start-value=1
#let default-name="xyz"
When you use the #let construct, the keyword is created if it does not
already exist. If the keyword already exists, it is assigned the new
value.
The use of attr (attribute retrieval) is an exception to the general
keyword-value syntax. The syntax for System Dictionary attribute
keyword-value pairs is as follows:
attr=(attr1 attr2 attr3 ...)
where attr1 attr2 attr3 are the names of the various attributes whose
values are to be retrieved from the System Dictionary. Keyword-value
pairs are then established for each of the keywords (attr1 attr2
attr3...) appearing in the attr=() clause. Here is an example of an
attribute retrieval:
attr=(element-type)
The clause attr=() can appear in constructs which retrieve information
from the System Dictionary, such as #for and #getrel. When the attribute
element-type is retrieved for a particular element or relationship, this
sets up a new keyword-value pair. In the example of Virtuoso source
earlier in this chapter, the attribute element-type had the value "9" for
element AMOUNT in the record ORDER-MAS-REC. Thus the keyword-value pair
element-type="9"
was created when the element AMOUNT was retrieved for record
ORDER-MAS-REC.
Keyword Naming Conventions. These are the rules for keywords:
* The maximum length of a keyword is 32 characters.
* The first character of a keyword must be alphabetic.
* Keywords can be made up of characters from a-z, A-Z, 0-9, hyphen (-)
and underscore (_).
* The generator upshifts all keywords before acting on them. Upper
case and lower case map to the same keyword name. Thus it is the
spelling of a keyword that makes it unique.
Note that the values of keywords are not upshifted by the generator. If
a keyword is assigned a value with lower case letters, this value will
not be upshifted to upper case letters.
Here are some examples of valid keywords:
image-database
Element_Type
R341
HP-OPEN-MODE
Here are some examples of invalid keywords:
this-is-an-excessively-long-keyword
943-entry
data*item
element'
Do not create keywords using the names loopcounter or numrels. These are
system-supplied keywords used by the generator.
Parameter Replacement
The Virtuoso Code Generator performs parameter replacement on keywords
preceded by the substitution character "!". The generator keeps track of
the keywords and their values. Here is an example:
#let element="STREET-ADDRESS"
MOVE !element TO !element!-DATA
The character "!" indicates substitution. That is, the value of the
keyword following the "!" is to be substituted. This value is the value
of the keyword which was set up via System Dictionary retrieval or
assignment via the #let construct.
Note the second "!" in !element!-DATA. This terminates the keyword
element. Otherwise, the Virtuoso Generator would assume that the keyword
element-DATA was meant. The second "!" is only necessary in ambiguous
cases such as this. If the keyword to be substituted is followed by a
character which is not a valid keyword character, such as a blank or a
quote mark, then there is no need for a closing "!".
The character "!" is the default substitution character. It can be
changed with the #option construct. Refer to Chapter 3 for more
information on #option.
Note that parameter replacement always occurs before code generation.
That is, all substitutions are made before any processing of the line is
done.