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
ID XOBWLIB
COMPONENT/ENTRY POINT
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.
CREATOR CLARKE,KYLE E
DBA Comments
7/21/16-MM: Tech writer discovered the HWSC 1.0 Developer's
Guide did not contained two APIs:

5.3.5      $$GETFAC^XOBWLIB(): Return Web Service Proxy Factory
5.4.7      $$GETRESTF^XOBWLIB(): Return REST Service Request Factory

ICR opened for editing.  Associated patch is XOBW*1.0*4.
EDITOR GARCIA,JOSE
DATE ACTIVATED 2009/06/16
MAIL MESSAGE 50288140
DATE/TIME EDITED
DATE/TIME EDITED ACTION AT THE REQUEST OF WITH CONCURRENCE OF
2009/06/16 09:15 APPROVED CLARKE,KYLE
2016/07/21 15:09 DEACTIVATED FOR EDITS GARCIA,JOSE GARCIA,JOSE
Generated from SEP 05, 2018@ IA Listing Descriptions