SEND

Send an HTTP request.

UHTTP.SEND(URL, Method, Username, Password, Headers, Content, Response )

Parameters

Parameter Type Direction Description
URL string IN URL to which the HTTP request should be sent.
Method string IN HTTP request method, for example, GET, POST, PUT, DELETE, HEAD, and so on.

The value of HttpRequestMethod is not checked. See HTTP Request Methods.

Username string IN User names for the web server (as specified by URL) or proxy server, or both. Optionally, for each user, the authentication method to be used on the server can also be specified. Maximum of 1024 bytes.

{ProxyUser{(scheme=ProxyAuthentication)};} {WebServerUser{(scheme=WebServerAuthentication)}}

If Username is not specified, anonymous access will take place.

See User Credentials and Authentication.

Password string IN Password to be used on the web server or proxy server, or both. This can be a single value specifying the web server password, a Uniface list specifying both the proxy server password and the web server user. Maximum of 1024 bytes.

{ProxyServerPassword;} {WebServerPassword}

See User Credentials and Authentication.

Headers string INOUT Uniface list of HTTP headers to be sent. After calling SEND, it contains the optional returned HTTP headers. See Headers and Content.
Content string INOUT Content to be sent with the HTTP request. After calling SEND, it contains optional returned documents. See Headers and Content.
Response string OUT Status line of the returned response.

Return Values

Values Returned in $status
Value Meaning
200 Success
1 More data to be read
-10 URL is not valid
-11 The SEND operation has timed out
-12 An internal error occurred. If the request is an HTTPS request, the certification may be incorrectly configured. As an alternative, use the SET_FLAGS.
-13 Request is invalid
-14 Instance has unread response data

If $status does not contain any of these values, it contains an HTTP response code, as returned by the remote resource. The first digit of the status code defines the class of response:

  • 1xx: Informational—request received, continuing process.
  • 2xx: Success—action was successfully received, understood, and accepted.
  • 3xx: Redirection—further action must be taken in order to complete the request.
  • 4xx: Client Error—the request contains bad syntax or cannot be fulfilled.
  • 5xx: Server Error—the server failed to fulfill an apparently valid request.

For more information on responses, consult the HTTP/1.1 specification: http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6

Description

The SEND operation is used to send an HTTP request to a given URL. The request can contain both headers and content, which need to be prepared using ProcScript and other UTTP operations before calling the SEND operation. Credentials (Username and Password) can be passed along with the request to be verified by the remote resource. You can further control the behavior of the SEND operation using the SET_FLAGS operation.

The SEND operation can be called only if there are no pending results from a prior request.

HTTP Request Methods

The HTTP 1.1 specification defines the semantics of common request methods, but more methods are being registered all the time. For more information on supported request methods, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods.

The semantics of some methods are not strictly defined. For example, the GET method should return response body content, but it is not defined whether content can be sent in the request. Some web servers may reject the request, others (like the Uniface Web Application Server) ignore it, and still others may use it.

The SEND operation will send both headers and content, if they are available, regardless of the Method selected. It is the developer's responsibility to determine what needs to be sent, based on the HTTP specification and how it is applied by the web server.

For historical reasons, there is a difference in behavior on Windows and Unix when using the POST method:

  • On Unix platforms, when the POST method is used, the header Content-Type: application/x-www-form-urlencode is automatically added if no Content-Type header is specified in the Headers parameter.
  • On Windows, no Content-Type header is added.

Note:  To ensure that the default behavior is the same on all platforms, it is recommended that you set the logical UHTTP_WPOST_FORM = T in your assignment file. This ensures that the default Content-Type header is added for POST requests on both Uniface and Windows platforms.

Headers and Content

Before calling SEND, you can prepare the Headers and Content to be sent with the request. A response can be generated by the resource, consisting of optional HTTP headers and an optional document, which are returned in Headers and Content parameters after the request has been sent.

Content cannot be specified in the following cases:

  • When using the file operations such as LOAD_FILE_CONTENTS and DUMP_FILE_CONTENTS.
  • When using the following methods, which do not allow a content body to be sent:

    • HEAD
    • DELETE
    • TRACE
    • LINK

The UNLINK method does allow a content body, but it has no defined semantics.

When Content is sent, the header Expect: 100-continue is added to a POST method if the content length is greater than 1024 bytes. This header is always added to other methods when Content is sent.

The Expect: 100-continue header is an HTTP 1.1 header, so if you are sending directly to an HTTP 1.0 server, you need to suppress it by explicitly adding "Expect" as an item (with no value) in the header list when constructing the list of headers.

Note:  However, when sending to an HTTP 1.0 proxy, the HTTP 1.1 header is not suppressed, and the proxy server may reject the request. For example, if Content is sent with a GET method to a HTTP 1.0 proxy server, the proxy server may reject the request because it does not accept Content with a GET request, or because it does not accept the header, or it may accept both.

