REQUEST DOCUMENT FROM
url
|
|||
|
|
WITH
[with-clause] |
|
|
|
|
RETURN
[return-clause] |
|
|
RESPONSE http-response-code
|
|||
[GIVING
natural-error-number] |
|||
Dieses Dokument behandelt folgende Themen:
Eine Erläuterung der in dem Syntax-Diagramm verwendeten Symbole entnehmen Sie dem Abschnitt Syntax-Symbole.
Verwandtes Statement: PARSE
XML
Gehört zur Funktionsgruppe: Internet und XML
Mit dem Statement REQUEST DOCUMENT haben Sie die
Möglichkeit, im Internet Dokumente abzurufen und hoch zu laden. Siehe auch
Statements für Internet- und
XML-Zugang im Leitfaden zur
Programmierung.
Informationen zur Unicode-Unterstützung siehe Unicode- und Codepage-Unterstützung in der Natural-Programmiersprache, Abschnitt Natural-Statements, Unterabschnitt REQUEST DOCUMENT in der Unicode- und Codepage-Unterstützung-Dokumentation.
Aus technischen Gründen wird das HTTPS-Protokoll nur unter z/OS unterstützt.
Cookies werden nicht unterstützt. Sie werden ignoriert.
Operanden-Definitionstabelle:
| Operand | Mögliche Struktur | Mögliche Formate | Referenzierung erlaubt | Dynam. Definition | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
url
|
C | S | A | ja | nein | ||||||||||||||
http-response-code |
S | I4 | ja | ja | |||||||||||||||
natural-error-number |
S | I4 | ja | nein | |||||||||||||||
Syntax-Element-Beschreibung:
| Syntax-Element | Beschreibung | |
|---|---|---|
url
|
Adresse des Dokuments:
Falls Es ist nicht möglich, eine Internet Protocol Version 4 (IPv6)-Adresse in eine IPv6-Adresse einzubetten. |
|
with-clause |
WITH-Klausel:
Siehe |
|
return-clause |
RETURN-Klausel:
Siehe |
|
http-response-code |
RESPONSE:
Siehe auch HTTP/HTTPS Status Codes weitergeleitet und verweigert. Eine Liste der möglichen HTTP/HTTPS Status Codes finden Sie unter dem RFC 2616 Memorandum, das vom World Wide Web Consortium (W3C) publiziert wird. |
|
natural-error-number |
GIVING-Option: natural-error-number
enthält die vierstellige Natural-Fehlernummer, wenn die Anfrage nicht
ausgeführt werden konnte.
|
|
[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}
...}]
|
Sie können die with-clause
benutzen, um optional Benutzer/Passwort, Header und Einzelheiten zu den Daten
für die Anfrage anzugeben.
Eine leere with-clause
wird ignoriert (d.h., wenn nach WITH kein Wert angegeben
wird).
Operanden-Definitionstabelle:
| Operand | Mögliche Struktur | Mögliche Formate | Referenzierung erlaubt | Dynam. Definition | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
user-id
|
C | S | A | ja | nein | ||||||||||||||
user-password
|
C | S | A | ja | nein | ||||||||||||||
header-name-out
|
C | S | A | ja | nein | ||||||||||||||
header-value-out
|
C | S | A | N | P | I | F | D | T | L | ja | nein | |||||||
outbound-document
|
C | S | A | U | N | P | I | F | B | D | T | L | ja | nein | |||||
code-page-out
|
C | S | A | ja | nein | ||||||||||||||
variable-name-out
|
C | S | A | ja | nein | ||||||||||||||
variable-value-out
|
C | S | A | N | P | I | F | D | T | L | ja | nein | |||||||
Syntax-Element-Beschreibung:
| Syntax-Element | Beschreibung | |
|---|---|---|
user-id
|
Benutzerkennung:
|
|
user-password
|
Benutzer-Passwort:
|
|
header-name-out
|
HEADER NAME/VALUE-Option:
header-name-out:
Header-Namen dürfen keinen header-value-out:
Header-Werte dürfen nicht
Siehe auch Automatisch erzeugte Headers. |
|
outbound-document
|
DATA ALL-Option:
|
|
code-page-out |
DATA ALL
ENCODED-Option: Bei der Datenübertragung mit dem REQUEST
DOCUMENT-Statement erfolgt normalerweise keine Codepage-Konvertierung.
Wenn Sie ausgehende Daten in einer bestimmten Codepage kodieren möchten, müssen
Sie die CODEPAGE-Option benutzen:
Kodierung und
Charset-Attribute
Falls das
Beispiel: Wenn ein ausgehendes XML-Dokument die
Attribut-Kodierung |
|
variable-name-out
|
DATA NAME/VALUE-Option:
Einschränkung:
Wenn
Während der Anfrage werden
|
|
[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]]]
|
Operanden-Definitionstabelle:
| Operand | Mögliche Struktur | Mögliche Formate | Referenzierung erlaubt | Dynam. Definition | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
header-all-in
|
S | A | ja | ja | |||||||||||||||
header-name-in
|
C | S | A | ja | nein | ||||||||||||||
header-value-in
|
S | A * | A | N | P | I | F | B | D | T | L | ja | ja | ||||||
inbound-document
|
S | A | U | B | ja | ja | |||||||||||||
mime-type
|
C | S | A | ja | nein | ||||||||||||||
code-page-in |
C | S | A | ja | nein | ||||||||||||||
Mit der return-clause
können Sie die Return-Informationen für die Headers und/oder das Dokument
angeben.
Syntax-Element-Beschreibung:
| Syntax-Element | Beschreibung | |
|---|---|---|
header-all-in |
HEADER ALL-Option:
Die erste Zeile enthält die Status-Informationen, und
alle folgenden Zeilen enthalten die Headers als Paare mit Namen und Werten. Die
Namen enden immer auf einen Doppelpunkt (:), und die Werte enden mit einem
Zeilenvorschub ( |
|
header-name-in
|
HEADER NAME/VALUE-Option:
|
|
inbound-document |
PAGE ALL-Option:
|
|
code-page-in |
ENCODED-Option:
Bei der Datenübertragung mit dem Falls nötig, wird das
Wenn der Wert von
Anmerkung: Beispiele für die Verwendung der Klausel |
|
mime-type |
FOR TYPES-Option:
Die als Antwort auf eine HTTP/HTTPS-Anfrage
eintreffenden Daten können Binärdaten enthalten (z.B. Bilddaten/gif) oder
Zeichendaten (z.B. Text/html). Zusammen mit der Antwort erhält das
Falls der zurückgegebene MIME-Typ eine Kodierung
enthält, wird das Falls der zurückgegebene MIME-Typ keine
Kodierung enthält, dann wird das
Falls der zurückgegebene MIME-Typ keine
Kodierung enthält, dann erfolgt eine zusätzliche Prüfung, ob der zurückgegebene
MIME-Typ mit einem der in |
|
Für eine HTTP-Anfrage werden einige Headers benötigt, z.B.
REQUEST-METHOD oder Content Type. Diese Headers werden in
Abhängigkeit von den Parametern, die mit dem REQUEST
DOCUMENT-Statement mitgegeben werden, automatisch erzeugt.
Anmerkung:
Es ist möglich, die automatisch erzeugten Headers zu
überschreiben. Natural prüft diese jedoch nicht auf Fehler. Es können
unerwartete Fehler auftreten.
Das REQUEST DOCUMENT-Statement unterstützt folgende
REQUEST-METHODs: HEAD, POST,
GET und PUT.
Die folgende Tabelle zeigt die HTTP REQUEST-METHOD,
die in Abhängigkeit von den gegebenen Operanden erzeugt wird:
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 |
Zusätzlich zu den oben aufgeführten
Standard-REQUEST-METHODs können in einem
REQUEST-METHOD Header die Methoden DELETE,
PATCH, OPTIONS und TRACE angegeben
werden.
| o | Optional. Operand kann optional angegeben werden. |
| - | Operand kann nicht angegeben werden. |
| x | Operand wird immer angegeben. |
| * | Betrifft nur DATA ALL und
nicht DATA NAME VALUE.
|
Die REQUEST-METHOD POST erfordert einen Content Type
Header für die HTTP-Anfrage. Wenn kein Content Type Header explizit angegeben
wird, fügt Natural den folgenden Standard Content Type Header in die Anfrage
ein:
application/x-www-form-urlencoded
Wenn POST-Daten mit dem Content-Typ
application/x-www-form-urlencoded gesendet werden, müssen
bestimmte Zeichen mittels URL-Kodierung dargestellt werden, was bedeutet, dass
das Zeichen ersetzt wird durch
%hexadecimal-character-code.
Nachfolgend sind einige grundsätzliche Informationen aufgeführt:
Ausführliche Informationen, wann und warum eine URL-Kodierung notwendig ist, finden Sie in den Memoranden RFC 1630, RFC 1738 and RFC 1808, die vom World Wide Web Consortium (W3C) veröffentlicht werden.
Alle Nicht-ASCII-Zeichen (d.h., gültige ISO 8859/1-Zeichen, die
nicht ebenfalls ASCII-Zeichen sind) müssen URL-kodiert werden. Beispielsweise
erscheint die Datei köln.html in einer URL als
k%F6ln.html.
Um Server-Fehler zu vermeiden, sollten Sie nicht eindeutige Zeichen URL-kodiert angeben:
| Nicht eindeutiges Zeichen | URL-Kodierung |
|---|---|
| Tabulatorzeichen | %09 |
| Leerzeichen | %20 |
| [ | %5B |
| \ | %5C |
| ] | %5D |
| ^ | %5E |
| ` | %60 |
| { | %7B |
| | | %7C |
| } | %7D |
| ~ | %7E |
Einige Zeichen haben spezielle Bedeutungen in URLs, z.B. der Doppelpunkt (:), der das URL-Schema vom Rest des URLs abtrennt, der doppelte Schrägstrich (//), der angibt, dass der URL der Common Internet Scheme-Syntax entspricht, und das Prozentzeichen (%). Wenn diese Zeichen als Teile von Dateinamen erscheinen, müssen sie generell URL-kodiert werden, um sie von ihrer Sonderbedeutung in URLs zu unterscheiden (dies ist eine vereinfachte Erklärung, vollständige Informationen finden Sie in den RFCs).
Reservierte Zeichen sind:
| Reserviertes Zeichen | URL-Kodierung |
|---|---|
| " | %22 |
| # | %23 |
| % | %25 |
| & | %26 |
| + | %2B |
| , | %2C |
| / | %2F |
| : | %3A |
| < | %3C |
| = | %3D |
| > | %3E |
| ? | %3F |
| @ | %40 |
Eine Liste der HTTP/HTTPS Status Codes finden Sie im Memorandum RFC 2616, das vom World Wide Web Consortium (W3C) publiziert wird.
Bei HTTP/HTTPS-Status Codes für umgeleitete oder zurückgewiesene Anfragen gelten folgende Besonderheiten:
Die HTTP Status Codes 301, 302 oder 303 bedeuten, dass sich der
URL, unter dem sich das Dokument befindet, geändert hat und dass die Anfrage
deshalb an einen anderen URL per Umleitung weitergeleitet wurde. Als Statuscode
wird der Rückgabe-Header mit dem Namen LOCATION (Adresse)
angezeigt. Dieser Header enthält den URL, wohin die angeforderte Seite
umgezogen ist. Es kann eine neue REQUEST DOCUMENT-Anfrage benutzt
werden, um die umgezogene Seite zu suchen.
HTTP-Browser leiten automatisch zum neuen URL weiter, aber das
Statement REQUEST DOCUMENT nimmt die Weiterleitung nicht
automatisch vor.
Der HTTP Status Code 401 bedeutet, dass die angeforderte Seite nur
aufgerufen werden kann, wenn mit der Anfrage eine gültige Benutzerkennung und
ein gültiges Passwort angegeben werden. Als Rückmeldung wird der
Rückgabe-Header mit dem Namen WWW−AUTHENTICATE mit dem für diese
Anfrage erforderlichen REALM (Bereich) übermittelt.
HTTP-Browser zeigen üblicherweise einen Dialog mit Benutzerkennung
und Passwort an, aber beim Statement REQUEST DOCUMENT wird kein
Dialog angezeigt.
Beispiel 3 — Einfacher HEAD-Request (keine zurückgelieferte Seite)
Beispiel 4 — Einfacher POST-Request (Standard-REQUEST-METHOD)
Beispiel 7 — GET-Request einer IPv6-Adresse an Port-Nummer 8080
Anmerkung:
Es gibt einen Beispiel-Dialog V5−RDOC für dieses
Statement in der Beispiel-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 #URL (A) DYNAMIC
1 #PAGE (A) DYNAMIC
1 #HTTPSTAT (I4)
1 #PATH (A) DYNAMIC
1 #NAME (A) DYNAMIC
1 #VALUE (A) DYNAMIC
1 #USERID (A8)
1 #PASSWORD (A8)
1 #AUTHHDR (A) DYNAMIC
1 #CREDENTIALS (A) DYNAMIC
1 #PADDCHAR (A2/0:2) INIT <' ','==','='>
1 #LENGTH (I4)
1 #FACTOR (I4)
1 #REMAINDER (I4)
/*
/* #USR4210
1 PARM-FUNCTION (A2) INIT <'BA'>
1 PARM-RC (I4)
1 PARM-ERRTXT (A72)
1 PARM-A (A) DYNAMIC
1 PARM-B (B) DYNAMIC
1 PARM-RFC (B1)
END-DEFINE
**
ASSIGN #URL = 'http://www.softwareag.com/corporate/default.asp'
REQUEST DOCUMENT FROM #URL
RETURN PAGE #PAGE ENCODED CODEPAGE ' '
RESPONSE #HTTPSTAT
*************************************************************
** HTTP response 407 means, that the proxy server requires **
** the client to identify itself! **
*************************************************************
IF #HTTPSTAT = 407
INPUT 'Please enter userid and password' (AD=I) /
'Userid :' #USERID / 'Password:' #PASSWORD
ASSIGN #AUTHHDR = 'Proxy-Authorization'
COMPRESS #USERID ':' #PASSWORD INTO PARM-B LEAVING NO
*************************************************************
** Convert credentials to ASCII **
*************************************************************
MOVE ENCODED PARM-B TO PARM-B
CODEPAGE 'ASCII'
*************************************************************
** ENCODE CREDENTIALS WITH BASE64 **
*************************************************************
** BASE64 demands that the length of the encoded string is **
** a multiple of 3. If encoding length does not match this **
** the encoded string has to be padded with '=' characters.**
** Since USR4210 does not support padding of the base64 **
** string with trailing '=' characters, we have to do this **
** our selfs. **
*************************************************************
CALLNAT 'USR4210N' PARM-FUNCTION PARM-RC PARM-ERRTXT PARM-B PARM-A
PARM-RFC
*
#LENGTH := *LENGTH(PARM-A)
WRITE PARM-A (AL=40) #LENGTH EJECT
DIVIDE 3 INTO #LENGTH GIVING #FACTOR REMAINDER #REMAINDER
COMPRESS PARM-A #PADDCHAR(#REMAINDER)
INTO #CREDENTIALS LEAVING NO
*************************************************************
** Build Proxy-Authorization HTTP header **
*************************************************************
COMPRESS 'Basic ' #CREDENTIALS
INTO #CREDENTIALS
ASSIGN #AUTHHDR = 'Proxy-Authorization'
*************************************************************
** Repeat HTTP request with valid client identification **
*************************************************************
REQUEST DOCUMENT FROM #URL
WITH HEADER NAME #AUTHHDR VALUE #CREDENTIALS
RETURN PAGE #PAGE ENCODED CODEPAGE ' '
RESPONSE #HTTPSTAT
END-IF
END
REQUEST DOCUMENT FROM "http://[2BFC:5022:4081:0000::C:41]:8080"
RETURN
PAGE #Resultxml
RESPONSE #rc
Server gibt einen Header zurück: 'Content-type:
text/html;charset=UTF-8'
Programmcode-Beispiel 1:
... RETURN PAGE inbound-document
Resultierende Verarbeitung:
inbound-document
remains UTF-8 encoded.
Programmcode-Beispiel 2:
... RETURN PAGE inbound-document ENCODED [..]
Resultierende Verarbeitung:
inbound-document wird
unabhängig davon, ob code-page-in und
mime-type angegeben werden, von UTF-8
in die Standard-Codepage umgesetzt. Wenn im Content Type Header eine gültige
Kodierung zurückgeliefert wird, werden
mime-type und
code-page-in ignoriert.
Server liefert einen Header zurück: 'Content-type:
text/xml'
Programmcode-Beispiel 1:
... RETURN PAGE inbound-document ENCODED
Resultierende Verarbeitung:
inbound-document wird
nicht umgesetzt, weil der Content Type-Header keine gültige Kodierung enthält.
Programmcode-Beispiel 2:
... RETURN PAGE inbound-document ENCODED FOR TYPES 'text/xml' IN CODEPAGE 'USASCII'
Resultierende Verarbeitung:
inbound-document wird
von USASCII-Codepage in die Standard-Codepage umgesetzt. In diesem Fall erfolgt
die Umsetzung gemäß der Annahme des Programmierers über die Kodierung der
empfangenen Seite.
Programmcode-Beispiel 3:
...
RETURN PAGE inbound-document ENCODED FOR TYPES 'text/html'
IN CODEPAGE ' '
Resultierende Verarbeitung:
inbound-document wird
nicht umgesetzt, weil der in mime-type
angegebene MIME-Typ 'text/html' nicht mit dem im Content Type
Header angegebenen Mime-Typ 'text/xml' übereinstimmt.
Programmcode-Beispiel 4:
... RETURN PAGE inbound-document ENCODED IN CODEPAGE ' '
Resultierende Verarbeitung:
inbound-document wird
von der mit dem Subparameter RDCP des Profilparameters
XML angegebenen Standard-Codepage in die
Standard-Codepage umgesetzt.
Anmerkung:
Der Standardwert für den
RDCP-Subparameter, der gültig ist, wenn nichts anderes
explizit angegeben wird, ist ISO-8859-1. Siehe auch
Statements PARSE XML und REQUEST
DOCUMENT aktivieren/deaktivieren in der
Parameter-Referenz-Dokumentation.
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
Im obigen Beispiel-Programm wären die folgenden Array-Definitionen (mit mehreren Dimensionen) ungültig:
RETURN HEADER NAME 'Set-Cookie' VALUE #COOKIES(1:3,2:3,3) RETURN HEADER NAME 'Set-Cookie' VALUE #COOKIES(*,2,*)