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

PropertyDescription
ClientRequestString, read-only, XML request sent by client, same as GetClientRequest
ClientTCString, read-only Transaction Control Data (XML) sent by client, same as GetClientTC
ClientResponseString, write, XML response to be returned to client, same as SetClientResponse
ClientResponseTCString, write, returned Transaction Control Data (XML), same as SetClientResponseTC. If not set, the server echoes the original request ClientTC

Global Functions

FunctionDescription
GetClientRequestObtain the XML request sent by client
GetClientTCObtain the Transaction Control Data (XML) sent by client
SetClientResponseSet the XML response to be returned to client
SetClientResponseTCSet the Transaction Control Data (XML) to be returned to client
SetErrorResponseSet a non-XML error response as transaction result that is returned to the client
DecodeLookup a descriptive value by given code using XX/1 lookup tables
EncodeRetrieve list of codes by value pattern from XX/1 lookup tables
TraceSend simple trace to attached XXTraceConsole
TraceTextSend trace with plain text data to attached XXTraceConsole
TraceXmlSend trace with XML data to attached XXTraceConsole
LoadFileRead a local file from disk
printWrite text to server error log file and log consoles that are attached to the server
ExecFuncExecutes several functions formerly defined for the XSL
WriteFileWrites a buffer into a file on the existing filesystem

Objects

ObjectDescription
xxProviderInstance to a provider adapter session
xxServerInstance to the current XX1 Server
xxAsyncProviderInstance to a provider adapter. The processing is asynchronous.
xxAsyncServerInstance to the current XX1 Server. The processing is asynchronous.
xxTransformInstance to a selected transformation service (XSLT processor)
xxDomDocumentInstance to a DOM implementation object that is implemented by a selected transformation service
xxNodeInstance to a DOM Node implementation object that is implemented by a selected transformation service
xxNodeSetInstance to a DOM Node-List implementation object that is implemented by a selected transformation service
xxScreenInstance to a String analyzing Object
xxDBCThe XX/1 Database object is used to establish a connection to a database.
xxResultSetIncludes 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:

 

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
{

}
})();