NAME

       VistaIOExtractAttr - fetch and delete an attribute

SYNOPSIS

       VistaIOBoolean VistaIOExtractAttr (list, name, dict, repn, value, required)
              VistaIOAttrList list;
              VistaIOStringConst name;
              VistaIODictEntry *dict;
              VistaIORepnKind repn;
              VistaIOPointer value;
              VistaIOBoolean required;

ARGUMENTS

       list      Specifies the list of attributes to be searched by name for the desired attribute.

       name      Specifies the name of the desired attribute.

       dict      May  specify  a dictionary to be used in recognizing a keyword stored as the attribute's value,
                 or it may be NULL

       repn      Specifies the representation in which the attribute value is to be returned.

       value     Specifies a location at which the attribute value is be returned.

       required  Is TRUE if failure to find the attribute should be considered an error.

DESCRIPTION

       VistaIOExtractAttr locates the first attribute named name in list, removing it if found and returning its
       value.

       If a dictionary, dict, 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  VistaIOdictionary(3)
       manual page.)

       The  value  obtained  directly  from the attribute, or indirectly via the dictionary, is converted to the
       representation repn and then stored at the location pointed to by value. The repn argument may  have  any
       VistaIORepnKind  value  or  any  of  the values returned by VistaIORegisterType(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 VistaIOGetAttrRepn(3) macro can be
       used to determine an attribute value's representation.)

RETURN VALUES

       VistaIOExtractAttr returns FALSE if required is TRUE and no  attribute  named  name  is  found.  If  also
       returns  FALSE  if an attribute is found but its value cannot be converted to the desired representation.
       Otherwise, VistaIOExtractAttr returns TRUE while perhaps modifying the list list and storing a  value  at
       value.

SEE ALSO

       VistaIOGetAttr(3), VistaIOGetAttrValue(3), VistaIOLookupAttr(3), VistaIODeleteAttr(3),
       VistaIOInsertAttr(3),
       VistaIOattribute(3), VistaIOdictionary(3),

NOTES

       VistaIOExtractAttr  is meant for use with attribute lists representing sets, in which each attribute name
       occurs at most once. If list contains multiple attributes named name, only the first is located.

       The value 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.

       If  a  string  value  is  returned, it will be in newly-allocated storage.  Release the storage with Vis‐
       taIOFree(3) when done with the string.

DIAGNOSTICS

       ``name attribute missing.''
              No attribute named name could be found, and required is TRUE

       ``name attribute has bad value.''
              The attribute was found, but its value cannot be converted to the desired representation.

AUTHOR

       Art Pope <pope@cs.ubc.ca>

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

VistaIO Version 1.2.14                            24 April 1993                            VistaIOExtractAttr(3)