Multics Technical Bulletin MTB-551, Revision 1
DM: collection_manager_ Functional Spec
To: Distribution
From: Matthew Pierret and Lindsey Spratt
Date: 06/04/84
Subject: Data Management: Collection Manager Functional Specification.
1 ABSTRACT
This document describes the interface to the collection manager.
As defined in the Data Management Architecture, modules in the
External Access Layer use the collection manager to manage
storage of elements of data. The index and record managers use
the collection manager to store and retrieve keys and records in
Data Management files. The interface to the collection manager
is externally available, so system programs and applications can
also use the collection manager.
The first revision includes the addition of new entry points in
collection_manager_, the re-naming of many entry points to have
names more descriptive of their function, new versions of input
structures, the re-ordering of parameters in some calling
sequences for consistency, and a general reorganization of the
documentation. The entry points are now presented in
alphabetical order.
Comments should be sent to the author:
via Forum:
>udd>m>lls>mtgs>DMS_Development.
via Multics Mail:
Pierret.Multics on either MIT Multics or System M.
via telephone:
(HVN) 261-9338 or (617) 492-9338
_________________________________________________________________
Multics project internal working documentation. Not to be
reproduced or distributed outside the Multics project without the
consent of the author or the author's management.
CONTENTS
Page
1 Abstract . . . . . . . . . . . . . . i
2 Introduction . . . . . . . . . . . . 1
3 Element storage management . . . . . 1
3.1 Basic Element Storage Method . 2
3.2 Ordered Element Storage Method 2
4 Control interval storage management 2
4.1 Unblocked control interval
storage method . . . . . . . . . . 3
4.2 Blocked control interval
storage method . . . . . . . . . . 3
5 Alternative access methods . . . . . 3
5.1 Direct access method . . . . . 4
5.2 Buffered access method . . . . 4
6 Significant changes contained in
revision 1 . . . . . . . . . . . . . 5
7 Description of the operations . . . 6
collection_manager_ . . . . . . . . 8
$allocate_control_interval . . . 9
$compact_control_interval . . . 10
$create_collection . . . . . . . 11
The The unblocked_cism_info
structure structure . . . . 12
The The blocked_cism_info
structure structure . . . . 12
The The basic_esm_info
structure structure . . . . 13
The The ordered_esm_info
structure structure . . . . 13
$create_file . . . . . . . . . . 15
The The file_create_info
structure structure . . . . 15
$delete . . . . . . . . . . . . 18
$delete_from_ci_buffer . . . . . 19
$destroy_collection . . . . . . 20
$free_control_interval . . . . . 21
$get . . . . . . . . . . . . . . 22
$get_control_interval_ptr . . . 24
$get_by_ci_ptr . . . . . . . . . 25
$get_from_ci_buffer . . . . . . 27
$get_header . . . . . . . . . . 29
$get_id . . . . . . . . . . . . 31
CONTENTS (cont)
Page
$get_portion . . . . . . . . . . 33
$get_portion_by_ci_ptr . . . . . 36
$get_portion_from_ci_buffer . . 39
$modify . . . . . . . . . . . . 42
$modify_in_ci_buffer . . . . . . 44
$modify_portion . . . . . . . . 46
$modify_unprotected . . . . . . 48
$put . . . . . . . . . . . . . . 50
$put_header . . . . . . . . . . 52
$put_in_ci_buffer . . . . . . . 53
$put_unprotected_header . . . . 55
$replace_ci_buffer . . . . . . . 56
$setup_ci_buffer . . . . . . . . 57
$simple_get_by_ci_ptr . . . . . 59
$simple_get_from_ci_buffer . . . 61
Multics Technical Bulletin MTB-551, Revision 1
DM: collection_manager_ Functional Spec
2 INTRODUCTION
The major service provided by the collection manager is the
organization of elements of data into collections and stored in
Data Management files. Elements are simply bit strings as far as
the collection manager is concerned, but the caller may view them
as keys or records of any type. The index, record and relation
managers use the collection manager to store keys, records and
header structures.
A collection is logically a set of elements of data provided by
the caller, and physically the set of page-sized control
intervals used to store the elements in a file. A collection
must be wholly contained in a single file, but several
collections can co-exist in the same file. The collection
manager keeps collections distinct and does not allow elements or
control intervals to be shared among collections. The ability to
keep distinct collections in one file allows for creating
entities made up of different kinds of objects. For example, a
MRDS relation is a single file consisting of a record collection
and a number of index collections.
The collection manager centralizes storage management functions
for External Access Layer modules, which may include applications
and system programs, but allows for different flavors of storage
management. The collection manager supports two methods of
managing element storage and two methods of managing control
interval storage.
3 ELEMENT STORAGE MANAGEMENT
The collection manager manages the storage of caller supplied
elements of data in collections. An element is a bit string of
arbitrary length with a 36-bit identifier unique to the
collection. The services of element storage management provided
by the collection manager are the allocation of space for new
elements and the insertion of element contents in that space, the
deletion of element contents and freeing of the space it
occupied, re-writing the contents of elements and retrieving all
or part of an element's contents.
An element is not necessarily stored as a single bit string.
Large elements may have to be split across control intervals and
elements which "grow" when being re-written may have to be
divided into fragments stored discontiguously. These
machinations are invisible to the caller. The collection manager
always receives from and returns to the caller a single
MTB-551, Revision 1 Multics Technical Bulletin
DM: collection_manager_ Functional Spec
undifferentiated bit string.
The collection manager supports two methods of element storage,
the Basic and Ordered Element Storage Methods.
3.1 Basic Element Storage Method
The Basic Element Storage Method (BESM) provides two major
services: permanent element identifiers and ease of maintenance.
The collection manager assigns an identifier to each element
which remains unchanged until the element is deleted. When
storing an element in a BESM collection, the collection manager
does not require the caller to supply the location to store the
element; it looks until it finds free space or creates free
space. The caller is not required to have any knowledge of
control intervals and need not keep track of the movements of
elements. The caller may, however, specify the control interval
where the collection manager should begin looking for free space
by giving the element identifier of an element in the control
interval. The record manager is the primary user of BESM
collections.
3.2 Ordered Element Storage Method
The primary feature of the Ordered Element Storage Method (OESM)
is that the caller specifies where elements should be allocated,
and other elements are shifted to make room for it. Element
identifiers are changed whenever an element is shifted in this
manner. The collection manager makes no attempt to find space
for elements other than in the control interval specified when
storing an element, so the caller must be prepared to go to other
control intervals to find space. Obviously, this requires the
caller to be aware of the control interval orientation of
operations and to make some effort at keeping track of where
elements are in the collection. The fact that activity is
limited to a single control interval at a time allows callers to
make use of control intervals as objects. The primary user of
OESM collections, the index manager, uses control intervals as
nodes in an index.
4 CONTROL INTERVAL STORAGE MANAGEMENT
The collection manager manages the storage of control intervals
in two ways. First, it reserves control intervals to a
particular collection, selecting the control intervals from a
pool available to all collections in a file, and releases control
intervals back into the file free pool. Secondly, it allocates
Multics Technical Bulletin MTB-551, Revision 1
DM: collection_manager_ Functional Spec
reserved control intervals for a collection from the collection's
pool of reserved control intervals, and frees control intervals
back into that pool. This two layer approach allows for the
distinction between control intervals which have been assigned to
a collection and are currently being used, and those which have
been assigned to a collection but are not in use. The collection
manager supports two methods of storage management of control
intervals for a collection called the Unblocked and Blocked
Control Interval Storage Methods.
4.1 Unblocked control interval storage method
The Unblocked Control Interval Storage Method (UCISM) reserves
and allocates control intervals one at a time. Collections do
not reserve control intervals that they are not using, thereby
allowing other collections the opportunity of using them.
Control intervals are organized as a collection by doubly
threading the control intervals chronologically.
4.2 Blocked control interval storage method
The Blocked Control Interval Storage Method (BCISM) reserves
control intervals for a collection in blocks. As long as a
collection is using any control intervals of the block, it keeps
all of the control intervals in the block reserved. Most
allocations are faster than with UCISM because the control
intervals are usually already reserved. The trade-off is the
expense of tying up all of the reserved but un-used control
intervals. Control intervals are organized as a collection by
means of a collection allocation map.
5 ALTERNATIVE ACCESS METHODS |
Normally the collection manager accesses data in a file by |
calling the file manager. There is a non-trivial amount of |
overhead associated with accessing a control interval in a file |
which need not be repeated on subsequent accesses. The |
collection manager does not keep track of what control intervals |
it has accessed, so the overhead is repeated every time a control |
interval is accessed. |
Under some circumstances, the caller knows before-hand that |
several elements in the same control interval will be accessed. |
The caller can take advantage of one of two alternative access |
methods which exploit the fact that the elements are in the same |
control interval and avoid repeating the overhead associated with |
MTB-551, Revision 1 Multics Technical Bulletin
DM: collection_manager_ Functional Spec
| accessing a control interval. The two methods are the direct and
| buffered access methods.
| 5.1 Direct access method
| The direct access method can enhance the performance of
| retrievals of several elements in the same control interval. The
| caller first gets a pointer to the control interval in the file
| using the get_control_interval_ptr operation. All of the file
| manager overhead of accessing the control interval occurs once in
| this operation. Subsequently, the caller can retrieve elements
| from this control interval by passing the control interval
| pointer to one of the operations which support the direct access
| method.
| Updating the control interval using the normal access method does
| not conflict with retrieving from the same control interval via
| the direct access method. However, retrieving via the direct
| access method and updating via the buffered access method can
| produce incorrect results if the caller is not extremely careful.
| Operations which support the direct access method are named with
| the suffix _by_ci_ptr.
| 5.2 Buffered access method
| The buffered access method can enhance performance and reduce on
| storage space used to journalize updates of several elements in
| the same control interval. Instead of getting a pointer directly
| to the control interval in the file, the caller gets a copy of
| the entire control interval in a caller-supplied buffer using the
| setup_buffered_ci operation. Afterward, the caller can get, put,
| allocate and free elements in this control interval buffer by
| passing a pointer to the control interval buffer to one of the
| operations which support the buffered access method. When the
| caller is finished updating the control interval, the
| replace_buffered_ci operation will copy it back into the file.
| The buffered access method is useful when the caller knows in
| advance that a particular control interval will be accessed
| repeatedly, such as during rotation of keys out of an index node.
| Great care must be taken when using the buffered access method,
| as updates can be lost if the caller accidentally updates the
| file copy of the control interval instead of the buffer.
| The cost of copying the control interval is much greater than
| that of getting a pointer to the control interval, so the direct
| access method is preferred over the buffered access method if
| only retrievals will be done.
Multics Technical Bulletin MTB-551, Revision 1
DM: collection_manager_ Functional Spec
Operations which support the buffered access method are named |
with the suffix _from_ci_buffer or _in_ci_buffer. |
Currently, only OESM collections can use the buffered access |
method. |
6 SIGNIFICANT CHANGES CONTAINED IN REVISION 1 |
The calling sequences to the entry points which modify and put |
elements are changed such that the length/pointer parameter pairs |
are now pointer/length pairs. The latter order is more |
consistent with other entry points and more like other standard |
Multics interfaces. |
The structures taken by the create_collection entry point are |
modified. They now have version strings and align their |
structure elements. |
The following entry points are new: |
compact_control_interval |
get_control_interval_ptr |
get_by_ci_ptr |
get_portion_by_ci_ptr |
get_portion_from_ci_buffer |
get_id |
modify_unprotected |
put_unprotected_header |
simple_get_by_ci_ptr |
simple_get_from_ci_buffer |
Many entry point names have been changed. They are: |
allocate_element changed to put |
allocate_element_buffered => put_in_ci_buffer |
free_element => delete |
free_element_buffered => delete_from_ci_buffer |
get_element => get |
get_element_buffered => get_from_ci_buffer |
get_element_portion => get_portion |
put_element => modify |
put_element_buffered => modify_in_ci_buffer |
put_element_portion => modify_portion |
The descriptions of the structures taken as input to |
$create_collection have been changed to take version strings and |
to align structure elements, and the names of the include files |
in which they are declared have changed. |
MTB-551, Revision 1 Multics Technical Bulletin
DM: collection_manager_ Functional Spec
| 7 DESCRIPTION OF THE OPERATIONS
| The entries in collection_manager_ are described and arranged
| alphabetically for ease in reference. The following is a list of
| the entries arranged by function:
| Creating and deleting files and collections:
| create_file
| create_collection
| destroy_collection
| Operations on control intervals:
| allocate_control_interval
| free_control_interval
| compact_control_interval
| Inserting and deleting elements:
| (By standard access method)
| delete
| put
| (By buffered access method)
| delete_from_ci_buffer
| put_in_ci_buffer
| Modifying elements:
| (By standard access method:)
| modify
| modify_portion
| modify_unprotected
| (By buffered access method:)
| modify_in_ci_buffer
| Retrieving elements:
| (By standard access method:)
| get
| modify_portion
| (By buffered access method:)
| get_from_ci_buffer
| get_portion_from_ci_buffer
| simple_get_from_ci_buffer
| (By direct access method:)
| get_by_ci_ptr
| get_portion_by_ci_ptr
| simple_get_by_ci_ptr
| Operations on caller-defined headers
| get_header
| put_header
| put_unprotected_header
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Set up of access methods: |
get_control_interval_ptr |
setup_buffered_ci |
replace_buffered_ci |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Name: collection_manager_
This facility is used to maintain collections of control
intervals in Data Management files. It centralizes control
interval storage management and element storage management.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$allocate_control_interval
Allocates a control interval in a file. |
Usage
dcl collection_manager_$allocate_control_interval entry (bit
(36) aligned, bit (36) aligned, fixed bin(24)unsigned,
fixed bin (35));
call collection_manager_$allocate_control_interval
(file_opening_id, collection_id,
control_interval_number, code);
where:
file_opening_id (Input)
is the opening id of a file.
collection_id (Input)
is the identifier of the collection for which the
control interval is to be allocated.
control_interval_number (Output)
is the number of the allocated control interval.
code (Output)
is a standard system error code. A code of
dm_error_$collection_not_found indicates that the
specified collection does not exist.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$compact_control_interval
| Given the identifier of a control interval in a file,
| re-arrange the contents of the control interval so as to
| concentrate all of the free space in one contiguous area of the
| control interval. This is necessary at times to recover
| scattered free space and is known as compacting the control
| interval. Normally, compaction is triggered automatically as
| needed, but some applications have the need to explicitly compact
| a control interval on demand.
| Usage
| dcl collection_manager_$compact_control_interval entry
| (bit(36)aligned, fixed bin (24) uns, fixed bin (35));
| call collection_manager_$compact_control_interval
| (file_opening_id, control_interval_number, code);
| where:
| file_opening_id (Input)
| is the opening identifier of the file.
| control_interval_number (Input)
| is the number of the control interval in a file to
| compact.
| code (Output)
| is a standard system error code.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$create_collection
Creates a collection. Basically, this consists of inserting |
a header for the collection in the file and associating an |
identifier with the collection. The control interval and element |
storage methods are specified. Currently, only collections which |
employ the Unblocked Control Interval Method can be created. |
Usage
dcl collection_manager_$create_collection entry (bit (36)
aligned, ptr, ptr, bit (36) aligned, fixed bin (35));
call collection_manager_$create_collection (file_opening_id,
cism_info_ptr, esm_info_ptr, collection_id, code);
where:
file_opening_id (Input)
is the opening_id of the file in which the collection
is to be created.
cism_info_ptr (Input) |
is a pointer to a control interval storage method |
info structure, one of blocked_cism_info and |
unblocked_cism_info, declared in |
dm_cism_info.incl.pl1. This structure describes the |
style of control interval storage management to be |
employed for the collection. |
esm_info_ptr (Input)
is a pointer to an element storage method info |
structure, one of basic_esm_info and |
ordered_esm_info, declared in dm_esm_info.incl.pl1. |
This structure describes the style of element storage |
management to be employed for the collection. |
collection_id (Output)
is the identifier of the collection assigned by
collection_manager_.
code (Output)
is a standard error code. Some possible error codes
are:
dm_error_$unimplemented_esm - The requested element
storage method is not support.
dm_error_$unimplemented_cism - The requested
control interval storage method is not supported.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| The unblocked_cism_info structure
| Following is the structure for the "unblocked" type of control
| interval storage management, declared in dm_cism_info.incl.pl1.
| dcl 1 unblocked_cism_info based (unblocked_cism_info_ptr) aligned,
| 2 version char (8) aligned,
| 2 type fixed bin (17);
| where:
| version
| is the version of the structure and must be equal to
| CISM_INFO_VERSION_1, declared in
| dm_cism_info.incl.pl1.
| type
| is the type of control interval storage method and
| must be equal to
| UNBLOCKED_CONTROL_INTERVAL_STORAGE_METHOD, declared
| in dm_cism_info.incl.pl1.
| The blocked_cism_info structure
| Following is the structure for the "blocked" type of
| control interval storage management, declared in
| dm_cism_info.incl.pl1.
| dcl 1 blocked_cism_info based (blocked_cism_info_ptr) aligned,
| 2 version char (8) aligned,
| 2 type fixed bin (17),
| 2 number_of_control_intervals_per_block
| fixed bin (17);
| where:
| version
| is the version of the structure and must be equal to
| CISM_INFO_VERSION_1, declared in
| dm_cism_info.incl.pl1.
| type
| is the type of control interval storage method and
| must be equal to
| BLOCKED_CONTROL_INTERVAL_STORAGE_METHOD.
| number_of_control_intervals_per_block
| is the number of control intervals to be reserved at
| a time.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
The basic_esm_info structure |
Following is the structure describing the "basic" type of element |
storage management, declared in dm_esm_info.incl.pl1. This |
method is primarily for use by record_manager_ and similar |
applications. |
dcl 1 basic_esm_info based (basic_esm_info_ptr) aligned,|
2 version char (8) aligned, |
2 type fixed bin (17), |
2 flags aligned |
3 threaded bit (1) unal, |
3 fixed_length bit (1) unal, |
3 pad bit (34) unal, |
2 maximum_element_length |
fixed bin (35); |
where: |
version |
is the version of the structure and must be equal to |
ESM_INFO_VERSION_1, declared in dm_esm_info.incl.pl1 |
type |
is the type of element storage management and must be |
equal to BASIC_ELEMENT_STORAGE_METHOD, declared in |
dm_esm_info.incl.pl1. |
flags.threaded |
indicates that the elements are to be maintained as a |
doubly threaded list. (Not yet supported.) |
flags.fixed_length |
indicates that all of the elements are to be the same |
length, as specified in maximum_element_length. |
maximum_element_length |
is the maximum length in bits of variable length |
elements, or the length in bits of fixed length |
elements. If -1, then the maximum size is the |
largest possible element, currently 2**35 bits. |
The ordered_esm_info structure |
Following is the structure describing the "ordered" type of |
element storage management, declared in dm_esm_info.incl.pl1. |
This method is primarily for use by index_manager_ and similar |
applications. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| dcl 1 ordered_esm_info based (ordered_esm_info_ptr) aligned,
| 2 version char (8) aligned,
| 2 type fixed bin (17),
| 2 flags aligned,
| 3 fixed_length bit (1) unal,
| 3 pad bit (35) unal,
| 2 maximum_element_length
| fixed bin (35);
| where:
| version
| is the version of the structure and must be equal to
| ESM_INFO_VERSION_1, declared in dm_esm_info.incl.pl1.
| type
| is the type of element storage management and must be
| equal to ORDERED_ELEMENT_STORAGE_METHOD, declared in
| dm_esm_info.incl.pl1.
| flags.fixed_length
| indicates that all of the elements are to be the same
| length, as specified in maximum_element_length.
| maximum_element_length
| is the maximum length in bits of variable length
| elements, or the length in bits of fixed length
| elements. If -1, then the maximum size is the
| largest possible element, currently 2**35 bits.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$create_file |
Create a file and format the first control interval (control |
interval zero) to prepare it for use by the collection_manager_. |
Usage |
dcl collection_manager_$create_file entry (char (*), char |
(*), ptr, bit (36) aligned, fixed bin (35)); |
call collection_manager_$create_file (file_dir, file_name, |
file_create_info_ptr, file_opening_id, code); |
where: |
file_dir (Input) |
is the pathname of the directory in which to create |
the file. |
file_name (Input) |
is the name of the file. |
file_create_info_ptr (Input) |
is a pointer to a file_create_info structure, or |
null. The file_manager_ expects this structure to |
describe attributes of the file. Defaults are |
applied if the pointer is null. |
file_opening_id (Output) |
is the opening identifier of the file. The file is |
opened in order to format control interval zero. |
code (Output) |
is a standard system error code. |
The file_create_info structure |
Following is the structure used to describe the attributes to |
assign to a file being created. It is declared in |
dm_file_create_info.incl.pl1. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| dcl 1 file_create_info aligned based (file_create_info_ptr),
| 2 version bit (36),
| 2 ci_size_in_bytes fixed bin (35),
| 2 blocking_factor fixed bin,
| 2 protected bit unal,
| 2 no_concurrency bit unal,
| 2 no_rollback bit unal,
| 2 mbz_1 bit (33) unal,
| 2 mbz_2 (30) fixed bin (71);
| where:
| version
| must be set by the caller to
| FILE_CREATE_INFO_VERSION_1. This permits upward
| compatible changes to this structure.
| ci_size_in_bytes
| is the control interval size. Currently the only
| size available is 4096. If this item is zero, a
| default value is used. Currently the default value
| is 4096.
| blocking_factor
| tells the file manager how to allocate disk storage.
| In the current implementation this will be
| interpreted as the number of control intervals to put
| in each segment, and only 64 and 255 will be allowed.
| If this item is zero, a default value is used. The
| current default value is 255.
| protected
| determines whether the file is protected from
| transaction failure and from concurrent access by
| other processes. If the protected bit is on, get,
| put, and allocate operations are permitted only in
| transaction mode. Create and delete operations are
| protected regardless of whether the process is in a
| transaction. If this bit is off, the file is
| unprotected, which means that the file and its
| contents may be damaged by concurrent access or
| transaction failure. An unprotected file may be
| accessed within or without a transaction. Accessing
| a protected file is substantially more expensive than
| accessing an unprotected file.
| no_concurrency
| turns off protection against concurrent access by
| other processes. Concurrency protection is
| implemented by locking each control interval that is
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
accessed. The get operation locks in share mode. |
All other operations lock in exclusive mode. Create |
and delete lock the entire file in exclusive mode. |
Locking is expensive. This bit turns it off if it is |
not needed. If protection is off, this bit is |
ignored. |
no_rollback |
turns off protection against transaction failure. |
Protection against transaction failure is implemented |
by journaling a before image of each modification. |
When a transaction fails, its modifications are |
undone by restoring these before images. Journaling |
is expensive. This bit turns it off if it is not |
needed. If protection is off, this bit is ignored. |
mbz_1, mbz_2 |
must be initialized to zero by the caller. This is |
so that upward compatible changes will be able to |
assume that existing programs put zeros in these |
areas. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$delete
| Deletes an element from a collection. The space which the
| element occupied is immediately made available.
| Usage
| dcl collection_manager_$delete entry (bit (36) aligned, bit
| (36) aligned, bit (36) aligned, bit (1) aligned, fixed
| bin (35));
| call collection_manager_$delete (file_opening_id,
| collection_id, element_id, zero_on_delete, code);
| where:
| file_opening_id (Input)
| is the opening identifier of the file of the
| collection.
| collection_id (Input)
| is the identifier of the collection.
| element_id (Input/Output)
| on input, is the identifier of the element to be
| deleted. If the collection uses the Basic Element
| Storage Method, on output is the identifier of the
| element which immediately followed the now-deleted
| element.
| zero_on_delete (not yet implemented)
if on, indicates that the storage associated with the
deleted element is to be set to zero.
code (Output)
is a standard system error code. Some of the codes
returned are:
dm_error_$collection_not_found - The specified
collection does not exist.
dm_error_$ci_not_in_collection - The specified
control interval does not belong to the specified
collection.
dm_error_$ci_not_allocated - The specified control
interval is not allocated.
dm_error_$misformatted_ci - The specified control
interval is not properly formatted.
dm_error_$no_element - The specified element id
does not correspond to an existing element.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$delete_from_ci_buffer |
Deletes an element from a control interval buffer. The |
element must begin in the supplied control interval. To update |
the file copy of the control interval to reflect this |
modification, use the replace_ci_buffer operation. This |
operation is currently supported only for collections using the |
Ordered Element Storage Method. |
Usage |
dcl collection_manager_$delete_from_ci_buffer entry (ptr, |
bit (36) aligned, bit (36) aligned, bit (36) aligned, |
bit (1) aligned, fixed bin (35)); |
call collection_manager_$delete_from_ci_buffer |
(ci_buffer_ptr, file_opening_id, collection_id, |
element_id, zero_on_delete, code); |
where: |
ci_buffer_ptr (Input) |
is a pointer to a buffer containing a control |
interval set up by the setup_ci_buffer operation. |
file_opening_id (Input) |
is the opening identifier of the file of the |
collection. |
collection_id (Input) |
is the identifier of the collection. |
element_id (Input) |
is the identifier of the element to be deleted. The |
element must begin in the supplied control interval. |
zero_on_delete (not yet implemented) |
if on, indicates that the storage associated with the
deleted element is to be set to zero.
code (Output)
is a standard system error code. Some of the codes
returned are:
dm_error_$collection_not_found - The specified
collection does not exist.
dm_error_$no_element - The element was not found.
dm_error_$ci_not_in_collection - The requested
element is in a control interval which does not
belong to the specified collection.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$destroy_collection
Destroys a collection in a DM file, freeing up the storage
used by the collection. Each control interval of the collection
is freed, as well as all associated header information.
Usage
dcl collection_manager_$destroy_collection entry (bit (36)
aligned, bit (36) aligned, fixed bin (35));
call collection_manager_$destroy_collection
(file_opening_id, collection_id, code);
where:
file_opening_id (Input)
is the opening identifier of the file.
collection_id (Input)
is the identifier of the collection to be destroyed.
code (Output)
is a standard system error code. A value of
dm_error_$collection_not_found indicates that the
specified collection does not exist.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$free_control_interval
Frees a control interval. |
Usage
dcl collection_manager_$free_control_interval entry (bit |
(36) aligned, bit (36) aligned, fixed bin (24) |
unsigned, bit (1) aligned, fixed bin (35)); |
call collection_manager_$free_control_interval |
(file_opening_id, collection_id, |
control_interval_number, zero_on_free, code); |
where:
file_opening_id (Input)
is the opening id of the file.
collection_id (Input)
is the identifier of the collection.
control_interval_number (Input)
is the number of the control interval to be freed.
zero_on_free (not yet implemented) |
if on, indicates that the storage associated with the |
control interval being freed is to be set to zero. |
code (Output)
is a standard system error code. A code of
dm_error_$collection_not_found indicates that the
specified collection does not exist.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$get
| Gets an element from a collection.
| Usage
| dcl collection_manager_$get entry (bit (36) aligned, bit
| (36) aligned, bit (36) aligned, fixed bin (17), ptr,
| fixed bin (35), ptr, bit (1) aligned, ptr, fixed bin
| (35), fixed bin (35));
| call collection_manager_$get (file_opening_id,
| collection_id, element_id, position, buffer_ptr,
| buffer_length, area_ptr, new_buffer_was_allocated,
| element_ptr, element_length, code);
| where:
| file_opening_id (Input)
| is a file opening id.
| collection_id (Input)
| is the identifier of the collection.
| element_id (Input/Output)
| is the identifier of the element to be retrieved. If
| the position argument has a non-zero value,
| element_id is the element from which to position. In
| this case, which is only supported for collections
| using the Basic Element Storage Method, the output
| value of element_id is the identifier of the
| retrieved element.
| position (Input)
| if greater than zero, is the number of elements away
| from the specified element in a forward direction the
| desired element is. If less than zero, its magnitude
| is the number of elements away from the specified
| element in a backward direction the desired element
| is.
| buffer_ptr (Input)
| is a pointer to the caller provided buffer in which
| the element is to be placed. If the value is null, a
| buffer is allocated in the provided area in which to
| return the element. The buffer must be byte-aligned.
| buffer_length (Input)
| is the length of the caller provided buffer in bits.
| If the buffer is longer than an integral number of
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
bytes, the excess bits will not be used. If |
buffer_ptr is null, this is interpreted as 0 whatever |
the supplied value. |
area_ptr (Input) |
is a pointer to an area in which a new buffer will be |
allocated by this routine if the caller-supplied |
buffer is too small to hold the element or if no |
buffer is supplied at all. If the buffer is too |
small or is not supplied and area_ptr is null, no |
data is returned. A new buffer is always allocated |
on an even-word boundary. The area may be of any |
type. |
new_buffer_was_allocated (Output) |
is a flag indicating, if on, the caller-provided |
buffer was not large enough to contain the requested |
portion of the element, and a larger buffer was |
allocated in the area pointed to by area_ptr, above. |
element_ptr (Output) |
is a pointer to the retrieved portion of the |
specified element. This pointer may be the same as |
buffer_ptr if no new buffer was allocated. |
element_length (Output) |
is the length of the retrieved element in bits. |
code (Output) |
is a standard system error code. Some of the codes |
returned are: |
dm_error_$collection_not_found - The specified |
collection does not exist. |
dm_error_$long_return_element - The element length |
is greater than the buffer length and no area was |
supplied in which to allocate a new buffer. |
dm_error_$ci_not_in_collection - The specified |
control interval does not belong to the specified |
collection. |
dm_error_$ci_not_allocated - The specified control |
interval is not allocated. |
dm_error_$misformatted_ci - The specified control |
interval is not properly formatted. |
dm_error_$no_element - The specified element id |
does not correspond to an existing element. |
dm_error_$beginning_of_collection - The requested |
position is before the beginning of the collection. |
dm_error_$end_of_collection - The requested |
position is after the end of the collection. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$get_control_interval_ptr
| Get a pointer directly to the beginning of the addressable
| portion of the specified control interval. Because control
| intervals are readable from the user ring, this pointer can be
| passed to certain get entries to efficiently get an element. The
| returned pointer is not valid across file closings or across
| transactions, and should be used carefully in well contained
| situations.
| Usage
| dcl collection_manager_$get_control_interval_ptr entry (bit
| (36) aligned, bit (36) aligned, fixed bin (24)
| unsigned, ptr, fixed bin (35));
| call collection_manager_$get_control_interval_ptr
| (file_opening_id, collection_id,
| control_interval_number, control_interval_ptr, code);
| where:
| file_opening_id (Input)
| is a file opening id.
| collection_id (Input)
| is the identifier of the collection.
| control_interval_number (Input)
| is the number of the control interval to which a
| pointer is to be returned.
| control_interval_ptr (Output)
| is a pointer to the addressable portion of the
| control interval. If code is equal to zero,
| control_interval_ptr must be non-null.
| code (Output)
| is a standard system error code. If equal to
| dm_error_$ci_not_allocated, the specified control has
| not been allocated in the file.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$get_by_ci_ptr |
Gets an element directly from the file using the supplied |
control interval pointer. The control interval pointer points to |
a control interval in a file and must have been set using the |
get_control_interval_pointer operation. This operation differs |
from the get operation in that it copies data directly from the |
control interval instead of calling file_manager_, and, as such, |
is considerably faster than the get operation. |
The control interval pointer must have been set by the |
get_control_interval_pointer operation. This entry is |
recommended for use in only very well contained situations. |
Usage |
dcl collection_manager_$get_by_ci_ptr entry (ptr, bit (36) |
aligned, bit (36) aligned, bit (36) aligned, ptr, fixed |
bin (35), ptr, bit (1) aligned, ptr, fixed bin (35), |
fixed bin (35)); |
call collection_manager_$get_by_ci_ptr |
(control_interval_ptr, file_opening_id, collection_id, |
element_id, buffer_ptr, buffer_length, area_ptr, |
new_buffer_was_allocated, element_ptr, element_length, |
code); |
where: |
control_interval_ptr (Input) |
is a pointer to a control interval in the file. This |
pointer must have been set by |
collection_manager_$get_control_interval_ptr and must |
not be used across transactions. |
file_opening_id (Input) |
is a file opening id. |
collection_id (Input) |
is the identifier of the collection. |
element_id (Input/Output) |
is the identifier of the element to be retrieved. |
buffer_ptr (Input) |
is a pointer to the caller provided buffer in which |
the element is to be placed. If the value is null, a |
buffer is allocated in the provided area in which to |
return the element. The buffer must be byte-aligned. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| buffer_length (Input)
| is the length of the caller provided buffer in bits.
| If the buffer is longer than an integral number of
| bytes, the excess bits will not be used. If
| buffer_ptr is null, this is interpreted as 0 whatever
| the supplied value.
| area_ptr (Input)
| is a pointer to an area in which a new buffer will be
| allocated by this routine if the caller-supplied
| buffer is too small to hold the element or if no
| buffer is supplied at all. If the buffer is too
| small or is not supplied and area_ptr is null, no
| data is returned. A new buffer is always allocated
| on an even-word boundary. The area may be of any
| type.
| new_buffer_was_allocated (Output)
| is a flag indicating, if on, the caller-provided
| buffer was not large enough to contain the requested
| element, and a larger buffer was allocated in the
| area pointed to by area_ptr, above.
| element_ptr (Output)
| is a pointer to the retrieved element. This pointer
| may be the same as buffer_ptr if no new buffer was
| allocated.
| element_length (Output)
| is the length of the specified element in bits.
| code (Output)
| is a standard system error code. Some of the codes
| returned are:
| dm_error_$collection_not_found - The specified
| collection does not exist.
| dm_error_$long_return_element - The element length
| is greater than the buffer length and no area was
| supplied in which to allocate a new buffer.
dm_error_$no_element - The specified element id
does not correspond to an existing element.
dm_error_$beginning_of_collection - The requested
position is before the beginning of the collection.
dm_error_$end_of_collection - The requested
position is after the end of the collection.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$get_from_ci_buffer |
Gets an element from the supplied control interval buffer. |
The caller must supply a control interval buffer that was |
initialized using the setup_ci_buffer operation. The caller must |
use this operation carefully, lest the file copy is changed, |
leaving the buffered copy inconsistent. This operation is |
currently supported only for collections using the Ordered |
Element Storage Method. |
Usage |
dcl collection_manager_$get_from_ci_buffer entry (ptr, bit |
(36) aligned, bit (36) aligned, bit (36) aligned, ptr, |
fixed bin (35), ptr, bit (1) aligned, ptr, fixed bin |
(35), fixed bin (35)); |
call collection_manager_$get_from_ci_buffer (ci_buffer_ptr, |
file_opening_id, collection_id, element_id, buffer_ptr, |
buffer_length, area_ptr, new_buffer_was_allocated, |
element_ptr, element_length, code); |
where: |
ci_buffer_ptr (Input) |
is a pointer to a control interval buffer set up by |
the setup_ci_buffer operation. |
file_opening_id (Input) |
is a file opening id. |
collection_id (Input) |
is the identifier of the collection. |
element_id (Input/Output) |
is the identifier of the element to be retrieved. |
buffer_ptr (Input) |
is a pointer to the caller provided buffer in which |
the element is to be placed. If the value is null, a |
buffer is allocated in the provided area in which to |
return the element. The buffer must be byte-aligned. |
buffer_length (Input) |
is the length of the caller provided buffer in bits. |
If the buffer is longer than an integral number of |
bytes, the excess bits will not be used. If |
buffer_ptr is null, this is interpreted as 0 whatever |
the supplied value. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| area_ptr (Input)
| is a pointer to an area in which a new buffer will be
| allocated by this routine if the caller-supplied
| buffer is too small to hold the element or if no
| buffer is supplied at all. If the buffer is too
| small or is not supplied and area_ptr is null, no
| data is returned. A new buffer is always allocated
| on an even-word boundary. The area may be of any
| type.
| new_buffer_was_allocated (Output)
| is a flag indicating, if on, the caller-provided
| buffer was not large enough to contain the requested
| element, and a larger buffer was allocated in the
| area pointed to by area_ptr, above.
| element_ptr (Output)
| is a pointer to the retrieved element. This pointer
| may be the same as buffer_ptr if no new buffer was
| allocated.
| element_length (Output)
| is the length of the specified element in bits.
| code (Output)
| is a standard system error code. Some of the codes
| returned are:
| dm_error_$collection_not_found - The specified
| collection does not exist.
| dm_error_$long_return_element - The element length
| is greater than the buffer length and no area was
| supplied in which to allocate a new buffer.
dm_error_$ci_not_in_collection - The specified
control interval does not belong to the specified
collection.
dm_error_$no_element - The specified element id
does not correspond to an existing element.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$get_header
Gets the data in the caller-defined header for a collection.
Usage
dcl collection_manager_$get_header entry (bit (36) aligned,
bit (36) aligned, ptr, fixed bin (17), ptr, bit (1)
aligned, ptr, fixed bin (35), fixed bin (35));
call collection_manager_$get_header (file_opening_id,
collection_id, buffer_ptr, buffer_length, area_ptr,
new_buffer_was_allocated, header_ptr, header_length,
code);
where:
file_opening_id (Input)
is the file opening id.
collection_id (Input)
is the identifier of the collection from which the
header is to be extracted.
buffer_ptr (Input)
is a pointer to a buffer in which the header is
placed. If the header is too long to fit in the
buffer or the buffer_ptr is null, a new buffer will
be allocated in the area pointed to by area_ptr. The
buffer must be byte-aligned.
buffer_length (Input)
is the length of the buffer in bits. If the buffer
is longer than an integral number of bytes, the
excess bits will not be used. If buffer_ptr is null, |
this is interpreted as 0 whatever the supplied value. |
area_ptr (Input) |
is a pointer to an area in which a buffer to hold the |
header may be allocated. A buffer is allocated in |
this area if the caller-provided buffer is too small |
or the buffer_ptr argument is null. If the buffer is |
too small or is not supplied and area_ptr is null, no |
data is returned. A new buffer is always allocated |
on an even-word boundary. The area may be of any |
type. |
new_buffer_was_allocated (Output) |
is a flag which, if on, indicates that a new buffer |
was allocated in the supplied buffer. This only |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| happens when no buffer is supplied or if the supplied
| buffer is too small for the requested data to fit.
| header_ptr (Output)
| is a pointer to the header. If a new buffer was
| allocated, it will not equal the caller-provided
| buffer_ptr.
| header_length (Output)
| is the length of the header placed in the buffer in
| bits.
| code (Output)
| is a standard system error code. Some possible error
| codes are:
| dm_error_$collection_not_found - The specified
| collection does not exist.
| dm_error_$long_return_element - The header length
| is greater than the buffer length and no area was
| supplied in which to allocate a new buffer.
| dm_error_$no_header_record - The collection does
| not have a caller-defined header..
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$get_id |
Gets the identifier of an element which is a specified |
number of elements before or after another element. |
Usage |
dcl collection_manager_$get_id entry (bit (36) aligned, bit |
(36) aligned, bit (36) aligned, fixed bin (17), bit (1) |
aligned, bit (36) aligned, fixed bin (35)); |
call collection_manager_$get_id (file_opening_id, |
collection_id, input_element_id, position_change, |
is_absolute_position, return_element_id, code); |
where: |
file_opening_id (Input) |
is the file opening identifier. |
collection_id (Input) |
is the collection identifier. |
input_element_id (Input) |
is the identifier of the element from which to |
position. |
position_change (Input) |
is the number of elements to position away from the |
input element. If less than zero, the direction of |
the position is backward, i.e., toward the beginning |
of the collection; if greater than zero the direction |
is forward, i.e., toward the end of the collection. |
is_absolute_position (Input) |
is a flag which, if on, indicates that the input |
element identifier should be ignored and the position |
is to start at either the beginning or end of the |
collection. If position_change is less than zero, |
the position starts at the end; if position_change is |
greater than zero, the position starts at the |
beginning. |
return_element_id (Output) |
is the identifier of the element to which was |
positioned. If an error occured, the value is zero. |
code (Output) |
is a standard system error code. Some of the codes |
returned are: |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| dm_error_$collection_not_found - The specified
| collection does not exist.
| dm_error_$no_element - The input element does not
| exist.
| dm_error_$beginning_of_collection - The beginning
| of the collection was reached before completing the
| backward position.
| dm_error_$end_of_collection - The end of the
| collection was reached before completing the
| forward position.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$get_portion |
Gets the value of all or part of an element. This operation |
is currently restricted to portions that start at the head of the |
element. |
Usage |
dcl collection_manager_$get_portion entry (bit (36) aligned, |
bit (36) aligned, bit (36) aligned, fixed bin (17), |
ptr, fixed bin (35), ptr, fixed bin (35), fixed bin |
(35), bit (1) aligned, ptr, fixed bin (35), fixed bin |
(35)); |
call collection_manager_$get_portion (file_opening_id, |
collection_id, element_id, position, buffer_ptr, |
buffer_length, area_ptr, portion_beginning_index, |
portion_length, new_buffer_was_allocated, element_ptr, |
element_length, code); |
where: |
file_opening_id (Input) |
is a file opening id. |
collection_id (Input) |
is the identifier of the collection. |
element_id (Input/Output) |
is the identifier of the element to be retrieved. If |
the position argument has a non-zero value, |
element_id is the element from which to position. In |
this case, which is only supported for collections |
using the Basic Element Storage Method, the output |
value of element_id is the identifier of the |
retrieved element. |
position (Input) |
if greater than zero, is the number of elements away |
from the specified element in a forward direction the |
desired element is. If less than zero, its magnitude |
is the number of elements away from the specified |
element in a backward direction the desired element |
is. |
buffer_ptr (Input) |
is a pointer to the caller provided buffer in which |
the element is to be placed. If the value is null, a |
buffer is allocated in the provided area in which to |
return the element. The buffer must be byte-aligned. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| buffer_length (Input)
| is the length of the caller provided buffer in bits.
| If the buffer is longer than an integral number of
| bytes, the excess bits will not be used. If
| buffer_ptr is null, this is interpreted as 0 whatever
| the supplied value.
| area_ptr (Input)
| is a pointer to an area in which a new buffer will be
| allocated by this routine if the caller-supplied
| buffer is too small to hold the element or if no
| buffer is supplied at all. If the buffer is too
| small or is not supplied and area_ptr is null, no
| data is returned. A new buffer is always allocated
| on an even-word boundary. The area may be of any
| type.
| portion_beginning_index (Input)
| is the index (1-originned) of the first bit of the
| portion of the element which is to be returned to the
| caller. Currently, only a value of 1 is allowed.
| portion_length (Input)
| is the length in bits of the portion of the element
| which is to be returned. A value of -1 means "as
| many bits as required to get to the end of the
| element". If portion_beginning_index is set to 1 and
| portion_length is set to -1, then the entire element
| is returned.
| new_buffer_was_allocated (Output)
| is a flag indicating, if on, the caller-provided
| buffer was not large enough to contain the requested
| portion of the element, and a larger buffer was
| allocated in the area pointed to by area_ptr, above.
| element_ptr (Output)
| is a pointer to the retrieved portion of the
| specified element. This pointer may be the same as
| buffer_ptr if no new buffer was allocated.
| element_length (Output)
| is the length of the retrieved portion of the
| specified element in bits.
| code (Output)
| is a standard system error code. Some of the codes
| returned are:
| dm_error_$collection_not_found - The specified
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
collection does not exist. |
dm_error_$long_return_element - The element length |
is greater than the buffer length and no area was |
supplied in which to allocate a new buffer. |
dm_error_$no_element - The specified element id
does not correspond to an existing element.
dm_error_$beginning_of_collection - The requested
position is before the beginning of the collection.
dm_error_$end_of_collection - The requested
position is after the end of the collection.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$get_portion_by_ci_ptr
| Gets the value of all or part of an element directly from
| the file using the supplied control interval pointer. This
| operation differs from the get_portion operation in that it
| copies data directly from the control interval instead of calling
| file_manager_, and, as such, is considerably faster than the get
| operation.
| Usage
| dcl collection_manager_$get_portion_by_ci_ptr entry (ptr,
| bit (36) aligned, bit (36) aligned, bit (36) aligned,
| fixed bin (17), ptr, fixed bin (35), ptr, fixed bin
| (35), fixed bin (35), bit (1) aligned, ptr, fixed bin
| (35), fixed bin (35));
| call collection_manager_$get_portion_by_ci_ptr
| (control_interval_ptr, file_opening_id, collection_id,
| element_id, position, buffer_ptr, buffer_length,
| area_ptr, portion_beginning_index, portion_length,
| new_buffer_was_allocated, element_ptr, element_length,
| code);
| where:
| control_interval_ptr (Input)
| is a pointer to a control interval in a file. This
| pointer must have been set by
| collection_manager_$get_control_interval_ptr.
| file_opening_id (Input)
| is a file opening id.
| collection_id (Input)
| is the identifier of the collection.
| element_id (Input/Output)
| is the identifier of the element to be retrieved. If
| the position argument has a non-zero value,
| element_id is the element from which to position. In
| this case, which is only supported for collections
| using the Basic Element Storage Method, the output
| value of element_id is the identifier of the
| retrieved element.
| position (Input)
| if greater than zero, is the number of elements away
| from the specified element in a forward direction the
| desired element is. If less than zero, its magnitude
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
is the number of elements away from the specified |
element in a backward direction the desired element |
is. |
buffer_ptr (Input) |
is a pointer to the caller provided buffer in which |
the element is to be placed. If the value is null, a |
buffer is allocated in the provided area in which to |
return the element. The buffer must be byte-aligned. |
buffer_length (Input) |
is the length of the caller provided buffer in bits. |
If the buffer is longer than an integral number of |
bytes, the excess bits will not be used. If |
buffer_ptr is null, this is interpreted as 0 whatever |
the supplied value. |
area_ptr (Input) |
is a pointer to an area in which a new buffer will be |
allocated by this routine if the caller-supplied |
buffer is too small to hold the element or if no |
buffer is supplied at all. If the buffer is too |
small or is not supplied and area_ptr is null, no |
data is returned. A new buffer is always allocated |
on an even-word boundary. The area may be of any |
type. |
portion_beginning_index (Input) |
is the index (1-originned) of the first bit of the |
portion of the element which is to be returned to the |
caller. Currently, only a value of 1 is allowed. |
portion_length (Input) |
is the length in bits of the portion of the element |
which is to be returned. A value of -1 means "as |
many bits as required to get to the end of the |
element". If portion_beginning_index is set to 1 and |
portion_length is set to -1, then the entire element |
is returned. |
new_buffer_was_allocated (Output) |
is a flag indicating, if on, the caller-provided |
buffer was not large enough to contain the requested |
portion of the element, and a larger buffer was |
allocated in the area pointed to by area_ptr, above. |
element_ptr (Output) |
is a pointer to the retrieved portion of the |
specified element. This pointer may be the same as |
buffer_ptr if no new buffer was allocated. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| element_length (Output)
| is the length of the retrieved portion of the
| specified element in bits.
| code (Output)
| is a standard system error code. Some of the codes
| returned are:
| dm_error_$collection_not_found - The specified
| collection does not exist.
| dm_error_$long_return_element - The element length
| is greater than the buffer length and no area was
| supplied in which to allocate a new buffer.
dm_error_$no_element - The specified element id
does not correspond to an existing element.
dm_error_$beginning_of_collection - The requested
position is before the beginning of the collection.
dm_error_$end_of_collection - The requested
position is after the end of the collection.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$get_portion_from_ci_buffer |
Gets the value of all or part of an element from the |
supplied control interval buffer. The caller must supply a |
control interval buffer that was initialized using the |
setup_ci_buffer operation. The caller must use this operation |
carefully, lest the file copy is changed, leaving the buffered |
copy inconsistent. This operation is currently supported only |
for collections using the Ordered Element Storage Method. |
Usage |
dcl collection_manager_$get_portion_from_ci_buffer entry |
(ptr, bit (36) aligned, bit (36) aligned, bit (36) |
aligned, ptr, fixed bin (35), ptr, fixed bin (35), |
fixed bin (35), bit (1) aligned, ptr, fixed bin (35), |
fixed bin (35)); |
call collection_manager_$get_portion_from_ci_buffer |
(ci_buffer_ptr, file_opening_id, collection_id, |
element_id, buffer_ptr, buffer_length, area_ptr, |
portion_beginning_index, portion_length, |
new_buffer_was_allocated, element_ptr, element_length, |
code); |
where: |
ci_buffer_ptr (Input) |
is a pointer to a control interval buffer set up by |
the setup_ci_buffer operation. |
file_opening_id (Input) |
is a file opening id. |
collection_id (Input) |
is the identifier of the collection. |
element_id (Input/Output) |
is the identifier of the element to be retrieved. |
buffer_ptr (Input) |
is a pointer to the caller provided buffer in which |
the element is to be placed. If the value is null, a |
buffer is allocated in the provided area in which to |
return the element. The buffer must be byte-aligned. |
buffer_length (Input) |
is the length of the caller provided buffer in bits. |
If the buffer is longer than an integral number of |
bytes, the excess bits will not be used. If |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| buffer_ptr is null, this is interpreted as 0 whatever
| the supplied value.
| area_ptr (Input)
| is a pointer to an area in which a new buffer will be
| allocated by this routine if the caller-supplied
| buffer is too small to hold the element or if no
| buffer is supplied at all. If the buffer is too
| small or is not supplied and area_ptr is null, no
| data is returned. A new buffer is always allocated
| on an even-word boundary. The area may be of any
| type.
| portion_beginning_index (Input)
| is the index (1-originned) of the first bit of the
| portion of the element which is to be returned to the
| caller. Currently, only a value of 1 is allowed.
| portion_length (Input)
| is the length in bits of the portion of the element
| which is to be returned.
| new_buffer_was_allocated (Output)
| is a flag indicating, if on, the caller-provided
| buffer was not large enough to contain the requested
| portion of the element, and a larger buffer was
| allocated in the area pointed to by area_ptr, above.
| element_ptr (Output)
| is a pointer to the retrieved portion of the
| specified element. This pointer may be the same as
| buffer_ptr if no new buffer was allocated.
| element_length (Output)
| is the length of the retrieved portion of the
| specified element in bits.
| code (Output)
| is a standard system error code. Some of the codes
| returned are:
| dm_error_$collection_not_found - The specified
| collection does not exist.
| dm_error_$long_return_element - The element length
| is greater than the buffer length and no area was
| supplied in which to allocate a new buffer.
| dm_error_$ci_not_in_collection - The requested
| element is in a control interval which does not
| belong to the specified collection.
| error_table_$bad_arg - A bad value was given for
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
the portion_beginning_index (^= 1) or |
portion_length (< 1). |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$modify
| Modifies the value of an existing element.
| Usage
| dcl collection_manager_$modify entry (bit (36) aligned, bit
| (36) aligned, ptr, fixed bin (35), bit (36) aligned,
| fixed bin (35), fixed bin (35));
| call collection_manager_$modify (file_opening_id,
| collection_id, element_ptr, element_length, element_id,
| maximum_space_available, code);
| where:
| file_opening_id (Input)
| is a file opening identifier.
| collection_id (Input)
| is the identifier of the collection.
| element_ptr (Input)
| is a pointer to the value of the element to be
| modified.
| element_length (Input)
| is the length of the element's new value in bits. A
| value of -1 is interpreted as "the current size of
| the existing element".
| element_id (Input)
| is the identifier of the element being modified.
| maximum_space_available (Output)
| if the operation failed because of a lack of space
| (code = dm_error_$long_element), is the amount of
| additional space in bits needed in the control
| interval to successfully modify the element. If the
| operation was successful, is the amount of free space
| in bits remaining in the control interval after the
| modification.
| code (Output)
| is a standard system error code. Some of the codes
| returned are:
| dm_error_$collection_not_found - The specified
| collection does not exist.
| dm_error_$long_element - The element was too long
| to fit in the control interval.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
dm_error_$ci_not_in_collection - The requested |
element is in a control interval which does not |
belong to the specified collection. |
dm_error_$ci_not_allocated - The specified control |
interval is not allocated. |
dm_error_$misformatted_ci - The specified control |
interval is not properly formatted. |
dm_error_$bad_element_length - The specified length |
is invalid (less than 0). |
dm_error_$no_element - The specified element was |
not found. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$modify_in_ci_buffer
| Modify the value of an existing element in a control
| interval buffer. The element begins in the control interval
| supplied by the caller. Only the copy of the control interval in
| the supplied buffer is modified, not the file itself. If the
| element is continued in another control interval, the file copy
| of that control interval is modified. In order to reflect the
| modification in the file copy of the control interval, the copy
| must be replaced with the replace_ci_buffer operation. This
| operation is currently supported only for collections using the
| Ordered Element Storage Method.
| Usage
| dcl collection_manager_$modify_in_ci_buffer entry (ptr, bit
| (36) aligned, bit (36) aligned, ptr, fixed bin (35),
| bit (36) aligned, fixed bin (35), fixed bin (35));
| call collection_manager_$modify_in_ci_buffer (ci_buffer_ptr,
| file_opening_id, collection_id, element_ptr,
| element_length, element_id, maximum_space_available,
| code);
| where:
| ci_buffer_ptr (Input)
| is a pointer to a buffer containing a control
| interval set up by the setup_ci_buffer operation.
| file_opening_id (Input)
| is a file opening identifier.
| collection_id (Input)
| is the identifier of the collection.
| element_ptr (Input)
| is a pointer to the value of the element to be
| modified.
| element_length (Input)
| is the length of the element's new value in bits. A
| value of -1 is interpreted as "the current size of
| the existing element".
| element_id (Input)
| is the identifier of the element being modified.
| maximum_space_available (Output)
| if the operation failed because of a lack of space
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
(code = dm_error_$long_element), is the amount of |
additional space in bits needed in the control |
interval to successfully modify the element. If the |
operation was successful, is the amount of free space |
in bits remaining in the control interval after the |
modification. |
code (Output) |
is a standard system error code. Some of the codes |
returned are: |
dm_error_$collection_not_found - The specified |
collection does not exist. |
dm_error_$long_element - The element was too long |
to fit in the control interval. |
dm_error_$ci_not_in_collection - The requested |
element is in a control interval which does not |
belong to the specified collection. |
dm_error_$bad_element_length - The specified length |
is invalid (less than 0). |
dm_error_$no_element - The specified element was |
not found. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$modify_portion
| Modifies the value of all or part of an element. This entry
| is not yet implemented.
| Usage
| dcl collection_manager_$modify_portion entry (bit (36)
| aligned, bit (36) aligned, fixed bin (35), ptr, fixed
| bin (35), fixed bin (35), bit (36) aligned, fixed bin
| (35), fixed bin (35));
| call collection_manager_$modify_portion (file_opening_id,
| collection_id, beginning_portion_index,
| element_portion_ptr, old_portion_length,
| new_portion_length, element_id,
| maximum_space_available, code);
| where:
| file_opening_id (Input)
| is a file opening identifier.
| collection_id (Input)
| is the identifier of the collection.
| beginning_portion_index (Input)
| is the Nth bit in the element where the first bit of
| the portion will be placed.
| element_portion_ptr (Input)
| is a pointer to the new value of the element portion.
| old_portion_length (Input)
| is the length in bits of the portion of the element
| which is being replaced. A value of -1 means "as
| many bits as it takes to get to the end of the
| element". A value of 0 means that the new portion is
| being inserted.
| new_portion_length (Input)
| is the length in bits of the new portion. A value of
| -1 means "the same size as the old portion". A value
| of zero means that no new data is to be inserted, but
| the data described by old_portion_length is to be
| removed.
| element_id (Input)
| is the identifier of the element to be modified.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
maximum_space_available (Output) |
if the operation failed because of a lack of space |
(code = dm_error_$long_element), is the amount of |
additional space in bits needed in the control |
interval to successfully modify the element. If the |
operation was successful, is the amount of free space |
in bits remaining in the control interval after the |
modification. |
code (Output) |
is a standard system error code. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$modify_unprotected
| Modify the value of an existing element, but do not
| journalize the data or exclusively lock the control interval in
| which the element is stored. This operation can be used only
| when the old and new values are identical in length, and when the
| value can fit in a single control interval. This operation
| should only be used in situations where the caller knows that the
| data is not critical, as the data will not be rolled back.
| Usage
| dcl collection_manager_$modify_unprotected entry (bit (36)
| aligned, bit (36) aligned, ptr, fixed bin (35), bit
| (36) aligned, fixed bin (35), fixed bin (35));
| call collection_manager_$modify_unprotected
| (file_opening_id, collection_id, element_ptr,
| element_length, element_id, maximum_space_available,
| code);
| where:
| file_opening_id (Input)
| is a file opening identifier.
| collection_id (Input)
| is the identifier of the collection.
| element_ptr (Input)
| is a pointer to the value of the element to be
| modified.
| element_length (Input)
| is the length of the element's new value in bits. A
| value of -1 is interpreted as "the current size of
| the existing element". The length must be the same
| as the old length, or -1.
| element_id (Input)
| is the identifier of the element being modified.
| maximum_space_available (Output)
| if the operation failed because of a lack of space
| (code = dm_error_$long_element), is the amount of
| additional space in bits needed in the control
| interval to successfully modify the element. If the
| operation was successful, is the amount of free space
| in bits remaining in the control interval after the
| modification.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
code (Output) |
is a standard system error code. Some of the codes |
returned are: |
dm_error_$collection_not_found - The specified |
collection does not exist. |
dm_error_$ci_not_in_collection - The requested |
element is in a control interval which does not |
belong to the specified collection. |
dm_error_$ci_not_allocated - The specified control |
interval is not allocated. |
dm_error_$misformatted_ci - The specified control |
interval is not properly formatted. |
dm_error_$bad_element_length - The specified length |
is invalid (less than 1). |
dm_error_$no_element - The specified element was |
not found. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$put
| Puts a new element in a collection.
| Usage
| dcl collection_manager_$put entry (bit (36) aligned, bit
| (36) aligned, ptr, fixed bin (35), bit (36) aligned,
| fixed bin (35), fixed bin (35));
| call collection_manager_$put (file_opening_id,
| collection_id, element_ptr, element_length, element_id,
| maximum_space_available, code);
| where:
| file_opening_id (Input)
| is a file opening identifier.
| collection_id (Input)
| is a collection identifier.
| element_ptr (Input)
| is a pointer to the value of the new element.
| element_length (Input)
| is the length of the new element.
| element_id (Input/Output)
| on output is the identifier of the new element. The
| interpretation of this argument on input depends on
| what Element Storage Method the collection uses. For
| an Ordered ESM collection, the input element_id
| identifies the location of the new element. The
| input and output values must be the same. For a
| Basic ESM collection, the input element_id is the
| element_id of a "related" element. The new element
| will be put in the same control interval as the
| related element if there is room; otherwise another
| location will be found. If element_id is "0"b, a
| random location is found.
| maximum_space_available (Output)
| if the operation fails because of a lack of space
| (code = dm_error_$long_element), is the amount of
| additional space in bits necessary to put the element
| in the specified control interval. If the operation
| was successful, is the maximum amount of free space
| in bits available for use in the control interval
| identified by the output value of element_id after
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
the put. |
code (Output) |
is a standard system error code. Some of the codes |
returned are: |
dm_error_$collection_not_found - The specified |
collection does not exist. |
dm_error_$long_element - The element was too long |
to fit in the buffer. |
dm_error_$ci_not_in_collection - The specified |
control interval does not belong to the specified |
collection. |
dm_error_$ci_not_allocated - The specified control |
interval is not allocated. |
dm_error_$misformatted_ci - The specified control |
interval is not properly formatted. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$put_header
| Puts a caller-defined header for a collection. The index
| and record managers keep an index header and a record collection
| header in caller-defined headers. If a header already exists for
| the collection, it is modified. If no header exists for the
| collection, a new one is put.
| Usage
| dcl collection_manager_$put_header entry (bit (36) aligned,
| bit (36) aligned, ptr, fixed bin (35), fixed bin (35));
| call collection_manager_$put_header (file_opening_id,
| collection_id, header_ptr, header_length, code);
| where:
| file_opening_id (Input)
| is the opening id of the file of the collection.
| collection_id (Input)
| is the identifier of the collection.
| header_ptr (Input)
| is a pointer to the data to be placed in the header
| of the collection.
| header_length (Input)
| is the length of the header data being put, in bits.
| code (Output)
| is a standard system error code. A value of
| dm_error_$collection_not_found indicates that the
| specified collection does not exist.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$put_in_ci_buffer |
Puts an element in the supplied control interval buffer. To |
update the file copy of the control interval to reflect this |
modification, use the replace_ci_buffer operation. This |
operation is currently supported only for collections using the |
Ordered Element Storage Method. |
Usage |
dcl collection_manager_$put_in_ci_buffer entry (ptr, bit |
(36) aligned, bit (36) aligned, ptr, fixed bin (35), |
bit (36) aligned, fixed bin (35), fixed bin (35)); |
call collection_manager_$put_in_ci_buffer (ci_buffer_ptr, |
file_opening_id, collection_id, element_ptr, |
element_length, element_id, maximum_space_available, |
code); |
where: |
ci_buffer_ptr (Input) |
is a pointer to a buffer containing a control |
interval set up by the setup_ci_buffer operation. |
file_opening_id (Input) |
is a file opening identifier. |
collection_id (Input) |
is a collection identifier. |
element_ptr (Input) |
is a pointer to the value of the new element. |
element_length (Input) |
is the length of the new element. |
element_id (Input) |
is the identifier and location of the new element. |
maximum_space_available (Output) |
if the operation fails because of a lack of space |
(code = dm_error_$long_element), is the amount of |
additional space in bits necessary to put the element |
in the specified control interval. If the operation |
was successful, is the maximum amount of free space |
in bits available for use in the control interval |
identified by the output value of element_id after |
the put. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| code (Output)
| is a standard system error code. Some of the codes
| returned are:
| dm_error_$collection_not_found - The specified
| collection does not exist.
| dm_error_$long_element - The element was too long
| to fit in the control interval.
| dm_error_$ci_not_in_collection - The requested
| element is in a control interval which does not
| belong to the specified collection.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$put_unprotected_header |
Puts a new or modifies an existing caller-defined header for |
a collection in an area of the file reserved for such headers. |
The index and record managers keep an index header and a record |
collection header in caller-defined headers. If the header does |
not already exist, it is put in the file. If the header already |
exists, the existing value is modified without journalizing the |
old value or exclusively locking the control interval in which |
the header resides. The caller should only use this operation if |
the changed data is not critical, as it will not be rolled back. |
The new length of the header value must be the same as the old |
length. |
Usage |
dcl collection_manager_$put_unprotected_header entry (bit |
(36) aligned, bit (36) aligned, ptr, fixed bin (35), |
fixed bin (35)); |
call collection_manager_$put_unprotected_header |
(file_opening_id, collection_id, header_ptr, |
header_length, code); |
where: |
file_opening_id (Input) |
is the opening id of the file of the collection. |
collection_id (Input) |
is the identifier of the collection. |
header_ptr (Input) |
is a pointer to the data to be placed in the header |
of the collection. |
header_length (Input) |
is the length of the header data being put, in bits. |
If the header already exists, this length must be |
identical to the length of the existing header's |
value. |
code (Output) |
is a standard system error code. A value of |
dm_error_$collection_not_found indicates that the |
specified collection does not exist. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| Entry: collection_manager_$replace_ci_buffer
| Copies the contents of a control interval buffer back into a
| file. The control interval buffer must have previously been set
| up by the setup_ci_buffer operation.
| Usage
| dcl collection_manager_$replace_ci_buffer entry (bit (36)
| aligned, bit (36) aligned, fixed bin (24) unsigned,
| ptr, fixed bin (35), fixed bin (35));
| call collection_manager_$replace_ci_buffer (file_opening_id,
| collection_id, control_interval_number, ci_buffer_ptr,
| ci_buffer_length, code);
| where:
| file_opening_id (Input)
| is a file opening identifier.
| collection_id (Input)
| is a collection identifier.
| control_interval_number (Input)
| is the number of the control interval to be replaced.
| ci_buffer_ptr (Input)
| is the pointer to the buffer holding the control
| interval.
| ci_buffer_length (Input)
| is the length in bits of the supplied buffer. The
| value must be greater than or equal to
| CONTROL_INTERVAL_ADDRESSABLE_LENGTH_IN_BITS, declared
| in dm_ci_lengths.incl.pl1.
| code (Output)
| is a standard system error code. Some of the codes
| returned are:
| dm_error_$collection_not_found - The specified
| collection does not exist.
| dm_error_$ci_not_in_collection - The requested
| element is in a control interval which does not
| belong to the specified collection.
| dm_error_$short_buffer - The buffer is not large
| enough to contain a control interval.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$setup_ci_buffer |
Copies the entire addressable contents of a control interval |
into a caller-supplied buffer. The caller may supply the pointer |
to this buffer to later invocations of buffered operations. For |
certain well contained situations, repeatedly accessing control |
interval in a buffer rather than in a file will save on overhead |
costs. The caller must be careful when using buffered control |
intervals to not accidentally access the control interval |
directly in the file, or updates may be lost. |
Usage |
dcl collection_manager_$setup_ci_buffer entry (bit (36) |
aligned, bit (36) aligned, fixed bin (24) unsigned, |
ptr, fixed bin (35), fixed bin (35)); |
call collection_manager_$setup_ci_buffer (file_opening_id, |
collection_id, control_interval_number, ci_buffer_ptr, |
ci_buffer_length, code); |
where: |
file_opening_id (Input) |
is a file opening identifier. |
collection_id (Input) |
is a collection identifier. |
control_interval_number (Input) |
is the number of the control interval to be set up. |
ci_buffer_ptr (Input) |
is the pointer to the buffer to hold the control |
interval. |
ci_buffer_length (Input) |
is the length in bits of the supplied buffer. The |
value must be greater than or equal to |
CONTROL_INTERVAL_ADDRESSABLE_LENGTH_IN_BITS, declared |
in dm_ci_lengths.incl.pl1. |
code (Output) |
is a standard system error code. Some of the codes |
returned are: |
dm_error_$collection_not_found - The specified |
collection does not exist. |
dm_error_$ci_not_in_collection - The requested |
element is in a control interval which does not |
belong to the specified collection. |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| dm_error_$ci_not_allocated - The specified control
| interval is not allocated.
| dm_error_$misformatted_ci - The specified control
| interval is not properly formatted.
| dm_error_$ci_contains_continuations - The control
| interval contains at a datum which is the
| continuation of an element started in another
| control interval. This is not allowed, as the
| caller has no control over when these get accessed,
| and updates can be lost.
| dm_error_$short_buffer - The buffer is not large
| enough to contain a control interval.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$simple_get_by_ci_ptr |
Get an element using the supplied control interval pointer |
to speed up the retrieval. This entry is not as general as other |
entries which get elements in order to make the entry as simple |
and efficient as possible. One of the simplifying restrictions |
is that the element must be completely contained within the |
control interval. The control interval pointer must have been |
set using the $get_control_interval_pointer operation. This |
entry is recommended for use in only very well contained |
situations. |
Usage |
dcl collection_manager_$simple_get_by_ci_ptr entry (ptr, |
bit(36)aligned, bit(36)aligned, ptr, fixed bin(35), |
fixed bin (35), fixed bin (35)); |
call collection_manager_$simple_get_by_ci_ptr |
(control_interval_ptr, collection_id, element_id, |
buffer_ptr, buffer_length, element_length, code); |
where: |
control_interval_ptr (Input) |
points to a control interval in the file. This |
pointer must have been set by |
collection_manager_$get_control_interval_pointer. |
collection_id (Input) |
is the identifier of the collection. If |
collection_id does not equal the collection id stored |
in the buffered control interval, an error results. |
element_id (Input) |
is the identifier of the element to retrieve. |
buffer_ptr (Input) |
points to a caller-supplied buffer in which to place |
the element, and also points to the retrieved |
element. The value remains the same. |
buffer_length (Input) |
is the length in bits of the buffer. |
element_length (Output) |
is the length in bits of the element. |
code (Output) |
is a standard system error code. The possible values |
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
| are:
| dm_error_$ci_not_in_collection - the supplied
| control interval is not in the supplied
| collection.
| dm_error_$long_return_element - the element is
| longer than the buffer.
| dm_error_$no_element - there is no element in the
| control interval with the same identifier
| as element_id.
___________________ ___________________
collection_manager_ collection_manager_
___________________ ___________________
Entry: collection_manager_$simple_get_from_ci_buffer |
Get an element from the supplied control interval buffer. |
This entry is not as general as other entries which get elements |
in order to make the entry as simple and efficient as possible. |
One of the simplifying restrictions is that the element must be |
completely contained within the control interval. The caller |
must supply a control interval buffer that was initialized using |
the setup_ci_buffer operation. The caller must use this |
operation carefully, lest the file copy is changed, leaving the |
buffered copy inconsistent. This operation is currently |
supported only for collections using the Ordered Element Storage |
Method. |
Usage |
dcl collection_manager_$simple_get_from_ci_buffer entry |
(ptr, bit(36)aligned, bit(36)aligned, ptr, fixed |
bin(35), fixed bin (35), fixed bin (35)); |
call collection_manager_$simple_get_from_ci_buffer |
(ci_buffer_ptr, collection_id, element_id, buffer_ptr, |
buffer_length, element_length, code); |
where: |
ci_buffer_ptr (Input) |
points to a control interval buffer initialized via |
the setup_ci_buffer operation. |
collection_id (Input) |
is the identifier of the collection. If |
collection_id does not equal the collection id stored |
in the buffered control interval, an error results. |
element_id (Input) |
is the identifier of the element to retrieve. |
buffer_ptr (Input) |
points to a caller-supplied buffer in which to place |
the element, and also points to the retrieved |
element. The value remains the same. |
buffer_length (Input) |
is the length in bits of the buffer. |
element_length (Output) |
is the length in bits of the element. |
code (Output) |
| is a standard system error code. The possible values
| are:
| dm_error_$ci_not_in_collection - the supplied
| control interval is not in the supplied
| collection.
| dm_error_$long_return_element - the element is
| longer than the buffer.
| dm_error_$no_element - there is no element in the
| control interval with the same identifier
| as element_id.