Server-side Scripts

Scripts that are run on the server may need to access the server's kernel objects. For this purpose, the server provides the 'running context' (RC) object in the script. The variable instance reads 'RC' if not defined otherwise by the JobDrivenEvents. The different jobs in JobDrivenEvents may furthermore provide proprietary objects. These will separately appear in the documentation of the respective job. The kind of how these objects are provided depends on the job.

Further information on server scripting with JavaScript can be found in the developer documentation.

Script Development

All kernel objects are assigned to the running context and, in contrast to objects that are added by the job itself, will never be seen directly in the global namespace of the script. These jobs may be visible in the global namespace. In any case, the kernel objects are additionally assigned to the running context. In this manner, kernel objects differ from job-specific objects because kernel objects will only be visible through the running context and never directly, whereas job-specific objects will always be visible through the running context and maybe directly as variables. The running context additionally allows you to access job-specific objects.

There are two ways to access the objects through the running context thanks to the 'Item' property, for example either 'RC.Item("SessionData")' or 'RC.SessionData'.

The first way accepts names and numbers. The object number can be passed as a parameter to the 'Item' property: RC.Item(2).

The 'RC.Count' property allows you to determine the total number of objects in the RC. Kernel objects will always be listed behind all job-specific objects, that is, the numbering changes for each call.

RC

In addition to all objects, the running context has the 'GUIAvailable' property, which can be used to determine from within the script whether the script allows GUI calls, and the 'NewJobsParams' method; the latter may be used to create a new instance of the parameter list due to which jobs can be run.

The third method of the RC is 'IncludeFile(BSTR FileName)', which is used to separate large scripts into multiple scripts.

Another RC property is 'UseNewDB'. It is used to control whether jobs can be called in a transaction or whether they receive an extra transaction context.

Objects

The following kernel objects of the first level are available:

• SessionData,

• ServerData,

• General,

• Logger,

• Jobs,

• Actions,

• Registry.

Each object will be described in the following.

SessionData

This object provides information about the user account in the context of which the script will be run. The following properties are currently available:

ServerData

This object delivers different configuration data from the runtime environment of the server. The following properties are currently available:

General

This object delivers some general information on the job. The following properties are currently available:

Logger

This object allows for logging within the kernel context. The script may also keep its own log by directly addressing the oxrpt.dll library via COM. In doing so, an individual configuration is used. The script may alternatively log through the logger object. The logger object provides the following methods:

The call of a log entry will appear in the log as 'SCRIPT: […]' text, while the passed text is logged in the square brackets. The entry will appear as 'Flow', 'Info', 'Warning', or 'Error', depending on the called method.

All methods have a 'Text' parameter that represents the actual log entry and, dependent on the method, further parameters:

Flow(BSTR Text);

Warning(BSTR Text);

Info(BSTR Text);

Error(BSTR Text);

FlowEx(BSTR Text, UINT Level, BSTR Function, UINT Line);

WarningEx(BSTR Text, BSTR Function, UINT Line);

InfoEx(BSTR Text, BSTR Function, UINT Line);

ErrorEx(BSTR Text, BSTR Function, UINT Line);

The 'Flow' method logs on level 5, the methods 'Info' and 'Warning' use level 3, and the 'Error' method logs on level 0.

Jobs

This object allows you to execute several server jobs. The jobs are run synchronously, that is, the calling method will be returned exactly when the job is finished, no matter if it was successful or not. A job call may look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
Dim PrmIn
Dim PrmOut
Set PrmIn = RC.NewJobsParams
Set PrmOut = RC.NewJobsParams
PrmIn.Clear()
PrmIn.Value("Flags") = 0
res = RC.Jobs.krn.GetNextIndex(PrmIn,PrmOut)
if res = 0 then
MsgBox("krn.GetNextIndex succeeded: " & NextIndex) 
else
MsgBox("krn.GetNextIndex failed: " & res)
end if
PrmOut.Clear()

