REQUEST
DOCUMENT FROM
url
|
|||
WITH
[ with-clause] |
|||
RETURN
[ return-clause] |
|||
RESPONSE
http-response-code
|
|||
[ GIVING
natural-error-number] |
This document covers the following topics:
For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.
Related Statement: PARSE XML
Belongs to Function Group: Internet and XML
The REQUEST DOCUMENT
statement is used to retrieve and upload documents on
the internet as described in REQUEST DOCUMENT in Statements for Internet and XML Access in the
Programming Guide.
For information on Unicode support, see REQUEST DOCUMENT in the Unicode and Code Page Support documentation.
See also the description of the Natural profile and session parameter RQTOUT
, which specifies
the timeouts used for HTTP requests issued internally by the REQUEST
DOCUMENT
statement.
Under the HTTP Protocol, a server uses cookies to maintain state information on the client workstation.
REQUEST DOCUMENT
is implemented using internet option settings. This
means that, depending on the security settings, cookies will be used.
If the internet option setting Disabled
is set, no cookies will be sent,
even if a cookie header (header-name-out/header-value-out
)
is sent.
For server environments, do not use the internet option setting Prompt
.
This setting leads to a "hanging" server, because no client will be able
to answer the prompt.
Cookies are handled automatically by the Windows API. This means that, if cookies are enabled in the browser, all incoming cookies will be saved and sent automatically with the next request.
Operand Definition Table:
Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
url
|
C | S | A | yes | no | ||||||||||||||
http-response-code |
S | I4 | yes | yes | |||||||||||||||
natural-error-number |
S | I4 | yes | no |
Syntax Element Description:
Syntax Element | Description | |
---|---|---|
url
|
Location of Document:
|
|
with-clause |
WITH Clause:
See |
|
return-clause |
RETURN Clause:
See |
|
http-response-code |
RESPONSE:
See also HTTP Responses Redirected and Denied. For a list of possible HTTP status codes, refer to the RFC 2616 memorandum published by the World Wide Web Consortium (W3C). |
|
natural-error-number |
GIVING
Option: natural-error-number
contains the 4-digit Natural error number if the request could not be
performed.
|
[USER
user-id]
|
[PASSWORD
user-password]
|
[HEADER {[NAME ] header-name-out [VALUE ] header-value-out} ...]
|
[DATA {ALL
outbound-document [ENCODED [[IN ] CODEPAGE
code-page-out]]
|
|{[NAME ] variable-name-out [VALUE ] variable-value-out} ...}]
|
The with-clause
is used to specify optional
user/password, header and data details for the request.
An empty with-clause
(that is, no value
specified after WITH
) is ignored.
Operand Definition Table:
Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
user-id
|
C | S | A | yes | no | ||||||||||||||
user-password
|
C | S | A | yes | no | ||||||||||||||
header-name-out
|
C | S | A | yes | no | ||||||||||||||
header-value-out
|
C | S | A | N | P | I | F | D | T | L | yes | no | |||||||
outbound-document
|
C | S | A | U | N | P | I | F | B | D | T | L | yes | no | |||||
code-page-out
|
C | S | A | yes | no | ||||||||||||||
variable-name-out
|
C | S | A | yes | no | ||||||||||||||
variable-value-out
|
C | S | A | N | P | I | F | D | T | L | yes | no |
Syntax Element Description:
Syntax Element | Description | |
---|---|---|
user-id
|
USER:
|
|
user-password
|
PASSWORD:
|
|
header-name-out
|
HEADER NAME/VALUE Option:
header-name-out:
Header names must not contain a carriage return (CR), a line feed (LF) or a
colon (:). This will not be checked by the header-value-out:
Header values are not allowed to contain CR/LF. This will not be checked by
the See also Automatically Generated Headers. |
|
outbound-document
|
DATA ALL Option:
|
|
code-page-out |
DATA ALL ENCODED Option:
Data transfer with the
If the outbound document contains an encoding (XML) or a charset (HTML)
attribute, we recommend that the value of the Example: If an outbound XML document contains the attribute encoding
|
|
variable-name-out
|
DATA NAME/VALUE Option:
Restriction:
If |
[HEADER [ALL
header-all-in] [[NAME ] header-name-in [VALUE ] header-value-in ...]]
|
[PAGE
inbound-document [ENCODED [[FOR
TYPES
mime-type
...] [IN ] CODEPAGE
code-page-in]]]
|
Operand Definition Table:
Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
header-all-in
|
S | A | yes | yes | |||||||||||||||
header-name-in
|
C | S | A | yes | no | ||||||||||||||
header-value-in
|
S | A * | A | N | P | I | F | B | D | T | L | yes | yes | ||||||
inbound-document
|
S | A | U | B | yes | yes | |||||||||||||
mime-type
|
C | S | A | yes | no | ||||||||||||||
code-page-in |
C | S | A | yes | no |
This clause can be used to specify return information for the headers and/or the document.
Syntax Element Description:
Syntax Element | Description | |
---|---|---|
header-all-in |
HEADER ALL Option:
The first line contains the status information and all following lines contain the headers as pairs of name and value. The names always end in a colon (:) and the values end in a line feed (LF). Internally, all carriage returns/line feeds (CR/LF) are transformed into line feeds (LF). |
|
header-name-in
|
HEADER NAME/VALUE Option:
|
|
inbound-document |
PAGE Option:
|
|
code-page-in |
PAGE ENCODED
Option:
Data transfer with the If necessary,
If
the value of Note: |
|
mime-type |
PAGE ENCODED FOR TYPES Option:
As a response of an HTTP/HTTPS request, incoming data may contain binary data
(for example, image/gif) or character data (for example, text/html). Together
with the response, the If the returned MIME type contains an encoding,
If the returned MIME type does not contain an encoding, then
If the returned MIME type does not contain an encoding, then an additional
check is performed if the returned MIME type matches one of the types given
with |
For an HTTP request, some headers are required, for example: REQUEST-METHOD
or content type. These headers will be automatically generated depending on the parameters
given with the REQUEST DOCUMENT
statement.
Note:
It is possible to overwrite the automatically generated headers. Natural will not
check them for errors. Unexpected errors may occur.
The REQUEST DOCUMENT
statement supports the following HTTP
REQUEST-METHOD
s: HEAD
, POST
, GET
and PUT
.
The following table shows the HTTP REQUEST-METHOD
generated depending on
the given operands:
WITH HEADER |
WITH DATA |
RETURN HEADER |
RETURN PAGE |
|
HEAD | o | - | x | - |
---|---|---|---|---|
POST | o | x | o | x |
GET | o | - | o | x |
PUT | o | DATA ALL
* |
o | o |
In addition to the standard REQUEST-METHOD
s mentioned above, the
method DELETE
can be specified in a REQUEST-METHOD
header.
o | Optional. Operand can be optionally specified. |
- | Operand cannot be specified. |
x | Operand is always specified. |
* | Only applies to DATA ALL and not DATA
NAME VALUE .
|
The REQUEST-METHOD
POST
requires a content-type header for the HTTP request. If no
content type is explicitly specified, Natural inserts the following default content-type
header into the request:
application/x-www-form-urlencoded
When sending POST
data with the content type
application/x-www-form-urlencoded
, certain characters must be represented
by means of URL encoding, which means substituting the character with
%hexadecimal-character-code
. Some basic
details are given here:
For full details of when and why URL encoding is necessary, refer to the memorandums RFC 1630, RFC 1738 and RFC 1808 published by the World Wide Web Consortium (W3C).
All non-ASCII characters (that is, valid ISO 8859/1 characters that are not also ASCII
characters) must be URL encoded, for example, the file köln.html
would
appear in an URL as k%F6ln.html
.
URL encode the following unsafe characters when you request web pages to avoid server failures:
Unsafe Character | URL Encoding |
---|---|
the tab character | %09 |
the space character | %20 |
[ | %5B |
\ | %5C |
] | %5D |
^ | %5E |
` | %60 |
{ | %7B |
| | %7C |
} | %7D |
~ | %7E |
Some characters have special meanings in URLs, such as the colon (:) that separates the URL scheme from the rest of the URL, the double slash (//) that indicates that the URL conforms to the Common Internet Scheme syntax and the percent sign (%). Generally, when these characters appear as parts of file names, they must be URL encoded to distinguish them from their special meaning in URLs (this is a simplification, refer to the RFCs mentioned earlier for full details).
Reserved characters are:
Reserved Character | URL Encoding |
---|---|
" | %22 |
# | %23 |
% | %25 |
& | %26 |
+ | %2B |
, | %2C |
/ | %2F |
: | %3A |
< | %3C |
= | %3D |
> | %3E |
? | %3F |
@ | %40 |
For a list of HTTP status codes, refer to the RFC 2616 memorandum published by the World Wide Web Consortium (W3C).
The following special considerations apply to the HTTP responses for redirected and denied requests:
The HTTP response codes 301, 302 and 303 mean that the URL where the requested document
resides has changed and that the request was therefore redirected to another URL. As a
response, the return header with the name LOCATION
will be displayed. This
header contains the URL where the requested page has moved to. A new REQUEST
DOCUMENT
request can be used to retrieve the page moved.
HTTP browsers redirect automatically to the new URL, but the REQUEST
DOCUMENT
statement does not handle redirection automatically.
The HTTP response code 401 means that the requested page can only be accessed if a
valid user ID and password are provided with the request. As a response, the return
header with the name WWW-AUTHENTICATE
will be delivered with the REALM
needed for this request.
HTTP browsers normally display a dialog with user ID and password, but with the
REQUEST DOCUMENT
statement, no dialog is displayed.
Note:
There is an example dialog V5-RDOC
for this statement in the example
library SYSEXV
.
REQUEST DOCUMENT FROM "http://bolsap1:5555/invoke/sap.demo/handle_RFC_XML_POST" WITH USER #User PASSWORD #Password DATA NAME 'XMLData' VALUE #Queryxml NAME 'repServerName' VALUE 'NT2' RETURN PAGE #Resultxml RESPONSE #rc
REQUEST DOCUMENT FROM "http://pcnatweb:8080" RETURN PAGE #Resultxml RESPONSE #rc
REQUEST DOCUMENT FROM "http://pcnatweb" RESPONSE #rc
REQUEST DOCUMENT FROM "http://pcnatweb/cgi-bin/nwwcgi.exe/sysweb/nat-env" WITH DATA NAME 'XMLData' VALUE #Queryxml NAME 'repServerName' VALUE 'NT2' RETURN PAGE #Resultxml RESPONSE #rc
REQUEST DOCUMENT FROM "http://pcnatweb/test.txt" WITH DATA ALL #document RETURN PAGE #Resultxml RESPONSE #rc
DEFINE DATA LOCAL 1 #FROM (A) DYNAMIC 1 #HEADER (A) DYNAMIC 1 #PAGE (A) DYNAMIC 1 #COOKIES (A20/1:3,1:4,2:5) 1 #RC (I4) END-DEFINE ASSIGN #FROM = 'http://www.myserver.com' REQUEST DOCUMENT FROM #FROM RETURN HEADER NAME 'Set-Cookie' VALUE #COOKIES(1,2:3,3) PAGE #PAGE RESPONSE #RC PRINT #COOKIES(*,*,*) END
In the example program above, invalid array definitions (with multiple dimensions) would be:
RETURN HEADER NAME 'Set-Cookie' VALUE #COOKIES(1:3,2:3,3) RETURN HEADER NAME 'Set-Cookie' VALUE #COOKIES(*,2,*)