'\" te
.\" CDDL HEADER START
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").  
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at CDDL.txt
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at CDDL.txt.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" CDDL HEADER END
.\" Copyright 2008 Sun Microsystems, Inc.  All
.\" rights reserved. Use is subject to license terms.
.TH scds_get_ext_property 3HA "13 Aug 2008" "Sun Cluster 3.2" "Sun Cluster HA and Data Services"
.SH NAME
scds_get_ext_property \- retrieve an extension
property
.SH SYNOPSIS
.LP
.nf
cc [\fIflags\fR\&.\|.\|.] \fB-I\fR /usr/cluster/include \fIfile\fR \fB-L\fR /usr/cluster/lib \fB -l \fR dsdev
#include <rgm/libdsdev.h>

\fBscha_err_t\fR \fB scds_get_ext_property\fR(\fBscds_handle_t\fR \fIhandle\fR, \fBconst char *\fR\fIproperty_name\fR,
    \fBscha_prop_type_t\fR \fI property_type\fR, \fBscha_extprop_value_t **\fR\fIproperty_value\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBscds_get_ext_property()\fR function retrieves the
value of a given extension property. 
.sp
.LP
The name of the property is first looked up in the list of properties
specified in the method argument list ( \fBargv[]\fR, which was
parsed by \fBscds_initialize()\fR). If the property name is not
in the method argument list, it is retrieved using the Sun Cluster API. See \fBscha_calls\fR(3HA).
.sp
.LP
Upon successful completion, the value of the property is placed in the
appropriate variable in the union in a \fBscha_extprop_value_t\fR structure
and a pointer to this structure is passed back to the caller in \fIproperty_value\fR.
.sp
.LP
You are responsible for freeing memory by using \fBscds_free_ext_property()\fR.
.sp
.LP
You can find information about the data types \fBscha_prop_type_t\fR and \fBscha_extprop_value_t\fR in \fBscha_calls\fR(3HA) and in the \fBscha_types.h\fR header
file.
.sp
.LP
DSDL provides convenience functions to retrieve the values of some of
the more commonly used resource extension properties. See the \fBscds_property_functions\fR(3HA) man page.
.SH PARAMETERS
.sp
.LP
The following parameters are supported:
.sp
.ne 2
.mk
.na
\fB\fIhandle\fR\fR
.ad
.RS 20n
.rt  
The handle returned from \fBscds_initialize\fR(3HA)
.RE

.sp
.ne 2
.mk
.na
\fB\fIproperty_name\fR\fR
.ad
.RS 20n
.rt  
Name of the property being retrieved
.RE

.sp
.ne 2
.mk
.na
\fB\fIproperty_type\fR\fR
.ad
.RS 20n
.rt  
Property value type. Valid types are defined in \fBscha_calls\fR(3HA) and \fBproperty_attributes\fR(5).
.RE

.sp
.ne 2
.mk
.na
\fB\fIproperty_value\fR\fR
.ad
.RS 20n
.rt  
Pointer to a property value
.RE

.SH RETURN VALUES
.sp
.LP
The \fBscds_get_ext_property()\fR function returns the
following values:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 20n
.rt  
The function succeeded.
.RE

.sp
.ne 2
.mk
.na
\fBnonzero\fR
.ad
.RS 20n
.rt  
The function failed.
.RE

.SH ERRORS
.sp
.ne 2
.mk
.na
\fB\fBSCHA_ERR_PROP\fR\fR
.ad
.RS 20n
.rt  
RTR file does not define the specified property.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCHA_ERR_NOERR\fR\fR
.ad
.RS 20n
.rt  
The function succeeded.
.RE

.sp
.ne 2
.mk
.na
\fBOther values\fR
.ad
.RS 20n
.rt  
Indicate that the function failed. See \fBscha_calls\fR(3HA) for  the meaning of the
failure codes.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBscds_get_ext_property()\fR
.sp
.in +2
.nf
#include <scha_types.h>
#include <libdsdev.h>
#define INT_EXT_PROP "Int_extension_property"
\&...
int  retCode;
scha_extprop_value_t *intExtProp;
int retrievedValue;
\&...
   retCode = scds_get_ext_property(handle,
       INT_EXT_PROP, SCHA_PTYPE_INT, &intExtProp);
   if (retCode != SCHA_ERR_NOERR) {
       scds_syslog(LOG_ERR,
           "Failed to retrieve the extension property %s: %s.",
           INT_EXT_PROP, scds_error_string(retCode));
      ...
   } else {
       retrievedValue = intExtProp->val.val_int;
       ...
       scds_free_ext_property(intExtProp);
       ...
   }
  ...
.fi
.in -2

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/usr/cluster/include/rgm/libdsdev.h\fR\fR
.ad
.sp .6
.RS 4n
Include file
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/cluster/lib/libdsdev.so\fR\fR
.ad
.sp .6
.RS 4n
Library
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) 
for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
AvailabilitySUNWscdev
_
Interface StabilityEvolving
.TE

.SH SEE ALSO
.sp
.LP
\fBscds_free_ext_property\fR(3HA), \fBscds_initialize\fR(3HA), \fBscds_property_functions\fR(3HA), \fBscha_calls\fR(3HA), \fBrt_reg\fR(4), \fBattributes\fR(5), \fBproperty_attributes\fR(5)
.SH NOTES
.sp
.LP
Only the values of extension properties that are defined in the RTR
file can be retrieved by using this function. See \fBrt_reg\fR(4).