I'm submitting this case on behalf of Alan Maguire. We're submitting
this as self-reviewed as we believe the change is obvious and it has
received review and discussion through the SMF community. The binding
is Patch as no incompatible changes are introduced (though there are no
current backport plans), and the interfaces remain Committed.
If there are concerns, please let us know.
liane
---
Template Version: @(#)onepager.txt 1.35 07/11/07 SMI
Copyright 2007 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
SMF property value ordering
1.2. Name of Document Author/Supplier:
Alan Maguire
1.3. Date of This Document:
07/07/08
4. Technical Description:
4.1. Details:
Proposed is an SMF interface change associated with the fix for
"6715372 SMF repository should store (and allow retrieval of) property
values in the order they were added"
Prior to this, SMF made no commitments with regard to ordering of
multiple values associated with properties. Addressing this RFE will
change interface behaviour such that SMF tools will store and retrieve
such values in the order in which they were added, whether via SMF
manifest import or property value modification via svccfg/libscf.
This will be achieved by upgrading the SMF repository schema to
store additional value ordering information.
Preserving value ordering in this manner means that the current
workaround for order-sensitive multi-valued properties - place them
all in a single string value with a value delimiter separating
individual values - is no longer needed.
4.2. Bug/RFE Number(s):
6715372 SMF repository should store (and allow retrieval of) property
values in the order they were added
4.3. In Scope:
Upgrade of repository format and associated svc* tools to honour value
ordering.
4.5. Interfaces:
All interfaces which deal with SMF property values are modified, since
their previous behaviour with respect to value ordering was unspecified.
Now svccfg (1M), scf_entry_add_value (3SCF) and
scf_iter_property_values(3SCF) respect the value ordering specified by
the interface user.
No new interfaces are imported or exported. Interface stability will
be Committed.
4.6. Doc Impact:
svccfg(1M) diffs:
...
addpropvalue pg/name [type:] value
Adds the given value to a property. If type is given and
the property exists, then if type does not agree with
the property's type, the subcommand fails. The values
may be enclosed in double-quotes. String values con-
taining double-quotes or backslashes must be enclosed by
double-quotes and the contained double-quotes and
backslashes must be quoted by backslashes. Nonexistent
properties are created, in which case the type specifier
must be present. See scf_value_create(3SCF) for a list
of available property types. See smf_security(5) for the
- privileges required to modify properties.
+ privileges required to modify properties. The new value
+ will be appended to the end of the list of property values
+ associated with the property.
...
setprop pg/name = [type:] value
setprop pg/name = [type:] ([values ...])
Sets the name property of the pg property group of the
current selection to the given values of type type. See
scf_value_create(3SCF) for a list of available property
types. If the property already exists and the type
disagrees with the existing type on the property, the
subcommand fails. Values may be enclosed in double-
quotes. String values which contain double-quotes or
backslashes must be enclosed by double-quotes and the
contained double-quotes and backslashes must be quoted
by backslashes. If the named property does not exist, it
is created, as long as the type is specified. See
smf_security(5) for the privileges required to create or
- modify properties.
+ modify properties. Multiple values will be stored in the order in
+ which they are specified.
scf_entry_create(3SCF) diffs:
DESCRIPTION
The scf_entry_create() function allocates a new transaction
entry handle. The scf_entry_destroy() function destroys the
transaction entry handle.
The scf_entry_handle() function retrieves the handle associ-
ated with entry.
A transaction entry represents a single action on a property
in a property group. If an entry is added to a transaction
using scf_transaction_property_new(3SCF),
scf_transaction_property_change(3SCF), or
scf_transaction_property_change_type(3SCF),
scf_entry_add_value() can be called zero or more times to
set up the set of values for that property. Each value must
be set and of a compatible type to the type associated with
the entry. When later retrieved from the property, the
- values will have the type of the entry.
+ values will have the type of the entry. If the values are committed
+ successfully via scf_transacton_commit(3SCF), they will
+ be set in the order in which they were added via
+ scf_entry_add_value().
scf_iter_create(3SCF):
DESCRIPTION
The scf_iter_create() function creates a new iterator asso-
ciated with handle. The scf_iter_destroy() function destroys
an iteration.
The scf_iter_reset() function releases any resources
involved with an active iteration and returns the iterator
to its initial state.
The scf_iter_handle_scopes(), scf_iter_scope_services(),
scf_iter_service_instances(), scf_iter_instance_snapshots(),
scf_iter_service_pgs(), scf_iter_instance_pgs(),
scf_iter_snaplevel_pgs(), scf_iter_pg_properties(), and
scf_iter_property_values() functions set up a new iteration
- of all the children of parent of a particular type.
+ of all the children of parent of a particular type.
+ scf_iter_property_values() + will iterate over values in the order
+ in which they were specified via scf_entry_add_value(3SCF).
4.7. Admin/Config Impact:
Users of SMF will be able to set/retrieve property values in a definite
order.
5. Reference Documents:
Design discussion at:
http://www.opensolaris.org/jive/thread.jspa?threadID=63250&tstart=15
6. Resources and Schedule:
6.1. Projected Availability:
Immediate
6.2. Cost of Effort:
N/A
6.3. Cost of Capital Resources:
N/A
6.4. Product Approval Committee requested information:
6.4.1. Consolidation or Component Name:
ON
6.4.3. Type of CPT Review and Approval expected:
Self-review
6.4.7. Target RTI Date/Release:
SNV100
6.4.8. Target Code Design Review Date:
Done
6.4.9. Update approval addition:
No
6.5. ARC review type:
SelfReview
6.6. ARC Exposure:
open
