-------------------------
session_secure() FUNCTION
-------------------------

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

    Setting:

      Within a PREPROCESS tag:

      &session_secure($secure);

    Retreiving:

      Where $secure is a session secure buffer:

      $secure = &session_secure();

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

    The session_secure() function is used to either set or retrieve the value of
    $_SESSION{'SECURE'}. 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{'SECURE'}, 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 SECURE value should be set to either 0 or 1. Other values will generally
    be ignored. When this value is set to 1, the PTM Session cookies will only
    be returned when a secure, HTTPS connection is in use. This ensures that
    sensitive data will only be distributed over a secure connection. Though
    this value can be set to 0 (zero), or set to empty from its ON state (value
    of 1), it is preferred to remove the value entirely with the
    session_delete('SECURE') call, as this ensures no security value is passed
    into the session cookies at all.

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

    $secure

      REQUIRED TO SET

      Should be set to '1' to enable session use over secure, HTTPS connections
      only. A session_delete('SECURE') function call should be made to remove
      this setting.

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

    The PTM Session 'secure' value from $_SESSION{'SECURE'}, or an empty string
    if not set.

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

    ---------------------------------------------------
    Example 1: Setting the PTM Session's Security Value
    ---------------------------------------------------

      <?:
        &session_secure(1);
        &update_session();
      ?>

    ----------------------------------------------------
    Example 2: Removing the PTM Session's Security Value
    ----------------------------------------------------

      <?:
        &session_delete('SECURE');
        &update_session();
      ?>

    ------------------------------------------------------------------
    Example 3: Displaying the PTM Session's Security Value to the User
    ------------------------------------------------------------------

      This PTM Session's Security value is <?= &session_secure() || '0' ?>

  --------
  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_name(),
      session_path(), set_cookie(), start_session(), update_session()