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