REQUEST DOCUMENT

#### Search Results

Search

# REQUEST DOCUMENT

`REQUEST` `DOCUMENT FROM` url
| `WITH` `[`with-clause`]` |
| `RETURN` `[`return-clause`]` |
`RESPONSE` http-response-code
`[``GIVING` natural-error-number`]`

Dieses Dokument behandelt folgende Themen:

- Funktion

- Syntax-Beschreibung

- Automatisch erzeugte Header

- URL-Kodierung bei Sonderzeichen

- HTTP/HTTPS Status Codes weitergeleitet und verweigert

- Beispiele

Eine Erläuterung der in dem Syntax-Diagramm verwendeten Symbole entnehmen Sie dem Abschnitt Syntax-Symbole.

Verwandtes Statement: `PARSE JSON` und `PARSE XML`

Gehört zur Funktionsgruppe: Internet und XML

## Funktion

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.

### Einschränkungen für Protokollarten

Aus technischen Gründen wird das HTTPS-Protokoll nur unter z/OS unterstützt.

### Keine Unterstützung von Cookies

Cookies werden nicht unterstützt. Sie werden ignoriert.

## Syntax-Beschreibung

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: `url` ist der URL, der benutzt wird, um auf das Dokument zuzugreifen. Falls `url` eine Internet Protocol Version 6 (IPv6)-Adresse in hexadezimaler Notation ist, müssen Sie die Adresse in eckigen Klammern ([]) einschließen. Siehe auch Beispiel 7 - Get-Anforderung einer IPv6-Adresse an Port-Nummer 8080. Es ist nicht möglich, eine Internet Protocol Version 4 (IPv6)-Adresse in eine IPv6-Adresse einzubetten.
`with-clause` | WITH-Klausel: Siehe `with-clause`.
`return-clause` | RETURN-Klausel: Siehe `return-clause`.
`http-response-code` | RESPONSE: `http-response-code` ist die HTTP/HTTPS Response Status Code-Nummer, die für den Request zurückgegeben wird, zum Beispiel: `200` (Request Completed/Anfrage ausgeführt). 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.

### with-clause

