DTW_SETCOOKIE

AIX HP-UX Linux OS/2 OS/390 OS/400 PTX SUN Win NT
X X X X X X X X X

Purpose

Generates JavaScript code that sets a cookie on the client system.

Format

@DTW_SETCOOKIE(IN cookie_name, IN cookie_value, IN adv_opts)

@DTW_SETCOOKIE(IN cookie_name, IN cookie_value)

Parameters

Table 49. DTW_SETCOOKIE Parameters
Data Type Parameter Use Description
string cookie_name IN A variable or literal string that specifies the name of the cookie
string cookie_value IN A variable or literal string the specifies the value of the cookie.

Avoid using semicolons, commas, and spaces as a part of cookie_value. When they are required, use the Net.Data function DTW_rURLESCSEQ to process the string that contains the special characters before passing it to DTW_SETCOOKIE. For example,

@DTW_SETCOOKIE("my_cookie_name", 
  @DTW_rURLESCSEQ("my cookie value"))
string adv_opts IN A string that contains optional attributes, separated by semicolons, that are used to define the cookie.*
*The optional attributes can be:

expires = date
Specifies a date string that defines the valid lifetime of the cookie. After the date expires, the cookie is not longer stored or retrieved. Syntax:
weekday, DD-month-YYYY HH:MM:SS GMT

Where:

weekday
Specifies the full name of the weekday.

DD
Specifies the numerical date of the month.

month
Specifies the three-character abbreviation of the month.

YYYY
Specifies the four-character number of the year.

HH:MM:SS
Specifies the timestamp with hours, minutes, and seconds.

domain = domain_name
Specifies the domain attributes of the cookie, for use in domain attribute matching.

path = path
Specifies the subset of URLs in a domain for which the cookie is valid.

secure
Specifies that the cookie is transmitted only over secured channels to HTTPS servers.

When the secure option is not specified, the cookie can be sent over unsecured channels. The secure option does not require that the browser encrypt the cookie, nor does it ensure that the page containing the DTW_SETCOOKIE statement is transmitted over SSL.

For additional information about all of the advanced options, see the Netscape cookie specification at http://home.netscape.com

Return Codes

Table 50. DTW_SETCOOKIE Return Codes
Return Code Explanation
-1001 The server could not process a Net.Data request to allocate memory.
1001 An input parameter contained a NULL value.
1002 An input parameter contained a string value which consisted of the null-terminating character.
1003 An incorrect number of parameters were passed on a function call.
1005 A parameter passed on a function call, required to be a string variable, was of a different variable type.

Usage Notes

  1. If the client Web browser does not support Java Script, the browser does not set the cookie.
  2. Because DTW_SETCOOKIE generates Java Script code, do not call DTW_SETCOOKIE inside a <script> or <noscript> HTML element.
  3. To retrieve a cookie, use the DTW_GETCOOKIE() function. See DTW_GETCOOKIE to learn how to define a cookie.
  4. Define and retrieve a cookie in two separate HTTP requests. Because a cookie is visible only after it has been sent to the client, if a macro tries to get a cookie that was defined in the same HTTP request, you might receive unexpected results.

Examples

Example 1: Defines cookies that contain user ID and password information with the Secure advanced option

@DTW_SETCOOKIE("mycookie_name_for_userID", "User1")
@DTW_SETCOOKIE("mycookie_name_for_password", "sd3dT", "secure")

Example 2: Defines cookies that contain the expiration date advanced option

@DTW_SETCOOKIE("mycookie_name_for_userID", "User1",
   "expires=Wednesday 01-Dec-2010 00:00:00")
@DTW_SETCOOKIE("mycookie_name_for_password", "sd3dT", 
   "expires=Wednesday, 01-Dec-2010 00:00:00;secure")

Function calls should be on one line; the lines are split in this example for formatting purposes.

Example 3: Determines if a cookie for a user exists before gathering user information

%HTML(welcome) {
  <html>
  <body>
  <h1>Net.Data Club</h1>
  @DTW_GETCOOKIE("NDC_name", name)
  %IF ($(RETURN_CODE) == "8000") %{ The cookie is not found. %}
  <form method="post" action="remember">
  <p>Welcome to the club. Please enter your name.<br />
  <input name="name">
  <input type="submit" value="submit"><br />
  </form>
  %ELSE
  <p>Hi, $(name). Welcome back.
  %ENDIF
  </body>
  </html>
  %}

The HTML(welcome) section checks whether the cookie NDC_name exists. If the cookie exists, the browser displays a personalized greeting. If the cookie does not exist, the browser prompts for the user's name, and posts it to the HTML(remember) section. This section records the user's name into the cookie NDC_name as shown below:

%HTML(remember) {
  <html>
  <body>
  <h1>Net.Data Club</h1>
  @DTW_SETCOOKIE("NDC_name", name,
   "expires=Wednesday, 01-Dec-2010 00:00:00;path=/")
  <p>Thank you.</p>
  <p><a href="welcome">Come back</a></p>
  </body>
  </html>
  %}


[ Top of Page | Previous Page | Next Page | Index ]