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:
Name |
Description |
---|---|
SessGUID |
GUID of the client session |
UserName |
User name |
StatName |
Name of the enaio® client computer |
InstName |
Name of the program to which the user has logged on |
UserGUID |
GUID of the user |
StatGUID |
GUID of the enaio® client workstation This is not a MAC address but the GUID of the record in the database. |
UserID |
User ID |
Supervisor |
The supervisor flag from the user table of the user |
LangID |
Language ID from the user table of the user |
ServerData
This object delivers different configuration data from the runtime environment of the server. The following properties are currently available:
Name |
Description |
---|---|
DataDir |
Path to the data area of the server group |
RootDir |
Path through which the server was started |
TempDir |
Path to the ostemp directory of the server |
ConfDir |
Path to the etc directory of the server group |
UserDir |
Path to the user directory of the server group |
Service |
Name of the service |
LogDir |
Path to the log directory into which the server saves its logs |
Connect |
Computer name and TCP port, separated by the hash character '#' |
ServerID |
ID of the server |
GroupID |
ID of the server group |
General
This object delivers some general information on the job. The following properties are currently available:
Name |
Description |
---|---|
JobNumber |
Number of the job, sequentially numbered since server start |
ThreadID |
ID of the thread in which the job is currently performed |
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:
Name |
Description |
---|---|
Flow |
Flow log on level 5 |
FlowEx |
Level and script location can be defined |
Info |
Flow log with facility 'informational' on level 3 |
InfoEx |
Like info, the script location can be defined |
Warning |
Flow log with facility 'warning' on level 3 |
WarningEx |
Like warning, the script location can be defined |
Error |
Error log with facility 'error' on level 0 |
errorEx |
Like error, the script location can be defined |
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:
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:
Name |
Description |
SendMail |
Sends an e-mail that contains the addresses of recipient and sender, subject, text, and list of files. |
SendAdminMail |
Sends an e-mail to the administrator provided that this e-mail address has been specified in the registry. |
StreamReset |
Clears an IStream. |
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:
Name |
Description |
Item |
This property can be read and written to, and has a parameter of the 'BSTR' type, which represents the full path to the element. The element's value also has the 'BSTR' type. |
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:
Name |
Type |
Description |
Flags |
Integer (2) |
A value of '1' will not remove the files that were passed to the job. |
Script |
String (1) |
Text of the script. If the parameter is an empty string, it will be checked whether at least one file is received with the job. If not, an error will be returned. If yes, the file content will be used as the script text. All incoming files will be deleted after the job, provided that 'Flags' has a value of '0'. |
GUI |
Boolean (3) |
Will be forwarded as 'bGUIAvailable' to the performer. A value of '0' will deactivate the option to show a message box. Conversely, a value of '1' activates the option unless it has been generally disabled in the registry. |
CtxName |
String (1) |
Name of the running context under which it is made visible in the script. If this parameter is empty, the name 'RC' will be used. |
Main |
String (1) |
Name of the function to be carried out by the script; may be empty as well. 'Main' will be used as the function if the parameter is missing. |
Eval |
Boolean (3) |
Specifies whether or not the script text represents an expression. |
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:
Name |
Type |
Description |
$SP_1_name$ |
String (1) |
name of the first script parameter |
$SP_1_value$ |
Random |
value of the first script parameter |
... |
|
|
$SP_xx_name$ |
String (1) |
name of the last script parameter |
$SP_xx_value$ |
Random |
value of the last script parameter |
These parameters must be numbered consecutively.