DTW_GETCOOKIE

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

Purpose

Returns the value of the specified cookie.

Format

@DTW_GETCOOKIE(IN cookie_name, OUT cookie_value)

@DTW_rGETCOOKIE(IN cookie_name)

Parameters

Table 35. DTW_GETCOOKIE 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 OUT A variable containing the value of the cookie retrieved by the function, such as user state information.

OS/400 and OS/390 users: If the cookie value has URL style encodings (for example "%20"), the cookie value is decoded before the value is returned.

Workstation users: If the cookie value has URL style encodings (for example "%20"), the cookie value is not decoded before the value is returned.

Return Codes

Table 36. DTW_GETCOOKIE 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.
1006 A literal string was passed on a function call for a parameter which was required to be an output parameter.
8000 The cookie cannot be found.

Usage Notes

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: Retrieves cookies that contain user ID and password information

@DTW_GETCOOKIE("mycookie_name_for_userID", userID)
@DTW_GETCOOKIE("mycookie_name_for_password", password)

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

%MESSAGE {
    8000 : "" : continue
%}
 
%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.</p>
  %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 form prompts for the user's name, and posts it to the HTML remember section, which sets 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 ]