NAME

       drmaa2_dict_create,  drmaa2_dict_free, drmaa2_dict_list, drmaa2_dict_has, drmaa2_dict_get,
       drmaa2_dict_del, drmaa2_dict_set - DRMAA2 dictionary routines

SYNOPSIS

       #include "drmaa.h"
       typedef struct drmaa2_dict_s *drmaa2_dict;

       typedef void (*drmaa2_dict_entryfree)(char **key, char **val);
       drmaa2_dict drmaa2_dict_create (const drmaa2_dict_entryfree callback);
       void drmaa2_dict_free(drmaa2_dict *d);
       drmaa2_string_list drmaa2_dict_list(const drmaa2_dict d);
       drmaa2_bool drmaa2_dict_has(const drmaa2_dict d, const char *key);
       const char *drmaa2_dict_get(const drmaa2_dict d, const char *key);
       drmaa2_error drmaa2_dict_del(drmaa2_dict d, const char *key);
       drmaa2_error drmaa2_dict_set(drmaa2_dict d, const char *key, const char *val);

DESCRIPTION

       drmaa2_dict_create()
              creates a new dictionary instance. Returns a pointer to the dictionary or  NULL  on
              error.   Optional  parameter  callback allows the application to provide a callback
              pointer to a collection element cleanup  function.   DRMAA2_UNSET_CALLBACK  may  be
              supplied instead of a valid callback pointer.

       drmaa2_dict_free()
              frees the dictionary and the contained members. If a callback function was provided
              on dictionary creation, it SHALL be called once per dictionary entry.

       drmaa2_dict_list()
              gets all dictionary keys as DRMAA drmaa2_string_list.  If the dictionary is  empty,
              a  valid  string  list  with  zero  elements  SHALL be returned. The application is
              expected to use drmaa2_list_free for freeing the returned data structure.

       drmaa2_dict_has()
              returns a boolean indication if the given key exists in the dictionary.  On  error,
              the function SHALL return FALSE.

       drmaa2_dict_get()
              gets  the  dictionary  value  for  the  specified  key.  If the key is invalid, the
              function returns NULL.

       drmaa2_dict_del()
              removes the dictionary entry with the given key and returns a  success  indication.
              If  a  callback  function  was  provided on dictionary creation, it SHALL be called
              before this function returns.

       drmaa2_dict_set()
              sets the specified dictionary key to the specified value.  Key  and  value  strings
              MUST be stored as the provided character pointers. If the dictionary already has an
              entry for this name, the value is replaced and the  old  value  is  removed.  If  a
              callback  was  provided  on  dictionary  creation,  it  SHALL be called with a NULL
              pointer for the key and the pointer of the previous value.

SEE ALSO

       drmaa2(3), drmaa2_list(3)

                                            2012-12-01                             drmaa2_dict(3)