If Content exceeds 10 MB, it must be read in segmented fashion using the READ_CONTENT operation. If it exceeds this range, the SEND operation notifies the client application by returning 1 (UHTTP_MORE_AVAILABLE) in $status.

It is possible to call the WRITE_CONTENT function to construct payloads exceeding 10 MB. Contents passed with the SEND operation are appended to contents passed by WRITE_CONTENT.

Using SEND

The following example shows how you can instantiate the UHTTP component and send an HTTP request:

variables
   handle  vUHTTP
   numeric vStatus
   string  vURI, vUser, vPassword, vHeaders, vContent, vResponse
endvariables
newinstance "UHTTP", vUHTTP

vURI = "http://mysite.com/op1"
vUser = "myname(scheme=L)"
vPassword = "mypassword"

;Create list of headers 
putitem/id vHeaders, "Content-Type", "application/soap+xml; charset=UTF-8"
putitem/id vheaders, "Accept-Charset", "ISO-8859-1 ; q = 0.4, UTF-16BE; q=0.9"

;Assemble content and assign to vContent ...
...

; Call the UHTTP.SEND operation
vStatus = vUHTTP->SEND(vURI, "POST", vUser, vPassword, vHeaders, vContent, vResponse)
...

User Credentials and Authentication

The SEND operation sends requests to a web server, often via a proxy server. One or both servers may require user credentials to authenticate the request.

User and password credentials can be provided using the Username and Password arguments. If no Username is provided, any supplied password is ignored.

If Username and Password are specified, they can contain a single value, or a Uniface list of two items. The first item is for a proxy server (if used) and the second item is for the web server, as specified by the URL parameter.

User Name and Password Parameters for UHTTP
Parameter Content Value
Username Single value for web server WebServerUser{(scheme=WebServerAuthentication)}
List for proxy server ProxyUser{(scheme=B | L)};
List for proxy and web servers ProxyUser{(scheme=B | L)};WebServerUser{(scheme=B | L | N)}
  • B (Basic)
  • L (NTLM)
  • N (Negotiate)
Empty (Anonymous access if no default authentication scheme is defined.)
Password Single value for web server WebServerPassword
List for proxy server ProxyPassword;
List for proxy and web servers ProxyPassword;WebServerPassword
Empty (Anonymous access)

For example:

vUsername=""
putitem vUsername, -1, "proxyuser(scheme=B)"
putitem vUsername, -1, "wsuser(scheme=L)"

vPassword=""
putitem vPassword, -1, "proxyPw1"
putitem vPassword, -1, "usPw1"

vStatus = vUHTTP->SEND(vUri, "POST", vUsername, vPassword, vHeaders, vContent, vResponse)

If there is an error in the supplied syntax of the scheme definition, it will not be recognised and be treated as part of the user name.

For more information, see Authentication with UHTTP.

Calling SEND from Server Pages

In a web application, the process responsible for executing the SEND operation is the WASV Uniface Server (userver), running under the its own account (for example, userver or UnifaceServer). In normal client/server applications it is uniface (or ide) running under a local account. If your LAN configuration uses proxy configuration to control access to the internet, it is likely that the Uniface Server account is not included. This can create problems when a server page (DSP or USP) has to call the SEND operation, which requires internet access.

You can configure the WASV to run under a user account that is allowed internet access:

  1. In the web.xml file (for example, in the uniface\webapps\uniface\WEB-INF directory of the default Uniface installation), find the WASV definition. For example:
    <param-name>MIDDLEWARE</param-name>
    <param-value>UV8:localhost+13002|UnifaceServer|Uniface_Server123|wasv</param-value>
  2. Replace UnifaceServer|Uniface_Server123 with your UserName|Password and save the changes.
  3. Restart the Web Server.
  4. Windows only: Add your user account to the Uniface Server users group. For more information, see Authorizing Users on Microsoft Windows Platforms.

Sending an HTTP Request and Reading the Response

The following example demonstrates how send an HTTP request and read the response when it exceeds 10 MB.

entry uHttpCallOut
params
  string pUrl         : IN
  string pUsername    : IN
  string pPassword    : IN
  string pHttpHeader  : INOUT
  string pHttpContent : INOUT
endparams
variables
  string vMoreContent, vResponse
endvariables

  activate "UHTTP".send(pUrl, "GET", pUsername, pPassword, pHttpHeader, pHttpContent, vResponse)
  while ($status = 1)
    activate "UHTTP".read_Content(vMoreContent)      ; get more data from UHTTP buffer
    pHttpContent = $concat(pHttpContent, vMoreContent)
  endwhile
  if ($status < 0)
    message/error $concat("UHTTP error:%%^", $status)
  else
    message/info $concat("UHTTP success:%%^", $status)  ; 200
  endif
  return 0
end