Kernel Toolkit APIs: $$GETURL^XTHC10

$$GETURL^XTHC10(): Return URL Data Using HTTP

Reference Type: Supported, Category: Toolkit—HTTP Client Helper, ICR#: 5553

Description

The $$GETURL^XTHC10 extrinsic function is a Hypertext Transfer Protocol (HTTP)/1.1 client that can request a Web page from another system and pass the returned data to the calling routine.

It can make both GET and POST requests.

It is the main API and returns in xt8rdat the returned data from the website.

NOTE: XTHC* routines are part of the HTTP Client Helper application for developers.

NOTE: This API was released with Kernel Toolkit Patch XT*7.3*123.

NOTE: This API is IPv6 compliant as of Kernel Toolkit patch XT*7.3*138.

Format

  $$GETURL^XTHC10(url[,xt8flg],xt8rdat,.xt8rhdr[,xt8sdat][,.xt8shdr][,.xt8meth])

Input Parameters

url:	(required) This is the Universal Resource Locator (URL) to access (http://host:port/path). It could be as simple as "www.va.gov".
xt8flg:	(optional) Request timeout. Default is 5 seconds.
xt8sdat:	(optional) Closed root of a variable containing the body of the request message. Data should be formatted as described in the xt8rdat parameter. NOTE: If this parameter is defined (i.e., not empty) and the referenced array contains data, then the POST request is generated; otherwise, the GET request is sent.
.xt8shdr:	(optional) Reference to a local variable containing header values, which is added to the request. For example: XT8SHDR("CONTENT-TYPE")="text/html"
.xt8meth:	(optional) Flag to indicate the request method: GET—Default if xt8sdat contains no data. POST—Default if xt8sdat contains data HEAD PUT OPTIONS DELETE TRACE

Input/Output Parameters

xt8rdat:

(required) Closed root of the variable where the message body is returned. Data is stored in consecutive nodes (numbers starting from 1). If a line is longer than 245 characters, only 245 characters are stored in the corresponding node. After that, overflow sub-nodes are created. For example:

@XT8DATA@(1)="<html>"
@XT8DATA@(2)="<head><title>VistA</title></head>"
@XT8DATA@(3)="<body>"
@XT8DATA@(4)="<p>"
@XT8DATA@(5)="Beginning of a very long line" 
@XT8DATA@(5,1)="Continuation #1 of the long line" 
@XT8DATA@(5,2)="Continuation #2 of the long line" 
@XT8DATA@(5,...)=...
@XT8DATA@(6)="</p>"

.xt8rhdr:

(required) Reference to a local variable where the parsed headers are returned. Header names are converted to uppercase; the values are left "as is". The root node contains the status line. For example:

XT8HDR="HTTP/1.1 200 OK" 
XT8HDR("ACCEPT-RANGES")="bytes" 
XT8HDR("CONNECTION")="close" 
XT8HDR("CONTENT-LENGTH")="16402" 
XT8HDR("CONTENT-TYPE")="text/html; charset=UTF-8" 
XT8HDR("DATE")="Thu, 25 Jun 2015 14:43:01 GMT" 
XT8HDR("ETAG")="a93a2-4012-5180156550680" 
XT8HDR("LAST-MODIFIED")="Mon, 08 Jun 2015 13:08:26 GMT" 
XT8HDR("SERVER")="Apache/2.2.15 (CentOS)"

Output

returns:

Returns:

Success: HTTP_Status_Code^Description

Common HTTP status codes returned:

Status Code	Description
200	OK
301	Moved Permanently
400	Bad Request
401	Unauthorized
404	Not Found
407	Proxy Authentication Required
408	Request Time-out
500	Internal Server Error
505	HTTP Version not supported

Fail: -1^Error Descriptor

Additional error information can be found in the VistA error trap or ^XTER in programmer mode.

REF: For more details, see http://www.faqs.org/rfcs/rfc1945.html or the Internet Engineering Task Force (IETF) sites at: http://www.ietf.org/rfc/rfc2616.txt (HTTP/1.1) and http://www.ietf.org/rfc/rfc2617.txt (HTTP Authentication).