HTTP

Parameters

opcode  (Num)  [in]

1 (XHTTPOP_REQ) = general HTTP request. Opcode must be set to "1" in all cases.

status  (Signed Num)  [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

flags  (Num)  [in]

sum of options flags. These flags are listed in ashinc: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 for customizing them.
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.
XHTTPF_REQHEAD	&h00000008	Makes the request a HEAD request
XHTTPF_REQXML	&h00000010	Deprecated. Use XHTTPF_REQPOST + XHTTPF_HDRBODY instead; see Customizing POST headers. Old description: Makes the request a POST using text/xml content
XHTTPF_REQGET	&h00000020	Simple GET (text of HTML page)
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.
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 1.4.132.
HTTPF_SSL_TLS1	&h00010000	XHTTPF_SSL modifier: request TLS 1.0 or higher
HTTPF_SSL_SSL2	&h00020000	XHTTPF_SSL modifier: request SSL 2.0
HTTPF_SSL_SSL3	&h00040000	XHTTPF_SSL modifier: request SSL 3.0
HTTPF_SSL_PCT1	&h00080000	XHTTPF_SSL modifier: request PCT 1.0
HTTPF_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.
Definition file: http.def

 

url  (String)  [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)  [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). 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. Note that some options only work with file mode, while some may only work with string mode.

response  (String)  [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)  [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 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)  [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

 

Note:

•   Prior to ASHNET 1.4.131, the normal return code for this operation was 0, and errors would return -12. In ASHNET 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] 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.

 

History

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 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.SBR 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.SBR via the new flags XHTTPF_SSL_TLS11 and XHTTPF_SSL_TLS12.

•   Append Connection Failure Codes 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.SBR 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.

2016 November, October, A-Shell 6.3.1535:  Replaced old parameter certfile with new parameter properties and much expanded its usage.

2014 October, A-Shell 6.1.1391:  Increased length of url from 260 to 1064.

2013 June, A-Shell 6.1.1350, ASHNET 1.4.135, which works with A-Shell 6.0 and later: added support for the certfile and certpw parameters. Previously they were ignored.

2012 October/November, A-Shell 6.0.1261 and 1263:  Various changes comprising ASHNET version 1.4.132/2.

2009 September, A-Shell 5.1.1159:  added to A-Shell