| $$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.
|
|
