JavaScript Reference
This chapter describes the extended functions and objects implemented by XX/1 that allow you to interact with the server. This is not a tutorial on JavaScript in general.
Global Properties
Property | Description |
---|---|
ClientRequest | String, read-only, XML request sent by client, same as GetClientRequest |
ClientTC | String, read-only Transaction Control Data (XML) sent by client, same as GetClientTC |
ClientResponse | String, write, XML response to be returned to client, same as SetClientResponse |
ClientResponseTC | String, write, returned Transaction Control Data (XML), same as SetClientResponseTC. If not set, the server echoes the original request ClientTC |
Global Functions
Function | Description |
---|---|
GetClientRequest | Obtain the XML request sent by client |
GetClientTC | Obtain the Transaction Control Data (XML) sent by client |
SetClientResponse | Set the XML response to be returned to client |
SetClientResponseTC | Set the Transaction Control Data (XML) to be returned to client |
SetErrorResponse | Set a non-XML error response as transaction result that is returned to the client |
Decode | Lookup a descriptive value by given code using XX/1 lookup tables |
Encode | Retrieve list of codes by value pattern from XX/1 lookup tables |
Trace | Send simple trace to attached XXTraceConsole |
TraceText | Send trace with plain text data to attached XXTraceConsole |
TraceXml | Send trace with XML data to attached XXTraceConsole |
LoadFile | Read a local file from disk |
Write text to server error log file and log consoles that are attached to the server | |
ExecFunc | Executes several functions formerly defined for the XSL |
WriteFile | Writes a buffer into a file on the existing filesystem |
Objects
Object | Description |
---|---|
xxProvider | Instance to a provider adapter session |
xxServer | Instance to the current XX1 Server |
xxAsyncProvider | Instance to a provider adapter. The processing is asynchronous. |
xxAsyncServer | Instance to the current XX1 Server. The processing is asynchronous. |
xxTransform | Instance to a selected transformation service (XSLT processor) |
xxDomDocument | Instance to a DOM implementation object that is implemented by a selected transformation service |
xxNode | Instance to a DOM Node implementation object that is implemented by a selected transformation service |
xxNodeSet | Instance to a DOM Node-List implementation object that is implemented by a selected transformation service |
xxScreen | Instance to a String analyzing Object |
xxDBC | The XX/1 Database object is used to establish a connection to a database. |
xxResultSet | Includes the resultset of a Query executed by the xxDBC object |
JavaScript Development Guidelines
Assumptions
When writing a JavaScript transaction script you can make the following assumptions for the script execution:
- The provider connection is already established and a session context is locked for your script
- Your script is executed on a separate thread that is bound to the client transaction
- The lifetime of a script is the client transaction
- Transformation documents (XSL files) specified in your script are pre-loaded and compiled at server start
Rules
Also, you have to follow these basic rules:
- You must not mix xxDOMDocument and xxNode objects that are implemented by different transformations services
- You must call at least one of both functions SetClientResponse or SetErrorResponse before your script terminates
Recommendations
For conformance and best performance:
- Use 'var' statements where possible for best performance
- Use SelectSingle and SelectNode methods rather then walking DOM trees yourself
Error Reporting
There are different types of errors, that may occur during script execution. You should handle and report them as recommended below.
General Script Execution Error
This error occurs when there is a syntax or system error related to the script execution. The error reporting is controlled by the server. The error message is sent to the client and the current server console log. You should debug and/or modify your script so that these errors never occur.
Provider Errors
Are set in the xxProvider.LastError property if xxProvider.SendTransaction fails. Normally you should abort your script and forward the error the user with the SetErrorResponse global function.
DOM Object Errors
Most of the time it is sufficient to test for 'null' on method return codes and handle the error within the code.
Reporting SUCCESS
Do not call SetErrorResponse and set the returned XML with the SetClientResponse function.
Reporting FAILURE
Use SetErrorResponse to report errors as plain text string. The client transaction will fail on the RPC (remote procedure call) level.
Sometimes you may want to report 'functional' errors as normalized XML in the scope of a successful client transaction on RPC level. In this case do not call SetErrorResponse but rather call SetClientResponse with your error XML.
LiveConnect
LiveConnect is a feature that allows you call true Java class implementations from your JavaScript. Requires the Sun Java Virtual Machine (VM) runtime modules to be installed on the machine.
JavaScript Native Interface
The JavaScript Native Interface (JSNI) allows you make calls to C/C++ libraries from your script.
Example for a XX/1 boiler-plate Javascript
(function() {
try
{
////////////////////////////////////
// Get client transaction input
//
var strRequest = GetClientRequest();
var strTC = GetClientTC();
////////////////////////////////////
// Create a transformation Object
//
var xslt = new xxTransform();
if (xslt)
{
// Transform the Request
var transReq = xslt.Transform("TestRQ.xsl", strRequest);
if (transReq)
{
// Create provider object to already connected provider
var provider = new xxProvider(strTC);
if (provider)
{
// send transaction to provider
if (provider.SendTransaction(transReq))
{
// get provider's response
var nativeRsp = provider.Response;
if (nativeRsp)
{
/////////////////////////////////////
// Transform the Native response...
//
var transRsp = xslt.Transform("TestRS.xsl", nativeRsp);
if (transRsp)
{
// OK - return to Client
SetClientResponse(transRsp);
}
else
{
SetErrorResponse(100, "Response transformation failed.");
}
}
else
{
SetErrorResponse(101, "Provider response empty.");
}
}
else
{
// Provider transaction failed
SetErrorResponse(102, provider.LastError);
}
}
else
{
SetErrorResponse(103, "Could not create Provider Object");
}
}
else
{
SetErrorResponse(104, "Request transformation failed");
}
}
else
{
SetErrorResponse(105, "Could not create Transformation Object");
}
}
finally
{
}
})();