# HTTP

> [HTML Version](http_sbr.htm)

_Updated October 2022; see History_

HTTP handles various kinds of HTTP requests. See the subtopics listed at the bottom of this page for in-depth comments.

**xcall HTTP, opcode, status, flags, url, request, response \{,properties, certpw\}**

**Parameters**

_opcode_  ([Num](num.md))  \[in\]

1 (XHTTPOP\_REQ) = general HTTP request. _Opcode_ must be set to "1" in all cases.

_status_  (Signed [Num](num.md))  \[out\]

0 = ok (for simple functions)

\>0 = response code returned from HTTP server. It generally means that operation succeeded in communicating with the server. Whether that represents an unqualified success will depend on the application and the body of the response. Note that these HTTP response codes are standardized; detailed descriptions can be found by searching the Internet for "HTTP Response Codes".

<0 = Operational errors; see [ashinc:HTTP.DEF](https://bitbucket.org/microsabio/soslib/src/master/907016/http.def)

_flags_  ([Num](num.md))  \[in\]

sum of options flags. These flags are listed in [ashinc:HTTP.DEF](https://bitbucket.org/microsabio/soslib/src/master/907016/http.def).

| **Symbol** | **Value** | **Description** |
|------|------|------|
| XHTTPF\_SSL | \&h00000001 | Use a secure protocol (SSL/TLS) per preference of server. See XHTTPF\_SSL\_xxx below to coerce a particular variation. Note: must be set explicitly (not automatic from "https:" in url). |
| XHTTPF\_REQPOST | \&h00000002 | Send the request as an HTTP POST transaction. Default headers will be automatically generated according to the request document (see _request_ parameter). Add XHTTFP\_DEBUG to see the generated headers in debug.req, and see [Customizing POST headers](customizingpostheaders.md) for customizing them. See History note of April 2025. |
| XHTTPF\_REQUPLOAD | \&h00000004 | Variation of an HTTP POST transaction used exclusively for uploading files containing data (not to be confused with file-based requests). Requires XHTTPF\_FILEREQ. See [Customizing REQUPLOAD Headers](customizingrequpload.md). |
| XHTTPF\_REQHEAD | \&h00000008 | Makes the request a HEAD request. See History note of April 2025. |
| XHTTPF\_REQXML | \&h00000010 | **Deprecated**. Use XHTTPF\_REQPOST + XHTTPF\_HDRBODY instead; see [Customizing POST headers](customizingpostheaders.md). Old description: Makes the request a POST using text/xml content. |
| XHTTPF\_REQGET | \&h00000020 | Simple GET (text of HTML page). Also see XHTTPF\_REQGETX below. |
| XHTTPF\_REQPUT | \&h00000040 | Simple PUT. |
| XHTTPF\_DOWNLOAD | \&h00000080 | Download a file. |
| XHTTPF\_FILEREQ | \&h00000100 | Request arg is a filespec (or list of) not a buffer. |
| XHTTPF\_FILERESP | \&h00000200 | Response arg is a filespec not a buffer. |
| XHTTPF\_DEBUG | \&h00000400 | Outputs copy of the generated request to debug.req; transcript of the transmission and internal calls to debug.log; appends connection summary to ashnet.log. |
| XHTTPF\_HDRBODY | \&h00000800 | Parse file into headers (added individually) and body. See [Customizing POST headers](customizingpostheaders.md). |
| XHTTPF\_PARMBODY | \&h00001000 | Like HDRBODY but use AddParam instead of AddHeader  |
| XHTTPF\_SETFROMURL | \&h00002000 | Extract path and form info from URL for use in the request header. Typically not used with XHTTPF\_REQPOST, since it will strip any ?<suffix> from the resulting POST header. |
| XHTTPF\_FORCEXFR | \&h00004000 | File parms are server-relative; transfer to PC |
| XHTTPF\_REQGETRAW | \&h00008000 | Like XHTTPF\_REQGET (\&h0020) but works around a limitation of XHTTPF\_REQGET in which certain characters outside the range supported by Latin1/ANSI (e.g. Russian or Chinese) would just be dropped from the response. Can also be used to retrieve binary data containing embedded nulls (such as a file), although you must then use XHTTPF\_FILERESP (\&h0200) to write the response to a file. Added in [ASHNET](ashnet.md) 1.4.132. |
| XHTTPF\_SSL\_TLS1 | \&h00010000 | XHTTPF\_SSL modifier: request TLS 1.0 or higher. |
| XHTTPF\_SSL\_SSL2 | \&h00020000 | XHTTPF\_SSL modifier: request SSL 2.0. |
| XHTTPF\_SSL\_SSL3 | \&h00040000 | XHTTPF\_SSL modifier: request SSL 3.0. |
| XHTTPF\_SSL\_PCT1 | \&h00080000 | XHTTPF\_SSL modifier: request PCT 1.0. |
| XHTTPF\_GETSTSTXT | \&h00100000 | Retrieve HTTP status text from last operation.  |
| XHTTPF\_SSL\_TLS11 | \&h01000000 | XHTTPF\_SSL modifier: request TLS 1.1 or higher. |
| XHTTPF\_SSL\_TLS12 | \&h02000000 | XHTTPF\_SSL modifier: request TLS 1.2 or higher. |
| XHTTPF\_REQGETX | \&h01000000 | Implements a more advanced version of the "GET" operation. The main visible difference is that the returned reponse will be more detailed in the case of a successful connection but a failed transaction, due to some kind of logic or validation issue on the server. Also supports [Customizing GET Headers](customizinggetheaders.md). |
| XHTTPF\_NOTLS13 | \&h04000000 | Specifically disables TLS 1.3 negotiation, making 1.2 the highest TLS level supported. This is a workaround for some exotic problems introduced in some server versions of TLS 1.3. |


**Definition file: **[http.def](https://bitbucket.org/microsabio/soslib/src/master/907016/http.def)



_url  _([String](string.md))  \[in\]

Fully qualified URL, with optional path and/or \{:port\}. URL maximum length is 1024. For example:

"http://www.microsabio.net/dist/51dev/temphold/junk.zip"

"https://www.paypal.com"

"http://someserver.com:10080/some/path" (see History notes below)

_request  _([String](string.md))  \[in\]

Contains content of the request, for operations that require it, such as uploading files, POST, etc. Depending on XHTTPF\_FILEREQ flag, may be a string buffer or a filespec (native or A-Shell, but see subtopic [ATE](ate_http.md)). For the XHTTPF\_REQUPLOAD option, can be a list of filespecs with semi-colon delimiters and an optional prefix indicating the content-type of the file and the "name" attribute to associate with it; see [Customizing REQUPLOAD Headers](customizingrequpload.md). Note that some options only work with file mode, while some may only work with string mode. 

_response_  ([String](string.md))  \[in/out\]  (If S,0, must be pre-initialized to desired maximum length)

Returns the body of the response, or in the case of XHTTPF\_GETSTSTXT, the HTTP status text from the _prior_ XCALL HTTP operation. If XHTTPF\_FILERESP is set, then the passed-in value of _response _is interpreted as a filespec (native) and the actual response is written to that file. Otherwise the response is returned in the specified parameter. Beginning with A-Shell 6.4.1555, _response _accepts AMOS-style filespecs; see History note.



_properties  _([String](string.md))  \[in\]

An optional list of name=value clauses delimited by semicolons, e.g.: name1=value;name2=value2,value3;...;nameN=valueN. See the following topic [HTTP Properties Parameter](httppropertiesparameter.md) for a table of _properties_. Note: to maintain backwards compatibility with old and now deprecated _certfile_ parameter and syntax: if there is no "=" (equals sign) character in the string, it will be intepreted as the old _certfile_ spec. 



_certpw  _([String](string.md))  \[in\]

Optional password for the PFX file. See History note of 2022 October.



**Example**

Simple file download: here we download a JPG file from our public server, using XHTTPF\_DOWNLOAD.

\++include ashinc:http.def

map1 params

map2 flags,b,4

map2 url\$,s,100,"http://www.microsabio.net/dist/other/images/EditorShot.jpg"

map2 response\$,s,20,"download.jpg"

map2 status,f



flags = XHTTPF\_DOWNLOAD or XHTTPF\_FILERESP    



xcall HTTP, XHTTPOP\_REQ, status, flags, url\$, "", response\$

? "status: ";status;

if status = 0 or status = 200 then

    ? "ok"

else

    ? "error - ";response\$;" may contain details (as text)"

endif



**Comments**

•	Prior to [ASHNET](ashnet.md) 1.4.131, the normal return code for this operation was 0, and errors would return -12. In [ASHNET](ashnet.md) 1.4.131 and later, it returns HTTP status codes (200 for ok, most everything else would be an error.)

•	In the case of an error, the response file may contain details (in text) rather than the downloaded file.

•	For ATE compatibility, use XCALL ATHTTP instead of XCALL HTTP. ATHTTP also works with local Windows as a pass-through to HTTP.

•	The function [Fn'HttpGet() in SOSLIB:\[907,10\]](https://bitbucket.org/microsabio/soslib/src/master/907010/fnhttpget.bsi) can also download files, although it uses multiple XCALL TCPX operations to do so. The approach shown here is somewhat more efficient when running under Windows, but less efficient under ATE (due to the need to transfer files back and forth between the ATE client and the server).

•	If the URL is https: (secure), simply add the XHTTPF\_SSL flag.



**See Also**

•	[EXLIB:\[908,25\]](https://bitbucket.org/microsabio/exlib/src/master/908025/) for several other examples.

•	[Google Cloud Access Token](googlecloudaccesstoken.md)

**(./images/hmtoggle_arrow0.gif)	History**

2025 April, A-Shell 7.0.1771, ASHNET 1.4.202:  XHTTPF\_REQPOST can now be combined with XHTTPF\_REQHEAD to retrieve both the headers and the body of the response together (separated by a blank line)..

2025 January, A-Shell 7.0.1767, ASHNET 1.4.200:  Add flag XHTTPF\_NOTLS13.

2022 October, A-Shell 6.5.1721, ASHNET 1.4.186:  The _certpw_ parameter now supports all three of the encryption modes supported by MX\_PWCRYPT. Previously it only recognized modes 1 and 2. Note that for mode 3, it assumes the default seed and key. 

2019 April, A-Shell 6.5.1660, ASHNET 1.12.165:  

•	When the XHTTPF\_REQGET call fails, it now returns an abbreviated status message in the response parameter instead of the full library debug string. In cases where the call succeeds in connecting to the endpoint, but the endpoint service then rejects the request, the response will be an HTTP header—e.g. "415 Unauthorized." In the case of a complete failure to connect, the response will be empty or "0". The status parameter will give additional information, as will a subsequent call using XHTTPF\_GETSTSTXT.

•	A new opcode flag, XHTTPF\_REQGETX (\&h01000000) has been defined to implement a more advanced version of the "GET" operation. Currently the main visible difference is that the returned reponse will be more detailed in the case of a successful connection but a failed transaction, due to some kind of logic or validation issue on the server. The [ashinc:HTTP.DEF](https://bitbucket.org/microsabio/soslib/src/master/907016/http.def) file contains the updated symbol definition.

•	You can now include custom headers—using XHTTPF\_HDRBODY—with the string request versions of the XHTTPF\_REQPOST and XHTTPF\_REQGETX operations. Previously this was only possible with XHTTPF\_FILEREQ, file based requests. Format the request string the same way you would the file, i.e. with CRLF between each custom header, then a blank line (terminate by CRLF), then, in the case of \_REQPOST, the body of the request. GET operations have no request body.

2019 April, A-Shell 6.5.1659, ASHNET 1.12.164:  Refinement to HTTP to allow custom headers to be added to a GET request (XHTTPF\_REQGET). Previously this was only possible with the POST request type (XHTTPF\_REQPOST / XHTTPF\_REQUPLOAD). To specify custom headers, set the XHTTPF\_HDRBODY flag and put the new headers into the request\$ parameter, using chr(13) to separate multiple headers, e.g.:

flags = XHTTPF\_REQGET or XHTTPF\_HDRBODY

request\$ = "Referer: http://www.microsabio.com"

request\$ += chr(13) + "User-Agent: A-Shell/ashnet-1.2.164"

...

xcall HTTP, 1, status, flags, url\$, request\$, response\$, properties\$



Note that you must specify at least 7 parameters—i.e., at least thru the properties\$ parameter—even if the properties\$ parameter is blank. Otherwise a more limited version of the routine will be used, which doesn't support this enhancement.

You can also put the custom headers into a file, as you would with XHTTPF\_REQPOST + XHTTPF\_FILEREQ + XHTTPF\_HDRBODY. With the GET request, anything following the first blank line would be ignored.

Note that to examine/debug your headers, set the XHTTPF\_DEBUG flag and then look at the debug.log file on return from the subroutine.

2018 May, A-Shell 6.5.1636, ASHNET 1.11.162:  Several changes:

•	Support secure protocols TLS 1.1 and TLS 1.2 in HTTP via the new flags XHTTPF\_SSL\_TLS11 and XHTTPF\_SSL\_TLS12.

•	Append [Connection Failure Codes](connection_failure_codes.md) to the XHTTPF\_GETSTSTXT return string, as well as the ashnet.log, to assist with debugging failed connections.

•	Remove 100 character limit on header lines included at the top of the request using XHTTPF\_HDRBODY. Maximum length is now unlimited, which is useful when headers include lengthy signatures or digests.

2017 November, A-Shell 6.4.1555:  the _request_ and _response_ parameters now accept AMOS-style filespecs. Previously they were assumed to be in native format, and didn't work properly otherwise.

2017 February, A-Shell 6.3.1544:  HTTP now exposed to Linux via libashnet.so.1.9.157. Also, filespecs passed in the request and response parameters are now folded to lower case. The documentation has always noted that they are to be native filespecs, but since case doesn't matter in the Windows world, folding them to lower avoids a common mistake when porting a working application from Windows to Linux.



**Subtopics**

- [HTTP Properties Parameter](httppropertiesparameter.md)

- [ATE](ate_http.md)

- [Customizing POST headers](customizingpostheaders.md)

- [Customizing GET Headers](customizinggetheaders.md)

- [Customizing REQUPLOAD Headers](customizingrequpload.md)

- [SOAP Example](soapexample.md)

- [Debugging HTTP.SBR](debugginghttp_sbr.md)

- [Retrieving HTTP status text](retrievinghttpstatustext.md)

- [Connection Failure Codes](connection_failure_codes.md)

- [Other HTTP Verbs](other-http-verbs.md)