HP 3000 Manuals HP 3000 Manuals
Programming Considerations
The following paragraphs contain information which may be helpful when
using System Dictionary intrinsics. It includes information about
setting up the programs to run properly (linking the programs with the
right capabilities, etc.) and information on how to make your programs
more efficient.
Prepping Programs for System Dictionary/V
A program running under MPE V and using System Dictionary intrinsics must
be prepped with at least the following capabilities:
IA BA DS
It is also recommended that the programs be prepped with:
MAXDATA = 20000.
Example :
:PREP <YOURUSL>, <PROGNAME>; MAXDATA = 20000; CAP = IA, BA, DS
WARNING Do not prep your programs with MR capability. Read the
information on Locking the Dictionary, which is located further
on in this section.
Linking Programs for System Dictionary/XL
A program running under MPE XL and using System Dictionary intrinsics
must be linked with at least the following capabilities:
IA BA DS
It is also recommended that the programs be linked with:
STACK = 20000.
Example :
LinkEd> LINK FROM = YOURUSL; TO = PROGNAME; STACK = 20000;
CAP = IA, BA, DS
WARNING Do not link your programs with MR capability. Read the
information on Locking the Dictionary, which is located further
on in this chapter.
Improving Program Performance
System Dictionary performance depends a great deal upon making the best
use of the System Dictionary intrinsics. The following suggestions can
greatly improve the efficiency of dictionary operations.
* Use internal numbers rather than names. All System Dictionary
intrinsics look up the internal number of any name provided as an
argument. If a number is provided, this step is bypassed, improving
the intrinsic operating efficiency. Internal numbering is explained
below.
* Provide attribute edits in decreasing order of use. This concept is
explained completely in the General Reference Manual (Volume 1).
* Use the intrinsics SDSwitchDomain, SDSwitchNameMode, SDSwitchScope,
and SDSwitchVersion, when changing domains, name modes, scopes, and
versions, respectively, rather than closing and re-opening the
dictionary. Detailed information about switching is located in
Volume 1 of the HP System Dictionary General Reference Manual, and
also in this manual, in the descriptions for the intrinsic SDOpen,
and the intrinsics listed above.
* Use methods which take advantage of System Dictionary's use of
TurboIMAGE chained-access paths. Wherever possible, System
Dictionary architecture uses TurboIMAGE chains for faster access to
definitions in the SYSDIC database. Therefore, program efficiency
may be increased by using a relationship such as USER owns ACCOUNT,
rather than an entity ACCOUNT having the attribute owner, as the
relationship uses chained access while attributes are accessed
serially.
* Create infrequently used attributes as variable length attributes,
which are handled by specific intrinsics only. These attributes will
then not be handled unless specifically asked for.
Internal Numbering. Each component within System Dictionary has an
internal number associated with it. The responsibility for these numbers
is completely under the control of System Dictionary and the number value
assigned to a particular component does not necessarily follow any set
pattern.
The reason for using internal numbers is efficiency. The use of internal
numbers can improve program response time when retrieving information,
although it can make the program more complex than when using names. The
following are guidelines for using internal numbers:
* Internal numbers are ascertained from the status array of creation
and retrieval operations.
* Internal numbers may be used instead of names when referencing
existing dictionary components by substituting the number where the
name would normally be. However, for parameters that identify more
than one dictionary component (list parameters) names and numbers
cannot be mixed. The format for passing internal numbers and the
details of each intrinsic's handling of them are covered in the
individual intrinsic descriptions located in Chapter 4 of this
manual.
* Use caution if coding internal numbers into a program. Once an
internal number is assigned to a dictionary component, it will remain
the same for the life of the component in the dictionary it was
created in. User created structure components are the only exception
to this. Internal numbers of these components are subject to change
in connection with dictionary software updates that require a
dictionary to be upgraded. If a component is deleted and then
re-added, the assigned internal number may not be the same.
Locking the Dictionary
Within System Dictionary, locking is a process which allows only one user
at a time to access the dictionary. System Dictionary includes a locking
facility that guarantees the integrity of all dictionary modifications.
This facility provides two types of dictionary locking:
1. Automatic Locking : Most System Dictionary intrinsics lock the
dictionary each time they are called, and unlock it as the call is
completed. In the case where a single intrinsic is called once to
accomplish a specific dictionary operation, this integral locking
is adequate to ensure accurate data update or retrieval.
Automatic locking issues an unconditional TurboIMAGE lock, where
control will return only after access is granted and the intended
operation completed.
_________________________________________________________________
NOTE Intrinsics which are usable in only Exclusive Update or
Exclusive Customization modes do not include automatic
locking, as other users are already denied access to the
dictionary.
_________________________________________________________________
Automatic locking is not sufficient protection, however, when the
dictionary operation calls several intrinsics, or calls a single
intrinsic multiple times to complete a specific task, such as
finding all the datasets in a particular database. Although the
dictionary is locked during each individual call of an intrinsic,
it is not locked between calls. It is therefore possible for
another user to modify the dictionary between calls, and while
this doesn't cause any loss of overall dictionary integrity, the
first user may get inaccurate data. Therefore, a second locking
mode is provided, which can eliminate this problem.
2. Manual Locking : This mode is accomplished by calling the
intrinsic SDLock before calling a multiple-call intrinsic or a
process consisting of several intrinsics. SDLock prevents any
dictionary access by another user while the lock is set, thereby
guaranteeing accurate data update or retrieval during
multiple-call or multiple intrinsic operations. When the
operation is complete, the manual lock should be released by
calling the intrinsic SDUnlock.
NOTE Manual locking would serve no real purpose when the dictionary open
mode is Shared Read-Only, Exclusive Update or Exclusive
Customization, as other users cannot produce conflicting updates or
are already denied access to the dictionary. Therefore, use of the
intrinsic SDLock is allowed only in Shared Read and Shared Update
open modes.
WARNING In MPE V and MPE XL, the following situation could result in a
deadlock: Open and lock a dictionary and then attempt to open
the same dictionary from the same process. If the calling
program has been linked with MR capability, the second open will
cause a deadlock. If the calling program has not been linked
with MR capability, however, the second open will simply return
an error.
In HP-UX, HPIMAGE will automatically "undo" a transaction which
would result in a deadlock and return an error message.
Referencing Intrinsic Names in Programs
When using MPE V. special considerations apply to referencing System
Dictionary intrinsics which have greater than 15 characters. Shown below
are examples of how to handle this problem, one for each of the four
programming languages supported on the HP 3000, using the System
Dictionary intrinsic SDAddAttrEntType.
Pascal (in the Declarations section of the program)
procedure SDAddAttrEntType $alias 'SDAddAttrEntTyp'$; intrinsic;
COBOL (in the procedure division of the program)
CALL INTRINSIC "SDADDATTRENTTYP' USING ...
SPL (no special considerations needed)
FORTRAN (in the declarations section of the program)
System Intrinsic SDAddAttrEntTyp
Accessing a Compiled Dictionary
System Dictionary includes two types of dictionaries which contain
metadata:
* Master Dictionaries. A master dictionary consists of a TurboIMAGE
(MPE V and MPE XL) database which can be accessed by all System
Dictionary intrinsics and SDMAIN commands. Because of its
complexity, however, the response time while using a master
dictionary may be a problem for some subsystems, especially those
which must read from the dictionary at run-time.
* Compiled Dictionaries. A compiled dictionary contains metadata
extracted from a master dictionary. Like a compiled program, a
compiled dictionary cannot be modified. It is therefore a read-only
dictionary which can be accessed by those System Dictionary
intrinsics and SDMAIN commands which only read dictionary metadata.
Compiled dictionaries provide faster dictionary read access and are
intended to be used by subsystems and applications that need only to read
the metadata. A compiled dictionary is less complex than a master
dictionary and is compacted into one or more flat files. It therefore
requires less disk storage space, and provides a more efficient means of
transporting dictionary data to other groups, accounts, or systems.
Once a compiled dictionary has been generated from a master dictionary,
it is considered completely independent of that master dictionary. In
other words, there is no need for the master dictionary to be present in
order to access a compiled dictionary.
Intrinsics Used With Compiled Dictionaries. The subset of System
Dictionary intrinsics listed below can be used to access a compiled
dictionary.
SDOpen SDGetAttr
SDClose SDGetAttrList
SDSwitchDomain SDGetEntType
SDSwitchNameMode SDGetEntTypeAttrList
SDSwitchScope SDGetEntTypeList
SDSwitchVersion SDGetRelClass
SDLock SDGetRelClassList
SDUnlock SDGetRelType
SDError SDGetRelTypeAttrList
SDFindRelList SDGetRelTypeList
SDGetAliasEntList SDGetDomain
SDGetAliasRelList SDGetDomainList
SDGetEnt SDGetDomainScopeList
SDGetEntList SDGetEntScope
SDGetEntVarAttr SDGetEntScopeList
SDGetPrimaryName SDGetRelScope
SDGetSynonymList SDGetRelScopeList
SDGetRel SDGetScope
SDGetRelList SDGetScopeList
SDGetRelVarAttr SDGetStatusVersionList
SDGetVersion
SDGetVersionList
Any of the System Dictionary intrinsics not listed above that are called
while accessing a compiled dictionary will return System Dictionary error
number 75:
Intrinsic cannot be performed on a compiled dictionary
(SDERR 75)