Syntax

result = openurl (text, mode)

or (for mode = 3, from Collections 1.16.3 and Designer 7.10.1.5478):

result = openurl (text, mode, tag, occ)

Arguments

text: text (string, string variable, or database field/tag containing the URL to be opened)

mode: 0, 1, 2 or 3 (3 is available from Collections 1.16.3 and Designer 7.10.1.5478)

tag: field tag or FACS alias for a field

occ: target occurrence number of designated field

result: numeric

Meaning

With this function you can only open a web page in a browser. You can only open internet addresses; addresses on your local network or workstation cannot be opened with openurl.

With the second parameter in the call (the mode parameter) you specify whether you just want to check whether the provided URL is valid (mode = 0) or if you'd like to actually open the URL in a browser window (mode = 1): for modes 2 and 3, see paragraphs below.
With 0, openurl checks whether the URL in a field is valid. The resulting numerical value conforms to the W3C http standard; on successful opening of the URL, 200 is returned, while failure returns 404. Besides that, there are dozens of other result codes.
The modes 0 and 1 should be used successively. First, with modus=0, check whether the URL can be opened, and only when result=200 you should actually open the URL with modus=1.

From Collections 1.15 a new mode value 2 has been added to be able to save the response of the call to a file, from a storage adapl, without opening the target in a browser window. The file to which the response is saved can be set using the PDEST … FILE instruction. A code snippet with an Axiell WebAPI call in the OPENURL statement to illustrate how this works, is the following:

text url[0]
text path[0]
numeric result

/* Set storage location for API output
path = '..\result_'+ date$(4) + '.xml'
pdest path file

/* Format the URL
url = 'https://ourserver.com/AxiellAPI/wwwopac.ashx?database=collect&search=all'

/* Open url and store output
result = openurl(url,2)

/* Check if HttpStatusCode OK was returned
if (result <> 200)
{
 errorm 'Error retrieving or writing response = ' + result + ': ' + error$(result)
}

The path used in PDEST for storing the response is relative to the application folder (e.g. \xplus). Note that for security reasons you can’t write files beyond the application root folder. If you try to do that anyway, OPENURL will result in an error 8 (internal error) with some details.

Instead of saving the response of the call to a file, you might want to save the response in a field in the currently processed record or a field in an opened FACS database (whether that field is temporary or not), to be able to access the contents of the response in the adapl itself. For that you can use mode 3. Only when using that mode, you'll need to provide a third and fourth argument to the OPENURL call, specifying the target field tag and the target occurrence number. A response text will only be stored in the field when the response code is 200 (successful). (Any provided third and fourth argument for modes smaller than 3 will be ignored.)

The OPENURL function can also be used in stand-alone adapls.

Examples

IF openurl('https://www.axiell.com/', 0) = 200 THEN {
 openurl('https://www.axiell.com/', 1)
}

or

result = openurl('http://localhost/imageserver/wwwopac.ashx?database=fullCatalogue&search=all%20random%201&fields=title&output=json', 3, TI, 1)

IF (result <> 200) {
  errorm 'Error retrieving content = ' + result + ': ' + error$(result)
}