IAdministerSystem Interface

The Unisys.AgileBusiness.RuntimeAPI namespace contains the IAdministerSystem interface that allows you to perform the runtime application administration operations and report administration operations. The RuntimeFactory class includes methods to return the IRuntimeSystem object.

Refer to Definition of the IAdministerSystem Interface for more information about the interface.

Namespace: Unisys.AgileBusiness.RuntimeAPI

Assembly: Unisys.AgileBusiness.RuntimeAPI (in Unisys.AgileBusiness.RuntimeAPI.dll)

Syntax

You can create the IAdministerSystem object by using the RuntimeFactory.GetSystem() method.

IAdministerSystem RuntimeSystem = Unisys.AgileBusiness.RuntimeAPI.RuntimeFactory.
GetSystem(string systemName);

The IAdministerSystem interface exposes the following methods. By default, all the methods can be accessed by a local administrator. Non-administrative users can use these methods only if they have the required security privileges. The security of the methods is controlled by using the COM+ roles. Refer to the following table for the specific security privileges.

Methods

Method

Description

Security Privileges

CheckUserMaintainedTables()

Specifies if a database table is reorganized by the user or system during deployment.

To access this administrative function:

  • Users should be a member of the Runtime Administrators role of Runtime Manager COM+ component.

  • Users should be member of Application Deployer role of Database Reorganization COM+ component.

  • Users should be member of Application Administrators role of the deployed COM+ application.

ClearSession()

Clears an existing orphan session based on a given station name or session id.

Users should be a member of the Application Administrators.

ConfigurePrintProperty()

Configures print properties to format the printed output of a Report/Outstream

Users should be a member of the Editors role of the Print Configuration Manager to access this function.

ConfigureSystemAuditLog()

Configures the system Audit log

Users should be a member of the following Runtime Manager COM+ role to access this administrative function:

  • Runtime Administrators

DeleteReportRecovery()

Deletes recovery information of a report.

Users must be a member of one of the following COM+ roles in order to access the method:

  • Report Runners (can delete the information of reports they have initiated)

  • Report Recovery Operators

  • Report Recovery Administrators

  • Report Administrators

  • Application Administrators

DisableHub()

Disables HUB for an application.

Users must be a member of one of the following COM+ roles in order to access the method:

  • HUB Administrators

  • Application Administrators

DisableSystem()

Disables an application.

Users must be a member of one of the following COM+ roles in order to access the method:

  • Application Operators

  • Application Administrators

EnableHub()

Enables HUB for an application.

Users must be a member of one of the following COM+ roles in order to access the method:

  • HUB Administrators

  • Application Administrators

EnableSystem()

Enables an application

Users must be a member of one of the following COM+ roles in order to access the method:

  • Application Operators

  • Application Administrators

GetAccountMonth()

Displays both the High and Low Account Months of an application

Users must be a member of one of the following COM+ roles in order to access the method:

  • Accountants

  • Application Administrators

GetHubStatus()

Returns the hub status

Users must be a member of one of the following COM+ roles in order to access the method:

  • HUB Monitors

  • HUB Administrators

  • Application Administrators

GetSystemStatus()

Displays the status of a system

Users must be a member of one of the following COM+ roles in order to access the method:

  • Application Operators

  • Application Administrators

ListIspecs()

Lists unique ispecs in an application

Users must be a member of one of the following COM+ roles in order to access the method:

  • Application Operators

  • Application Administrators

ListRunningReports()

Displays information about the active reports and reports awaiting recovery in an application.

Users must be a member of one of the following COM+ roles in order to access the method:

  • Report Runners (only able to obtain information on reports they have initiated)

  • Report Monitors

  • Report Recoverers

  • Report Recovery Operators

  • Report Recovery Administrators

  • Report Administrators

  • Application Administrators

ListUsers()

Displays a list of stations connected to a runtime system.

Users must be a member of one of the following COM+ roles in order to access the method:

  • Application Administrators

RunReport()

Initiate a report or recover a report with recovery information available.

Users must be a member of one of the following COM+ roles in order to access the method:

  • Report Runners

  • Report Administrators

  • Application Administrators

SendAMessage()

Sends a short message to other users logged onto an application.

Users must be a member of one of the following COM+ roles in order to access this method:

  • Message Senders

  • Message Broadcasters

SetAccountMonth()

Sets both the High and Low Account Months of an application.

Users must be a member of one of the following COM+ roles in order to access the method:

  • Accountants

  • Application Administrators

SetMultiLanguagePath()

Specifies the path to language.dll

Users should be member of the following Runtime Manager COM+ role to access this administrative function:

  • Runtime Administrators