[`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-id` ist die Kennung des Benutzers, die für die Anfrage (Request) benutzt wird.
`user-password` | Benutzer-Passwort: `user-password` ist das Passwort des Benutzers, das für die Anfrage benutzt wird.
`header-name-out` `header-value-out` | HEADER NAME/VALUE-Option: `header-name-out` und `header-value-out` können nur gemeinsam verwendet werden: `header-name-out` ist der Name einer mit dieser Anfrage versandten Header-Variablen. `header-value-out` ist der Wert einer mit dieser Anfrage versandten Header-Variablen. header-name-out: Header-Namen dürfen keinen `CR` (Carriage Return), `LF` (Line Feed) oder Doppelpunkt (:) enthalten. Dies wird nicht vom Statement `REQUEST DOCUMENT` überprüft. Gültige Header-Namen entnehmen Sie den HTTP-Spezifikationen. Aus Gründen der Kompatibilität mit der Web-Schnittstelle können Header-Namen mit Unterstrich (_) anstatt Bindestrich (-) geschrieben werden. (Intern wird der Unterstrich durch einen Bindestrich ersetzt). header-value-out: Header-Werte dürfen nicht `CR`/`LF` enthalten. Dies wird vom Statement `REQUEST DOCUMENT` nicht überprüft. Gültige Header-Werte und -Formate entnehmen Sie den HTTP-Spezifikationen. Siehe auch Automatisch erzeugte Headers.
`outbound-document` | DATA ALL-Option: `outbound-document` ist ein vollständiges Dokument, das versendet werden soll. Dieser Wert ist normalerweise erforderlich für die HTTP `REQUEST-METHOD PUT` (siehe Automatisch erzeugte Headers).
`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: `outbound-document` wird von der Standard-Codepage (Wert der Systemvariablen `*CODEPAGE`) in die Codepage konvertiert, die in `code-page-out` angegeben wird. Kodierung und Charset-Attribute Falls das `outbound-document` eine Kodierung (XML) oder ein "Charset" (HTML) enthält, wird empfohlen, dass der Wert der `ENCODED`-Option den Attribut-Wert des Dokuments abbildet. Beispiel: Wenn ein ausgehendes XML-Dokument die Attribut-Kodierung `="UTF-8"` enthält, kodieren Sie das `REQUEST DOCUMENT`-Statement mit der Option `DATA ALL #DOCUMENT ENCODED CODEPAGE 'UTF-8'`.
`variable-name-out` `variable-value-out` | DATA NAME/VALUE-Option: `variable-name-out` und `variable-value-out` fordern nur spezifische `DATA`-Variablen-Informationen anstelle des vollständigen Dokuments an. Sie dürfen nur zusammen benutzt werden: `data-variable-name` ist der Name der `DATA`-Variablen, die mit dieser Anfrage gesendet werden soll. `data-variable-value` ist der Wert der `DATA`-Variablen, die mit dieser Anfrage gesendet werden soll. Dieser Wert wird für die HTTP `REQUEST-METHOD POST` benötigt (URL-Kodierung nötig, insbesondere das Et-Zeichen, auch kaufmännisches Und-Zeichen genannt, (&), Gleichheitszeichen (=), Prozentzeichen (%). Einschränkung: Wenn `data-variable-name` und `data-variable-value` gegeben sind und die Kommunikation standardmäßig `http://` oder `https://` ist, dann wird die `REQUEST-METHOD POST` (siehe Automatisch erzeugte Headers) mit Content-Typ `application/x-www-form-urlencoded` verwendet. Während der Anfrage werden `data-variable-name` und `data-variable-value` durch Gleichheitszeichen (=) und Et-Zeichen (&) getrennt. Deshalb dürfen diese Operanden keine Gleichheitszeichen (=), Et-Zeichen (&) und, wegen der URL-Kodierung, keine Prozentzeichen (%) enthalten. Dieser werden als reserviert betrachtet und brauchen nicht, wie unter Reservierte Zeichen angegeben, kodiert zu werden.

### return-clause

[`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: `header-all-in` enthält alle mit der HTTP-Response angegebenen Header-Werte. 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 (`LF`). Intern werden alle `CR`/`LF` auf Zeilenvorschub, d.h. `LF`, umgesetzt.
- `header-name-in` `header-value-in` | HEADER NAME/VALUE-Option: `header-name-in` und `header-value-in` geben nur header-spezifische Informationen zurück. Sie können nur gemeinsam verwendet werden: `header-name-in` ist der Name eines mit dieser Anfrage erhaltenen Header. Aus Gründen der Kompatibilität mit dem Web Interface können Header-Namen mit Unterstrich (_) anstatt Bindestrich (-) geschrieben werden. Intern wird der Unterstrich durch einen Bindestrich ersetzt. Wenn `header-name-in` eine Leerzeichenkette ist, werden die Status-Informationen zurückgegeben:
      HTTP/1.0 200 OK
`header-value-in` ist der Skalar- oder Array-Wert, der erforderlich ist, um den mit dieser HTTP-Anfrage zurückgegebenen Header zu erhalten. Eine Array-Definition ist erforderlich, wenn mehr als eine Ausprägung des selben Header erwartet wird, zum Beispiel, bei mehreren Set-Cookie Headers. Nur eine Dimension eines mehrdimensionalen Array darf einen Indexbereich enthalten (siehe Beispiel 9). Ein X-Array muss verwirklicht sein, bevor es benutzt werden kann. Wenn die Anzahl der Ausprägungen die Anzahl der Header übersteigt, werden die nicht benutzten Ausprägungen zurückgesetzt. Wenn die Anzahl der Header die Anzahl der Ausprägungen übersteigt, werden die übrig bleibenden Header ignoriert. Beispiel einer Array-Definition siehe Beispiel 9 - RETURN HEADER NAME VALUE mit Array-Definition.
`inbound-document` | PAGE ALL-Option: `inbound-document` ist das für diese Anfrage zurückgegebene Dokument. Es erfolgt keinerlei Kodierung der zurückgegebenen Seite, d.h., die Seite bleibt so kodiert, wie sie vom HTTP-Server geliefert wird.
`code-page-in` | ENCODED-Option: Bei der Datenübertragung mit dem `REQUEST DOCUMENT`-Statement erfolgt normalerweise keine Codepage-Konvertierung. Wenn Sie herein kommenden Daten in einer bestimmten Codepage kodieren möchten, können Sie die `ENCODED`-Option benutzen: Falls nötig, wird das `inbound-document` in der Standard-Codepage (Wert der Systemvariablen `*CODEPAGE`) der Natural-Session kodiert. Wenn der Wert von `code-page-in` leer ist, dann wird `inbound-document` von der Codepage, die mit dem Schlüsselwort-Subparameter `RDCP` definiert ist, in die Standard-Codepage (A/B) oder (U) kodiert. Der Schlüsselwort-Subparameter `RDCP` des Profilparameters `XML` wird benutzt, um den Namen der Standard-HTML/XML-Codepage anzugeben. Anmerkung "Returned MIME type contains an encoding" bedeutet, dass der HTTP-Server einen Content Type Header mit einer Klausel `charset=` zurückgibt, zum Beispiel: `charset=ISO-8859-1`. Beispiele für die Verwendung der Klausel `RETURN PAGE ENCODED` siehe unter Beispiel 8 - RETURN PAGE ENCODED-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 `REQUEST DOCUMENT`-Statement einen Parameter, der den Typ des Inhalts des angeforderten Dokuments (MIME-Typ, auch bekannt als Internet-Media-Typ) angibt. Dieser Parameter kann Informationen über die Codepage enthalten, in der das Dokument kodiert ist. `mime-type` ist die Liste der MIME-Typen, für die eine Kodierung des zurück gegebenen Dokuments `inbound-document` ausgeführt wird. Falls der zurückgegebene MIME-Typ eine Kodierung enthält, wird das `inbound-document` von dieser Codepage in die Standard-Codepage (A/B) oder (U) kodiert. Falls der zurückgegebene MIME-Typ keine Kodierung enthält, dann wird das `inbound-document` von der mit `code-page-in` definierten Codepage in die Standard-Codepage (Wert der Systemvariablen `*CODEPAGE`) (A/B) oder (U) kodiert. 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 `mime-type` gegebenen Typen übereinstimmt. Wird eine Übereinstimmung festgestellt, dann wird `inbound-document` von der mit `code-page-in` definierten Codepage in die Standard-Codepage (A/B) oder (U) kodiert.

## Automatisch erzeugte Header

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.

- HTTP REQUEST-METHOD

- Content-Typ

### HTTP REQUEST-METHOD

Das `REQUEST DOCUMENT`-Statement unterstützt folgende `REQUEST-METHOD`s: `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-METHOD`s können in einem `REQUEST-METHOD` Header die Methoden `DELETE`, `PATCH`, `OPTIONS` und `TRACE` angegeben werden.

#### Erläuterung:

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`.

### Content-Typ

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

## URL-Kodierung bei Sonderzeichen

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:

- Nicht-ASCII-Zeichen

- Nicht eindeutige Zeichen

- Reservierte Zeichen

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.

### Nicht-ASCII-Zeichen

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`.

### Nicht eindeutige Zeichen

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

### Reservierte Zeichen

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

## HTTP/HTTPS Status Codes weitergeleitet und verweigert

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:

- Statuscodes 301 - 303 (redirected/weitergeleitet)

- Statuscode 401 (denied/verweigert, unauthorized/nicht authentifiziert)

### Statuscodes 301 - 303 (redirected/weitergeleitet)

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.

### Statuscode 401 (denied/verweigert, unauthorized/nicht authentifiziert)

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.

## Beispiele

- Beispiel 1 — Allgemeiner Request

- Beispiel 2 — Einfacher GET-Request (keine Daten)

- Beispiel 3 — Einfacher HEAD-Request (keine zurückgelieferte Seite)

- Beispiel 4 — Einfacher POST-Request (Standard-REQUEST-METHOD)

- Beispiel 5 — Einfacher PUT-Request (mit DATA ALL)

- Beispiel 6 — REQUEST DOCUMENT mit Proxy-Autorisation

- Beispiel 7 — GET-Request einer IPv6-Adresse an Port-Nummer 8080

- Beispiel 8 — RETURN PAGE ENCODED-Klausel

- Beispiel 9 - RETURN HEADER NAME VALUE mit Array-Definition

Anmerkung
Es gibt einen Beispiel-Dialog `V5−RDOC` für dieses Statement in der Beispiel-Library `SYSEXV`.

### Beispiel 1 — Allgemeiner Request

    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

### Beispiel 2 — Einfacher GET-Request (keine Daten)

    REQUEST DOCUMENT FROM "http://pcnatweb:8080"
      RETURN
        PAGE #Resultxml
    RESPONSE #rc

### Beispiel 3 — Einfacher HEAD-Request (keine zurückgelieferte Seite)

    REQUEST DOCUMENT FROM "http://pcnatweb"
    RESPONSE #rc

### Beispiel 4 — Einfacher POST-Request (Standard-REQUEST-METHOD)

    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

### Beispiel 5 — Einfacher PUT-Request (mit DATA ALL)

    REQUEST DOCUMENT FROM "http://pcnatweb/test.txt"
      WITH
        DATA ALL     #document
      RETURN
        PAGE #Resultxml
    RESPONSE #rc

### Beispiel 6 — REQUEST DOCUMENT mit Proxy-Autorisation

    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

### Beispiel 7 — GET-Request einer IPv6-Adresse an Port-Nummer 8080

    REQUEST DOCUMENT FROM "http://[2BFC:5022:4081:0000::C:41]:8080"
      RETURN
        PAGE #Resultxml
    RESPONSE #rc

### Beispiel 8 — RETURN PAGE ENCODED-Klausel

1. 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.

2. 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.

### Beispiel 9 - RETURN HEADER NAME VALUE mit Array-Definition

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

### On this page

- Funktion
- Syntax-Beschreibung
- Automatisch erzeugte Header
- URL-Kodierung bei Sonderzeichen
- HTTP/HTTPS Status Codes weitergeleitet und verweigert
- Beispiele