HP 3000 Manuals HP 3000 Manuals
DICTVPD
VPLUS Forms File Definition Utility
The VPLUS Forms File Definition utility (DICTVPD) enters the definition
for an existing VPLUS forms file into the Dictionary. This utility
creates the entries for the forms file, the forms in the forms file, and
the data fields for the forms in the Dictionary. The forms file is
entered in the Dictionary as a VPLS type file. The forms are entered as
FORM type files and the data fields are entered as data elements in the
Dictionary.
DICTVPD also establishes the associations of the data fields with the
forms and the relationships between the forms and the forms file.
However, form family relationships are not established in the Dictionary
by DICTVPD. In the Dictionary, the parent forms and the child forms in a
form family will only be related to the forms file.
Before the definition of a forms file is loaded in the Dictionary,
DICTVPD checks the existing entries to avoid entering duplicate or
redundant entries. If the name used for a forms file, form or data field
being loaded is the same as the name of an existing entry, a warning
message is issued. For a duplicate forms file name or a duplicate data
field name, you are given the option to either enter a new name or to use
the existing entity in the Dictionary. For a duplicate form name, you
are given the option to either skip that form (that form would not be
loaded, but subsequent forms would be loaded), purge the existing form
(the form name and all associations with the form would be purged but the
elements associated with the file would not be purged), or enter a new
name for the form to be loaded.
Whenever a name is changed for an entity being loaded into the
Dictionary, the new name entered becomes the "primary" name for that
entity. The original name then becomes the "alias" name for that entity
in the Dictionary. Because HP Inform will reference these entities by
their aliases, the original names used by VPLUS do not have to be changed
to be consistent with the Dictionary. However, since DICTDBM uses the
primary names for all entities, it is important to remember what the new
primary names are for the entities whose names were changed.
The following description explains how to execute DICTVPD and gives an
explanation of each prompt.
This utility assumes that the Dictionary to be used by DICTVPD is in
DICT.PUB in the logon account. If the forms file is to be loaded in a
Dictionary which is not in that group and account, use an MPE file
equation to redefine the Dictionary's location before running this
utility.
To execute DICTVPD, enter the following MPE command:
RUN DICTVPD.PUB.SYS
After an acknowledgement message, DICTVPD prompts for the Dictionary
password to open and read the Dictionary as follows:
DICTIONARY PASSWORD>
Enter the Dictionary password and press [[RETURN]]. The password must
grant at least PROGRAMMER level access to the Dictionary. (See Appendix
C for an explanation of the levels of access.) This password will not be
displayed on the terminal as it is entered. However, it must be entered
correctly or an error will result and the prompt will be reissued. If
[[RETURN]] is pressed as the only response to this prompt DICTVPD will
terminate. After the password is accepted DICTVPD then prompts for the
name of the forms file to be loaded into the Dictionary.
FORMS FILE NAME>
Enter the forms file name (20 characters maximum).
DICTVPD now checks the Dictionary for any existing entries which may have
the same name as the name entered. If an entry already exists with this
name, the following warning and prompt are issued:
*WARNING: FORMS FILE ALREADY NAMED IN DATA DICTIONARY
DO YOU WANT TO LOAD UNDER A DIFFERENT NAME(Y/N)>
If N is entered in response to this prompt, DICTVPD will load the forms
file into existing file defined in the Dictionary. If Y (the default) is
entered in response to this prompt, a new prompt is issued to rename the
forms file to be loaded into the Dictionary.
NEW FORMSFILE NAME>
Enter the new forms file name. This name must be unique to the
Dictionary; otherwise, the above warning and prompt will be reissued.
This name becomes the primary name for this forms file in the Dictionary.
Once the forms file name is accepted, the following prompt is issued:
SELECT DATA CONVERSION(Default/Char)>
The response to this prompt determines how the data types defined for the
data fields are converted to Dictionary compatible data types. For
instance, if Char (or C) is entered as the response to this prompt, then
any data types defined in the forms file will be converted to Dictionary
type X when loaded into the Dictionary. The size and storage length will
be the same as the field length. If Default (or D) is entered as the
response to this prompt, then the data types defined in the forms file
will be converted and entered into the Dictionary as shown on the next
page.
-----------------------------------------------------------------------------------------------------
| | |
| VPLUS | DICTIONARY/3000 |
| | |
-----------------------------------------------------------------------------------------------------
| | | | | | |
| TYPE | FIELD LENGTH | TYPE | SIZE | DECIMAL | STORAGE LENGTH |
| | | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | | |
| CHAR | L | X | L | 0 | L |
| | | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | | |
| NUM | L (if L is 1) | R | 1 | 0 | 4 |
| | | | | | |
| | L (if L is 2, 3, 4, 5 or | R | L-1 | 0 | 8 |
| | 6) | | | | |
| | | | | | |
| | L (if L is 7 or greater) | R | L-1 | 0 | 8 |
| | | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | | |
| NUMn | L (if L is 1) | I | 1 | n | 2 |
| | | | | | |
| | L (if L is 2, 3, 4, or 5) | I | L-1 | n | 2 |
| | | | | | |
| | L (if L is 6, 7, 8, 9 or | I | L-1 | n | 4 |
| | 10) | | | | |
| | | | | | |
| | L (if L is 11 or greater) | P | L-1 | n | * (L + 1)/2 |
| | | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | | |
| DIG | L (if L is 1, 2, 3, or 4) | I+ | L | 0 | 2 |
| | | | | | |
| | L (if L is 5, 6, 7, 8 or | I+ | L | 0 | 4 |
| | 9) | | | | |
| | | | | | |
| | L (if L is 10 or greater) | P+ | L | 0 | * (L + 2)/2 |
| | | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | | |
| IMPn | L (if L is 1) | I | 1 | n | 2 |
| | | | | | |
| | L (if L is 2, 3, 4, or 5) | I | L-1 | n | 2 |
| | | | | | |
| | L (if L is 6, 7, 8, 9 or | I | L-1 | n | 2 |
| | 10) | | | | |
| | | | | | |
| | L (if L is 11 or greater) | P | L-1 | n | * (L + 1)/2 |
| | | | | | |
-----------------------------------------------------------------------------------------------------
L = VPLUS Field Length
* when computing these numbers always round down
The following examples use the chart above to determine how data types,
size, decimal and storage lengths are converted into the dictionary if
the elements have NOT been previously defined and you have selected
DEFAULT conversion.
Example
VPLUS DICTIONARY
Type Field Length Type(Size,Decimal,Storage Length)
CHAR 10 X(10,0,10)
Dictionary converts the CHAR to type X and takes the VPLUS field length
as its size and storage length. Decimal is 0.
NUM 10 R(9,0,8)
Dictionary converts type to R. Size is 9 because the VPLUS field length
is 10, and 10 - 1 is 9. Decimal is 0. Storage length is 8.
NUM 1 R(1,0,4)
Dictionary converts type to R. Size is 1. Decimal is 0. Storage length
is 4.
NUM5 10 I(9,5,4)
(n=5)
Dictionary converts type to I. Size is 9 because the VPLUS field length
is 10, and 10 - 1 is 9. Decimal is equal to n which is 5. Storage
length is 4.
NUM5 20 P(19,5,10)
(n=5)
Dictionary converts type to P. Size is 19 because the VPLUS field length
is 20, and 20 - 1 is 19. Decimal is equal to n which is 5. Storage
length is 10 because (20 +1)/2 = 10 (rounded down).
DIG 10 P+(10,0,6)
Dictionary converts type to P+. Size is equal to the VPLUS field length
which is 10. Decimal is 0. Storage length is 6 because (10 + 2)/2 = 6.
IMP5 10 I(9,5,4)
(n=5)
Dictionary converts type to I. Size is 9 because the VPLUS field length
is 10, and 10 - 1 is 9. Decimal is equal to n which is 5. Storage
length is 4.
IMP5 20 P(19,5,10)
(n=5)
Dictionary converts type to P. Size is 19 because the VPLUS field length
is 20, and 20 - 1 is 19. Decimal is equal to n which is 5. Storage
length is 10 because (20 + 1)/2 = 10 (rounded down).
If the data fields (elements) have not been previously defined in the
Dictionary, enter N. This indicates that new element entries are to be
created when the elements are loaded into the Dictionary.
DATA ELEMENTS ALREADY DEFINED(Y/N)>
If the data fields for the forms file have already been defined as
elements in the Dictionary, enter Y in response to the prompt. This
indicates that DICTVPD will use the existing element entries to define
the data fields as long as the existing element data is compatible with
the data for the data fields to be loaded. If DICTVPD finds that the two
element definitions are not compatible, an error will be displayed as the
utility tries to load the data field.
DICTVPD determines that an existing dictionary element and a VPLUS field
are compatible if the display size of the dictionary element is 1 less
than (for the signed numeric data types 9, Z, I, P, R, K, J, and E) or
equal to (for the remaining data types such as 9+, Z+, I+, etc.) the
VPLUS field length. The reason that the dictionary display size for
signed numeric data types must be 1 less than the VPLUS field length is
that the display size stored in the dictionary does not include a
character position for the sign while the VPLUS field length does. If
DICTVPD determines that the dictionary element and the VPLUS field are
incompatible, the user receives an error message and is prompted for a
new primary element name.
After DICTVPD loads the forms file in the Dictionary, a reference list is
generated which shows the loaded forms file, forms, and data fields.
Also included in the reference list are the data names, aliases, data
dispositions and data types as they were loaded in the Dictionary. This
list can be a useful tool to ensure that the loaded forms and data are
the correct ones and to provide future reference documentation. (See the
example following the discussion of DICTVPD for a sample reference list.)
The next prompt allows you to direct the reference list to the terminal,
the line printer, on a specified disc file, or to suppress the listing
entirely.
LIST FILE>
Enter one of the following options in response to the LIST FILE prompt:
LP sends the reference list to the line printer. If there
is no device LP configured on your system, use a file
equation to redirect DICTLIST to another device.
NULL suppresses the list.
filename sends the list to a disc file. If the specified file
already exists, an error message will be issued and you
will be asked if the contents of the file should be
purged. If not, you will be prompted for a new list
file.
*filename sends the listing to the file identified in the
back-referenced file equation.
[[RETURN]] displays the list on $STDLIST after the forms file has
been loaded.
DICTVPD then issues the prompt:
CHANGE UNDERSCORE TO HYPHEN(Y/N)>
Although the Dictionary and VPLUS recognize an underscore character ("_"
) as a valid character, IMAGE does not. (However, IMAGE does recognize a
hyphen ("-" )). Therefore, in order to ensure compatibility between
IMAGE and the forms file, you may choose to allow DICTVPD to change any
occurrence of an underscore character in the forms file to a hyphen.
Enter N to keep the underscore character as itself when the forms file is
loaded.
After you respond to the above prompt, DICTVPD loads the forms file in
the Dictionary and displays the following message:
LOADING DATA DICTIONARY
The utility then begins the loading process for the forms and data
fields. Since DICTVPD allows you to selectively load forms into the
Dictionary, you can specify which forms are to be loaded for this forms
file with the following prompt:
FORM NAME TO BE LOADED(or "@"/"?")>
Enter the name of an individual form belonging to the forms file. If you
are not sure of the names of the forms in the forms file, enter "?" .
DICTVPD will display the list of forms that may be loaded. DICTVPD will
then reprompt you to enter the form name. If an individual form name is
entered in response to this prompt, DICTVPD will continue to prompt for
form names until no other form names are entered and [[RETURN]] is
pressed.
Enter "@" to load all forms in the forms file. Note that if this forms
file is a new entry in the Dictionary, the VPLUS reserved form $REFRESH
will also be loaded in the Dictionary for this forms file. This form
will not have any data fields associated to it. Also, $REFRESH will not
appear on the reference list for the forms file but will appear when the
Dictionary is accessed by the program DICTDBM.
As each form is loaded in the Dictionary, the following message will
appear:
LOADING FORM: formname
If DICTVPD finds an existing entry in the Dictionary with the same name
as the form to be loaded, the following warning and prompt are issued:
*WARNING: DICTIONARY ALREADY CONTAINED FORM: formname
SKIP, PURGE OR ENTER NEW FORM(S/P/N)>
If S is entered in response to this prompt, DICTVPD will ignore the
current form and proceed to load the next form in the forms file. If P
is entered, DICTVPD will purge the existing form in the Dictionary along
with all the associations it may have. Note that the elements themselves
are not purged, only the associations to the form are purged. Once the
existing form has been purged, DICTVPD will load the form which belongs
to the forms file in the Dictionary. If N is entered in response to this
prompt, a new prompt is issued to rename the form to be loaded as
follows:
NEW FORM NAME>
Enter a new name for the form. This name must be unique to the
Dictionary or DICTVPD will reissue the warning and prompts above. The
original name used for the form in the forms file becomes the alias name
in the Dictionary. The new name entered becomes the primary name in the
Dictionary.
As each form is loaded in the Dictionary, DICTVPD checks that there are
no data field name conflicts between the existing elements defined in the
Dictionary and the data fields currently being loaded. For instance, if
Y was entered in response to the DATA ELEMENTS ALREADY DEFINED prompt and
DICTVPD can not find the existing entry for a data field being loaded,
the following message will be issued:
ELEMENT NOT DEFINED, NEW ELEMENT LOADED: element
This indicates that DICTVPD has loaded the specified data field from the
forms file in the Dictionary as a new element entry.
If N was entered in response to the DATA ELEMENTS ALREADY DEFINED prompt,
DICTVPD will still check for existing data elements in the Dictionary
with the same name and compatible definition. If DICTVPD finds a
duplicate entry in the Dictionary and the data type and data size are
compatible with the data field to be loaded, DICTVPD will issue the
following message and prompt:
COMPATIBLE DEFINITION ALREADY IN DICTIONARY FOR ELEMENT element
DO YOU WANT ELEMENT TO HAVE A DIFFERENT NAME(N/Y)>
Enter N to use the existing entry in the Dictionary for this element.
Enter Y to rename the element being loaded. A new prompt will then be
issued:
NEW PRIMARY ELEMENT NAME>
Enter the new primary name for the data field being loaded in the
Dictionary. Once again, the original name becomes the alias for the
element. If [[RETURN]] is pressed in response to this prompt, the data
field is not loaded in the Dictionary and the following warning is
issued:
*WARNING: ELEMENT HAS NOT BEEN LOADED INTO DICTIONARY
If N was entered in response to the DATA ELEMENTS ALREADY DEFINED prompt
and DICTVPD finds an existing element in the Dictionary with the same
name but an incompatible definition, the following message and prompt are
issued:
INCOMPATIBLE DEFINITION ALREADY IN DICTIONARY FOR ELEMENT: element
NEW PRIMARY ELEMENT NAME>
Enter the new primary element name for the element being loaded.
Note that a new element name must be entered and the existing element can
not be used for this data field because the data type and data size for
the existing element are not compatible with the data field's definition.
If [[RETURN]] is pressed in response to this prompt the data field will
not be loaded and a warning will be issued (as shown above).
After all forms and respective data fields have been loaded into the
Dictionary, DICTVPD will generate the listing of the loaded forms file,
the forms and the data fields. (See the LIST FILE prompt for information
on this listing. See the example that follows for a sample reference
list.)
After the listing is produced, DICTVPD terminates.
Example
The following is an example of DICTVPD:
RUN DICTVPD.PUB.SYS How to execute this utility.
<The Dictionary/3000 VPLUS Loader program banner appears here.>
DICTIONARY PASSWORD> ; Password for modify access used.
FORMS FILE NAME> Formf1
SELECT DATA CONVERSION (Default/Char)> D
DATA ELEMENTS ALREADY DEFINED (Y/N)> N
LIST FILE> LP The report is sent to the Line Printer.
CHANGE UNDERSCORE TO HYPHEN (Y/N)> Y
LOADING DATA DICTIONARY
FORM NAME TO BE LOADED (or "@"/"?")> @ All forms in the forms file to be
loaded.
LOADING FORM: FORMA
LOADING FORM: FORMB
Name Alias NEW/OLD Type
FORMF1 NEW VPLS
FORMA NEW FORM
F5 NEW X ( 5, 0, 5)
F10 NEW X (10, 0,10)
F20 NEW X (20, 0,10)
F2 NEW X ( 2, 0, 2)
UNDER_SCORE_TO NEW X (14, 0,14)
FORMB NEW FORM
CHAR NEW X ( 5, 0, 5)
NUMN NEW I ( 4, 3, 2)
NUM NEW R ( 4, 0, 4)
DIG NEW I+( 5, 0, 4)
IMPN NEW I ( 4, 2, 2)
IMP NEW I ( 4, 0, 2)
MDY NEW X ( 5, 0, 5)
DMY NEW X ( 5, 0, 5)
YMD