Tcl_GetKeyedListKeys(3Tcl)			    Tcl_GetKeyedListKeys(3Tcl)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #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    [Toc]    [Back]

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

   Tcl_GetKeyedListKeys    [Toc]    [Back]
     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.






									Page 1






Tcl_GetKeyedListKeys(3Tcl)			    Tcl_GetKeyedListKeys(3Tcl)



     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    [Toc]    [Back]
     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    [Toc]    [Back]
     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    [Toc]    [Back]
     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.


									PPPPaaaaggggeeee 2222