-------------------------
session_domain() FUNCTION
-------------------------

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

    Setting:

      Within a PREPROCESS tag:

      &session_domain($domain);

    Retreiving:

      Where $domain is a session domain buffer:

      $domain = &session_domain();

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

    The session_domain() function is used to either set or retrieve the value of
    $_SESSION{'DOMAIN'}. 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{'DOMAIN'}, 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.
    
    The domain argument must qualify as a valid cookie domain, meaning that it
    must contain at least 2 periods (.) and must represent at least a general
    domain -- e.g. '.mydomain.com'. Optionally, more specific values are
    allowed, such as 'www2.mydomain.com' if preferred.

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

    $domain

      REQUIRED TO SET

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

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

    The PTM Session domain from $_SESSION{'DOMAIN'}.

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

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

      <?:
        &session_domain('.mydomain.com');
        &update_session();
      ?>

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

      This PTM Session's Domain value is <?= &session_domain() ?>

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

    TAGS

      PREPROCESS, DISPLAY

    VARIABLES

      %_COOKIES, %_SESSION, %_SET_COOKIES

    FUNCTIONS

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