---------------------
set_cookie() FUNCTION
---------------------

  ------------
  USAGE FORMAT
  ------------

    Within a PREPROCESS tag:

    &set_cookie($name)
    &set_cookie($name, $value)
    &set_cookie($name, $value, $domain)
    &set_cookie($name, $value, $domain, $path)
    &set_cookie($name, $value, $domain, $path, $expires)
    &set_cookie($name, $value, $domain, $path, $expires, $secure)

  -----------
  DESCRIPTION
  -----------

    Sets a cookie in the end user's cache. May ONLY be used in a PREPROCESS tag.

  ---------
  ARGUMENTS
  ---------

    $name

      REQUIRED

      The name of the cookie, used to define the cookie in the user's cache.

    $value

      REQUIRED

      The cookie value to store.

    $domain

      OPTIONAL

      A cookie-qualifying domain value containing at least two (2) periods (.)
      defining at least a general site domain -- e.g. '.mydomain.com' or
      'www2.mydomain.com'.

    $path

      OPTIONAL

      A cookie-qualifying path value that begins and ends with a forward slash
      (/) and represents a valid relative path from your root web accessible
      directory on your host server -- e.g. '/' or '/mypath/'.

    $expires

      OPTIONAL

      May be left empty to set a session cookie. Must be set for a time-based
      cookie. Can be set using a value referenced from Perl's time() function.
      Values are also acceptable in the +/- form of seconds, minutes, hours,
      days, or years for example: +30s, +10m, +2h, +1d, +10y. If a negative (-)
      value is set the cookie will be deleted. The word 'now' is acceptable as
      well. Additionally, the formatted date is acceptable in the format:
      Thursday, 25-Apr-1999 00:40:33 GMT

    $secure

      OPTIONAL

      Set this value to 1 to receive the cookie only during secure, HTTPS
      connections.

  -------
  RETURNS
  -------

    NONE

  --------------
  USAGE EXAMPLES
  --------------

    ------------------------------------------------------------------
    Example 1: Set a Secure Cookie to Expire at the Same Time Tomorrow
    ------------------------------------------------------------------

      <?: &set_cookie('Color', 'red', '.mydomain.com', '/', '+1d', 1); ?>

  --------
  SEE ALSO
  --------

    TAGS

      PREPROCESS

    VARIABLES

      %_COOKIES, %_SESSION, %_SET_COOKIES

    FUNCTIONS

      delete_cookie()