OASyS DNA®

Business Object Reference

www.schneider-electric.com
Legal Information
The Schneider Electric brand is the sole property of Schneider Electric Industries SAS. Any
trademarks of Telvent Canada Ltd. or Telvent USA, LLC referred to in this guide are the sole
property of Telvent Canada Ltd. or Telvent USA, LLC. The Schneider Electric brand and
trademarks may not be used for any purpose without the owner's permission, given in writing. This
guide and its content are protected, within the meaning of the applicable copyright and trademark
laws and international conventions. Unless otherwise agreed in writing, you may not reproduce all
or part of this guide on any medium whatsoever without the permission of Telvent Canada Ltd. You
also agree not to establish any hypertext links to this guide or its content. All other rights are
reserved.
© 2016 Telvent Canada Ltd. All rights reserved.
 Table of Contents

Table of Contents
1 Business Object Client (.NET) Reference ..............................................................................................5
1.1 Languages available for business objects......................................................................................5
2 .NET Clients introduction.......................................................................................................................19
2.1 Using the OASyS DNA Visual Studio Wizard to create a new Business Object Component.......19
2.2 Deployment..................................................................................................................................33
2.3 Testing and Debugging.................................................................................................................35
3 RealTime Business Objects...................................................................................................................40
3.1 ACEAddCode...............................................................................................................................40
3.2 ACECompile.................................................................................................................................40
3.3 ACEGetCode................................................................................................................................41
3.4 Acknowledge................................................................................................................................42
3.5 Addarea........................................................................................................................................43
3.6 AddDBalarm.................................................................................................................................44
3.7 addAPPalarm...............................................................................................................................45
3.8 AddFlexTag...................................................................................................................................46
3.9 AddSYSalarm...............................................................................................................................48
3.10 Almattr........................................................................................................................................49
3.11 Checkin.......................................................................................................................................50
3.12 CheckForDSTIssues..................................................................................................................50
3.13 Collect_fields..............................................................................................................................52
3.14 Collect_tables.............................................................................................................................52
3.15 ControlGroups............................................................................................................................53
3.16 CreateXosCmdRec.....................................................................................................................54
3.17 Droparea.....................................................................................................................................55
3.18 Enumerate..................................................................................................................................55
3.19 Filteralm......................................................................................................................................56
3.20 FilterFlexTag...............................................................................................................................57
3.21 FilterTag......................................................................................................................................58
3.22 FilterMaskedAlm.........................................................................................................................59
3.23 Fldget..........................................................................................................................................60
3.24 Fldput..........................................................................................................................................61
3.25 Fnput..........................................................................................................................................61
3.26 GetActiveAORPermissions.........................................................................................................62
3.27 GetFlexTagGroupMembers........................................................................................................64
3.28 GetFlexTagGroupRestrictionStates............................................................................................65
3.29 GetProtocolTable........................................................................................................................66
3.30 GetStatMsgTxt............................................................................................................................66
3.31 GetSystemDOASPermissions....................................................................................................67
3.32 GetTableFieldsOfKind.................................................................................................................67
3.33 GetTablesWithFieldName...........................................................................................................68
3.34 GetTagGroupCurValve...............................................................................................................68
3.35 GetTaggingVersion.....................................................................................................................71
3.36 GetUserAORPermissions...........................................................................................................71
3.37 GetYMinMax...............................................................................................................................71
3.38 Helpdb........................................................................................................................................72
3.39 Helptype.....................................................................................................................................72
3.40 InterpTrend.................................................................................................................................73
3.41 Modarea.....................................................................................................................................75
3.42 ModifyFlexTag............................................................................................................................75
3.43 RemoveFlexTag..........................................................................................................................77

3
Table of Contents

3.44 Request Access..........................................................................................................................79

3.45 RouteSwitch...............................................................................................................................80
3.46 RtTrend.......................................................................................................................................84
3.47 ShowAccessFlags......................................................................................................................84
3.48 SpoolMsg....................................................................................................................................85
3.49 StoreAndForwardSummary........................................................................................................86
3.50 TestModeSupported...................................................................................................................87
3.51 Trend..........................................................................................................................................88
3.52 Trend_filter..................................................................................................................................89
3.53 Trendview...................................................................................................................................90
3.54 UpdateCollect.............................................................................................................................91
3.55 ViewGroups................................................................................................................................92
3.56 Xoslogin......................................................................................................................................93
4 PI Business Objects..............................................................................................................................94
4.1 InterpTrend...................................................................................................................................94
4.2 Trend_points.................................................................................................................................94
4.3 Trend............................................................................................................................................94
4.4 TrendView.....................................................................................................................................95
5 Common Business Objects...................................................................................................................97
5.1 CFGConvUser..............................................................................................................................97
5.2 CFGGetArchivableServices..........................................................................................................97
5.3 CFGGetArchiveHost.....................................................................................................................97
5.4 CFGGetCompList.........................................................................................................................98
5.5 CFGGetGroupList.........................................................................................................................99
5.6 CFGGetSrvList...........................................................................................................................101
5.7 CFGGetSysList...........................................................................................................................101
5.8 CFGGetUserList.........................................................................................................................102
5.9 CFGGetUserRoleMembership...................................................................................................102
5.10 CFGGetXOSList.......................................................................................................................103
5.11 GetServiceProcessList.............................................................................................................103
5.12 GetUserPermissions.................................................................................................................104
5.13 ProcessCheckout.....................................................................................................................106
5.14 RunProcess..............................................................................................................................106
5.15 ServiceShutdown......................................................................................................................107
5.16 ServiceStartup..........................................................................................................................107
5.17 ToggleDebug............................................................................................................................107
5.18 ValidateUser.............................................................................................................................108
6 Arbitration Business Objects...............................................................................................................109
6.1 ServiceFailover...........................................................................................................................109

4
 Business Object Client (.NET) Reference

1 Business Object Client (.NET) Reference

Business Object Components interface with data tier components to update and retrieve database
information. They are used by first creating a business object client.

Business Object components are instantiated on a RealTime or Historical station remotely from a
presentation tier client. Presentation tier clients use the Business Object Client class to activate OASyS
DNA Business Object Components and perform processing.

The Business Object Client class provides a client-side interface for invoking OASyS DNA Business
Object Components from:

• Visual C#

• Visual Basic .NET

• Managed Visual C++

The Business Object Client has a default constructor that is used to create a new instance of the
Business object client.The syntax for it is:

BLTClient bltclient = newBLTClient();

The Business Object Client class also has several methods and properties that help to customize calls
to RealTime and the component.

1.1 Languages available for business objects

The business objects that are available as part if the OASyS DNA product suite can be created using
three languages: Visual C# , C# Script, Visual Basic .NET.

The features and capabilities of the different languages used for client application creation vary. Different
languages have distinct strengths and limitations. The selection of a language used for development
depends on the following:

• project maintenance requirements

• ongoing additional development

• ease of use/learning, and hence time-to-market

• degree of sophistication required for the application

A quick comparison of the features and strengths of each available language options follows:

Visual C#:

• medium speed

• intermediate compiled code

• easy to write

• requires Visual Studio.NET for development

• examples available

5
Business Object Client (.NET) Reference

C# Script:

• slow

• interpreted language

• easy to write

• does not require a development tool

• examples available

Language: Visual Basic .NET

• medium speed

• easy to write

• requires Visual Studio.NET for development

• example available

1.1.1 Methods for Business Object Clients

AddParameter
This method is used to add a parameter to pass to the Business Object RPC.

Declaration:

public void AddParameter(object Value, bool IsOutput);

Table 1 - Parameters of AddParameter

Parameter Description
Value String specifying the value of the object
IsOutput Identifies whether the component will return data for bool

Remarks:

Output parameters will be overwritten with new values after the Execute method is called. The
parameter list will persist between invocations of the Execute method unless changed.
Related Information
Execute on page 8

Create
This method is used to create a new Business Object component on the specified host. The creation of
the component will time out according to the value set in the ExecutionTimeout property, the default for
which is 10 seconds.

Declaration:

public void Create (string Name, string Host);

6
 Business Object Client (.NET) Reference

Table 2 -
Parameter Description
Name Name of the Business Object component to create such as “Fnput” or
“HelpType” or Filteralm”
Host Name of the host on which to create the component

DeleteParameter
This method is used to delete a parameter from the end of the list to pass to the Business Object RPC.

Declaration:

public void DeleteParameter ();

7
Business Object Client (.NET) Reference

Example:

using System;

using OASySDNA.Common;

class Test

static void Main(string[] args)

BLTClient bltclient = newBLTClient();

//Create the Helptype component

bltclient.Create(“Helptype”, “localhost”);

//Add two parameters

bltclient.AddParameter(“analog”, false);

bltclient.AddParameter(“dummy”, false);

//Delete the last parameter from the list

bltclient.DeleteParameter();

Execute
This method is used to invoke changes to the Business Object component.

Declaration:

public void Execute();

Remarks:

The eecution of the component will time out according to the value set in the ExecureTimeout property,
the default for which is 10 seconds. This method results in one or more ADO.NET tables being returned

8
 Business Object Client (.NET) Reference

from the RPC. These may be retrieved using the TabularResults property which returns a DataSet
containing the tables.

1.1.2 Properties for Business Object Clients

ExecuteTimeout
This property indicates the timeout that will be used when the Business Object component’s are called.

Declaration:

punlic int ExecuteTimeout {get; set;}

9
Business Object Client (.NET) Reference

Example:

using System;

using OASySDNA.Common;

class Test

static void Main(string[] args)

try

BLTClient bltclient = new BLTClient();

//Create the component

bltclient.Create(“Fnput”,”localhost”);

//Add parameters

bltclient.AddParameter(“analog”, false);

bltclient.AddParameter(“1”, false);

bltclient.AddParameter(“manual”, false);

//Set a timeout for executing the component (5 seconds)

bltclient.CreationTimeout = 500

// Execute the component

bltclient.Execute();

catcj(System.Exception e)

10
 Business Object Client (.NET) Reference

Console.WriteLine(e.Message);

Console.WriteLine(e.StackTrace);

Locale
This property indicates which locale the Business Object component uses for internationalizing strings.

Declaration:

public int Locale {get;set;}

Remarks:

When you “get” this property, an integer is returned that specifies the locale ID. This ID is a Windows
local ID. In .NET, the locale ID of the current thread can be retrieved using the
System.Globalization.CultureInfo.CurrentCulture.LCID property. The default value is returned by the
GetSystemDefaultLCID () Win32 API call.

NOTE: Baseline OASyS DNA Business Object components do not currently use this property for
internationalizing strings. The use the locale of the server instead

11
Business Object Client (.NET) Reference

Example:

using System;

using OASySDNA.Common;

class Test

static void Main(string[] args)

try

BLTClient bltclient = new BLTClient();

//Create the component

bltclient.Create(Almattr”, “localhost”);

//Set the locale

bltclient.Locale = System.Globalization.CultureInfo.CurrentCulture.LCID;

//Execute the component

bltclient.Execute();

catch(System.Exception e)

Console.WriteLine(e.Message);

Console.WriteLine(e.StackTrace);

12
 Business Object Client (.NET) Reference

MaxRowsToReturn
This property controls how many rows the Business Object should return

Declaration:

public int MaxRowsToReturn {set;}

Remarks:

This property is passed to the Business Object as an extra parameter in the Params recordset. The
Business Object decides if this property will affect its outfut for:

• Collect_Fields
• Collect_Tables

• Filteralm

• ListConfigDatasets

• ListSelectmodes

• ShowAccessFlags

• Trend

• TrendView

• TrendFilter

13
Business Object Client (.NET) Reference

Example:

using System;

using OASySDNA.Common;

class Test

static void Main(string[] args)

try

BLTClient bltclient = new BLTClient();

//Create the component

bltclient.Create(“Almattr”, “localhost”);

//Set the maximum number of rows to return

bltclient.MaxRowsToReturn = 10;

//Execute the component

bltclient.Execute();

catch(System.Rxception e)

Console.WriteLine(e.Message);

Console.WriteLine(e.StackTrace);

14
 Business Object Client (.NET) Reference

NumParameters
This property indicates how many parameters are used in calling the RPC

Declaration:

public int NumParameters {get;}

15
Business Object Client (.NET) Reference

Example:

using System;

using OASySDNA.Common;

class Test

static void Main(string[] args)

try

BLTClient bltclient = new BLTClient();

//Create the component

bltclient.Create(“Filteralm”, “localhost”);

//Add parameters

blt.AddParameter(0,false);

blt.AddParameter(“both”,false);

//print the number of parameters

Console.WriteLine(“Number of parameters is:“ + bltclient.NumParameters +

“\n”);

catch(System.Exception e)

Console.WriteLine(e.Message);

Console.WriteLine(e.StackTrace);

16
 Business Object Client (.NET) Reference

RowsAffected
This property indicates the number of rows affected by an Execute method for the Business Object
component.

Declaration:

public int RowsAffected {get;}

Remarks:

The RowsAffected property is set by the Business Object component.

Related Information
Execute on page 8

Syntax
This property invokes the Business Object component’s Syntax property. It returns the XML syntax
string for the Business Object component.

Declaration:

public string Syntax {get;}

17
Business Object Client (.NET) Reference

Example:

using System;

using OASySDNA.Common;

classTest

static void Main(string[] args)

try

BLTClient bltclient = new BLTClient();

//Create the component

bltclient.Create(“Filteralm”, “localhost”);

//print the syntax for the component

Console.WriteLine(“Syntax for this component is:”);

Console.WriteLine(bltclient.Syntax);

catch(System.Exception e)

Console.WriteLine(e.Message);

Console.WriteLine(e.StackTrace);

18
 .NET Clients introduction

2 .NET Clients introduction

A .NET client class is used to execute business object components created with Visual C# or Visual
Basic.

Visual C# and Visual Basic are intermediate compiled languages. The compiler produces Intermediate
Language (IL) code that is interpreted by the .NET Framework Common Language Runtime (CLR). The
files produced are executable files (.exe), or if appropriately configured, dynamically loaded libraries
(.dll). The executables are compiled to run under the Microsoft .NET Framework.

Before you can create a business object client, the OASyS DNA Common product, Microsoft Visual
Studio.NET (Professional, Enterprise, or Architect), and the OASyS DNA Visual Studio.NET Wizard
must be available to you.
You will need to create a business object client before you can:

• create a client GUI application

• use the OASyS DNA.NET Business Object Client class

• use Microsoft Visual C# or Visual Basic for client creation

2.1 Using the OASyS DNA Visual Studio Wizard to create a new
Business Object Component
Creating a new Business Object Component through Visual Studio.NET, requires that the program has
been configured to use the OASyS DNA Visual Studio Wizard.

Procedure

1. Start Microsoft Visual Studio.NET.

2. Select File > New Project

Step Result: The New Project dialog box appears.

19
.NET Clients introduction

Figure 1 - New Projects dialog box

3. Select Visual C# Projects or Visual Basic Projects from the left-hand pane under Project Types.
4. Select OASySDNA Service Framework BLT from the left-hand pane and BLT_Component under
Templates as shown in the figure above.
5. Type the project name in the Name: field.
6. Click OK.

Step Result: The OASyS DNA Visual Studio Wizard Welcome dialog box starts

Figure 2 - OASyS DNA Visual Studio Wizard Welcome dialog box

20
 .NET Clients introduction

7. Click Next. The appears.

Step Result: The OASyS DNA Visual Studio Wizard Select Product dialog box appears

Figure 3 - OASyS DNA Visual Studio Wizard Select Product dialog box

8. Select the product in which the component is deployed and click Next.

Step Result: The OASyS DNA Visual Studio Wizard Finished dialog box appears.

Figure 4 - OASyS DNA Visual Studio Wizard Finished dialog box

NOTE: You can add your own product to this list by creating a directory under <install dir>\DNA

21
.NET Clients introduction

9. Verify or change the source file location and click Next.

10. Click Finish to create a new Business Object component.

2.1.1 Customizing the Component

A general overview of writing and invoking Business Object components will help you not only
understand how they are invoked, but also customize them to perform your desired business logic.

