NAME

       VistaIOGetAttr, VistaIOGetAttrValue - fetch an attribute's value

SYNOPSIS

       VistaIOGetAttrResult VistaIOGetAttr (list, name, dict, repn, value)
              VistaIOAttrList list;
              VistaIOStringConst name;
              VistaIODictEntry *dict;
              VistaIORepnKind repn;
              VistaIOPointer value;

       typedef enum { VistaIOAttrFound, VistaIOAttrMissing, VistaIOAttrBadValue } VistaIOGetAttrResult;

       VistaIOBoolean VistaIOGetAttrValue (posn, dict, repn, value)
              VistaIOAttrListPosn *posn;
              VistaIODictEntry *dict;
              VistaIORepnKind repn;
              VistaIOPointer value;

ARGUMENTS

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

       name      Specifies the name of the desired attribute.

       posn      Specifies the position of the desired attribute within its attribute list.

       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.

DESCRIPTION

       These  routines  both return an attribute's value, but they differ in how the attribute is
       identified:

         • VistaIOGetAttr fetches the value of the first attribute with the name name in the list
           list.

         • VistaIOGetAttrValue  fetches  the  value  of  the  attribute  whose position within an
           attribute list is posn.

       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 (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.)

       If  repn 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.

RETURN VALUES

       If the specified attribute is not found, VistaIOGetAttr returns VistaIOAttrMissing. If  it
       is  found  but its value cannot be converted to the desired representation, VistaIOGetAttr
       returns VistaIOAttrBadValue.  Otherwise,  VistaIOGetAttr  is  successful  and  it  returns
       VistaIOAttrFound, having stored the attribute's value at *value.

       VistaIOGetAttrValue  returns TRUE if it is successfully returning the attribute's value at
       *value, and FALSE if the value cannot be converted to the desired representation.

EXAMPLES

       The following code fragment prints the name of an image:

              VistaIOImage image;
              VistaIOStringConst name;

              if (VistaIOGetAttr (VistaIOImageAttrList (image), VistaIONameAttr, NULL,
                     VistaIOStringRepn, (VistaIOPointer) & name) == VistaIOAttrFound)
                     printf ("Name: %s\n", name);

SEE ALSO

       VistaIOExtractAttr(3), VistaIOSetAttr(3), VistaIOSetAttrValue(3),
       VistaIOattribute(3), VistaIOdictionary(3),

NOTES

       VistaIOGetAttr 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 and returned.

       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.

AUTHOR

       Art Pope <pope@cs.ubc.ca>

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