NAME
          Tcl_GetKeyedListKeys,                 Tcl_GetKeyedListField,
          Tcl_SetKeyedListField, Tcl_DeleteKeyedListField - Keyed list
          management routines.

     SYNOPSIS
          #include <tclExtend.h>

          int
          Tcl_GetKeyedListKeys (Tcl_Interp  *interp,
                                const char  *subFieldName,
                                const char  *keyedList,
                                int         *keyesArgcPtr,
                                char      ***keyesArgvPtr);

          int
          Tcl_GetKeyedListField (Tcl_Interp  *interp,
                                 const char  *fieldName,
                                 const char  *keyedList,
                                 char       **fieldValuePtr);

          char *
          Tcl_SetKeyedListField (Tcl_Interp  *interp,
                                 const char  *fieldName,
                                 const char  *fieldvalue,
                                 const char  *keyedList);

          char *
          Tcl_DeleteKeyedListField (Tcl_Interp  *interp,
                                    const char  *fieldName,
                                    const char  *keyedList);

     DESCRIPTION
          These routines perform operations on keyed lists.   See  the
          Extended Tcl man page for a description of keyed lists.

        Tcl_GetKeyedListKeys
          Retrieve a list of keyes from a keyed  list.   The  list  is
          walked  rather  than  converted  to  a  argv  for  increased
          performance.

          Parameters:
            o interp - Error message will be return in result if there
            is an error.
            o subFieldName - If "" or NULL, then the keys are retreved
            for  the  top level of the list.  If specified, it is name
            of the field who's subfield keys are to be retrieve.
            o keyedList - The list to search for the field.
            o keyesArgcPtr - The number of keys in the keyed  list  is
            returned here.
            o keyesArgvPtr - An argv containing the key names.  It  is
            dynamically  allocated,  containing both the array and the
            strings. A single call to ckfree will release it.

          Returns:
            TCL_OK if a list of keys is  returned,  TCL_BREAK  if  the
            field was not found, or TCL_ERROR if an error occured.

        Tcl_GetKeyedListField
          Retrieve a field value from  a  keyed  list.   The  list  is
          walked  rather  than  converted  to  a  argv  for  increased
          performance.  This if the  name  contains  sub-fields,  this
          function recursive.

          Parameters:
            o interp - Error message will be return in result if there
            is an error.
            o fieldName - The name of  the  field  to  extract.   Will
            recusively process sub-field names seperated by `.'.
            o keyedList - The list to search for the field.
            o fieldValuePtr - If the field is found, a  pointer  to  a
            dynamicly   allocated   string  containing  the  value  is
            returned here.   If  NULL  is  specified,  then  only  the
            presence  of  the  field  is  validated,  the value is not
            returned.

          Returns:
            TCL_OK if the field was found,  TCL_BREAK if the field was
            not found or TCL_ERROR if an error occured.

        Tcl_SetKeyedListField
          Set a field value in keyed list.

          Parameters:
            o interp - Error message will be return in result if there
            is an error.
            o fieldName - The name of  the  field  to  extract.   Will
            recusively process sub-field names seperated by `.'.
            o fieldValue - The value to set for the field.
            o keyedList - The keyed list to set a field value in,  may
            be an NULL or an empty list to create a new keyed list.

          Returns:
            A pointer to a dynamically allocated string, or NULL if an
            error occured.

        Tcl_DeleteKeyedListField
          Delete a field value in keyed list.

          Parameters:
            o interp - Error message will be return in result if there
            is an error.
            o fieldName - The name of  the  field  to  extract.   Will
            recusively process sub-field names seperated by `.'.
            o fieldValue - The value to set for the field.
            o keyedList - The keyed list to delete the field from.

          Returns:
            A pointer to a dynamically allocated string containing the
            new list, or NULL if an error occured.