StopReport()

Terminates or stops a running report.

Users must be a member of one of the following COM+ roles in order to access the method:

  • Report Runners (only able to stop reports they have initiated)

  • Report Operators

  • Report Administrators

  • Application Administrators

StopSystem()

Stops a runtime system.

Users must be a member of one of the following COM+ roles in order to access the method:

  • Application Operators

  • Application Administrators

TerminateReport()

Terminates an active report immediately.

Users must be a member of one of the following COM+ roles in order to access the method:

  • Report Runners (only able to stop reports they have initiated)

  • Report Operators

  • Report Administrators

  • Application Administrators

WakeUpReport()

Wakes up a report

Users must be a member of one of the following COM+ roles in order to access the method:

  • Application Administrators

  • Report Administrators

  • Report Operators

  • Report Recovery Administrators

  • Report Recovery Operators

  • Report Runners

IAdministerSystem.CheckUserMaintainedTables Method

This method allows you to verify whether a database table is reorganized by the user or by the system during deployment. This method is valid for persistent AB Suite entities such as, Ispecs (tables), Profiles (indexes), Events and Classes with no stereotype.

Syntax

CheckUserMaintainedTables()

Arguments

None

Return Value

If this method succeeds, it returns the StatusInfo object with success else, it returns an error status.

IAdministerSystem.ClearSession Method

This method allows you to clear an existing orphan session from the Runtime application based on a given station name or session id.

Syntax

ClearSession(string userOrSession)

Arguments

userOrSession: string

User name or Session Id of a known session, which needs to be cleared.

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.ConfigurePrintProperty Method

This method allows you to define the print properties, which are helpful in formatting the printed output for a Report/OutputStream.

Syntax

ConfigurePrintProperty(parameter As Unisys.AgileBusiness.RuntimeAPI.PrintParameter, 
mode As Unisys.AgileBusiness.RuntimeAPI.ModeType)

Arguments

Return Value

If this method succeeds, it returns the StatusInfo object with the status code: Error, Warning, or Success and status message, if any. Refer to Runtime Operations Utility for more information on validation messages specific to configuring print properties.

IAdministerSystem.ConfigureSystemAuditLog Method

This method allows you to define how activities and transactions are logged to the Audit log.

Syntax

ConfigureSystemAuditLog(parameter As 
Unisys.AgileBusiness.RuntimeAPI.AuditLogParameter mode As 
Unisys.AgileBusiness.RuntimeAPI.ModeType)

Arguments

Return Value

If this method succeeds, it returns the StatusInfo object with the status code: Error, Warning, or Success and status message, if any. Refer to Runtime Operations Utility for more information on validation messages specific to configuring audit logs.

IAdministerSystem.GetAccountMonth Method

This method allows you to display both the High and Low Account months.

Syntax

GetAccountMonth(out int highAccount, out int lowAccount)

Arguments

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status

IAdministerSystem.GetSystemStatus Method

This method allows you to display the status of a system whether Enabled, Disabled, Running, or Stopped.

Syntax

GetSystemStatus(out Unisys.AgileBusiness.RuntimeAPI.SystemStatus systemStatus)

Arguments

systemStatus: SystemStatus object

The object describes if the runtime system status is Stopped, Enabled, Disabled, or Running

The SystemStatus class exposes the following members.

Members of SystemStatus class

Name

Description

Enabled

Enable an application

Disabled

Disable an application

Stopped

Stop an application

Running

Execute an application

Unknown

No known status that are stated earlier

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.EnableSystem Method

This method allows you to enable an application.

Syntax

EnableSystem()

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.DisableSystem Method

This method allows you to disable an application.

Syntax

DisableSystem()

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.StopSystem Method

This method allows you to stop an application and optionally cause termination of an application when it is idle.

Syntax

StopSystem([bool disable = false])

Arguments

disable: By default, the value is false. This argument is optional.

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.GetHubStatus Method

This method allows you to get the status of an external automatic entry (HUB) transaction of an application.

Syntax

GetHubStatus(out bool isEnabled)

Arguments

isEnabled: bool

isEnabled is set to true, to enable HUB

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.EnableHub Method

This method allows you to enable HUB for an application.

Syntax

EnableHub()

Return Value

If this method succeeds, it returns the StatusInfo object with success else, it returns an error status.

IAdministerSystem.DisableHub Method

This method allows you to disable HUB for an application.

Syntax

DisableHub()

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.ListIspecs Method

This method lists the unique ispecs in an application.

Syntax

ListIspecs(out System.Collections.Generic.IList<string> ispecsList)

