As noted in VTS Web Service Commands, once a web service is successfully registered via SetWSDL, a variable named “WSDrvr” is added to the connected module. This variable exposes a set of data points for use by the web service and the WebService functions, as well as a small group of helper functions. The data points are presented to the web service on a READ ONLY basis – developers should never attempt to modify these values as it will adversely affect their web service. The helper functions are presented following the data points:
Web Service Data Points
\WSDrvr\Realm: This is a copy of the realm name to which the web service is attached.
\WSDrvr\Rscope: This is an object reference to the connected module.
\WSDrvr\WSDL: A copy of the WSDL in use. This has not been converted into VTS format; it is a raw text dump.
\WSDrvr\XMLHandle: The XML processor used for this web service, it contains the basic schemas for SOAP processing as well as a schema-converted version of the WSDL.
\WSDrvr\MsgNamespace: The target namespace of the WSDL, used by all messages and operations.
\WSDrvr\XMLns: A list of “xmlns:” declarations delineating all of the namespaces used in the WSDL and basic SOAP schemas (and therefore all namespaces usable by this web service). Any messages generated by this service must have at least a subset of these declarations attached.
\WSDrvr\NSminus: Due to a rule of SOAP 1.1, the tags in a response message to a SOAP request should not (and in most cases must not) have namespace prefixes if they are declared in the “MsgNamespace”. This is a list of all other namespace / prefix pairs declared for the service and is used to generate output messages.
\WSDrvr\Nsp: This object allows rapid conversion of namespaces to prefixes. It consists of a group of variables with names matching the namespaces declared for this web service (note that these contain “illegal” variable name characters, and can only be referenced via the Scope keyword), the value of each being a string containing the prefix associated with that namespace.
\WSDrvr\Pfx: This object allows rapid conversion of prefixes to namespaces. It consists of a group of variables with names matching the namespace prefixes declared for this web service, the value of each being a string containing the namespace name itself.
\WSDrvr\CallIdx: An object containing linkage data between messages and modules. This is of use only to the WebService functions.
\WSDrvr\ClassFactory: The XML Class Factory object used by the Web Service connected to the given module, it can be used to instantiate any of the types in any of the schemas registered by this service. The user of this service is free to add additional schemas to the ClassFactory object as desired. This object is generated without a static module, so any modifications will not survive VTS shutdown. Each Web Service has its own ClassFactory object in order to prevent a single damaged service from affecting others.
Web Service Helper Functions
\WSDrvr\MakeTypeArray
Description: The MakeTypeArray function creates a SOAP 1.1 compliant array within the variable provided and of the size specified.
Format: \WSDrvr\MakeTypeArray(pParent, Namespace, Name, Size, MemberNamespace, MemberName);
Parameters: pParent is a pointer to the module where the array will be added
Namespace is the namespace of the array type
Name is the name of the array
Size is the size of the array
MemberNamespace is the namespace of the member type
MemberName is the name of the member type
Comments: This function supports only single-dimension arrays (vectors), and does not support the sparse array format (part of the SOAP 1.1 array standard). Unlike normal VTS arrays, this does support arrays of zero length. Note that the encoding of a SOAP 1.1 array is slightly peculiar when viewed from VTS, as the array has a “container” object and the array itself is actually a variable within that object. Technically this "container" object can have any number of sub-modules, all of which should be considered part of the same array. MakeTypeArray, however, only creates a single sub-module for the sake of simplicity. As a result the variable provided is assigned the container object, and the array is instantiated within. Each array element can be assigned an object of a requested type, but by default is invalid.
Return Value: Invalid.
MakeTypeArray may only be called in a script.
\WSDrvr\ReportFault
Description: Used to raise an engine level SOAP fault from within the service, causing the next processing phase to abort and a SOAP fault packet to be returned to the client.
Format: \WSDrvr\ReportFault(Description, Detail, ProcessFault);
Parameters: Description is a string describing the fault
Detail is a string providing extra detail information
ProcessFault 0 indicates an input problem, 1 indicates a processing problem.
Comments: The SOAP fault can be attributed to either local web service processing or poor input data from the client. Detailed fault information must be added to the message.
Return Value: Invalid
ReportFault may only be called in a script.
\WSDrvr\GetAttValue
Description: GetAttValue returns the value of the specified XML attribute (stored as value metadata) within a particular tag representation
Format: \WSDrvr\GetAttValue(pTag, Name, NameSpace);
Parameters: pTag is a pointer to the variable to be inspected.
Name is the name of the attribute to be retrieved.
NameSpace is the namespace of the member type.
Comments: The tag representation may functionally be any variable. The name of the attribute to retrieve is first attempted to be resolved as a full QName, and if no match is found then just the name of the attribute is resolved. QName construction is first attempted by using the NameSpace parameter, and then by getting the namespace of the tag.
Return Value: The value of the attribute if found, otherwise Invalid
GetAttValue may only be called in a script.