The following diagram shows how the Business Object components are invoked:

The client uses the BLTClient.NET class to create the component through the Business Object
infrastructure. The infrastructure controls invocation on remote hosts and process isolation. The
infrastructure runs in a separate process from the client. The client and component may or may not be
on separate computers. The client chooses where to instantiate the component – locally or remotely.
The client and component are always on machines within the same domain.

The component is hosted in a special BLTHost process. This process is provided by the OASySDNA
Insfrastructure, and loads the component DLL when the component is invoked.

The infrastructure calls the interface code, which is in the <name>Component object that is derived
from the BLTComponent class. This class uses the IBLT interface to retrieve parameters from the
client. The parameters are stored in the <name>Processor object, which derives from the
BLTProcessor class.

22
 .NET Clients introduction

Files that comprise a new component

Each new component is comprised of at least four files: AssemblyInfo, RPC<name>,
<name>Processor,and a process method example.

AssemblyInfo

This file contains information about the entire .NET assembly, such as product information, version
information, and an assembly GUI. This file is also responsible for giving the assembly a strong name.
Strong-named assemblies have a unique identifier and a private key that prevents tampering.

RPC<name>

This file implements the interface class for the component. The interface class is responsible for
exposing the component to the Business Object infrastructure. It contains an instance of the
<name>Processor class, which performs the business logic. The RPC<name> class is derived from the
BLTComponent class, which does all of the interface work for you. You should not need to modify this
class.

<name>Processor

This file implements the <name>Processor class, which is derived from the BLTProcessor class.
This class implements a Process() method, which is where you write the business logic. The
constructor for this class defines the syntax for the component. The BLTProcessor class provides
built-in properties and methods to assist you in writing the business logic code.

The C# version of this class is commented using special /// comment markers and XML tags. These
tags are interpreted by the compiler to produce an XML documentation file, which can be processed by
tools such as nDoc and the built-in Build Comment Web Pages tool to produce Windows Help files and
HTML help files.

File Modification
There are two files you may want to modify to customize your Business Object Component: the
constructor, and the process() method.

Modifying the Constructor

The constructor of the <name>Processor class can be modified to initialize any member variables
that you create. It is also where you must initialize the component’s parameters. In order to modify the
constructor, you must create a list of its parameters.

The constructor for the <name>Processor component is where you generate the parameter list for the
component. This list determines how many parameters there are, which of them are input or output, and
what type each parameter is. These parameters are validated by the BLTComponent class. Parameter
information is also made available to the client in XML form. The XML shows details for each parameter
as well as a general usage string.

Generate a parameter list by creating a BLTParameterList object and adding BLTParameter

objects to it. You can override the usage string by setting the BLTParameterList::UsageText
property. Save the parameter list in the component by setting the this.Parameters property.

23
.NET Clients introduction

Modifying the Process() Method