Arguments

ispecsList: System.Collections.Generic.IList<string>

This argument provides the list of ispecs in a system.

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.ListUsers Method

This method displays a list of stations connected to a runtime system. The information includes a list of users logged into the system.

Syntax

ListUsers(out System.Collections.Generic.IList<string> usersList)

Arguments

usersList: System.Collections.Generic.IList<string>

This argument provides a list of connected users.

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.SendAMessage Method

This method sends a short message to other users logged onto an application.

Syntax

SendAMessage(string station, string message)

Arguments

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.SetAccountMonth Method

This method sets a High Account Month (HAM) or Low Account Month (LAM) value for a running application.

Syntax

SetAccountMonth([int highAccount = 0], [int lowAccount = 0])

Arguments

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.SetMultiLanguagePath Method

This method allows you to specify the path to the language.dll to be used by the running application.

Syntax

SetMultiLanguagePath(languagePath As String)

Argument

languagePath: String

This argument is the absolute path to language.dll.

Return Value

If this method succeeds, it returns the StatusInfo object with success else, it returns an error status.

Using the IAdministerSystem Interface for the Application Administration Operations

To use the interface for the application administration operations through the C# example, perform the following:

  1. Create a new C# Class Library in Microsoft Visual Studio.

  2. Add a reference to the following assembly that you need when calling from the Class Library:

    • Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 7.0 Installation directory>\bin64 folder)

    • Log4net.dll (add this assembly to record the log details from <AB Suite 7.0 Installation directory>\bin64 folder)

  3. Add the following code.

    namespace SampleSystem
    {
    	using System;
    	using Unisys.AgileBusiness.RuntimeAPI;
    
    	class Program
    	{
        static string configFilelocation = null;
    
    		static void Main(string[] args)
    		{
    			//Get the RuntimeSystem
     			IAdministerSystem sample = RuntimeFactory.GetSystem("SAMPLE");
    
           configFilelocation = Unisys.AgileBusiness.RuntimeAPI.Util.GetPublicFolderPath() + 
           System.IO.Path.DirectorySeparatorChar + "RuntimeAPI.XML";
           log4net.Config.XmlConfigurator.ConfigureAndWatch(new System.IO.FileInfo(configFilelocation));
    
    			//Get the System status
    			SystemStatus systemStatus;
    			StatusInfo status = sample.GetSystemStatus(out systemStatus);
    
    			if (status.Status == StatusEnum.Success)
    			{
    				Console.Write(string.Format("Status : "));
    				switch (systemStatus)
    				{
    					case SystemStatus.Enabled | SystemStatus.Stopped: Console.WriteLine
    					(SystemStatus.Enabled + " and " + SystemStatus.Stopped);
    					break;
    					case SystemStatus.Enabled | SystemStatus.Running: Console.WriteLine
    					(SystemStatus.Enabled + " and " + SystemStatus.Running);
    					break;
    					case SystemStatus.Disabled | SystemStatus.Running: Console.WriteLine
    					(SystemStatus.Disabled + " and " + SystemStatus.Running);
    					break;
    					case SystemStatus.Disabled | SystemStatus.Stopped: Console.WriteLine
    					(SystemStatus.Disabled + " and " + SystemStatus.Stopped);
    					break;
    					case SystemStatus.Disabled | SystemStatus.Stopped: Console.WriteLine
    					(SystemStatus.Disabled + " and " + SystemStatus.Stopped);
    					break;
    					default: Console.WriteLine("Unknown");
    					break;
    				}
    			}
    			else
    			{
    				Console.WriteLine(status.Status + status.StatusMessage);
    			}
    
    			//Enable system
    			status = sample.EnableSystem();
    
    			//Disable system
    			status = sample.DisableSystem();
    
    			//Stop system
    			status = sample.StopSystem();
    
    	 		//Get the status of the System HUB
    			bool isHubEnabled;
    
    			status = sample.GetHubStatus(out isHubEnabled);
    
     			//Disable Hub of the system
    			status = sample.DisableHub();
    
     			//Enable Hub of the System
    			status = sample.EnableHub();
    
    			//Configure system log
    			//Construct the AuditLogParameter
    			AuditLogParameter parameter = new AuditLogParameter()
    			{
    				FileSize = 5000,
    				NoOfBackups = 7,
    				FilePath = @"C:\Temp\RuntimeAPI",
    				Level = AuditLogLevel.ActivitiesAndTransactionsInNOF
    			};
    			//Invoke ConfigureSystemAuditLog to update with the new values
    			StatusInfo status = runtimeSystem.ConfigureSystemAuditLog(parameter, ModeType.Write);
    
    			Console.WriteLine(statusInfo.StatusMessage);
    
    			//Invoke ConfigureSystemAuditLog to read the values
    			statusInfo = runtimeSystem.ConfigureSystemAuditLog (parameter, ModeType.Read);
    
    			if (statusInfo.Status == StatusEnum.Success)
    			{
    				//Prints the read values
    				Console.WriteLine("Enable : " + parameter.LogStatus);
    				Console.WriteLine("Log Level : " + parameter.Level);
    				Console.WriteLine("File Path : " + parameter.FilePath);
    				Console.WriteLine("Reset File Size : " + parameter.FileSize);
    				Console.WriteLine("No of backups : " + parameter.NoOfBackups);
    			}
    			else
    			{
    				Console.WriteLine(statusInfo.Status + statusInfo.StatusMessage);
    			}
    
    			//List users
    			IList<string> usersList = null;
    			status = sample.ListUsers(out usersList);
    
     			if (status.Status == StatusEnum.Success)
    			{
    				if (usersList.Count > 0)
    				{
    					foreach (string user in usersList)
    					Console.WriteLine(user);
    				}
    				else
    				{
    					Console.WriteLine("No users are logged in");
    				}
    			}
    			//Set language.dll path
    			string languagePath = @"C:\Temp";
    			statusInfo = runtimeSystem.SetMultiLangaugePath(languagePath);
    			Console.WriteLine(statusInfo.Status + statusInfo.StatusMessage);
    
    			//Check consistency of user-maintained tables
    			statusInfo = runtimeSystem.CheckUserMaintainedTables();
    			Console.WriteLine(statusInfo.Status + statusInfo.StatusMessage);
    			//Configure print properties
    			//Construct the PrintParameter
    			PrintParameter parameter = new PrintParameter ()
    			{
    				PageDepth = 50,
    				PageWidth = 120,
    				MarginHorizontal = 10,
    				MarginVertical = 10,
    				PageOrientation = PageOrientation.Landscape,
    				FontName = @"Times New Roman"
    			};
    
    			//Invoke ConfigurePrintProperty to update with the new values
    
    			statusInfo = runtimeSystem.ConfigurePrintProperty(parameter,
    			ModeType.Write);
    
    			Console.WriteLine(statusInfo.StatusMessage);
    
     			//Invoke ConfigurePrintProperty to read the values
    			statusInfo = runtimeSystem.ConfigurePrintProperty (parameter, ModeType.Read);
    
    			if (statusInfo.Status == StatusEnum.Success)
    			{
    				//Prints the read values
    				Console.WriteLine("Page Depth : " + parameter. PageDepth);
    				Console.WriteLine("Page Width : " + parameter. PageWidth);
    				Console.WriteLine("Margins Horizontal : " + 
    				parameter. MarginHorizontal);
    				Console.WriteLine("Margins Vertical : " + 
    				parameter. MarginVertical);
    				Console.WriteLine("Font Name : " + parameter. FontName);
    			}
    			else
    			{
    				Console.WriteLine(statusInfo.Status + statusInfo.StatusMessage);
    			}
    		}
    	}
    }
  4. Build the Class Library.

