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 bezüglich Unicode-Support finden Sie im Abschnitt REQUEST DOCUMENT in der Unicode and Code Page Support-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,*)