WSDrvr Services

After 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 not attempt to modify these values as it will adversely affect their web service.

The Web Service Helper Functions are described 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 VTScada 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 enables 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 enables 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 Schema Cache Dictionary 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 Schema Cache Dictionary object as desired. Each Web Service has its own ClassFactory object 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 parent XMLNode provided and of the size specified.
Returns: Invalid.
Usage: Script
Format: \WSDrvr\MakeTypeArray(pParent, Namespace, Name, Size, MemberNamespace, MemberName);
Parameters:  
pParent
A pointer to the XMLNode where the array will be added.
Namespace
The namespace of the array type.
Name
The name of the array.
Size
The size of the array.
MemberNamespace
The namespace of the member type.
MemberName
The name of the member type
Comments: The function creates an array of the specified size under a member called Name in the parent XMLNode. If the MemberName can be found in the schema cache under the MemberNamespace, then each element of the array will be of the specified type. Otherwise, it will be a plain XMLNode.

\WSDrvr\MakeTypeInstance

Description: The MakeTypeInstance function creates a copy of an XMLNode representing an XMLType.
Return Value: The XMLNode representing the type or invalid if the type cannot be found.
Usage: Script
Format: \WSDrvr\MakeTypeInstance(Namespace, Name)
Parameters:  
Namespace
The namespace of the type
Name
The name of the type
Comments: This function creates a clone of the XMLType specified by Name in the Namespace. If the type doesn't exist in the Namespace or the Namespace doesn't exist in the Schema Namespace Cache (ClassFactory) then invalid is returned.

\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.
Return Value: Invalid
Usage: Script
Format: \WSDrvr\ReportFault(Description, Detail, ProcessFault);
Parameters:  
Description
A string describing the fault.
Detail
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.

\WSDrvr\GetAttValue

Description: GetAttValue returns the value of the specified XML attribute (stored as value metadata) within a particular tag representation.
Usage: Script
Return Value: The value of the attribute if found, otherwise Invalid
Format: \WSDrvr\GetAttValue(pTag, Name, NameSpace);
Parameters:  
pTag
A pointer to the variable to be inspected.
Name
The name of the attribute to be retrieved.
NameSpace
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.
A QName is a qualified name. For example, <tns:myElement tns:myAttrib="abc">. In this case "tns:myAttrib" is the QName. Thus, if a Namespace is provided, then the prefix for that namespace is looked up and preprended to the name and then tried first when searching for an attribute. If not found, then the plain Name is used.