Version

The SCEX's Version interface is the simplest contained in the SCEX, and hence makes an ideal starting point. The versions of libraries in use by their host applications is also of critical importance, so let us tackle it now.

Sample Request

All XML requests sent to the SCEX must conform to a document structure that the SCEX expects and can understand. Since the application calling the SCEX is providing the XML data which the SCEX will parse, it is necessary that the calling application create valid XML queries.

The following is a sample SCEX request for version information:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>  
<!DOCTYPE inVERSION SYSTEM "inVERSION.dtd">  
<inVERSION/>  

As this is the first XML message we are documenting, let’s go through this (admittedly small) XML document line by line.

Line 1 is the XML declaration, and will be the same for all requests sent to the SCEX, no matter the loan type and/or data contained within the request. Note that the XML declaration line is optional.

Line 2 is the document type declaration, and will vary depending upon the 'calculation' you wish the SCEX to perform. In this instance, the document type declaration specifies that this XML request is for the Version module, and that the inputs will adhere to the definition found in the DTD (document type definition) file inVERSION.dtd. If you are familiar with DTD files, then you may view each to get a concise (and completely up to date) definition of the input and output XML queries supported by the current version of the SCEX. Note that DTD declaration line is also optional.

Note that the file name inVERSION.dtd is not a fully qualified path name (FQPN). That is, it does not include the entire file system path to the DTD file. If a FQPN is not provided for the DTD, then the SCEX assumes that the DTD is located in the xml directory where the SCEX.DLL is located. If you are using the SCEX in its installed location, then this would be InstallDir\xml\.

Also, please note that the DTD files should never be modified by you unless you have been instructed to do so by Sherman and Associates, Inc. The DTD files describe the valid interface to the SCEX, and if modified, may render the SCEX unable to verify if input and output XML messages are valid.

Line 3 contains the version request in its entirety. The version request is a trivial request, made up of a single element.

Since lines 1 and 2 are optional, an even more compact request that results in the same response is as follows:

<inVERSION/>

Sample Response

After submitting an inVERSION request to the SCEX, and receiving a successful calculation result from the xmlcalc() routine, the buffer for the result XML is ready to be parsed.

The following is a sample XML result generated by the previous sample request, at the time this documentation was being written (2007-01):

<?xml version="1.0" standalone="no" ?>  
<!DOCTYPE outVERSION SYSTEM "outVERSION.dtd">  
<outVERSION>  
  <SCEVersion>N/A</SCEVersion>  
  <SCEVersion>2007.1.0</SCEVersion>  
  <SCEXPath>N/A</SCEXPath>  
  <SCEXPath>C:\Sherman\SCEX\</SCEXPath>  
  <DefaultDataDirPath>C:\Sherman\SCEX\</DefaultDataDirPath>  
  <CurrentPath>C:\Sherman\SCEX\</CurrentPath>  
</outVERSION>  

Lines 1 and 2 consist of the XML declaration and the document type declaration, respectively. If a FQPN for the DTD was specified in the request, then the result XML will also contain a FQPN for the DTD file name.

Line 3 is the root element for the outputs of the Version response. This element contains all the child elements holding the calculation results.

Line 5 returns the version information for both the SCEX. Lines 6 through 9 return path information about the SCEX and current directory. Line 10 closes out the root element and terminates the XML result.

Please note that the SCE is now subsumed within the SCEX, so lines 4 and 6 will always return a value of N/A.