Reading Input Parameters is a fundamental step in changing the process method. Input parameters are
passed by the this.Parameters property that you set in the constructor. Each BLTParameter object
in the list contains a parameter value. Retrieve the parameters with code like this (C# version):

string szCity = this.Parameters.Item(0).Value.ToString();int iSomeNumber =

(int) this.Parameters.Item(1).Value;

Parameters are expected to appear in the same order in which they were added in the constructor. It is
also important to be mindful of how you write output parameters. Output parameters are designated as
such with the IsOutput property:

if(this.Parameters.Item(0).IsOutput == true) then{…}

Output parameters are set by modifying the Value property of the BLTParameter object in the
Parameters list:

this.Parameters.Item(0).Value = “test”;this.Parameters.Item(1).Value = 1;

You can use the built-in properties, to modify your process method in even more detail. The
BLTProcessor class, from which the <name>Processor class is derived, contains other useful
properties. These are listed in the following table.

Table 3 - Optional properties for Process Method modification

Property Description
this.RowsAffected Sets the number of rows affected by the operation and returns it to the client.
this.Locale Gets the locale ID of the client, which can be used for internationalization.
this.MaxRowsToReturn Gets the maximum number of rows to return, which was set by the client

NOTE: Use the Object Browser to examine the built in properties for the Business Object

Returning rows to the client helps you verify that your changes to the Process method have worked. The
this.AddResultSet method is used to return rows of data to the client. This method takes a
DataTable object as a parameter. The DataTable class is an ADO.NET datatype available under the
System.Data namespace.

To return rows to the client, create a DataTable object and use the methods provided to add columns
and rows. Then use the this.AddResultSet method to save the recordset for returning to the client.
Multiple DataTables may be returned.

DataTable tabularResult = new DataTable

(“DataTable1”);tabularResult.Columns.Add (“StringColumn”, type of
(String));tabularResult.Columns.Add (“IntColumn”, type of (int));DataRow
row = tabularResult.NewRow();row [“StringColumn”] = “aString”;row
[“IntColumn”] = 1;tabularResult.Rows.Add(row);this.ResultSet
(tabularResult);

You may also want to return errors to the client to edit your changes to the Process method. Errors can
be returned to the client by throwing a BLTException or System.Exception exception. Errors
should be divided into two types:

Unexpected errors (OS-related, memory access, crashes, etc.). Throw a System.Exception

exception to signify these errors.

24
 .NET Clients introduction

Expected errors (RealTime dberr codes, errors caused by the client, database locks being held, etc.).
The built in BLTException class error code is used to signify these errors. Throw a BLTException
exception to signify these errors.

Expected errors are not serious and do not affect the operation of the system. However, they should
generally be communicated to the client via a descriptive message, so that the client can show the
message to the user.

Example 1: Sending an expected error to the client

BLTException bltexcept = new BLTException("User error");throw(bltexcept);

Unexpected errors require the intervention of highly technical personnel, and usually have a negative
impact on system operations. As such, they should be logged in the oasErrLog.log file. A message
indicating that the user call technical support (or some other appropriate message) should be sent to the
client.

The <name>Component class already traps all unexpected errors and logs them to the oasErrLog.log
file, so you usually don’t need to worry about them. However, in cases where you do need to trap these
kinds of errors, the following example should help:

Example 2: Trapping and logging an unexpected error

try{ // … processing code ….}catch(System.Exception except)

{OASySDNA.Common.DNALog.DumpNonFatalExceptionTocobjLog(except);System.Excep
tion newexcept = new System.Exception("Internal error. Consult the
oasErrLog.log file for details.");throw(newexcept);}

Examining built-in properties using the Object Browser

When your are making modifications in order to customize a Business Object component, you may want
to examine the properties with the Object Browser
Properties can be set and retrieved in the Process () method as follows:

int MaxRows = this.MaxRowsToReturn;

this.RowsAffected = 10;

Procedure

1. Click View > Other Windows > Object Browser.

2. Expand OASyS DNA.Common.BLTServer.
3. Expand OASyS DNA.Common.BLTServer again.
4. Select BLTProcessor.
5. Select a property from the right-hand pane. A description and remarks will appear in the bottom
section of the Object Browser window.

25
.NET Clients introduction

Accessing OASyS DNA Net Configuration Data Store

The OASyS DNA Net Configuration Data Store is used to store system-wide information on security,
host names, and other information. It resides in Active Directory Lightweight Directory Services (ADLDS)
To access it from your component, you add a reference to OASySDNA.Common:

Procedure

1. Click View > Solution Explorer.

2. Expand your project until you see the References item.
3. Right-click References, and select Add Reference.
4. Go to the .NET tab, and double-click on OASySDNA.Common.
5. Click OK.
6. Go to the <name>Processor file and add the following line at the top:using
OASySDNA.Common.Config;

NOTE: The following example gets the virtual host name of the RealTime service.

OASySDNA.Common.Config.DNAService dnaService = new

DNAService();dnaService.Attach("MYSYSTEM","Realtime");string
szRealtimeHost = dnaService.GetVirtualHostName();

Accessing an OLE DB or ODBC Data Source

Data can be obtained from a variety of OLE DB and ODBC data sources, such as the SQL Engine and
MSSQL. Returned data can even be forwarded to the client. The following example queries the
RealTime database for a list of analog points belonging to the cmsgroup1 group. It then returns this list
to the client.

26
 .NET Clients introduction

Example: Executing a query against the RealTime database

using OASySDNA.Common.Config;

using OASySDNA.Common.DAL.ClientSDK;

using OASySDNA.Common.DAL.ServerUtilities;

DNAService dnaService = new DNAService (“Realtime”,

DNAEnvironment.SystemName);

string szADOConnectString;

//= dnaService.GetFQADOString();

DALService.Initialize(DNAEnvironment.SystemName);

szADOConnectString = SQLDriver.GetADOConnectionString("Realtime");

DALService.Shutdown();

// Connect to the Realtime database

ADODB.Connection conRealtime = new ADODB.ConnectionClass();

conRealtime.Open(szADOConnectString,"","",0);

ADODB.RecordsetClass rsReturn = new ADODB.RecordsetClass();

rsReturn.CursorLocation = ADODB.CursorLocationEnum.adUseClient;

rsReturn.Open("select name,curval from analog where \"group\" =

27
.NET Clients introduction

'cmsgroup1'", conRealtime,ADODB.CursorTypeEnum.adOpenStatic,
ADODB.LockTypeEnum.adLockBatchOptimistic,0);

// Disconnect the recordset from the source

rsReturn.ActiveConnection = null;

// Close the connection

conRealtime.Close();

// Create a new BLTRecordset from the results

BLTRecordset bltrsResults = new BLTRecordset();

bltrsResults.Recordset = rsReturn;

// Return the recordset to the client

this.AddRecordset(bltrsResults);

Executing Other Business Object Components

Often, one Business Object Component will perform a function that another component needs. It is easy
to chain calls to several Business Object Components to perform a large task.

To call other Business Object components, you use the OASySDNA.Common.BLTClient class. The
following example is a component that executes a function put on a series of RealTime points by calling
the Fnput component. In order to run this example, you must add a .NET reference to
OASySDNA.Common. You must also add the following line at the top of the <name>Processor file (C#
code):

using OASySDNA.Common.Config;

Calling other Components - Constructor

this.Parameters = new BLTParameterList();

this.Parameters.Add(newBLTParameter(“PointList”, typeof
(string),false,false));

this.Parameters.Add(new BLTParameter(“Command”, typeof (string),

false,false));

28
 .NET Clients introduction

Calling other Components - Process() method

string szPointList = this.Parameters.Item(0).Value.ToString();

string szCommand = this.Parameters.Item(1).Value.ToString();

string[] szPointArray = szPointList.Split (‘;’);

int i = 0;

//Attach to AD LDS and get the virtual host name // of the Realtime
database.OASySDNA.Common.Config.DNAService dnaService = new DNAService();

OASySDNA.Common.Config.DNAService dnaService = new dnaService();

dnaService.Attach(“CHRISS”,”Realtime”);

string szRealtimeHost =dnaService.GetVirtualHostName();

// Create the component on the Realtime host

OASySDNA.Common.BLTClient bltclient = new BLTClient();

bltclient.Create("Fnput",szRealtimeHost);

for(i=0;i<szPointArray.Length;i++)

string szPath = szPointArray[i];

string[] szPathArray = szPath.Split('.');

if(szPathArray.Length == 2)

string szTable = szPathArray[0];

string szPointName = szPathArray[1];

bltclient.AddParameter(szTable,false);

bltclient.AddParameter(szPointName,false);

29
.NET Clients introduction

bltclient.AddParameter(szCommand,false);

bltclient.Execute();

Directly accessing the RealTime Database

In some cases it may be more efficient to directly access the RealTime database, instead of using the
SQLEngine (OLE DB access).

The following example shows how components can access RealTime database using the RealTime
High Performance DB classes. The component takes two status points as input. The status points must
be two-bit input status points. The component returns the four-bit status represented by the combination
of the two points.

In order to run this example, you must add a .NET reference to

OASySDNA.RealTime.HighPerformanceSetDB andOASySDNA.RealTime.HighPerformanceDB.
You must also add the following line at the top of the <name>Processor file (C# code):

using OASySDNA.RealTime.HighPerformanceSetDB;

using OASySDNA.RealTime;

using OASySDNA.RealTime.HighPerformanceDB;

In addition, the component must be installed on all machines that host the RealTime service and the
component must run on the hot RealTime machine.

Constructor:

this.Parameters = new BLTParameterList();

this.Parameters.Add(new BLTParameter(

"Status1Name",typeof (string),false,false));

this.Parameters.Add(new BLTParameter(

"Status2Name",typeof (string),false,false));

this.Parameters.Add(new BLTParameter("Result",typeof (int),false,true));

30
 .NET Clients introduction

Process() method:

bool bAnyFeed1;

bool bAnyFeed2;

byte bytBitWidth1;

byte bytBitWidth2;

byte bStatus1Value;

byte bStatus2Value;

int bStatusRetval;

// Get the input parameters

string szStatus1Name = this.Parameters.Item(0).Value.ToString();

string szStatus2Name = this.Parameters.Item(1).Value.ToString();

// Open the Realtime database as the default user (required)

OASySDNA.RealTime.HighPerformance.RealTimeDatabase.Open();

// Bind to the status table

RealTimeTable rtStatus=new RealTimeTable("status");

// Create a key field for the status.name field

RealTimeStringField rtfName = new RealTimeStringField(rtStatus,”name”);

// Lock the status table for SAFE_READ

rtStatus.Lock(TableLockRequestType.SAFE_READ,0);

// Find the status records we need

RealTimeRecord rtrecStatus1 = rtStatus.FindRecord(rtfName,szStatus1Name);

RealTimeRecord rtrecStatus2 = rtStatus.FindRecord(rtfName,szStatus2Name);

// Lock the status records we need

31
.NET Clients introduction

// Wrap the following in a try-catch block so that we can unlock the

status table and records even if an exception occurs (the Lock methods
throw an exception if the lock cannot be achieved).

try

{rtrecStatus1.Lock(RecordLockRequestType.SAFE_READ,0);

rtrecStatus2.Lock(RecordLockRequestType.SAFE_READ,0);

// Get the field values that we need bAnyFeed1 =

rtrecStatus1.ReadBool("anyfeed");

bytBitWidth1 = rtrecStatus1.ReadByte("inbit.bitwi");

bAnyFeed2 = rtrecStatus2.ReadBool("anyfeed");

bytBitWidth2 = rtrecStatus2.ReadByte("inbit.bitwi");

if(bAnyFeed1 && bAnyFeed2 &&(bytBitWidth1 == 2) && (bytBitWidth2 == 2)){

bStatus1Value = rtrecStatus1.ReadByte("cursta");

bStatus2Value = rtrecStatus2.ReadByte("cursta");

this.Parameters.Item(2).Value = bStatusRetval;

bStatusRetval = bStatus1Value | bStatus2Value;

catch(System.Exception e)

// Let the BLT error handler handle the exception.

throw(e);

}finally{

// Unlock the status records

if(rtrecStatus1.Locked)

32
 .NET Clients introduction

{rtrecStatus1.UnLock();}

if(rtrecStatus2.Locked){rtrecStatus2.UnLock();}

if(rtStatus.Locked{

// Unlock the status table.

rtStatus.UnLock();

Security
A note about the security for Business Object Components.

Business Object Components use role-based security to provide component-level access control. Each
component can be configured to be accessible by a certain user or group of users. This configuration is
done at run-time.

As well, Business Object Components can determine the original calling client’s security information
(such as the user ID).

Determining the Calling User

To determine who the originator of a Business Object Component call is, you can use the built-in
OriginalClientDomainName and OriginalClientUserName properties of the BLTProcessor
class:

string szUserName = this.OriginalClientUserNamestring szDomainName =

this.OriginalClientDomainName

2.2 Deployment
The two principles that affect deployment of Business Object Components are Configuration and
Installation

Business Object Components are distributed the same as other OASySDNA dlls. A configuration file
specifies which components to load and who can access them.

The startup scripts for the associated product or service must be modified to start the application under
which the components will be loaded.

33
.NET Clients introduction

2.2.1 Determining where to install the Component during configuration

Business Object Components can be installed on any machine that has the OASyS DNA Suite installed.

Business Object Components may be started as part of any service or product. This leaves a lot of room
for choosing the installation location. In general, Business Object Components should be distributed and
installed as part of the product that contains them. For instance, the RealTime product contains many
Business Object Components that are distributed and installed with RealTime.

Another factor in choosing the installation location is the OASyS DNA SCADA Suite services that the
component uses. For example, a component that uses the RealTime.HighPerformanceDB class
must be installed on a RealTime host. This is because the HighPerformanceDB class accesses the
RealTime database directly on the local host.

BLT Host Applications

Business Object components run under BLTHost applications, which are collections of components that
are hosted by the same process.

The hosting process is called BLTHost.exe. Each Business Object BLT application is started by a
script that runs when the associated service is started. The applications are registered with the
Schneider Electric SCADA Suite process monitoring system. Each application will automatically load the
correct DLL at run-time to execute a given component.

This architecture allows Business Object Components to be grouped together in a single application or
split into multiple applications. Depending on your scalability needs, or for debugging purposes, you may
want to install all of your components in one application (standard) or use multiple applications.

Adding Components for Deployment

Each Business Object application is configured using a text configuration file located in the <install
dir>\config\BLT directory. Each configuration file must follow a naming convention:

<AppName>.txt

For instance, the Arbitration Business Object Components are configured as one application in the
Arbitration.txt file.

To configure a Business Object BLTHost application file and add your first component, create a new text
file with Notepad and add the following lines:

bobjYourNewComponent2DllName, DNA Permission - View

bobjYourNewComponent3DllName, DNA Permission - View
bobjYourNewComponent4DllName, DNA Permission – View

As indicated, the first part of the line contains the name of the Business Object Component DLL you
created above – without the .DLL extension. The second part is a list of security groups that have
access to the component. The DNA Permission – View group contains all users and will allow any
OASyS DNA user to access your component.

34
 .NET Clients introduction

Configuring Component security

Component security can be configured so that it limits the users that can access the component. Use
this procedure to see what permission groups are available.

You can choose seperate security permission group from the default to prevent unauthorized users from
accessing the component. You must choose one of the DNA Permission groups. To add more than one
group, separate them with commas as shown below:

bobjSomeComponent, DNA Permission - Control_SCADA, DNA Permission -

Supervise_SCADA

Procedure

1. Select Start > Programs > OASyS DNA > Network Management Console
2. Select Permissions from the list.

Configuring the Startup Scripts

Business Object component applications should be configured to start when the associated service
starts.

If Business Object Component applications start when the associated service starts, it ensures that the
OASyS DNA system will monitor the health of the application. It also ensures that the application will be
shut down properly when the service stops (allowing you to update the component DLLs). Each service
has run_processes scripts located under the <install dir>\scripts\<servicename> directory.
The run_processes script for your service should include code to start up the Business Object
Component application. To see an example examine the run_processes.csc file in the RealTime
directory and find the starting BLTHost.exe.

2.2.2 PC Installation (Using the Distribute Utility)

Once you have configured the text file defining the Business Object Component application, you are
ready to install the application. You can do this on both a developer PC and a project PC.

You should use the distribute utility to install your application on the appropriate project PC. The service
that your application is part of should have a text configuration file for use by distribute. This should
appear in the <install dir>\config directory. For example, the Common service has a
Common.txt configuration file. To configure your application for distribution, add the following lines to
the file on the project Engineering Station:

>bin\bobjYourComponent.dll-e >bin\bobjYourComponent.pdb>config\BLT
\YourAppComponents.txt

When you distribute the service, the Business Object Components will be installed automatically on the
target machine.

35
.NET Clients introduction

2.3 Testing and Debugging

You have to use the test applications to ensure the component is communicating with the client.

Since Business Object Components are not standalone executables, you will need to use a client to test
them. The blttestclient application is provided to assist you in testing. This client will exercise the
component and ensure that it is communicating properly with the client.

To run blttestclient, type blttestclient in a command prompt.

2.3.1 Debugging clients and components

There are several processes you can use to debug clients and components from Visual Studio.NET.

Currently, only Visual Studio .NET or the Microsoft Common Language Runtime (CLR) debugger can be
used to debug C# or VB.NET applications (i.e. managed code). The free Debugging Tools for Windows
package (included with OASyS DNA and downloadable from Microsoft) cannot be used to debug these
components.

While inside a Remote Desktop Connection or Terminal Services Client session, you will not be allowed
to use Visual Studio.NET to debug a local process that has not been started by your session. However,
you can debug any remote process using Visual Studio.NET from a Remote Desktop Connection.

Generating Symbolic Debugging Information

In order to debug your component, you must ensure that symbolic debugging information has been
generated for it and distributed to the correct host.

Procedure

1. Open your component’s project solution in Microsoft Visual Studio.NET on the Engineering Station or
your developer PC.
2. Choose View > Solution Explorer.
3. Right-click on the component’s project and select Properties.
4. Expand Configuration Properties, then select Build.
5. Ensure that Generate Debugging Information is selected (or set to True).
6. Repeat the above steps for each project configuration (Release and Debug).
7. Recompile the project. This will generate a .pdb file in the <install dir>\bin directory.
8. Distribute the .pdb file to the host on which the component is installed.

Determining the PID of the BLTHOST Process

All Business Object Components are hosted by the blthost.exe process. There are typically many
blthost processes running on a single machine. You can use the NMC to determine which process to
debug.

Procedure

1. Start the NMC.

2. Find the list of processes for the service to which your BLTHost belongs.
3. Make a note of the process ID for the BLTHost you want to debug.

36
 .NET Clients introduction

Figure 5 - NMC Processes for RealTime

Local Debugging Using Visual Studio .NET

When performing local debugging, you have to decide between the tool provided by Visual Studio.NET
or Microsoft CLR Debugger.
If the component resides on a PC that has Visual Studio.NET installed, you debug the component as
follows:

Procedure

1. Start Microsoft Visual Studio.NET on the host where the component is installed.
2. Click the Tools menu and select Debug Processes.
3. Select the BLTHost process that is hosting your application and click Attach.
4. Select Managed, then click OK.

Visual Studio.NET will attach to the process. You can then use the debugger to set a breakpoint in
your code. If the local host does not have source code installed, you can map a network drive to the
Engineering Station and open a source code file from there. When you stop debugging or close
Visual Studio.NET, the BLTHost process will terminate.

Local Debugging Using the Microsoft CLR Debugger

If the component resides on a PC that does not have Visual Studio .NET installed, then you can debug
using the Microsoft Common Language Runtime (CLR) debugger. This debugger is included with the
Microsoft.NET Framework SDK.

37
.NET Clients introduction

Verifying that the debugger is installed on your machine

Before attempting to debug a client or component, you may need to verify that the debugger is installed
and available for use.

Procedure

1. Open Windows Explorer.

2. Navigate to C:\Program Files\Microsoft.NET\FrameworkSDK\GuiDebug.
3. Locate the DbgClr.exe file. This is the CLR Debugger.

To download and install the Microsoft .NET Framework SDK, refer to the following web page:
http://msdn.microsoft.com/downloads/default.asp?url=/downloads/sample.asp?url=/msdn-files/
027/000/976/msdncompositedoc.xml

Debugging a Business Object Component using the CLR debugger

You can use the CLR debugger to load a source file and set a breakpoint in it, and you can also perform
debugging remotely.

Procedure

1. Open C:\Program Files\Microsoft.NET\FrameworkSDK\GuiDebug\DbgClr.exe.

2. Choose Tools > Debug Processes.
3. Double-click on the process that contains the component you want to debug.
4. Click Close.

You can now load a source file and set a breakpoint in it.

Verifying that the Visual Studio debugger is installed on your machine

When you navigate to the VS7 debug folder, there should be a number of files, including the Machine
Debug Manager (mdm.exe)

Procedure

1. Start Windows Explorer.

2. Navigate to C:\Program Files\Common Files\Microsoft Shared\VS7Debug.

If the Machine Debug Manager is not installed, you can install it yourself from the Visual Studio .NET
CD. You do not need an extra Visual Studio .NET license to install this.
For information on installing the Machine Debug Manager, refer to the Microsoft Developer Network
website:

http://www.msdn.microsoft.com

Search for Setting up Remote Debugging. You may also use the following direct link:

http://msdn.microsoft.com/library/en-us/vsdebug/html/vctskInstallingRemoteDebugMonitor.asp

38
 .NET Clients introduction

Debugging a Business Object Component

Before you can debug a Business Object Component, you must insure that the components necessary
for using the Machine Debug Manager are installed on the target machine.
After configuring the users that can debug Business Object Components on the target machine, you can
use the following procedure to debug a component. Go to http:// msdn.microsoft.com/library/en-us/
vsdebug/html/vxtskinstallingdcom.asp for more information on configuring users.

Procedure

1. Start Remote Desktop Connection or Terminal Services Client on the remote machine.
2. Log on to the Engineering Station, or another project PC that has Visual Studio.NET installed.
3. In the remote session, start Microsoft Visual Studio.NET.
4. Click Tools > Debug Processes.
5. In the Name field, select the host name of the target machine.
6. Double-click on the PID of the process hosting your component.
7. Select Managed check box, then click OK.

You can now set a breakpoint in your code.

Remote Debugging

If you do not have physical access to the machine hosting the component, you can debug it remotely
from another machine. The remote machine must be on the same domain as the machine hosting the
Business Object Component. In a typical remote debugging scenario, you can log on to the Engineering
Station using Terminal Services Client or Remote Desktop Connection and debug processes on another
project machine from that session, for example:

Developer station >---RTS session---->Engineering Station>---Visual Studio Debugger--->BLTHost

process on target machine

To remotely debug Business Object Components written in VB.NET or C#, the target machine must
have the Visual Studio remote debugging components (Machine Debug Manager) installed. All OASyS
DNA systems should already have this installed.

39
RealTime Business Objects

3 RealTime Business Objects

3.1 ACEAddCode
When a text string is provided, this business object adds the string as an ACE procedure in the system.

Syntax:

ACEAddCode <procedureName> <code>

Table 4 - Parameters
Name Description
procedureName This parameter is a unique identifier for an ACE procedure. The name is
composed of the procedure name, followed by a backslash ()\ and the
procedure type. For example:

testACE\ACE Engine CSharp.NET

The type is defined in the Editor Types configuration file for the languages
as shown below:

<EditorFileType>

<Name>ACE Engine CSharp.NET</Name>

code This parameter is the source code for the ACE procedure. This source
code includes the user code and the wrapper code that ACE inserts to
make a valid object that is easy to compile.

Example:
“...” represents the wrapper code.

ACEAddCode testAce

...
//<code>Output=input1+input2

...

Comments:

The RPC creates a record in the ACECode, and ACE souce code files are created on all servers
through cmxrep.

40
 RealTime Business Objects

3.2 ACECompile
The function of this business object is to compile the specified code.

Syntax:

ACECompile <procedureName> <code>

Table 5 - Parameters
Name Description
procedureName This parameter is a unique identifier for an ACE procedure. The
name is composed of the procedure name, followed by a
backslash ()\ and the procedure type. For example:

testACE\ACE Engine CSharp.NET

The type is defined in the Editor Types configuration file for the
languages as shown below:

<EditorFileType>

<Name>ACE Engine CSharp.NET</Name>

code This parameter is the source code for the ACE procedure. The
source code includes the user code and the wrapper code that
ACE inserts to make a valid object that is easy to compile

Example:

ACECompile testACE “F”

Comments:

The RPC gathers the source code for the specified ACE procedure from the file system and compiles it.
Any errors or warnings generated are returned to the caller in a datatable. If no errors are generated, the
datatable is empty. The datatable contains the columns explained in the following table.

Table 6 - Datatable columns

Column Name Description
Error This column displays the error message in string form.
Line This column indicates the line number in the source code where the
error occurs.
Column This column indicates the character number in the source code
(starting from the beginning of the Line) where the error occurs.
IsWarning This column displays a value of “True” of the error is actually a
warning. “False” represents an error.

41
RealTime Business Objects

3.3 ACEGetCode
This business objects function is to retrieve the code from the RealTime server.

Syntax:

ACEGetCode <ProcedureName> <code>

Table 7 - Parameters
Name Description
procedureName his parameter is a unique identifier for an ACE procedure. The
name is composed of the procedure name, followed by a
backslash ()\ and the procedure type. For example:

testACE\ACE Engine CSharp.NET

The type is defined in the Editor Types configuration file for the
languages as shown below:

<EditorFileType>

<Name>ACE Engine CSharp.NET</Name>

code This parameter is the source code for the ACE procedure. The
source code includes the user code and the wrapper code that
ACE inserts to make a valid object that is easy to compile

Example:

ACEGetCode testACE””

Comments:

If the code is not found, the output parameter is a blank string.

3.4 Acknowledge
This business object’s function is to acknowledge a list or page of alarms.

Syntax:

Acknowledge <tablename> <ptname> <fieldname> <category> [<tablename>

<ptname> [<fieldname> <category>]

42
 RealTime Business Objects

Table 8 - Parameters
Name Description
tablename The name of the RealTimeDB table whose record alarm is
acknowledged.
ptname The name of the record or point for which the alarm is
acknowledged
fieldname The name of the particular field for which the alarm is
acknowledged. A “*” here acknowledges alarms for all fields of the
specified table, point, and category.
NOTE: A NULL (“”) is considered to be a valid field name
category The name of the alarm category for which the alarm is
acknowledged. A “*” here acknowledges alarms for all categories
of the specified table, point, and field.
NOTE: A NULL (“”) is considered to be a valid field name

Example:

Acknowledge analog MasterAna_10*””

Comments:

The sequence of tablename, ptname, fieldname, and category parameters can be repeated for up to 40
individual alarms in a single call to Acknowledge.

This procedure is used primarily by ezXOS to perform page acknowledgement for alarm summary
displays. Individual alarms can be acknowledged using either Acknowledge or Fnput and the
appropriate function command. Nothing happens if acknowledge is not provided with parameters.
Related Information
AddDBalarm on page 44
AddSYSalarm on page 48
Almattr on page 49
Filteralm on page 56

3.5 Addarea
This business object’s function is to add an area to the list of areas on which a user is currently logged.

Syntax:

Addarea <area> [ <selControl> <selView> <control>]-d <displayName>

43
RealTime Business Objects

Table 9 - Parameters
Name Description
area The name of the area to be added to the user’s list. If a “*” is
specified all current areas are added.
selControl yes or no Indicates whether or not the user has selected this area for control.
Defaults to no.
selView yes or no Indicates whether or not the user has selected this area for
viewing. Defaults to no.
control yes or no Indicates whether or not the area is controllable by the user.
Defaults to no.

Example:

Addarea “LINE 3/4” no yes no

Addarea “LINE 3/4”

Comments:

This procedure fails if a display name is not set prior to being called.

The RealTime table that is used for this business object is xoslogins
Related Information
Droparea on page 55
Modarea on page 75
Xoslogin on page 93

3.6 AddDBalarm
This business object’s function add an alarm to a RealTimeDB table point. It is for internal use only.
Alarm generated solely by executing this RPC are transient unless additional RealTimeDB processing is
performed.

Syntax:

AddDBalarm <tableName> <ptName> <fldname> <category> <message>

<persistent> <inalarm> <flashing> <severity> <purgetime> <timestamp>
[<host>]

NOTE: The syntax shown is contained in one line. The RealTime database must be open before calling
AddDBalarm. Use VDB.OpenDatabase() to open the RealTime database.

Table 10 - Parameters
Name Description
tableName RealTimeDB table name
ptName RealTimeDB point name

Table continued…

44
 RealTime Business Objects

Table 10 - Parameters (continued)

Name Description
fldname The point field name
category The category to which the alarm belongs. This can be arbitrary. It is used to
distinguish alarms assigned to the same point. The category must be one
word. with no spaces.
message Alarm message to display.
persistent Indicates whether or not the alarm remains in the alarm summary after
acknowledgement or purge.
inalarm Can be yes, no. or nochange. This indicates whether or not the point is
declared to be in an alarm state (yes), a normal state (no), or has not changed
(nochange)
flashing Determines if the point should flash to indicate the alarm
severity Severity of the alarm, can be low, medium or high.
purgetimer Purge timer in seconds. The timer starts after the alarm is acknowledged. The
alarm is purged from the almsum table if the purge time has expired and the
persistent flag is “no”.
timestamp Timestamp for alarm (or 0 for current time).
host Name of the host that generated the alarm.

Comments:

If the alarm represents a state change, for example, the HI limit is exceeded, then the inalarm parameter
is used to flag whether or not the RealTimeDB point is considered to be in the alarm state or not. If the
momentary alarm, for example a command failure alarm, the the point’s alarm state should not be
changed and the inalarm parameter should be set to nochange.

The severity specified for the alarm using addDBalarm indicates the severity level for which the alarm
should appear in the alarm summary. This does not affect the alarm severity of the RealTimeDB point.
Apply the update command to the flag.severity field.
Related Information
AddSYSalarm on page 48
Almattr on page 49
Filteralm on page 56

3.7 addAPPalarm
This business object’s function is to add an application alarm.

Syntax:

AddAPPalarm <dbname> <ptname> <fldname> <description> <group> <category>

<almMsg> <persistent> <flashing> <severity> <purgeTimer> <timestamp>
<msec> <dataset> <host> <priorityDisplay>

NOTE: The above is entered as one line of syntax. The RealTime database must be open before calling
AddAppalarm. Use VDB.OpenDatabase() to open the RealTime database.

45
RealTime Business Objects

Table 11 - Parameters
Name Description
dbName Any string that is used to filter the alarm summary by table name, this is one of
the four parameters used to distinguish a unique alarm.This table does not
need to exist in RealTimeDB.
ptName Any string that is used t filter the alarm summary by point name, this is one of
the four parameters used to distinguish a unique alarm. This point does not
need to exist in RealTimeDB.
fldName Any string that is used to filter the alarm summary by field name, this is one of
the four parameters used to distinguish a unique alarm. This field does not
need to exist in RealTimeDB,
description A description of the value that is in alarm.
group The name of the AOR group.
category The category to which the alarm belongs, this is one of the four parameters
used to distinguish a unique alarm. Only one persistent alarm can exist for a
point for an alarm category.
message Alarm message to display.
persistent If false, the larm will be removed from the alarm summary after
acknowledgement. If true, in order to delete/replace the alarm, AddAPPalarm
must be called later with the same fldname and category, and with persistent
set to false.
flashing Determines if the point should flash to indicate the alarm.
severity Alarm severity, either low, minor, medium, major, high, critical.
purgetimer Purge time in seconds. The timer starts after the alarm is acknowledged. The
alarm is purged from the almsum table if the purge time has expired and the
persistent flag is “no”. Put a 0 not to invoke purge timer functionality.
timestamp Timestamp for the alarm, added in the format of number of seconds since
January 1, 1970 00:00 Greenwich Mean Time. If 0, the system assigns both
the timestamp and msec values automatically.
msec The number of milliseconds. Part of the combine timestamp value.
dataset The dataset name from the database.
host Name of the host that generated the alarm.
priorityDisplay The name of the priority exXOS display to associate with the alarm. Can be
blank.

Example:

AddAPPalarm “myDBName” “myPtName” “myFldName” “my description” “groupName” “myCategory”

“the alarmmessage” “no” “yes” “high” 0 0 0 “” “myhostName” “myDisplayName”
Related Information
Acknowledge on page 42
AddSYSalarm on page 48
Almattr on page 49
Filteralm on page 56

46
 RealTime Business Objects

3.8 AddFlexTag
This BLT adds one or more flexTag record.

Input Parameters

• dbName - the database of the (first) tagged point (analog, status, rate, or multistate).

• ptName - the point name of the (first) tagged point.

• tagType - the tag type of the record - the valid values can be found by calling
the GetFlexTagTypes BLT.

• paramList - a string with additional parameters, with zero or more entries separated by asterisks
(*).
NOTE: Within each item, the field name and value are separated by a pipe (|).

The paramList is of the form:

fieldName1|value1*fieldName2|value2*fieldName3|value3

In the paramList, additional tags can be created by specifying DBnPnt fields. The DBnPnt value is of
the form "point/database". This feature supports Tag Grouping, and if a DBnPnt is specified, the
tagGroup field must also be specified.

Results
The first result set contains the tags that were successfully added.
The second result set contains the tags that did not get added (including those not within the user's
AOR).

Examples

• dbName - analog

• ptName - point1

• tagType - Info1

• paramList –

Results:

database point tagType workOrder tagGroup description

analog point1 Info1

• dbName - analog

• ptName - point1

• tagType - Info1

• paramList - workOrder|myWorkOrder *description|point1 tag description

Results:

database point tagType workOrder tagGroup description

analog point1 Info1 myWorkOrder point1 tag
description

47
RealTime Business Objects

• paramList - workOrder|myWorkOrder *description|point1 tag description

• ptName - point1

• tagType - Info1

• paramList - workOrder|myWorkOrder *description|point1 tag

description*DBnPnt|point2/status*DBnPnt|point3/multistate*tagGroup|
myTagGroup

Results:

database point tagType workOrder tagGroup description

analog point1 Info1 myWorkOrder myTagGroup point1 tag
description
status point2 Info1 myWorkOrder myTagGroup point1 tag
description
multistate point3 Info1 myWorkOrder myTagGroup point1 tag
description

3.9 AddSYSalarm
This business object’s function is to add a RealTime Service system alarm to the database.

Syntax:

AddSYSalarm <key> <category> <messagetxt> <persistent> <flashing>

<severity> <purgetimer> <group> <timestamp> <msec> [<host>]

NOTE: The above is entered as one line of syntax. The RealTime database must be open before calling
AddSYSalarm. Use VDB.OpenDatabase() to open the RealTime database.

Table 12 - Parameters
Name Description
key A reference key for toggling the in alarm state of an alarm summary entry.
category The category to which the alarm belongs. This can be arbitrary. This is used to
distinguish similar alarms. The category must be one word without spaces.
messagetxt Alarm message to be displayed.
persistent This indicates whether or not the alarm remains in the alarm summary after
acknowledgement and purge.
flashing Indicates whether or not the point should be flashing.
severity Alarm severity, either low, medium, or high
purgetimer Purge timer, expressed in seconds. The timer starts after the alarm is
acknowledged. The alarm is purged from the almsum table. if the purge time
has expired and the persistent flag is “no”.
group The group name

Table continued…

48
 RealTime Business Objects

Table 12 - Parameters (continued)

Name Description
timestamp The timestamp of the alarm, added in the format of number of seconds since
January 1, 1970, 00:00 Greenwich Mean Time.
msec millisecond value of the timestamp
host The name of the host generating the alarm.

Example:
The following adds a test system alarm:

AddSYSalarm “test1” “low_alarm” “test system alarm” “no” “yes” “low” 10 “”

12345 “radserv1”

Comments:
Alarms generated solely by executing this RPC are transient unless additional RealTime Service
processing is performed.

The host is optional, but the timestamp and msec parameters are required.
Related Information
AddDBalarm on page 44
Almattr on page 49
Filteralm on page 56

3.10 Almattr
This business object’s function is to return the alarm attributes of the appropriately filtered maximum
severity unacknowledged alarm.The RealTimeDB tables this business object uses are: xoslogins, area,
and xosalmattr.

Syntax:

Almattr

Example:

Almattr

Frequency: 2

Delay: 1

Repeat: -1

The current maximum severity unacknowledged alarm beeps twice every second, with a delay every
second, with not end time set.

Comments:

If a display name is not set, then the maximum alarm is not filtered by area of responsibility. Otherwise,
the maximum alarm is filtered according to the areas where the user and display are currently logged.

49
RealTime Business Objects

If no alarm is detected. no row is returned.

Related Information
Addarea on page 43
AddDBalarm on page 44
AddSYSalarm on page 48
Droparea on page 55
Filteralm on page 56
Modarea on page 75

3.11 Checkin
This business object is called by ezXOS session to periodically update the check in time for a list of
areas. The check in time is set to the current time. It uses the area table in the RealTimeDB to do this.

Syntax:

Checkin <area> [<area ...>]

Table 13 - Parameters
Name Description
area The name of the area for which the check in time is to be updates. Up to eight
areas may be specified.

Example:

Checkin “LINE 3/4“ “northarea”

Comments:

The list of area should only include the areas that are currently under control by the user.

The check-in time is used by ezXOS to check whether or not the alarms for a particular area of
responsibility are currently being monitored by an ezXOS session.
Related Information
Acknowledge on page 42
Addarea on page 43
AddDBalarm on page 44
AddSYSalarm on page 48
Filteralm on page 56
Modarea on page 75

50
 RealTime Business Objects

3.12 CheckForDSTIssues
This business object’s function is to check for any potential issues with daylight savings time, when
given a date time. This is primarily used for checking DST issues for a dsh record.

Syntax:
CheckForDSTIssues <year>, <month>, <day>, <hour>, <minute>, <second>

Table 14 - Parameters
Name Description
year This parameter indicates the year of the datetime being checked. 0 indicates any
year.
month This parameter indicates the month of the datetime being checked. 0 indicates
any month.
day This parameter indicates the day of the datetime being checked. Values 1-7
correspond to different days of the week starting at 1 for Sunday. 0 indicates any
day.
hour This parameter indicates the hour of the datetime being checked. 0 indicates any
hour.
minute This parameter indicates the minute of the datetime being checked.0 indicates
any minute.
second This parameter indicates the second of the datetime being checked. 0 indicates
any second.

Comments:

After the BLT checks for any potential issues, it returns a tabular result with any findings. Potential
isuues are displayed as an errorNumber and corresponding errorMessage. The errorNumber is a
positive value if it represents a warning, and a negative value if it represents an error. Use the table
below to decode the errorNumber that is returned when this BLT is called.

errorNumber errorMessage Cause of error/ warning

0 No warnings or errors were detected.
-1 Error: Invalid time <datetime> An error was generated because the input
arguments were invalid.
-1 Error: Invalid time due to daylight An error was generated because the input time
savings time transition is invalid due to daylight savings time transition.
1 Warning: Ambiguous time for A warning was generated because the input
daylight savings time transition time is an ambiguous time for daylight savings
time transition.
2 Warning: This will skip the time A warning was generated because the input
when entering daylight savings time will be skipped when entering daylight
time. savings time.
3 Warning: This time will be A warning was generated because the input
repeated when leaving daylight time will be repeated when leaving daylight
savings time. savings time.

51
RealTime Business Objects

3.12.1 Daylight Savings Time (DST)

™ ™
The infrastructure of OASyS DNA 7.6 and OASyS DNA 7.5 uses UTC (Coordinated Universal Time),
a neutral form which is not affected by Daylight Savings Time (DST). How these times are converted for
your convenience varies by application.

For applications that include a timestamp (log files, NMC, AdminPager) the timestamp is converted to
the time zone that has been set for your computer. This setting can be accessed in the Microsoft Date
and Time Properties panel.

NOTE: Within the Historical documentation, there are references to both GMT and UTC. All fields refer
to data in the same time zone, the two notations are to indicate a difference in how the data is
represented. GMT represents a time in older tables which are stored in seconds. UTC
represents a time in newer tables which is stored as a SQL datetime2 data type.

Custom applications developed for your system may handle the UTC to DST conversion differently;
check with your Service manager if you have questions.

3.13 Collect_fields
This business object’s function is to return the names and data-types of columns in a specified table.

Syntax:

Collect_fields <table_name> [<key_name>]

Table 15 - Parameters
Name Description
table_name The name of the RealTimeDB table to be searched.
key_name The value of the key for the specific record in the RealTimeDB table. The
procedure returns the names of fields that are currently configured for
historical data collection from the record. This parameter is optional; if it is
not specified, the procedure returns the names of fields that may be
collected from the specified table.

Comments:

This procedure is used by the XOS Forms Editor to configure historical data collection of datapoints at
regular time intervals. Suitable table names may be listed by executing the Collect_tables procedure.
Related Information
Collect_tables on page 52
Trend on page 94

52
 RealTime Business Objects

3.14 Collect_tables
This business object’s function is to collect data from tables for timeline history through regular
sampling. The collect_tables registered procedure returns the names, unique key names, and
descriptions of these tables. It uses selected RealTime and application tables.

Syntax:

Collect_tables

Example:

Collect_tables

table_name unique_key description

analog name Analog structure descriptor
application name Application database structure
commline name Communications line
rate name Rate structure descriptor
remote name Remote terminal unit descriptor
status name Status structure descriptor
var name Software variable

(7 rows affected, return status = 0)

Comments:

This procedure is used by the XOS Forms Editor to configure historical data collection of data points at
regular time intervals.
Related Information
Collect_fields on page 52
Trend on page 94

3.15 ControlGroups
This business object’s function is to return an SQL “ where groupName in (<groups>” statement. This
statement filters data to include only AOR based objects you have control permission for. Control
permission is configured using the ezXOS Select Control Area dialog.

Syntax:

ControlGroups <display>

53
RealTime Business Objects

Table 16 - Parameters
Name Description
display The name of the ezXOS display session

Example:

ControlGroups “OASXOS_2”

This example returns a list of the groups of responsibility that may be controlled by the current
OASXOS_2 session

Comments:

This procedure is used primarily by ezXOS to retrieve information for filtering queries for data from
HistoricalDB.
Related Information
Addarea on page 43
GetActiveAORPermissions on page 62
Modarea on page 75
ViewGroups on page 92
Xoslogin on page 93

3.16 CreateXosCmdRec
This business object’s function is to create an ezXOS command with a unique name, given the access
name and type.

Syntax:

CreateXosCmdRec <accessName> <xostype? <winCmds>

Table 17 - Parameters
Name Description
accessName The user or display name.
xostype The control type: user control or MMI control.
winCmds A comma- separated list of ezXOS displays to be called up when it starts.

Example:

CreateXosCmdRec “Schneider Electric” “UserControl” “v_almsum”

(1 row affected. return status)

Comments:

If user control is specified, the ezXOS displays will be called up by the “accessname” parameter starting
ezXOS. If MMI Control is specified, the ezXOS displays will be called up when it is started on the ezXOS
stations specified by accesname (regardless of the user’s identity).

54
 RealTime Business Objects

3.17 Droparea
This business object’s function is to delete an area from the list of areas on which a user is currently
logged.

Syntax:

Droparea <area>

Table 18 - Parameters
Name Description
area The name of the area to be deleted from the user’s list. If no area name
is specified, all areas are deleted.

Comments:

This procedure used the xos logins table in the RealTime database. It will fail if a display name is not set
prior to being called.
Related Information
Addarea on page 43
Modarea on page 75
Xoslogin on page 93

3.18 Enumerate
This business object’s function is to list the enabled members of an enumerated type and their numerical
equivalents.

Syntax:

Enumerate <enumType>

Table 19 - Parameters
Name Description
enumType The name of the enumerated type.
enabled Allows only enabled or disable members of the enumeration to be shown.

Example:

Enumerate hilowstate

55
RealTime Business Objects

enumeration value
normal 0
hi 1
lo 2
dev 3
hi-hi 4
lo-lo 5
inst-hi 6
inst-lo 7
roc 8

Comments:

This procedure is used primarily by rhw XOS Forms Editor.

3.19 Filteralm
This business object’s function is to return filtered alarm summary data. Foreground color and flashing
status are returned along with up to 10 requested fields per alarm.

Syntax:
filteralm <skip> <almFilter> <ackFilter> <dbname> <ptname> <field <{field]>

Table 20 - Parameters
Name Description
skip The number of matching alarms to skip before returning data.
almFilter If this is yes, filteralm returns data that are in alarm, If this is no, filteralm
returns data that are not in alarm. If this is both, filteralm returns both data
that is and is not in alarm.
ackFilter If this is yes, filteralm returns unacknowledged alarms. If this is no,
filteralm returns acknowledged alarms. If this is both, filteralm returns
both acknowledged and unacknowledged alarms.
dbName The table that generated the alarm.
ptName The point on the table that generated the alarm.
field One or more field names from the almsum table. The values of these
fields are returned in addition to the foreground color integer (fgint), the
flashing status, and the severity (sevint) of the alarm.

Comments:
NOTE: Best practice is to use filterMaskedAlm instead of filterAlm.

Alarm information is returned, sorted in order from the highest to lowest severity. Within severity, the
data is sorted from newest to oldest.

56
 RealTime Business Objects

The alarm filter returns non-covered and/ or system alarms based on the configuration in the xosdisplay
table and the current user and display.

If no configuration is defined in the xosdisplay table for the user or display, both non-covered and system
alarms are returned.

The foreground color is based on the alarm severity. The relationship between alarm color and severity
is defined in the xosalmattr table. If the severity is not defined in the xosalmattr table, the color is
returned red(1).

If a display name is not set, then alarms are not filtered by area of responsibility. Otherwise, alarms are
filtered according to the areas on which the user and display are currently logged.

Example:
Filteralm 0 both both analog dbname ptname

fgint flash sevint dbname ptname

2 yes 1 analog test 1
2 yes 1 analog test 2
2 yes 1 analog test 3
2 yes 1 analog test 4
2 yes 1 analog

(4 rows affected) (return status = 0)

This example filters by the analog table. Notice that no point was indicated. This has the effect of
returning all the alarms in the analog table.
NOTE: By setting the dbname to “station” and ptname to the Remote name, filteralm can be used to
return all alarms from an remote.
Related Information
Addarea on page 43
AddDBalarm on page 44
AddSYSalarm on page 48
Almattr on page 49
Droparea on page 55
FilterMaskedAlm on page 59
Modarea on page 75

3.20 FilterFlexTag
FilterFlexTag lists all flexTag records that match the specified values.

Input Parameters

• dbName - the tagged database (analog, status, rate, or multistate).

• ptName - the tagged point.

• tagGroup - the tag group name.

57
RealTime Business Objects

• workOrder - the work order defined for the tag.

• tagType - the tag type of the record - valid values can be found by calling the GetFlexTagTypes
BLT.

• priority - all flexTag records that are the specified priority or higher priority will be returned.

− valid values in increasing order: undefined, low, minor, medium, high, critical.

• oldTag - only return tags gone past their expected removal date.

• messageSet - for status and multistate points, the message set of the point being tagged,

• skip - number of matching records to skip - used for scrolling in the ezXOS display.

Results
The result set lists all matching tags (within the user's AOR) in priority order.

Examples
Existing tags:

tagType priority table point

myWarn low analog ana1
myHighInh high analog ana2
myLowInh low analog ana3
myCritInh critical analog ana4
myHighInh high status sta1
myCritInh critical status sta2

Input to FilterFlexTag

• dbName = analog

• priority = high

Results

tagType priority table point

myCritInh critical analog ana4
myHighInh high analog ana2

3.21 FilterTag
This business object’s function is to list all tag records that match the specified values. The FilterTag BLT
is used for Existing tagging, not Flexible tagging.

Syntax:

FilterTag

58
 RealTime Business Objects

Table 21 - Parameters
Name Description
dbfilter (optional) This parameter is the database of the tagged point (analog, status, or
multistate).
ptfilter (optional) This parameter is the point name of the tagged point.
rtufilter (optional) This parameter is the remote associated with the tagged point.
wofilter (optional) This parameter is the work order defined for the tag.
tagtypeFilter (optional) This parameter indicates the type of the tag
skip (optional) This parameter indicates the number of matching records to skip. This
parameter is used for scrolling in the ezXOS display.

Example:

Input to Filtertag:
dbfilter = analog

ptfilter = myPoint

rtufilter = myRemote

wofilter = myWorkOrder

tagtypeFilter = no program cmds

skip = 100

Comments:

Thisbusiness object returns a list of all matching tags that correspond with your AOR.

3.22 FilterMaskedAlm
This business object’s function is similar to filterAlm (to return filtered alarm summary data) but with 2
added parameters. In order to see Test Mode alarms in ezXOS, FilterMaskedAlm must be used.

Syntax:
FilterMaskedAlm <skip> <almFilter> <ackFilter> <filterMask> <filterValue>
<dbname> <ptname> <field <{field]>

Property Type Property Description

skip The number of matching alarms to skip before returning data.
almFilter If this is yes, filteralm returns data that are in alarm. If this is no, filteralm returns data
that are not in alarm. If this is both, filteralm returns both data that is and is not in
alarm.
ackFilter If this is yes, filteralm returns unacknowledged alarms. If this is no, filteralm returns
acknowledged alarms. If this is both, filteralm returns both acknowledged and
unacknowledged alarms.
filterMask Allows you to specify which filter, using 0 for no filter and 1 test mode filtering.

59
RealTime Business Objects

Property Type Property Description

filterValue Allows you to specify the values of the filters, using 0 to hide test mode alarms and 1
to see test mode alarms.
dbname The table that generated the alarm.
ptname The point on the table that generated the alarm.
field One or more field names from the almsum table. The values of these fields are
returned in addition to the foreground color integer (fgint), the flashing status, and the
severity (sevint) of the alarm.

Comments:
NOTE: Best practice is to use filterMaskedAlm instead of filterAlm.

Example:

Table 22 - Filter application results

filterMask filterValue Expectation
0 0 No filtering is active; all alarms
are shown.
0 1 No filtering is active; all alarms
are shown.
1 0 Test mode filtering is active;
active test mode alarms are
hidden, but all other alarms are
shown.
1 1 Test mode filtering is active;
active test mode alarms are
shown, but all other alarms are
hidden.

Related Information
Filteralm on page 56

3.23 Fldget
This business object’s function is to perform a RealTimeDB field get. It reads a field’s value for a given
RealTime DB table point.

Syntax:

Fldget <table> <key> <field> -0 <value> [-d <displayName>]

60
 RealTime Business Objects

Table 23 - Parameters
Name Description
table The RealTime DB table name.
key The RealTimeDB table point name or number.
field The RealTimeDB table point field name.
value Output variable that stores the value of the field.

Example:

Fldget analog 1 hilow.doitdoit -0 value

Related Information
Fldput on page 61

3.24 Fldput
This business object’s function is to perform a RealTimeDB field put. It sets a field’s value for a given
RealTimeDB table point.

Syntax:

Fltput <table> <key> <field> <value>

Table 24 - Parameters
Name Description
table The RealTime DB table name.
key The RealTimeDB table point name or number.
field The RealTimeDB table point field name.
value Output variable that stores the value of the field.

Example:

Fldput analog 1 curval 1400

This example inserts a mew current value.

Related Information
Fldget on page 60

61
RealTime Business Objects

3.25 Fnput
This business object’s function is to perform a RealTimeDB function put. It executes a function put such
as “open“ or “close” for a RealTimeDB table point.

Syntax:

Fnput <table>, <key> <command>

Table 25 - Parameters
Name Description
table The RealTimeDB table name.
key The RealTimeDB table point name or number.
command The Command to run

Example:

Fnput status.1 open

This example commands a status point to open.

Fnput analog.grn3suctpress manval.30.1

This command sets the manual value of a analog point.

3.26 GetActiveAORPermissions
This business object returns a result set listing of all RealTime database groups for which you have
selected view and/or control access. The result set specifies whether or not you have view and/or
control permission for each group. The results of this business object change as you change the
selected view and control areas within your ezXOS session.

Syntax:
GetActiveAORPermissions

Comments:
NOTE: For user configured security settings that are independent of the ezXOS view and control
selections, use the GetUserAORPermissions BOR.

62
 RealTime Business Objects

Example:

Figure 6 - BOR Test Client - GetActiveAORPermissions results example

Table 26 - BOR Test Client - GetActiveAORPermissions results description

Column Description
groupName Contains the RealTime group point name.
NOTE: The row with the blank groupName
indicates the default permissions allowed
when accessing RealTime points that
have not had their group field configured.
canView An entry of 1 indicates that the group has view
permission and 0 indicates that permission has
not been given.
canControl An entry of 1 indicates that the group has control
permission and 0 indicates that permission has
not been given.

Related Information
ControlGroups on page 53
GetUserAORPermissions on page 71

63
RealTime Business Objects

ViewGroups on page 92
GetUserPermissions on page 104

3.27 GetFlexTagGroupMembers
Returns all points for a given group tag, along with their message set (for status and multistate points).

Input Parameters

• tagGroup (required) - a string specifying the tag group. If this input parameter is blank, it will return
all tagged points that have tags with a blank value for the tagGroup field (i.e. ungrouped tags).

Results
A result set with the following columns:
• Table

• Point

• Message set

Examples
In each case, the following flexTags are defined:

database point tagType tagGroup

analog ana1 InfoLow tagGroup1
analog ana1 InfoLow
analog ana2 WarningHigh tagGroup2
status sta1 InhCrit tagGroup1
status sta2 InfoLow tagGroup2
multistate mul1 InfoLow
multistate mul1 InhCrit tagGroup1
multistate mul1 InfoLow tagGroup1
multistate mul2 WarningHigh tagGroup2

The status points are defined as:

Name Message Set (flag.bmsg)

sta1 status
sta2 common

The multistate points are defined as:

Name Message Set (outBmsg)

mul1 multistate
mul2 common

Results from calling GetFlexTagGroupMembers with tagGroup =:

64
 RealTime Business Objects

Table Point Message set

analog ana1
multistate mul1 multistate

Results from calling GetFlexTagGroupMembers with tagGroup = tagGroup1:

Table Point Message set

analog ana1
status sta1 status
multistate mul1 multistate

Results from calling GetFlexTagGroupMembers with tagGroup = tagGroup2:

Table Point Message set

analog ana2
status sta2 common
multistate mul2 common

3.28 GetFlexTagGroupRestrictionStates
This BLT returns the output states that are common among a group of points. If even one point has
different output states, it returns an empty data set.

Input Parameters
DBnPnts (required) - a list of database points separated by an asterisk (*).

Results
The result set contains the message text for the message set configured for the specified points. These
strings will be used for selecting a state-specific restriction on a group (or sub-group) of tags.

Examples
Given the following configuration:
status.sta1 message set: OPEN, CLOSE

status.sta2 message set: OPEN, CLOSE

multistate.mul1 message set: OPEN, CLOSE

DBnPnts - sta1/status

Results:

OPEN

CLOSE

DBnPnts - sta1/status*sta2/status

Results:

65
RealTime Business Objects

DBnPnts - sta1/status*mul1/multistate

Results:

OPEN

CLOSE

3.29 GetProtocolTable
This business object’s function is tp specify the output parameter of a protocol. When the name of a
protocol is entered, GetProtocolTable returns the name of the RealTime table that is used to configure
the protocol records.

Syntax:

//Usage text

static char *usageTest=” @protocolType, @protocolTable output”; // one

parameter.

Example:

GetProtocolTable “OPC Client”

This example returns “opc” since opc is the name of the RealTime table used to configure OPC Client
protocols.

3.30 GetStatMsgTxt
This business object’s function is to return the text status point’s ON and OFF states and use as labels
for the buttons on the ezXOS control panel.

Syntax:

GetStatMsgTxt <tableName> <pointName><fldName> <msgstate1 output>

<msgstate2 output> <msgstate3 output> <msgstate4 output>

Table 27 - Parameters
Name Description
tableName The RealTimeDB table name.
pointName The RealTimeDB point name
fldName The RealTimeDB flag name
msgstate1 The message table base record
msgstate2 The message table base record + 1

Table continued…

66
 RealTime Business Objects

Table 27 - Parameters (continued)

Name Description
msgstate3 The message table base record + 2
msgstate4 The message table base record + 3

Example:

GetStatMsgTxt status stat1 flag -o msgstate1 -o msgstate2 -o msgstate3 -o

msgstate4

(return status

= 0)

Return parameters

ERR
OPEN

CLOSE

TRANSIT

Comments:

The fldName field has also been provided as a parameter, becacuse there are multiple flag structures
available for various tables.

In BLTTestClient, tableName, pointName, andd fldName are specified as input parameters. The
msgstate# parameters are output parameters.

3.31 GetSystemDOASPermissions
This business object’s function is to return a result set listing all RealTimeDB doas_dataset points. The
result set specifies whether or not your connected system, that is the system the BLT is executing on,
has ownership, control privileges and configuration privileges for points assigned to the doas_dataset.

Syntax:

GetSystemDOASPermissions

3.32 GetTableFieldsOfKind
This business object’s function is to return a list of all the fields of a specified kind in a table.

Syntax:
GetTableFieldsOfKind <TableName> <KindName>

67
RealTime Business Objects

Table 28 - Parameters
Name Description
Table Name This parameter indicates the name of the table you are requesting a list of
fields for.
Kind Name This parameter indicates the RealTime Kind that you want to look for in the
table.

Example:
GetTableFieldsOfKInd analog numeric

Comments:

The RPC creates a DataTable containing all of the field names of the specified Kind.

3.33 GetTablesWithFieldName
This business object’s function is to return a list of all the tables in the RealTime database containing the
specified field.

Syntax:

GetTablesWithFieldName <FieldName> <getUniqueStringKeyname?>

<forWriteAccess?>

Table 29 - Parameters
Name Description
FieldName This parameter indicates the name of the field you want to find.
getUniqueStringKeyName? This is an optional parameter. True indicates that only unique key string
fields are examined during the search for the specified field.
forWriteAccess? This is an optional parameter. True indicates that only fields to which you
have write access are returned

Example:

GetTablesWithFieldName dataset

Comments:

A DataTan;e os returned listing all of the tables containing the specified field.

If the getUniqueStringKeyName parameter is “True”, the DataTable will contain a second column
containing the unique key fields.

68
 RealTime Business Objects

3.34 GetTagGroupCurValve
Provides the current value for all of the user-modifiable tag fields (in flexTag), given a tag group and a
(possibly empty) set of points. This is used for determining what to display for the current value of fields
in a tag group or subset of points in a tag group.

Input Parameters

• TagGroup - the name of the tag group.

• DBnPnts - a list of database points separated by an asterisk (*), if empty all members of the tag
group will be considered.

Results
The result set contains the values for the following flexTag fields:
• curTagType

• cmsg

• workOrder

• description

• expectedRemovalDate

• operatorCmdOverride

If not all members of the tag group (or specified database points) have the same value, then the value
returned will be blank.

Examples
For all of the examples, assume the following flexTag records exist:

tagGrou database point curTagTy cmsg workOrd descripti expected operator

p pe er on Removal CmdOve
Date rride
TG1 analog ana1 warn wo1 ana1_war 1/1/2013 no
n 12:00:00.
000
TG1 analog ana2 no_comm wo1 ana1_no 1/1/2013 no
and 12:00:00.
000
TG1 status sta1 warn OPEN wo1 sta1_war 1/1/2013 no
n 12:00:00.
000
TG1 status sta2 no_comm CLOSE wo1 sta2_no 1/1/2013 no
and 12:00:00.
000
TG2 analog ana1 warn wo2 ana1_war 1/1/2013 no
n 12:00:00.
000

Table continued…

69
RealTime Business Objects

tagGrou database point curTagTy cmsg workOrd descripti expected operator

p pe er on Removal CmdOve
Date rride
TG2 analog ana2 no_comm wo2 ana2_no 1/1/2013 no
and 12:00:00.
000
TG2 status sta1 warn wo2 sta1_war 1/1/2013 no
n 12:00:00.
000

Input to GetTagGroupCurValue:

TagGroup =

DBnPnts =

curTagType cmsg workOrder description expectedRem operatorCmd

ovalDate Override
1/1/2013 no
12:00:00.000

Input to GetTagGroupCurValue:

TagGroup = TG1

DBnPnts =

Results:

curTagType cmsg workOrder description expectedRem operatorCmd

ovalDate Override
wo1 1/1/2013 no
12:00:00.000

Input to GetTagGroupCurValue:

TagGroup = TG1

DBnPnts = ana1/analog

Results:

curTagType cmsg workOrder description expectedRem operatorCmd

ovalDate Override
warn wo1 ana1_warn 1/1/2013 no
12:00:00.000

Input to GetTagGroupCurValue:

TagGroup = TG1

DBnPnts = ana1/analog*ana2/analog

Results:

70
 RealTime Business Objects

curTagType cmsg workOrder description expectedRem operatorCmd

ovalDate Override
wo1 1/1/2013 no
12:00:00.000

3.35 GetTaggingVersion
GetTaggingVersion returns the tagging version in effect (i.e., Existing tagging or Flexible tagging).
The BLT will read the USE_FLEXIBLE_TAGGING registry variable from config\Registry
\RealTime.xml to obtain this information.

Input Parameters
None.

Results

tag (for Existing Tagging)

- OR -

flexTag (for Flexible Tagging)

3.36 GetUserAORPermissions
This business object’s function is to return a result set listing all RealTime database groups. The result
set specifies whether or not you have view and/or control permission for each group. The information
indicates whether or not your security settings allow view and/or control, not if your view and/or control
permissions are enabled within an ezXOS session.

Syntax:

GetUserAORPermissions

Related Information
GetActiveAORPermissions on page 62

3.37 GetYMinMax
This business object’s function is to specify the point path from which the maximum and minimum y-axis
values are derived.

Syntax:

GetYMinMax <dataset>

The column format of the <dataset> parameter is:

71
RealTime Business Objects

Table 30 - Parameters
Dataset Column Dataset Column Type Description
Name
YAxisName string This parameter indicates the name of the trend/plot
y axis under consideration.
PenName string This parameter indicates the name of the pen
associated with the specified y-axis
PointPath string This parameter indicates the point path from which
the maximum and minimum y-axis values are
derived.

NOTE: There can be more than one pen associated with any given y-axis. While not used in the
baseline version of GetYMinMax, this column facilitates a level of project customization should it
become necessary for any given project to override or replace baseline functionality.

Comments:

Currently, baseline automatically retrieves minimum and maximum values for status, analog, rate, and
multistate point types. If customization is required, the BLT must be replaced with the custom version
and the parameter and results dataset column definitions must be honored.

3.38 Helpdb
This business object’s function is to display information on all RealTimeDB tables, or if specified a
particular RealTimeDB table.

Syntax:

helpdb {table_name]

Table 31 - Parameters
Name Description
table_name Information on the RealTimeDB table, which is specified by this parameter, is
displayed. If table_name is not given, a report on all RealTimeDB tables is
returned.

Example:

Helpdb analog

Name Points Data Overhead %Data Dimension

analog 7845 3772440 1590472 70.343127 8000

Comments:

72
 RealTime Business Objects

3.39 Helptype
This business object’s function is to display the definition of a RealTimeDB data-type or table.

Syntax:

Helptype <typename>

Table 32 - Parameters
Name Description
typename helptype returns a description of the RealTimeDB datatype specified by
this parameter.

Example:

Helptype analog

name kind description

var structure software variable
field type description
name pntname variable name
fltval double floating point value
intval int integer value
description pntdescription description of the member
key unique case sensitive
name yes no

Related Information
Enumerate on page 55

3.40 InterpTrend
This business object’s function is to retrieve collection/ summary data from the RealTime database
collect table and the Historical database TimeSeries or timeline table. It interpolates the start time and
end time values from previously collected values for all collect value points.

Syntax:

InterpTrend <tablename> <tagname> <columnname> <starttime> <endtime>

[showFieldTime]

73
RealTime Business Objects

Table 33 - Parameters
Name Description
tablename The name of the RealTimeDB/HistoricalDB table that contains the data to be
accessed. This can be any of the following: collect, hour, day, month, or year.
tagname The name of the point to be viewed.
columnname The column of the RealTimeDB/HistoricalDB tables to view. This can be any
of the following: value, minimum, maximum, and average. If the table name is
collect, the only column allowed is the value column. If the table name is not
collect, then the value column is the instantaneous value of the point.
starttime The time from which to begin the trend data. This is entered as an integer
representing GMT time, which is localized to your time zone.
endtime The time at which the trend data stops. This is entered as an integer
representing GMT time, which is localized to your time zone.
showFieldTime If the table name is collect, enter 1 to display the field timestamp of the
collection. Enter 0 or null to not display the field timestamp of the collection.

Example:
InterpTrend 'collect', 'analog.0analog.curval', 'value', 1401375720,
1401376860, 1

time milliseconds value status fieldTime fieldMillisecon

ds
1401375720 0 2 O 1401375720 0
1401375780 0 2 O 1401375780 0
1401375840 0 2 O 1401375840 0
1401375900 0 2 O 1401375900 0
1401375960 0 2 O 1401375960 0
1401376020 0 2 O 1401376020 0
1401376080 0 2 O 1401376080 0
1401376140 0 2 O 1401376140 0
1401376200 0 2 O 1401376200 0
1401376260 0 2 O 1401376260 0
1401376320 0 2 O 1401376320 0
1401376380 0 2 O 1401376380 0
1401376440 0 2 O 1401376440 0
1401376500 0 2 O 1401376500 0
1401376560 0 2 O 1401376560 0
1401376620 0 2 O 1401376620 0
1401376680 0 2 O 1401376680 0
1401376740 0 2 O 1401376740 0
1401376800 0 2 O 1401376800 0
1401376860 0 2 O 1401376860 0

74
 RealTime Business Objects

(20 rows affected)

Related Information
Collect_fields on page 52
Collect_tables on page 52
Trend on page 94

3.41 Modarea
This business object’s function is to modify an area within the list of areas.

Syntax:

Modarea <area> <[<selControl> <selView> <control>]>

Table 34 - Parameters
Name Description
area The name of the area to be modified in the user’s list. A “*” results
in all areas being modified.
selControl yes or no This indicates whether or not the user has selected the area for
control.
selView yes or no This indicates whether or not the user has selected the area for
viewing.
control yes or no This indicates whether or not the area can be controlled by the
user.

Example:

Modarea LINE 3/4 yes yes yes

Comments:
This procedure fails if a display name is not set prior to being called. If only the area parameter is given,
the area remains unchanged.

The control parameter must be set to yes if the selControl parameter is to be set to yes.
Related Information
Addarea on page 43
Droparea on page 55
Xoslogin on page 93

75
RealTime Business Objects

3.42 ModifyFlexTag
This BLT modifies all flexTag records that match.

Input Parameters

• paramList (required) - a string with "find" and "modify" parameters.

• At least one "modify" parameter is required.

• Entries are separated by asterisks (*).

• Witin each item, the paramater type (F or M), field name, and value are separated by pipes (|).

• The paramList is of the form: F|findFieldName1|value1*F|findFieldName2|value2*M|

modifyFieldName3|value3*M|modifyFieldName4|value4.

• In the paramList, the "find" items are AND'ed together, so that all fields must match.

• There is one exception to this rule - if DBnPnt items are specified, they are OR'ed together.

• DBnPnt values are of the form "point/database". This feature supports Tag Grouping.

Results
The first result set contains the matching tags that were successfully modified. The second result set
contains the matching tags that did not get modified (including those not within the user's AOR).

Examples
In each case, these are the flexTags defined before the ModifyFlexTag BLT is called (we assume
they are reset to these values):
Initial:

database point tagType workOrder description

analog ana1 InfoLow
analog ana2 WarningHigh
status sta1 InhCrit
status sta2 InfoLow
multistate mul1 InhCrit
multistate mul1 InfoLow
multistate mul2 WarningHigh

Records after ModifyFlexTag are called with paramList = M|workOrder|myWO * M|

description|new description:

database point tagType workOrder description

analog ana1 InfoLow myWO new description
analog ana2 WarningHigh myWO new description
status sta1 InhCrit myWO new description
status sta2 InfoLow myWO new description
multistate mul1 InhCrit myWO new description

Table continued…

76
 RealTime Business Objects

database point tagType workOrder description

multistate mul1 InfoLow myWO new description
multistate mul2 WarningHigh myWO new description

Records after ModifyFlexTag are called with paramList = F|database|analog * M|

description|analog tags:

database point tagType workOrder description

analog ana1 InfoLow analog tags
analog ana2 WarningHigh analog tags
status sta1 InhCrit
status sta2 InfoLow
multistate mul1 InhCrit
multistate mul1 InfoLow
multistate mul2 WarningHigh

Records after ModifyFlexTag are called with paramList = F|curTagType|InfoLow * M|

curTagType|WarningCrit:

D=database point tagType workOrder description

analog ana1 WarningCrit
analog ana2 WarningHigh
status sta1 InhCrit
status sta2 WarningCrit
multistate mul1 InhCrit
multistate mul1 WarningCrit
multistate mul2 WarningHigh

Records after ModifyFlexTag are called with paramList = F|DBnPnt|ana2/analog*F|

DBnPnt|sta2/status*F|DBnPnt|mul2/multistate*M|description|subset:

databse point tagType workOrder description

analog ana1 InfoLow
analog ana2 WarningHigh subset
status sta1 InhCrit
status sta2 InfoLow subset
multistate mul1 InhCrit
multistate mul1 InfoLow
multistate mul2 WarningHigh subset

77
RealTime Business Objects

3.43 RemoveFlexTag
Removes all flexTag records that match.

Input Parameters

• paramList (required) - a string with parameters to match.

• At least one parameter is required - this prevents all of the tags from being accidentally deleted.

• Entries are separated by asterisks (*).

• Within each item, the field name and value are separated by pipes (|).

• The paramList is of the form: fieldName1|value1*fieldName2|value2.

• In the paramList, the items are AND'ed together, so that all fields must match.

• There is one exception to this rule - if DBnPnt items are specified, they are OR'ed together.

• DBnPnt values are of the form "point/database". This feature supports Tag Grouping.

Results
The first result set contains the matching tags that were successfully deleted. The second result set
contains the matching tags that did not get deleted (including those not within the user's AOR).

Examples
In each case, these are the flexTags defined before the RemoveFlexTag BLT is called (we assume
they are reset to these values):
Initial:

database point tagType workOrder description

analog ana1 InfoLow
analog ana2 WarningHigh
status sta1 InhCrit
status sta2 InfoLow
multistate mul1 InhCrit
multistate mul1 InfoLow
multistate mul2 WarningHigh

Records after RemoveFlexTag is called with paramList = database|analog:

database point tagType workOrder description

status sta1 InhCrit
status sta2 InfoLow
multistate mul1 InhCrit
multistate mul1 InfoLow
multistate mul2 WarningHigh

Records after RemoveFlexTag is called with paramList = database|analog * curTagType|

InfoLow:

78
 RealTime Business Objects

database point tagType workOrder description

analog ana2 WarningHigh
status sta1 InhCrit
status sta2 InfoLow
multistate mul1 InhCrit
multistate mul1 InfoLow
multistate mul2 WarningHigh

Records after RemoveFlexTag is called with paramList = DBnPnt|ana1/analog*DBnPnt|sta2/

status* curTagType|InfoLow:

database point tagType workOrder description

analog ana2 WarningHigh
status sta1 InhCrit
multistate mul1 InhCrit
multistate mul1 InfoLow
multistate mul2 WarningHigh

3.44 Request Access

This business object’s function is to set or clear an advisory flag on the specified record within the
specified table.

Syntax:

RequestAccess <tableName> <ptName> <action> <[ptName,action]>

Table 35 - Parameters
Name Description
tableName The RealTimeDB table name.
ptName The table row name.
action Specifies the action required (set, clear, or test)

Comments:

requestAccess sets, clears, or tests the status of the advisory flag on the specified record.

All applications that configure RealTime DB tables should obey the advisory flag and use the
requestAccess RPC.

Request access has the folowing return values:

79
RealTime Business Objects

• 0- the access request is successful or the flag is currently clear. If action =”set” abd tge accessFlag
field is “clear”, 0 is returned

• 1 - the access request flag is currently set. If action = “test” or “set”, and the accessFlag is “set”, 1 is
returned

• 2 - the point does not exist

• 3 - unknown access re quest action

• 4 - VDB Library error

• read only access allowed

requestAccess returns two columns of results. However, it returns one column if any of the following is
true:

• The tableName is incorrect or inaccessible

• One of the actions is invalid

• A single action was specified

Multiple commands are primarily used to both clear one accessFlag and set the next accessFlag in a
single operation.

3.45 RouteSwitch
This business object's function is to trigger the switch between the Primary and Alternate replication
routes configured in the storeAndForward table. It can be used to go back and forth. When routes are
not used by the mode that is currently active (primary or alternate), they are placed in a suspended state
and wait for activation.

Syntax:
RouteSwitch <override> <ModeName>

Table 36 - Parameters
Name Description
override Specify yes to override the need for all systems to be connected
and synchronized. This will allow you to switch routes regardless of
whether or not the system is currently available and
communicating. The behavior of the override parameter defaults to
no and the routes cannot be switched if the systems are not
connected and synchronized.
ModeName Entering primary causes the BLT to attempt a route switch to the
primary destination configured in the Store and Forward table.
Entering alternate causes the BLT to attempt a route switch to
the alternate destination. In order for the RouteSwitch BLT to
succeed, the override paramater must be entered as yes in both
cases if not all systems are connected and synchronized.

80
 RealTime Business Objects

Example 1:

Assume that all systems are connected and synchronized in alternate mode. Entering RouteSwitch
yes primary will result in calls to the RemoteRouteSwitchActivation BLT on each remote system
and the local machine. This enables the routes to be switched from alternate to primary on all machines.
Since an override is not required because all systems are connected and synchronized, entering
RouteSwitch and letting the override parameter default to no would still work. An override is not
required since all systems are connected and synchronized.

Example 2:

Assume that not all systems are connected nor synchronized, and that the last known state of the
storeAndForward routes is that all systems were operating on primary routes. RouteSwitch yes
alternate results in an attempt to call the RemoteRouteSwitchActivation BLT on each remote
system in order for the routes to be switched from primary to alternate. However, allowing the override
parameter to default to no prevents the RouteSwitch BLT from attempting the route switch on remote
machines. If the BLT is entered as such in this scenario, an error message is returned to indicate that all
systems must be synchronized unless the override is performed.

Comments:

The RouteSwitch BLT calls the RemoteRouteSwitchActivation BLT on all remote systems that
require it. This gets them to perform the route switch for their local routes. If you are currently operating
with the primary route active, calling this BLT results in an attempt to switch all routes to the alternate
routes configured in the storeAndForward table.
NOTE: If nothing is configured in the storeAndForward table and this BLT is used, an error message is
returned that states that the function is not allowed.
If the RouteSwitch BLT commands a system to switch into the route that it is already in,
RemoteRouteSwitchActivation will not run on that system. Note that the current system can fall
out of sync with other systems. You want all systems to be using the same route. The specification of
ModeName allows you to command synchronization to the route you desire, so that if some systems are
primary and some are alternate, specifying alternate causes RemoteRouteSwitchActivation to
run only on the systems that are using the primary route.

NOTE: You must allow the system to stabilize in between uses of the RouteSwitch BLT, otherwise the
synchronization between systems will be compromised. When the RouteSwitch BLT is
executed, an event is generated at the system from which it is executed. This event tells you
that the route switch was activated and from which location it was, as well as the current mode
and new mode. This event is generated whether the BLT is executed successfully or only
partially. If the RouteSwitch is only partially executed, it is likely that not all systems are
connected nor synchronized. In this case, the override should be used.

3.45.1 RemoteRouteSwitchActivation
This business object is usually executed internally to perform the route switch between primary and
alternate StoreAndForward routes on remote machines. You do not usually enter this BLT manually.

Syntax:
RemoteRouteSwitchActivation <originalCallingUserName>
<originalCallingHostName> <originalCallingSystemName>

81
RealTime Business Objects

Table 37 - Parameters
Name Description
originalCallingUserName The name of the user that called the RouteSwitch BLT. This
parameter is used to issue events that occur as a result of a route
switch.
originalCallingHostName The name of the computer from which the RouteSwitch BLT was
executed. This parameter is used to issue events that occur as a
result of a route switch.
originalCallingSystemName The name of the system from which the RouteSwitch BLT was
executed. This parameter is used to issue events that occur as a
result of a route switch.

Example:
RemoteRouteSwitchActivation dnaOperator1 backupRTS1 Backup
The example above shows the parameters that would be automatically passed to the remote systems
from the machine that initiated the RouteSwitch BLT. This example means the BLT was initiated by a
user named dnaOperator1 at server backupRTS1, which is part of the Backup system. The remote
systems need this information in order to perform their route switches.

Comments:

This BLT is called as a result of the execution of the RouteSwitch BLT. When that is called, it triggers
this BLT, which will perform the actual route switch between the primary and alternate storeAndForward
routes on the local system where first BLT was called. Futhermore, it may also forward itself to any
downstream systems configured in the storeAndForward table.

Usually, the parameters this BLT requires (username, hostname, and system name) are generated
automatically when RouteSwitch is executed.

Figure 7 - RouteSwitch BLT Executed on the Backup Machine

Following the configuration shown above, if the RouteSwitch BLT is executed from the Backup
system, the Main system forwards the RemoteRouteSwitchActivation call to the Submaster
systems. This passes along the information required for the parameters needed by
RemoteRouteSwitchActivation. This gives the Submaster systems the ability to be responsible for
switching their own routes by executing this BLT.

82
 RealTime Business Objects

NOTE: This BLT will return true or false depending upon whether or not it was successful. You should
not need to enter this BLT manually.

3.45.2 Scenarios Requiring Use of the RouteSwitch BLT

The RouteSwitch BLT can be used with the override to allow you to recover functioning replication
between systems if one goes down.

Example Configuration

Figure 8 - Primary and Alternate Routes

In this example, Es owns the data which is replicated to Main or Backup depending on the active mode.
In primary mode, Main is the forwarding system and sends data to Backup and Dss. When the alternate
mode is active, the Backup system forwards the data. Assuming that the Primary mode is active, there
are two scenarios in which you would need to use the RouteSwitch BLT from a system that is not the
forwarding system.

Main Becomes Disconnected

The RouteSwitch BLT allows you to issue a route switch from any other machine in the system if Main
becomes disconnected from the rest of the systems. The RouteSwitch BLT must be issued using the
override option in this scenario. For example, if Main goes down, you could initiate the route switch by
using the BLT from Es, Backup or Dss. This switches the active route to the Alternate, where Backup is
the forwarding system. The BLT would be entered as follows: RouteSwitch yes . Issuing the BLT
triggers the RemoteRouteSwitchActivation BLT, that causes the routes to be switched on all
machines.

Route Switch is Triggered, but Backup is Disconnected

Assuming that you triggered a route switch from the Primary to Alternate route, but Backup was
disconnected, it would result in suspension of the Primary routes and the activation of the Alternate
route could not be completed because Backup is not available to be the forwarding system. In this
scenario, no replication would be happening. All routes would either be suspended or inactive.

This scenario can be fixed by reissuing the RouteSwitch BLT, using the override parameter, from any
of the other machines. This will allow Main to resume control as the forwarding system. The BLT would

83
RealTime Business Objects

be entered as follows: RouteSwitch yes. Issuing the BLT triggers the

RemoteRouteSwitchActivation BLT that causes the routes to be switched back on all machines.

3.46 RtTrend
This business object’s function is to retrieve instantaneous trend data from RealTimeDB.

Syntax:

RtTrend <table_name> <rec_name> <field_name><{unusedInt, unusedInt2]>

Table 38 - Parameters
Name Description
table_name The RealTimeDB table name of the data to be accessed.
rec_name The point name to be viewed.
field_name The field of the RealTimeDB tables to be viewed. This must ne a field
containing a numeric value.
unusedInt This parameter is not used. It is provided for backward compatibility only
unusedInt2 This parameter is not used.

Example:

RtTrend analog, CROSS0001, curval, value

time milliseconds value status

801355620 0 80.000000 M

Comments:

unusedint and unusedint2 are optional parameters. Int the example above, value is used as one of
these parameters.
Related Information
Trend on page 94

3.47 ShowAccessFlags
This business object’s function is to display information on a point’s access flags

Syntax:

ShowAccessFlags [<skip>] [-d <displayName>]

84
 RealTime Business Objects

Table 39 - Parameters
Name Description
skip Skip the first n rows of results

Example:

ShowAccessFlags

table point key_0 key_1 key_2 key_3 key_4 key_5 XOSdisplay current_user
analog 1 wrsucpre NULL NULL NULL NULL NULL NorthConsol supervisor1
ss e
status 3 wr2invalv NULL NULL NULL NULL NULL CasualUser1 NULL
e

(2 rows affected)

Comments:

The current_user appears as NULL if the ezXOS display is no longer logged on. Otherwise, the system
user’s record name of the current ezXOS display log-on session appears.

3.48 SpoolMsg
This business object’s function is to spool a message to a spooler. The RealTime database must be
open before calling SpoolMsg. You can use VDB.OpenDatabase() to open the RealTime database.

Syntax:

SpoolMsg <spooler> <time> <msec> <type> <host> <process> <dbName> <ptname>

<description> <rtu> <group> <message> <severity> <color>

Table 40 - Parameters
Name Description
spooler The spooler to which the message is directed.
time The timestamp for the spooler message.
msec The millesecond value of the timestamp.
type The type of message. This can be any of the following: alarm, control,
event, or sequence of events (soe)
host The name of the host where the message came from.
process The name of the process generating the message.
dbName The RealTimeDB table name or “” if there is none.
ptName The RealTimeDB point name or “” if there is none.
description The long description of the point, or “”.
rtu The name of the remote at which the point is located or “”.

Table continued…

85
RealTime Business Objects

Table 40 - Parameters (continued)

Name Description
group The group name of the point, or “”.
message The text of the message to be spooled.
severity The message priority.
color The alarm color (for future use).

Example:
To spool a test event message:

SpoolMsg 1,0,0, “event”, “OASXIS1”, “”,””,””,””,””,”group1”,”a test event

message”, 1, “white”

Comments:
A timestamp for the current time can be determined by using the Utility Open Server getDate call.

3.49 StoreAndForwardSummary
This business object's function is to retrieve configuration details from the StoreAndForward database to
help you determine if you want to perform a route switch. Different information will be retrieved
depending on how the BLT is entered and whether the route is in Primary or Alternate mode.

Syntax:

StoreAndForwardSummary <systemName> <activeMode>

Table 41 - Parameters
Name Description
systemName Enter the name of the source system that is responsible for
replicating the data that it owns or the data that it is forwarding.
This parameter can also be left blank.
activeMode Enter yes if you want the BLT to return the list of destination
systems for the active mode of the specified system. Enter no if
you want the BLT to return the list of destination systems for the
mode that is currently inactive on the specified system. This
parameter can also be left blank.

Example:
StoreAndForwardSummary es yes
Entering the BLT as shown above returns the list of destination systems for the active mode on es.
Assuming that the es system is the source system in Primary mode and has three destination systems
configured in the StoreAndForward database, the results appear as shown in the table below.

86
 RealTime Business Objects

Table 42 - Results Table in Business Object Test Client

Mode Source Destination
Primary backup main
Primary dss main
Primary es main
Primary main es
Primary main backup
Primary main dss

Comments:

Entering this BLT without specifying parameters returns a list of all primary and alternate destination
systems configured in the StoreAndForward database. Entering this BLT and only specifying the
<system name> returns a list of all primary and alternate destination systems configured for that system.
Entering this BLT with <systemName> and no returns a list of destination systems configured in the
StoreAndForward database for the inactive mode; for instance, if the active mode is primary, entering
the BLT in this way returns the configuration for the system's alternate mode.

In order to get the full picture of StoreAndForward configuration for the route that is currently active, you
can enter this BLT using yes for the <activeMode>, but without specifying the <systemName>.
Conversely, the configuration for the mode that is currently inactive will be retrieved if you use no for the
<activeMode> without supplying a <systemName>. This is an ideal method for using this BLT to
consider performing a route switch as it returns the configuration that will happen as a result of one.

3.50 TestModeSupported
This business object’s function is to list the tables available for test mode configuration, This includes the
baseline supported tables and any tables defined through extension.

Syntax:

TestModeSupported

Example:

If no extra tables have been defined to use test mode:

analog
multistate
rate
remote
status

If the Plm table is defined to use test mode:

analog
multistate
rate
remote

87
RealTime Business Objects

status
plm

Comments:

The result set contains the names of all tables that are able to have test mode defined.

3.51 Trend
This business object’s function is to retrieve collection and summary data from the RealTime database
collect table and the Historical database TimeSeries or timeline table.

Syntax:

Trend <tablename> <tagname> <columnname> <starttime> <endtime>

[showFieldTime]

Table 43 - Parameters
Name Description
tablename The name of the RealTimeDB/HistoricalDB table that contains the data to
be accessed. This can be any of the following: collect, hour, day, month,
year.
tagname The name of the point to be viewed.
columnname The column of the RealTimeDB/HistoricalDB tables to view. This can be
any of the following: value, minimum, maximum, average. If the table
name is collect, the only column allowed is the value column. If the table
name is not collect, the value column is the instantaneous value of the
point. (The value at the top of the hour).
starttime The time from which to begin the trend data. This is entered as an integer
representing GMT time, which is localized to your time zone.
endtime The time at which the trend data stops. This is entered as an integer
representing GMT time, which is localized to your time zone.
showFieldTime If the table name is collect, enter 1 to display the field timestamp of the
collection. Enter 0 or null to not display the field timestamp of the
collection.

Example:

Trend 'collect', 'analog.0analog.curval', 'value', 1401375720, 1401376860,

1

time milliseconds value status fieldTime fieldMillisecon

ds
1401375720 0 2 O 1401375720 0
1401375780 0 2 O 1401375780 0
1401375840 0 2 O 1401375840 0

Table continued…

88
 RealTime Business Objects

time milliseconds value status fieldTime fieldMillisecon

ds
1401375900 0 2 O 1401375900 0
1401375960 0 2 O 1401375960 0
1401376020 0 2 O 1401376020 0
1401376080 0 2 O 1401376080 0
1401376140 0 2 O 1401376140 0
1401376200 0 2 O 1401376200 0
1401376260 0 2 O 1401376260 0
1401376320 0 2 O 1401376320 0
1401376380 0 2 O 1401376380 0
1401376440 0 2 O 1401376440 0
1401376500 0 2 O 1401376500 0
1401376560 0 2 O 1401376560 0
1401376620 0 2 O 1401376620 0
1401376680 0 2 O 1401376680 0
1401376740 0 2 O 1401376740 0
1401376800 0 2 O 1401376800 0
1401376860 0 2 O 1401376860 0

(20 rows affected)

3.52 Trend_filter
This business object’s function is to retrieve a list of points that can be trended by ezXOS.

Syntax:

Trend_filter [<skip> <onCollect> <rtu> <group>]

Table 44 - Parameters
Name Description
skip An integer number of matching rows to skip before returning any rows.
Defaults to 0, meaning no rows are skipped.
onCollect This parameter can be set to yes or no. It defaults to yes, meaning only
points that are currently being collected are returned. If this parameter is
set to no, all points that have been placed on collect are returned.
However, the name of points that have been recently placed on collect
(new points) are not returned. This is because data for new points does
not yet exist in the HistoricalDB

Table continued…

89
RealTime Business Objects

Table 44 - Parameters (continued)

Name Description
rtu The name of the remote; only piints from the specified remote are
returned. If no remote is specified, remote filtering is not enforced.
Defaults to no remote, or “”.
group The name of the group of responsibility; only points that belong to the
specified group are returned. If no group is specified, group filtering is not
enforced. Defaults to no group, or “”.

Example:

Trend_filter 0 yes HWZRTU

Comments:
This procedure is primarily used by ezXOS.
Related Information
Trend on page 88
Trendview on page 90

3.53 Trendview
The function of this business object is to retrieve collection or summary data from the RealTime
database collect or Historical database TimeSeries or timeline tables.

Syntax:

Trendview <tablename> <tagname> <columnname> <starttime> <endtime>

[showFieldTime]

Table 45 - Parameters
Name Description
tablename The name of the RealTimeDB/HistoricalDB table that contains the data to
be accessed. This can be any one of the following: collect, hour, day,
month, or year.
tagname The name of the point to be viewed.
columnname The column of the RealTimeDB/HistoricalDB tables to be viewed. This can
be any of the following: value, minimum, maximum or average. If the table
name is collect, the only column allowed is the value column. If the table
name is not collect, then the value column is the instantaneous value of
the point.
starttime The time at which to begin the trend data. This is entered in the MM/DD/
YYYY HH:MM:SS format (as per your computer’s Regional and
Language settings).

Table continued…

90
 RealTime Business Objects

Table 45 - Parameters (continued)

Name Description
endtime The time at which the trend data stops. This is entered in the MM/DD/
YYYY HH:MM:SS format (as per your computer’s Regional and
Language settings).
showFieldTime If the table name is collect, enter 1 to display the field timestamp of the
collection. Enter 0 or null to not display the field timestamp of the
collection.

Example:

Trendview 'collect', 'analog.0analog.curval', 'value', '2014-05-29

13:35:00', '2014-05-29 13:42:00', 1

time millisecon status timestamp value fieldTimes fieldMillise

ds tamp conds
2014-05-29 0 O 2014-05-29 2 2014-05-29 0
13:35:00 13:35:00 13:35:00.0
000
2014-05-29 0 O 2014-05-29 2 2014-05-29 0
13:36:00 13:36:00 13:36:00.0
000
2014-05-29 0 O 2014-05-29 2 2014-05-29 0
13:37:00 13:37:00 13:37:00
2014-05-29 0 O 2014-05-29 2 2014-05-29 0
13:38:00 13:38:00 13:38:00.0
000
2014-05-29 0 O 2014-05-29 2 2014-05-29 0
13:39:00 13:39:00 13:30:00.0
000
2014-05-29 0 O 2014-05-29 2 2014-05-29 0
13:40:00 13:40:00 13:40:00.0
000
2014-05-29 0 O 2014-05-29 2 2014-05-29 0
13:41:00 13:41:00 13:41:00.0
000
2014-05-29 0 O 2014-05-29 2 2014-05-29 0
13:42:00 13:42:00 13:42:00.0
000

(8 rows affected)

3.54 UpdateCollect
This business object’s function is to modify collect data and re-summarize the affected day, month, and
year. It can add, delete, or change the collect data that exists in the Historical database collect table.

91
RealTime Business Objects

The procedure automatically re-summarizes the data for the Historical database hour, day, month, and
year tables.

Syntax:

UpdateCollect <pointName> <time> <milliSec> <value> <operType>

[<fieldTime> <fieldMillisec>]

Table 46 - Parameters
Name Description
pointName The name of the point to be modified.
time The time of the affected collect data to be modified. This value is shown
as 'YYYY-MM-DD hh:mm:ss' format (as per your computer’s Regional
and Language settings).
milliSec The field shows the millisecond value of the time field.
value The new value of the point after modification or addition. This
parameter is ignored during deletions.
operType There are three potential actions: ADD, MOD, and DEL.
fieldTime The new value of the field timestamp. This value is shown as 'YYYY-
MM-DD hh:mm:ss' format (as per your computer’s Regional and
Language settings).
fieldMillisec The field shows the millisecond value of the fieldTime field.

Example:
UpdateCollect 'analog.03_billt.curval' '2014-06-01 13:45:05' 35 75.3 'ADD'
'2014-06-01 13:45:18' 174

(1 row affected)

3.55 ViewGroups
T his BLT returns a SQL “groupName in (<groups>” statement. This statement filters data to include only
AOR based objects for which you have view permission. View permission is configured using tthe
ezXOS Select View Area dialog.

Syntax:

ViewGroups <display>

Table 47 - Parameters
Name Description
display The name of the ezXOS display session.

Example:

ViewGroups “OASXOS_2”

92
 RealTime Business Objects

This example returns a list of the groups of responsibility that can be viewed by the current OASXOS_2
session.

Comments:

This procedure is used primarily by ezXOS to get information on filtering queries for data from
HistoricalDB.
Related Information
GetActiveAORPermissions on page 62

3.56 Xoslogin
This business object’s function is to initialize an ezXOS login session.

Syntax:

Xoslogin

Comments:

This procedure is used primarily by ezXOS.

Related Information
Addarea on page 43
Droparea on page 55
Modarea on page 75

93
PI Business Objects

4 PI Business Objects

4.1 InterpTrend
This business object’s function is to retrieve collection and summary data from the PI Server. The
procedure returns interpolated values from the PI archive over the specified time range.

Syntax:

InterpTrend <table_name> <tag_name> <column_name> <start_time> <end_time>

<show_DQ>

Table 48 - Parameters
Name Description
table_name This parameter displays the length of the summary period used to
calculate the summary values. This can be any of the following: hour,
day, month, or year.
tag_name This parameter displays the name of the point to be viewed.
column_name This parameter displays the sample interval time used to calculate the
interpolated values. This must be the value column
start_time This parameter indicates the start time in GMT.
end_time This parameter indicates the end time in GMT
show_DQ This parameter indicates whether or not the return value will display data
quality. This is an optional field. The default value is yes.

4.2 Trend_points
This business object’s function is to retrieve a list of PI points that may be trended by ezXOS.

Syntax:

Trend_points

4.3 Trend
This business objects function is to retrieve collection or summary data from the PI Server.

Syntax:

Trend <table_name> <tag_name> <column_name> <start_time> <end_time>

<show_DQ>

94
 PI Business Objects

Table 49 - Parameters
Name Description
table_name This parameter displays the length of the summary period used to
calculate the summary values. This can be any of the following: hour,
day, month, or year. It can also be instant, which gives you the collect
values in the PI server. If instant is used, value must also be used in the
column_name field.
tag_name This parameter displays the name of the point to be viewed.
column_name This parameter displays the summary type of data to be viewed. It can be
any of the following: vlaue, minimum, maximum, or average.
start_time This parameter indicates the start time in GMT.
end_time This parameter indicates the end time in GMT
show_DQ This parameter indicates whether or not the return value will show data
quality. This is an optional field. The default value is yes.

Example:

Trend collect analog.CROSS0001.curval value 801355616 802373010

time milliseconds value status

801355616 0 80.000000 O
801355680 0 2.034600
801355740 0 40.000000 M
802373010 0 12.000000

Related Information
Collect_fields on page 52
Collect_tables on page 52

4.4 TrendView
Retrieves collection or summary data from the PI archive over a specified time range.

Syntax:

Trend <table_name> <tag_name> <column_name> <start_time> <end_time> <show

DQ>

Table 50 - Parameters
Name Description
table_name This parameter displays the length of the summary period used to calculate
the summary values. This can be any of the following: instant, hour, day,
month, or year
tag_name This parameter displays the name of the point to be viewed.

Table continued…

95
PI Business Objects

Table 50 - Parameters (continued)

Name Description
column_name This parameter displays the summary type of the data to be viewed. It can be
any one of the following: value, minimum, maximum, average.
start_time This parameter indicates the time at which the trend data begins. This is
entered in the MM/DD/YY HH:MM:SS format.
end_time This parameter indicates the time at which the trend data stops. This is
entered in the MM/DD/YY HH:MM:SS format.
show_DQ This parameter indicates whether or not the return value will show data
quality. This is an optional field. The default value is set to yes.

Example:

TrendView collect analog.a1.curval value

“03/21/1999 17:00:00” “03/21/1999 17:15:00”

96
 Common Business Objects

5 Common Business Objects

5.1 CFGConvUser
This business object’s function is to convert the distinguished name (Active Directory) of a user to the
user’s common name.

Syntax:

CFGConvUser <distinguished name>

Example:

CFGConvUser ”cn=CHRISS”

Row results:

Name AccountName

chriss chriss

(0 rows affected)

Resulting parameters:

cn=CHRISS

5.2 CFGGetArchivableServices
This business object’s function is to retrieve the list of services that can be archived within a system

Syntax:

CFGGetArchivableServices <system name>

Example:

CFGGetArchivableServices “main”

Row results:

Service Name

Historical

97
Common Business Objects

5.3 CFGGetArchiveHost
This business object’s function is to retrieve the list of the computers that run the archive service in a
specific system.

Syntax:

CFGGetArchiveHost <system name>

Example:

CFGGetArchiveHost “main”

Row Results:

Service Name

Historical

5.4 CFGGetCompList
This business object’s function is to retrieve the list of computers in the current OASyS DNA system or
domain.

Syntax:

CFGGetCompList [<system name>]

Example:

C:\> CFGGetCompList

Row results:

name

DISTRICTSVR1

DISTRICTSVR2
MASTERRTS2

MASTERXOS2

DISTCTXOS

OFFSITESVR

MASTERIIS

MASTERHS1

MASTERXOS6

MASTERRTS1

MASTERXOS9

98
 Common Business Objects

OFFSITEXOS

OASYSDES

MASTERXOS 1

NOTE: If a system name is given, then only computers in that system are returned. Otherwise, all
computers in the OASyS DNA domain are returned.

5.5 CFGGetGroupList
This business object’s function is to retrieve a list of all groups in the OASyS DNA domain.

Syntax:

CFGGetGroupList

Example:

C:\> CFGGetGroupList

Row results:

name

DNA XISSQL Admins

DNA Send AdminPages

DNA HDBData Admins

DNA HDBData Editors

DNA HDBDataViewers

DNA report@WEB

DNA HDBSQL Admins

DNA display@WEB

DNA operator@WEB

DNAreport@WEB operators

DNAreport@WEB admins

DNAreport@WEB viewers

DNAreport@WEB users

TestSecurity

Murray Test East Operators

DNA Admins

DNA Apps

DNA Permission - Change_Shift

DNA Permission - Config_Database

99
Common Business Objects

DNA Permission - Config_Displays

DNA Permission - Control_SCADA

DNA Permission - Exit_XOS

DNA Permission - Modify_XIS_Data

DNA Permission - Schedule_Ops

DNA Permission - Supervise_SCADA

DNA Permission - View

DNA Permission - XIS_Archive_Ops

DNA Authority - DBAdmin

DNA Authority - DBConfig

DNA Authority - SCADA Admin

DNA Authority - Operator

DNA Authority - Scheduler

DNA Authority - Supervisor

DNA Authority - Viewer

Administrators

Users

Guests

Backup Operators

Replicator

Server Operators

Account Operators

Print Operators

Pre-Windows 2000 Compatible Access

VS Developers

DHCP Users

DHCP Administrators

Debugger Users

Domain Computers

Domain Controllers

Schema Admins

Enterprise Admins

Cert Publishers

Domain Admins

Domain Users

100
 Common Business Objects

Domain Guests

Group Policy Creator Owners

RAS and IAS Servers

DnsAdmins

DnsUpdateProxy

WINS Users

(0 rows affected)

5.6 CFGGetSrvList
This business object’s function is to take the system and service, such as RealTime, as parameters and
return a list of computers that are the primary and secondary computers for that service.

Syntax:

CFGGetSrvList <system name> <service name>

Example:

C:\> CFGGetSrvList MASTER Realtime

Row results:

name

MASTERRTS1

MASTERRTS2

(0 rows affected)

Resulting parameters:

master

realtime

5.7 CFGGetSysList
This business object’s function is to retrieve the list of systems defined in the OASyS DNA project

Syntax:

CFGGetSysList

Example:

C:\> CFGGetSysList

101
Common Business Objects

Row results:

name

Offsite1 district2

esmaster

district

dss

(0 rows affected)

5.8 CFGGetUserList
This business object’s function is to retrieve the list of SCADA users in the domain.

Syntax:

CFGGetUserList

Example:

C:\> CFGGetUserList

Row results:

name

CN=dnaAdmin, OU=Users, OU=Falcon, OU=OASySDNA, DC=oasysdna, DC=local,

CN=dnaSybaseApp, OU=Users, OU=Falcon, OU=OASySDNA, DC=oasysdna, DC= local,
CN=PB_operator, OU=Users, OU=Falcon, OU-OASySDNA, DC=oasysdna, DC=local CN=GKop2,
OU=Users, OU=Falcon, OU=OASySDNA, DC=oasysdna, DC=local, CN=Tickle, Me.elmo, OU=Users,
OU=Falcon, OU=OASySDNA, DC=oasysdna, DC=local, CN=TestOpGroup, OU=Users, OU=Falcon,
OU=OASySDNA, DC=oasysdna, DC=local, CN=TestOp1, OU=Users, OU=Falcon, OU=OASySDNA,
DC=oasysdna, DC=local, CN=GKop1, OU=Users, OU=Falcon, OU=OASySDNA, DC=oasysdna,
DC=local, CN=GKview1, OU=Users, OU=Falcon, OU=OASySDNA, DC=oasysdna, DC=local,
CN=webviewproxy, OU=Users, OU=Falcon, OU=OASySDNA, DC=oasysdna, DC=local

(0 rows affected)

5.9 CFGGetUserRoleMembership
This business object’s function is to retrieve the set of roles assigned to the user.

Syntax:

CFGGetUserRoleMembership

102
 Common Business Objects

Example:

C:\> CFGGetUserRoleMembership

Row results:

Row

DNAPermission - Change Shift

DNAPermission - Config_Database

5.10 CFGGetXOSList
This business object’s function is to retrieve a list of ezXOSworkstations that are part of the specified
system

Syntax:

CFGGetXOSList <system name>

Example:

C:\> CFGGetXOSList <system name>

Row results:
name
MASTERXOS2 MASTERXOS6

MASTERXOS9 MASTERXOS1

(0 rows affected)

Resulting parameters:

master

5.11 GetServiceProcessList
This business object’s function is to retrieve a list of processes that are running as part of the service
you specify.

Syntax:

GetServiceProcessList <service name>

Example:

C:\> GetServiceProcessList common

Row results:

103
Common Business Objects

ProcessName ProcessId

dnaService.exe 1484

PSengine.exe 5412

processMonitor.exe 2532

dnaHealthMonitor.exe 2944

dllhost.exe 3672

dllhost.exe 5524

dllhost.exe 2764

SplSvc. exe 5276

WMIMonitor.exe 3932

dnaConfigRefresh.exe 3220

SQLEngine.exe 4704

(1 row affected)
Resulting parameters:

common

5.12 GetUserPermissions
This business object’s function is to retrieve the set of permissions granted to the user.

Syntax:

GetUserPermissions

Returned Information

The first result set returns:

the list of permissions granted for objects that do not use AOR access control.
the set of AOR Groups for which the user has at least one permission, the permissions are returned
as a string of semicolon separated by permission names as well as the corresponding permission bit
mask
an entry with a blank AORGroupName that list the permissions given to objects for which an AOR
Group has not yet been assigned.

The second result set consists of the list of permissions that have an assigned mask bit value and their
corresponding mask value. For example, “DNA Permission -Change_Shift” has a PermissionMask of
512, which represents 200 in hexidecimal. because the permission uses Mask Bit 9, where the far-right
bit position is bit 0.

Example:

GetUserPermissions

104
 Common Business Objects

Results:

Table 51 - Example Results - User Permissions

AORGroupName PermissionsNames PermissionMask
No AOR DNA Permission -Change_Shift; DNA Permission 262911
- Config_Database; DNA Permission -
Config_Displays; DNA Permission -
Config_OASyS_DNA; DNA Permission -
Control_SCADA; DNA Permission - Exit_XOS;
DNA Permission - Modify_XIS_Data;DNA
Permission - Schedule_Ops; DNA Permission -
Supervise_SCADA; DNA Permission - View;
DNA Permission - XIS_Archive_Ops
AOR Group - CalgaryNW DNA Permission - Exit_XOS; DNA Permission - 171
Config_Database; DNA Permission -
Schedule_Ops; DNA Permission -
Control_SCADA; DNA Permission - View
AOR Group - Calgary NE DNA Permission - Exit_XOS; DNA Permission - 171
Config_Database; DNA Permission -
Schedule_Ops; DNA Permission -
Control_SCADA; DNA Permission - View
AOR Group - EDM_con3 DNA Permission - Config_Database; DNA 35
Permission - Control_SCADA; DNA Permission -
View
AOR Group - EDM_CON1 DNA Permission - Config_Database; DNA 35
Permission - Control_SCADA; DNA Permission -
View
AOR Group - global DNA Permission - Config_Database; DNA 35
Permission - Control_SCADA; DNA Permission -
View

Table 52 - Example Results - Assigned Permission Bit Mask

Permission Names Permission Mask
DNA Permission - Change_Shift 512
DNA Permission - Config_Database 32
DNA Permission - Config_Displays 16
DNA Permission - Control_SCADA 2
DNA Permission - Exit_XOS 128
DNA Permission -Modify_XIS_Data 64
DNA Permission -Schedule_Ops 8
DNA Permission - Supervise_SCADA 4
DNA Permission - View 1
DNA Permission - XIS_Archive_Ops 262144

Related Information
GetActiveAORPermissions on page 62

105
Common Business Objects

5.13 ProcessCheckout
This business object’s function is to unregister the process from the specified service and optionally
terminate the process

Syntax:

ProcessCheckout <service name> <process id> <kill process>

Example:

This example unregisters process 4180 from the Common service and kills the process.

C:\> ProcessCheckout 4180 yes

Row results:

-----Empty Output Recordset -----

(1 rows affected)

Resulting parameters:

common

4180

5.14 RunProcess
This business object’s function is to run the shell command you specify.

Syntax:

RunProcess <command string>

Example:

This example creates a file called “out” under “c:\” that contains the word “hello”.

C:\> RunProcess “echo hello > c:\out”

Row results:

----- Empty Output Recordset -----

(1 row affected)

Resulting parameters:

echo hello > c:\out

NOTE: This component can only be used by a member of the DNA Apps group. The command is run in
the background, and as such, will not be permitted to show a user interface or interact with any
logged in user.

106
 Common Business Objects

5.15 ServiceShutdown
This business object’s function is to shut down the service you specify on the current computer.

Syntax:

ServiceShutdown <service name>

Example:

C:\> ServiceShutdown Realtime

Row results:
-----Empty Output Recordset ----

(0 rows affected)

Resulting parameters:

realtime

5.16 ServiceStartup
This business object’s function is to start the OASyS DNA service you specify on the local computer.

Syntax:

ServiceStartup <service name>

Example:

C:\> ServiceStartup realtime

Row results:

----- Empty Output Recordset -----

(0 rows affected)
Resulting parameters:
realtime

107
Common Business Objects

5.17 ToggleDebug
This business object’s function is incrementing the debug level of the process you specify.

Syntax:

ToggleDebug <process id>

Example:

This example increments the debug level of the process with ID 1000.

C:\> ToggleDebug 1000

Comments:

Increasing the debug level increases the output to the oasErrlog.log and other log files. When using this
component, you must ensure that log file sizes do not become too large.

If the debug level is already at maximum, then the debug level is reset to its lowest value.

This component only works with OASyS DNA processes.

This component can only be used by members of the DNA Apps group.

5.18 ValidateUser
This business object’s function is to retrieve a list of the systems the user is able to login to.

Syntax:

ValidateUser <username> <password>

Example:

ValidateUser “OASyS\user1” “my password”

108
 Arbitration Business Objects

6 Arbitration Business Objects

6.1 ServiceFailover
This business object’s function is to cause the specified arbitrated service to fail over.

Syntax:

ServiceFailover <service name>

Example:

C:\> ServiceFailover Realtime

NOTE: This component can only be used by members of the DNA Apps group. If the service is running
with hot and standby hosts and the command is run on the current hot host, the current hot
machine will stand down and the standby machine will become hot. Otherwise, no action is
taken.

109
Schneider Electric
49 Quarry Park Blvd SE
Calgary, AB T2J 6V8 - Canada
Phone: 1 (403) 253-8848
www.schneider-electric.com

As standards, specifications, and designs change from time to time,

please ask for confirmation of the information given in this publication.

© Schneider Electric. All Rights Reserved.