---------------------
session_id() FUNCTION
---------------------

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

    Setting:

      Within a PREPROCESS tag:

      &session_id($id);

    Retreiving:

      Where $id is a session ID buffer:

      $id = session_id();

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

    The session_id() function, like the other session_... functions is used to
    set and retrieve PTM Session related values from the %_SESSION hash.
    However, unlike these other functions, session_id() may also be used when no
    PTM Session is in progress.

    When an argument is provided, the value of $_SESSION{'ID'} is set to the
    provided argument value. If a session is in progress and no argument is
    given, the value of $_SESSION{'ID'} is returned. However, if no session is
    in progress (the ID value has not be set), and no argument is given, a
    randomly generated ID number, 60+ characters in length, is returned. This
    ID number is generated based on the remote user's address and port, the
    current time, and two randomly generated numbers (based on time and Perl's
    random process ID), each of which is 9 digits in length. This ensures that
    even 2 connections from either the same computer or behind the same routed
    network will receive different session ID numbers. This allows the developer
    to uniquely identify each user in a session.

    The reason an ID number can be optionally set, instead of using random
    generation, is to provide for the case of database-managed persistent ID
    sessions, in which session IDs for each user are stored to a database and
    are read back in each time that user logs in.

    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
  ---------

    $id

      REQUIRED TO SET

      The requested PTM Session ID number -- should be unique in most instances.

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

    The PTM Session ID number from $_SESSION{'ID'}.

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

    --------------------------------------------
    Example 1: Setting the PTM Session ID Number
    --------------------------------------------

      <?:
        &session_id('90012');
        &update_session();
      ?>

    -----------------------------------------------------------
    Example 2: Displaying the PTM Session ID Number to the User
    -----------------------------------------------------------

      <? if (&is_session()) { ?>
        Your PTM Session ID Number is <?= session_id() ?>
      <? } ?>

    --------------------------------------------------------------
    Example 3: Getting a Random ID Number (No Session In Progress)
    --------------------------------------------------------------

      <?
        unless (&is_session()) {
          $id = &session_id();
        }
      ?>

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

    TAGS

      PREPROCESS, DISPLAY, DO

    VARIABLES

      %_COOKIES, %_SESSION, %_SET_COOKIES

    FUNCTIONS

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