IAdministerSystem.ListRunningReports Method

This method displays information about the active reports or reports awaiting recovery in an application.

Syntax

ListRunningReports(out System.Collections.Generic.IList<ReportInformation> 
reportsList)

Arguments

reportsList: System.Collections.Generic.IList<ReportInformation>

This argument provides a list of reports of the type ReportInformation.

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.RunReport Method

This method allows you to initiate or recover a report with the available recovery information.

Syntax

RunReport(string reportName, Unisys.AgileBusiness.RuntimeAPI.RuntimeCallBack
callBack, [string recoveryKey = ""], [bool waitForReportCompletion = true], 
[string parameter = ""], [string device = "LP"], 
[string language = ""], [bool trace = false])

Arguments

Note: Refer to IDeployPackage Interface for more information about the SecurityHelper class to set the security.

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.DeleteReportRecovery Method

This method allows you to delete recovery information for a report.

Syntax

DeleteReportRecovery(int sessionID)

Arguments

sessionID: int

The Session ID or recovery key of a report

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.StopReport Method

This method allows you to terminate running reports.

Syntax

StopReport(string reportName, Unisys.AgileBusiness.RuntimeAPI.StopReportFlags
stopReportFlags, [string processId = null])

Arguments

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.TerminateReport Method

This method allows you to terminate an active report immediately.

Syntax

TerminateReport(string reportName, Unisys.AgileBusiness.RuntimeAPI.StopType 
stopType, [string processId = null])

