Toolkit 7.3 APIs Banner [skip navigation]
Office of Information & Technology (OIT) Banner

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

Reference Type: Supported, Category: Toolkit—HTTP Client Helper, Integration Agreement: 5553

Description

The Kernel Toolkit Hypertext Transfer Protocol (HTTP) Client Helper software release adds a new tool in a set of Infrastructure software tools that developers can use. HTTP is a fast and reliable way for an application to collect data from another source. Kernel Toolkit Patch XT*7.3*123 allows VistA to tap into this information and retrieve Web data.

This code was developed by another VistA application that had a pressing need for this capability. The Kernel Toolkit development team is providing it as generic tool so that other developers may use its functionality for their needs. For example:

This extrinsic function returns the HTTP status code and description for the input URL using the HTTP Client Helper 1.0 software. This API was introduced with Kernel Toolkit Patch XT*7.3*123.

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

Format

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

Input Parameters

url:

(required) Universal Resource Locator (URL): http://host:port/path

xt8flg:

(optional) Timeout and flags to control processing. If the value of this parameter starts from a number then this number is used as a value of the timeout (in seconds). Otherwise, the default value of 5 seconds is used.

xt8rdat:

(optional) Closed root of the variable where the message body is returned. Data is stored in consecutive nodes. 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:

(optional) 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.0 200 OK"
XT8HDR("CACHE-CONTROL")="private"
XT8HDR("CONNECTION")="Keep-Alive"
XT8HDR("CONTENT-LENGTH")="2690"
XT8HDR("CONTENT-TYPE")="text/html"
XT8HDR("DATE")="Fri, 26 Sep 2003 16:04:10 GMT"
XT8HDR("SERVER")="GWS/2.1"
xt8sdat:

(optional) Closed root of a variable containing the body of the request message. Data should be formatted as described in the xtT8rdat 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 will be added to the request.

Output

Returns:

Return values:

  • <0—Error Descriptor (see the $$ERROR^XTERROR)

  • >0—HTTP Status Code^Description

The most common HTTP status codes include:

Status Code Description
200 OK.
301 Moved Permanently.

The application should either automatically update the URL with the new one from the Location response header or instruct the user on how to do this.
302 Moved Temporarily.

The application should continue using the original URL.

NOTE: You will not see this code for GET requests. They are redirected automatically.
303 See Other.

The resource has moved to another URL given by the Location response header, and should be automatically retrieved by the client using the GET method. This is often used by a CGI script to redirect the client to an existing file.

NOTE: You will not see this status code, because it is handled automatically inside the function.
400 Bad Request.
404 Not Found.
500 Server Error.

An unexpected server error. The most common cause is a server-side script that has bad syntax, fails, or otherwise cannot run correctly.

REF: For more details, see http://www.faqs.org/rfcs/rfc1945.html

 


VA (Internet) / VA(Intranet) / OI / PD / Site Map / Terms of Use / VA Privacy Policy / Accessibility

Reviewed/Updated: August 26, 2011

If you have questions, need more information, or are having accessibility problems with this website, please contact us by E-Mail: Webmasters, Phone: 510-768-6800, or FAX: 510-768-6850.