NAME

       read-hash -  (hash)

PURPOSE

       Get data from hash.

SYNTAX

           // Random access to hash data:

           read-hash <hash> \
               key <key> \
               value <value> \
               [ delete [ <delete> ] ] \
               [ status <status> ]

           // Sequential access to hash data:

           read-hash <hash> traverse begin

           read-hash <hash> traverse \
               key <key> \
               value <value>  \
               [ delete [ <delete> ] ] \
               [ status <status> ] \

DESCRIPTION

       WITHOUT TRAVERSE CLAUSE

       read-hash  will  obtain  an element from <hash>, which is a string <value> (in "value" clause) based on a
       string <key> (in "key" clause). <hash> was created by new-hash.

       You can also delete an element from the hash by using "delete" clause - the  <value>  is  still  obtained
       though  it  is  no  longer  in  the  hash. The hash element is deleted if "delete" clause is used without
       boolean variable <delete>, or if <delete> evaluates to true.

       If no <key> was found in the hash, <status> number (in "status" clause) is GG_ERR_EXIST  and  <value>  is
       unchanged, otherwise <status> is GG_OKAY.

       WITH TRAVERSE CLAUSE

       read-hash  with "traverse" clause obtains <key> and <value> of the current element, and then positions to
       the next one. You can also delete this element from the hash by using "delete" clause  -  the  <key>  and
       <value>  are  still  obtained though the element is no longer in the hash. The hash element is deleted if
       "delete" clause is used without boolean variable <delete>, or if <delete> evaluates to true.

       Use "begin" clause to position at the very first element. This is useful if  you  wish  to  get  all  the
       key/value pairs from a hash - note they are not extracted in any particular order. When there are no more
       elements,  <key>  and  <value>  are  unchanged  and <status> number (in "status" clause) is GG_ERR_EXIST,
       otherwise <status> is GG_OKAY.

       You may search, add or delete elements while traversing a  hash,  and  this  will  be  reflected  in  all
       elements not yet traversed.

EXAMPLES

       In this example, a new hash is created, a key/value pair is written to it, and then the value is obtained
       and the element deleted; return status is checked:

           // Create new hash
           new-hash h

           // Write to a hash
           write-hash h key "X0029" value "some data"

           // Read from a hash
           read-hash h key "X0029" value res status f delete
           if-true f equal GG_ERR_EXIST
               @No data in the hash!
           else-if
               @Deleted value is <<print-out res>>
           end-if

       The following will traverse the entire hash and display all the data:

           // Position at the beginning of the hash
           read-hash h traverse begin
           start-loop
               // Get elements, one by one, until NULL returned as a key
               read-hash h traverse key k value r status f
               if-true f equal GG_ERR_EXIST
                   break;
               end-if
               print-format "Key [%s] data [%s]\n", k, r
           end-loop

SEE ALSO

        Hash

       get-hash new-hash purge-hash read-hash resize-hash write-hash See all documentation

$DATE                                               $VERSION                                           GOLF(2gg)