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 explanations 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,*)