----------------------
%_SET_COOKIES VARIABLE
----------------------

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

    NOTE:

      All cookie modification code should be written in PREPROCESS tags. Any
      cookie modification taking place outside of PREPROCESS tags will be
      ignored.

    The %_SET_COOKIES variable is used to store "Set-Cookie:" HTTP header
    strings. Because cookies must be written into the HTTP file headers BEFORE
    the page can be displayed, any modification to the %_SET_COOKIES hash must
    be made in PREPROCESS tags, so as to run before any of the normal PTM script
    is evaluated, otherwise it wouldn't be available to put into the HTTP header
    string.

    The %_SET_COOKIES hash is structured similar to the following:

      %_SET_COOKIES = (
        cookie1 => 'cookie1=value1; path=/'
        cookie2 => 'cookie2=value2; domain=.mysite.com; path=/'
        cookie3 => 'cookie3=value3; domain=.mysite.com; path=/; secure=1';
      );

    The %_SET_COOKIES keys (cookie names) can be accessed as a list (array) with
    Perl's "keys" command like so:

      @cookie_names = keys %_SET_COOKIES;

    The cookie values can be accessed by referencing the specific name of the
    requested cookie:

      $cookie_value = $_SET_COOKIES{'cookie1'};

    Notice that, when referencing a specific cookie value, the '%' is changed to
    a '$' when referencing the hash, as you are referencing a specific value and
    not the entire hash.

    Though you CAN read the values of the %_SET_COOKIES hash, there is usually
    no reason to do so. The %_SET_COOKIES hash is simply a storage buffer for
    cookies that are about to be set, not ones that have been set already. To
    get cookies that are already set, see the documentation on the %_COOKIES
    variable.

    You can set and delete cookies using the set_cookie() function and the
    delete_cookie() function. These, and any other calls that modify the
    %_SET_COOKIES variable must be made in PREPROCESS tags to have any effect on
    the cookie related portion of your HTTP header, as any changes to this
    variable must be made BEFORE the HTTP header is printed.

    Cookie strings stored in the %_SET_COOKIES hash lack the "Set-Cookie:"
    prefix and the trailing new line character (\n) necessary to make them fully
    qualified HTTP header data. This information is added to them when they are
    sent to the user.

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

    ------------------------------------------
    Example 1: Setting a Normal Session Cookie
    ------------------------------------------

      <?: &set_cookie('color', 'red'); ?>
    
    -----------------------------------------------------------------------
    Example 2: Manually Setting a Normal Session Cookie (Same as Example 1)
    -----------------------------------------------------------------------

      <?: $_SET_COOKIES{'color'} = 'color=red; path=/'; ?>

    --------------------------------------------------------------
    Example 3: Setting a Time-Based Cookie to Expire in 30 Minutes
    --------------------------------------------------------------

      <?: &set_cookie('color', 'red', '', '/', '+30m'); ?>

    -------------------------------------------------------
    Example 4: Deleting a Cookie, Regardless of Cookie Type
    -------------------------------------------------------

      <?: &delete_cookie('color'); ?>

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

    TAGS

      PREPROCESS

    VARIABLES

      %_COOKIES, %_SESSION

    FUNCTIONS

      delete_cookie(), set_cookie()