Two objects that serve as input and output parameters of the job are created in the lines 1 to 4. These objects cannot only be used for one but for a number of jobs. Elements can be added and queried but not deleted separately. Therefore, the 'Clear' method is introduced because it clears the list (lines 5 to 13). The list can consequently be populated with input parameters. The property that represents the respective parameter is called 'Value' and its parameter name is the argument. The type of the parameter will be analyzed, thereby creating an XMLRPC parameter with the same type. 'BSTR' will be converted to 'XMLRPC string'. Different 'Integer values' become 'XMLRPC integer' and 'BOOL' becomes 'XMLRPC boolean'. The current version does not support other 'XMLRPC types'.

Afterwards, the call is performed as follows:

RC.Jobs.namespace.jobname(in-list,out-list)

Here, 'namespace' is the name of an executor or namespace (three characters as usual) that is followed by the job name. The job call returns an integer value that usually is set back to '0' if the job was successful. This value represents 'dwResult' that returns the actual job function. If problems that prevent the job from being executed (an exception or either the job or the namespace is unknown, for example) occur, instead of passing a return value, a COM exception will be generated. If the 'Job.krn.MyJob' call returns without triggering a COM exception, it can be assumed that MyJob has been executed; and if, for example, it returns the value '-1', this value is passed by the job function and not by the kernel.

In order to pass files to the job, another parameter must be added. This parameter is called $Job$Files$ and is a string. It consists of file names that are separated by semicolons.

After being returned, output parameters can be interpreted; in the example they are located in the 'PrmOut' list of output parameters. Naturally, the parameter names must be known. The output files are obtained by analyzing and splitting the job.

In doing so, note that a question mark may be prepended to each file name. This will be the case if the job has created temporary files in the ostemp directory, for example, when decrypting a file from the WORK directory into the ostemp directory.

If there is no question mark prepended to the file name, it is not a temporary file and has been filed in either the CACHE or WORK directory.

If, for example, a non-existing variable is queried, the parameter is consequently returned; the variable has not been initialized, meaning it has the type 'VT-EMPTY'. The 'IsEmpty' function can be used to check it in the script. Job names and names and types of job parameters are described in the server API documentation.

If BASE64 parameters are meant to be passed to the job or to be read out of the job, consult the following section on 'Parameters'. If, for example, the DOM variable is an MSXML.DOMDocument object into which an XML was loaded, the command

PrmIn.Value("Buffer") = Dom

is used to assign an input parameter of the BASE64 type to the job. Conversely, an output parameter can be read out as follows:

B64Result = PrmOut.Value("Result")

Dom.load(B64Result)

When calling a job at the server and passing the $$$Server ID$$$ parameter to it, this job is forwarded to the transferring server and executed. For security reasons, this process is only available if the job is called in a script at the server via RC.

Actions

This object allows you to execute functions that are implemented by the kernel itself. The following methods are currently available:

The list of file names is a semicolon-separated string. The methods have the following parameters:

SendMail(BSTR To, BSTR From, BSTR Subject, BSTR Text, BSTR Files);

SendAdminMail(BSTR From, BSTR Subject, BSTR Text, BSTR Files);

StreamReset (VARIANT stream); // VARIANT is of type IStream or BYREF | VARIANT and then IStream

Registry

This object allow you to read elements out of and write elements to the server registry. The following properties are available:

The path to the element begins with the current schema. For example, the 'ComString' element, which is located under the current schema, is accessed as follows: RC.Registry.Element("ComString").

The 'Schema' element, which is located under the 'DataBase' key, is accessed as follows: 'RC.Registry.Element("DataBase\Schema")'. Keep in mind the case-sensitivity of the entry.

Parameters

Several parameters can be passed to the script. Likewise, the parameters can be returned after the script's execution.

