XOBWLIB ICR (5421)

Name

Value

NUMBER

5421

IA #

5421

DATE CREATED

2009/03/20

CUSTODIAL PACKAGE

WEB SERVICES CLIENT

USAGE

Supported

TYPE

Routine

ROUTINE

XOBWLIB

NAME

XOBWLIB

GENERAL DESCRIPTION

Public APIs for the HWSC package.

STATUS

Under Revision

DURATION

Till Otherwise Agreed

XOBWLIB

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

$$GETPROXY

$$GETPROXY (web service name, web server name)

Returns a Cache web service client proxy object for the specified web service,
ready to invoke web service methods on the specified web server. Use this
method to obtain a web service proxy if you are going to invoke web service
methods on a single server only.

VARIABLES

TYPE

VARIABLES DESCRIPTION

web service name

Input

first input parameter, name of of entry in WEB
SERVICE (#18.02) file.

web server name

Input

Name of entry in WEB SERVER (#18.12) file.

return value

Output

Web service client proxy object ready to invoke web
service methods on the specified web server.

$$GENPORT

$$GENPORT (.infoarray)

Use in installation post-init routines to import a WSDL file and run the Cachi
WSDL import wizard. This call runs the Cache SOAP client wizard to create
proxy classes for communicating with an external web service, using the web
service's WSDL file. Creates entry for web service in file #18.02, WEB
SERVICE.

VARIABLES

TYPE

VARIABLES DESCRIPTION

infoarray

Input

pass by reference. set up array as follows:

infoarray("WSDL FILE")  WSDL file location on host operating system

infoarray("CACHE PACKAGE NAME") Package name to place generated Cache classes
in.

infoarray("WEB SERVICE NAME"):  Name to store web service information in file
#18.02 (WEB SERVICE) - used for lookups, should be namespaced for your
application.

infoarray(""AVAILABILITY RESOURCE"")    (optional) resource for HWSC to access
via an HTTP GET when checking if the web service is available. HWSC appends
the resource to the IP address and context root of the web service.

return value

Output

Success:        positive value Failure:
0^failure description

REGSOAP

REGSOAP (wsname, wsroot, class, [path], [resource])

Use in installation post-init routines to register a web service by creating
an entry in the WEB SERVICE file (#18.02), without calling the Cache WSDL
compiler. Typical use cases would be:

1. Compiled classes are exported for install on the target system rather than
just a WSDL, because classes were manually modified by development team after
initial import.

2. A site calls the WSDL import wizard itself to create a client to a web
service, and needs to create a Web Service entry to associate with the
imported classes.

VARIABLES	TYPE	VARIABLES DESCRIPTION
wsname	Input	first input parameter. Web Service name.
wsroot	Input	second input parameter. Web Service root (without trailing '/').
class	Input	third input parameter: Cache package + class name of the main class created for the web service client proxy, as created by the Cache WSDL compiler. NOTE: The WSDL compiler uses the value of the name attribute (of the port element, within the service element, in the WSDL file) as the name for the main class it creates.
path	Input	fourth input parameter (optional). WSDL file location on host operating system (WSDL file is copied into Web Service file entry.)
resource	Input	fifth input parameter (optional): Resource for HWSC to access via an HTTP GET when checking if the web service is available. HWSC appends the resource to the IP address and context root of the web service.

UNREG

UNREG (service name)

Use in installation post-init routines to un-register/delete a web service
entry in the WEB SERVICE file (#18.02). Can be either a SOAP or REST web
service. Also removes the service from any web servers it is authorized to.

VARIABLES	TYPE	VARIABLES DESCRIPTION
servicename	Input	SOAP or REST Web Service Name (entries in File #18.02).

$$GETREST

$$GETREST (service name, server name)

Return REST service request object. Use to make GET, POST and PUT calls to the
specified service and server.

VARIABLES	TYPE	VARIABLES DESCRIPTION
service name	Input	REST Web Service Name (entry File #18.02).
server name	Input	Web Server Name (entry in File #18.12).
return value	Output	REST service request (xobw.RestRequest) object.

$$GET

$$GET (RestRequest, resource, [.error], [ForceError])

Make HTTP GET call and (by default) force an error trap if problem
encountered.

VARIABLES	TYPE	VARIABLES DESCRIPTION
RestRequest	Input	xobw.RestRequest object.
Resource	Input	resource string to use with GET method.
error	Input	(optional) where to store any error encountered (pass by ref) - errors returned as an xobw.error object.
ForceError	Input	(optional) force error trap (1) or not (0). Defaults to 1.
returnvalue	Output	True if succeeded, false if an error occurred. NOTE: If ForceError is set to 1, a $ECODE is thrown and the return value QUIT is never reached.

$$POST

$$POST (RestRequest, Resource, [.error],
[ForceError])

Make HTTP POST call and (by default) force an error trap if problem
encountered.

VARIABLES	TYPE	VARIABLES DESCRIPTION
RestRequest	Input	xobw.RestRequest object.
Resource	Input	resource string to use with POST method.
error	Input	(optional) where to store any error encountered (pass by ref) - errors returned as an xobw.error object.
ForceError	Input	(optional) force error trap (1) or not (0). Defaults to 1.
returnvalue	Output	True if succeeded, false if an error occurred. NOTE: If ForceError is set to 1, a $ECODE is thrown and the return value QUIT is never reached.

$$HTTPCHK

$$HTTPCHK (RestRequest, [.error], [ForceError])

Check HTTP status after a GET, POST, or PUT operation has completed; if HTTP
status code indicated condition other than success, create an HttpError object
and return false.

VARIABLES	TYPE	VARIABLES DESCRIPTION
RestRequest	Input	xobw.RestRequest object.
error	Input	(optional) where to store any error encountered (pass by ref) - errors returned as an xobw.error object.
ForceError	Input	(optional) force error trap (1) or not (0). Defaults to 1.
returnvalue	Output	True if HTTP status judged OK, false if a condition other than success occurred. NOTE: If ForceError is set to 1, a $ECODE is thrown and the return value QUIT is never reached.

$$HTTPOK

$$HTTPOK (http status code)

Check HTTP status after a GET, POST, or PUT operation has completed; if HTTP
status code indicated condition other than success, return false.

VARIABLES	TYPE	VARIABLES DESCRIPTION
http status code	Input	String containing HTTP status code (e.g., from xobw.RestRequest.HttpResponse.StatusCode).
returnvalue	Output	True if HTTP status judged OK, false if a condition other than success occurred.

$$EOFAC

$$EOFAC ([SOAP proxy object])

For use in error trap handlers during SOAP and REST web services calls, to
make it easy to process error conditions. Creates an error object based on the
error condition in the partition, representing a SOAP, Cachi Object, HWSC
dialog, or basic M error. Includes special parsing for <ZSOAP> web service
errors.

Intended for use in an error trap handler, i.e., a known error condition is
already present in the partition.

VARIABLES

TYPE

VARIABLES DESCRIPTION

SOAP proxy object

Input

(optional) SOAP proxy object (if making a SOAP call).

returnvalue

Output

Cachi Object representing the trapped and parsed
error (assumes EOFAC^XOBWLIB is being called in an error trap handler) is an
instance of one of the following classes in the "xobw.error" package:

BasicError: basic M/ Cache error DialogError: HWSC fault with corresponding
DIALOG file (#.84) entry ObjectError: Cache Object-level error SoapError: SOAP
fault returned from web service invocation AbstractError: base class for all
error types

$$EOSTAT

$$EOSTAT (status object)

Create ObjectError from Cache status (%Library.Status) object.

VARIABLES	TYPE	VARIABLES DESCRIPTION
status object	Input	Cache %Library.Status object.
returnvalue	Output	xobw.error.ObjectError object.

$$EOHTTP

$$EOHTTP (response object)

Create HttpError object from Cache %Net.Response object.

VARIABLES	TYPE	VARIABLES DESCRIPTION
response object	Input	%Net.HttpResponse object (e.g., from xobw.RestRequest.HttpResponse).
returnvalue	Output	xobw.error.HttpError object.

ERRDISP

ERRDISP (error object)

Does a simple display of an error's information to the screen. "Error Object"
should be of the type xobw.error.AbstractError or one of its descendants.

VARIABLES	TYPE	VARIABLES DESCRIPTION
error object	Input	Any HWSC error object in the xobw.error package.

ERR2ARR

ERR2ARR (error object, .return array)

Decomposes an error object into an M array carrying the various components of
the error object. "Error Object" is should be of the type
xobw.error.AbstractError or one of its descendants.

VARIABLES

TYPE

VARIABLES DESCRIPTION

error object

Input

Any HWSC error object in the xobw.error package.

return array

Both

(pass by ref) Array in which to return the decomposed
components of the error object.

Different array nodes are returned depending on the type of xobw.error object
passed in:

xobw.error.BasicError:
ARRAY("errorType") = type of error (BASIC, DIALOG)
ARRAY("code") = error code
ARRAY("text") =
ARRAY("text",i..n) =

xobw.error.DialogError:
ARRAY("errorType") = type of error (BASIC, DIALOG)
ARRAY("code") = error code
ARRAY("text") =
ARRAY("text",i..n) =

xobw.error.HttpError:
ARRAY("errorType") = type of error (HTTP)
ARRAY("code") = error code
ARRAY("statusLine") = error dcode
ARRAY("text") =
ARRAY("text",i..n) =

xobw.error.ObjectError:
ARRAY("errorType") = type of error (OBJECT)
ARRAY("code") = error code
ARRAY("dcode") = error dcode
ARRAY("domain") = error domain
ARRAY("text") =
ARRAY("text",i..n) =

xobw.error.SoapError:
ARRAY("errorType") = type of error (SOAP)
ARRAY("soapFaultType") = SOAP Fault Type
ARRAY("faultactor") = SOAP fault actor
ARRAY("faultcode") = SOAP fault code
ARRAY("faultstring") = SOAP fault string
ARRAY("detail") = SOAP fault detail
ARRAY("text") =
ARRAY("text",i..n) =

$$STATCHK

$$STATCHK (status object, [.error], [ForceError])

Check Cache %Library.Status status object (returned by many Cache Object
calls); if not OK create ObjectError object and return false.

VARIABLES	TYPE	VARIABLES DESCRIPTION
status object	Input	Cache %Library.Status object.
error	Input	(optional) where to store any error encountered (pass by ref) - errors returned as an xobw.error object
forceerror	Input	(optional) force error trap (1) or not (0). Defaults to 1.
returnvalue	Output	True if succeeded, false if an error occurred. NOTE: If ForceError is set to 1, a $ECODE is thrown and the return value QUIT is never reached.

ZTER

ZTER (error object)

Performs two functions:

1. Decomposes error object into an XOB-namespaced M array carrying the various
components of the error object.

2. Calls Kernel error trap to record error.

It is useful to decompose the error into an M array before calling the Kernel
error trap, because otherwise the Cachi Object error information is not
captured in the error trap.

VARIABLES

TYPE

VARIABLES DESCRIPTION

error object

Input

Any HWSC error object in the xobw.error package
(should be of the type xobw.error.AbstractError or one of its descendants).

XOB-namespaced array

Output

Array contains different nodes depending on
xobw.error subclass type of input parameter:

xobw.error.BasicError:
ARRAY("errorType") = type of error (BASIC, DIALOG)
ARRAY("code") = error code
ARRAY("text") =
ARRAY("text",i..n) =

xobw.error.DialogError:
ARRAY("errorType") = type of error (BASIC, DIALOG)
ARRAY("code") = error code
ARRAY("text") =
ARRAY("text",i..n) =

xobw.error.HttpError:
ARRAY("errorType") = type of error (HTTP)
ARRAY("code") = error code
ARRAY("statusLine") = error dcode
ARRAY("text") =
ARRAY("text",i..n) =

xobw.error.ObjectError:
ARRAY("errorType") = type of error (OBJECT)
ARRAY("code") = error code
ARRAY("dcode") = error dcode
ARRAY("domain") = error domain
ARRAY("text") =
ARRAY("text",i..n) =

xobw.error.SoapError:
ARRAY("errorType") = type of error (SOAP)
ARRAY("soapFaultType") = SOAP Fault Type
ARRAY("faultactor") = SOAP fault actor
ARRAY("faultcode") = SOAP fault code
ARRAY("faultstring") = SOAP fault string
ARRAY("detail") = SOAP fault detail
ARRAY("text") =
ARRAY("text",i..n) =

$$SKEYADD

$$SKEYADD (key name, [description], [.error])

Add a new server lookup key, or edit an existing one.

VARIABLES	TYPE	VARIABLES DESCRIPTION
key name	Input	Name of server lookup key.
description	Input	(optional) Brief description of lookup key.
error	Both	(optional) location to return error description (pass by reference) - returned as array node(s) starting at error(1)
return value	Output	if successful: IEN of new or existing entry (always > 0) if unsuccessful: 0 (Also, error description node(s) are returned in optional error parameter.)

$$SNAME4KY

$$SNAME4KY (key name, .retvalue, [.error])

Retrieve the server name associated with a server lookup key.

VARIABLES	TYPE	VARIABLES DESCRIPTION
key name	Input	Name of server lookup key.
retvalue	Both	Storage location to return server name if successful (pass by reference).
error	Both	(optional) location to return error information in if failure (pass by reference). [error format]: error code^error text. Possible errors: 186008^description (invalid key) 186009^description (server association missing)
return value	Output	if successful: IEN of new or existing entry (always > 0) (and the matching server name is returned in the "server name" parameter) if unsuccesful: 0 Also, an error is returned in the optional error parameter.

ATTACHDR

ATTACHDR (proxy object)

Attach a "VistaInfoHeader" header block to outgoing web service request.  It
can be processed by the receiving web service as a SOAP header by using a
handler. This header block contains partition and Kernel environment variables
as follows:

duz: the user's DUZ value mio: the partition's $IO value mjob: the partition's
$JOB value production: "1" if the calling VistA system is a production system,
"0" if test.  station: station # (currently the Kernel site parameter default
institution value) vpid: the user's VPID

VARIABLES	TYPE	VARIABLES DESCRIPTION
proxy object	Input	SOAP web service client proxy object.

REGREST

REGREST (service name, context root, [resource])

Use in installation post-init routines to register a REST service by creating
an entry in the WEB SERVICE file (#18.02).

VARIABLES

TYPE

VARIABLES DESCRIPTION

service name

Input

REST Web Service Name (entry in File #18.02).

context root

Input

Context Root for the REST service (without leading or
trailing '/' characters)

resource

Input

resource for HWSC to access via an HTTP GET when
checking if the web service is available. HWSC appends the resource to the IP
address and context root of the web service.

DATE ACTIVATED

2009/06/16