ns_set(3aolserver)					    AOLserver Built-In Commands 					ns_set(3aolserver)

__________________________________________________________________________________________________________________________________________________

NAME

       ns_set - commands

SYNOPSIS

       Manipulate sets of key-value pairs.

SYNTAX

       ns_set copy ?-persist? setId

       ns_set cput setId key value

       ns_set create ?-persist? name

       ns_set delete setId fieldNumber

       ns_set delkey setId key

       ns_set find setId key

       ns_set free setId

       ns_set get setId key

       ns_set icput setId key value

       ns_set idelkey setId key

       ns_set ifind setId key

       ns_set iget setId key

       ns_set isnull setId fieldNumber

       ns_set iunique setId key

       ns_set key setId fieldNumber

       ns_set merge high low

       ns_set move to from

       ns_set name setId

       ns_set new ?-persist? name

       ns_set print setId

       ns_set put setId key value

       ns_set size setId

       ns_set split ?-persist? setId ?splitChar?

       ns_set truncate setId size

       ns_set unique setId key

       ns_set update setId key value

       ns_set value setId fieldNumber

_________________________________________________________________

DESCRIPTION

       ns_set copy
	      Returns  a  new  set  that has the same name and key value pairs as the passed-in set (setId). If -persist is specified, the new set
	      will persist even after the current transaction ends, and you can free it later with ns_set free. If -persist is not specified,  the
	      new set is automatically freed when the transaction ends.

       ns_set cput
	      appends  a new field to the set with key key and value value if the field does not already exist in the set. The field number of the
	      new field is returned.

       ns_set create
	      (which is the same as ns_set new) allocates memory for a new set and returns the ID for the new set. If -persist is  specified,  the
	      new  set will persist even after the current transaction ends, and you can free it later with ns_set free. If -persist is not speci-
	      fied, the new set is automatically freed when the transaction ends.

       ns_set delete
	      deletes the field in the set at field number fieldNumber.

       ns_set delkey
	      removes the first field in the set whose key is key. Note that there could be multiple fields in the set with this key; this command
	      only removes the first occurrence.

       ns_set find
	      returns  the  index  of  the first field in the specified set whose key name matches the specified key. Zero(0) is the index of the
	      first field. If no matching fields are found, ns_set find returns -1.

       ns_set free
	      frees the specified set. Sets must be explicitly freed with ns_set free if the -persist option was used when creating the set.  Oth-
	      erwise, sets are automatically freed when the transaction ends.

       ns_set get
	      returns the first value associated with the passed-in key. If the key is invalid, an empty string is returned.

       ns_set icput
	      is the case-insensitive counterpart of ns_set cput.

       ns_set idelkey
	      is the case-insensitive counterpart of ns_set delkey.

       ns_set ifind
	      is the case-insensitive counterpart of ns_set find.

       ns_set iget
	      is the case-insensitive counterpart of ns_set get.

       ns_set isnull
	      returns  1  if the value of the field specified by fieldNumber is null and 0 if it is not. Note that an empty string is not the same
	      as a null. ns_set isnull will return 0 for an empty string.

       ns_set iunique
	      returns 1 if the specified key is unique in the specified set and 0 if it is not. The test for uniqueness is performed case-insensi-
	      tively. ns_set unique is the case-sensitive version of this function.

	      For  example, a client could send multiple "Accept:" headers which would end up in the header set for the connection. ns_set iunique
	      would return 0 for the "Accept:" key, because there are multiple fields with the key "Accept:".

       ns_set key
	      extracts the key of the set at field number fieldNumber. This command is useful when looping through all the key-value pairs in  the
	      set.

       ns_set merge
	      merges  two sets. Any fields in the low set are appended to the high set if a field with the same key name does not already exist in
	      the high set.

       ns_set move
	      moves all fields from the from set to the end of the to set, leaving the from set a valid, empty set.

       ns_set name
	      returns the name of the set.

       ns_set new
	      (which is the same as ns_set create) allocates memory for a new set and returns the ID for the new set. If  -persist  is	specified,
	      the  new	set  will  persist even after the current transaction ends, and you can free it later with ns_set free. If -persist is not
	      specified, the new set is automatically freed when the transaction ends.

       ns_set print
	      prints the specified set to stderr.

       ns_set put
	      appends a new field to the set with key key and value value. Note that the field is appended so if a previous field has the same key
	      as the new field, the previous field is returned by ns_set get command. The field number of the new field is returned.

       ns_set size
	      returns the number of key-value pairs in the set.

       ns_set split
	      splits  one  set into multiple sets based on the splitChar as described below and returns a Tcl list of the newly-allocated sets. It
	      assumes that the keys in the specified set (setId) contain a specific character (splitChar) that can be used to separate the name of
	      a new set and the key in the new set. The default splitChar is a period (.).

	      For  example,  if  two fields in the original set have "dog.food" and "cat.food" as their key names and "Yummy dog food!" and "Yummy
	      cat food!" as their values, ns_set split would return two new sets named "dog" and "cat". The dog set  would  have  a  single  field
	      whose  key is "food" and whose value is "Yummy dog food!". The cat set would have a single field whose key is "food" and whose value
	      is "Yummy cat food!".

       ns_set truncate
	      reduces the set to the first size key-value pairs and frees the memory for the rest of the key-value pairs that may have been in the
	      set.

       ns_set unique
	      returns  1  if the specified key is unique in the specified set and 0 if it is not. The test for uniqueness is performed case-sensi-
	      tively. ns_set iunique is the case-insensitive version of this function.

       ns_set update
	      updates the first field in the specified set whose key is key and replaces its value with value.	ns_set	update	is  equivalent	to
	      ns_set delkey followed by ns_set put.

       ns_set value
	      extracts	the  value  of the set at field number fieldNumber. This command is useful when looping through all the key-value pairs in
	      the set.

NOTES

       The fields in the set are ordered by number. The field numbers range from 0 to one less than the total number of fields.  For  example,	if
       you have a set with 5 fields, you would use "ns_set key $setid 4" to extract the key of the last field in the set.

KEYWORDS

       key value

AOLserver								4.0							ns_set(3aolserver)