------------------
%_SESSION VARIABLE
------------------

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

    NOTE:
    
      All PTM Session modification code should be written in PREPROCESS tags.
      Any session modification taking place outside of PREPROCESS tags will be
      ignored.

    The %_SESSION variable is the crossroads for cookie-based PTM Sessions.
    PTM Sessions allow for a group of cookie values to be stored in a group
    with a scrambled, unique ID number (60+ characters in length). Optionally,
    an alternate developer-selected ID number may be used. The ID is stored in a
    cookie named PTMSESSIONID. In fact, all PTM Session related cookies begin
    their name with "PTMSESSION" and then the name of the session variable is
    appended. Therefore, %_SESSION works almost exactly like the %_COOKIES hash,
    except that it only stores PTM Session cookies. When the session cookies are
    read in, their "PTMSESSION" prefix is removed before being placed in the
    %_SESSION hash. The only session variable required in a PTM Session is the
    previously mentioned ID number, which is stored as "ID" in %_SESSION and as
    a cookie named "PTMSESSIONID" in the user's browser.

    The %_SESSION variable is structured similar to the following:

      %_SESSION = (
        ID      => &session_id(),
        NAME    => 'username',
        DOMAIN  => '.mysite.com',
        PATH    => '/',
      );

    The %_SESSION keys (PTM Session variable names) can be accessed as a list
    (array) with Perl's "keys" command like so:

      @var_names = keys %_SESSION;

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

      $session_id = $_SESSION{'ID'};

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

    When you wish to start a new PTM session, the start_session() function is
    used. Likewise, to end a PTM session, the end_session() function is used. To
    change anything during a PTM session the values stored in %_SESSION must be
    modified. New session values can be added via the session_add() function,
    and the session values can be deleted with the session_delete() function.
    Alternately, you may modify the values within the %_SESSION hash manually.
    Whichever method of session modification you choose, after modifying the
    %_SESSION hash, the update_session() function MUST be called, otherwise your
    session changes will be ignored when the user changes pages. Also, the
    is_session() function, which tells whether or not a PTM Session is currently
    in progress, simply bases its response on whether or not $_SESSION{'ID'} is
    defined. If the session value 'ID' is not defined, then as far as your PTM
    script is concerned, no session is in progress. In other words, don't delete
    the session ID.

    All PTM Session related code should be written in PREPROCESS tags, as
    cookies need to be assigned BEFORE the HTTP headers are written. Any session
    modification taking place outside of PREPROCESS tags will be ignored.

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

    --------------------------------------------------------------------------
    Example 1: Starting a Cookie-Based PTM Session Based On a POSTed User Name
    --------------------------------------------------------------------------

      <?:
        if (defined $_POST{'name'}) {
          &start_session($_POST{'name'});
        }
      ?>

    ------------------------------------------------
    Example 2: Adding a "Color" Value to the Session
    ------------------------------------------------

      <?:
        &session_add('Color', 'red');
        &update_session();
      ?>

    ---------------------------------------------------------------------
    Example 3: Manually adding a Session Value (Same Effect as Example 2)
    ---------------------------------------------------------------------

      <?:
        $_SESSION{'Color'} = 'red';
        &update_session();
      ?>

    ----------------------------------------------------
    Example 4: Ending a Session, If One Currently Exists
    ----------------------------------------------------

      <?:
        if (&is_session()) {
          &end_session()
        }
      ?>

    ------------------------------------------------------------------------
    Example 5: Displaying a PTM Session Value to the User with a DISPLAY Tag
    ------------------------------------------------------------------------

      Hello <?= $_SESSION{'NAME'} ?>, Welcome Back!

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

    TAGS

      PREPROCESS

    VARIABLES

      %_COOKIES, $_POST, %_SET_COOKIES

    FUNCTIONS

      delete_cookie(), end_session(), is_session(), session_add(),
      session_delete(), session_domain(), session_id(), session_name(),
      session_path(), session_secure, set_cookie(), start_session(),
      update_session()