Please enable JavaScript to view this site.

A-Shell Consolidated Reference

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)  [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). 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.

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. Also supports Customizing GET Headers.

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

 

Comments

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.

 

See Also

EXLIB:[908,25] for several other examples.

History

Subtopics

HTTP Properties Parameter

ATE

Customizing POST headers

Customizing GET Headers

Customizing REQUPLOAD Headers

SOAP Example

Debugging HTTP.SBR

Retrieving HTTP status text

Connection Failure Codes