.ds Vv 1.2.14
.TH VistaIOGetAttr 3 "24 April 1993" "VistaIO Version \*(Vv"
.SH NAME
VistaIOGetAttr, VistaIOGetAttrValue \- fetch an attribute's value
.SH SYNOPSIS
.nf
.ft B
VistaIOGetAttrResult VistaIOGetAttr (\fIlist\fP, \fIname\fP, \fIdict\fP, \fIrepn\fP, \fIvalue\fP)
.RS
VistaIOAttrList \fIlist\fP;
VistaIOStringConst \fIname\fP;
VistaIODictEntry *\fIdict\fP;
VistaIORepnKind \fIrepn\fP;
VistaIOPointer \fIvalue\fP;
.RE
.PP
.ft B
typedef enum { VistaIOAttrFound, VistaIOAttrMissing, VistaIOAttrBadValue } VistaIOGetAttrResult;
.PP
.ft B
VistaIOBoolean VistaIOGetAttrValue (\fIposn\fP, \fIdict\fP, \fIrepn\fP, \fIvalue\fP)
.RS
VistaIOAttrListPosn *\fIposn\fP;
VistaIODictEntry *\fIdict\fP;
VistaIORepnKind \fIrepn\fP;
VistaIOPointer \fIvalue\fP;
.RE
.fi
.SH ARGUMENTS
.IP \fIlist\fP 10n
Specifies the list of attributes to be searched by name for the desired
attribute.
.IP \fIname\fP
Specifies the name of the desired attribute.
.IP \fIposn\fP
Specifies the position of the desired attribute within its attribute list.
.IP \fIdict\fP
May specify a dictionary to be used in recognizing a keyword
stored as the attribute's value, or it may be
.SB NULL\c
.
.IP \fIrepn\fP
Specifies the representation in which the attribute value is to be 
returned. 
.IP \fIvalue\fP
Specifies a location at which the attribute value is be returned.
.SH DESCRIPTION
These routines both return an attribute's value, but they differ in how the 
attribute is identified:
.RS 2n
.IP \(bu 2n
\fBVistaIOGetAttr\fP fetches the value of the first attribute with the name 
\fIname\fP in the list \fIlist\fP. 
.IP \(bu 2n
\fBVistaIOGetAttrValue\fP fetches the value of the attribute whose position 
within an attribute list is \fIposn\fP. 
.RE
.PP
If a dictionary, \fIdict\fP, has been provided and the attribute's value is 
stored as a character string, the routine determines whether the string is 
a keyword defined in the dictionary. If so, it uses the value associated 
with that keyword rather than the attribute's original value. (See the 
\fBVistaIOdictionary\fP(3) manual page.) 
.PP
The value obtained directly from the attribute, or indirectly via the 
dictionary, is converted to the representation \fIrepn\fP and then stored 
at the location pointed to by \fIvalue\fP. The \fIrepn\fP argument may have 
any \fBVistaIORepnKind\fP value (any of the values 
returned by \fBVistaIORegisterType\fP(3). However, an attribute value that is a 
string can only be returned as a string or a number, and other attribute 
values can only be returned in the representation with which they are 
stored. (The \fBVistaIOGetAttrRepn\fP(3) macro can be used to determine an 
attribute value's representation.) 
.PP
If \fIrepn\fP calls for a number to be returned, the caller receives a copy 
of the value stored with the attribute. If, on the other hand, it calls for 
a string, attribute list, pointer, image, edge set, etc. to be returned, 
the caller receives a pointer to the same value as that stored with the 
attribute.
.SH "RETURN VALUES"
If the specified attribute is not found, \fBVistaIOGetAttr\fP returns
\fBVistaIOAttrMissing\fP. If it is found but its value cannot be converted to the
desired representation, \fBVistaIOGetAttr\fP returns \fBVistaIOAttrBadValue\fP.
Otherwise, \fBVistaIOGetAttr\fP is successful and it returns \fBVistaIOAttrFound\fP,
having stored the attribute's value at *\fIvalue\fP.
.PP
\fBVistaIOGetAttrValue\fP returns
.SB TRUE
if it is successfully returning the attribute's value at *\fIvalue\fP, and
.SB FALSE
if the value cannot be converted to the desired representation.
.SH EXAMPLES
The following code fragment prints the name of an image:
.PP
.RS
.nf
.ft B
VistaIOImage image;
VistaIOStringConst name;
.PP
.ft B
if (VistaIOGetAttr (VistaIOImageAttrList (image), VistaIONameAttr, NULL, 
.RS
VistaIOStringRepn, (VistaIOPointer) & name) == VistaIOAttrFound)
printf ("Name: %s\\n", name);
.RE
.RE
.fi
.SH "SEE ALSO"
.na
.nh
.BR VistaIOExtractAttr (3),
.BR VistaIOSetAttr (3),
.BR VistaIOSetAttrValue (3),
.br
.BR VistaIOattribute (3),
.BR VistaIOdictionary (3),

.ad
.hy
.SH NOTES
\fBVistaIOGetAttr\fP is meant for use with attribute lists representing sets, in 
which each attribute name occurs at most once. If \fIlist\fP contains 
multiple attributes named \fIname\fP, only the first is located and 
returned. 
.PP
The \fIvalue\fP argument must point to sufficient storage to contain a 
value of the representation requested. Neither the routine nor the C 
compiler can automatically check that this is so. 
.SH AUTHOR
Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>