Arguments

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

IAdministerSystem.WakeUpReport Method

This method allows you to wake up a report.

Syntax

WakeUpReport(string reportName, [string wakeUpParameters = ""])

Arguments

Return Value

If this method succeeds, it returns the StatusInfo object with success; else, it returns an error status.

Using the IAdministerSystem Interface for the Report Administration Operations

To use the interface for the report administration commands through the C# example, perform the following:

  1. Create a new C# Class Library in Microsoft Visual Studio.

  2. Add a reference to the following assembly that you need when calling from the Class Library:

    • Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 7.0 Installation directory>\bin64 folder)

  3. Add the following code

    namespace SampleReport
    {
    	using System;
    	using Unisys.AgileBusiness.RuntimeAPI;
    
    	class Program
    	{
    		static void Main(string[] args)
    		{
    
    			//Report operations
    
    			//Get the RuntimeSystem, GetSystem sets the security
    			IAdministerSystem sample = RuntimeFactory.GetSystem("SAMPLE");
    
    			//Get the callback object for report callback
    			CallBackHandler callBack = new CallBackHandler();
    
    			//Execute report
    			sample.RunReport("CUSTLIST", callBack);
    
     			//List Running Reports
    			IList<ReportInformation> reportsList = null;
    			status = sample.ListRunningReports(out reportsList);
    
    			if (status.Status == StatusEnum.Success)
    			{
    				if (reportsList.Count > 0)
    				{
    					Console.WriteLine("USER NAME               
    					PID   SID   REPORT           STATUS");
    					foreach (ReportInformation report in reportsList)
    					{
    						Console.WriteLine(string.Format("{0,-26}{1,-6}{2,-6}{3,-17}{4,-20}", 
    						report.UserName, report.ProcessId, report.SessionId, 
    						report.ReportName, report.Status));
    					}
    				}
    				else
    				{
    					Console.WriteLine("No active/waiting recovery reports are available");
    				}
    			}
    		}
    	}
    }
  4. Build the Class Library.

Definition of the IAdministerSystem Interface

Following is the definition of the IAdministerSystem interface.

namespace Unisys.AgileBusiness.RuntimeAPI
{
	public interface IRuntimeSystem
	{
		StatusInfo CheckUserMaintainedTables();
		StatusInfo ClearSession(string userOrSession);
		StatusInfo GetAccountMonth(out int highAccount, 
		out int lowAccount);
		StatusInfo GetSystemStatus(out Unisys.AgileBusiness.RuntimeAPI.
		SystemStatus  systemStatus);
		StatusInfo ListIspecs(out System.Collections.Generic.IList<string> ispecsList);
		StatusInfo ListRunningReports(out System.Collections.Generic.IList
		<ReportInformation> reportsList);
		StatusInfo ListUsers(out System.Collections.Generic.IList<string> usersList);
		StatusInfo ConfigurePrintProperty(parameter As 
		Unisys.AgileBusiness.RuntimeAPI.PrintParameter, mode As 
		Unisys.AgileBusiness.RuntimeAPI.ModeType);
		StatusInfo ConfigureSystemAuditLog(parameter As 
		Unisys.AgileBusiness.RuntimeAPI.AuditLogParameter mode As 
		Unisys.AgileBusiness.RuntimeAPI.ModeType);
		StatusInfo EnableSystem();
		StatusInfo DisableSystem();
		StatusInfo StopSystem([bool] disable = false);
		StatusInfo GetHubStatus(out bool isEnabled);
		StatusInfo EnableHub();
		StatusInfo DisableHub();
		StatusInfo SendAMessage(string station, string message);
		StatusInfo SetAccountMonth([int highAccount = 0], 
		[int lowAccount = 0]);
		StatusInfo SetMultiLanguagePath(string languagePath);
		StatusInfo RunReport(string reportName, Unisys.AgileBusiness.RuntimeAPI.
		RuntimeCallBack callBack, [string recoveryKey = ""], 
    [bool waitForReportCompletion = true], 
	   [string parameter = ""], [string device = "LP"], [string language = ""], 
    [bool trace = false]);
		StatusInfo DeleteReportRecovery(int sessionID);
		StatusInfo StopReport(string reportName, Unisys.AgileBusiness.RuntimeAPI.
		StopReportFlags stopReportFlags, [string processId = null]);
		StatusInfo TerminateReport(string reportName, Unisys.AgileBusiness.RuntimeAPI.
		StopType stopType, [string processId = null]);
		StatusInfo WakeUpReport(string reportName, [string wakeUpParameters = ""]);