------------------------
start_session() FUNCTION
------------------------

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

    Within a PREPROCESS tag:

    &start_session()
    &start_session($name)
    &start_session($name, $id)
    &start_session($name, $id, $domain)
    &start_session($name, $id, $domain, $path)
    &start_session($name, $id, $domain, $path, $secure)

  -----------
  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 start_session() function begins a new PTM Session, via modification to
    the %_SESSION hash and required set_cookie() function calls. See
    documentation on the %_SESSION variable for more detail on PTM Sessions.

    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.

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

    $name

      OPTIONAL

      Used to set the value of $_SESSION{'NAME'} and set the 'PTMSESSIONNAME'
      cookie.

    $id

      OPTIONAL

      Used to set the value of $_SESSION{'ID'} and set the 'PTMSESSIONID'
      cookie. If no value is given a unique 60+ character ID number is generated
      in place of a custom ID.

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

    $secure

      OPTIONAL

      Should be set to '1' to enable session use over secure, HTTPS connections
      only.

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

    NONE

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

    ----------------------------------------------------------------------
    Example 1: Starting a New Secure Session if One Does Not Already Exist
    ----------------------------------------------------------------------

      <?:
        unless (&is_session()) {
          start_session('admin', '', '.mydomain.com', '/', 1);
        }
      ?>

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

    TAGS

      PREPROCESS

    VARIABLES

      %_COOKIES, %_SESSION, %_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(), update_session()