.ds Vv 1.2.14
.TH VistaIOExtractAttr 3 "24 April 1993" "VistaIO Version \*(Vv"
.SH NAME
VistaIOExtractAttr \- fetch and delete an attribute
.SH SYNOPSIS
.nf
.ft B
VistaIOBoolean VistaIOExtractAttr (\fIlist\fP, \fIname\fP, \fIdict\fP, \fIrepn\fP, \
\fIvalue\fP, \fIrequired\fP)
.RS
VistaIOAttrList \fIlist\fP;
VistaIOStringConst \fIname\fP;
VistaIODictEntry *\fIdict\fP;
VistaIORepnKind \fIrepn\fP;
VistaIOPointer \fIvalue\fP;
VistaIOBoolean \fIrequired\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 \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.
.IP \fIrequired\fP
Is
.SB TRUE
if failure to find the attribute should be considered an error.
.SH DESCRIPTION
\fBVistaIOExtractAttr\fP locates the first attribute named \fIname\fP in \fIlist\fP, 
removing it if found and returning its value.
.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 or 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.) 
.SH "RETURN VALUES"
\fBVistaIOExtractAttr\fP returns
.SB FALSE
if \fIrequired\fP is
.SB TRUE
and no attribute named \fIname\fP is found. If also returns
.SB FALSE
if an attribute is found but its value cannot be converted to the desired 
representation. Otherwise, \fBVistaIOExtractAttr\fP returns 
.SB TRUE
while perhaps modifying the list \fIlist\fP and storing a value at 
\fIvalue\fP. 
.SH "SEE ALSO"
.na
.nh
.BR VistaIOGetAttr (3),
.BR VistaIOGetAttrValue (3),
.BR VistaIOLookupAttr (3),
.BR VistaIODeleteAttr (3),
.BR VistaIOInsertAttr (3),
.br
.BR VistaIOattribute (3),
.BR VistaIOdictionary (3),

.hy
.ad
.SH NOTES
\fBVistaIOExtractAttr\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. 
.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.
.PP
If a string value is returned, it will be in newly-allocated storage.
Release the storage with \fBVistaIOFree\fP(3) when done with the string.
.SH DIAGNOSTICS
.IP "``\fIname\fP attribute missing.''"
No attribute named \fIname\fP could be found, and \fIrequired\fP is
.SB TRUE\c
.
.IP "``\fIname\fP attribute has bad value.''"
The attribute was found, but its value cannot be converted to the desired 
representation.
.SH AUTHOR
Art Pope <pope@cs.ubc.ca>

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