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
       VistaIOFree(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>