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>