Dim InputNames
 InputNames = RC.InputParams.Names
 MsgBox("Input params: " & InputNames)
 
 Dim NameArray
 NameArray = Split(InputNames,";",-1,1)
 MsgBox("VarType((NameArray) = " & VarType(NameArray))
 Dim sMsg, i, sName
 Dim Param
 for i = LBound(NameArray) to UBound(NameArray)
    sName = NameArray(i)
    if (len(sName) > 0) then
         Param = RC.InputParams.Value(sName)
         if (IsEmpty(Param)) then
          sMsg = sMsg & "Parameter " & sName & " not found"
        else
          sMsg = sMsg & sName
           sMsg = sMsg & ": "
           sMsg = sMsg & Param
        end if
           sMsg = sMsg & vbCrLf
        end if
   next
   MsgBox(sMsg)
 
   RC.OutputParams.Value("hallo") = "Welt"

Both objects 'RC.InputParams' and 'RC.OutputParams' allow you to work with parameters. The 'Names' property returns the names of all listed parameters, separated by a semicolon. The 'Value' property allows you to read and write the parameter.

A particular case of script execution is the execution of scripts of KernelDrivenEvents. The KDEs will be run before and after the job. Therefore, they must access the job parameters. This is ensured due to the 'InputParams' and 'OutputParams' variables. All parameters are provided to the script as input parameters in the Before script of a KDE. After the script's execution, this list of input parameters will entirely replace the parameter list of the original job because single parameters can be removed from the list, as well. The After script of a KDE provides all input parameters of the job (or the Before script) as well as all output parameters. You can now modify the output parameters. In contrast to the Before script, output parameters will not be entirely replaced but the values of available parameters will be modified.

The values of parameters can be queried and edited as described above, except for parameters of the 'BASE64' type. The latter require a different procedure as they are represented as 'IStreams'. The script can pass IStreams only to those interfaces that are capable of identifying IStreams, for example, an XMLDOMDocument, because the 'msxml' implementation allow you to load XML from IStreams. A DOM may subsequently be again saved to an IStream. However, the IStream must be cleared first as the content of the 'DOMDocument' will be added to it. The 'RC.Actions.StreamReset(param)' can be used for this purpose.

Files

The running context provides methods that allow passing file lists to the script and getting them back.

The 'RC.InputFiles' can be used to read out the file list from within the script that the script has received as an input list.

The 'RC.OutputFiles' can be used to define the output list of files in the script.

Example: RC.OutputFiles = "c:\temp\1.txt;c:\temp\2.txt"

File names must be separated by a semicolon.

RunScript

The 'krn.RunScript' job allow you to test the described functionality. It can be additionally used for administrative purposes, such as the frequent execution of particular scripts.

The 'RunScript' job requires the following parameters:

After job execution, the return value of the script function (the function is called 'Main' if the 'Main' job parameter is empty) that was executed on the server side will be returned as '$ScriptResult$' return value (of the data type string).

Example:

Set oServer = CreateObject( "OxSvrSpt.Server" )
set oSession = oServer.Login("<User>" , "<PWD>" , "<Server>", "<Port>" )
 
sScript= _
"Function Main" & vbcrlf & _
"Main=now" & vbCrLf & _
"End Function"
MsgBox _
"Lokale Zeit: " & vbTab & now & vbCrLf & _
"~Zeit am Server: " & vbTab & _
RunScript(oSession, sScript), vbInformation, _
"Zeitdifferenz lokal/server"
 
Function RunScript(oSession, sScript)
     set oJob = oSession.NewJob("krn.RunScript")
     oJob.InputParameters.AddNewStringParameter "Script", sScript
     oJob.InputParameters.AddNewStringParameter "CtxName", ""
     oJob.InputParameters.AddNewIntegerParameter "Flags", 0
     oJob.InputParameters.AddNewBooleanParameter "GUI", 0
     oJob.InputParameters.AddNewBooleanParameter "Eval", 0
     oJob.Execute
     RunScript = oJob.OutputParameters("$ScriptResult$.Value
End Function

The following message box will be returned as the result:

To pass a parameter list to the script, further optional parameters can be passed to the job. These parameters must differ from normal job parameters by having other names than available for this job. In addition, the names and values must be separated as follows upon execution:

These parameters must be numbered consecutively.