-----------------------
session_name() FUNCTION
-----------------------

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

    Setting:

      Within a PREPROCESS tag:

      &session_name($name);

    Retreiving:

      Where $name is a session name buffer:

      $name = &session_name();

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

    The session_name() function is used to either set or retrieve the value of
    $_SESSION{'NAME'}. When an argument is provided, the value is set. If no
    argument is provided the value is simply returned. To clear the value of
    $_SESSION{'NAME'}, the session_delete() function may be used to remove the
    value from the %_SESSION hash all together or session_add() can be used to
    set it to an empty value. Alternately, the hash value can be set manually.

    When using this function to set values for the PTM Session, it may be used
    ONLY in a PREPROCESS tag to have any effect on the "Set-Cookie:" HTTP
    headers. After any modifications have been made using this function, a call
    to update_session() or start_session() MUST be made before ending the
    PREPROCESS tag, otherwise changes will have no effect.

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

    $name

      REQUIRED TO SET

      A name to assign to the PTM Session. Common values to use here are either
      the account name of the logged in user or the type of session in progress.

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

    The PTM Session name from $_SESSION{'NAME'}.

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

    ---------------------------------------
    Example 1: Setting the PTM Session Name
    ---------------------------------------

      <?:
        &session_name('admin');
        &update_session();
      ?>

    ------------------------------------------------------
    Example 2: Displaying the PTM Session Name to the User
    ------------------------------------------------------

      This PTM Session's Name is <?= &session_name() ?>

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

    TAGS

      PREPROCESS, DISPLAY

    VARIABLES

      %_COOKIES, %_SESSION, %_SET_COOKIES

    FUNCTIONS

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