agile business suite runtime for windows operating system ... · no warranties of any nature are...

Unisys

Agile Business Suite

Runtime for Windows Operating System Administration Guide

Copyright © 2013 Unisys Corporation.All Rights Reserved.

Release 4.0

December 2013 3826 5856-005

NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the products described in this document are set forth in such agreement. Unisys cannot accept any financial or other responsibility that may be the result of your use of the information in this document or software material, including direct, special, or consequential damages.

You should be very careful to ensure that the use of this information and/or software material complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used.

The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions.

Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data rights clauses.

Correspondence regarding this publication should be forwarded to Unisys Corporation by addressing remarks to Product Information, Unisys Global Services - India, Purva Premier, 135/1, Residency Road, Bangalore-560025, India. Comments about documentation can also be sent through e-mail to [email protected].

Unisys and MCP are registered trademarks of Unisys Corporation in the United States and other countries.Microsoft, Windows, Windows NT, Internet Explorer, Visual Studio, Visual C++, Visual SourceSafe, Visual Studio Team Foundation, SQL Server, ActiveX are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.All other brands and products referenced in this document are acknowledged to be the trademarks or registered trademark of their respective holders.

Contents

Section 1. Agile Business Suite Runtime Overview ..............................1–1

About This Guide ........................................................................................................1–2Audience .......................................................................................................................1–2Documentation Update .............................................................................................1–2

Section 2. Runtime Administration.........................................................2–1

Using the Administration Tool .................................................................................2–1Using the Scope Pane ........................................................................ 2–2

Defining Network Users ..........................................................................................2–4The Station Info (LINCIINET) File .......................................................2–4Creating a Station Info (LINCIINET) File ...........................................2–5

Setting Up Your Runtime Environment ................................................................2–6Adding a Runtime Server ..................................................................2–6Removing a Server from Favorites ..................................................2–6Adding a Database Server Registration .........................................2–6Removing a Database Server Registration ................................... 2–7Configuring User Rights to Add or Remove a Database ............2–8Adding a Database ..............................................................................2–8Removing a Database ...................................................................... 2–10Using Scale-Out ...................................................................................2–11

Configuring Protocol Adapters ............................................................................ 2–12Configure Adapters Dialog Box ...................................................... 2–13Creating Views .................................................................................. 2–13

Configuring Log Files .............................................................................................. 2–16Managing Your Application ................................................................................... 2–16

Security ................................................................................................ 2–17Working with Systems ..................................................................... 2–17Setting Up AB Suite for Database Mirroring ...............................2–33Reports .................................................................................................2–35Monitoring Performance .................................................................2–37

Section 3. Using Administration Commands ........................................ 3–1

Application Related Commands ............................................................................ 3–1Setting or Displaying High Account Month ....................................3–2Setting or Displaying Low Account Month ....................................3–3Setting or Displaying the Language .................................................3–4Sending a Message .............................................................................3–4Listing Ispecs ........................................................................................3–5Stopping an Application ......................................................................3–6Display External Automatic Entry Status ........................................3–6Enabling External Automatic Entries ...............................................3–7

3826 5856-005 iii

Contents

Disabling External Automatic Entries .............................................3–8Displaying a list of active stations ...................................................3–8

Report Administration Commands ........................................................................3–9Listing Running and Recoverable Reports .....................................3–9Running and Recovering Reports .................................................. 3–10Deleting Recovery Information ..................................................... 3–12Stopping a Report .............................................................................. 3–12Terminating an Active Report ......................................................... 3–13Wake Up Report ................................................................................ 3–15

Admin.exe Command Line Utility ........................................................................ 3–16

Section 4. Deployment Package Manager .............................................4–1

Prerequisites for DPM .............................................................................................. 4–1Create Cloned MSIs of Existing MSIs ...................................................................4–2Update the Package Parameters of Cloned MSI ................................................4–3Create Partial MSIs for Cloned MSIs .....................................................................4–3Deploying MSIs or CAB Files Using Runtime Transfer .....................................4–4Executing DPM from Command Prompt .............................................................4–5Creating a Cloned MSI by Changing Configuration Settings in Builder .........4–7

Section 5. Command Line and Programmatic Access to Runtime ......5–1

Command Line Utilities .............................................................................................5–1Configure Log Files Utility (ConfigureLog.exe) .............................. 5–2Configure Protocol Adapters Utility (ConfigureAdapter.exe) ....5–5AB Suite System Deployment Utility (DeployPackage.exe) .... 5–10Deployment Package Manager Utility (ManagePackage.exe) . 5–14Runtime Operations Utility (AdminSystem.exe) .........................5–22Application Administration Commands ........................................5–23Report Administration Commands ................................................5–33Reconfigure External Persistent Class Utility

(EPCReconfigure.exe) .................................................................. 5–41Programmatic Access to Runtime .......................................................................5–43

IConfigureRuntime Interface .......................................................... 5–44IDeployPackage Interface ................................................................5–50IAdministerSystem Interface ..........................................................5–62

Troubleshooting Runtime API Operations .........................................................5–77

Section 6. Runtime Programming Interfaces.........................................6–1

Segment COM+ Interface ....................................................................................... 6–1Connect() ............................................................................................... 6–1Disconnect() ......................................................................................... 6–2CreateInstance() ................................................................................... 6–2ProcessMsg() ........................................................................................6–3Admin() ...................................................................................................6–3Handling Unsolicited Messages .......................................................6–3IMessages Object ................................................................................6–3ICallBack Object ...................................................................................6–4Connect() ................................................................................................6–5

iv 3826 5856-005

Contents

General Processing ..............................................................................6–5Using Messages COM Object to handle Unsolicited Messages .....

6–6Definition of ISegmentCycle Interface ............................................6–9

GenericClass COM+ Interface ................................................................................6–9GenericClass Field Names .............................................................. 6–10SetValue() ............................................................................................. 6–10GetValue() ............................................................................................6–11SetArrayValue() ....................................................................................6–11GetArrayValue() ...................................................................................6–11GetNumMessages() ..........................................................................6–11GetMessage() .....................................................................................6–11GetMaxCopies() ...................................................................................6–11GetNumDynamicLists() ......................................................................6–11GetDynamicList() ................................................................................ 6–12Initialize() ............................................................................................... 6–13CreateCopy() ....................................................................................... 6–13GetSwitchToData() ............................................................................. 6–13GetSwitchToData2() ........................................................................... 6–13Definition of IIspecCycle Interface ................................................. 6–15

Processing Ispecs via the Segment COM Interface ........................................ 6–16Processing Ispec Messages ........................................................... 6–16Unmanaged C++ Example ............................................................... 6–17Managed .NET C# Example ............................................................. 6–18

Calling Segment Methods .....................................................................................6–20Unmanaged C++ Example ............................................................... 6–21Managed .NET C# Example ............................................................. 6–21Using the Start command with non-administrative callers ......6–22

Method Interface for a Segment Method ........................................................6–23

Section 7. Using Protocol Adapters .......................................................7–1

SOAP over HTTP and SOAP over MSMQ .............................................................7–1RATL over TCP/IP and RATL over MSMQ ........................................................... 7–2HUB (External Automatic Entries) .......................................................................... 7–2

Preparing Projects in Developer .......................................................7–3Communicating with Other Hosts ..................................................7–4Sending External Automatic Entries ...............................................7–5How an External Automatic Entry Works ......................................7–5Security Issues with External Automatic Entries ........................ 7–7

USER (User Interface) ...............................................................................................7–8Sending a Transaction ........................................................................7–9Sample User Program .........................................................................7–9

NOF/OFF/GLI ............................................................................................................. 7–10Non-Formatted Input/Output (NOF) ............................................... 7–10GLI (Generalized Interfaces) ............................................................. 7–19Offline Input .......................................................................................7–28

Views .........................................................................................................................7–30Security ......................................................................................................................7–30

Section 8. Database Structure ............................................................... 8–1

3826 5856-005 v

Contents

Database Tables ......................................................................................................... 8–1_Id Column ............................................................................................ 8–1Ordinates ...............................................................................................8–2Naming Conventions ..........................................................................8–2Adding a new Column .........................................................................8–2

Profiles ........................................................................................................................8–3Events .........................................................................................................................8–3User Maintained Tables ............................................................................................8–3

.......................................................................................................................................8–4

Section 9. Report Operations..................................................................9–1

Creating Reports ........................................................................................................ 9–1Standard Reports ................................................................................. 9–2Direct Reports ......................................................................................9–3Enterprise Output Manager Reports .............................................9–3Built-in Attributes and Reports ........................................................9–4Using the CriticalPoint Logic Command ........................................9–4

Running Reports .......................................................................................................9–5Report Session Manager ..................................................................9–5Running Asynchronous Reports from Ispec Logic ......................9–6Running Asynchronous Reports from Presentation Client .......9–6Running Asynchronous Reports from a Command Prompt

Window ............................................................................................9–6Running Asynchronous Reports from a Client Interface or COM+

9–8Passing Parameters to a Report ...........................................................................9–8

Recovering Parameter Data for Reports ........................................9–8Using Returned Values from a Report ................................................................9–8Where Report Output is Located ..........................................................................9–9

Standard Report Output .................................................................. 9–10Location of Standard Report Output ............................................. 9–10Security of Standard Report Output ..............................................9–11Direct Report Output ........................................................................ 9–12Enterprise Output Manager Report Output ................................ 9–13

Recovering Reports ............................................................................................... 9–13Recovering Reports Initiated with the Run Logic Command .9–14Recovering Reports Initiated from a Command Prompt Window .

9–14Recovering Reports Initiated with the :RUN Command ........... 9–15Extended Report Recovery ............................................................ 9–15

Report Output Control (ROC) ................................................................................ 9–15Initiating ROC ...................................................................................... 9–17Defining a ROC Alias ......................................................................... 9–17Managing Expired Reports ............................................................. 9–18Accessing ROC from Ispec Logic ................................................. 9–18Accessing ROC from standalone Presentation Client .............. 9–19Accessing ROC from Presentation Client as a Browser Applet ......

9–20Accessing ROC from ASP.NET Web Forms ................................ 9–21Accessing ROC from VB.NET Winforms .....................................9–25

Printing Reports ......................................................................................................9–27

vi 3826 5856-005

Contents

Defining Printers ...............................................................................9–28Assigning Report Destinations ...................................................... 9–30Printing Special Attributes ............................................................... 9–31Formatting CODES File Records .....................................................9–33Example of Defining an Output Control Code ............................ 9–34

Overriding the Default FormDepth or PageDepth .......................................... 9–36Deleting Reports ..................................................................................................... 9–36

Section 10. Using SQL Views ..................................................................10–1

About SQL Views ....................................................................................................10–1Generating and Maintaining SQL Views ..............................................................10–1What SQL Views are Created .............................................................................. 10–2

Keyed Classes ................................................................................... 10–2Non-Keyed Classes .......................................................................... 10–3Events .................................................................................................. 10–3Profiles ................................................................................................ 10–3Attribute .............................................................................................. 10–3

Using SQL Views .................................................................................................... 10–3Limits and Performance Issues with SQL Views ...................... 10–5

Section 11. Migrating Data...................................................................... 11–1

EAE Data Migration Wizard ................................................................................... 11–1Source Database Settings ...............................................................11–2Target Database settings ..................................................................11–3Options settings ..................................................................................11–3Advanced Migration Techniques .....................................................11–4

Addressing Migration Issues .................................................................................11–5LANGUAGE Migration Tool ....................................................................................11–6

Appendix A. Related Product Information................................................A–1

Index ....................................................................................................... Index–1

3826 5856-005 vii

Contents

viii 3826 5856-005

Section 1 Agile Business Suite Runtime Overview

Agile Business Suite enables flexible and rapid development of runtime solutions by supporting deployment of both its own components and those developed with other tools together with the capability of multiple platform deployment.

Agile Business Suite Web Services support makes it possible to integrate applications among your suppliers, distributors, and partners. With Web Services, transactions are defined as self-describing services that can interact with other foreign applications to speed up everyday business-to-business processes. If you decide to adopt a Services Oriented Development of Applications (SODA), Agile Business Suite is the perfect tool.

Databases are optimized for each specific operating environment including SQL Server for the Windows operating systems.

The first release of Agile Business Suite runtime is targeted at the Windows COM+ environment. This brings a number of advantages including lightweight protocol adapters replacing previous runtime gateways. Because object pooling is available, protocol adapters can talk directly to the COM+ application. Although this is a significant advantage, the flexibility of COM+ applications is such that users can choose to bypass protocol adapters altogether by making COM calls directly from any COM aware language including a scripting language such as VBScript.

Because of the need to support a number of different protocols and transport layers, there are a number of different protocol adapters. Following is a list of the protocol adapters for this initial release of Agile Business Suite:

• SOAP over HTTP (Web Services)

Simple Object Access Protocol (SOAP) is a protocol that has a predominant role in XML development and Web Services. It plays a major role in Microsoft's next generation of Visual Studio, and is a basis of their .NET strategy.

• SOAP over MSMQ

This protocol adapter provides SOAP over Microsoft Message Queuing (MSMQ).

• HUB

HUB is a proprietary protocol that allows Agile Business Suite systems to communicate with each other and EAE systems.

• NOF/OFF/USER/GLI

These are proprietary protocols used in Agile Business Suite applications.

• RATL over TCP/IP

A protocol that is used by Component Enabler.

3826 5856-005 1–1

Agile Business Suite Runtime Overview

• RATL over MSMQ

A feature of Component Enabler.

For Agile Business Suite users a protocol adapter is a Windows service, which appears in the Services, accessed from the Control Panel. Because of their nature, protocol adapters can be started and stopped independently of the rest of the system, and exist outside of the application.

About This GuideThe AB Suite Windows Runtime Admin Guide describes the process of configuring the Runtime environement, deploying systems, and performing administrative tasks required for the deployed systems.

AudienceThe primary audience for this document consists of Windows administrators and application developers who are building and deploying database-centric applications.

Documentation UpdateThis document contains all the information that was available at the time of publication. Changes identified after release of this document are included in problem list entry (PLE) 18974860.

To obtain a copy of the PLE, contact your Unisys representative or access the current PLE from the Unisys Product Support Web site:

http://www.support.unisys.com/all/ple/18974860

Note: If you are not logged into the Product Support site, you will be asked to do so.

1–2 3826 5856-005

Section 2Runtime Administration

The Runtime installation includes three Microsoft Management Console (MMC) snap-ins, through which the administration of the runtime environment and deployed applications are performed.

The Administration Tool snap-in enables you to configure the runtime environment to be ready for deployment of applications and perform administration tasks required for deployed applications.

The Component Services is a standard Windows snap-in, through which you can configure the required security roles. You can also stop and disable deployed applications through Component Services. See your Agile Business Suite Installation and Configuration Guide for details of security configuration.

The OpenTI snap-in is required to achieve OLTP transactions in AB Suite 4.0 Windows Runtime. It enables you to configure the services for OLTP Server systems which can be used for OLTP transactions with AB Suite Runtime systems. See the Agile Business Suite Installation and Configuration Guide for further details.

Using the Administration ToolThe Runtime Administration Tool is a snap-in to the Microsoft Management Console. It enables you to configure and manage the runtime environment and deployed Agile Business Suite applications.

You can also manage your applications through a client interface or directly through COM+ using administration commands.

The Administration Tool has two panes:

• Scope Pane

The left pane contains the navigation tree, which displays all servers, databases, and Agile Business Suite applications to which the Administration tool is connected. Administration functions are invoked from the scope pane.

• Result Pane

The right pane displays the contents of the selected navigation tree node.

3826 5856-005 2–1

Runtime Administration

The use of many of the administration functions are restricted to users with the required security priveleges. Security for administration functions is controlled using the COM+ roles. Those functions that require COM+ roles to be assigned are listed in the Security topic.

The following topics are covered in this section:

• Using the Administration Tool

• Defining Network Users

• Setting Up Your Runtime Environment

• Configuring Protocol Adapters

• Configuring Log Files

• Managing Your Application

Using the Scope Pane

The nodes in the scope pane represent the structures required to run and manage deployed applications, as described in the following table:

Icon Name Description

Administration Tool snap-in The root node of the Administration Tool MMC snap-in.

Local Domain The local domain of the Windows workstation.

Network Neighborhood The additional domains of a Windows network.

Message Log Contains logged messages. Select to view the logged messages in the result pane.

Favorites Contains server machines that are selected for use in Runtime.

Runtime Servers The server machines that are selected for use in Runtime.

Views The protocol adapter views that are set up for use by the server.

2–2 3826 5856-005


Accessing Administration Options

All available options can be selected from either the menu bar or the context menus. Using the right mouse button gives you fast access to context menus and lets you quickly perform functions on a selected node.

Refreshing the Scope Pane

The navigation tree dynamically changes as you modify its structures. Changes that other users make are not visible to you unless you refresh the navigation tree. You need to refresh individual nodes so that changes are visible.

To refresh the navigation tree:

1. Select the required node.

2. On the Action menu, select Refresh. Alternatively, right-click the node and select Refresh.

Event Log A Windows Event log is installed for every server machine.

Database Server Registration

The servers registered for use on a given machine.

SQL Server 2012 Database SQL Server 2012 databases that are available on the selected server.

SQL Server 2012 application

Applications that are generated and deployed to an SQL Server 2012 database.

Report Reports that are available in the selected application.

Running Report Reports that are currently running in the selected application.

Stopped Report Reports that have been stopped and are available for recovery.

Icon Name Description

3826 5856-005 2–3


Defining Network Users The administrator can create a LINCIINET file, or station data file, which specifies user privileges for a System. When a user signs on to a System or a Report is initiated, the LINCIINET file provides information about the user's privilege level.


• The Station Info (LINCIINET) File

• Creating a Station Info (LINCIINET) File

The Station Info (LINCIINET) File

User privileges can be specified using a Station File. In previous versions of the product, the equivalent file has been referred to as the LINCIINET file. This file should be placed in the application private folder, the path of which is stored in the registry under the key HKEY_LOCAL_MACHINE\SOFTWARE\Unisys\AB Suite 4.0\SM Runtime\PrivateFolder. By default, this is C:\AB Suite 4.0\Data\private.

When a user signs on to a System, the Station Info file is opened for the System and entries corresponding to the current user account are read. These entries are moved into global attributes that can be accessed by the logic of the System, as follows:

• The username is stored in Glb.User

• The user’s access privilege level is stored in Glb.Priv (1 through 15)

• The user’s associated printer is stored in Glb.ASCPrt

Every presentation ispec in the model has a configurable privilege level property. This property should be set for each ispec before generating the system.

Note: For all existing 3.3 models, ispec privilege levels need to be configured after importing into Agile Business Suite. Every time ispec privilege levels are changed the system should be regenerated.

Once the system is generated, user privilege levels will be read from the Station Info files and the COM+ roles as defined in the Administration Tool. The Station Info values will override the COM+ roles. If the user’s privilege level as specified in the Station Info file or in the COM+ roles is lower than that specified by the presentation ispec, the user will get an insufficient privilege level error.

If no entry is found for a user account (or the Station Info file is not found), Glb.Priv defaults to 1 for users in the Users COM+ role, or 15 if the user is an Administrator. Glb.ASCPrt is set to Glb.Spaces

The various interfaces to and from Systems (NOF, GLI and USER, for example) use the value of Glb.Priv of the originating user account.

2–4 3826 5856-005


Specific logic can be also be restricted to certain users by checking Glb.Priv:

DW Glb.Priv > 12 :some code End

Creating a Station Info (LINCIINET) File

To create a Station Info (LINCIINET) file, in the directory indicated by the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Unisys\AB Suite 4.0\SM Runtime\PrivateFolder create a text file with the filename <segmentname>.stn. For example:

SAMPLE.stn

Note: By default, the STN file name is <segmentname>.stn. The file name can be changed by setting the ALTERNATE NAME property of the segment’s configuration properties.

The file should follow the same format as in Enterprise Application Environment 3.3. Each line of the Station Info (LINCIINET) file should be of the format:

<userid>:<privilege level>:<ascprinter>

The user ID and privilege must each be followed by a colon (:), while each line must be terminated by a new line character.

For example:

Unisys\Appuser:15:lp -d Unisys\William:11:lp Unisys\Louis:14:lp -d laser Unisys\James:1:

In this example, Unisys\James has no associated printer defined. The default printer will be used.

NameMaximum

Size Description

User ID or Station name

40 This should be the full Windows user ID in the format <domain>\<username>. The username value can be used by itself without the domain, but in this case this entry will apply to all users with this username regardless of their domain.

You can optionally use the station name if the client has been configured with a user-defined station name.

privilege 2 Number in range 1 through 15.

ascprinter 40 Optional name of an associated printer. If defined, this value is moved into the attribute Glb.Stn for TP Reports to provide a default printer.

3826 5856-005 2–5


Setting Up Your Runtime Environment Before you can generate an application to your runtime environment, there are several set up requirements that you must complete:

• Adding a Runtime Server

• Adding a Database Server Registration

• Configuring User Rights to Add or Remove a Database

• Adding a Database

• Setting the Machine ID for Scale-Out

Adding a Runtime Server

Adding a runtime server requires a server machine to be added to the Favorites folder of the Administration Tool.

There are several ways to add a server machine:

• Using the Domain and Network Neighborhood nodes, navigate to the required server machine.

Then either:

– Right-click the machine name, select All Tasks > Add to Favorites.

– Drag and drop the machine to the Favorites folder.

• Alternatively, right-click the Favorites node and select Add Server.

Enter the name of the required server machine and click OK.

Removing a Server from Favorites

You can remove a server from the Favorites folder in one of the following ways:

• Right-click the server node and select All Tasks > Remove From Favorites.

• Right-click the server node and select Delete.

• Select the server node and press the Delete key.

Adding a Database Server Registration

Once you select a server machine, you need to add a database server registration for each of the runtime servers to which you want to add databases.

2–6 3826 5856-005


To add a database server registration:

1. Right-click the required server node, and select All Tasks > Register Database Server.

The Register DB Server dialog box is displayed.

2. In the DBMS registration alias name field, enter a name to identify the database server registration.

3. In the Server machine field, enter the name of the database server. If the database server is local, enter localhost. Otherwise, enter the remote database server name. If the database server is in a cluster, enter the database cluster name.

4. In the Instance name field, enter the SQL server instance name if you are using a named instance. If the SQL server instance on the database server is the default instance, leave this field blank.

5. Click OK to add the database server registration node to the runtime server node.

Register DB Server Dialog Box

Use this dialog box to register a database server for use in the runtime environment.

DBMS registration alias name

Enter a name by which the server registration will be identified in the navigation tree.

Server machine

Enter the database server name. If the database server is local, enter localhost. Otherwise, enter the remote database server name. If the database server is in a cluster, enter the database cluster name.

Instance name

Enter the SQL server instance name if you are using named instances. If the SQL server instance on the database server is the default instance, leave this field blank.

MSSQL Server Settings

This is used to register an SQL server.

If not using the default instance, you must enter the instance name in the Instance name field.

Removing a Database Server Registration

To remove a database server registration either:

• Right-click the registration node and select Delete.

• Select the registration node and press the Delete key.

3826 5856-005 2–7


Configuring User Rights to Add or Remove a Database

Note: Only a system administrator can configure the privilege rights for users to add or remove a database.

To ensure that a user has the privilege rights to add or remove a database in the Agile Business Suite Administration Tool, add the user to the following policy, groups, and roles.

• Allow logon through Terminal Services policy

Refer to the Help provided with your Microsoft Windows Operating System for information on how to add a user to a policy.

• Users and Remote Desktop Users groups

Refer to the Help provided with your Microsoft Windows Operating System for information on how to add a user to a group.

• Database Creators and Database Preparers roles in the AB Suite 4.0 Database Manager.

To add a user to a role, perform the following steps:

1. Go to Start > Apps > Agile Business Suite 4.0 > Administration Tool.

The AdminTool window appears.

Note: You can also add a user to a role from Control Panel > System and Security > Administrative Tools > Component Services. In the Component Services window, navigate to Roles as mentioned in the following step.

2. In the left pane of the AdminTool window, navigate to Component Services > Computers > My Computer > COM+ Applications > AB Suite 4.0 Database Manager > Roles.

The Database Creators and Database Preparers roles are displayed in the right pane of the AdminTool window.

3. Double-click the role to which you want to add a user.

The Users folder is displayed in the right pane of the AdminTool window.

4. Right-click the Users folder and select New > User.

The Select Users or Groups dialog box appears.

5. Specify the user you want to add to the role in the Enter the object names to select box in the Select Users or Groups dialog box.

6. Click Ok to add the user in the selected role.

Adding a Database

There are two ways to add a database to your runtime environment:

• Create a new database

• Attach an existing database

2–8 3826 5856-005


Creating a New Database

The Administration Tool provides the functionality to create a new database on the database server. However, it is recommended that you create your own databases using the Enterprise Management tools that come with your server software. This has the advantage of enabling you to fully control the preparation, deployment, and configuration of the database.

To create a new database:

1. Right-click the required database registration node and select New, Database...

The Add a New Database dialog box is displayed.

2. In the Name field, enter the name of the new database.

3. Click OK.

This adds a new database on the database server.

Database Configuration

After you create a new database on the database server, you can configure the database properties.

Right-click the new database node, and select All Tasks > Configure Database Parameters.The Database Configuration dialog appears. It consists of two tabs – DBTimer Properties, and DataAccessor Properties.

DBTimer Properties

The DBTimer Properties tab consists of three properties which are explained as follows:

• Connection Time-Out – Defines how long a connection attempt should wait before time-out.

• Command Time-Out – Defines how long database commands should wait before time-out.

• Lock Time-Out – Defines how long lock requests should wait before time out.

The above three properties may need to be increased when you experience a large number of time-outs (for example over a slow network or a heavily used resource). This allows AB Suite to successfully complete certain database operations.

Data Accessor Properties

The Data Accessor Properties tab provides us with the option of choosing either Data Readers or Data Sets as the data accessors. By default, the option Use Data Readers is checked, enabling the use of Data Readers, which helps achieve performance compared to the use of Data Sets.

3826 5856-005 2–9


The Data Reader fetches one row at a time and hence is faster compared to the Data Set, which fetches all data from the data source at a time to the memory.

A Data Reader is a preferred choice over a Data Set in scenarios where you need to fetch data that requires no transaction.

Attaching an Existing Database

To add an existing database, you must attach it to the new Windows Runtime environment using the Administration tool.

An existing database can be:

• A SQL server database.

• An AB Suite 1.2, 2.0, 3.0 or 4.0 Runtime environment database.

• An AB Suite 1.2, 2.0, 3.0 or 4.0 runtime database to be used as a new debugger database.

• An AB Suite 1.2, 2.0, 3.0 or 4.0 debugger database created by another user to be used as a new debugger database.

To attach an existing database:

1. Right-click the Database Server node and select All Tasks > Attach Existing Database.

The Attach a Database dialog box is displayed with a list of databases that can be attached.

Notes:

• The list includes AB Suite 1.2, 2.0, 3.0 or 4.0 Runtime environment databases and existing SQL server databases.

• Only the AB Suite runtime database names are appended with “(AB Suite)”.

2. Select a database from the list.

3. Click OK.

After attaching the database you can start the AB Suite system.

Removing a Database

Database nodes represent the Agile Business Suite Runtime capable databases on the selected server.

There are two options for removing a database from your runtime environment:

• Deleting a database

• Detaching a database

2–10 3826 5856-005


Deleting a Database

Deleting a database involves the complete removal of the database from the server. You can only delete a database if it does not contain any applications.

To delete a database, either:

1. Right-click the required database and select Delete.

2. Click OK to confirm deletion.

Or,

Select the required database and press the Delete key.

Detaching a Database

Detaching a database involves the removal of the database from the runtime environment but does not delete the database or the data it contains.

This option is useful if you want to remove a database from use but retain the application data it contains.

To detach a database:

1. Right-click the required database and select All Tasks > Detach From Runtime.

2. Click OK to confirm.

Using Scale-Out

A scale-out scenario describes the deployment of a single runtime application on multiple Runtime server machines on a network, where all instances of the application are connected to a single database.

In order to implement a scale-out scenario, a unique ID must be specified for each server machine involved, using the Administration Tool. See Setting the Machine ID for Scale-Out for further details.

You should be aware of the following when implementing a scale-out scenario:

• Synchronizing

The administrator is responsible for ensuring that all instances of a deployed application are kept synchronized with the database, and thus the same version is maintained across all machines. This applies to applications and reports.

• Redeploying

All instances of a scale-out application must be shutdown prior to it being redeployed.

3826 5856-005 2–11


• Database Reorganization

All instances of a scale-out application must be shut down during database reorganization. A reorganization cannot be started if any instance is running.

• Activities

– All system activities operate on the instance of the application and the machine on which they were initiated.

– All report activities operate on the instance of the application and the machine on which they were initiated.

Setting the Machine ID for Scale-Out

Each Runtime server machine that is to be part of a scale-out scenario must first be assigned a unique ID using the Administration Tool:

1. Right-click the Server node, and select All Tasks > Set Machine ID.

2. Enter a value in the displayed dialog box. This value must be unique between the current machine and any other machine involved in the scale-out.

3. Click OK.

The default number is one when installed.

Configuring Protocol Adapters Protocol adapters are external interfaces that can be used to connect external clients to applications. See Using Protocol Adapters for further details.

Note: If the protocol adapters are not installed on the server machine, the Configure Adapters menu option is not available.

To configure protocol adapters:

1. Right-click the required server node and select All Tasks > Configure Adapters.

The Configure Adapters dialog box is displayed.

2. Complete the necessary fields on the individual protocol adapter tab pages.

You can enable or disable packet logging for each protocol adapter.

3. Click OK to confirm the settings.

To facilitate connection to your Agile Business Suite application you must set up views, which contain all required connection information. See Creating Views for further details.

2–12 3826 5856-005


Configure Adapters Dialog Box

Use the tab pages contained in this dialog box to set the configuration options for protocol adapters.

RATL over MSMQ and SOAP over MSMQ

MSMQ Server Machine

Enter the name of the machine on which the required MSMQ server is located.

Packet Logging

• Enabled – Select to enable packet logging.

• File path – Specify the file path and name of the log file.

• File size (kb) – Specify the maximum size of the log file.

• Number of backups – Specify the number of backup files that can be created once the log file has reached its maximum size.

RATL over TCP/IP and HUB

Port number

Enter the port number on which the RATL-over-TCP/IP (RATLSocket) or the HUB (HUBSocket) protocol adapter listens for incoming connections with the Agile Business Suite application.

Time out

Enter the time, in seconds, that the adapter waits before timing out.

Packet Logging

• Enabled – Select to enable packet logging.

• File path – Specify the file path and name of the log file.

• File size (kb) – Specify the maximum size of the log file.

• Number of backups – Specify the number of backup files that can be created once the log file has reached its maximum size.

Creating Views

Views store the information that is required for protocol adapters to connect to applications. A view can apply to several protocols or can be unique to one protocol. See Using Protocol Adapters for further details.

Note: If protocol adapters are not installed on the server machine, the View menu option is not available.

3826 5856-005 2–13


To add a view:

1. Right-click the View node of the required server and select New > View.

The Add a View dialog box is displayed.

2. On the General tab page you must specify:

• The name of the view.

• The name of the system to which the view connects.

Note: When creating a view for Component Enabler User Interfaces, this System name is case sensitive and should correspond exactly to the system name of the application. The system name will be the name of the Segment or else the Alternate Name if it has been defined.

• The runtime server to which the view relates.

3. Complete the fields on the option pages as required:

• General

• IP Access List

• Anonymous User

4. Click OK.

Configuring Views

Once you have created a view, you can change and configure its values by either double-clicking the view node, or by right-clicking the view node and selecting Properties.

Note: If you make changes to an existing view, you must restart the appropriate AB Suite Protocol Adapter for these changes to be actioned.

General

Use this page to specify the application and protocol details of the view.

The following fields are mandatory:

• View Name

• System Name

• Runtime Server

Note: View Name and System Name fields are case sensitive.

Select the protocols to which the view is to apply. Some of the protocols require additional information to be entered:

• If you select RATL over MSMQ, you must also enter the name of the message queue to be used.

2–14 3826 5856-005


• If you select SOAP over MSMQ, you must also enter the name of the message queue to be used.

• If you select HUB, you must also enter the details of an existing user that can access the target application.

• If you select RATL over MSMQ or TCP/IP you can customize the RATL login labels. Click on the RATL Login Settings button to customize the login greetings and labels.

IP Access List

Use this page to restrict access to the view for specified IP addresses.

To allow access to all addresses you can either leave the IP Address list blank, or specify the address range *.*.*.*.

You can specify address ranges (for example, 123.123.12.*) to allow and deny access. You can specify a range to allow access and deny one address in that range, or vice versa.

Once you add an address to the list, any addresses not included in the list as allowed are denied access, that is, you must specify all addresses to which you want to grant access.

To specify IP addresses to be specifically allowed or denied access:

1. Enter the required address in the edit fields.

2. Select either Allow or Deny.

3. Click Insert to add the address to the list.

To edit an IP address:

1. Select the address from the list.

2. Make the required changes.

3. Click Update.

To delete an IP address, select the required address and click Delete.

When accessing, the list is processed in descending order. Use the Move Up and Move Down buttons to organize the address list.

Anonymous User

Use this page to set up anonymous user login details for the view. Anonymous user login enables all users to login using the same details.

Select Use Anonymous User Login to enable anonymous user support for the view.

3826 5856-005 2–15


Enter the Name, Domain, and Password of the existing user account that is to be used for anonymous login.

Configuring Log Files Logging can be configured at the server level to capture details of deployment, database reorganization, application and Runtime API transactions.

• The Deployment log file is used each time deployment packages are deployed, either automatically as part of the build process from Developer, or manually on the runtime server (this does not include the redeployment/database reorganization process).

• The DB Reorg log file is used each time an application is redeployed and the database reorganized. It contains any error messages, and debug information created during the database reorganization process.

• The System log file applies to all other Runtime components.

To configure logging for your server:

1. Right-click the required server node and select All Tasks > Configure Log Files.

2. Select the required tab and complete the following options:

Enabled – Select to enable logging.

Logging Level – Specify the level of logging information to be logged. By default Error messages are logged. The increasing level of log information is Error, Warning, Information, and Debug, where Debug is the highest level of log information.

File path – Specify the location of the log file. The default location is <installation directory>\data\public\log.

File size (kb) – Specify the maximum size of the log file.

Number of backups – Specify the number of backup files that can be created once the log file has reached its maximum size.

Managing Your Application There are several ways to manage an application. The most convenient way is using the Runtime Administration Tool.

If you are using a client interface to access an application, administration functions can be accessed using administration commands. If you are accessing an application directly through COM+, administration methods are also available. See Using Administration Commands for further details.

The performance monitoring capabilities enable you to track the activity of an application.

2–16 3826 5856-005



• Security

• Working with Systems

• Reports

• Monitoring Performance

Security

Several of the administration functions require users to have certain security privileges in order to use them. The following table lists the administration functions and the COM+ roles that can access them. Users do not require all listed COM+ roles to use a function, they only need to be assigned to one.

To configure security:

1. Expand the nodes of the Component Services snap-in until you locate the required generated application.

2. Update the roles as required:

Working with Systems

System nodes represent the applications deployed on a selected database.

The available administration options for applications are:

• Configuration Options

Administrative Function COM+Role(s)

Enabling/Disabling HUB Hub Administrators

Application Administrators

Setting High Account Month Accountants


Setting Low Account Month Accountants


Running a Report Report Runners

Report Administrators


Stopping a Report Report Runners (Own reports only)

Report Operators

Report Administrators


3826 5856-005 2–17


• Enabling/Disabling a System

• Stopping a System

• Deleting a System

• Redeploying a System

• List Current Users

• Transferring a System

Configuration Options

To configure the properties of an application, right-click the application node and select All Tasks, Configure.

The following configuration option pages are available for each application:

• Customize

• Multilanguage

• HUB

• Print

Customize

Audit Logging

Use these options to define how activities and transactions are logged to the Audit log:

• Log Activities – Select to log the activities of the application.

• Log Transactions – Select to log the transactions of the application.

• Log Transactions in NOF format – Select to log the transactions of the application with the ispec data values logged as a single string value in the NOF format.

• File Path – Specify the location of the log file.

• File Size (kb) – Specify the maximum size of the log file.

• Number of Backups – Specify the number of backup files that can be created once the log file has reached its maximum size.

Every record written to the audit log (and other log files such as the System.log) contains a standard log record header with the following information:

<date/time> <process> (<process id>:<thread id>) [<user id>]

Where,

<date/time> is in the format YYYY-MM-DD hh:mm:ss.ttt (<ttt> = thousandths of a second).

2–18 3826 5856-005


<process> is the name of the process executing the activity/transaction and will generally be “dllhost” for on-line activities or transactions and “ReportContainer” for report activities.

<process id>:<thread id> is the current process ID and thread ID.

<user id> is the user ID under which the process is running. For online transactions this will generally be the client user from which the transaction was submitted. For audit records written from reports, this user ID will always be the Application User. For an accurate record of the client users actually performing online and report activities and transactions refer to the user ID as recorded within the audit <event> part of the record as described below.

Activities logging

If the “Log Activities” option is set, events such as user log on or log off and report start or finish will be logged. The format of these log messages is:

<standard log record header>; <event>

Where,

<event> can be,

LOGON <domain user id> <#session id> SUCCESS

ISPEC HI USER <domain user id> <#session id>

LOGOFF <domain user id> <#session id>

REPORT START <report name>@<session id> USER <domain user id> LANGUAGE <language name> PA <parameter value>

REPORT FINISH <report name> @<session id>

Transaction Logging

If the “Log Transactions” option is set, all transactions will be logged.

If the “Log Transactions in NOF Format” option is set, all transactions will be logged with the Ispec data logged as a single string value in the NOF format.

Note: You can only set either of these options if the “Log Activities” option is also set.

The format of these log messages is:

<standard log record header>; <event>

Where,

<event> can be:

3826 5856-005 2–19


<direction> <ispec name> USER <domain user id> <#session id> STATION <station name> [<ispec data>]

<direction> can be one of the following values:

IN – normal transaction input

OUT – normal transaction output

HUBIN – HUB transaction input

HUBOUT – HUB transaction output

<ispec data> consists of the data that is input/output to/from the ispec. This data can be in one of two formats determined by whether the “Log Transactions” or “Log Transactions in NOF Format” option is set.

Log Transactions

This specifies the standard format which consists of a comma separated list of field name/value pairs for all input/output ispec fields, with each in the format:

[<field name> (<data value length>) = <data value>]

The <data value> is masked with the mask definition (* by default) specified in the model (MaskDefinition property) if an attribute has the EnableMaskDefinition configuration property set to true.

This is an example of an input transaction event for the ispec “SalesRep” by the user “UNISYS\Smith”:

IN SalesRep USER UNISYS\Smith #2 STATION UNISYS\Smith [[_ISPEC (8) = SalesRep], [_SOURCE (1) = T], [_TRANNO (6) = 000001], [_INPUT_DATE (7) = 27APR09], [_ACTMTH (4) = 0904], [_UserMAINT (3) = ADD], [SalesRep_Id (2) = S1], [Name (10) = John Smith], [Area (9) = “Australia”], [Return (0) = ]]

Log Transactions in NOF Format

This specifies an alternative format in which the ispec field data is logged as a NOF string. The NOF string value is where all ispec field values are concatenated together into a single string. The format of this NOF string is defined in a “field description” XML file for each ispec. These “field description” files are located in the <System>\Interfaces\ProtocolAdaptors folder for each deployed system.

The <ispec data> part of a NOF format audit log record has this format:

[NOFDATA (<NOF string length>) = <NOF string value>]

The <NOF string value> is a NOF formatted message containing the ispec data. This is a serialized version of the Ispec data with the field data sequenced according to the NOFOrder property value for each attribute.

2–20 3826 5856-005


The <NOF string value> is masked with the mask definition (* by default) specified in the model (MaskDefinition property) if an attribute has the EnableMaskDefinition configuration property set to true.

If an output Ispec message contains a single status line message or a single user/error message, this value will be part of the <NOF string value> (appended to the end). However, if the output message includes multiple user/error messages, then these messages will be formatted into a separate MESSAGEDATA tag. This will have the format:

[MESSAGEDATA (<Message string length>) = <MESSAGEDATA string value>]

The <MESSAGEDATA string value> will consist of all messages formatted as 80 character values appended together.

This is an example of an input transaction event for the ispec “SalesRep” by the user “UNISYS\Smith” that is logged in the NOF format:

IN SalesRep USER UNISYS\Smith #2 STATION UNISYS\Smith [NOFDATA (58) = SREP T00000127APR090904ADDS1 John Smith Australia]

High and Low Account Months

High – Specify the High Account Month for the application.

The High Account Month value prevents the application from accepting any transactions that have a later date (specified by the built-in attribute ActMth). The default value is the year and month that the application was initiated.

Any valid High Account Month value remains in effect until a new one is specified, or until the application date becomes greater than the current value, at which time its value is increased automatically. The High Account Month value is stored in the application database.

Low – Specify the Low Account Month for the application.

The Low Account Month prevents the application from accepting any transactions that have an earlier date (specified by the built-in attribute ActMth). The default value is the year and month that the application was initiated.

Any valid Low Account Month remains in effect until a new one is specified. The value of the Low Account Month is stored in the application database.

Multilanguage

Use this page to specify the path to the language.dll to be used by the application.

HUB

Use this page to enable or disable external automatic entries (HUB) for an application.

3826 5856-005 2–21


Before you can enable external automatic entries, the HUB protocol adapter must be running for the current environment.

While HUB is activated, this page displays the statistics on requests sent and received.

See HUB (External Automatic Entries) for further details of using HUB.

Print

Use this dialog page to configure print properties required to format the print output for a Report/Outputstream.

These parameters are described in the following table:

Name Type Description Default Value Rules

Print Tab Panel

Used to configure print properties for Reports/OutputStreams

N/A Selecting the Print tab, the drop-down lists “View/Change Settings”, for reports and output streams will be re-populated to have the latest list of entities which are configured for printing.

View/Change Settings for reports

Combo Box

Contains all the Reports added to the list for configuring print properties

“All Reports” The list of Reports will not be pre-populated. The user can add selected reports to the drop-down list by clicking on the “Add Report/OutputStream List” button. This will open up the “Add Report/OutputStream” dialog through which the reports can be added. All Reports and Outputstreams defined in the system will be available to be added. You should only add those Reports and Outputstreams for which you need to configure print properties.

2–22 3826 5856-005


View/Change Settings for OutputStreams

Combo Box

Contains all the OutputStreams added to the list for configuring print properties

“All OutputStreams”

The list of OutputStreams will not be pre-populated. The user can add selected OutputStreams to the drop-down list by clicking on the “Add Report/OutputStream List” button. This will open up the “Add Report/OutputStream” dialog through which the OutputStreams can be added. All Reports and Outputstreams defined in the system will be available to be added. You should only add those Reports and Outputstreams for which you need to configure print properties.

Add Report/Output Stream List

Button To add a Report/OutputStream to the list

NA N/A

Delete Report/Output Stream List

Button To delete a Report/OutputStream from the list

NA The report/outputstream selected in the “View/Change Settings” combo box for reports and output streams will be deleted from the drop-down list and also the configured values for this entity is lost.

Use Default Check Box

When checked, the default value for the property will be used. The default value indicates the value inherited from up the hierarchy.

Checked N/A


3826 5856-005 2–23


Page Depth Text Box

View or modify the page depth value. This will result in the print font size being set such that the defined number of lines will fit onto a single page.

60 Positive values only will be accepted. The value range is 0-9999.

Page Width Text Box

View or modify the page width value. This will result in the print font size being set such that the defined number of characters will fit across the printed page.

132 Positive values only will be accepted. The value range is 0-9999.

Horizontal Margin Text Box

View or modify the horizontal margin value

0 The value range is 0-9999. Any value above 25 will be rounded off to take the default value, i.e., 0.

Vertical Margin Text Box

View or modify the vertical margin value

0 The value range is 0-9999. Any value above 25 will be rounded off to take the default value, i.e., 0.

Page Orientation: Portrait

Radio Button

Sets the page orientation to portrait

Selected N/A

Page Orientation: Landscape

Radio Button

Sets the page orientation to landscape.

Not Selected N/A


2–24 3826 5856-005


Adding Reports/OutputStream

It is possible to add the set of Reports/OutputStreams existing in an AB Suite application, for which the print property values need to be configured. Use the Add Reports/OutputStream dialog box to add a Report/OutputStream to the existing Report/ OutputStream list of Print Properties. You can specify the options listed in the following table, using this Interface.

Font Combo Box

Select the desired font name for printing. The drop-down list will show the font names available on that particular machine.

LincDefault New The font you select here is used for all the reports. To use a different font for specific reports:

1. Select the report from the Reports combo box

2. Uncheck Use Default in Font frame.

3. From the combo box, select the required font from the list of available fonts

Configure Printer Names

Button To set the Default Printer name and the EOM Printer name

N/A On clicking this button, the “Configure Printer Names” dialog box is opened for configuring the Default Printer name and EOM Printer Name.


Report Name Combo Box

Will list all the available reports. The user can select the desired Report by typing the name.

All reports NA

OutputSteam Name

List Box Will list all the OutputStreams available within the selected report. Multiple OutputStreams within a report can be selected and added at once.

List of all OutputStreams within the system (All Reports).

NA


3826 5856-005 2–25


Configuring Printer Names

Use the Configure Printer Names dialog box to specify the name of the Default Printer and the EOM Printer. The User Interface has the two options listed in the following table:

Note: You can delete the configured values for a report/outputstream when they are not required.

Enabling/Disabling a System

When an application is enabled, it is running and available to users.

When an application is disabled, it cannot take input from user workstations or clients, and cannot run reports.

To enable or disable an application, right-click it and select Enable or Disable.

This can be done while the application is running or stopped.

Note: Applications can also be enabled or disabled using the Component Services snap-in.

Stopping a System

Stopping an application causes an unconditional, orderly termination of the application as soon as it is idle. A message is displayed on the status line of all users of the application.


Default Printer

Text Box

Will accept the name of a printer to be used as the default printer. No validation for the printer name is performed. In a case where GLB.Station is not set to any value, then the printer configured through this dialog will be used as the station for printing.

Empty NA

EOM Printer

Text Box

Will accept the EOM printer name. No validation for the printer name is performed.

Empty This feature of configuring EOM Printer name is currently not implemented and thus the EOM Printer text box is disabled.

2–26 3826 5856-005


The input of transactions from terminals is stopped. Currently active transactions are processed until completed. Terminals may still supply messages in response to Accept logic from running reports. All administration commands (except those for Running and Recovering Reports) can be entered.

Active reports are forced to terminate when:

• A Sleep logic statement is executed.

The attribute Glb.Close is set to “CLOSE”, and the report is woken. It processes any termination logic and then terminates.

• The report is just starting.

When all reports have terminated, any external automatic entry server or USER programs are terminated. The system programs are then terminated, and the logic defined in the public segment method Closedown is invoked. The next time the application is initiated, the logic defined in the public segment method Startup is invoked.

To stop an application, right-click the application, and select Stop. If the application is still enabled, a user will be able to reconnect.

Note: Applications can also be stopped using the Component Services snap-in.

Deleting a System

To delete an application from the database do the following:

• Stop the system.

• Disable the system.

• Right-click the application node and select Delete.

Redeploying a System

Redeployment can occur if an existing application is regenerated from Developer. Alternatively you can redeploy an existing application directly from the Administration Tool.

Redeploying an application either replaces, or forces a reorganization of, the application’s database.

To redeploy an application using the Administration Tool:

1. Right-click an application and select All Tasks > Deploy.

3826 5856-005 2–27


2. Select Retain existing database to reorganize the existing application database. If this option is not selected, a new database is built.

List Current Users

To view the users currently logged in to the application, right-click the application node and select All Tasks > List Current Users.

This displays the Current System Clients dialog box, which displays a list of currently connected users of the system, using the :WHO colon command facility.

The text box at the bottom allows you to enter a message to be sent to the users. You can select the intended receiver of the entered message from the list of users and click the Send button to send that message. Additionally, you can send messages to all the users on the list by checking the Send message to all clients check box. The message sending facility uses the underlying :SMG mechanism, so all required security privileges for sending messages via this screen is the same as that of: SMG colon command.

The Refresh button allows you to refresh the list of connected users.

Transferring a System

You can use the Runtime transfer process to deploy an application to a different Runtime machine without using Developer. It can also be used to redeploy an application on the local machine.

The runtime transfer process uses the concept of deployment units, which enables you to deploy a number of MSI or CAB packages at one time.

During a build operation, at the end of the generate phase, the contents of the system or report being built are packaged into an MSI file or a CAB file. These are referred to as "packages". All deployable folders are packaged into the corresponding MSI packages. When you do a single-report build operation, the report is packaged into a CAB package. For single-report deploys, CAB files are used instead of MSI files, because the CAB files are generally simple and efficient to deploy.

1. Right-click the runtime server node on which the required MSI packages are currently deployed.

2. Select All Tasks > Runtime Transfer.

The Initiate Runtime Transfer dialog box appears. It provides the following two options to select deployable units:

CautionReorganizing a very large database may take a long time, depending on the size of the database. Ensure you have a backup of the database before reorganizing it.

2–28 3826 5856-005


a. The Existing Deployment System option to select an existing deployed system on the local server.

b. The Custom Packaged System option to select MSI or CAB files to be deployed.

3. Select an option to initiate the runtime transfer process, and click OK.

The List of Deployment Packages dialog box appears.

4. From the Available Deployment Packages list, select the deployable packages that you want to deploy.

5. Click Add to add the selected packages to the Packages to Transfer and Deploy list.

6. Click OK.

7. If you did not enter a target deployment unit name to be used on the target runtime server, you will be asked if you want to use the existing deployment name or specify a new name.

Note: If you are redeploying to the local machine and you do not specify a new name, the existing package will be overwritten.

Click Yes to retain the existing name.

Click No to enter a new unit name.

8. For each package in the deployment unit, the Deployment Settings for Package dialog box is displayed. You must specify the Target DB server registration and Target DB name for each package.

If you do not specify values for the remaining options, the values entered when the package was built are used.

9. Click Next when you have completed the options for each package.

When you specify the target server name as the same machine, you receive a warning message – “The Source server is same as the Target server. The system will be moved from Source database to Target database and will no longer be accessible from the Source database”. The warning is displayed because there can only be one instance of the system name allowed on a runtime host.

Click Yes.

The Application User Details for Target Machine dialog box appears.

10. Specify the details of the Application User on the target machine.

11. Click Finish.

The progress information for the deployment is displayed in the Event Log node.

Deploy an Application in a Cluster

A cluster comprises of machines or nodes connected to each other. The Cluster software monitors the clustered processes and services running on each node and ensures that these processes and services are switched to another node in the cluster in the event of any failure.

3826 5856-005 2–29


The Runtime Transfer process is also used to deploy an application in a clustered environment, as you have to deploy the application to each Node in the cluster separately. It is recommended that you use a script for the deploy process as that will ensure the sames settings are used on each Node.

Note: During deployment, the location of the Extract Files is fixed. Hence for a cluster environment, a relative path should be used so that the extract files are places in the Data folder of the deployed application. For example, .\Data or ..\Data.

To deploy an application in a cluster:

1. In the Runtime Administration Tool, right-click the Machine name/LOCALHOST node.

Note: You must copy the MSI files and the Resource Group to the cluster Node that you are deploying to.

2. Select All Tasks > Runtime Transfer.

The Initiate Runtime Transfer dialog box appears.

3. Select Custom Packaged System and in Select Package Folder enter the location of the folder that contains the MSI file.

4. Click Next.


5. From the Available Deployment Packages list, select all the MSI files and Cab files (if separate reports in IC1800 or higher) that you want to deploy.

6. Click Add to add the MSI or CAB files to the Packages to Transfer and Deploy list.

7. Complete the Deployment settings dialog as required. Click Next.

Note: The Target Server name must be Localhost.

8. Ignore the warning message and click Yes.

9. Complete the Application User Details dialog and click Finish.

After a few minutes an information dialog is displayed to indicate that the system has deployed successfully. If you selected additional report MSI files then these will be deployed now but you will only receive a success or failure message, not the information dialog.

Repeat this process on each of the other Nodes by first moving the Resource Group to the next Node and then repeating this procedure on that Node. Ensure exactly the same locations and values are used for the system.

After deploying the applications on all the Nodes, you can perform other configurations such as defining Views as in a non-clustered environment. The only difference is that the IP address or Network name to use is not one of the physical Node names but the IP address or Network name of the Resource Group that the Applications have been deployed under (i.e. the network name of the Resource Group that the Protocol Adapters belong to).

2–30 3826 5856-005


Initiate Runtime Transfer

Source Runtime Server Details

Source Server name

Displays the source Runtime server from where Runtime Transfer is initiated.

Existing Deployment System

Select this option to deploy a unit that has been deployed on the local machine. Select the required unit from the list.

Custom Packaged System

Select this option to deploy a unit that has been created from MSI packages that were not originally deployed together. Enter the path of the folder containing the required unit.

List of Deployment Packages

This dialogue allows the user to customize the list of MSI packages for deployment.

Deployment Folder

Displays the selected Deployment folder path.

Available Deployment Packages

Lists all the MSI Packages present in the selected Deployment folder.

Packages to Transfer and Deploy

Lists all the MSI Packages selected by the user, to be transferred and deployed.

Add->

The selected Packages from ‘Available Deployment Packages’ list will be added to ‘Packages to Transfer and Deploy’ list.

Add All

All the MSI packages present in the selected Deployment folder will be added to ‘Packages to Transfer and Deploy’ list.

<-Remove

The selected Package will be removed from ‘Packages to Transfer and Deploy’ list.

Remove All

All the MSI Packages present in the ‘Packages to Transfer and Deploy’ list will be removed.

3826 5856-005 2–31


Move Up and Move Down

Provides a provision to re-order the ‘Packages to Transfer and Deploy’ list.

Notes:

1. Multiple Packages can be selected using CTRL and SHIFT key.

2. Ensure that the Segment Package is deployed before any dependant Report Packages.

Deployment Settings for Package

This dialog box is displayed for each MSI package in the selected unit. Click Next to move onto the next package.

Package Name

Displays the MSI package name, to be deployed.

Target Server Name

This is a mandatory field. Enter the name of the Runtime server to which you want to deploy. Enter “localhost” to redeploy to the local machine.

Target DB server registration

This is a mandatory field. Select the name of the server registration to which you want to deploy.

Target DB name

This is a mandatory field. Select the name of the database to which you want to deploy.

Deployment unit name

Displays the name given to the selected unit when it is deployed on the target machine. It can also be modified as per user wish.

Target application folder

Enter the path of the folder in which the deployed application files will be stored. If you leave this field blank, the path defined when the package was originally built will be used.

Target Winform folder

Enter the path of the folder in which the Winform files are to be stored. If you leave this field blank, the path defined when the package was originally built will be used.

Retain existing database

Select this option if you want to retain the existing database when redeploying to the local machine.

2–32 3826 5856-005


Application User Details for Target Machine

The Application User account details are required to gain access to the target machine.

Name – Enter the name of the user account defined as the Application User.

Domain – Enter the domain name of the destination machine. Enter a period (.) if the target is the local machine.

Password – Enter the password defined for the Application User.

Setting Up AB Suite for Database Mirroring

AB Suite supports Database Mirroring functionality provided by SQL Server. You must set up AB suite for database mirroring on the following servers:

• Runtime Server

• Principal SQL Server

• Mirror SQL Server

Using the Runtime Server1. Install AB Suite Runtime software.

2. Click All Tasks > Register Database Server in the Runtime Administrator Tool to register the principal SQL server as a database server.

3. Add a new runtime database.

4. Deploy a sample system to the newly created database.

5. Change the schema password in Windows Runtime and SQL Server using the Administrator Tool.

6. Ensure that the system is working.

7. Stop and disable the system.

8. Shut down all running instances of dllhost.exe.

Using the Principal SQL Server1. Retrieve the SQL Server ID (SSID) of the runtime schema (to which AB Suite

system is deployed).Query: SELECT SID FROM sys.server_principals where Name=’<Runtime DB SCHEMA name>’

2. Complete a backup of the runtime database from the principal server.

3. Complete a backup of the transaction log of the runtime database from the principal server.

Using the Mirror SQL Server1. Create a database on the mirror server with the same name as that of the runtime

database on the principal instance.

3826 5856-005 2–33


2. Copy the database and transactional log backup files to the mirror server.

3. Create a schema login for the newly created database on the mirror server with the same name and SID as on the principal server. Set the schema password to match the password on the principal server.

Query: CREATE login SAMPLE WITH password=’Welcome@123’, sid=<SID same as principalDB>

4. Update the login after it is created. Query: exec sp_change_users_login ’Update_One’, ’<Schema login name>’, ’<Schemalogin name>’

5. Restore the complete backup of the principal database to the mirror database with the NO RECOVERY option.

6. Restore the backup of the transactional log of the principal database to the mirror database with the NO RECOVERY option.

Configuring SQL Mirroring

You must perform the following steps on the principal database to configure SQL mirroring:

1. Connect to the principal instance in Microsoft SQL Server Management Studio.

2. Select the database to be mirrored on the principal server, for example, SAMPLEDB.

3. Right-click the database, and select Tasks > Mirror.

The Mirroring page of the Database Properties dialog box is displayed.

4. Click the Configure Security button to begin the SQL mirroring configuration.

The Configure Database Mirroring Security Wizard is displayed.

5. Click Yes to add a witness server.

6. Click Yes to configure the witness server.

7. Select the Witness server instance check box.

8. Configure the Principal, Mirror and Witness server by entering the corresponding Listener port, for example, 5022 and the Endpoint name for example, Mirroring.

9. Verify the server configuration summary.

10. After setup is completed, the status of Endpoint configuration is displayed.

This completes the setup of the SQL mirror.

11. Click the Start Mirroring button to start SQL Mirroring.

The change in database status from this database is not configured for mirroring to the databases are fully synchronized is displayed.

Notes:• Principal server database status “SAMPLEDB (Principal, synchronized)”.

• Mirror server database status “SAMPLEDB (Restoring...)”.

2–34 3826 5856-005


Reports

Reports are displayed under the system node to which they belong. You can identify their status by their associated icon or value in the result pane.

Running a Report

To run a report:

1. Right-click the required report node and select Run.

2. Complete the settings in the Run Report dialog box:

• Override default device – Select this option to select a device type to override the default device type of the report.

• Parameters – Select this option to enter a literal string with a maximum of 254 characters, to be passed to the report. The ReportParameter property must have been set prior to generation.

• Set report language – Select this option to select a language to set the report language that is to apply to the current user account.

3. Click OK.

Note: Reports containing the ACCEPT command cannot be run from the Administration Tool.

Stopping a Report

To stop a report:

1. In the result pane, right-click a running report and select Stop.

2. Select the way in which you want to stop the report:

Stop report normally

This is the default.

Select this option to terminate a running report that is either waiting for input, or contains Sleep or CriticalPoint (with the Sleep) logic commands.

The built-in attribute Glb.Close is set for the report the next time the report resumes processing following a Sleep logic command. When the next Sleep logic command is executed, the report terminates.

This option has no affect on a running report that is not sleeping or is not waiting for input.

Terminate report immediately

Use this option to terminate an active Report immediately.

This command is useful if a report is looping or has been started accidentally. You can terminate inquiry reports without affecting the remainder of the application.

3826 5856-005 2–35


There are three options for terminating a report immediately:

• Recover – Select this option if the report is to be rerun. An attempt is made to recover the report up to and including any transaction that may have been processing when the termination was executed.

Two attempts are made to recover the report. If both attempts fail, a message is sent to the errorlog and no further attempts are made.

• No recover – Select this option to delete any recovery information saved for the report, unless extended report recovery is active.

• Discard – Select this option to delete any recovery information saved for the report.

If you select Stop report normally, Recover, or No recover (when extended report recovery is used), the report will still be listed as a candidate for recovery in the navigation tree.

3. In the navigation tree, right-click the report node and select Refresh.

Deleting Report Recovery Information

To delete the recovery information for a report, either right-click the recovery node for a report that is not running and select Delete, or select the recovery node and press the Delete key.

Viewing Report Properties

To view the properties of a report, either:

• Right-click a report node and select Properties.

• Double-click the report in the display pane.

The property information includes:

• Recovery key (if relevant)

• User name

• Status

– A – Abort

– I – Initializing

– X – Running

– R – Recovering

• Device type

• Language

• Parameters

2–36 3826 5856-005


Recovering a Report

Depending on how a report has been stopped, it may be available for recovery.

To recover a report, in the result pane right-click a stopped report and select Recover.

The previously selected options are already present. Change these options as needed.

If the report is recovered successfully, it appears as a running report next time you refresh the list.

Monitoring Performance

The performance monitoring capabilities of Agile Business Suite enable you to keep track of the activity of your Agile Business Suite applications. Agile Business Suite performance monitoring takes advantage of the Performance interface which runs in the Microsoft Management Console (MMC). The System Monitor component of the interface enables you to chart the activity of your application. The Performance Log and Alerts enable you to record the performance monitoring data of your application.

When an application is deployed to your Runtime environment, it becomes a category in the performance interface. This enables it to be monitored and individual counters to be selected for monitoring different aspects of the application.

To access Performance in MMC, go to Control Panel > System and Security > Administrative Tools > Performance Monitor > Performance > Monitoring Tools > Performance Monitor.

Notes:

• For Windows Server 2008 R2, from the Start menu select Control Panel > Administrative Tools > Performance Monitor > Performance > Monitoring Tools > Performance Monitor.

• For Windows 7, go to Start > Control Panel > Administrative Tools > Performance Monitor > Performance > Monitoring Tools > Performance Monitor

• For Windows 8, go to Control Panel > Administrative Tools > Performance Monitor > Performance > Monitoring Tools > Performance Monitor

To monitor an application:

1. In the Tree panel select Performance Monitor.

2. In the right hand pane of the window either right-click and select Add Counters, or click the Add toolbar button.

The Add Counters dialog box is displayed.

3. Select the category for the required application in the Performance objects list.

4. Select the required counters.

Select the Show Description check box for a description of the selected counters.

3826 5856-005 2–37


5. Click Add>> to display the selected counters.

6. Click OK to close the dialog box.

Use the System Monitor toolbar buttons to select the display options. You can also use the Performance Log and Alerts node to create log files of the data. See the Microsoft Management Console online help for further details of using the Performance functions.

2–38 3826 5856-005

Section 3Using Administration Commands

There are several ways to manage an application. The most convenient way is to use the Runtime Administration tool which provides all the required administration functions. A command line utility is also available.

If using a client interface (such as Presentation Client) to access an application, administration functions can be accessed using administration commands.

If accessing an application directly through COM+, administration methods are available.

The use of many of the administration functions are restricted to users with the required security privileges. Security for administration functions is controlled using the COM+ roles. The required roles for each command are listed with the command descriptions.

The following sections describe the administration commands and COM+ methods available for administering an application:

• Application Related Commands

• Report Administration Commands

• Admin.exe Command Line Utility

Application Related Commands

Command Method/Property DescriptionSecurity Required

:HAM SetAccountMonth() Set or display High Account Month.

Yes

:LAM SetAccountMonth() Set or display Low Account Month.

Yes

:SLA SetSessionInfo() Set or display the language. No

:SMG SendAMessage() Send a message to a user. Yex

:LIS ListIspecs() List the ispecs in an application.

No

:STO StopSystem() Stop an application in an orderly way.

Yes

3826 5856-005 3–1

Using Administration Commands

Setting or Displaying High Account Month

Use this command to set or display the High Account Month for the running application.

The High Account Month value prevents the application from accepting any transactions that have a later date (specified by the built-in attribute ActMth). The default value is the year and month that the application was initiated.

Any valid High Account Month value remains in effect until a new one is specified, or until the application date becomes greater than the current value, at which time its value is increased automatically. The High Account Month value is stored in the application database.

Note: A High Account Month value may be less than the Low Account Month value, to allow for change of century.

Administration command :HAM [ yymm ]

Where yy is the year and mm is the month.

If no value is entered, the current High Account Month value is displayed.

COM+ property LONG SetAccountMonth([in] long, plHigh, [in] long, plLow)

Where, plHigh and plLow are the year and month, specified in the format yymm. This property is used to set both the High and Low Account Months.

LONG GetAccountMonth([out] long* plHigh, [out] long* plLow)

Where, plHigh and plLow are the year and month, specified in the format yymm. This property is used to display both the High and Low Account Months.

:HUB GetHubStats() Display HUB statistics. Yes

:HUB+ SetHubStatus() Enable external Automatic Entries (HUB).

Yes

:HUB- SetHubStatus() Disable external Automatic Entries(HUB).

Yes

:WHO ListUsers() Display a list of active stations

Yes

Command Method/Property DescriptionSecurity Required

3–2 3826 5856-005


Security

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

• Accountants

• Application Administrators

Setting or Displaying Low Account Month

Use this command to set or display the Low Account Month for the running application.

The Low Account Month prevents the application from accepting any transactions that have an earlier date (specified by the built-in attribute ActMth). The default value is the year and month that the application was initiated.

Any valid Low Account Month remains in effect until a new one is specified. The value of the Low Account Month is stored in the application database.

Note: A Low Account Month value may exceed the High Account Month value to allow for change of century.

Administration command :LAM [ yymm ]

Where, yy is the year and mm is the month.

If no value is entered, the Low Account Month value is displayed.

COM+ property LONG SetAccountMonth([in] long, plHigh, [in] long, plLow)

Where, plHigh and plLow are the year and month, specified in the format yymm. This property is used to set both the High and Low Account Months.

LONG GetAccountMonth([out] long* plHigh, [out] long* plLow)

Where, plHigh and plLow are the year and month, specified in the format yymm. This property is used to display both the High and Low Account Months.

Security


• Accountants


3826 5856-005 3–3


Setting or Displaying the Language

Use this command to set or display the language to apply to the current user session.

The language value must be a language name previously defined for the application.

The language can only be changed if the user has a current session.

If no language is entered, the current language is displayed.

Administration command :SLA [ language ]

Where, language is a language defined for the application.

COM+ method SetSessionInfo([in] long lSessId, [in]BSTR bstrName, [in] VARIANT vtValue)

Where:

• lSessId is the session ID for which the language is being set.

• bstrName is the name of the session attribute being set. Valid values are:

– LANGUAGE – sets the language for the session.

– STYLE – sets the Glb.Style value.

– GUI – sets the Glb.GUI value.

• vtValue is the value of the session attribute being set. When setting the session language, use the language id, for example, 1033 for English.

Security



• Application Operators

Sending a Message

Use this command to send a short message to other users logged onto an application.

Administration command :SMG destination message

3–4 3826 5856-005


Where:

• destination is a user account, terminal name, or ALL (for all users of the application).

• message is the text to display on the status line of destination terminals.

COM+ method SendAMessage([in] BSTR destination, [in] BSTR message)

Where:

• destination is a user account, terminal name, or ALL (for all users of the application).

• message is the text to display on the status line of destination terminals.

Security


• Message Senders

• Message Broadcasters

Listing Ispecs

Use this command to list the unique ispecs in the application. The list also contains the ispecs’ alternate names and flags the fire-up ispec.

Administration command :LIS [ ispec ]

Where, ispec is a SAFEARRAY of b-strings.

COM+ method ListIspecs([out, retval] SAFEARRAY* ispec)

Where, ispec is the name (or first part of the name) of the ispec from which you want the list to start.

Security




3826 5856-005 3–5


Stopping an Application

Use this command to cause an unconditional, orderly termination of the application as soon as it is idle. A message is displayed on the status line of all users of the application.

This command stops the input of transactions from terminals. Currently active transactions are processed until completed. Terminals may still supply messages in response to Accept logic from running reports.

Active reports are forced to terminate when:

• A Sleep logic statement is executed.

The attribute Glb.Close is set to “CLOSE”, and the report is woken. It processes any termination logic and then terminates.

• The report is just starting.

When all reports have terminated, any external automatic entry server or USER programs are terminated. The system programs are then terminated, and the logic defined in the public segment method Closedown is invoked. The next time the application is initiated, the logic defined in the public segment method Startup is invoked.

Administration command :STO [DISABLE]

Include DISABLE to stop the application, and to prevent any users from initiating it again.

COM+ method StopSystem([in] bool disable)

Where, DISABLE stops the application and prevents any users from initiating it again.

Security




Display External Automatic Entry Status

Use this command to display the status of the external automatic entry (HUB) transactions for the application.

3–6 3826 5856-005


The information returned includes:

• For requests received:

– Sent messages received from HUB

– Requests completed

– Total

• For requests sent:

– Reply messages sent to HUB

– Requests completed

– Total

Administration command :HUB

COM+ method GetHubStatus([out,retval] VARIANT_BOOL* pbEnabled)

Security


• HUB Monitors

• HUB Administrators


Enabling External Automatic Entries

Use this command to enable external automatic entries (HUB).

Before you can enable external automatic entries, the HUB Listener service must be running for the current environment. You can start the HUB Listener service from Control Panel > Administrative Tools > Services.

Administration command :HUB+

COM+ method SetHubStatus([in] VARIANT_BOOL bEnabled)

Where, bEnabled is true, to enable HUB.

3826 5856-005 3–7


Security




Disabling External Automatic Entries

Use this command to disable external automatic entries (HUB). External automatic entries involving a disabled application set Glb.Status to “NODB”.

Administration command :HUB-

COM+ method SetHubStatus([in] VARIANT_BOOL bEnabled)

Where, bEnabled is false, to disable HUB.

Security




Displaying a list of active stations

Use this command to display a list of stations connected to a runtime system. The information returned includes a list of users logged into the system.

Administration command :WHO

COM+ method ListUsers([out, retval] SAFEARRAY* users)

Where, users is the name of the station you want to interrogate.

Security

Users must be an Application Administrators (COM+ roles) in order to access this administrative function.

3–8 3826 5856-005


Report Administration Commands

Listing Running and Recoverable Reports

Use this command to display information about the reports in an application.

The information displayed includes:

Administration command :REP [ RECOVER ]

Where RECOVER displays reports awaiting recovery. A key value for recovery information is displayed for each report awaiting recovery. You can use this key value with the :DEL command to remove recovery information, or with the :RUN command to recover the report.

COM+ methods SAFEARRAY(BSTR) ListRunningReports

Use this method to display reports awaiting recovery. A unique identifier for and the status of the recovery information is displayed for each report awaiting recovery. You can use this identifier with the DeleteReportRecovery() method to remove recovery information, or with the RecoverReport() method to recover the report.

Command Method DescriptionSecurity Required

:REP ListRunningReports() View the status of active and running report programs.

Yes

:RUN RunReport() Start or recover a report program. Yes

:DEL DeleteReportRecovery() Delete report recovery information. Yes

:STR StopReport() Stop a report at the next Sleep logic. Yes

:TER StopReport() Terminate a report immediately. Yes

:WUP WakeUpReport() Reactivate a report suspended by a previous Sleep or CriticalPoint logic.

Yes

Information Description

Username User account

Report Name Name of the report

Process ID Process ID of the report

Report Status Status of the report

ID The Session ID / recovery key of the report

3826 5856-005 3–9


Security


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

• Report Monitors

• Report Recoverers

• Report Recovery Operators

• Report Recovery Administrators

• Report Administrators

Running and Recovering Reports

Use this command to initiate a report or to recover a report with recovery information available.

Standard input, standard output, and standard error may be redirected as desired. By default, all are directed to the initiating terminal.

The output produced depends on the options specified when the report was created, as well as the device type specified when the report is executed.

Administration command :RUN report [RECOVER key ] [ device ] [TR] [PA params]

Where:

• report is the name of the report.

• key is a unique key value for recovery information.

Include RECOVER key to use the recovery information to recover the report. Use the :REP command to find values for key.

• device is a device type that will override the device type set for the report.

Valid device types are:

LP – Piped to the command defined by the LP alias

TP – Piped to the command defined by an alias

EX – Output to an alias

VD – Output to a temporary file (the name is displayed when the report is initiated)

DI – Direct output to an alias

DP – Direct output to Enterprise Output Manager

• params is a string literal (enclosed in quotation marks) to pass to the report.

3–10 3826 5856-005


PA enables you to pass a string literal with a maximum of 254 characters to the report. The report must have the receiving parameter attribute named in its properties prior to generation.

• Include TR to enable Trace for the report.

COM+ method RunReport([in VARIANT vtReport, [in] IMessages* pMessages, [in, optional, defaultvalue(“”)] BSTR bstrParameter, [in, optional, defaultvalue(“LP”)] BSTR bstrDevice, [in,optional,defaultvalue(“”)] BSTR bstrLanguage, [in, optional, defaultvalue(0)] unsigned long ulFlags)

Use this method to initiate or recover a report.

Where:

• vtReport is the name of the report.

• pMessage is the user’s Imessage interface used to retrieve massages.

• bstrParameter is the parameter to be passed to the report

• You can pass a string literal with a maximum of 254 characters to the report. The report must have the receiving parameter attribute named in its properties prior to generation.

• bstrDevice is a device type that will override the device type set for the report.

Valid device types are:

LP – Piped to the command defined by the LP alias

TP – Piped to the command defined by an alias

EX – Output to an alias

VD – Output to a temporary file (the name is displayed when the report is initiated)

DI – Direct output to an alias

DP – Direct output to Enterprise Output Manager

• bstrLanguage is a language defined for the application.

• ulFlags are flags to indicate where the report is run from. (Not used internally.)

Security


• Report Runners



3826 5856-005 3–11


Deleting Recovery Information

Use this command to delete recovery information for a report.

Administration command :DEL [ key ]

Use the :REP command to obtain the key value.

COM+ method DeleteReportRecovery(LONG sessionID)

Use the ListRunningReports() method to obtain the sessionID value.

Security


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





Stopping a Report

Use this command to terminate running reports that are either waiting for input, or contain the following logic commands:

• Sleep

• CriticalPoint with the Sleep command option

The attribute Glb.Close is set for the report the next time the report resumes processing following a Sleep logic statement. When the next Sleep logic statement is executed, the report terminates.

This command has no effect on a running report that is not sleeping.

Administration command :STR report process

Where:


• process is the process ID of the report.

3–12 3826 5856-005


COM+ method StopReport(VARIANT vtReport, StopReportFlags)

Where:


• Flags determines how any transaction in progress is handled. In this context the Flag value is 1. See Terminating an Active Report for further details of other values.

Security


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

• Report Operators



Terminating an Active Report

Use this command to terminate an active report immediately. This command is useful if a report is looping or has been started accidentally. You can terminate inquiry reports without affecting the remainder of the application.

It is preferable for the report to detect error conditions and terminate itself normally, if possible.

Administration command :TER report [process] [stoptype] :TER report-name [PID] [stoptype] :TER session-number [stoptype]

Session number can be derived using the :REP command.

Where:


• process is the process ID of the report.

CautionIf the report contains Sleep logic statements, transactions prior to the last Sleep logic statement are committed to the application database.

3826 5856-005 3–13


• The process can only be omitted when the command is entered using the user account that initiated the report. In this case, only active reports or reports awaiting normal recovery (not extended recovery) are terminated.

• stopType determines how any transaction in progress is handled.

Use one of the following values for stopType, depending on how you want to terminate the report:

– NO.RECOVERY (or NOR) – use if the report is not to be rerun. Any recovery information saved for the report is deleted, unless extended recovery is in use. This is the default type.

– DISCARD – use if the report is not to be rerun. Any recovery information saved for the report is deleted.

– RECOVER (or NO.DISCARD ) – use to rerun the report, attempting to recover up to and including any transaction it may have been processing when the :TER command was entered.

Two attempts are made to recover the report. If these both fail, a message is sent to the error log and no further attempts are made.

COM+ method StopReport(VARIANT vtReport, StopReportFlags)

Where:


• Flags determines how any transaction in progress is handled.

In the COM+ method, Flags is a numeric value of 1 through 4, depending on how you want to terminate the report:

– 1 – stops the report at the next critical point. See Stopping a Report for further details.

– 2 – does not rerun the report. Any recovery information saved for the report is deleted, unless extended recovery is in use. This is the default type. This corresponds to the NO.RECOVERY stopType of the administration command.

– 3 – does not rerun the report. Any recovery information saved for the report is deleted. This corresponds to the DISCARD stopType of the administration command.

– 4 – the report, attempting to recover up to and including any transaction it may have been processing when the StopReport method was entered. This corresponds to the RECOVER stop type of the administration command.

Two attempts are made to recover the report. If these both fail, a message is sent to the errorlog and no further attempts are made.

Security


3–14 3826 5856-005






Wake Up Report

Use this command to call the Wake logic command, but it does not set GLB.STATUS.

Administration command :WUP report [PA parameters]

Where:

• report is the name of the Report to be run.

• PA specifies a text or numeric expression to pass to the report. This bypasses the prior move to the Glb.Param built-in segment attribute. If a numeric value is used, it will be converted to text. This expression is limited to a maximum length of 254 characters.

The Wake logic command reactivates a report suspended by a previous Sleep or CriticalPoint logic command. When a Wake logic statement is executed, a Wake message is sent to the specified report.

The Wake logic command can also be executed from a report method. If multiple copies of the report are running, each copy of the report is sent a Wake message by the Wake logic command. Specifically, it sends Wake messages to any reports with the same repository path, segment name, and report name that are suspended on the same workstation.

If multiple copies of the report are running, only one copy receives the data specified by the PA command option.

Reports check for Wake messages when Sleep or CriticalPoint logic statements are executed.

COM+ method WakeUpReport(BSTR bstrReport, BSTR bstrWakeUpParam)

Where:

• bstrReport is the name of the report

• bstrWakeUpParam is the text or numeric expression to pass to the report

3826 5856-005 3–15


Security







• Report Runners

Admin.exe Command Line UtilityRuntime administration commands can be accessed using the admin.exe command line utility. This utility is provided with Agile Business Suite Runtime and is located in the Runtime installation directory. The admin.exe command line utility allows you to invoke the same colon commands that you can invoke via a client interface. The syntax is:

admin.exe <system name>

A valid system name must be passed to the utility as a parameter, before it can be used.

For example, to pass the SAMPLE system to the utility:

C:\Program Files\Unisys\AB Suite 4.0\Bin >admin.exe SAMPLE Connected to SAMPLE

Typing help at the colon prompt will display the commands available in the admin utility.

Once connected, the command prompt changes to a colon. The syntax and parameters for these commands are as listed in the Using Administration Commands section. The user invoking the utility must have the appropriate privileges for the command to be successful.

The following commands can be used through scripts. The description is as given below:

Enable

Use this command to enable the system.

Administration command

:Enable

3–16 3826 5856-005


This utility can even be invoked through scripts.

Command

Admin.exe <systemname> /c "ENABLE"

When an application is enabled, it is running and available to users.

Disable

Use this command to disable the system.

Administration command

:Disable

Command

Admin.exe <systemname> /c "Disable"

When an application is disabled, it cannot take input from user workstations or clients, and cannot run reports. To enable or disable an application, right-click on the Application and select Enable or Disable. This can be done while the application is running or stopped.

Note: Applications can also be enabled or disabled using the Component Services snap-in.

For the other Commands like WHO, HUB, STO, etc., we can use scripts to log the output as:

Admin.exe <systemname> /c "WHO" > "C:\filename.txt"

For the STO DISABLE command, use the following syntax:

Admin.exe SAMPLE "STO DISABLE"

3826 5856-005 3–17


3–18 3826 5856-005

Section 4 Deployment Package Manager

Deployment Package Manager (DPM) is an executable that allows you to create a clone of an AB Suite Windows application. The cloned application can co-exist with the original application on the same machine, or can be installed on a different machine.

Cloning of an AB Suite application is required because two instances of a system cannot coexist on the same machine. The Windows installer does not allow the MSI to be installed twice as it uses a unique product GUID. For two instances of the same system to co-exist, their package properties such as instance name and package installation directory should be different. The Windows installer will then treat the second system as a new system with a new COM+ application. This is possible by creating a clone of the MSI using DPM. The cloned MSI will have a unique product GUID (along with other properties) which is different to that in the original MSI.

In addition, DPM provides an option to update the package properties of the cloned MSI or create partial MSIs of the cloned system.

DPM is available in AB Suite Installation Package/CD Runtime/DeploymentPackageManager. You should manually copy the DPM executable from the Runtime CD to your computer. There is no need to install DPM in your computer.

DPM allows you to:

• Create Cloned MSIs of Existing MSIs

• Update the Package Parameters of Cloned MSI

• Create Partial MSIs for Cloned MSIs

Prerequisites for DPMFor DPM to work, the following applications must be present in your computer.

• CSC.exe – C# Compiler is required for compiling and generating new COM+ binary. You should install Microsoft .NET framework for installing CSC.exe. After installation, the CSC.exe is available at: C:\Windows\Microsoft.NET\Framework\v4.0.30319 in your machine.

• SN.exe – Strong Name (SN) generator is required for generating strong name for new COM+ application assembly. You should install Microsoft SDK for installing SN.exe. After installation, the SN.exe is available at: C:\Program Files\Microsoft SDKs\Windows\v8.0A\bin\NETFX 4.0 Tools in your machine.

3826 5856-005 4–1

Deployment Package Manager

• MSIDB.exe – MSIDB.exe is required for analyzing input MSI. You should install Microsoft SDK for installing MSIDB.exe. After installation, the MSIDB.exe is available at: C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin in your machine.

• CABARC.exe – CABARC.exe is required for creating cabinet file for MSI. CABARC.exe is available at: C:\Program Files\Unisys\AB Suite 4.0\Bin in your machine. This file gets installed when you install AB Suite.

The DPMSettings.xml file contains the path of all the pre-requisite applications. This file is automatically created when Deployment Package Manager is run for the first time. This file is automatically created at %allusersprofile%\Unisys \DPM. When this file is created for the first time, DPM automatically locates the path of all pre-requisite applications. You can also edit the paths in this file.

To validate whether the path details in the DPMSettings.xml file are correct:

1. Go to AB Suite Installation package/CD Runtime/DeploymentPackageManager.

2. Double-click DPM-GUI.exe.

The Deployment Package Manager dialog box appears.

3. Click Check Prerequisites.

This displays the path validation status of all the prerequisite applications.

Create Cloned MSIs of Existing MSIsPerform the following steps to create a cloned MSI:

1. Go to AB Suite Installation package/CD Runtime/DeploymentPackageManager, and double-click DPM-GUI.exe.


2. Click Create Deployment Package for a New Instance.

The Create Deployment Package dialog box appears.

3. In the Builder Generated Application MSI field, select the existing MSI file.

The package parameters of the existing MSI file are displayed in the Builder Generated Package column.

The New Instance Package Properties column will be automatically populated with the default values. If required, you can update the parameters with the required values. The new package instance will be created with these parameter values.

4. Click Run.

The task status appears in the next dialog box and a cloned MSI is created in the specified package path.

5. Click Exit to exit the DeploymentPackageManager dialog box.

4–2 3826 5856-005


Update the Package Parameters of Cloned MSI

DPM allows you to change the package parameters of a cloned MSI after its creation.

Perform the following steps to update the MSI package parameters:



2. Click Update Deployment Package for a New Instance.

The Update Deployment Package dialog box appears.

3. In the Builder Generated Application MSI field, select the original MSI file.

The package parameters of the existing MSI file are displayed in the Builder Generated Package column.

4. In the Upgrade Instance Package Location field, select the cloned MSI file.

The Upgrade Instance Package Properties column will be automatically populated with the existing values. If required, you can update some parameters with the required values. The package instance will be updated with these parameter values.

5. Click Run.

The task status appears in the next dialog.

The cloned MSI is updated with the new package parameters.


Create Partial MSIs for Cloned MSIsDPM allows you to create partial MSIs for the cloned application. You can use the partial MSIs to generate new or updated report files for the cloned system.

Perform the following steps to create a partial MSI:



2. Click Create Partial MSI for the Existing Instance.

The Create Partial MSI dialog box appears.

3. In the Builder Generated Application MSI field, select the original partial MSI file.

The package properties of the existing MSI file are displayed in the Builder Generated Package column.

3826 5856-005 4–3


4. In the Instance Deployment Package Location field, select the cloned partial MSI file.

The New Partial Instance Package Properties column will be automatically populated with the existing values. If required, you can update some properties with the required values. The partial MSI will be created with these property values.

5. Click Run.

The task status appears in the next dialog box.

The new partial MSI is created in the specified package path.


Deploying MSIs or CAB Files Using Runtime Transfer

It is recommended that you use Runtime Transfer to deploy cloned MSIs, partial MSIs, or CAB files.

Perform the following steps to deploy cloned MSIs, partial MSIs, or CAB files:

1. Open the Runtime Administration Tool, right-click the runtime server, and select All Tasks > Runtime Transfer.

The Initialise Runtime Transfer dialog box appears.

2. Perform the following in the Initialise Runtime Transfer dialog box.

a. Select the Custom Packaged System option.

b. In the Select Package Folder field, browse and select the cloned or partial MSI\CAB.

c. Click OK.


3. Perform the following in the List of Deployment Packages dialog box.

a. In the Available Deployment Packages pane, the MSI\CAB that you selected is displayed.

Click Add to add the MSI\CAB to the Packages to Transfer and Deploy pane.

b. Click OK.

The Deployment Settings for Package dialog box appears.

4. Perform the following in the Deployment Settings for Package dialog box.

a. Specify the Target Server Name.

b. Select the Target DB Server Registration.

c. Select the Target DB Name.

4–4 3826 5856-005


d. Specify the Deployment Unit Name, Target Application Folder, and Target Winform folder.

e. Select the Retain Existing Database checkbox.

f. Click Next.

The Application User Details for Target Machine dialog box appears.

5. In the Application User Details for Target Machine dialog box, enter the Application User details and click Finish.

The Administration Client Console window displays the runtime transfer details.

6. Click OK to exit.

The cloned MSI, the partial MSI, or the CAB file is deployed to the machine.

Executing DPM from Command PromptPerform the following steps to execute DPM from the command prompt.

1. Open Command Prompt.

2. Enter the path where DPM-Console.exe is located and execute it. The syntax to execute the DPM is:

<DPM-Console.exe location path> <arguments>

Where the arguments are:

Argument Description

-N Creates a new instance package from builder generated package.

-U Upgrades an existing instance package.

-P Creates a new partial instance for DPM generated package from builder generated package.

-V Validates environment for cloning. Application returns non-zero value as exit code.

-B Builder generated package path (.msi or .cab).

-I Instance package path generated by DPM. Valid with -U and -P options.

-O (optional) Overwrites OutputPath Package.

-OutputPath (optional) Output package path. Default value is My Documents.

-SchemaName (optional) Database Schema Name. Valid with -N and -U options.

-DatabaseName (optional) Database Name. Valid with -N and -U options.

-ServerReg (optional) Database Server Registration. Valid with -N and -U options.

3826 5856-005 4–5


Examples• To validate the environment for cloning.

DPM-Console.exe -V

• To clone an instance, you need to provide the following arguments: the package path of the builder generated MSI, a unique database schema name, the output path where the cloned MSI will be available, the database name, the database server registration name, a unique package instance name, and a unique package installation directory.

DPM-Console.exe -N -B="C:\ABSuite\BuilderSAMPLEDeploy.msi"-SchemaName=CLONEDSAMPLESCHEMA -OutputPath=C:\ClonedPackages-DatabaseName=CLONESAMPLEDDB -ServerReg=SQLSERVER -InstanceName=SAMPLECLONE-PkgInstDir="C:\ABSuite\Systems\SampleClone" -O

• To upgrade an instance, you need to provide the following arguments: the package path of the builder generated MSI, the package path of the cloned MSI, the database schema name for the cloned MSI, the output path where the cloned MSI is available, the database name, and the database server registration name.

DPM-Console.exe -U -B="C:\ABSuite\BuilderSAMPLEDeploy.msi" -I="C:\ClonedPackages\SAMPLECLONE.msi" -SchemaName=CLONEDSCHEMA-OutputPath=C:\ClonedPackages -DatabaseName=CLONESAMPLEDDB -ServerReg=SQLSERVER -O

• To create a partial clone for an MSI, you need to provide the following arguments: the package path of the builder generated MSI, the package path of the cloned MSI, the output path where the cloned MSI is available, and a unique package instance name.

DPM-Console.exe -P -B="C:\ABSuite\BuilderSAMPLEReports.msi"-I="C:\ClonedPackages\SAMPLECLONE.msi" -OutputPath=C:\ClonedPackages -InstanceName=SAMPLECloneReports -O

• To create a partial clone for a CAB file, you need to provide the following arguments: the package path of the builder generated CAB file, the package path of the cloned MSI, the output path where the cloned MSI is available, and a unique package instance name.

DPM-Console.exe -P -B="C:\ABSuite\SAMPLE_BuilderSAMPLEReports_AGEDSTOCK.cab" -I="C:\ClonedPackages\SAMPLECLONE.msi" -OutputPath=C:\ClonedPackages -InstanceName=AGEDSTOCK -O

-InstanceName (optional) Instance Name (New Package Name). Valid with -N and -P options.

-PkgInstDir (optional) Package Installation Directory. Valid with -N and -U options.

-Wait (optional) Waits after cloning.

-WaitOnError (optional) Waits only if any error occurs.

-help Displays help.


4–6 3826 5856-005


Creating a Cloned MSI by Changing Configuration Settings in Builder

You can also create a cloned MSI by changing the configuration settings in Builder. The cloned MSI can be deployed side by side with the existing MSI.

Perform the following steps to create a cloned MSI using Builder:

1. Open an existing project in Visual Studio.

2. In the Standard toolbar, select Release from the Solution Configurations drop-down list and select Windows from the Solutions Platform drop-down list.

The Configuration Manager dialog box appears.

3. Perform the following in the Configuration Manager dialog box:

a. From the Active solution configuration drop-down list, select New.

The New Solution Configuration dialog box appears.

Enter a Name.

Ensure that the Create new project configurations checkbox is selected.

Click OK. The new configuration is added.

b. From the Platform drop-down list, select the platform for deployment.

c. Ensure that the Build check box is selected.

d. Click Close to close the Configuration Manager dialog box.

Note: Ensure that Location is added in the model.

4. In the Class View, right-click the Location > Properties.

5. In the Location Property Pages dialog box, enter the new Path Name, and click Apply and OK.

6. In the Class View, right-click the deployment folder and select Properties.

7. In the Deployment Folder Property Pages dialog box, change the following properties:

• Package Name

• Package Intermediate Directory (Not mandatory but recommended to change)

• Package Installation Directory

8. Click Apply and OK.

9. In the Class View, right-click the segment and select Properties.

10. In the Segment Property Pages dialog box, change the following properties:

• Alternate Name

• COM Prog Id

3826 5856-005 4–7


• Database Schema Name

• Database Name


12. In the Class View, right-click the deployment folder and select Build.

After the build process is successfully completed, the cloned MSI is created in the specified Package Intermediate Directory and the name of the package will be <Package_Name>.msi.

4–8 3826 5856-005

Section 5 Command Line and Programmatic Access to Runtime

This section discusses about an interface that allows batchable and programmatic access to the Runtime Administration operations. The interface is designed to:

• Provide command line interfaces allowing you to script the regular runtime administration tasks.

• Include the behavior from multiple predefined sources of runtime administration functions in a class by accessing the Runtime API interfaces that expose several methods. This allows a client to script for automating complex operations by accessing the commonly used functions.

Command Line UtilitiesThis subsection discusses about the following command line utilities.

Note: You must have local administrator privilege to use the command line utilities. A normal user without administrative privileges can access the command line utilities by using the user group “AB Suite Runtime Administrators" on the local machine. You can refer to “Configuring Runtime for Normal Users” in the Installation and Configuration Guide and the relevant command line utilities for more information about security information pertaining to Runtime Administration tasks.

Description Command Name

Configure log files ConfigureLog.exe

Configure protocol adapters ConfigureAdapter.exe

Deploy AB Suite generated package DeployPackage.exe

Create a clone of a builder generated package ManagePackage.exe

Runtime administration and report administration operations AdminSystem.exe

Reconfigure External Persistent Class Utility EPCReconfigure.exe

3826 5856-005 5–1

Command Line and Programmatic Access to Runtime

Configure Log Files Utility (ConfigureLog.exe)

The Configure Log Files utility allows you to configure logging at the server level to capture details of deployment, database reorganization, and application transactions. The log types include AB Suite Runtime System.log, Deployment.log, DBReorg.log, and RuntimeAPI log.

This utility is automatically installed with Agile Business Suite Runtime and is located in the AB Suite 4.0 installation directory. You can invoke the utility from the command line to configure or read the log information.

Note:By default, a local administrator can use ConfigureLog.exe.

For non-administrative users to access this utility, the users must be a member of the "Runtime Administrators" COM+ role of Runtime Manager application or member of the "AB Suite Runtime Administrators" user group.

To run ConfigureLog.exe from a command line

1. Point to the bottom-left corner of the screen to enable the Start icon, right-click Start, and then click Run.

2. Type cmd in the Run dialog box and press Enter to open a Command Prompt.

3. In the command prompt, change the working directory to the /bin folder of the AB Suite 4.0 installation directory.cd C:\Program Files\Unisys\AB Suite 4.0\Bin

4. Type “ConfigureLog.exe /?”. This displays the complete usage of the utility.

The syntax of Configure Log Files command line utility is

ConfigureLog /C [<SYSTEM|DBREORG|DEPLOYMENT|RUNTIMEAPI>] [/E <true|false>][/LL <Debug|Info|Warning|Error>] [/L <location>] [/S <size>] [/N <number>] [/?]

5–2 3826 5856-005


Parameters


/C [<SYSTEM|DBREORG|DEPLOYMENT|RUNTIMEAPI>]

Specifies configuring the log information at the server level for the following log types:

• SYSTEM: The System log file applies to all runtime components. You can specify this option to configure or read the log information of an application transaction.

• DBREORG: The DBReorg log file is used each time an application is redeployed and the database is reorganized. You can specify this option to configure or read the log error messages during database reorganization.

• DEPLOYMENT: The Deployment log file is used each time deployment packages are deployed either automatically as part of the build process from Developer, or manually on the Runtime server.

• RUNTIMEAPI: The RuntimeAPI log file is used to capture the log details of Runtime API operations. By default, the file is stored within the Data folder.

Notes:

• This argument is mandatory.

• Apart from "/C" with option, if you do not pass any other arguments, it displays and lists the information from the log file. This information is read-only. For example: To display the log information that was set previously for the DBReorg log file, type

ConfigureLog.exe /C DBREORG

/E <true|false> You can set this argument to “true” to enable logging and vice versa.

Note: If you set this argument to false, the log level changes to "Disable" and no other log information changes.

For example: To enable the DBReorg log file, type

ConfigureLog.exe /C DBREORG /E true

/LL Error|Warning|Info|Debug

Specifies the level of logging information to be logged. By default, the log level is “Error”. The other log levels are Warning, Information, and Debug.

For example: To set the log level to “Information” for an enabled log , type

ConfigureLog.exe /C SYSTEM /LL INFO

3826 5856-005 5–3


/L <location> Specifies the location path of the log file. You should specify the absolute file path. The default location is the Data\public\log folder.

Notes:

• If you provide empty quotes, "", the location that is already set is considered.

• If you provide an invalid path, the error message“Unable to create directory. Enter a valid directory name.” appears.

For example: To modify only the location parameter of the DBReorg log file, type

ConfigureLog.exe /C DBREORG /L c:\a1

/S <Size> Specifies the maximum size of the log file in kB. This parameter value sets the value of the File Size.

Notes:

• The default file size displayed is the previous value available from the server. Although, you specify a value for File Size via this parameter, it is modified only at the next start of the server. This specification is applicable only for the “System” log type.

• Ensure that you enter a numeric value that is greater than zero and within the range of1-65,535.

For example: To modify only the File Size parameter of the System log file, type

ConfigureLog.exe /C SYSTEM /S 120

/N <number> Specifies the number of backup files that can be created once the log file has reached its maximum.

Note: Ensure that you enter a numeric value that is greater than zero and within the range of1-65,535.

For example: To modify only the number of backups of Deployment log file, type

ConfigureLog.exe /C DEPLOYMENT /N 6

/? Displays the command line syntax and arguments of the utility. If specified, a usage message appears, and the utility exits without starting the configuring process.


5–4 3826 5856-005


Troubleshooting—Error Messages• If you provide incorrect option for an argument, an error message specifying that

the argument is invalid along with the argument appears, along with the usage of the utility, for reference.

• If you pass an incorrect argument, an error message specifying that the input is invalid, along with the argument and the usage of the utility, for reference.

• If you do not pass any arguments to the command line utility, an error message specifying that the mandatory argument“/C” is missing appears, along with the usage of the utility, for reference.

• If you pass arguments values that are the same as the existing values, the error message “No configuration changes have been made” appears.

• If you pass an incorrect value for an argument, an error message specifying that the argument is invalid appears along with the argument and the usage of the utility, for reference.

• If you try to pass any argument when logging is disabled, a warning message specifying that logging is disabled and suggestion to enable logging to change the property values appears.

• If you pass any argument after logging is disabled, a warning message specifying that logging is disabled and suggestion to enable log to configure log files appears.

• If you pass valid parameters to run the utility, the message “Completed successfully” appears.

• If you pass duplicate arguments, the error message “Encountered duplicate arguments. Please address the duplicates before proceeding” appears.

Examples1. The following command configures log information of an application transaction

with the log file size as "1000" and number of backup files as "100" for an "Error" log level.

ConfigureLog.exe /C System /E true /LL ERROR /L c:\temp /S 1000 /N 100

2. The following command displays the log information of an application transaction that was set in the previous transaction.

ConfigureLog.exe /C System

Configure Protocol Adapters Utility (ConfigureAdapter.exe)

The Configure Protocol Adapters utility allows you to configure protocol adapters that can be used to connect external clients to applications. See “Using Protocol Adapters” for further details about external clients and AB Suite applications.

This utility is automatically installed with Agile Business Suite Runtime and is located in the AB Suite 4.0 installation directory. You can invoke the utility from the command line to configure protocol adapters.

Note:By default, a local administrator can use ConfigureAdapter.exe.

3826 5856-005 5–5


For non-administrative users to access this utility, the users must be member of the "Runtime Administrators" COM+ role of Runtime Manager application or member of the "AB Suite Runtime Administrators" user group.

To run ConfigureAdaptor.exe from a command line




The syntax of configure protocol adapters command line utility for RATL over TCP/IP and Hub is

ConfigureAdapter /TCPIP <[RATL|HUB]> [/P <portNumber>][/TO <Timeout in seconds>] [/STO <Session Timeout>] [/E <enable>] [/L <FilePath>] [/S <FileSize>] [/N <NumberOfBackups>] [/?]

Parameters


/TCPIP <[RATL|HUB]> Specifies configuring the TCPIP protocol adapters for the following protocols:

• RATL: You can specify this option to configure or read the protocol adapter information of RATLSocket.

• HUB: You can specify this option to configure or read the protocol adapter information of HubSocket.

Notes:

• This argument is mandatory. If you do not pass any option with this argument, the error message "Invalid argument" appears.

• Apart from "/TCPIP" with options, if you do not pass any other arguments, it displays and lists the TCPIP configuration details for RatlSocket or HubSocket. This information is read-only. For example: To display the TCPIP configuration details of RatlSocket that was set previously, type

ConfigureAdapter.exe /TCPIP RATL

/P <portNumber> You can specify the port number on which the RATLSocket or the HUBSocket listens.

Note: Ensure that you enter a numeric value within the range of port numbers of 1-65,535.

For example: To modify the port number for TCPIP over Hub, type

ConfigureAdapter.exe /TCPIP HUB /P 4000

5–6 3826 5856-005


/TO <Timeout in seconds> You can specify the time in seconds that the adapter waits before timing out.

/STO <Session Timeout> Specifies the time-out period assigned to the Session object of the application, in seconds.

For example: To modify the time out and session protection timeout for TCPIP over Hub, type

ConfigureAdapter.exe /TCPIP HUB /TO 10 /STO 100

/E <enable> You can set this argument to “true” to enable the packet logging for RATL over TCPIP and HUB, and vice versa.

For example: To enable packet logging for TCPIP over HUB, type

ConfigureAdapter.exe /TCPIP HUB /E true

/L <FilePath> Specifies the path to the location of the log file. You should specify the absolute file path.

Notes:

• If you provide an invalid file path, an error message appears.

• If you provide empty quotes, "", the location that is already set is considered.

• If you provide empty quotes with a space within the quotes, the error message "Unable to create directory. Enter a valid directory name." appears.

For example: To modify only the location parameter for RATL over TCPIP, type

ConfigureAdapter.exe /TCPIP RATL /L c:\temp\stg

/S <FileSize> Specifies the maximum size of the log file in kB.

Note: Ensure that you enter a numeric value that is greater than zero and within the range of 1-65,535.

For example: To modify only the File Size parameter for RATL over TCPIP, type

ConfigureAdapter.exe /TCPIP RATL /S 100

/N <NumberOfBackups> Specifies the number of backup files that can be created once the log file has reached its maximum.

Note: Ensure that you enter a numeric value that is greater than zero and within the range of 1-65,535.

For example: To modify only the number of backups parameter for RATL over TCPIP, type

ConfigureAdapter.exe /TCPIP RATL /N 6

/TCPIP /? Displays the command line syntax and options of the utility for RATL over TCPIP and Hub. If specified, a usage message appears, and the utility exits without starting the configuring process.


3826 5856-005 5–7


The syntax of Configure Protocol Adapters command line utility for RATL over MSMQ and SOAP over MSMQ is

ConfigureAdapter /MSMQ <[RATL|SOAP]> /SM <MSMQ Server Machine>[/E <enable>] [/L <FilePath>] [/S <FileSize>] [/N <NumberOfBackups>] [?]

Parameters


/MSMQ <[RATL|SOAP]> Specifies configuring the MSMQ protocol adapters for the following protocols:

• RATL: You can specify this option to configure or read the protocol adapter information for RATL over MSMQ.

• SOAP: You can specify this option to configure or read the protocol adapter information for SOAP over MSMQ.

Notes:

• This argument is mandatory. If you do not pass any option with this argument, the error message "Invalid argument" appearss.

• Apart from "/MSMQ" with options, if you do not pass any other arguments, it displays and lists the MSMQ configuration details for RATLQueue and SoapQueue. This information is read-only. For example: To display the MSMQ configuration details of RATL over MSMQ that was set previously, type

ConfigureAdapter.exe /MSMQ RATL

/SM <MSMQ Server Machine>

Specifies the name of the machine on which the required MSMQ server is located.

Note: If you specify a wrong machine name, an error message appears.

For example: To modify only the server machine for RATL over MSMQ, type

ConfigureAdapter.exe /MSMQ RATL /SM <ServerName>

/E <enable> You can set this argument to “true” to enable the packet logging for RATL over MSMQ and SOAP over MSMQ and vice versa.

For example: To enable packet logging for RATL over MSMQ, type

ConfigureAdapter.exe /MSMQ RATL /E true

5–8 3826 5856-005


Troubleshooting—Error Messages• If you provide incorrect option for an argument, an error message appears

specifying that the argument is invalid appears, along with the argument and the usage of the utility, for reference.

• If you pass an incorrect command, the error message “Invalid input specified” appears.

• If you pass an incorrect argument, an error message specifying that the input is invalid appears along with the argument and the usage of the utility, for reference.

• If you pass any incorrect values for an argument, an error message specifying that the argument is invalid appears, along with the argument and the usage of the utility, for reference.

/L <FilePath> Specifies the location of the log file. You should specify the absolute file path.

Notes:

• If you provide an invalid file path, an error message appears.

• If you provide empty quotes, "", the location that was already set is considered.

• If you provide empty quotes with a space within the quotes, the error message "Unable to create directory. Enter a valid directory name." appears.

For example: To modify only the location parameter for RATL over MSMQ, type

ConfigureAdapter.exe /MSMQ RATL /L c:\temp\stg

/S <FileSize> Specifies the maximum size of the log file in kB.

Note: Ensure that you enter a numeric value that is greater than zero and within the range of1-65,535.

For example: To modify only the File Size parameter for RATL over MSMQ, type

ConfigureAdapter.exe /MSMQ RATL /S 1000

/N <NumberOfBackups> Specifies the number of backup files that can be created once the log file has reached its maximum.

Note: Ensure that you enter a numeric value that is greater than zero and from 1-65,535.

For example: To modify only the number of backups parameter for SOAP over MSMQ, type

ConfigureAdapter.exe /MSMQ SOAP /N 1

/MSMQ /? Displays the command line syntax and options of the utility for RATL over MSMQ and SOAP over MSMQ. If specified, a usage message appears, and the utility exits without starting the configuring process.


3826 5856-005 5–9


• If you pass argument values that are same as the existing values, the error message appears “No configuration changes have been made” appears.

• If you try to pass any argument when logging is disabled, a warning message specifying that logging is disabled and suggestion to enable logging to change the property values appears.

• If you pass any argument after logging is disabled, an error message specifying that no configuration changes have been made and suggestion to enable log appears.

• If you pass valid arguments to run the utility, the message “Successfully updated the configuration” appears.


Example

The following command displays the configuration details of RATL over MSMQ that was set in the previous transaction:

ConfigureAdapter.exe /MSMQ RATL

AB Suite System Deployment Utility (DeployPackage.exe)

The Deployment command line utility allows you to deploy an AB Suite generated package to a local or remote server. This enables you to

• Install an MSI package containing a system and/or report to a server

• Install a CAB package containing a single report to a server

See “Transferring a System” for further details on deploying an application to a Runtime machine.

This utility is automatically installed with Agile Business Suite Runtime and is located in the AB Suite 4.0 installation directory. You can invoke the utility directly from the command line.

Note: You must have local administrator privileges to use DeployPackage.exe

To run DeployPackage.exe from a command line




4. Type “DeployPackage.exe /?”. This displays the complete usage of the utility.

5–10 3826 5856-005


The command line syntax of the AB Suite system deployment utility is

Deploy /L <DeployPackagePath> /U <UserName>/P <Password> [/DN <DeploymentName>] [/PC <true|false>] [/RDB <true|false>] [/BDB <true|false>] [/TSN <TargetServerName>] [/TDBR < TargetDatabaseRegistration>] [/TDBN <TargetDatabaseName>] [/TP <TargetPath>] [/TS <TargetSystemName>] [/TW <TargetWinformPath>] [/?]

Parameters


/L <DeployPackagePath> Specifies the MSI package or CAB files to be deployed along with the complete path. You should specify the absolute file path.

Notes:


• If you do not pass any option with this argument, the error message "Error: Missing value for required parameter/s: DeployPackagePath" appears.

• If you provide an incorrect value or enter spaces as a value for this argument, an error message specifying that the package file cannot be found along with the package file location appears. You can also provide the MSI package name within double quotes.

For example: If you try to deploy an AB Suite system with the corresponding Application User account details without providing the deploy package path, you receive an error message.

DeployPackage /U Appuser /P Password

3826 5856-005 5–11


/U <UserName> Specifies the name of the user account that is defined as the Application User. You can provide the user name as Domain\user for a remote server or a period (.) as the domain, if the target is the local server.

Notes:


• If you do not pass any option with this argument, the error message "Error: Missing value for required parameter/s: UserName" appears.

• If you pass an incorrect user account name, the error message "UserName/Password details are incorrect" appears.

For example:

• When you deploy an MSI package to a local server without specifying the Application User details, an error message appears.

DeployPackage /L C:\TEMP\stagingarea\sampapi.msi /P Password

• To deploy an MSI package to a remote server by specifying the domain name, type

DeployPackage /L C:\TEMP\stagingarea\NGENSampleDeploy.msi /U Unisys\Appuser /P Password

/P <Password> Specifies the password for the Application User.

Notes:


• If you do not pass any option with this argument, the error message "Error: Missing value for required parameter/s: Password" appears.

/DN <DeploymentName> Specifies the folder on the target machine in which the package (MSI or CAB) is saved. The default value is the current package name.

/PC <true|false> You can set the argument Deploy Progress Callback to “true” to receive the progress messages and vice versa. The default value is true.

Note: If you set this argument to “false”, you will not receive any progress messages. For example: Deploying an MSI package to a local server by setting the /PC argument to false does not return any progress message.

DeployPackage /L C:\TEMP\stagingarea\NGENSampleDeploy.msi/U Appuser /P Password /PC false


5–12 3826 5856-005


/RDB <true|false> You can set this argument to “true” so that the existing application database is not reorganized when redeploying to the local server. The default value is true. If this argument is false, the database is reorganized.

For example: To reorganize an application database while deploying an MSI package to a local server, type

DeployPackage /L C:\TEMP\stagingarea\NGENSampleDeploy.msi/U Appuser /P Password /RDB false

/BDB <true|false> You can set this argument to true to have a backup of the existing database. The default value is false.

Note: Since reorganizing a large database may take time depending on the size of the database, ensure that you back up the database before reorganizing it.

For example: To back up a database while deploying an MSI package to a local server, type

DeployPackage /L C:\TEMP\stagingarea\NGENSampleDeploy.msi/U Appuser /P Password /BDB true

/TSN <TargetServerName> Specifies the name of the Runtime server to which you want to deploy. The default value is “localhost”, which redeploys to the local server.

Note: If you do not pass any value for this argument, the package is deployed to the local server.

/TDBR <TargetDatabaseRegistration>

Specifies the name of the database server registration of the local or remote server to which you want to deploy.

Note: If target database registration is not provided, the utility uses the built-in values.

For example: To deploy an MSI package to a specified target database server registration, type

DeployPackage /L C:\TEMP\stagingarea\NGENSampleDeploy.msi/U Appuser /P Password /TDBR UNIREG

/TDBN <TargetDatabaseName>

Specifies the name of the database of the local or remote server to which you want to deploy.

Note: If you do not pass any value for this argument, the utility uses the built-in values.

For example: To deploy an MSI package to a specified target database, type

DeployPackage /L C:\TEMP\stagingarea\NGENSampleDeploy.msi/U Appuser /P Password /TDBN UNIDB

/TP <TargetPath> Specifies the path of the folder in which the deployed application files are stored. If you do not provide any value for this argument, the utility uses the path defined when the package was originally built.

/TS <TargetSystemName> Specifies the deployed system name of the target server.

If you do not provide any value for this argument, the utility uses the built-in name.


3826 5856-005 5–13


Troubleshooting—Error Messages• If database server registration does not exist on the target server, an error

message specifying that the Database Server Registration does not exist appears along with the database server name.

• If database does not exist on the target server, an error message specifying that the Database does not exist appears along with the database name.

• If you provide incorrect option for an argument, an error message specifying that the argument is invalid appears along with the usage of the utility, for reference.

• If you pass an incorrect command, the error message “Invalid input specified” appears.

• If you pass an incorrect argument, an error message specifying that the input is invalid appears, along with the argument and the usage of the utility, for reference.


• If you pass valid arguments to run the utility, the message "Operation Completed successfully" appears.

• If any failure is detected, the error message "Operation Completed with errors" appears.

Example

The following command deploys an MSI package for Appuser.

DeployPackage /L C:\TEMP\stagingarea\sampapi.msi /U Appuser /P Password

Deployment Package Manager Utility (ManagePackage.exe)

The Deployment Package Manager (DPM) command line utility allows you to create a clone of a builder generated package (.msi or .cab). In addition, DPM provides an option to

• Upgrade the cloned MSI

• Create partial MSIs to generate new or updated report files for the cloned system

/TW <TargetWinformPath> Specifies the path of the folder in which the Winform files should be stored. If you do not provide any value for this argument, the path defined when the package was originally built is used.

/? Displays the command line syntax and arguments of the utility.

If specified, a usage message appears and the utility exits without starting the deployment process.


5–14 3826 5856-005


This utility is automatically installed with Agile Business Suite Runtime and is located in the AB Suite 4.0 installation directory. Refer to the Prerequisites for DPM for details about the prerequisite information. You can invoke the utility directly from the command line.

Note: You must have local administrator privileges to use ManagePackage.exe.

To run ManagePackage.exe from a command line




4. Type “ManagePackage.exe /?”. This displays the complete usage of the utility along with the description of all the arguments.

Cloning an Instance

You should clone an Instance so that two or more instances of the same system can coexist on a machine by changing a few properties. By changing the properties, the second instance of the system is treated as a new system with a new COM+ application.

The command line syntax of creating a clone of a builder generated package is

ManagePackage /C /BP <SourcePackageLocation> [/TP <TargetPackagePath>] [/DB <DBName>] [/DBS <DBSchema>] [/DBR <DBServerRegistration>] [/IN <InstanceName>] [/PD <PackageDir>] [/O <true|false]>] [/?]

Parameters


/C Specifies whether you want to create a clone of the builder generated MSI package or CAB files.

Notes:


• If you do not pass this argument, the error message "Mandatory Input missing or Invalid: /C /P /U", including the complete usage of the utility appears.

3826 5856-005 5–15


/BP <SourcePackageLocation>

Specifies the path to builder generated package (.msi or .cab). You can specify the absolute path, relative file path, or network path (Uniform Naming Convention).

Note: This argument is mandatory and allows the Windows installer to determine the existing builder generated MSI or cab file so that the new system can coexist mutually by changing a few properties. If you do not pass any value with this argument, an error message specifying that the input is invalid, including the argument and the usage of the utility appears, for reference.

For example:

• To create a clone of an MSI package, type

ManagePackage /C /BP C:\GeneratedFiles\BuilderGeneratedPackage.msi

• To create a clone using the relative path for a builder generated package located at C:\GeneratedFiles\, type

ManagePackage/C /BP ..\BuilderGeneratedPackage.msi• To create a clone of an MSI package using the Uniform

Naming convention (UNC) syntax, type

ManagePackage /C /BP \\network\my folder\ BuilderGeneratedPackage.msi

• When you create a clone of the MSI package without specifying the path to the builder generated package, the error message “Invalid input specified" appears. For instance,

ManagePackage /C /BP /TP C:\ClonedPackages• If you pass empty quotes, "" or an incorrect path, the error

message “Invalid builder generated package provided." appears. For instance,

ManagePackage /C /BP ""

/TP <TargetPackagePath> Specifies the absolute target path where the DPM generated package should be copied.

Note: The default path is "My Documents".

/DB <DBName> Specifies the target database name of the DPM generated package.

Note: The default value is the Instance name appended with "DB".

For example: If Instance name is Sample, the DBName is SampleDB.

/DBS <DBSchema> Specifies the Database schema name of the DPM generated MSI package.

Note: The default value is the Instance name.

For example: If Instance name is "Sample", the DBSchema is "Sample".

/DBR <DBServerRegistration>

Specifies the Database server registration name.

Note: The default value is the builder generated value.


5–16 3826 5856-005


Example

The following command clones an instance:

ManagePackage /C /BP C:\TEMP\stagingarea\Sample.msi /TP C:\ClonedPackages /DB CLONESAMPLEDB /DBS CLONEDSAMPLESCHEMA /DBR SQLSERVER /IN SAMPLECLONE /PD C:\ABSuite\Systems\SampleClone /O True

Updating an Instance

You can upgrade a cloned MSI by updating few parameters. The command line syntax of updating an Instance is

ManagePackage /U /BP <SourcePackageLocation> /DP <DPMGeneratedPackage> [/TP <TargetPackagePath>] [/DB <DBName>]

/IN <InstanceName> Specifies the Instance name of the new .msi or .cab package name.

Note: This argument allows the Windows installer to determine the name of the cloned system. The default value is the builder generated value appended with "Clone".

For example: If the existing Instance name is "Sample", the InstanceName of the newly created MSI package is "SampleClone".

/PD <PackageDir> Specifies the Package installation directory, which is the absolute path to the builder generated instance package.

Note: The default value is the builder generated value appended with "Clone".

For example: If the existing PackageInstallationDirectory is

"C:\ABSuite\Systems\Sample", the PackageInstallationDirectory of the newly created MSI package is "C:\ABSuite\Systems\SampleClone"

To clone an MSI package for a specified Package installation directory, type

ManagePackage /C /BP C:\TEMP\stagingarea\Sample.msi /PD C:\ABSuite\Systems\SampleClone

/O <true|false> You can set this argument to true to overwrite the existing OutPath package. The default value is false.

Notes:

• If no value is specified for this argument or option is false and target path is available, the warning message “Target Path is already available” appears.

• If a package with the same name exists in the target path, an error message specifying that the package already exists in the path appears.

/C /? Displays command line syntax and options of the utility for cloning an instance. If specified, a usage message displays, and the utility exits without starting the cloning process.


3826 5856-005 5–17


[/DBS <DBSchema>] [/DBR <DBServerRegistration>] [/PD <PackageDir>] [/O <true|false]>] [/?]

Parameters


/U Specifies whether you want to update the package parameters of a cloned MSI.

Notes:





Note: This argument is mandatory and allows the Windows installer to determine the existing MSI file. If you do not pass any value with this argument, an error message appears specifying that the input is invalid, including the argument and the usage of the utility, appears for reference.

For example:

• When you update an instance without specifying the path to the builder generated package, the error message "Mandatory Input Missing or Invalid: /U /BP /DP", including the usage of the utility appears, for reference. For instance,

ManagePackage /U /BP /DP C:\ClonedPackages\SampleClone.msi

• If you pass empty quotes, "", or an incorrect path, the error message “Invalid builder generated package provided." appears. For instance,

ManagePackage.exe /U /BP "" /DP C:\GeneratedFiles\DPMGeneratedPackage.msi

5–18 3826 5856-005


/DP <DPMGeneratedPackage>

Specifies the path to the DPM generated instance package. You can specify the absolute path, relative file path, or network path (Uniform Naming Convention).

Note: This argument is mandatory and enables the Windows installer to determine the location of the cloned MSI. If you do not pass any value with this argument, the error message “Mandatory Input Missing or Invalid: /U /BP /DP", including the usage of the utility appears, for reference.

For example:

• To update a cloned MSI package, type

ManagePackage /U /BP C:\GeneratedFiles\BuilderGeneratedPackage.msi /DP C:\GeneratedFiles\DPMGeneratedPackage.msi

• If you pass empty quotes, "", or an incorrect path, the error message “Invalid instance generated package provided." appears. For instance,

ManagePackage.exe /U /BP "C:\TEMP\StagingArea\NGENSampDepClone.msi" /DP ""

/TP <TargetPackagePath> Specifies the absolute path to the output package where the upgraded MSI package is copied.


/DB <DBName> Specifies the updated database name.

For example: To update the DBName for DPM generated package, type

ManagePackage /U /BP C:\TEMP\stagingarea\Sample.msi /DP C:\ClonedPackages\SampleClone.msi /TP C:\ClonedPackages /DB CLONESAMPLEDDB

/DBS <DBSchema> Specifies the updated Database schema name.

/DBR <DBServerRegistration>

Specifies the updated Database server registration name.

/PD <PackageDir> Specifies the updated Package installation directory, which is the absolute path to the builder generated instance package.

/O <true|alse> You can set this argument to true to overwrite the target path package. The default value is false.

Notes:

• If you do not specify any value for this argument or if the option is false and target path is available, the warning message “Target Path is already available” appears.


/U /? Displays the command line syntax and options of the utility for updating an instance. If specified, a usage message appears, and the utility exits without starting the update process.


3826 5856-005 5–19


Example

The following command upgrades an existing instance.

ManagePackage /U /BP C:\TEMP\stagingarea\Sample.msi /DP C:\ClonedPackages\SampleClone.msi /TP C:\ClonedPackages /DB CLONESAMPLEDDB /DBR SQLSERVER /DBS CLONEDSAMPLESCHEMA /PD C:\ABSuite\Systems\SampleClone /O True

Creating Partial Clone for an MSI or a Cab File

You can create partial MSIs or cab files to generate new or updated report files for a cloned system, such as Reports cab files. The command line syntax of creating a partial clone is

ManagePackage /P /BP <SourcePackageLocation> /DP <DPMGeneratedPackageLocation> [/TP <TargetPackagePath>] [/IN <InstanceName>] [/O <true|false]>] [/?]

Parameters


/P Specifies whether you want to create partial MSI of a cloned MSI.

Notes:





Note: This argument is mandatory and allows the Windows installer to determine the original partial MSI file. If you do not pass any value with this argument, an error message specifying that the input is invalid, including the argument and the usage of the utility appears, for reference.

For example:

• When you create a partial clone without specifying the path to the builder generated package, an error message appears. For instance,

ManagePackage /P /BP /DP C:\ClonedPackages\SampleClone.msi

• If you pass empty quotes, "", or an incorrect path, the error message “Invalid builder generated package provided.” appears. For instance,

ManagePackage.exe /P /BP ""

5–20 3826 5856-005


Examples

1. The following command creates partial clone for an MSI.

/DP <DPMGeneratedPackageLocation>

Specifies the path to the DPM generated instance package. You can specify the absolute path, relative file path, or network path (Uniform Naming Convention).

Note: This argument is mandatory and enables the Windows installer to determine the location of the DPM generated partial MSI file. If you do not pass any value with this argument, the error message “Mandatory Input Missing or Invalid: /P /BP /DP", including the usage of the utility appears, for reference.

For example:

• To create a partial clone, type

DPM /P /BP C:\GeneratedFiles\BuilderGeneratedPackage.msi /DP C:\GeneratedFiles\DPMGeneratedPackage.msi

• If you pass empty quotes, "", or an incorrect path, the error message “Invalid instance generated package provided." appears. For instance,

DPM.exe /P /BP "C:\TEMP\StagingArea\NGENSampDepClone.msi" /DP ""

/TP <TargetPackagePath> Specifies the absolute path to the output package where the upgraded MSI package is copied.


/IN <InstanceName> Specifies the Instance name of the new .msi or .cab package name.

Note: This argument allows the Windows installer to determine the name of the partial MSI file. The default value is the existing Instance name appended with "ClonePartial".

For example, If existing Instance name is "Sample", the InstanceName of the newly created partial MSI package is "SampleClonePartial".

/O <true|false> You can set this argument to true to overwrite the OutPath package. The default value is false.

Notes:

• If you do not specify any value for this argument or if the option is false and the target path is available, the warning message “Target Path is already available” appears.


/P /? Displays the command line syntax and options of the utility for updating an instance. If specified, a usage message appears, and the utility exits without starting the update process.


3826 5856-005 5–21


ManagePackage /P /BP C:\TEMP\stagingarea\SampleReports.msi /DP C:\ClonedPackages\SAMPLEClone.msi /TP C:\ClonedPackages /IN SAMPLECloneReports /O TRUE

2. The following command creates partial clone for a CAB file.ManagePackage /P /BP C:\TEMP\stagingarea\SAMPLE_Reports_AGEDSTOCK.cab /DP "C:\ClonedPackages\SAMPLEClone.msi" /TP C:\ClonedPackages /IN AGEDSTOCK /O True

Troubleshooting—Error Messages• If you provide an incorrect option for an argument, an error message specifying

that the argument is invalid appears, along with the argument and the usage of the utility, for reference.

• If you pass an incorrect command, the error message "Invalid input specified" appears.


• If you do not pass the mandatory arguments, an error message specifying that the mandatory input is missing or invalid appears, along with the mandatory arguments and the usage of the utility, for reference.

• If you pass any incorrect values for the mandatory arguments, an error message specifying that the details are incorrect appears, along with the argument and the usage of the utility, for reference.

• If you pass an empty value for a mandatory argument, an error message specifying that the input is invalid appears, along with the argument and the usage of the utility, for reference.

• If you pass valid arguments to run the utility, the message "Create Package completed successfully" appears.

Runtime Operations Utility (AdminSystem.exe)

The runtime operations utility allows you to perform the runtime system and report administration operations.

This utility is automatically installed with Agile Business Suite Runtime and is located in the AB Suite 4.0 installation directory. You can invoke the utility from the command line. By default, a local administrator can use the AdminSystem.exe. For non-administrative users, the use of AdminSystem.exe is restricted to users with the required security privileges described in the subsequent subsections.

To run AdminSystem.exe from a command line




5–22 3826 5856-005


4. Type “AdminSystem.exe /?”. This displays the complete usage of the utility.

Application Administration Commands

The AdminSystem.exe command line utility replaces most of the functionalities available in the existing Admin.exe and includes system administration capabilities in accordance with the rest of the new Runtime API administration interface features. The Admin.exe will be deprecated and removed from the future releases. The use of the administration functionalities is restricted to users with the required security privileges. The security for administration commands is controlled by using the COM+ roles. The required roles for each command are listed in the following table along with the command descriptions.

Following is the parameter list of Runtime operations utility for the application administration commands through AdminSystem.exe.

Argument Description Security Privileges

/S Displaying the status of an application

Users must be a member of one of the following COM+ roles to access this administrative function:



/CLR Clearing User Session Users should be a member of the Application Administrators to access this administrative function.

/DIS Disabling an Application Users must be a member of one of the following COM+ roles to access this administrative function:



/ENA Enabling an Application Users must be a member of one of the following COM+ roles to access this administrative function:



/HAM Setting or displaying the High Account Month (HAM)


• Accountants


3826 5856-005 5–23


In all the application administration commands, the /S argument is mandatory. This argument specifies a valid system name. Refer to “Displaying the Status of an Application” for complete information about the /S argument.

Displaying the Status of an Application

The syntax of the runtime operations utility to display the status of an application is

AdminSystem /S <SystemName>

If you pass valid parameters, a message specifying the status of a specified system appears. The valid system status messages are

• Enabled and Running

• Disabled and Running

• Enabled and Stopped

/HUB Displaying, Enabling, or Disabling external automatic entries (HUB)




/LAM Setting or displaying the Low Account Month (LAM)


• Accountants


/LIS Listing ispecs in an application




/SMG Sending a short message to a user


• Message Senders


/STO Stopping an Application Users must be a member of one of the following COM+ roles to access this administrative function:



/WHO Displaying the list of current users or active stations

Users should be a member of the Application Administrators to access this administrative function.


5–24 3826 5856-005


• Disabled and Stopped

Parameters

Clearing a User Session

The syntax of clearing a user session from the runtime application is

AdminSystem /S <SystemName> /CLR <UserName/SessionId>

If you pass valid parameters to clear a session, the message "The session has been successfully cleared." appears.

Parameters


/S <SystemName> Specifies that a valid system name must be passed as a parameter.

Notes:


• The system name is case-sensitive.

• If you do not pass any value, the error message "Provide a valid Runtime System Name" appears, along with the usage of the utility.

• If you provide empty quotes, " ", or an invalid system name, an error message specifying that the system is not available appears.

For example:

• If you provide an incorrect system name, an error message appears.

AdminSystem /S Sa• To view the system status, type

AdminSystem /S SampleThe message "Sample Status: Enabled and Running" appears.

/S <SystemName> /? Displays the usage of the utility and the utility exits without starting the process.


/S <SystemName> Specifies that a valid system name must be passed as a parameter. Refer to “Displaying the Status of an Application” for complete description of the /S argument.

3826 5856-005 5–25


Setting or Displaying Low Account Month (LAM)

The syntax of setting or displaying the Low Account Month (LAM) for a running application is

AdminSystem /S <SystemName> /LAM <AccountMonth>

The Low Account Month prevents an application from accepting any transactions that have an earlier date (specified by the built-in attribute ActMth value). The default value is the year and month that the application was initiated.

Any valid Low Account Month remains in effect until a new one is specified. If you pass valid parameters to run the utility, the message "Updated account month" appears.

Parameters

/CLR <UserName/SessionId>

Specifies that a valid system name must be passed as a parameter.

Notes:


• You must sign in to a user session on the system.

• If you do not pass any value or pass an invalid option, an error message specifying that the input is invalid appears.

• You can obtain the session number of an anonymous session by using the utility with the /WHO parameter.

For example: To clear a session, type

AdminSystem /S Sample /CLR Admin.exeThe message specifying that the session has been successfully cleared appears.

/S <SystemName> /CLR /?

Displays the command line syntax and its usage for clearing a user session, and the utility exits without starting the process.


/S <SystemName> Specifies that a valid system name must be passed as a parameter. Refer to “Displaying the Status of an Application” for a complete description of the /S argument.


5–26 3826 5856-005


Setting or Displaying High Account Month (HAM)

The syntax of setting and displaying the High Account Month (HAM) for a running application is

AdminSystem /S <SystemName> /HAM <AccountMonth>

The HAM value prevents the application from accepting any transactions that have a later date (specified by the built-in attribute ActMth). The default value is the year and month that the application was initiated.

Any valid HAM value remains in effect until a new one is specified, or until the application date becomes greater than the current value, at which time its value is increased automatically. If you pass valid parameters to run the utility, the message "Updated account month" appears.

Parameters

/LAM <AccountMonth>

Specifies the year and month in the format, yymm. If no value is passed, the utility displays both the current HAM and LAM values.

Notes:


• A Low Account Month (LAM) value may exceed the High Account Month (HAM) value to allow for a change of century value.

• If you pass a value not confirming to the yymm format or a value earlier than the ActMth value, the error message "Invalid account month value" appears.

• You can obtain the session number of an anonymous session by using the utility with the /WHO parameter.

For example: To display the current LAM value for a running application, type

AdminSystem /S Sample /LAM

/S <SystemName> /LAM /?

Displays the command line syntax and its usage for displaying the LAM value, and the utility exits without starting the process.


/S <SystemName> Specifies that a valid system name must be passed as a parameter. Refer to “Displaying the Status of an Application” for a complete description about the /S argument.


3826 5856-005 5–27


Sending a Short Message

The syntax of sending a short message to other users logged on to an application is

AdminSystem /S <SystemName> /SMG /STN <Station> /MSG <message>

If you pass valid parameters to run the utility, the message "Sent the message" appears.

Parameters

/HAM <AccountMonth>

Specifies the year and month in the format, yymm. If no value is passed, the utility displays both the current HAM and LAM values.

Notes:


• A High Account Month (HAM) value may be less than the Low Account Month value (LAM), to allow for change of century value.

• If you pass a value not confirming to the yymm format or a value earlier than the ActMth value, the error message "Invalid account month value" appears.

For example: To set the HAM value for a running application, type

AdminSystem /S Sample /HAM 1402The message "Updated account month" appears.

/S <SystemName> /HAM /?

Displays the command line syntax and its usage for displaying the HAM value, and the utility exits without starting the process.



/SMG Specifies that a short message needs to be sent to other users.

/STN <Station> Specifies a user account, terminal name, or ALL (for all users of the application).

Note: This argument is mandatory.

/MSG <message> Specifies the text to be displayed on the status line of destination terminals.

For example: To send a short message to another user, type

AdminSystem /S Sample /SMG /STN Sample.exe /MSG HelloThe confirmation "Sent the message" appears.

/S <SystemName> /SMG /?

Displays the command line syntax and its usage for sending a short message, and the utility exits without starting the process..


5–28 3826 5856-005


Listing Unique Ispecs

The syntax of listing the unique ispecs in an application is

AdminSystem /S <SystemName> /LIS

The list displays the alternate names of ispecs and flags the fire-up ispec. If you pass valid parameters to run the utility, the message "The following ispecs are available in the specified system", along with the list of ispecs, appears.

Parameters

Displaying a List of Current Users

The syntax of listing the current users logged into the application is

AdminSystem /S <SystemName> /WHO

The list displays the currently connected users of the system. The information returned includes a list of users logged into the system. If you pass valid parameters to run the utility, a list of stations connected to a runtime system appears; else, the message "No users are logged in" appears.

Parameters



/LIS You can specify this argument to list the unique ispecs.

Note: This argument is mandatory.

For example: To list the ispecs, type

AdminSystem /S Sample /LIS

/S <SystemName> /LIS /?

Displays the command line syntax and its usage for displaying a list of unique ispecs, and the utility exits without starting the listing process.



3826 5856-005 5–29


Stopping an Application

The syntax of the runtime operations utility for stopping an application is

AdminSystem /S <SystemName> /STO <[disable]>

If you pass valid parameters to stop and disable an application, the message “System stopped and disabled” appears. If you do not pass the "disable" argument, the message "System Stopped" appears.

Parameters

Disabling an Application

The syntax of the runtime operations utility for disabling an application is

/WHO You can specify this argument to list the currently connected users of the system.

Notes:

• You must sign in to a user session on the system.


For example: To list the current users, type

AdminSystem /S Sample /WHO

/S <SystemName> /WHO /?

Displays the command line syntax and its usage for listing the current users, and the utility exits without starting the listing process.



/STO [disable] You can set this argument to “disable” to stop and disable an application. This prevents any users from initiating it again and all processes are stopped.

Notes:

• If you do not pass any option or pass an invalid option, the system is stopped.

• If you try to stop an already stopped system, the warning message "System already stopped" appears.

For example: To stop and disable an application, type

ConsoleAdmin /S Sample /STO disable

/S <SystemName> /STO /? Displays the usage of the utility and the utility exits without starting the process.


5–30 3826 5856-005


AdminSystem /S <SystemName> /DIS

If you pass valid parameters to run the utility, the message “System disabled” appears.

Parameters

Enabling an Application

The syntax of the runtime operations utility for enabling an application is

AdminSystem /S <SystemName> /ENA

If you pass valid parameters to run the utility, the message “System enabled” appears.

Parameters

Displaying, Enabling, or Disabling HUB

The syntax of the runtime operations utility for enabling and disabling external automatic entries (HUB) is

AdminSystem /S <SystemName> /HUB <[Start|Stop]>

If you pass valid parameters to run the utility, the message “HUB enabled” or "HUB disabled" appears.



/DIS You can set this argument to disable an application. This prevents any users from initiating the application that is disabled and you can attempt to stop a disabled application through the /STO parameter after disabling the application.

For example: to disable an application, type

AdminSystem /S Sample /DIS

/S <SystemName> /DIS /? Displays the usage of the command line utility and the utility exits without starting the process.



/ENA You can set this argument to enable an application.

For example: to enable an application, type

AdminSystem /S Sample /ENA

/S <SystemName> /ENA /? Displays the usage of the utility and the utility exits without starting the process.

3826 5856-005 5–31


Parameters



/HUB <[Start|Stop]> Specifies the following options for HUB Listener service to enable or disable the HUB:

• Start: You can specify this option to start the HUB Listener service.

• Stop: You can specify this option to stop the HUB Listener service.

Notes:

• If a system is disabled, the error message "The application has been disabled" appears and thereby the HUB cannot be enabled.

• If you do not pass any options with "HUB", it displays the status of the HUB for a system. This information is read-only.

For example:

• To enable external automatic entries (HUB), type

AdminSystem /S Sample /HUB Start• To disable the HUB by stopping the HUB Listener service,

type

AdminSystem /S Sample /HUB Stop• To check the status of the HUB, type

AdminSystem /S Sample /HUB

/S <SystemName> /HUB /? Displays the usage of the utility and the utility exits without starting the process.

5–32 3826 5856-005


Report Administration Commands

Following is the parameter list of Runtime operations utility for the report administration commands along with the required roles for each command.


/REP Displaying information about the reports



• Report Monitors





/DEL Deleting Report Recovery Information







/RUN Running or Recovering a Report


• Report Runners



/STR Stopping a Report Users must be a member of one of the following COM+ roles to access this administrative function:





3826 5856-005 5–33


In all the report administration commands, the /S argument is mandatory. This argument specifies a valid system name. Additionally, the argument that specifies the report name is a mandatory argument in most of the report administration commands. Refer to “Displaying the Status of an Application” for complete information about the /S argument. Refer to “Running or Recovering a Report” for more information about the report name argument.

Displaying the Status of Reports

The syntax of displaying information about the running reports and reports waiting for recovery in an application is

AdminSystem /S <SystemName> /REP

The information displayed includes

• Username: User account

• Report Name: Name of the report

• Process ID: Process ID of the report

• Report Status: Status of the report

• ID: The Session ID / recovery key of the report

/TER Terminating an Active Report Users must be a member of one of the following COM+ roles to access this administrative function:





/WUP Reactivate a report suspended by a previous Sleep or CriticalPointLogic







• Report Runners


5–34 3826 5856-005


Parameters

Running or Recovering a Report

The syntax of the runtime operations utility to initiate a report or to recover a report with recovery information is

AdminSystem /S <SystemName> /RUN <ReportName> [/REC key] [/DEV] [/TR] [/LA <lang>] [/PA <param>]

Parameters



/REP You can specify this argument to display information about the reports in an application.

Note: A key value for recovery information is displayed for each report awaiting recovery. You can use this key value with the /DEL parameter of the command to remove recovery information, or with the /RUN parameter of the command to run a report that is awaiting recovery.

For example: To display information about the running reports and reports awaiting recovery, type

AdminSystem /S Sample /REP RECOVER

/S <SystemName> /REP /? Displays the command line syntax and its usage for displaying the report information, and the utility exits without starting the process.



3826 5856-005 5–35


/RUN <ReportName> Specifies the name of a report.

Notes:


• If you do not pass any value, the error message “Provide a valid Report Name”, along with the usage of the utility appears.

• If the specified report name does not exist, an error message specifying that the report does not exist and the name should be checked appears.

• If you provide empty quotes, " ", or an invalid report name, an error message specifying that the Report is not available appears.

• If a system is already disabled, the error message "The application has been disabled" appears.

For example: To initiate a report with a valid report name and system name, type

AdminSystem /S Sample /RUN SampleReport

/REC key Specifies a unique key value for the recovery information, which is the ProcessId of a recoverable report.

For example: To run a report that is awaiting recovery, type

AdminSystem /S Sample /RUN SampleReport /REC 43

/DEV Specifies a device type that overrides a device type set for a report.

The valid device type options are

• LP – Piped to the command defined by the LP alias

• TP – Piped to the command defined by an alias

• EX – Output to an alias

• VD – Output to a temporary file (the name is displayed when the report is initiated)

• DI – Direct output to an alias

• DP – Direct output to Enterprise Output Manager

Note: If you provide invalid device type options, an error message appears.

/TR Specifies whether tracing is enabled for a report. The default value is "off".

For example: To run a report with tracing enabled, type

AdminSystem /S Sample /RUN SampleReport /TR on

/LA <lang> Specifies the language defined for an application

Note: While setting the language, you should use the language id, such as 1033 for English.


5–36 3826 5856-005


Stopping a Report

The syntax of the runtime operations utility for stopping a report is

AdminSystem /S <SystemName> /STR <ReportName> [/MIX <ProcessId>]

You can use the command to stop reports that are either waiting for input, or contain the following logic commands:

• Sleep

• CriticalPoint with the Sleep command option

This command has no effect on a running report that is not sleeping. If you pass valid parameters to run the utility, the message "Report has been requested to stop" appears.

Parameters

Terminating an Active Report

The syntax of the runtime operations utility for terminating an active report is

/PA <param> Specifies a parameter to be passed to a report.

Note: You can pass a string literal with a maximum of 254 characters to a report. If the string literal contains embedded spaces, enclose the string in quotation marks (“”).

For example: To run a report by passing a report parameter, "SampleName", type

AdminSystem /S Sample /RUN SampleReport /PA SampleName

/S <SystemName> /RUN <ReportName> /?

Displays the command line syntax and its usage for running a report, and the utility exits without starting the process.


/S <SystemName> Specifies that a valid system name must be passed as a parameter. Refer to “Displaying the Status of an Application” for complete description about the /S argument.

/STR <ReportName> Specifies the name of a report. Refer to “Running or Recovering a Report” for more information about the report name argument.

For example: To stop a report with a valid report name, type

AdminSystem /S Sample /STR SampleReport

/MIX <ProcessId> Specifies the process ID of a report.

/S <SystemName> /STR <ReportName> /?

Displays the command line syntax and its usage for stopping a report, and the utility exits without starting the process.


3826 5856-005 5–37


AdminSystem /S <SystemName> /TER <ReportName> [/MIX <ProcessID>] [/REC <NORECOVERY|RECOVER|DISCARD>]

You can use the command to terminate an active report immediately. This command is useful if a report is looping or has been started accidentally. You can terminate any inquiry reports without affecting the remainder of the application.

Notes: It is recommended for a report to detect error conditions and terminate normally. A report containing the Sleep or Accept logic command reflects the following behavior:

• If a report contains Sleep logic statements, transactions prior to the last Sleep logic statement are committed to the application database.

• If a report with a Sleep logic statement that is initiated from a client session is terminated, it is recommended to terminate the client session manually either from the task manager or with other user commands.

• If a report with an Accept logic statement that is initiated from a client session is terminated, the client session might wait for your input to end the session. This is applicable only for reports initiated from the command prompt. A report that is initiated from the GUI clients behaves differently as you can continuously supply commands without waiting for the report completion.

If you pass valid parameters to run the utility, the message "Report has been requested to terminate" appears.

Parameters



/TER <ReportName> Specifies the name of a report. Refer to “Running or Recovering a Report” for more information about the report name argument.

For example: To stop a report with a valid report name and system name, type

AdminSystem /S Sample /TER SampleReport

/MIX <ProcessId> Specifies the process ID of a report.

Note: This argument is optional and takes the value of the user account that initiated the report, if not specified.

5–38 3826 5856-005


Waking Up a Report

The syntax of the runtime operations utility for waking up a report is

AdminSystem /S <SystemName> /WUP <ReportName> [/PA <param>]

The command reactivates a report that is suspended by a previous Sleep or CriticalPoint logic command. When a Wake logic statement is executed, a Wake message is sent to the specified report. The Wake messages are sent to any reports with the same repository path, segment name, and report name that are suspended on the same workstation. If you pass valid parameters to run the utility, the message “Report invoices woken up” appears. If a report to be reactivated is not available, the message "Failed To Wake Up Report" appears.

Parameters

/REC <NORECOVERY|RECOVER|DISCARD>

Determines the handling of any transaction in progress. You can use one of the following recovery options to terminate a report.

• NORECOVERY – Use, if the report is not to be rerun. Any recovery information saved for the report is deleted, unless extended recovery is in use. This is the default option

• DISCARD – Use if the report is not to be rerun. Any recovery information saved for the report is deleted

• RECOVER – Use to rerun the report, attempting to recover up to and including any transaction it may have been processing when the command was executed.

Two attempts are made to recover the report. If both fail, a message is sent to the error log and no further attempts are made.

Note: If you provide invalid options for recovery mode, the error message “Invalid input specified" appears.

For example: To terminate a report by enabling the recovery mode, "RECOVER", type

AdminSystem /S Sample /TER SampleReport /REC RECOVER

/S <SystemName> /TER <ReportName> /?

Displays the command line syntax and its usage for terminating a report, and the utility exits without starting the process.




3826 5856-005 5–39


Deleting Report Recovery Information

The syntax of the runtime operations utility to delete recovery information for a report that is identified in a session is

AdminSystem /S <SystemName> /DEL <SessionId>

If you pass valid parameters to run the utility, the message “Report recovery information deleted” appears. Prior to using the Runtime API command with the /DEL parameter, you can use the /REP parameter to obtain the SessionId value.

Parameters

/WUP <ReportName> Specifies the name of a report. Refer to “Running or Recovering a Report” for more information about the report name argument.

For example: To wake up a report with a valid report name and system name, type

AdminSystem /S Sample /WUP SampleReport

/PA <param> Specifies a parameter to be passed to a report.

Note: You can pass a string literal with a maximum of 254 characters to a report. If a numeric value is used, it will be converted to text.

/S <SystemName> /WUP <ReportName> /?

Displays the command line syntax and its usage for waking up a report, and the utility exits without starting the process.



/DEL <SessionId> Specifies the session ID of a report.

You can use this value to remove the recovery information of a report that is awaiting recovery.

Note: This argument is mandatory. A session ID is a unique integer for every session. If the value is invalid or null, an error message specifying that the Input string is not in the correct format appears.

For example: To delete the recovery information of a report identified by a session ID, type

AdminSystem /S Sample /DEL 47

/S <SystemName> /DEL <SessionId> /?

Displays the command line syntax and its usage for deleting recovery information of a report, and the utility exits without starting the process.


5–40 3826 5856-005


Troubleshooting—Error Messages

This topic provides a list of error messages you may encounter while attempting to use AdminSystem.exe.

• If you provide incorrect option for an argument, an error message specifying that the argument is invalid appears, along with the argument and the usage of the utility, for reference.

• If you pass an incorrect command, the error message "Invalid input specified" appears.


• If you do not pass the mandatory argument or arguments to the command line utility, an error message specifying that the mandatory input is missing or invalid appears, along with the usage of the utility for the relevant runtime administration operations or report administration operations, for reference.

• If system is disabled for any of the command line function, an error message specifying that the specified system has been disabled appears. You must enable the system to proceed with runtime or report administrative functions.

• If you pass an incorrect value for an argument, an error message specifying that the input is invalid appears, along with the argument and the usage of the utility, for reference.

• If you pass duplicate arguments, the error message "Encountered duplicate arguments. Please address the duplicates before proceeding" appears.

Reconfigure External Persistent Class Utility (EPCReconfigure.exe)

The Reconfigure External Persistent Class utility (EPCReconfigure.exe) can be used at runtime to view, delete, or change the configuration properties of an external class with persistent members. This utility stores the configuration details in the _Config table of the runtime database. The _Config table is created when you first deploy an AB Suite system only if the system contains external classes with persistent members.

The configuration details stored in the _Config table take precedence over those set in the model. Therefore, after deploying the runtime application, you can use the Reconfigure utility to modify the configuration details with which the system was originally generated. This allows a system to be deployed using the Runtime Transfer and any external persistent classes within the system to be reconfigured and connected to different external data.

You can modify configuration details, such as the external host, the TCIP port number, the external EAE system, the external table, the user id, and the password required to access the host server.

3826 5856-005 5–41


This utility is available in the CD Runtime\Windows Runtime\Runtime Utilities\EPCReconfigure folder of the Agile Business Suite 4.0 Installation CD. You can invoke the utility from a command line.

Note: You must have local administrator privileges to use EPCReconfigure.exe

The EPCReconfigure utility requires a set of command line arguments for each of the following options:

• GETCONFIG - To view the configuration propertiesEPCReconfigure.exe GETCONFIG <system name> <model class name>

• DELETECONFIG - To delete the configuration propertiesEPCReconfigure.exe DELETECONFIG <system name> <model class name>

• SETCONFIG - To modify the configuration propertiesEPCReconfigure.exe SETCONFIG <system name> <model class name> <ExternalHost> <PortNumber> <ExternalSystem> <ExternalTable> <UserId> <Password>

Note: An error message appears if you do not specify the required command line arguments for an option. All error messages are available in the system.log file.

where,

Configuration Property Description

<system name> Specifies the deployed AB Suite system.

Note: An error message appears if the system does not exist.

<model class name> Specifies the external class with persistent members used to read the OS 2200 database.

<ExternalHost> Specifies the IP address or the name of the external host server.

For example: \\USTR-TIS2.UNISYS.COM

<PortNumber> Specifies the TCIP port number to connect to the external host server. The port number must be between 1 and 65535 inclusive.

<ExternalSystem> Specifies the name of the deployed EAE system.

<ExternalTable> Specifies the OS 2200 table being accessed or the Source Name of the external data source.

Note: An error message appears if the Source Name is invalid and you should verify the external table in the OS 2200 RDMS database. You can access the system.log file for more information on this.

5–42 3826 5856-005


Programmatic Access to RuntimeThis subsection describes the following AB Suite public interfaces that can be implemented.

Note: You must have local administrator privilege to access the public interfaces. A normal user without administrative privileges can access the interfaces by using the user group, “AB Suite Runtime Administrators" on the local machine. You can refer to the Configuring Runtime for Normal Users in the Installation and Configuration Guide and the relevant AB Suite Interfaces for more information about security information pertaining to Runtime Administration tasks.

StatusInfo Object of Runtime API Interfaces

The methods in the AB Suite public interfaces return the StatusInfo object. This object saves the status information of all the methods from the StatusInfo class. The StatusInfo class exposes the following members.

<UserId> Specifies the registered user-id that can access the host server.

The user-id can be

• Alphanumeric character

• Period (.)

• Hyphen (-)

• Of length less than or equal to 12

The user-id must not begin with an underscore or a numeral.

Note: The user-id is encrypted and stored in the _Config table.

<Password> Specifies the password required for the authorized user id on the host server.

The password can be

• Alphanumeric character

• Of length less than or equal to 18

A password must not contain a comma (,) or a slash (/).

Note: The password is encrypted and stored in the _Config table.

Description Interface Name

Runtime administration tasks IConfigureRuntime

Deploy AB Suite generated package IDeployPackage

Create a clone of a builder generated package IDeployPackage

Runtime administration and report administration operations IAdministerSystem

Configuration Property Description

3826 5856-005 5–43


Members of StatusInfo class

IConfigureRuntime Interface

The Unisys.AgileBusiness.RuntimeAPI namespace contains the IConfigureRuntime interface that enables you to perform the Runtime Administration tasks. The RuntimeFactory class includes methods to return the IConfigureRuntime objects.

Refer to “Definition of the IConfigureRuntime Interface” for a complete description of the interface.

Namespace: Unisys.AgileBusiness.RuntimeAPI

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

Syntax

The IConfigureRuntime object can be created using RuntimeFactory.GetRuntime() method.

IConfigureRuntime RuntimeConfig = RuntimeFactory.GetRuntime()

The IConfigureRuntime interface exposes the following members.

Methods

Note: The interface enables you to perform the administration tasks required for pre-deployed applications.

Required Security Privileges

Name Type Description

Status StatusEnum Sets the status with the status codes: Error, Success, Warning.

By default, the status is "Error".

StatusMessage string Message associated with the status. Initially StatusMessage is initialized with an empty string.

Method Description

ConfigureLog() Called by an application to configure logging at the server level to capture details of deployment, database reorganization, and application transactions.

ConfigureSocketAdapter() Called by an application to configure adapter details for TCPIP over RatlSocket or HubSocket.

ConfigureQueueAdapter() Called by an application to configure adapter details for RATL over MSMQ and SOAP over MSMQ.

5–44 3826 5856-005


By default, a local administrator can access the methods.

To allow non-administrative users to access this utility, the users must be a member of the "Runtime Administrators" COM+ role of Runtime Manager application or member of the "AB Suite Runtime Administrators" user group.

IConfigureRuntime.ConfigureLog Method

This method allows you to read and update the System, DBReorg, Deployment log, and Runtime API log details.

SyntaxConfigureLog(Unisys.AgileBusiness.RuntimeAPI.ConfigureLogParameter logParameter, Unisys.AgileBusiness.RuntimeAPI.ModeType mode)

Arguments

• logParameter: ConfigureLogParameter object

The object describes all the Configure Log parameters or values available from the ConfigureLogParameter class.

The ConfigureLogParameter class exposes the following members.

Members of ConfigureLogParameter class

• mode: Read or Write mode of the configuration

This argument stores the mode type of the Configure operations, Read/Write.

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 “Configure Log Files Utility (ConfigureLog.exe)” for more information on validation messages.

Using the IConfigureRuntime Interface for the ConfigureLog Method

The following steps and code example illustrates the implementation of IConfigureRuntime for Get (read) and Set (write) methods of Configure log:


logName Enum LogFileName Log types: System/DBReorg/Deployment/RuntimeAPI

LogStatus Enum LogStatus LogStatus: Enable/Disable/None

NoOfBackups int Number of backups of the log file

FileSize int Log file size in kB

FilePath string Absolute file path of the log file

Level enum LogLevel Log level: Error/Warning/Debug/Information

3826 5856-005 5–45


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 4.0 Installation directory>\bin folder)

3. Add the following code to the Class to get and set configure log data into the Sample application.

namespace SampleConfigLog{

using System;using Unisys.AgileBusiness.RuntimeAPI;

class Program{

static void Main(string[] args){

//Get the Runtime configIConfigureRuntime config = RuntimeFactory.GetRuntime();

//Construct the ConfigureLogParameterConfigureLogParameter parameter = new ConfigureLogParameter()

{LogName = LogFileName.System,LogStatus = LogStatus.Enable,Level = LogLevel.Information,FilePath = @"C:\TEMP",FileSize = 10000,NoOfBackups = 7

};

//Invoke configurelog to update with the new valuesStatusInfo statusInfo = config.ConfigureLog(parameter, ModeType.Write);

Console.WriteLine(statusInfo.StatusMessage);

//Invoke configurelog to read the valuesstatusInfo = config.ConfigureLog(parameter, ModeType.Read);

if (statusInfo.Status == StatusEnum.Success){

//Prints the read valuesConsole.WriteLine("File Name : " + parameter.LogName);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);}

}}

4. Build the Class Library.

IConfigureRuntime.ConfigureSocketAdapter Method

This method allows you to configure the RatlSocket/HubSocket adapter details.

Syntax

5–46 3826 5856-005


ConfigureSocketAdapter(Unisys.AgileBusiness.RuntimeAPI.SocketParameter socketParameter, Unisys.AgileBusiness.RuntimeAPI.ModeType mode)

Arguments

• socketParameter: SocketLogParameter object

The object describes all the RATL/HUB socket configuration parameters or values available from the SocketParameter class.

The SocketParameter class exposes the following members.

Members of SocketParameter class


This argument stores the mode type of the Configure RatlSocket/HubSocket operations, Read/Write.

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 “Configure Protocol Adapters Utility (ConfigureAdapter.exe)” for more information on validation messages.

Using the IConfigureRuntime Interface for the ConfigureSocketAdapter Method

The following steps and code example illustrates the implementation of IConfigureRuntime for Get (read) and Set (write) methods of ConfigureSocketAdapter for RatlSocket:





SocketType enum Socket Type Represents socket name: RATL/HUB

PortNumber int Socket port number

TimeOut int Socket time out. The value must be in seconds.

SessionProtectionTimeOut int Socket session protection timeout. The value must be in seconds.





3826 5856-005 5–47


3. Add the following code to the Class to get and set configure adapter details for RatlSocket into the Sample application.

namespace SampleConfigSocketAdapter{


class Program{


//Get the Runtime configIConfigureRuntime config = RuntimeFactory.GetRuntime();

//Construct the Socket parameterSocketParameter parameter = new SocketParameter()

{SocketType = SocketType.RatlSocket,PortNumber = 2850,LogStatus = LogStatus.Enable,FilePath = @"C:\TEMP",FileSize = 1000,NoOfBackups = 7

};

//Invoke ConfigureSocketAdapter to update with the new valuesStatusInfo statusInfo = config.ConfigureSocketAdapter(parameter, ModeType.Write);


//Invoke ConfigureSocketAdapter to read the valuesstatusInfo = config.ConfigureSocketAdapter(parameter, ModeType.Read);


//Prints the read valuesConsole.WriteLine("Socket Name : " + parameter.RatlSocketName);Console.WriteLine("Port Number : " + parameter.PortNumber);Console.WriteLine("Time out : " + parameter.TimeOut);Console.WriteLine("Session timeout : " + parameter.SessionProtectionTimeOut);Console.WriteLine("Enable : " + parameter.LogStatus);Console.WriteLine("File Path : " + parameter.FilePath);Console.WriteLine("Reset File Size : " + parameter.FileSize);Console.WriteLine("No of backups : " + parameter.NoOfBackups);

}else{


}}


IConfigureRuntime.ConfigureQueueAdapter Method

This method allows you to configure the RatlQueue/SoapQueue adapter details.

SyntaxConfigureQueueAdapter(Unisys.AgileBusiness.RuntimeAPI.QueueParameter queueParameter, Unisys.AgileBusiness.RuntimeAPI.ModeType mode)

Arguments

5–48 3826 5856-005


• queueParameter: QueueParameter object

The object describes all the RATL/SOAP queue configuration parameters or values available from the QueueParameter class.

The QueueParameter class exposes the following members.

Members of QueueParameter class


This argument stores the mode type of the Configure RatlQueue/SoapQueue operations, Read/Write.

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 “Configure Protocol Adapters Utility (ConfigureAdapter.exe)” for more information on validation messages.

Using the IConfigureRuntime Interface for the ConfigureQueueAdapter Method

The following steps and code example illustrates the implementation of IAdmin for Get (read) and Set (write) methods of Configure Adapter for RatlQueue:




3. Add the following code to the Class to get and set configure adapter details for RatlQueue into the Sample application.

namespace SampleConfigQueueAdapter{


class Program{


//Get the Runtime config.


QueueType enum QueueType Queuename: RATL/SOAP

ServerName string MSMQ Server machine of the queue adapter





3826 5856-005 5–49


IConfigureRuntime config = RuntimeFactory.GetRuntime();

//Construct the Socket parameterQueueParameter parameter = new QueueParameter()

{QueueType = QueueType.RatlQueue,ServerName = "ServerName",LogStatus = LogStatus.Enable,FilePath = @"C:\TEMP",FileSize = 1000,NoOfBackups = 7};

//Invoke ConfigureQueueAdapter to update with the new values.StatusInfo statusInfo = config. ConfigureQueueAdapter(parameter, ModeType.Write);


//Invoke ConfigureQueueAdapter to read the valuesstatusInfo = config. ConfigureQueueAdapter(parameter, ModeType.Read);


//Prints the read valuesConsole.WriteLine("Queue Name : " + parameter. QueueType);Console.WriteLine("Server Name : " + parameter. ServerName);Console.WriteLine("Enable : " + parameter.LogStatus);Console.WriteLine("File Path : " + parameter.FilePath);Console.WriteLine("Reset File Size : " + parameter.FileSize);Console.WriteLine("No of backups : " + parameter.NoOfBackups);

}else{


}}

}


Definition of the IConfigureRuntime Interface

Following is the definition of the IConfigureRuntime interface.

namespace Unisys.AgileBusiness.RuntimeAPI{public interface IConfigureRuntime { StatusInfo ConfigureQueueAdapter(QueueParameter queueParameter, ModeType mode); StatusInfo ConfigureSocketAdapter(SocketParameter socketParameter, ModeType mode); StatusInfo ConfigureLog(LogParameter logParameter, ModeType mode);

}}

IDeployPackage Interface

The Unisys.AgileBusiness.RuntimeAPI namespace containsthe IDeployPackage interface that allows you to deploy an AB Suite generated package to a local or remote server and create a clone of a builder generated package (.msi or .cab). Refer to

5–50 3826 5856-005


“Prerequisites for DPM” for details about the prerequisite information before cloning a builder generated package. The RuntimeFactory class includes methods to return the IDeployPackage objects.

Refer to “Definition of the IDeployPackage Interface” for a complete description of the interface.



Syntax

You can create the IPackageDeploy object by using the RuntimeFactory.GetDeployer()method.

IDeployPackage DeployPackage = Unisys.AgileBusiness.RuntimeAPI.RuntimeFactory.GetDeployer();

The IDeployPackage interface exposes the following methods.

Methods

Note: You must have local administrator privileges to use all the methods.

IDeployPackage.PackageInstall Method

This method allows you to install the generated package.

SyntaxPackageInstall(Unisys.AgileBusiness.RuntimeAPI.PackageInstallParameter parameter, Unisys.AgileBusiness.RuntimeAPI.PackageDeployCallBack callBack)

Arguments

• parameter: PackageInstallParameter object

A data object class containing parameter information to install a package.

The PackageInstallParameter class exposes the following members.

Method Description

PackageInstall() Installs a generated package

ClonePackage() Creates a deployment package for a new instance

CreatePartialPackage() Creates partial MSIs and CAB files for an existing instance

UpdatePackage() Updates the deployment package of an existing instance

3826 5856-005 5–51


Members

• callBack: RuntimeCallBack object

To allow a client program to handle the progress messages received from the PackageInstall(), ClonePackage(), CreatePartialPackage(), and UpdatePackage() methods, the client must:

– Implement the RuntimeCallBack class to receive the progress messages.

– Pass the RuntimeCallBack object to the server in the PackageInstall() call.

The RuntimeCallBack class is an abstract class that implements the ICallBack interface. To obtain the deploy progress messages, the client should create a new class that inherits the RuntimeCallBack class. If the client passes this argument as null, no progress messages appear.

The RuntimeCallBack class exposes the following methods.

Methods


DeployPackagePath string Absolute file path of the MSI or CAB files to be deployed.

UserName string Application User Name, which must be in the format: "Domain\Username"

Password SecureString Application User password

DeploymentName string Folder on the target machine in which the MSI or CAB package is saved. The default value is the current package name

RetainExistingDatabase bool Determine whether an existing database should be retained or a new database be recreated during the deploy process. The default value is true, which retains an existing database.

BackupExistingDatabase bool Back up an existing database. The default value is false.

TargetServerName string Target Runtime server name. If empty, the default value will be localhost.

TargetDBRegistration string Target DB server registration

TargetPath string Target application folder

TargetSystemName string Target System Name

TargetWinformPath string Target Winform folder

TargetDBName string Target DB name

Method Description Parameter

CompletionStatus() Completion status int status

5–52 3826 5856-005


Refer to “Example of a RuntimeCallBack Class” for the syntax of these methods.

Note: A client program can also use the default class, ConsoleCallBackHandler to get the progress messages in the PackageInstall method. If the client program desires to modify the progress message, the client can customize by creating a class that implements the override methods of the RuntimeCallback class.

Definition of ConsoleCallBackHandler Class

The ConsoleCallBackHandler class enables a client program to handle the progress messages with the default template.

The ConsoleCallBackHandler class exposes the following methods.

Example of a RuntimeCallBack Class

Following is a C# example of the class. This example isfor a simple console client that indicates how you can write a callback message to the console output. The received messages are written to the console.

public class CallBackHandler : RuntimeCallBack { protected override void ProgressMessage(string theMsg, MSGTYPEMSGTYPE) { Console.WriteLine(theMsg); }

protected override void CompletionStatus(int Status) { Console.WriteLine("Operation Completed successfully",

Status); }

protected override void ReceiveAccept(IAccept pIAccept, stringprompt)

ProgressMessage() Receives the progress message and message code

String message, Unisys.AgileBusiness.RuntimeAPI.MSGTYPE MSGTYPE

ReceiveAccept() Receives the IAccept object from report.

Unisys.AgileBusiness.RuntimeAPI.IAccept pIAccept

String prompt


CompletionStatus() Completion status int status

ProgressMessage() Receives the progress message and message code

String message, Unisys.AgileBusiness.RuntimeAPI.MSGTYPE MSGTYPE

ReceiveAccept() Receives the IAccept object from report.

Unisys.AgileBusiness.RuntimeAPI.IAccept pIAccept

String prompt


3826 5856-005 5–53


{ Console.WriteLine(prompt); string lReply = Console.ReadLine(); pIAccept.Reply(lReply); }

}

Example of a ConsoleCallBackHandler Class

Following is a C# example of this class with default template.

ConsoleCallBackHandler callBack = new ConsoleCallBackHandler();StatusInfo status = deploy.PackageInstall(param, callBack);

Return Value

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

SecurityHelper Class

This public class sets the default security required for installing a generated package. The class exposes the following members.

Members

Using the IDeployPackage Interface for the PackageInstall() method

Perform the following steps to use the interface through C# example:




3. Add the following code to perform an AB Suite system deployment to a local server.

Note: If client wants to receive the progress messages, the second argument of the PackageInstall method must never be null.

namespace SampleDeployer{

using System;using Unisys.AgileBusiness.RuntimeAPI;using System.Security;

class Program{

static void Main(string[] args)


CoInitializeSecurity int Enables setting different security parameters apart from the default security.

SetSecurity int Set the default security required for deploying.

5–54 3826 5856-005


{//Get the deployerIDeployPackage deployer = RuntimeFactory.GetDeployer();//GetDeployer sets the securitySecureString securePwd = new SecureString();string pass = @"Password";foreach (char c in pass)

securePwd.AppendChar(c);//Construct the PackageInstallParameterPackageInstallParameter param = new PackageInstallParameter(){

DeployPackagePath=@"C:\TEMP\stagingarea\NGENSampleDeploy.msi",

UserName = @"Appuser",Password = securePwd

};

//Get the callback object for progress message.CallBackHandler callBack = new CallBackHandler();

StatusInfo statusInfo = deployer.PackageInstall(param, callBack);}

}


IDeployPackage.ClonePackage Method

This method allows you to create a deployment package for the new instance.

SyntaxClonePackage(Unisys.AgileBusiness.RuntimeAPI.ClonePackageParameter parameter, Unisys.AgileBusiness.RuntimeAPI.RuntimeCallBack callBack)

Arguments

• parameter: ClonePackageParameter object

The object consists of all Clone package user input.

The ClonePackageParameter class exposes the following list of members.

Members


BuilderGeneratedPackage string Absolute path, relative file path, or network path to the builder generated package; .msi or .cab.

This member is mandatory.

For example:

• BuilderGeneratedPackage = @"C:\TEMP\stagingarea\Sample.msi"

• BuilderGeneratedPackage = @“C:\AB Suite 4.0\Data\public\ PrototypePackageMessagesSimple.msi"

• BuilderGeneratedPackage = @"..\Sample.msi"

• BuilderGeneratedPackage = @"\\network\my folder\ BuilderGeneratedPackage.msi"

3826 5856-005 5–55



Refer to the callback argument of the PackageInstall() method for further information.

Return Value

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

OverWrite bool Overwrites OutputPath package. The default value is false.

For example:

OverWrite = true

TargetPackagePath string Output package path

The default path is "MyDocuments"

For example:

TargetPackagePath = @"C:\ClonedPackages"

DBName string Database name

The default value is the existing Intance name appended with "DB "

For example: for Sample instance, type

DBName = @"SAMPLEDB"

DBRegistration string Database server registration name

The default value is the builder generated value.

For example:

DBRegistration = @"SQLSERVER"

DBSchemaName string Database schema name

The default value is the existing Instance name.

For example:

DBSchemaName = @"SAMPLESCHEMA"

InstanceName string Instance name or new package name

The default value is the builder generated value appended with "Clone"

For example:

InstanceName = @"SAMPLECLONE"

PackageInstallationDirectory

string Absolute path to the builder generated instance package

The default value is the builder generated value appended with "Clone".

For example:

PackageInstallationDirectory = @"C:\ABSuite\Systems\SampleClone"


5–56 3826 5856-005


Using the IDeployPackage Interface for the ClonePackage() method

Perform the following steps to use the interface for creating a deployment package of a new instance through C# example:




3. Add the following code to create a deployment package.

Note: If a client wants to receive the progress messages, the second argument of the ClonePackage method must never be null.

namespace SampleDPM{


class Program{


//Get the deployerIDeployPackage deployer = RuntimeFactory.GetDeployer();

//Construct the ClonePackageParameterClonePackageParameter param = new ClonePackageParameter(){

BuilderGeneratedPackage = @"C:\TEMP\stagingarea\Sample.msi",TargetPackagePath = @"C:\ClonedPackages",DBName = @"SAMPLEDB",DBSchemaName = @"SAMPLESCHEMA",DBRegistration = @"SQLSERVER",InstanceName = @"SAMPLECLONE",

PackageInstallationDirectory = @"C:\ABSuite\Systems\SampleClone",OverWrite = true

};

//Get the callback object for progress messageCallBackHandler callBack = new CallBackHandler();

//Execute ClonePackageStatusInfo statusInfo = deployer.ClonePackage(param, callBack);

}}

}


IDeployPackage.CreatePartialPackage Method

This method allows you to create a partial MSI package for an existing instance. A partial package is used to clone Report MSIs.

SyntaxCreatePartialPackage(Unisys.AgileBusiness.RuntimeAPI.PartialPackageParameter parameter, Unisys.AgileBusiness.RuntimeAPI.RuntimeCallBack callBack)

3826 5856-005 5–57


Arguments

• parameter: PartialPackageParameter object

The object consists of partial package input.

The PartialPackageParameter class exposes the following list of members.

Members



Return Value


Using the IDeployPackage Interface for the CreatePartialPackage() method




For example:

BuilderGeneratedPackage = @"C:\TEMP\stagingarea\SampleReports.msi"


For example:

OverWrite = true



For example:


DpmGeneratedPackage string Absolute path, relative file path, or network path to the DPM generated instance package


For example:

DpmGeneratedPackage =@"C:\ClonedPackages\SampleClone.msi"

InstanceName string Instance name or new package name

The default value is the existing Instance name appended with "ClonePartial"

For example:

InstanceName = @"SAMPLECloneReports"

5–58 3826 5856-005


Perform the following steps to use the interface for creating a partial MSI package of the existing instance:




3. Add the following code to create a partial MSI package.

Note: If client wants to receive the progress messages, the second argument of the CreatePartialPackage method must never be null.



class Program{



//Construct the PartialPackageParameterPartialPackageParameter param = new PartialPackageParameter(){BuilderGeneratedPackage = @"C:\TEMP\stagingarea\SampleReports.msi",DpmGeneratedPackage = @"C:\ClonedPackages\SampleClone.msi",TargetPackagePath = @"C:\ClonedPackages",InstanceName = @"SAMPLECloneReports",OverWrite = true};


//Execute CreatePartialPackageStatusInfo statusInfo = deployer.CreatePartialPackage(param, callBack);}

}}


IDeployPackage.UpdatePackage Method

This method allows you to update the deployment package of the existing instance.

SyntaxUpdatePackage(Unisys.AgileBusiness.RuntimeAPI.UpdatePackageParameter parameter, Unisys.AgileBusiness.RuntimeAPI.RuntimeCallBack callBack)

Arguments

• parameter: UpdatePackageParameter object

The object consists of Updatepackage user input.

The UpdatePackageParameter class exposes the following list of members.

3826 5856-005 5–59


Members



Return Value




For example:

BuilderGeneratedPackage = @"C:\TEMP\stagingarea\Sample.msi"


For example:

OverWrite = true



For example:


DBName string Database name

For example:

DBName = @"CLONESAMPLEDB"

DBRegistration string Database server registration name

For example:

DBRegistration = @"SQLSERVER"

DBSchemaName string Database schema name

For example:

DBSchemaName = @"CLONEDSAMPLESCHEMA"

DpmGeneratedPackage string Absolute path, relative file path, or network path to the DPM generated instance package


For example:

DpmGeneratedPackage = @"C:\ClonedPackages\SampleClone.msi"

PackageInstallationDirectory string Absolute path to builder generated instance package

For example:

PackageInstallationDirectory = @"C:\ABSuite\Systems\SampleClone"

5–60 3826 5856-005



Using the IDeployPackage Interface for the UpdatePackage () method

Perform the following steps to use the interface for updating the deployment package through C# example:




3. Add the following code to update the deployment package.

Note: If client wants to receive the progress messages, the second argument of the UpdatePackage method must never be null.



class Program{



//Construct the UpdatePackageParameterUpdatePackageParameter param = new UpdatePackageParameter(){

BuilderGeneratedPackage = @"C:\TEMP\stagingarea\Sample.msi",DpmGeneratedPackage = @"C:\ClonedPackages\SampleClone.msi",TargetPackagePath = @"C:\ClonedPackages",DBName = @"CLONESAMPLEDB",DBSchemaName = @"CLONEDSAMPLESCHEMA",DBRegistration = @"SQLSERVER",PackageInstallationDirectory = @"C:\ABSuite\Systems\SampleClone",OverWrite = true

};


//Execute UpdatePackageStatusInfo statusInfo = deployer.UpdatePackage(param, callBack);

}}

}


Definition of the IDeployPackage Interface

Following is the definition of the IDeployPackage interface.

namespace Unisys.AgileBusiness.RuntimeAPI{

3826 5856-005 5–61


public interface IDeployPackage { StatusInfo ClonePackage(ClonePackageParameter parameter, RuntimeCallBack callBack); StatusInfo CreatePartialPackage(PartialPackageParameter parameter, RuntimeCallBack callBack); StatusInfo PackageInstall(PackageInstallParameter parameter, RuntimeCallBack callBack);StatusInfo UpdatePackage(UpdatePackageParameter parameter, RuntimeCallBack callBack);

}}

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 complete description of the interface.



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. Please refer to the following table for the specific security privileges.

Methods

Method Description Security Privileges

ClearSession() Clears an existing orphan session based on a given station name or session id

Users should be a member of the Application Administrators.

5–62 3826 5856-005


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:






DisableHub() Disables HUB for an application.




DisableSystem() Disables an application. Users must be a member of one of the following COM+ roles in order to access the method:



EnableHub() Enables HUB for an application.




EnableSystem() Enables an application Users must be a member of one of the following COM+ roles in order to access the method:



GetAccountMonth() Displays both the High and Low Account Months of an application


• Accountants


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




3826 5856-005 5–63


GetSystemStatus() Displays the status of a system




ListIspecs() Lists unique ispecs in an application




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



• Report Monitors






ListUsers() Displays a list of stations connected to a runtime system.



RunReport() Initiate a report or recover a report with recovery information available.


• Report Runners



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


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


• Accountants



5–64 3826 5856-005


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.

SyntaxClearSession(string userOrSession)

Arguments

userOrSession: string

StopReport() Terminates or stops a running report.






StopSystem() Stops a runtime system. Users must be a member of one of the following COM+ roles in order to access the method:



TerminateReport() Terminates an active report immediately.






WakeUpReport() Wakes up a report Users must be a member of one of the following COM+ roles in order to access the method:






• Report Runners


3826 5856-005 5–65


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

Return Value


IAdministerSystem.GetAccountMonth Method

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

SyntaxGetAccountMonth(out int highAccount, out int lowAccount)

Arguments

• highAccount: integer

Stores and displays the High Account Month (HAM) value in the format, yymm.

• lowAccount: integer

Stores and displays the Low Account Month (LAM) value in the format, yymm.

Return Value


IAdministerSystem.GetSystemStatus Method

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

SyntaxGetSystemStatus(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

5–66 3826 5856-005


Return Value


IAdministerSystem.EnableSystem Method

This method allows you to enable an application.

SyntaxEnableSystem()

Return Value


IAdministerSystem.DisableSystem Method

This method allows you to disable an application.

SyntaxDisableSystem()

Return Value


IAdministerSystem.StopSystem Method

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

SyntaxStopSystem([bool disable = false])

Arguments

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

Return Value


Running Execute an application

Unknown No known status that are specified above

Name Description

3826 5856-005 5–67


IAdministerSystem.GetHubStatus Method

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

SyntaxGetHubStatus(out bool isEnabled)

Arguments

isEnabled: bool

isEnabled is set to true, to enable HUB

Return Value


IAdministerSystem.EnableHub Method

This method allows you to enable HUB for an application.

SyntaxEnableHub()

Return Value


IAdministerSystem.DisableHub Method

This method allows you to disable HUB for an application.

SyntaxDisableHub()

Return Value


IAdministerSystem.ListIspecs Method

This method lists the unique ispecs in an application.

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

5–68 3826 5856-005


Arguments

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

This argument provides the list of ispecs in a system.

Return Value


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.

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

Arguments

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

This argument provides a list of connected users.

Return Value


IAdministerSystem.SendAMessage Method

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

SyntaxSendAMessage(string station, string message)

Arguments

• station: string

This argument is the destination station that can be a user account, terminal name, or ALL (for all users of an application).

• message: string

The text to be displayed on the status line of destination terminals.

Return Value


3826 5856-005 5–69


IAdministerSystem.SetAccountMonth Method

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

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

Arguments

• highAccount: integer

This argument is the HAM specified in the format, yymm. By default, the value is "0" and is updated only if value is not zero.

• lowAccount: integer

This argument is the LAM specified in the format, yymm. By default, the value is "0" and is updated only if value is not zero.

Return Value


Using the IAdministerSystem Interface for the Application Administration Operations

Perform the following steps to use the interface for the application administration operations through C# example:




3. Add the following code.namespace SampleSystem{


class Program{


//Get the RuntimeSystemIAdministerSystem sample = RuntimeFactory.GetSystem("SAMPLE");

//Get the System statusSystemStatus systemStatus;StatusInfo status = sample.GetSystemStatus(out systemStatus);

if (status.Status == StatusEnum.Success){

Console.Write(string.Format("Status : "));switch (systemStatus){

5–70 3826 5856-005


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;

default: Console.WriteLine("Unknown");break;

}}else{

Console.WriteLine(status.Status + status.StatusMessage);}

//Enable systemstatus = sample.EnableSystem();

//Disable systemstatus = sample.DisableSystem();

//Stop systemstatus = sample.StopSystem();

//Get the status of the System HUBbool isHubEnabled;status = sample.GetHubStatus(out isHubEnabled);

//Disable Hub of the systemstatus = sample.DisableHub();

//Enable Hub of the Systemstatus = sample.EnableHub();

//List usersIList<string> usersList = null;status = sample.ListUsers(out usersList);


if (usersList.Count > 0){

foreach (string user in usersList)Console.WriteLine(user);

}else{

Console.WriteLine("No users are logged in");}

}

}}

}


3826 5856-005 5–71


IAdministerSystem.ListRunningReports Method

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

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

Arguments

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

This argument provides a list of reports of type ReportInformation.

Return Value


IAdministerSystem.RunReport Method

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

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

Arguments

• reportname: string

name of the report

• callback: RuntimeCallBack object

To allow a client program to handle the progress messages received from the RunReport() method, the client must

– Implement the RuntimeCallBack class to receive the progress messages.

– Pass the RuntimeCallBack object to the server in the RunReport() call.

Refer to “IDeployPackage Interface” for more information about the usage of RuntimeCallBack class.

• recoverKey: string

A unique key value to recover a report.

• waitForReportCompletion: bool

Enables wait for a report completion. The default value is true. If you do not want to wait for completion, the value can be set to false.

• parameter: string

5–72 3826 5856-005


The parameter to be passed to the report. This argument is optional.

• device: string

Device type that overrides the device type that is set for a report

This argument is optional. The default value is "LP", which means piped to the command defined by the LP alias. Other valid device types are:

– TP: Piped to the command defined by an alias

– EX: Output to an alias

– VD: Output to a temporary file (the name is displayed when the report is initiated)

– DI: Direct output to an alias

– DP: Direct output to Enterprise Output Manager

• language: string

Language defined for an application. This argument is optional.

• trace: bool

Enables trace for a report. This argument is optional. The default value is false.

Note: Refer to “IDeployPackage interface” for more information about the SecurityHelper class to set the security.

Return Value


IAdministerSystem.DeleteReportRecovery Method

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

SyntaxDeleteReportRecovery(int sessionID)

Arguments

sessionID: int

The Session ID or recovery key of a report

Return Value


IAdministerSystem.StopReport Method

This method allows you to terminate running reports.

3826 5856-005 5–73


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

Arguments

• reportName: string

Name of the report

• stopReportFlags: StopReportFlags object

The object determines how any transaction in progress is handled. The StopReportFlags class exposes the following members.

Members of StopReportFlags class

• processId: string

Specifies the process ID of a report. This argument is optional. By default, this argument is set to “Null”.

Return Value


IAdministerSystem.TerminateReport Method

This method allows you to terminate an active report immediately.

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

Arguments


Name of the report

• stopType: StopType object

Name Description

StopDefault Does not rerun a report and any recovery information saved for the report is deleted, unless extended recovery is in use.

StopDiscard Reruns a report, attempting to recover up to and including any transaction it may have been processing when the StopReport method was triggered.

StopNormal Terminates running report.

StopRecover Does not rerun a report

Any recovery information saved for a report is deleted, unless extended recovery is in use.

StopTerminate Stops a report at the next critical point

5–74 3826 5856-005


The object determines how any transaction in progress is handled. The stopType class exposes the following members.

Members of stopType class

• processId: string

Specifies the process ID of a report.

This argument is optional. By default, this argument is set to “Null”.

Return Value


IAdministerSystem.WakeUpReport Method

This method allows you to wake up a report.

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

Arguments


Name of the report

• wakeUpParameters: string

Specifies a text to be passed to the report. This argument is optional.

Return Value


Using the IAdministerSystem Interface for the Report Administration Operations

Perform the following steps to use the interface for the report administration commands through C# example:


Name Description

DISCARD Does not rerun a report and any recovery information saved for a report is deleted.

NORECOVERY Does not rerun a report and any recovery information saved for a report is deleted, unless extended recovery is in use.

RECOVER Reruns a report, attempting to recover up to and including any transaction it may have been processing when the TerminateReport method was triggered.

3826 5856-005 5–75




3. Add the following code.namespace SampleReport{


class Program{


//Report operations

//Get the RuntimeSystem, GetSystem sets the securityIAdministerSystem sample = RuntimeFactory.GetSystem("SAMPLE");

//Get the callback object for report callbackCallBackHandler callBack = new CallBackHandler();

//Execute reportsample.RunReport("CUSTLIST", callBack);

//List Running ReportsIList<ReportInformation> reportsList = null;status = sample.ListRunningReports(out reportsList);


if (reportsList.Count > 0){

Console.WriteLine("USER NAME PID SID REPORTSTATUS");

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 areavailable");

}}

}}

}


Definition of the IAdministerSystem Interface

Following is the definition of the IAdministerSystem interface.

namespace Unisys.AgileBusiness.RuntimeAPI{public interface IAdministerSystem {

5–76 3826 5856-005


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 EnableSystem(); StatusInfo DisableSystem(); StatusInfo StopSystem([bool] disable = false); StatusInfo GetHubStatus(out bool isEnabled); StatusInfo EnableHub(); StatusInfo DisableHub(); 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 SendAMessage(string station, string message); StatusInfo SetAccountMonth([int highAccount = 0], [int lowAccount = 0]); 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 = ""]);

Troubleshooting Runtime API OperationsAll the log details from the Runtime API operations are logged in the RuntimeAPI.log file. By default, this log file is stored within the Data folder at

<Data Folder>\public\log

RuntimeAPI.log

The RuntimeAPI.log file is accessed each time Runtime API tasks are performed, either through the command line, or programmatically on the runtime server.

RuntimeAPI.xml Configuration File

You can configure the logging at the server level to capture details of Runtime API operations. The file is stored within the Data folder.

Note: It is recommended, you use the Configure Log Files utility to modify log configuration, unless suggested by the Unisys Support team to edit the file manually.

3826 5856-005 5–77


5–78 3826 5856-005

Section 6 Runtime Programming Interfaces

Segments and ispecs can be accessed directly through COM+ using interface methods.

The following sections describe the COM+ methods available for interfacing with an application:

• Segment COM+ Interface

• GenericClass COM+ Interface

Segment COM+ Interface The interface to the Business Segment object is through the ISegmentCycle interface. A description of this interface is shown below. The Connect(), Disconnect(), ProcessMsg() and CreateInstance() methods deal with the normal processing of user ispec client transaction messages.

Refer to Definition of ISegmentCycle Interface for a full description of the interface.

Refer to Unmanaged C++ Example or to Managed .NET C# Example.

Connect()

This method creates a new user session, which is used to maintain state information between ispec transactions. It will return an integer session identifier, which must be passed as a parameter to all subsequent ispec transaction method calls that are part of that session.

Method Description

Connect() Create a user session

Disconnect() End a user session

CreateInstance() Request an ispec

ProcessMsg() Process an input message for an ispec

Admin() Returns the IAdmin Interface

3826 5856-005 6–1

Runtime Programming Interfaces

A negative return value (for example, -999) indicates a Connect() error and a session has not been established. Examples of error codes are:

• -999 A session for this user already exists

• -998 A session cannot be established because a previous build resulted in a database reorganization error.

When you call Connect(), you can also pass in a pointer to an IMessages interface (as the first parameter). This interface points to an object in your own address space that is used to receive asynchronous messages and accepts. If you pass in NULL for this parameter, then you will not receive any messages or accepts. See section Handling Unsolicited Messages for more information.

The second parameter is a Boolean that indicates whether this is an “anonymous” login or not. If this parameter is set to TRUE then there will be no check for duplicate logins from the same user.

The third parameter is a Boolean that indicates whether to “force” a login for this user or not. Normally, when a Connect() request is made, a check is done to ensure that there is not already an open session for this user. If there is already an open session for this user the Connect() request will be rejected and will return a value of -999. However, if the bForceLogin parameter is set to TRUE the existing session for this user will be automatically disconnected and the new session will be established. This is useful in the situation where an “orphan” session has been left for the current user. This can happen if the client program crashes or exits without doing a Disconnect().

The fourth parameter is optional. A string can be passed and will be used as the “station name” and will be loaded into GLB.STATION.

Disconnect()

This method will terminate the current session. You must pass the ID of the session to terminate as a parameter.

CreateInstance()

This method is used to create an instance of an ispec. The session ID and the name of the ispec are passed as parameters. The system will create an instance of the ispec and “recall” it resulting in the ispec’s Construct() method being executed. An object referred to as a GenericClass object is returned. This object is used to pass information between a client and an ispec. It contains the values of all ispec fields, plus status line messages, error messages, etc.

6–2 3826 5856-005


ProcessMsg()

This method is used to perform a full ispec transaction. A GenericClass object is passed, containing the values of all ispec input fields. A full ispec cycle transaction will be executed, including the ispecs Prepare(), Main() and Construct() methods (if refreshing or recalled). A new GenericClass object representing the returned ispec will be passed back as a return value. This will be for the same ispec if it has recalled itself or refreshed, or another ispec if recalled. The values from all ispec output fields can be retrieved from this returned GenericClass object.

Admin()

This method returns the user the IAdmin interface. This interface exposes a several other methods that can be called as well, such as StopSystem, RunReport.

Handling Unsolicited Messages

This section describes the programming required to allow a client program to handle unsoliticed messages sent from the runtime application to the client. Examples of such messages are text messages sent to a session via the SendMessage LDL command or the :SMG colon command, output messages and accepts from Reports and the output from most other colon commands. For example, :LIS, :HEL, etc.

The following needs to be done to implement this functionality:

• Implement an IMessages object to receive the messages.

• Pass the IMessages object to the server in the Connect() call.

When the server has a message that is destined for this client session, it will be passed to the corresponding IMessages object, where it can be handled by the client and displayed to the user.

An optional step is to implement an ICallBack object to contain the implementation of the message handlers. This allows for a clean object-oriented design, where the IMessages class acts simply as an interface class that receives the messages and then passes them on to an ICallBack object that contains the full implementation for handling the display of messages and user input for Accepts. The example code below includes this structure.

IMessages Object

To be able to receive messages from an AB Suite user application you need to implement the IMessages interface that is defined in the NGSystem.tlb. This type library can be found in the AB Suite runtime Bin or Include folder. When a reference is added to this type library file, Visual Studio will generate an interop reference to NGLINC. The Visual Studio Object Browser will reveal all the interfaces that are available.

3826 5856-005 6–3


Here is an example C# implementation for this class:

class MessageObject : IMessages{ // This message object will construct a callback object that // will do all the work. The IMessages methods will // just pass the objects to the callback object. // protected ICallBack m_CallBack; public MessageObject( SampleClient pCaller ) { m_CallBack = new CallBackObject( pCaller ); } #region IMessages Members public void PutAccept( IAccept pIAccept, string prompt ) { m_CallBack.ReceiveAccept( pIAccept, prompt ); } public void PutCompletion( int Status ){ m_CallBack.ReceiveCompletion( Status ); } public void PutMessage( string message, MSGTYPE MSGTYPE ) { m_CallBack.ReceiveMessage( message, MSGTYPE ); } public void SetCallBack( ICallBack callBack ) { m_CallBack = callBack; } #endregion }

ICallBack Object

An ICallBack class should be implemented to handle the received messages. This is where most of the work is done to process the received messages.

Here is an example C# implementation for this class. This is for a simple console client. Received messages are written to the console and Accepts are handled by reading input from the console.

class CallBackObject : ICallBack { // This class handles the messages that the SampleClient receives // from the Sample system. In the implementation here, it will just write // to and read from the command-line. // protected SampleClient m_Caller; public CallBackObject( SampleClient pCaller ) { m_Caller = pCaller; } #region ICallBack Members // This method receives an IAccept object. Here, the method reads the user input // from the command-line and sends it back to Sample through the Reply method // public void ReceiveAccept( IAccept pIAccept, string prompt ) { Console.WriteLine( "CallBackObject received an Accept request" ); Console.Write( prompt ); string lReply = System.Console.ReadLine(); pIAccept.Reply( lReply );

6–4 3826 5856-005


} // // This method is called after the End-Of-Job notification from the Report. It is // used here to tell the SampleClient we are finished. // public void ReceiveCompletion( int pStatus ) { Console.WriteLine( "CallBackObject received a Completion indicator \’{0}\’", pStatus ); m_Caller.OnFinished(); } public void ReceiveMessage( string theMsg, MSGTYPE MSGTYPE ) { Console.WriteLine( "CallBackObject received a {0} message \"{1}\"", MSGTYPE, theMsg ); } #endregion }

Connect()

In the client start-up code, an instance of the IMessages class must be created (which will in turn create an instance of the ICallBack class). The IMessages object is then passed to the application as the first parameter in the Connect() call.

Here is an example C# implementation for this code:

// Create a IMessages implementation instance that will handle // the messages and Accept requests from the Sample system IMessages myMsgObject = new MessageObject( this ); // Finally, connect to Sample, pass MessageObject onto Sample and // store the SessionId. ISegmentCycle mySampleInterface = ( ISegmentCycle ) myBusinessObject; mySessionId = mySampleInterface.Connect( myMsgObject, false, false, null );

General Processing

Messages:

When the application has a message to send to this client, it will call PutMessage() on the corresponding IMessages object passing the message text as a string parameter.

PutMessage() will simply pass the message text on to the ICallBack object via the ReceiveMessage() call where the message string can be handled in any way required and displayed to the user.

Accepts:

When a report run from this client executes an Accept command the application will call PutAccept() on the client’s IMessage object. It will pass an IAccept object as the first parameter. PutAccept() will simply pass the parameters through to ICallBack.ReceiveAccept(). The implementation here is expected to take input from the user and return it to the report by calling the Reply() method on the IAccept object.

3826 5856-005 6–5


Completion:

When a report that has been run from this client goes to end-of-job the application will send a “completion” message to the client. It will do this by calling PutCompletion() on the corresponding IMessages object.

Using Messages COM Object to handle Unsolicited Messages

In addition to the methods that has been described, another way of handling unsolicited messages is using Messages COM object. The Messages COM object implements the IMessages interface required to be passed in the Connect method of the ISegmentCycle. You do not need to implement the IMessages interface as described in the previous sections. You must only implement the ICallBack interface in a class as described previously.

You should instantiate the CallBackObject class in your code and the pointer of the object must be passed to the SetCallBack method of the IMessages object. This ensures that the messages can be passed on to the CallBackObject by Messages COM object to be handled by you.

Following is the code and its description of using the Messages COM object to get user messages from an AB Suite system.

Native VC++ code…#import <…\bin\NGSystem.tlb> no_namespace raw_interfaces_onlyclass CallBackObject : public ICallBack{public:

…HRESULT __stdcall ReceiveMessage(BSTR message, MSGTYPE type){

wprintf(_T("%d: %s\n"), type, message);return S_OK;

}};int _tmain(int argc, _TCHAR* argv[]){

::CoInitializeEx(NULL, COINIT_MULTITHREADED);

HRESULT hr;CComPtr<IMessages> messenger;hr = messenger.CoCreateInstance(_T("Messenger.Messages.2.0.1"));CallBackObject callback;hr = messenger->SetCallBack(&callback);

CComPtr<ISegmentCycle> app;hr = app.CoCreateInstance(_T("Sample.1"));LONG sessId;

hr = app->Connect(messenger, VARIANT_FALSE, VARIANT_FALSE, _variant_t(NULL), &sessId);

…}

6–6 3826 5856-005


In this code, the CallBackObject is the class that implements the ICallBack interface as described in the “ICallBack Object” section previously. The implementation of ReceiveMessage is shown here for clarity.

Note: Unlike .NET Framework for C#, VC++ libraries do not provide a wrapper over COM classes, which implements the IUnknown methods. This requires the IUnknown interface methods to be implemented in the CallBackObject class.

In the main method, the first line initializes the COM library for the main thread. The function also sets the concurrency model of the main thread. The concurrency model set is, Multithreaded. See addendum at the end of the section for more information on the concurrency model of the application. An instance of the Messages COM object and an object of the CallBackObject class is created. The callback object is then passed to the SetCallBack method of the IMessages interface implemented by the Messages COM object. Subsequently, an instance of the AB Suite system is created and the Messages COM object is passed in the Connect method of the ISegmentCycle interface.

When AB Suite system sends a message through the Messages COM object stored in the AB Suite system, the Messages COM object forwards this message to the CallBackObject to be handled by CallBackObject. Similarly when there is an accept request by the system, the request is forwarded to the CallBackObject by the Messages COM object in the system.

Managed C# code

To use Messages COM object, the following assemblies must be added as references in the application: Interop.NGLINC and Interop.Messenger. These assemblies can be found in the bin folder of the AB Suite installation directory.

…using NGLINC;class CallBackObject : ICallBack{

…public void ReceiveMessage(string theMsg, MSGTYPE MSGTYPE){

Console.WriteLine(MSGTYPE.ToString() + ": " + theMsg);}

}[MTAThread]static void Main(string[] args){

IMessages messenger = new Messenger.MessagesClass();ICallBack callback = new CallBackObject ();messenger.SetCallBack(callback);ISegmentCycle testApp =

(ISegmentCycle)Activator.CreateInstance(Type.GetTypeFromProgID("Sample.1"));int sessionId = testApp.Connect(messenger, false, false, null);…

}

In the above code, the CallBackObject is the class that implements the ICallBack interface as described in the “ICallBack Object” section above. The ReceiveMessage implementation is shown here for clarity.

3826 5856-005 6–7


The MTAThread attribute of the main method sets the COM threading model of the main thread of the application to multithreaded apartment (MTA). See addendum at the end of the section for more information on threading model of an application. In the main method, an instance of the Messages COM object is created by using the MessagesClass class exposed by the Interop.Messenger.dll library. Then an object of CallBackObject class is created and passed in the SetCallBack method of the IMessages interface implemented by the Messages COM object. Finally, an instance of the AB Suite system is created and the Messages COM object is passed to the Connect method of the ISegmentCycle interface.

Whenever AB Suite system sends a message through the Messages COM object stored in the system, the Messages COM object forwards this message to the CallBackObject to be handled by it. Similarly when there is an accept request by the system, the request is forwarded to the CallBackObject by the Messages COM object in the system.

Addendum

The concurrency model orthreading model of the thread that creates the Messages COM object must be multithreaded. By making the concurrency model of the thread multithreaded, the Messages COM object is created in a multithreaded apartment (MTA). This is required because Messages COM object is passed to the AB Suite system COM object and accessed by other COM objects such as Report Session Manager, which are created in multithreaded apartments. The thread that creates the Messages COM object should be in multithreaded apartment.

If the concurrency model of the thread is set to single then Messages COM object is created in a single threaded apartment (STA). This can lead to cross-apartment synchronization problems when the object is passed to processes initialized in multithreaded apartments. These can cause the AB Suite system code to stop responding. For example, a report can hang while sending messages using the Messages COM object sent in the Connect method of the ISegmentCycle.

To ensure that the application does not hang, the thread that creates the Messages COM objects need to be set to multithreaded concurrency model orthreading model. In native VC++ code, do not use CoInitialize(NULL) function or COINIT_APARTMENTTHREADED concurrency model in CoInitializeEx() function to initialize the COM library in the thread that creates the Messages COM object. Use the CoInitialize(NULL) function as mentioned in the code. In C# code, do not use STAThread attribute in the main method or set the Thread.ApartmentState property to Apartmvfbb entState.STA in the thread that creates the Messages COM Object. Use MTAThread attribute in the main method or set the Thread.ApartmentState property to ApartmentState.MTA in any thread other than the main thread of the application. For more information, refer to, http://msdn.microsoft.com/en-us/library/system.threading.thread.apartmentstate.aspx.

6–8 3826 5856-005


Definition of ISegmentCycle Interface interface ISegmentCycle : IDispatch { HRESULT Connect( [in] IUnknown *pComms , [in, defaultvalue(0)] VARIANT_BOOL bIsAnonymous, [in, defaultvalue(0)] VARIANT_BOOL bForceLogin, [in,optional] VARIANT vStation, [out,retval] LONG *plSessId); HRESULT ProcessMsg( [in] LONG lSessId, [in] IDispatch *pdispInParams, [out,retval] IDispatch **pdispOutParams ); HRESULT Disconnect( [in] LONG lSessId ); HRESULT CreateInstance( [in] LONG lSessId, [in] BSTR bstrClassName, [out,retval] IUnknown **ppIspec ); HRESULT STDMETHODCALLTYPE get_Admin(/* [retval][out] */ IAdmin **pAdmin) = 0; };

GenericClass COM+ Interface The interface to the GenericClass object is through the IIspecCycle interface.

Refer to Definition of IIspecCycle Interface for a full description of the interface.

There are a number of other methods present on the IIspecCycle interface, however these are for internal use by the product and are therefore not described here.

Refer to Unmanaged C++ Example or to Managed .NET C# Example for details.

Method Description

SetValue() Set the value of an ispec field

GetValue() Get the value of an ispec field

SetArrayValue() Set the value of a copied or array ispec field

GetArrayValue() Get the value of a copied or array ispec field

GetNumMessages() Returns the number of status line or error messages

GetMessage() Returns a status or error message

GetMaxCopies() Returns the number of copies for a CopyIspec

GetNumDynamicLists() Returns the number of dynamic list objects

GetDynamicList() Returns a specified dynamic list object

Initialize() Initializes a GenericClass object

CreateCopy() Creates a new copy of a GenericClass object

GetSwitchToData() Returns true if a SwitchTo has been done

3826 5856-005 6–9


GenericClass Field Names

The names of the Ispec fields that are used in the GenericClass COM+ Interface are defined as a series of “Field Description Files” – one per Ispec. These field description files are XML files and are contained within a folder called Interfaces\ProtocolAdapters amongst the deployed system files. The XML file names have the format <ispec name>-FieldDesc.xml. These XML files are generated for each ispec as a part of the build process from Developer. The XML files contain details of an ispec transaction interface along with corresponding attributes and mask definitions if any. The GenericClass component creates a GenericClass object for each ispec at runtime. The GenericClass component passes transaction data including mask definitions if applied in the model. For more information about the configuration properties that can be used to enable a mask definition for an attribute, see the Agile Business Suite Developer User Guide.

For most user-defined Ispec fields, the name is simply the attribute name, for example, “NAME”, “ADDRESS”. The system-defined Ispec fields that appear on the top line of ispecs are all prefixed with an underscore, for example, “_ISPEC”, “_INPUT_DATE”, “_ACTMTH”, “_UserMAINT”. Inherited, inserted or aggregated fields have a name that is qualified with the class name and attribute name of the owning class and attribute. The dollar character ‘$’ is used as the qualification character. An example from the SAMPLE system is “ACTION_LINE$ACTION_LINE$ACTION”.

There are a number of special fields that are used to pass information via the GenericClass object. The names of these special fields begin and end with an exclamation character, for example, “!CURSOR!”. Some of the useful special fields are:

• !CURSOR! – Contains the name of the field in which the cursor should be placed.

• !CURSORCOPY! – When placing the cursor in a copied field, this contains the copy number.

• !ISPECALIAS! – The alias (i.e. short five-character name) of the Ispec.

• !TEACH! – The name of a Teach screen, if a Teach screen has been recalled.

• !TEACHALIAS! – The alias (i.e. short five-character name) of a Teach screen, if a Teach screen has been recalled.

• !LANGID! – The language ID in a multi-language system.

The value of these special fields can be retrieved via the GetValue() method. For example, pOutput->GetValue( L"!CURSOR!" );

SetValue()

This method is called to set the value of a field. The name of the field and a string value are passed as parameters.

6–10 3826 5856-005


GetValue()

This method is called to get the value of a field. The name of the field is passed as a parameter and the field value is returned as a string value.

SetArrayValue()

This method is called to set the value of a copied field. The name of the field, the index of the field to set, and a string value are passed as parameters. The index is zero-based, so to set the value for the first copy, use an index value of 0. For the second copy, use an index value of 1, and so on.

GetArrayValue()

This method is called to get the value of a copied field. The name of the field and the index of the field to get are passed as parameters and the field value is returned as a string value. The index is zero-based, so to get the value for the first copy, use an index value of 0. For the second copy, use an index value of 1, and so on.

GetNumMessages()

This method returns the number of messages. The status line message will be the first message. If the ispec generates more than one error message, this will return the number of error messages.

GetMessage()

This method returns a single message. The index of the required message is passed as a parameter. The index is zero-based, with the status line message always having an index of 0.

GetMaxCopies()

This method returns the total number of copies for a CopyIspec or CopyEvent i.e. the value of the Copies property for the CopyIspec.

GetNumDynamicLists()

If one or more dynamic listbox objects were created via the SendListDynamic LDL command during the execution of an ispec transaction, those listbox objects will be available in the returned GenericClass object.

This method returns the number of dynamic listbox objects that are present.

3826 5856-005 6–11


GetDynamicList()

If one or more dynamic listbox objects were created via the SendListDynamic LDL command during the execution of an ispec transaction, those listbox objects will be available in the returned GenericClass object.

This method can be used to retrieve a listbox object. The index of the required listbox is passed as a parameter. The index is zero-based, with the first listbox always having an index of 0.

The listbox object is returned as an IStream pointer containing the contents of the listbox. The first four bytes of each listbox row contains the number of bytes in that row. To process the listbox information in the IStream you should do the following:

• Read the first four bytes and convert to a number – this is the row length.

• Read the next <row length> bytes – this is the first row of listbox data

• Repeat until end-of-stream.

The following is sample Managed C++ code to retrieve and process a dynamic listbox object:

GenericClass::IStream* pList = pOutput->GetDynamicList(0); System::Runtime::InteropServices::ComTypes::IStream *managedList; managedList= __try_cast<System::Runtime::InteropServices::ComTypes::IStream*>(pList); System::Runtime::InteropServices::ComTypes::STATSTG stats; managedList->Stat(&stats, 0); String* listName = stats.pwcsName; do {

//read the first 4 bytes to find out the size of the following item. unsigned char buffer __gc[] = new unsigned char __gc[4]; System::IntPtr bytesRead = new int; managedList->Read(buffer, 4, bytesRead); unsigned int * bytesReadPtr = (unsigned int*)bytesRead.ToPointer(); if (*bytesReadPtr == 0) {

break; // EOF - break out of the loop } unsigned int rowLength = System::BitConverter::ToUInt32(buffer, 0);

//read the next <rowlength> bytes with the item into a String. buffer = new unsigned char __gc[rowLength]; managedList->Read(buffer, rowLength, bytesRead); bytesReadPtr = (unsigned int*)bytesRead.ToPointer(); System::String* rowData; Encoding * asciiChars = Encoding::ASCII; Char myChars[] = new Char[asciiChars->GetCharCount(buffer)]; asciiChars->GetChars(buffer, 0, buffer->Length, myChars, 0); rowData = new String(myChars);

// rowdata contains a single listbox file line - process it here. }

6–12 3826 5856-005


Initialize()

This method initializes a new GenericClass object for a specified ispec (name of the ispec class is passed as a string parameter).

The ISegmentCycle pointer is passed as the first parameter and a string containing the name of the ispec class is passed as the second parameter.

CreateCopy()

This method creates a new GenericClass object that is a copy of another GenericClass object.

The ISegmentCycle pointer is passed as the first parameter and the new GenericClass object will be returned as the return value.

GetSwitchToData()

This method is applicable only for AB Suite Windows Debugger systems. For AB Suite Windows Runtime System, refer to GetSwitchToData2().

If a SwitchTo LDL command has been executed to switch to a new Segment, then this method will return true, and will pass information about the new segment via parameters.

A reference to an ISegmentCycle pointer should be passed as the first parameter. This will point at the new Segment after returning. A reference to a string should be passed as the second parameter. This will contain the name of the new Segment after returning.

GetSwitchToData2()

If a SwitchTo LDL command has been executed to switch to a new Segment, then this method will return true, and will pass information about the new segment via parameters.

Syntax

STDMETHODIMP GenericClass::GetSwitchToData2( BSTR *pbstrGUID, BSTR *pbstrHost,BSTR *pbstrSystemName, BOOL *pbSwitched )

Parameters

pbstrGUID

This is a reference to the GUID pointer and will point at the GUID of the system to be switched after returning.

3826 5856-005 6–13


pbstrHost

This is a reference to the string containing the host machine name where the system is deployed after returning.

pbstrSystemName

This is a reference to a string containing the name of the new Segment after returning.

pbSwitched[out]

This Boolean value will be set to true if a valid SwitchTo command data is found otherwise it will be set to false.

Once this method is executed, an instance of the segment should be created using the GUID value and then can be used communicating with the switched system.

Example/// <summary> /// This method checks if there were any SwitchTo Command that was executed in the current Ispec transaction /// </summary> /// <param name="IspecOutput">Output GenericClass object of the ProcessMsg() method</param> /// <returns>0 if no SwitchTo happened, 1 if SwitchTo happened</returns> public int CheckSwitchTo(ref IIspecCycle IspecOutput) { int ret; string ispec; string guid; string host;string segmentname; ret = IspecOutput.GetSwitchToData2( out guid, out host, out newSegmentName); // if ret is 0 means where is no switchto happening, return if (ret == 0) return ret; // Disconnect the old systemTry { mySegmentCycle.Disconnect(sessid); NGLINC.ISegmentCycle iSegmentCycle = (NGLINC.ISegmentCycle)(mySegmentCycle); ((IDisposable)iSegmentCycle).Dispose(); } catch (Exception ex) { return 999; } Type tp = Type.GetTypeFromCLSID(gd, host, false); objApp = Activator.CreateInstance(tp); // mySegmentCycle is an object of NGLINC.ISegmentCycle mySegmentCycle = (ISegmentCycle)objApp;// Once this is done, call Connect() on mySegmentCycle to start using the switched system return 1; }

6–14 3826 5856-005


Definition of IIspecCycle Interface interface IIspecCycle : Idispatch { [id(1), helpstring("Initialize the GenericClass")] HRESULT Initialize([in] IUnknown* punkSegment, [in] BSTR bstrClassName ); [id(2), helpstring("Creates a copy of this GenericClass")] HRESULT CreateCopy([out,retval] IIspecCycle **pOutput); [id(3), helpstring("Set an attribute on the class")] HRESULT SetValue([in] BSTR bstrName, [in] BSTR bstrValue); [id(4), helpstring("Return the value of an attribute in the class")] HRESULT GetValue([in] BSTR bstrName, [out,retval] BSTR* pbstrValue); [id(5), helpstring("Processes the Ispec cycle")] HRESULT Process( LONG lSessId ); [id(6), helpstring("Converts a NOF buffer to this class")] HRESULT FromNof([in] SAFEARRAY(BYTE) saNofData, [in] LONG lcidNofData); [id(7), helpstring("Converts this class to a NOF buffer")] HRESULT ToNof([in] LONG lcidNofData, [out,retval] SAFEARRAY(BYTE) *psaNofData); [id(8), helpstring("Converts an XML document to this class")] HRESULT FromXml([in] IUnknown *punkSegment, [in] BSTR bstrXml); [id(9), helpstring("Converts an XML document to this class")] HRESULT FromXmlDom([in] MSXML2.IXMLDOMNode *pClassNode); [id(10), helpstring("Converts this class to an XML document")] HRESULT ToXml([out,retval] BSTR *pbstrXml); [id(11), helpstring("Converts this class to an XML document fragment")] HRESULT ToXmlDom([in] BSTR bstrNamespace, [in,out] MSXML2.IXMLDOMDocumentFragment *pDocFragment, [in,defaultvalue(0)] bool bIncTypes); [id(12), helpstring("Initialize the GenericClass with a parser type")] HRESULT Initialize2([in] IUnknown* punkSegment, [in] BSTR bstrClassName, [in] LONG lParserType, [in] BSTR bstrIspecFieldDescr ); [id(13), helpstring("Converts a GLI buffer to this class")] HRESULT FromGli([in] SAFEARRAY(BYTE) saGLIData, [in] LONG lcidGLIData); [id(14), helpstring("Converts this class to a GLI buffer")] HRESULT ToGli([in] LONG lcidGLIData, [out,retval] SAFEARRAY(BYTE) *psaGLIData); [id(15), helpstring("Sets a value in an array or copy.from region")] HRESULT SetArrayValue( [in] BSTR bstrName, [in] LONG lRowNumber, [in] BSTR bstrValue ); [id(16), helpstring("Returns a value in an array or copy.from region")] HRESULT GetArrayValue( [in] BSTR bstrName, [in] LONG lRowNumber, [out,retval] BSTR *pbstrValue ); [id(17), propget, helpstring("Returns the maximum number of copies in the copy.from region")] HRESULT MaxCopies( [out,retval] LONG *plNumCopies ); [id(18), propget, helpstring("Returns the number of messages we’ve got")] HRESULT NumMessages( [out,retval] LONG *plNumMessages ); [id(19), propget, helpstring("Returns the given message. The first message is the status line")] HRESULT Message( [in] LONG lMessage, [out,retval] BSTR *pbstrValue ); [id(20), helpstring("Appends a message to the list of messages we have")] HRESULT AppendMessage( [in] BSTR bstrMessage ); [id(21), helpstring("Clears the message queue in the object")] HRESULT ClearMessages(); [id(22), helpstring("Adds a dynamic list our internal list")] HRESULT AddDynamicList( [in] IStream *pList ); [id(23), propget, helpstring("Returns the number of lists we’re holding a reference to")] HRESULT NumDynamicLists( [out,retval] LONG *plNumLists ); [id(24), helpstring("Returns (and removes the reference to) the given list")] HRESULT GetDynamicList( [in] LONG lListNumber, [out,retval] IStream **ppList ); [id(25), helpstring("Clears the list of dynamic lists that we have a reference to")]

3826 5856-005 6–15


HRESULT ClearDynamicLists(); [id(26), propget, helpstring("Returns an integer describing whatever errors there were, or 0 if everything succeeded.")] HRESULT Error( [out,retval] LONG *plError ); [id(27), helpstring("Returns the data needed to switch to another application") HRESULT GetSwitchToData( [out] IUnknown **ppunkNewSegment, [out] BSTR *pbstrNewSystemName, [out,retval] BOOL *pbSwitched ); };

The following IIspecCycle methods have now been documented:

• GetMaxCopies()

• GetNumDynamicLists()

• GetDynamicList()

• Initialize()

• CreateCopy()

• GetSwitchToData()

There are a number of other methods present on the IIspecCycle interface, however these are for internal use by the product and are therefore not described.

Note: A number of the methods in the IIspecCycle interface are declared in the IDL definition as properties with the propget attribute. This means that the method is invoked by appending "Get" to the method name declared in the IDL definition. An example is the following:

[id(19), propget, helpstring("Returns the given message. The first message is the status line")]

HRESULT Message( [in] LONG lMessage, [out,retval] BSTR *pbstrValue );

To invoke this method you must use syntax like:

msg = pOutput->GetMessage(1);"

Processing Ispecs via the Segment COM Interface

This section describes the typical usage of the ISegmentCycle and IIspecCycle interfaces with an example using unmanaged C++ or Managed .NET C#.

Processing Ispec Messages

See the Unmanaged C++ Example and the Managed .NET C# Example.

The Connect() and Disconnect() methods are used solely to maintain ‘state’. They mark the beginning and end of a session. When you call the Connect() method, a unique integer session ID is returned.

6–16 3826 5856-005


In subsequent calls to CreateInstance() and ProcessMsg() you must pass the session ID so that the state for that session is restored for that message. Calling Disconnect() with the session ID will end the session and remove your state from the system.

When you call Connect(), you can also pass in a pointer to an IComms interface. This interface points to an object in your own address space that is used to receive asynchronous messages and accepts. If you pass in NULL for this parameter, then you will not receive any messages or accepts.

If you don’t want or don’t need to maintain state, you can simply call the ProcessMsg() method passing in 0 for the session id. In this case, you do not need to call Connect() or Disconnect(), but no state is maintained between transactions. You will also not get any messages or accepts (since the interface for receiving these is passed in via the Connect() method).

CreateInstance() can now be called to create an instance of an ispec, including the execution of the ispec’s Construct() method. A GenericClass object for this ispec is returned containing field values as initialized by the Construct() logic.

You can now call the SetValue() and/or SetArrayValue() methods to set values into individual fields. These methods are called once for each field that needs to be set with a value.

The ProcessMsg() method is now called to perform the ispec transaction. The GenericClass object that you have previously defined is passed as a parameter. This performs the full ispec cycle including automatic and user-defined logic, such as automatic editing, Prepare() logic, automatic lookups, Main() logic, etc. A GenericClass object representing the output ispec is passed as a return value.

Values from the returned ispec fields can be retrieved via calls to GetValue() and/or GetArrayValue().

Any messages generated by the ispec are returned in a messages array. The number of messages can be retrieved via GetNumMessages(). The normal ispec status-line message is always the first message in the array. Individual messages can be retrieved by calling GetMessage(), passing the index (zero-based) of the required message as a parameter.

Unmanaged C++ Example

Include the following headers:

#include "stdafx.h"#include <atlstr.h> // This is for the atl types

Add references to the following libraries and namespace reference

#import <NGSystem.tlb> no_namespace#import <GenericClass.dll> no_namespaceusing namespace std;

Define main method

3826 5856-005 6–17


int _tmain(int argc, _TCHAR* argv[]){

Define the ISegmentCycle COM interface pointer and create an instance of the segment component. In this case we are connecting to the SAMPLE.1 Component (the business segment of SAMPLE application)

CComPtr<ISegmentCycle> pSegment;HRESULT hr = ::CoInitialize(NULL); // initialise COM libraries hr = pSegment.CoCreateInstance( L"SAMPLE.1" );

Establish a session

long Sessid = pSegment->Connect(NULL, FALSE, FALSE);

Declare IIspecCycle interface pointers and call CreateInstance(). Here we are adding a Sales Rep to SAMPLE:

CComPtr<IIspecCycle> pInput, pOutput;pInput = CComQIPtr<IIspecCycle>(pSegment->CreateInstance(Sessid, L"SREP"));

Set values in ispec fields and process the transaction:

pInput->SetValue( L"_UserMAINT", L"ADD");pInput->SetValue( L"AREA", L"Asia");pInput->SetValue( L"NAM", L"John Smith");pInput->SetValue( L"SALESREP", L"1");

Retrieve output in the output interface pointer from the ProcessMsg call

pOutput = CComQIPtr<IIspecCycle>(pSegment->ProcessMsg( Sessid, pInput ));

Use the output interface pointer as the next input interface pointer to ensure transaction ID is correct

pInput = pOutput;

Process another transaction to retrieve the Sales Rep just entered

pInput->SetValue( L"_UserMAINT", L"INQ");pInput->SetValue( L"SALESREP", L"1");pOutput = CComQIPtr<IIspecCycle>(pSegment->ProcessMsg( Sessid, pInput ));std::cout << pOutput->GetValue( L"NAM" ); // Display entered Sales Rep on command line}

Disconnect the session

pSegment->Disconnect(Sessid);

Managed .NET C# Example

1. Deploy SAMPLE to your machine.

2. To create an instance of the segment, you will need to know the type name to create. You can find this from Component Services. Under COM+ Applications, find the application representing your system, and expand it to get to the component,

6–18 3826 5856-005


which could be named "<Segment name>.1". For example, "SAMPLE.1". Open the Properties and you will see the type name in the Description field on the General tab, which will be "<segment name>COMManager".

3. Create a new C# Windows Console Application in Microsoft Visual Studio.

4. Add references to the various assemblies and components that you will need when calling your application. As a minimum, you need to add:

• Interop.GenericClass (from <AB Suite Installation folder>\bin\CLR\bin folder)

• Interop.NGLINC (from <AB Suite Installation folder>\bin\CLR\bin folder)

• Interop.MSXML (from <AB Suite Installation folder>\bin\CLR\bin folder)

• System.EnterpriseServices (.NET assembly)

• Unisys.AgileBusiness.RuntimeFramework (from <AB Suite Installation folder>\bin\CLR\bin folder)

• <Segment>.dll, for example, SAMPLE.dll (from your deployed application folder)

• <Segment>COMManager.dll, for example, SAMPLECOMManager.dll (from your deployed application folder)

5. Add the following code to the Class to set and retrieve data into the Sample application.

using System; namespace SampleCaller

{ class Class1 { /// The main entry point for the application. [STAThread] static void Main(string[] args) { // Define the Sample object // This requires a reference to the Sample // application Type tp = Type.GetTypeFromProgID("Sample.1");

System.Object aSysInfoObject = Activator.CreateInstance(tp); NGLINC.ISegmentCycle sample = (NGLINC.ISegmentCycle)aSysInfoObject // Establish a session int sessId = sample.Connect(null, false, false, "MyMachine"); // Declare GenericClass objects and call // CreateInstance(): // Here we are adding a Sales Rep to SAMPLE GenericClass.IIspecCycle inParams = new GenericClass.GenericClassClass(); GenericClass.IIspecCycle outParams = new GenericClass.GenericClassClass(); inParams = (GenericClass.IIspecCycle) sample.CreateInstance(sessId, "SREP"); // Set values in ispec fields and process the // transaction: inParams.SetValue("_UserMaint", "ADD"); inParams.SetValue( "AREA", "Asia"); inParams.SetValue( "NAM", "John Smith");

3826 5856-005 6–19


inParams.SetValue( "SALESREP", "1"); // retrieve output in the output object from the // ProcessMsg call outParams = (GenericClass.IIspecCycle) sample.ProcessMsg(sessId, inParams); // Use the output object as the next input object // to ensure transaction_id is correct inParams = outParams; // Process another transaction to retrieve the // Sales Rep just entered inParams.SetValue("_UserMAINT","INQ"); inParams.SetValue("SALESREP","1"); outParams = (GenericClass.IIspecCycle) sample.ProcessMsg(sessId, inParams); System.Console.WriteLine(outParams.GetValue("NAM")); // Disconnect your open session sample.Disconnect(sessId); // Call administration methods NGLINC.IAdmin mySysAdmin = sample.Admin; Array arrReports = mySysAdmin.ListRunningReports(); for (int i = 0; i < arrReports.Length; i++) { if (null != arrReports.GetValue(i)) { string strValue = arrReports.GetValue(i).ToString().Trim(); System.Console.WriteLine(strValue); } } // Stop the system MySysAdmin.StopSystem(); } } }

6. Run the application. The SalesRep account relating to John Smith should appear on the command line.

Note: You have to manually delete this account before running this example again.

Calling Segment Methods User-defined methods implemented in the Segment class and with a public visibility are exposed via the Segment’s COM interface. These are available in an interface called I_<segment name>, for example I_SAMPLE.

Segment methods can be called directly and executed as stand-alone methods, that is. outside the ispec cycle. You do not need to have a current session active, so state information is not retained between calls to methods.

Parameters can be passed and values returned.

See the Unmanaged C++ Example and Managed .NET C# Example.

6–20 3826 5856-005


Unmanaged C++ Example

Import type libraries:

#import "NGSystem.tlb" no_namespace#import "genericclass.dll" no_namespace#import "C:\SAMPLE\Release\SAMPLE\Core\Bin\SAMPLE.tlb" no_namespace

Initialise COM libraries

HRESULT hr = ::CoInitialize(NULL);

Define the ISegmentCycle COM interface pointer and create an instance of the Segment component. In this case we are connecting to the SAMPLE.1 component (the Segment component for the SAMPLE application). The exact name of the component can be found by expanding the COM+ application in Component Services.

CComPtr<ISegmentCycle> pSegment;pSegment.CoCreateInstance( L"SAMPLE" );CComQIPtr<I_SAMPLE>pSAMPLE(pSegment);

Call the method:

_bstr_t CustomerId = L"123456";_bstr_t CustName = L"John Smith"; pSAMPLE->AddCustomer(CustomerId, CustName);

Managed .NET C# Example

1. Include Public methods in the Segment class, for example AddCustomer().

2. Create an instance of the segment. Use the <system>ComManager for this.

3. If you need to call public methods from another AB Suite system then you will need to first register the generated dlls into the GAC. You do not need to do this if calling public methods from languages like C#.

• Gacutil -i <system>.dll

• Gacutil -i <system>ComManager.dll

• Gacutil -i <system><shortId>_IF.dll

• Gacutil -i <system><shortId>-<n>.dll

where <system> is the system name, <shortId> is a two or three character identifier generated by ABS, and <n> is a number that represents the logic library dll's generated by AB Suite.

4. In your C# project, add references to the various assemblies and components that you will need when calling your application. As a minimum, you need to add:

• Interop.NGLINC (from <AB Suite Installation folder>\bin\CLR\bin folder)

• System.EnterpriseServices (.NET assembly)

• Unisys.AgileBusiness.RuntimeFramework (from <AB Suite Installation folder>\bin\CLR\bin folder)

3826 5856-005 6–21


• <segment>.dll (from your deployed application folder)

5. Create an instance of the segment:

I_Sample mySample = new SampleCOMManager() as I_Sample;

Call the method:

string CustomerId = "123456"; string CustName = "John Smith"; mySsample.AddCustomer( CustomerId, CustName ); External Call Helper

The External Call Helper is an AB Suite 4.0 Runtime COM+ application that handles calls from AB Suite 4.0 Runtime applications to external components defined as External Classes in the model. These External Classes can be executables, .dlls, shell commands, as well as other components. Data marshalling behavior between is defined by the configuration properties you set for the External Classes in your model. For more information see details in subsequent sections below.

External Call Helper controls access via the Program Runner's role. Users requiring access to external classes will need to be added to the Program Runner's role, using the Component Services applet in the Control Panel. Note that the External Call Helper uses the caller's credentials to invoke External Classes, so it is important to ensure that in addition to role membership, the caller is also provided with sufficient access rights to the files, directories and resources that you may want to access during an external call.

Using the Start command with non-administrative callers

The Start command makes use of the Program Runner role under the AB Suite External Call Helper. To ensure that users have sufficient privileges to use the Start command, ensure they are added to this role.

To execute the Start command through a non-administrative user, additional privileges will have to be provided explicitly. For example, if the RATL anonymous user is a non-administrative user, Start commands invoked by an anonymous connection might fail due to lack of privileges.

Consider the following example that explains the above scenario:

• RATL anonymous user is a non-administrative user.

• Logic implements the Start command that runs a BAT file, which in turn generates an output.txt file to a specified folder.

In this case, for the Start command to be executed, the RATL user needs to be added to the "Program Runner" role under AB Suite External Call Helper component through the Administration Tool.

This configuration would allow the user to execute the Start command, but is not sufficient to produce the required output. It will be seen that the BAT file will not generate the output.txt file. This is because, the anonymous user is not an administrator and would not have the write permission to direct the output file onto the

6–22 3826 5856-005


specified folder. On providing write and execute permissions to the user on the required folder, the output.txt file will be generated successfully on executing the Start command with the anonymous user.

Consider a second scenario, where the Start command needs to execute a script. The anonymous user fails to execute the script as the cscript.exe cannot be launched through a low privileged user. In this case, add the user to this program with Read & Execute permission enabled, as this would provide the required rights to run the script.

Method Interface for a Segment Method Parameter types for the segment method are shown in this table:

For example, if you had a segment method called PublicMethod which has an in

parameter of each type and an in/out parameter of each type, this is how that method would be generated into the IDL file.

HRESULT PublicMethod([in] BSTR _sg_StringIn, [in] BSTR _sg_WideStringIn, [in] DECIMAL _sg_NumberIn, [in] DECIMAL _sg_SignedNumberIn, [in] DATE _sg_DateIn, [in] VARIANT_BOOL _sg_BooleanIn, [in,out] BSTR * _sg_StringInOut, [in,out] BSTR * _sg_WideStringInOut, [in,out] DECIMAL * _sg_NumberInOut, [in,out] DECIMAL * _sg_SignedNumberInOut, [in,out] DATE * _sg_DateInOut, [in,out] VARIANT_BOOL * _sg_BooleanInOut);

Parameter Type In Parameter Out or Input Parameter

String BSTR BSTR*

Wide String BSTR BSTR*

Number DECIMAL DECIMAL*

Signed Number DECIMAL DECIMAL*

Date DATE DATE*

Boolean VARIANT_BOOL VARIANT_BOOL*

3826 5856-005 6–23


6–24 3826 5856-005

Section 7Using Protocol Adapters

Protocol adapters form a gateway between your application and external clients.

Protocol adapters appear as Windows services in the Services Control panel. They exist outside the application and can be started and stopped independently of the Runtime system.

They can be installed on the same machine as the application or on a different machine.

The following protocol adapters are covered in this section:

• SOAP over HTTP and SOAP over MSMQ

• RATL over TCP/IP and RATL over MSMQ

• HUB (External Automatic Entries)

• NOF/OFF/GLI

• USER (User Interface)

RATL, HUB, NOF/GLI/OFF, and USER are legacy protocols, which are used to communicate with existing Enterprise Application Environment applications, as well as Agile Business Suite applications.

SOAP over HTTP and SOAP over MSMQ The SOAP protocol is an international standard for exchanging data via the internet. See the World Wide Web Consortium’s Web services website for further details, http://www.w3.org/2002/ws/

SOAP is an XML based protocol which enables Web services clients to communicate with your application using an HTTP connection or Microsoft Message Queuing (MSMQ).

Both forms of this protocol enable the client to download the WSDL file for an application. The WSDL file contains all the information required for communication with your application and is created by the protocol adapter the first time a client makes a request. Thereafter it is cached for fast access.

See Configuring Protocol Adapters for further details on configuring SOAP in the Runtime Administration Tool.

3826 5856-005 7–1

Using Protocol Adapters

RATL over TCP/IP and RATL over MSMQ These protocols are used for communication between Component Enabler and your application. They use the RATL protocol through the Remote Access Server.

The RATL protocol is a simple wrapping of a standardized and extended set of NOF messages that provide all the functionality needed to support GUI forms.

See your Remote Access Guide for further details.

See Configuring Protocol Adapters for further details on configuring SOAP in the Runtime Administration Tool.

HUB (External Automatic Entries) HUB is a Unisys proprietary protocol that enables Agile Business Suite applications to communicate. It also enables Agile Business Suite applications to communicate with legacy Enterprise Application Environment applications.

Automatic entries between applications are referred to as external automatic entries. External automatic entries enable communications between Runtime for Windows Operating Systems and:

Other Runtime for Windows Operating Systems on other Windows servers.

Applications in ClearPath MCP, UNIX, and ClearPath OS 2200 environments, using TCP/IP

Notes:

1. In the event of a system failure, all transactions that are part of external automatic entries are fully recovered when you resubmit the transaction that initiated the external automatic entry.

2. External automatic entries using VPN (Virtual Private Network) are not supported.

If an ispec is specified as Automatic Entry Capable, it can receive data from internal automatic entries (from within the current application database), external automatic entries (from another Agile Business Suite-generated database), or through the screen layout.


• Preparing Projects in Developer

• Communicating with Other Hosts

• Sending External Automatic Entries

• How an External Automatic Entry Works

• Security Issues with External Automatic Entries

7–2 3826 5856-005


See Configuring Protocol Adapters for further details of configuring protocol adapters in the Runtime Administration Tool.

Preparing Projects in Developer

To prepare the projects of the destination and originating applications, perform the following procedures. These procedures apply to Agile Business Suite applications only.

Destination Application

For the destination application (receives automatic entries):

1. For each ispec that is to receive data, select True for the Automatic Entry Capable property.

2. Use the attributes Glb.Origin, Glb.Originhost, and Glb.Originenv to identify the source of a transaction, if necessary. See your Agile Business Suite online help for further details of built-in attributes.

3. Generate and deploy the application.

Originating Application

For the originating application (sends automatic entries):

1. Create an external class. This class must have the same attributes as the receiving ispec in the destination application.

Note: This class must not only have the same name, attributes as the receiving ispec class, but also must have the same Alias name as the receiving ispec class.

2. Decide whether to use two-phase commit. Set the Two Phase Commit configuration property for the segment. You can override this setting in logic, by using the attribute Glb.TwoPC.

3. In the logic of the class that initiates the external automatic entry, define the appropriate attributes, as follows:

For an external automatic entry to an application:

• Move the application view name defined in the Runtime Administration Tool into Glb.Destination.

• Assign the runtime SQL database name to Glb.Destenv.

• Move the runtime server IP or the host name for the destination application to Glb.Desthost.

• Use Glb.TwoPC to override the setting of two-phase commit, if required.

• Define attributes on an instance of the class and call the Send built-in method on that class.

• Test Glb.Status and Glb.Hubstatus for possible errors.

3826 5856-005 7–3


For an external Automatic Entry to a NOF program:

• Move Non Format to Glb.Destination.

• Move the name of a script to Glb.DestNoForm. The name must not contain period (.), hyphen (-), backslash (\), or slash (/) characters.

For an internal automatic entry, Glb.Destination is equal to Glb.Spaces or Glb.Self.

Refer to your Developer online help for details of the various built-in attributes.

Note: If communicating with an application created with Enterprise Application Environment 3.3, or earlier, you are limited to 2000 bytes when transferring data using external automatic entries.

4. Generate and deploy the originating application.

Communicating with Other Hosts

No additional steps are required to send external automatic entries or to communicate with applications on the same machine. However, if both EAE Windows and AB Suite Windows are installed on the same machine, to send external automatic entries, the following needs to be configured:

1. The EAE HubSocket should be running for Hubbing from AB Suite Windows to EAE Windows.

2. Similarly, AB Suite HubSocket should be running for Hubbing from EAE Windows to AB Suite Windows.

To receive external automatic entries from applications on other hosts, you must do the following on the Windows server:

• Start the HUB Protocol Adapter if communicating with non Agile Business Suite applications.

• Configure the other host(s) for HUB communications, as described in the documentation for the specific host type.

To HUB between two Agile Business Suite for Windows runtime applications on two different hosts, additional security settings are required:

• The two hosts have to be in the same domain.

• AppUser and AppAdminUser must be domain users and on both source and destination machines they need to have the same set of privileges as local Agile Business Suite users need.

• Distributed Transaction Coordination (DTC) has to be enabled for both machines.

To enable DTC, on each machine:

1. Start Administration Tool.

2. From the Console Root, select Component Services > Computers > My Computer > Distributed Transaction Coordinator.

7–4 3826 5856-005


3. Right-click Local DTC from the Distributed Transaction Coordinator folder and click Properties.

4. From the Security tab in the Local DTC Properties dialog box, select Network DTC Access, Allow Inbound, Allow Outbound, No Authentication Required.

• For Service Pack 1, select Network DTC Access, Network Transactions.

• For Service Pack 2, select Network DTC Access, Allow Inbound, Allow Outbound, No Authentication Required.

For external automatic entries between Windows operating systems and most other host types, the default TCP/IP port number is 6001. Use the Runtime Administration Tool to change the default port number of the HUB protocol adapter. All hosts in the HUB ring must use the same port number.

Note: For external automatic entries between Windows operating systems and ClearPath OS 2200 hosts, the Windows operating system host HUB protocol adapter automatically uses the port number that is one higher than the Port Number defined in the Administration Tool. Ensure the TCP/IP port number on the Windows operating system host is the same as the lower TCP/IP port number on the ClearPath OS 2200 host. The default port numbers on the ClearPath OS 2200 host are 6001 and 6002. For details on changing the default port numbers on your OS 2200 host, see your Unisys Enterprise Application Runtime for ClearPath OS 2200 Administration Guide. If you change the default port numbers, the second port number must be one higher than the lower port number (for example, if the lower port number is 7001, the second port number must be 7002).

Sending External Automatic Entries

To send external automatic entries, perform the following steps for the originating and destination applications:

1. For both the originating and destination applications, enable external automatic entries by checking the Enable HUB checkbox on the HUB tab of the System Configuration dialog box in the Runtime Administration Tool, or using the IsHubEnabled method.

2. If the destination application is a non-Agile Business Suite application, start the HubSocket service.

3. If the destination application is an Agile Business Suite application, a view name must be specified for the destination application. See Views below for further details.

When a transaction is sent, the originating application is suspended while waiting for a response from the external automatic entry.

How an External Automatic Entry Works

The following sections detail the process of sending an external automatic entry.

3826 5856-005 7–5


Message is Assembled

The Send built-in persistent class method packages the attributes of the external class and sends them to the destination application.

An external automatic entry requires that both applications recognize all the attributes being used in the message. Therefore, the following must apply:

• In the originating application, the direction of the attributes must be defined as input-output in order to be valid in both the auto entry buffer and the video buffer.

• In the destination application, the attributes can have their direction defined as either input or input-output in order to be valid.

Message is Sent

The Send built-in persistent class method transfers the message in the auto entry buffer, as required, to:

• The HUB server of applications on the same host.

• Applications on other hosts, for non-Agile Business Suite applications using the HUB Listener service/HUB Socket protocol adapter.

Message is Processed

In the destination application, the message is processed as if it were normal screen input. A value for the built-in attribute Maint may need to be supplied.

Note: External automatic entries use the same value of Glb.Priv as the originating user account.

All logic is processed, except for construct logic.

Note: This is different from internal automatic entries, where the logic of the receiving ispec is not performed.

Within the destination ispec, a recall (using the Recall command) of a different ispec is ignored. A recall of the same ispec causes a reply to be returned to the originating application. If Glb.Error is set to “*****”, an error is returned when processing is complete.

CautionThe destination ispec may initiate automatic entry transactions to other ispecs. Any resulting chain of automatic entry transactions must not be cyclical. See Series of Automatic Entries in Security Issues with External Automatic Entries

7–6 3826 5856-005


Replies are Received

The response is received in the auto entry buffer of the originating application. Information regarding the result of the external automatic entry is contained in Glb.Status and Glb.Hubstatus.

Security Issues with External Automatic Entries

You can use Glb.Status and Glb.Hubstatus to determine failure of security checks. See your Developer online help for details of built-in attributes.

There are two types of commitment available to external automatic entries: immediate commit or two-phase commit.

Immediate Commit

With immediate commitment, destination applications make (commit) all changes immediately, as follows:

1. The originating application sends an external automatic entry.

2. The destination application attempts to commit the changes.

3. The originating application commits or aborts its changes as appropriate.

Note: If the originating application sends multiple automatic entries to the same destination application, each automatic entry is treated as a separate transaction.

Two-phase Commit

Two phase commitment ensures that all destination applications are able to commit all changes before any of these applications (including the originating application) commit.

With two-phase commitment:

1. The originating application sends an external automatic entry.

2. The destination application determines whether it is able to make (commit) the changes. It processes the transactions, but does not commit the changes to its database.

3. The destination application sends a message to the originating application to commit the changes.

4. If the destination application is able to commit, the originating application sends a message to the destination application to commit the changes.

If the destination application is not able to commit, the originating application sends a message to the destination application to abort the changes.

5. The originating application then commits or aborts its changes as appropriate.

Note: If the originating application sends multiple automatic entries to the same destination application, all of the automatic entries are treated as a single transaction.

3826 5856-005 7–7


Using Two-Phase Commit for HUB

To achive Two-Phase-Commit transactions for HUB in AB Suite Runtime Systems, the Transaction Support property should be set to Required. By default it is Requires New. To change this value to Required perform the following:

1. In Component Services console, expand the COM Component of the deployed system.

2. Right-click the COM Component, and select Properties. The Properties window appears.

3. In the Transactions tab, select Required for the Transactions Support field.


Note: HUB transactions time out in one minute. To override this, select the Override global transaction timeout value option in the Properties window.

Series of Automatic Entries

It is possible that an external automatic entry from the originating application causes another external Automatic Entry from the destination application.

To define the requirements for each application, consider the applications as originating and destination application pairs. Ensure that each application fulfills its role as an originating and destination application.

It is recommended that you use a two-phase commit in this situation. This ensures atomicity, that is, either all automatic entries succeed, or all fail.

Note: Closed cycles (where a destination is one of the originating applications) result in an error. Glb.Status is set to “*****” and Glb.Hubstatus is set to Cycle.Error.

USER (User Interface) The USER protocol enables users to create a custom subprogram that can be called from logic to communicate with an external system. A sample file, USER.cpp, is supplied with the Runtime installation.

The User Interface facility enables an application to initiate a transaction to another type of system, and to receive a response from that system. The User Interface provided with Runtime for Windows Operating Systems allows the user to create a C++ subprogram that does the following:

1. Receives data from the application through the logic of an ispec or report. The ispec or report sets Glb.Destination to USER.EXE (or NON.LINC), then sends the data using the Send built-in persistent class method.

2. Processes the received data. This may include calls to other types of systems.

3. Returns the result of the processing to the application.

7–8 3826 5856-005


A graphical representation of the User interface is shown below:

User Interface

The user-supplied C++ program must be called USER. It performs the following functions:

1. Receives a transaction from the application through the logic of an ispec or report. The transaction is formatted as an XML document, and piped into the USER program’s stdin.

2. Constructs the transaction in the format required by the external system, then passes it to that system for processing.

3. Waits for a response from the external system.

4. Constructs the response into an XML format and writes it to stdout.

The User facility handles a single transaction at a time. Processing within the originating ispec or report is suspended until a reply is received.

The User facility can be used in conjunction with NOF (or GLI) to create a two-way interface.

The following topic is covered in this section:

• Sending a Transaction

• Sample User Program

Sending a Transaction

To send a transaction, move the value USER.EXE (or NON.LINC) into Glb.Destination. The transaction is sent using the Send built-in persistent class method, in the same way as a transaction is sent to another system by way of an external automatic entry.

The application waits for a reply from the external application. This may contain data in response to an inquiry. Glb.Status and Glb.Priv are set the same as for external automatic entries.

Sample User Program

A sample C++ User program, USER.cpp, is provided in the SAMPLE folder of your installation directory. This file contains extensive comments containing all the detail required to modify and use the program.

3826 5856-005 7–9


You can compile the program to USER.exe. It is your responsibility to ensure that the program functions correctly.

NOF/OFF/GLI These are Unisys proprietary interfaces which are supplied primarily for communication with legacy clients. A client program is supplied for each interface with the Runtime installation. They each use their own specific protocol to communicate between the client and server. The three client programs take either individual lines from the standard input or complete files of data.

NOF – The Non-Formatted Input/Output (NOF.exe) interface enables an external program to send NOF input to, and receive standard output from, your application.

OFF – The Offline input client program (OFF.exe) is used to load OFF data into a target application. OFF only transfers input, the protocol does not support output

GLI – The Generalized Interface (GLI.exe) facility provides a GLI interface into an application.

The use of each of these protocols is described in the following subsections.

The following syntax is used to invoke the interfaces:

<prog>.exe --host[<hostname>] --view[<viewname>] [<input>]

Note: --host can be replaced with –h and --view can be replaced with –v.

Where:

Non-Formatted Input/Output (NOF)

The Non-Formatted Input/Output (NOF) interface is a means by which an external program can send input to, and receive standard output from, your application. NOF is a flexible method for communicating with a system, where multiple transactions can be in process at the same time. With the NOF programmatic interface, both participants in the interface can initiate transactions. The NOF interface method has the following feature:

Parameter Description

<prog> Either NOF, GLI, or OFF depending on the type of packets you are sending.

<hostname> The name of the machine to which you are sending the packets. If this parameter is omitted, then localhost is the default.

<viewname> The view with which you want to connect.

<input> Command line input that is read by <prog>.exe. It is possible to pipe a file containing NOF, OFF, or GLI data.

7–10 3826 5856-005


Sending NOF program.

An external program can initiate a transaction to an application, and the application will return a response.

NOF enables you to input transactions into an application from any source defined in that program, and receive any resulting output in a predetermined but unformatted layout. You can rearrange this output for use in your application.

Communication between the application and an external system are handled by the NOF program, as shown in the figure below:

Non-Formatted Input/Output (NOF) Interface

The NOF.exe file is included as part of the Runtime installation and is located in the Bin folder of your installation directory. You can copy this file to any client machine, and as long as the host name of the server is specified, it will run correctly.

Note: The preferred method for providing user-written, custom access from a client program to Runtime for Windows Operating Systems is to use Component Enabler. The NOF Client Interface functionality is included in Component Enabler, which uses the Remote Access Server.

Invoking the NOF Program

The NOF program will transfer all data from standard input directly to the application. The data will not be formatted in any way by the NOF program, so you need to enter the records in the required format.


NOF.exe --host[<hostname>] --view[<viewname>] [<input>]


Where:




<input> Command line input that is read by NOF.exe. It is possible to pipe a file containing NOF data

3826 5856-005 7–11


The program waits for your input. Entering any random string (for example, Hello) results in an error because the string is not in the required format.

The following string is in the correct format:

CUST T00002524AUG999908FIR

If you enter this string but you have not populated the CUST ispec (to which it refers) with data, you receive the following message; ** ITEM NOT FOUND **.

Enter BYE to exit the program.

Note: Ensure that the last four digits of the formatted input correspond to the current account month (in the format YYMM) otherwise you will receive an error. The preceding digits, representing a full date, are not important.

Use NOF to access Ispec data

You can also pipe input data and output it as follows:

NOF -v SampleView <NOF.IN>NOF.OUT

An example of the contents of NOF.IN might look like:

CUST T00002524AUG999908FIR CUST T00002624AUG999908NEX CUST T00002724AUG999908INQ 2 CUST T00002824AUG999908NEX CUST T00002924AUG999908LAS BYE

The output from this data would appear as follows:

CUST T00006224AUG999908FIR 1 Customer #1 10001 APos APostal Addr 1 of 1 Postal Addr 2 of 1 Postal Addr 3 of 1 Delivery Addr 1 of 1 Delivery Addr 2 of 1 Delivery Addr 3 of 1 @ 15:53:48:22 INQUIRY REQUEST 0.00 ISPEC CUST CUST T00006324AUG999908NEX 1 Customer #1 10001 APos tal Addr 1 of 1 Postal Addr 2 of 1 Postal Addr 3 of 1 Delivery Addr 1 of 1 Delivery Addr 2 of 1 Delivery Addr 3 of 1 @ 15:53:48:16 INQUIRY REQUEST 0.00 ISPEC CUST CUST T00006424AUG999908NEX 1 Customer #1 10001 APos tal Addr 1 of 1 Postal Addr 2 of 1 Postal Addr 3 of 1 Delivery Addr 1 of 1 Delivery Addr 2 of 1 Delivery Addr 3 of 1 @ 15:53:48:17 INQUIRY REQUEST 0.00 ISPEC CUST CUST T00006524AUG999908LAS 2 Customer #2 10001 APos tal Addr 1 of 2 Postal Addr 2 of 2 Postal Addr 3 of 2Delivery Addr 1 of 2 Delivery Addr 2 of 2 Delivery Addr 3 of 2 @ 15:53:48:23 INQUIRY REQUEST 0.00 ISPEC CUST BYE GOOD BYE

7–12 3826 5856-005


You can use the ADD command to add data, but it must be in the correct format to avoid misplacement.

Data Format Sent to an Application from a Sending NOF Program

The following types of output format can be sent from the NOF program to the application:

• Output for administration commands

• Output for ispecs

• Output for copyispecs

• Other output

Output for Administration Commands

For an administration command:

• Output consists of the command and its parameters.

• The first character must be a colon.

Output for Ispecs

The first five characters of the transaction identify the ispec. In earlier versions, ispec names were limited to a maximum of five characters which meant that the ispec field in the NOF format had length equal to five. In Agile Business Suite, full ispec names can be up to 65 characters in length. However, to maintain backwards compatibility, the NOF format continues to allow only five characters for the ispec name, and will therefore use the ispec Alias value (which is limited to five characters) to identify the ispec.

Use the ispec name ROC_I to access the Report Output Control system (ROC).

The sixth character (stored in the attribute Glb.Source) specifies the type of transaction, and must be one of the values shown in the following table:

Screen data for ispecs must be in the following form:

number date month [ maint ] data

Value Type of Transaction

N Recall ispec screen.

T Send ispec screen using the screen data that follows (details below).

Space Recall Teach screen using Teach screen name that follows.

3826 5856-005 7–13


Details of these values are given in the following table:

Obtain the required format from the Field Description file for each ispec. These files are generated into the Interfaces\ProtocolAdapters folder and have names such as <ispec>-FieldDesc.xml, for example CUST FieldDesc.xml. The start property defines the relative starting position for each attribute in the NOF format.

Note: In the Field Description file, the Ispec field is defined as length=65, which is the full length of an ispec name in the model. The start property value in the Field Description file for subsequent fields is based upon this length. However, in the actual NOF format, only five characters are allowed for the ispec name. Therefore, you must subtract 60 from the start property value of each field after the name to determine the actual starting position of that field in a NOF message.

For copied attributes, the start property will define the starting position of the first copy of that attribute. To find the starting position of the next copy, you need to add the length of this block of contiguous copied attributes to the start position of the first copy.

Output for CopyIspecs

The NOF format for CopyIspecs in a system migrated from EAE 3.x is identical to that in EAE 3.x, maintaining “safe passage”.

However, as changes are made to these ispecs (for example, copied attributes added) the order in which these copied attributes are positioned within the NOF message is different.

Message order for EAE 3.x

In EAE 3.x, all copied data items were contained in a single contiguous block in the NOF message. The layout of these fields in the NOF message is:

<1st copy of all copied fields><2nd copy of all copied fields><subsequent copies, etc.>

For example, if we have an ispec with 3 copies and with the following data items:

DA-BEFORE – before the copied ispecs

Value Meaning

number Transaction number to be stored in the built-in attribute TranNo.

date Date (in the format DDMMMYY) to be stored in the built-in attribute Input_Date.

month Account month (in the format YYMM) to be stored in the built-in attribute ActMth.

maint Maintenance value, for ispecs that have one or more key fields, to be stored in the built-in attribute Maint.

data Values of the various ispec attributes.

7–14 3826 5856-005


CF-DATA1 – for the copied ispecs

CF-DATA2 – for the copied ispecs

DA-AFTER – after the copied ispecs

Where, DA is data and CF are copied fields.

The NOF message format for this ispec would be:

<DA-BEFORE><CF-DATA1><CF-DATA2><CF-DATA1><CF-DATA2><CF-DATA1><CF-DATA2><DA-AFTER>

<----first copy----><----second copy---><----third copy---->

Message order for Agile Business Suite

In Agile Business Suite, copied attributes do not have to be contiguous in the NOF message. You can assign any NOF order value to any attribute, and this value will determine its relative position in the NOF message. It is possible to have non-copied attributes interleaved with copied attributes.

The layout of copied attributes in the NOF message follows the same rules as in EAE 3.x for each block of one or more contiguous copied attributes. It is possible to have multiple blocks of contiguous copied attributes in the NOF message. Each block will follow the rules above, that is they will have the first copy of all copied attributes in the block followed by the second copy of all copied attributes in the block, and so on.

For example, if we have the following NOF order:

DA 1NOF Order=1

C_DA2NOF Order=2, copied 3 times


DA 4NOF Order=4


DA 6NOF Order=6

The NOF message format would be:

<DA1><C_DA2><C_DA3><C_DA2><C_DA3><C_DA2><C_DA3><DA4><C_DA5><C_DA5><C_DA5><DA6>

<--1st copy--><--2nd copy--><--3rd copy--> <-1st-><-2nd-><-3rd->

Other Output

There are two types of other output to the application:

• Sign on to the application (displays Fireup Ispec screen) HI

3826 5856-005 7–15


This returns the Fireup Ispec screen.

• Sign off from the application: BYE

This returns a status line message of GOOD BYE.

See Data Format Returned From an Application for further details.

Position of attributes with Direction=Out (equivalent of Usage INQUIRY)

All attributes with a Direction value of “Out” will be grouped together at the end of the NOF message. This group of attributes will be sorted according to their NOF order value. Therefore, the generalized layout of a NOF message will be:

1. All Direction=In and Direction=InOut attributes sorted according to NOF order

2. All Direction=Out attributes sorted according to NOF order

An important exception to this general rule is for Copied attributes with Direction=Out – these attributes are sorted within the “In” and “InOut” attributes according to NOF order.

Data Format Returned From an Application

Different types of input format are produced by the application for the NOF program. The sixth character of the transaction indicates the input format. The types of format are described in the following table:

Automatic Entry Messages

If the sixth character is A, the transaction has resulted in an external automatic entry from the application in the following format:

ispec A screendata

Here ispec is the five-character Alternate Name defined for the ispec in Developer. For the format of the ispec screen data value screendata, see Data Format Sent to an Application from a Sending NOF Program.

Value Transaction

A Data sent by external Automatic Entry (HUB)

T Ispec screen (transaction)

& End of transaction

S Error, status line, system command, report reply, or teach screen

B Listbox

O Hub header

7–16 3826 5856-005


This reply is unusual in that it does not signal the end of a transaction sent by the NOF program. It can only occur if GLB.DestNoForm is set to spaces in the application.

To handle this reply, the NOF program must:

• Process the data, and return a response to the application, the same code is used for both receiving and sending NOF programs.

• Wait for a reply to the original transaction (that initiated the automatic entry).

Ispec Screen

If the sixth character is T, the response is an ispec selection, in the following format:

ispec T screendata status

Eighty bytes are sent for the status line status. See Data Format Sent to an Application from a Sending NOF Program for the format of the Ispec screen data value screendata. You should use the value of TranNo returned from the application as the value for TranNo for the next transaction you send to the application.

End of Message

If the sixth character is an ampersand (&), the response is end-of-transaction, in the format, &&&&&&.

Hub Header

If the sixth character is a zero (0), the response is a universal HUB header, which precedes all automatic entries. It is provided for information purposes only. The HUB header includes information on the source and associated attributes of the request. Refer to the NOF sample program for details of the HUB-HEADER format.

If the sixth character is B, the response is listbox data:

• For static listboxes, the format is: SLISTBOOlistboxfile

The listbox name listbox is 23 characters, while the listbox file name file is 256 characters.

• For dynamic listboxes, the format is: DLISTBnndata

Where, nn is the number of listbox data definitions, and data is:

sequencedefinition

Where, sequence is a single character indicating which data buffer is being processed, as outlined in the following table:

Sequence Meaning

S Start (first) buffer

3826 5856-005 7–17


Each definition is in the following form:

namenumberrecords

Where, name is the listbox name, number is the number of records, and records is a number of listbox values, each in the following form:

sizedelimitervaluedelimiterdescription

Other Messages

If the sixth character is S, the response may be one of the following:

• Application termination message: BYE S01status

Eighty bytes are sent for the status line status.

• Response to an administration command: COLONSnnlines

Eighty bytes are sent for each of up to 24 status lines lines, with nn giving the number of lines (in the range 01 through 24).

• Error messages or multiple Message commands: ERRORSnnlines

Eighty bytes are sent for each of up to 19 status lines lines, with nn giving the number of lines (in the range 01 through 19).

• Reply from a Report: REPLYS01message

Eighty bytes are sent for the message.

• Request for input from a Report (run with the administration command :RUN): REPLYS01>

• Status line message: STATUS01status

Eighty bytes are sent for the status line.

• Switch to a new application: SWTCHSnnSystem

Returns the name of the application switched to ROC (for the Report Output Control system).

• Response to request for a Teach screen: TEACHSnnlines

Eighty bytes are sent for each of up to twenty-four status lines lines, with nn giving the number of lines (in the range 01 through 24).

E End (first) buffer

O Only buffer

0 Middle buffer

Sequence Meaning

7–18 3826 5856-005


GLI (Generalized Interfaces)

The Generalized Interface (GLI) facility provides an interface into an application.

The GLI client is an executable command, which reads the command line input, parses the input buffer, and uses the view name, passed as one of the parameter to get the system information. The GLI program (GLI.exe) accepts input formatted for GLI from stdin and sends it to the target system. Responses are returned to the GLI program and echoed to stdout. Some error conditions may be noted in stderr.

You can use GLI with your own applications by piping your application's stdout into the GLI program (GLI.EXE), and redirecting stdout and stderr back into your application. Using this technique, your application is in control of the interaction with the target system.

GLI input format uses commands and keywords in a freeform style. A graphical representation of GLI is shown below:

GLI (Generalized Interface)

When GLI data is passed to the application, edit checks are performed on the data.

The value of Glb.Stn is GLI for data entered through the Generalized Interface. The value of Glb.Source is G. GLI is assigned the same value of Glb.Priv as for the initiating username. Glb.Work is also available for use in GLI.

Note: If the source data is already correctly formatted and error free, it is much more efficient to use NOF for large amounts of data.

• Running the GLI Program

• Using the GLI Program

• GLI Input

• GLI Output

• GLI Recovery

Running the GLI Program

The GLI program can be located on the server running the application or on any other client machine as long as the host name of the server is specified.

3826 5856-005 7–19


The GLI program can be run from a Windows command prompt using the following syntax:

<GLI>.exe --view[<viewname>] [<input>]

Note: --view can be replaced with –v.

Where:

The content of the input file must be in the format acceptable to GLI. See GLI Input for further details.

Using the GLI Program

The GLI program can be run from a Windows command prompt using the following syntax:

GLI -v/--view ViewName | --help

Where:

The input can be entered through the command line once the program has been started or it can be read from a file. Similarly output can be redirected to a file. The syntax of reading the input through the file and resulted output directed to a file:

GLI -v ViewName <C:\GLIin.txt >C:\GLIout.txt 2>C:\GLIerror.txt

• Input is read from GLIin.txt

• The acknowledgment and the error messages are written to the GLIout.txt or the standard output

• Detailed error messages are moved to GLIerror.txt.

GLI Input

There are four valid types of input record. The GLI input (file) must supply records in the following order:



<input> Command line input that is read by GLI.exe. It is possible to pipe a file containing GLI data.


--help Shows the user the usage of GLI and details of all the parameters used by GLI.exe

-v /--view ViewName. Specifies the view that will process the input

7–20 3826 5856-005


1. Header records

2. Ispec

3. Data

4. Finish records

Each record may contain up to 4150 characters. The first six characters of each record identify the record type.

If a header record or an ispec record is accepted, the message OK is returned.

If there is an error in the header record or an ispec record, the message FATAL is returned and the program terminates. All data preceding the error will have been successfully loaded.

Note: When GLI input reaches ten or more validation errors, no additional input is recorded in the database. Moving spaces to Glb.Error does not prevent this from occurring.

Header Record

The header record defines the origin, destination, and source of the data, as well as various attributes detailing the handling of messages and errors.

A header record is mandatory and must be the first record supplied to the GLI program after execution.

The first six characters of the header record must be the word HEADER. The remaining positions contain header attributes and their operands. Header attributes can be included in any order separated by spaces. All header attributes except LOG; are mandatory. The header record may not be continued over multiple lines.

Valid header attributes and their abbreviations are detailed in the following table:

Header Attribute Abbr. Description

DESTINATION; DES; Specifies the name of the database to be updated.

ORIGIN; ORI; Specifies an alphanumeric string of up to eight characters for identification.

SOURCE; SR; Gives a description of the source of the input, for your documentation purposes.

REQD.ACK; RQA; Specifies whether you want an acknowledgment for each transaction to be passed back to the source of the input through standard output. Valid operands are YES (Y) and NO (N).

If YES is entered, acknowledgment messages are returned to the input source. Messages can have the following values: OK, NOT OK, and FATAL. A fatal error causes GLI to terminate immediately.

REQD.ACK;Y is required if ERROR.MSG;Y is specified.

3826 5856-005 7–21


Example of a header record:

HEADER DES;XXXSYS SR;PROG ORI;ZZZSYS ERM;Y RQA;Y LOG;Y

Ispec Record

The ispec record specifies the ispec to be updated, and defines the format of the data in any later data records. Attributes are validated against the corresponding ispec in the application.

The data may be in one of two forms:

• Unformatted

When the data is unformatted, attributes to be loaded by GLI are defined in the ispec record. Definitions must be included in the same order as the values in any later data records for that ispec. This order is not necessarily the same order as in the attribute. Attributes not included in the record are set to blanks or zeros in the application.

Attributes in copy classes should be included only once.

• Formatted

When the data is already formatted for input to the application, the conversion performed by GLI may be bypassed. The required format must be that contained in the Field Description file (in the application directory), except that values for the built-in attributes TranNo and Input_Date must not be provided.

Defining an Ispec Record for Formatted Data

The first five characters of the ispec record must be the word ISPEC, and the sixth character must be a space.

ERROR.MSG; ERM; Specifies whether error messages are to be passed back to the source of the input (through standard output). Valid operands are YES (Y) and NO (N). REQD.ACK;Y is required if ERROR.MSG;Y is set.

If error messages are being returned to the input source, the end of each transaction is indicated by a single status message with a value of OK, NOT OK, or FATAL.

If a transaction incurs errors, all of the errors are returned to the source of the input. When all errors have been returned, the message NOT OK is returned. All error messages returned after an OK or NOT OK message and before the next NOT OK or FATAL message relate to a single transaction.

A FATAL message is returned if GLI encounters a severe error, and GLI terminates immediately.

LOG; Optional attribute which specifies whether GLI will produce a printed log of errors to standard error. Valid operands are YES (Y) and the default NO (N).

Header Attribute Abbr. Description

7–22 3826 5856-005


EVENT; or COMPONENT; (COMP;) must identify the ispec. The ispec can not be usage output.

Include FORMATTED; (or BYPASS; or BY;) to bypass the conversion process. Nothing further is required in the ispec record.

Defining Ispec Records for Unformatted Data

The first five characters of each ispec record (including lines continued over more than one line) must be the word ISPEC, and the sixth character must be a space.

EVENT; or COMPONENT; (COMP;) must identify the ispec. The ispec can not be specified as usage output.

Several ispec records may be needed to define the data format for an ispec. Attributes must be defined in the correct sequence, using particular property names followed by their values.

Properties of ispec records are shown below:

The following conditions apply to these properties:

• At least one DATA; or SETUP.DATA; properties is required for an ispec.

• Each specified characteristic must be present in the ispec in the application. All attributes, except persistent attributes, are valid.

• Built-in attributes can also be included, in particular:

– ActMth is required for all ispecs.

– Maint is required for ispecs with one or more key fields defined.

– Last-Line is required for copy classes.

• Glb.Spaces can be included between attributes to enable spaces to be included in the input file. The LENGTH; for Glb.Spaces determines the number of spaces between the items.

• Attributes with the REQUIRED; properties in the application must be included, otherwise the GLI transactions will be rejected.

• Each specified attribute must have an associated LENGTH. This length can be less than or equal to that specified in the relevant ispec.

Properties Abbreviation

DATA; DA;

LENGTH; LE;

EDIT; ED;

DECIMAL; DE;

SETUP.DATA; SD;

3826 5856-005 7–23


• The number of decimal places may be less than or equal to the actual decimals for the attribute in the application. All decimal points are implied.

• Separator characters must not be entered through GLI.

• EDIT; is optional. It must match that defined in the application. The default type is alphanumeric.

Edit types are listed in the following table:

Setup.Data

SETUP.DATA; can be used in the ispec record. This command defines an attribute that is to have the same literal value applied for all later GLI data records for that ispec. The following conditions apply to SETUP.DATA;

• Transient attributes require a LENGTH;. The length must equal the number of characters within the parentheses, and must be less than or equal to the length specified in the application.

• Leading and trailing spaces are not permitted in the value of the transient attribute.

• Do not include EDIT; with transient attributes.

• No space is reserved for transient attributes in GLI data records for that ispec.

Examples of formatted data in an ispec record:

ISPEC EVENT; SALE FORMATTED;

Examples of unformatted data in an ispec record:

ISPEC EVENT; SALE DA; CLIENT LE; 10 EDIT; A ISPEC DATA; PRODUCT LENGTH; 5 ED; N DA; GLB.SPACES LE; 2 ISPEC DA; ANUMBER ED; LE; 4 DE; 2 SD; ACTMTH (9904) LE; 4

In this example, the built-in attribute ActMth receives the value 9904 for all data records. Notice that all lines of the ispec record begin with ISPEC.

Edit Description

A Alphanumeric item

N Unsigned numeric

S Signed numeric item (negative DR)

C Signed numeric item (negative CR)

+ Signed numeric item (shows + and -)

- Signed numeric item (negative -)

D Date item

7–24 3826 5856-005


Data Records

Data records are passed by GLI to the application. The first five characters of the record must contain the name of an ispec previously defined in a GLI ispec record. The sixth character must be a space. The data for the ispec then follows, in the format defined by the ispec record.

A GLI data record can be included at any time after the ispec record with which it is associated. A particular ispec can occur in more than one ispec record and can have different definitions (for example, different LENGTH; and EDIT; values). Data records for an ispec use the last ispec record declared for that ispec.

Unformatted Data

For a copy class, supply data for each copy in a separate record.

Do not include a decimal character for numeric values.

Signed numeric values are assumed to have the sign specified by EDIT. To indicate that the value has the opposite sign, replace the digit in the first numeric position, according to the following table:

Examples

To load a negative value of 56500 into an attribute of length 5 with EDIT; +, load

N6500

To load an attribute of length 8, load

}0056500

Digit Replace with...

0 }

1 J

2 K

3 L

4 M

5 N

6 O

7 P

8 Q

9 R

3826 5856-005 7–25


To load a positive value of 7634127 into an attribute of length 7 with EDIT; -, load

P634127

There are different considerations for unformatted data and formatted data.

Formatted Data

For a copy class, data for all copies must be supplied in one record.

Signed numeric values require a sign (+, -, DR, or CR) following the value.

Numeric values with decimals must not include a decimal character. Add a leading zero if the attribute in the application has DECIMAL.KEYED.

Numeric values must not include separator characters. Add a leading zero to allow for each separator character if the attribute in the application has SEPARATOR.

Examples of records for unformatted data:

ISPEC EVENT; SALE DA; CLIENT LE; 12 EDIT; A ISPEC DATA; PRODUCT LENGTH; 5 ED; N DA; GLB.SPACES LE; 2 ISPEC DA; ANUMBER ED; N LE; 4 DE; 2 SD; ACTMTH (9904) LE; 4 SALE MR NO BODY 12345 0100 SALE MS SOME BODY12345 }100 FINISH

Examples of records for formatted data:

ISPEC EVENT; SALE FORMAT; SALE 9904MR NO BODY 1234500100 SALE 9904MS SOME BODY1234500100-

For both types of format, the results are the same. For the first data record, the attribute CLIENT takes the value MR NO BODY, PRODUCT 12345, ANUMBER 1.00, and ACTMTH 9904. For the second data record, CLIENT takes the value MS SOME BODY, PRODUCT 12345, ANUMBER - 1.00, and ACTMTH 9904.

Finish Record

The finish record indicates the end of input to the GLI program.

The first six characters of the record must be FINISH, and the remainder must be blank. No acknowledgment is returned.

GLI Output

The first six characters (positions 1 through 6) of the GLI output file indicate the status of the GLI definition and the status of the transaction (if the definition has no errors). The status value determines the contents of the remainder of the line.

7–26 3826 5856-005


GLI Definition Status

If there is an error in the GLI definition (for example, incorrect formatting), NOT OK is returned in the status position of the record. An error message starts at position 15 of the record (including the status value).

For definition lines that do not contain errors, OK is returned in the status position.

GLI Transaction Status

If there are no errors in the GLI definition, the status position for the data records contains the transaction status.

For acknowledgment records, the status is one of OK, NOT OK, and FATAL. For records in error, the status value is ERRORS if there is an error in the application; or FATAL or ERROR if there is an error in the GLI program.

For a recall or an inquiry (Maint is REC or INQ), a status of OK is accompanied by up to ten error messages starting in position 15 of the record (including the status value).

For a transaction status of OK, data is returned, formatted according to the Field Description file, and starting in position 15 of the record (including the status value).

GLI Recovery

The first record returned by GLI to an external program at BOJ (beginning-of-job) is the value OK, except where recovery is required.

Where, recovery is required, the first record passed back at BOJ is:

RECOVE number

Where, number is an eight-digit number indicating the number of GLI data records processed.

If input is from a file, the GLI program repositions the input file to the correct record for restarting. If input is from an external program using pipes, provision must be made to ensure that the correct number of records is supplied when recovery is required. The RECOVE message is a signal to the external program that it must resynchronize with the application.

If the system/FORMSGLI file is not present in the application directory on a GLI recovery run, the output passed by GLI to your user GLI program has the following format:

RECOVE number REQNUMBERS

This requests that the header records be resent to the GLI program. To run recovery, all records must be resent. The header records are processed, and the data records are rejected if they have been entered before. (Records that have been entered before are determined by maintaining a counter of records received from the GLI user program.)

3826 5856-005 7–27


To abort recovery and treat this as a new run with new data, the user GLI program must send the following back as its first input:

NORECO;

Notes:

• GLI does not recognize whether records being sent have been previously processed.

• GLI does not detect values of Glb.Spaces or Glb.Zeros declared for a key.

• GLI produces a workfile named FORMGLI. This file is used by GLI Recovery, and is purged by GLI at normal EOJ.

Offline Input

The Offline Input client program (OFF.exe) is used to load entire files of data into a target application. The input data is piped into the Offline client's stdin, and application responses are displayed to stderr. The input records must be in the correct format required by the target application, and must be error free.

A graphical representation of the Offline Input program interface is shown below:

Offline Input Program Interface


• Formatting for Offline Input

• Executing the Offline Program

• Offline Recovery

Formatting for Offline Input

Format data according to the following rules:

CautionOffline Input has largely been superseded by the Non-Formatted Input/Output facility (NOF). Consider developing a sending NOF program for your data loading needs.

7–28 3826 5856-005


• Start the record layout at position 1, with the order and field lengths matching those in the Field Description File file. The Field Description File is generated automatically with the application.

• Ignore the usage output and status line fields in the Field Description File.

• Start each record with the ispec name followed by the value O (for Offline) for the attribute Glb.Source field.

• Define values for all other items, including standard information, as required. The first line of an ispec screen layout is described in the “Built-in Attributes topic of the Developer online help.

• Include a decimal character in the value for an attribute that has DECIMALS.KEYED. Separator characters can be included.

• Include the sign (+ , -, DR, CR) after the value for signed number attributes.

Executing the Offline Program

The OFF client program (OFF.exe) can be run from a Windows command prompt on the server running the application, or on a different Windows operating system connected to the server via a network. The OFF client program accepts its input from stdin, and directs output to stderr.


OFF.exe --host[<hostname>] --view[<viewname>] [<input>]


Where:

The value of Glb.Stn is set to OFF for data entered through the Offline program. The value of Glb.Source is O (for Offline). Glb.Work should not be referenced by the Offline program. Glb.Priv is set to the same value as the originating user account.

Offline Recovery

If the application goes down while data is being entered through the Offline program, recovery is fully automatic, provided the same input file is used again.

Records successfully processed prior to the application failure are skipped automatically before reprocessing begins.

Parameter Descrition



<input> Command line input that is read by OFF.exe. It is possible to pipe a file containing OFF data

3826 5856-005 7–29


Views Views are used to configure the connection to your application. They contain all the necessary information including protocols, logging, and access control. Views can be created and configured using the Runtime Administration Tool. The view information is contained as part of the NGRuntime.xml file which is stored in the Data\public folder of your Runtime installation directory and is accessible by all protocol adapters. Although this file can be edited manually it is recommended you use the Administration Tool to configure the views.

Views enable a simple connection to an application, as the client does not need to know the exact details of the applications location. They also give flexibility, for example allowing you to create several views to the same application each with different parameters. See the Creating Views for further details.

Access Control

When creating a view you can specify the IP addresses that can use that view and therefore restrict access to the application to which the view connects.

To enable everyone to access the application you can either leave the IP address field blank, or specify the address range *.*.*.*. You can specify address ranges to allow and deny access. You can specify a range to allow access and deny one address in that range, or vice versa.

Any addresses not included as allowed in the list are denied access, that is, you must specify all addresses to which you want to grant access.

Security If your environment is configured in such a way that the protocol adapters are installed on a different machine to your application, the clients of your application must be defined as domain users.

7–30 3826 5856-005

Section 8Database Structure

Agile Business Suite Runtime for Windows supports a SQL Server for a runtime system via the Ole DB interface. A runtime application generated to target a database can be a runtime transferred to an SQL Server based runtime environment without needing to regenerate the source code for the system.

The following topics describe specifics of the database structure:

• Database Tables

• Profiles

• Events

• User Maintained Tables

Database Tables A database table is created for each class (ispec) that contains persistent attributes. Each record in the table contains the persistent attributes for an instance of the class.


• _Id Column

• Ordinates

• Naming Conventions

• Adding a new Column

_Id Column

Each database table contains a column called _Id that contains the unique identifier for each instance of a persistent class. The database software generates the content of the _Id column.

For SQL Server, setting the “IDENTITY” property of the _Id column to TRUE, means that a unique value is generated in the column each time a row is inserted in the table.

3826 5856-005 8–1

Database Structure

Ordinates

The ordinates of a class are specified in Developer by setting the IsKey property of an attribute to either Ascending or Descending (this also sets the attribute’s IsPersistent property to True). The IsKey property can be set on more than one attribute.

The ordinates of a class are implemented as a unique index on the class’s database table.

Naming Conventions

All names relating to the database use the Alternate name configuration property of the item.

The alternate name for a class containing persistent attributes is used as the name of the class’s database table. The alternate name for a persistent attribute is used as the attribute’s column name in the database table. The maximum length of an alternate name is 25 characters.

Note: Tables of each system are owned by the user derived from the database schema name. For more information refer to the section Configuration Properties in the Developer User Guide.

The alternate name defaults to the name of the object in the model. If the object name is not appropriate, for example it can be up to 64 characters in length or it is not unique within its containing class, and the user has not specified an alternate name, then Builder generates an alternate name from the object’s GUID. An example of a generated alternate name is “FFGB2WPGHITFGJR33IZPCBMUL”.

Adding a new Column

When a new column is added to an existing table, the value of these columns in existing records will be initialized to NULL. This improves the performance of Database Reorganization and limits the disk space required for the reorganized table.

In most cases, the value of these columns returned to the application will appear to be spaces (String attribute) or zeros (Number attribute). One exception to this is if you use the new column in a Profile, then a value of NULL in a String column will be sorted before spaces. This might result in an unexpected behavior in the order or selection of records while reading via Profiles. If you suspect this might be an issue, then you would need to create a process to explicitly update the columns in the existing records with spaces or zeros.

8–2 3826 5856-005

Database Structure

Profiles

Non-conditional Profiles

A non-conditional profile over a class is generated as an index on the class’s database table. The DuplicatesAllowed property for a profile specifies whether duplicate keys can be created for the index. Setting this property to True will create an index that is not unique.

If the DuplicatesAllowed property is set to False the UNIQUE clause is used on the creation of the index to ensure the key values for the profile are unique.

Conditional Profiles

Conditional profiles are created as an Index View for an SQL Server Runtime database. These are structures maintained by the DBMS software. The key columns of the conditional profile plus the _Id column are the columns contained in the view. The conditional logic for the profile is used in the view’s WHERE clause.

Two indexes are created on the view, one on the _Id column and the other is the profile’s key columns. If the DuplicatesAllowed property of the conditional profile is set to False, then the UNIQUE clause is used on the key column index to ensure the key values for the profile are unique. If the DuplicatesAllowed property is set to True, then the UNIQUE clause is not used, allowing duplicate key values.

Events The event database structure is where more than one class, each of stereotype Event, share a single database table. Each Event class has an Autopersist dependency to the containing event class (target) for which the database table is created. The Autopersist dependency implies that all persistent attributes in an event ispec that is the source of the dependency, are persisted in the table of the target event class.

It is possible to code multiple event structures, that is, to have multiple classes of stereotype event each of which is the target of Autopersist dependencies from other event classes.

User Maintained Tables User Maintained Tables option specifies whether a database table is reorganized by the user or by the system during deployment. This option is available for persistent AB Suite entities such as Ispecs (tables), Profiles (indexes), Events and vanilla Classes. Marking an AB Suite entity as ‘User Maintained’ will ensure that AB Suite deployment would not create or modify the related database structures. These structures will also not be available to Administration Client for modification.

If an Ispec is marked as user-maintained, the profiles under that Ispec also become user-maintained.

3826 5856-005 8–3

Database Structure

Database Reorganization

The database reorganization facility creates DDLs for persistent AB Suite entities but will not process user-maintained entities. The reorganization application will not in any way create, alter or drop the user-maintained entities for SQL Server. This is also applicable in the case where a system is deployed after an import, since database reorganization normally creates the database at this time. In case of a new deployment, the reorganization application ignores all user-maintained database objects while preparing the reorganization plan.

An on-demand consistency check option is provided by the Runtime Administration to ensure that the database structures created by the process of database reorganization are equivalent to the actual structures AB Suite expects to be present. The functionality will accept a database table or view as long as it contains the minimum number of columns that AB Suite expects.

It is possible for a component marked as user-maintained to be reverted back to being AB Suite-maintained. In this case, the consistency check should be made to see that the related database structures are in a form that exactly matches the form that AB Suite would have produced had they been AB Suite-maintained in the first place.

During the actual database reorganization process, the application uses DatabaseSchema.XML and the current database schema to generate a new physical schema on the target machine. DatabaseSchema.XML contains information on the user-maintained AB Suite entities. This information helps the reorganization application create appropriate database structures and avoid schema mismatches.

8–4 3826 5856-005

Section 9Report Operations


• Creating Reports

• Running Reports

• Passing Parameters to a Report

• Using Returned Values from a Report

• Where Report Output is Located

• Recovering Reports

• Report Output Control (ROC)

• Printing Reports

• Overriding the Default FormDepth or PageDepth

• Deleting Reports

Creating ReportsReports are created using Developer. See your Developer online help for information on creating reports.

Reports are generally described as being one of three types; standard, direct, or Enterprise Output Manager, according to the type of device to which the report output is to be directed.

Standard reports are those reports whose default device type is defined as one of the following:

• Line printers (LP)

• Terminal printers (TP)

• Extract files (EX)

• Video Display (VD)

They also use the Remote Output Control System (ROC) database to store control information and to manage output.

3826 5856-005 9–1

Report Operations

Direct reports (DI) do not do not use ROC to manage their output. Rather, output is directed to files or devices depending on the specified device and the built-in attribute Glb.Stn.

Enterprise Output Manager reports are specially formatted reports designed to be used with the Enterprise Output Manager print management application (previously called DEPCON). They can be defined by selected the Add Enterprise Output Manager Report option in Developer.

Reports can be further distinguished as either synchronous or asynchronous, according to the way in which a report is to be executed.

The most common form of reports are asynchronous reports. Asynchronous reports can be executed, stopped, recovered, and deleted using the Runtime Administration tool or administration commands. They can be executed from logic using the Run logic command.

Synchronous reports can be called from the logic of a generated application or from an external program and are loaded into COM+. Synchronous reports are called from the logic of your generated application using external classes. Refer to your online help for details of using external classes.

Standard Reports

Output from standard reports is sent to ROC.

Standard report output is:

• Recovered in the event of failure.

• Independent of the output device. Output can be directed to a specific destination type (LP, TP, EX, or VD), or the device can be left unspecified (to be supplied at a later time using ROC).

• Produced by applying device-dependent control codes as late as possible, to ensure maximum flexibility. The actual delivery mechanism utilizes standard system software.

• Synchronized with the state of the application database.

Sending Output to Multiple Stations

By default, a standard report is printed at the destination specified by the attributes Glb.Device and Glb.Stn. If the output needs to be printed at multiple destinations, use the SendPrint logic command.

9–2 3826 5856-005

Report Operations

Direct Reports

The output of direct reports is not placed in ROC. Instead output is directed to files or devices, depending on the settings of the report's device specification and the built-in attribute Glb.Stn (see Direct Report Output for further details). Direct report output is not printed unless these settings and the choice of a ROC alias are configured appropriately.

Direct report output is not automatically recovered after a report or application failure. It is the user's responsibility to save the old report output before restarting a report that has failed.

Enterprise Output Manager Reports

Enterprise Output Manager (previously called DEPCON) is a comprehensive print management and file distribution solution for mixed platform networks. The primary function of the Enterprise Output Manager application is to automatically route print files from any supported platform to any other supported platform. However, the main advantage when paired with Agile Business Suite is to increase flexibility in designing and printing reports.

Enterprise Output Manager Reports are usually reports that have been defined in Developer using the Enterprise Output Manager Wizard, however it is possible to direct the output of any report to Enterprise Output Manager.

Enterprise Output Manager Reports are similar to direct reports. Output from a Enterprise Output Manager Report is a text file with control headers that specify the print attributes for a given report. Enterprise Output Manager automatically detects the output print jobs. It is the Enterprise Output Manager administrator's responsibility to set up Enterprise Output Manager to print reports. Enterprise Output Manager then uses File Masks to read the header information and assign print attributes and a printer.

Printing

Printing to Enterprise Output Manager is triggered by using the device type DP.You should configure an EOM printer in your Windows Operating System to print the EOM report. The report output will be in the EOM output data format. In order to print the Enterprise Output Manager report from a default printer you should do one of the following:

1. Set the Enterprise Output Manager (EOM) Printer as your default printer in the Printer’s dialog when GLB.STN is set to blank. As long as the GLB.STN is blank, the output will be directed to the application user's Windows Default Printer, which can be set via Microsoft Printer dialog. See Using a Windows (Standard) Printer section for configuring a default printer.

2. Use the GLB.STN and ROC ALIAS if you want to direct the output to printer regardless of whether the device is set to LP or DP. This way the physical printer name can be made independent of their LDL logic. It should avoid the hidden default printer name in Windows which can be overlooked by the users.

3826 5856-005 9–3

Report Operations

See "Printing Enterprise Output Manager Reports" in your Developer online help and the Enterprise Output Manager Configuration and Operations Guide for detailed instructions on setting up Enterprise Output Manager for printing. For details on creating and modifying a Enterprise Output Manager report in Developer, see "Defining a Enterprise Output Manager Report" in the Developer online help.

Note: To create shared Enterprise Output Manager printers you need to install Enterprise Output Manager software and configure its mechanism.

Built-in Attributes and Reports

When a report is executed, built-in attributes are used to define many operations of the report.

Glb.Device defines the type of output device. This is set in the logic of the report.

Glb.Priv is set to 0 (zero). The value of Glb.Priv is used only to define the privilege level of output held in the ROC database.

Glb.Stn defines where output is produced.

Glb.Task defines a return-value (or exit code) for the report.

For more details on built-in attributes refer to your Developer online help.

Using the CriticalPoint Logic Command

The CriticalPoint logic command is primarily intended to enable the recovery of report output. However, there is an additional consideration with the use of standard reports.

When a CriticalPoint command is performed, any print-line buffering is unconditionally written to the file.

The inclusion of CriticalPoint logic in direct reports depends on the requirements for recovery of the reports.

If a report fails in which Glb.User is changed after a Release logic command is executed, but before a CriticalPoint command is executed, you may not be able to restart the report. This is due to access to the output file being restricted to the value of Glb.User. In addition, output released by a Release command in a standard report is not visible until database transactions have been committed using a CriticalPoint command.

Including the Sleep Variant

There are several rules that apply when the Sleep variant is included in the CriticalPoint logic command:

9–4 3826 5856-005

Report Operations

• In synchronous reports, the sleep is ignored, as it could delay the transaction or commit prematurely.

• All outstanding HUB transactions are committed.

• Existing database updates are committed and new transactions begun.

• If the value of Glb.Close is “CLOSE”, the report terminates.

• If a Wake or stop signal is received, the report handles it.

• If there is time remaining, the report sleeps before checking for a Wake or stop signal.

• If the EndAfter time elapses, it is handled in the same way as a stop signal.

Running Reports Reports are built as individual .dlls.

Reports are run according to whether they are defined as asynchronous or synchronous.

Asynchronous Reports

Asynchronous reports can be run in the following ways:

• Using the Run command in ispec logic.

• From the Runtime Administration Tool.

• From a client application (such as Presentation Client).

• From a server command prompt window.

• Using the generated COM+ application’s RunReport() method.

• Using the :RUN administration command.

Synchronous Reports

Synchronous reports can be called from the logic of a generated application using external classes, or from an external program.

Report Session Manager

The Report Session Manager is responsible for running asynchronous reports.

The Report Session Manager:

• Starts reports.

• Monitors the status of running reports through to their completion.

• Keeps record of reports awaiting recovery.

3826 5856-005 9–5

Report Operations

• Stores the parameters needed by reports.

• Stops and terminates reports.

• Handles WakeUp calls.

In the event of a report failure, the Report Session Manager will restart the report automatically. If there is a problem with the restart, it will be attempted three times before aborting. If a report uses CriticalPoint logic, the Report Session Manager can restart it from the last good Critical Point.

Running Asynchronous Reports from Ispec Logic

Asynchronous reports are run from ispec logic using the Run logic command.

Non-video reports are run in the background, asynchronously from the application. Standard input and output are directed to NUL: More than one report can be running.

Running Asynchronous Reports from Presentation Client

To run a report from the Presentation Client:

1. In Presentation Client, select Run Report on the System menu.

2. Either select or enter the name of the report to run and click OK.

The View Messages/Errors window is displayed if a report requires input.

Running Asynchronous Reports from a Command Prompt Window

Reports can be run from a command prompt window on the server, without having to connect to your application. An executable file, runrep.exe, is supplied with your Runtime software, which is responsible for calling the Report Session Manager to run the requested report.

To run a report from a command prompt window:

1. From the command prompt window, change to your application directory, the location of System.config.

2. Enter the following syntax to initiate the report: runrep <report> [RECOVERY <pid>][DEVICE <device>] [LA <language>][PA <literal>]

Where:

• <report> is the name of the report to be run.

• Include RECOVERY to restart a report. <pid> is the process ID of the report.

9–6 3826 5856-005

Report Operations

• <device> is a valid device type, LP, TP, VD, or EX (see Where Report Output is Located ). If no device type is specified, LP is the default.

• <language> is the language in which the report (generated in multiple languages) is to be initiated. If no language is specified, the default language of the application is used.

• <literal> is parameter information to be passed to the report (refer to Passing Parameters to a Report). If <literal> contains embedded spaces, enclose the string in quotation (“”) marks.

Notes:

1. Avoid using the [USER <username>] parameter in AB Suite as it is ignored and does not affect GLB.USERCODE. However, if you use this parameter the report will not crash or give any error.

2. When initiating a report from a command prompt window, the entire command (including parameter) is subject to the command prompt window limit on command length.

Redirecting a Report

Redirection can be included as follows:

• Standard input and standard output default to the workstation command prompt window.

• Output from standard reports is placed in the ROC database, while output from direct reports is directed to standard output (and may require redirection).

• Standard output can be redirected to user specified files using a pipe command. For example, the following command enables you to run a report from a .bat file or script, and saves output to Report_log:

runrep <report> > <your_directory>\Report_log

• Enterprise Output Manager Reports are automatically routed if the Enterprise Output Manager print queues are set up correctly. See “Printing Enterprise Output Manager Reports” in your Developer online help. For detailed instructions on setting up Enterprise Output Manager print queues see your Enterprise Output Manager Configuration and Operations Guide.

Replying to Requests for Input

If the Accept logic command is included in the report and standard input is a command prompt window, you are prompted for input. The prompt is the right angle bracket character (>).

Enter your input and press Enter. Your input must start after the prompt character (>).

3826 5856-005 9–7

Report Operations

Running Asynchronous Reports from a Client Interface or COM+

To run a report from a client interface use the administration command :RUN.

To run a report through COM+ use the RunReport() method.

Passing Parameters to a Report When you run a report, you can pass parameters to it. Parameter values are received by the report in an attribute. The receiving attribute is defined as part of the report properties when the report is created.

The value of a parameter must:

• Have 254 characters or less.

• Contain leading zeros for numeric values.

• Not contain decimals for numeric values.

• Not contain separators for numeric values.

Note: When initiating a report from a server command prompt window, the entire command (including parameter) is subject to the command prompt window limit on command length.

Recovering Parameter Data for Reports

For reports initiated from ispec logic using the Run command, parameter data passed to the report is saved and is automatically passed again during recovery.

For reports that are restarted manually parameter data is not saved and the same parameters must be entered again.

Using Returned Values from a Report A report run from the command prompt (via RUNREP) returns a value in the range 0 through 199. A number in the range 0-99 is returned for a normal report completion, and a number in the range 100-199 for a failed report (abnormal termination - for example, file not found error).

The default return codes are:

• 0 – Normal report completion

• 100 – Failed report

9–8 3826 5856-005

Report Operations

This return code will be affected by the value of GLB.TASK. This is a built-in attribute that has an initial value of 0. Your report logic can assign any value in the range 0-99 to this attribute. If the report completes normally the value of GLB.TASK at the completion of the report will be returned.

If the report has an abnormal termination, then the return value will be the current value of GLB.TASK plus 100.

For example, if your report logic assigns the value 50 to GLB.TASK, then the return value would be 50 for a normal report completion and 150 for an abnormal report termination.

Example

The following logic is included in a report Budgtrpt:

Multiply 9 BUDGET-SALES Giving TOO-LOW Multiply 1.1 BUDGET-SALES Giving TOO-HIGH DoWhen TOTAL-SALES < TOO-LOW OR DoWhen TOTAL-SALES > TOO-HIGH Move 60 GLB.TASK End

The following batch program runs the report BUDGRPT and uses the return code to determine whether to run the additional report EXCEPTN. The batch command if errorlevel tests for the exit value of the last program executed:

Runrep BUDGRPT if errorlevel 60 EXCEPTN

Note: The errorlevel return is true if the actual exit value is greater than or equal to the return value.

Where Report Output is Located The report output destination depends on the type of report (Standard, Direct, or Enterprise Output Manager/Depcon) and the settings of the GLB variables - GLB.DEVICE, GLB.STN, and GLB.TITLE. See the Built-in Attribute section in LDL+ Programming Reference Guide for more details on these GLB variables.

A numeric suffix (<releaseno>) is added to the file name to ensure uniqueness when output files are released.

Aliases defined in ROC can be used internally in specifications and reports for convenience.


• Standard Reports

• Direct Reports

• Enterprise Output Manager Reports

3826 5856-005 9–9

Report Operations

Standard Report Output

Standard reports store control information in the ROC database and output in separate files. The ROC output file is generated in XML format so that it can store printing attributes.

Location of Standard Report Output

The default location for Standard (ROC) output files is the <AB Suite Data folder>\private\Reports folder. At runtime, you may redirect the output to other devices. However, there will be a copy in the ROC database which can be used to browse or reprint the report output from within the ROC system.

The location of the report output files is determined by the value specified in the ROC Output Location property in the Runtime Options section of the segment build and deployment configuration properties. The default value (which is <AB Suite Data folder>\private\Reports) can be changed by setting a ROC Output Location to override the default value.

The destination for standard report output depends on the value of the GLB.Device, Glb.Stn, and Glb.Title. This is summarized in the following table:

Note: For shadow reports, the equivalent of Glb.Stn and Glb.Title is <shadow name>.Station and <shadow name>.Title (where <shadow name> is the name of the Glb.OutputStream object defined in the report).

There are two types of report output files that can be produced by Standard ROC reports:

Glb.Device Glb.Stn Glb.Title Description

Default As Developer setting

LP Physical printer name (ROC not installed)

n/a Physical printer = GLB.STN value

Logical printer name (as defined in ALIAS table in ROC system)

n/a Physical printer = ROC.ALIAS[GLB.STN] value

VD n/a n/a Report Output dialog (Winforms only) & ROC database

TP Define key to ALIAS value for LPR command

n/a ROC.ALIAS[GLB.STN] as “linclp –S <Server> -P <PrinterName>”

EX File Path (if provided) File name Path provided in Glb.Stn

<spaces> File name Default value: ~\Data\private\Temp\

The location of this folder can be defined for each system in the Admin tool.

9–10 3826 5856-005

Report Operations

• XML files which are used by the ROC system for browsing report output and redirecting output to printers.

• Text file versions of report output. These will be produced by reports with Device=EX or if ROC is not installed.

For standard (ROC) reports, the XML output files will be stored in the <AB Suite Data folder>\Private\Reports folder (or in the folder specified in the ROC Output Location Segment configuration property if defined).

Text file versions of report output (for example, for EX reports or if ROC is not installed) will be stored by default in the <AB Suite Data folder>\Private\Temp folder. The Admin tool includes an option to change this location of the text file version of report output for each system.

From the Admin tool,

a. Right-click on the system, select All Tasks.

b. Select Configure.

c. Select the Print tab.

d. Click Configure Text Report Output Location.

e. Specify the path where the report output needs to be stored in the Configure Text Report Output Location dialog box.

f. Click OK.

If a report sets a value to Glb.Title, a text version of the report output will be stored by default in the <AB Suite Data folder>\Private\Temp folder with the filename set to the value in Glb.Title. If the report output location has been changed using the admin tool, then the text version of the report output will be stored in the user configured location.

Note: Path specified in "Configure Text Report Output Location" overrides the default path <AB Suite Data folder>\Private\Temp folder for the report output.

Security of Standard Report Output

Security for standard report output is based on the setting of the built-in attribute Glb.User in the logic of the report. Output from reports that set Glb.User cannot be viewed by users signed on with different user accounts. The text files containing the output can, however, be deleted by any user.

If Glb.User is not set, all users have access to the output.

The user accounts with which a user is signed on to ROC can be changed by using the ROC Options screen.

3826 5856-005 9–11

Report Operations

Direct Report Output

Direct reports send output according to the device type specified when the report is executed or the value of Glb.Device is modified in your logic and the value of Glb.Stn when output is first produced by the report.

Shadow reports direct output to a file based on the values of <shadow name>.Device, <shadow name>.Station and <shadow name>.Title (where <shadow name> is the name of the Glb.OutputStream object defined in the report). If <shadow name>.Title is defined, output from shadow reports is directed to the file specified by <shadow name>.Title.

The default location for Direct report output files (including shadow reports) is <AB Suite Data folder>\private\Temp. The Admin tool includes an option to change the location of the text file version of report output for each system.

The following table summarizes the destination of the Direct report output based on the values of the Glb.Device, Glb.Stn, and Glb.Title.

Note: For shadow reports (Glb.Outputstream objects), the equivalent of Glb.Stn and Glb.Title is <shadow name>.Station and <shadow name>.Title (where <shadow name> is the name of the Glb.OutputStream object defined in the report).

Glb.Device Glb.Stn Glb.Title Description

Default stdout

LP Blank n/a Windows Default Printer of Application User

Physical printer name (ROC not installed)

n/a Physical Printer = GLB.STN value

Logical printer name (as defined in ALIAS table in ROC system)

n/a Physical Printer = ROC.ALIAS value (GLB.STN as key)

VD n/a n/a Report Output dialog screen (Winforms only)

TP Define key to ALIAS value for LPR command

n/a ROC.ALIAS[GLB.STN] = “linclp -S <server> -P <PrinterName>”

EX File Path (if provided) File name Path provided in Glb.Stn

<spaces> File name ~\Data\private\Temp\

The location of this folder can be defined for each system in the AdminTool.

9–12 3826 5856-005

Report Operations

Enterprise Output Manager Report Output

Users need to configure the Enterprise Output Manager (EOM)/Depcon printer before running any Enterprise Output Manager report.

EOM reports are automatically detected and routed if the EOM print queues are set up correctly. From there, output is redirected to whichever printer or output format is specified in the print queue.

The EOM report output should not include any plain text. This is because the Data Dependent Attributes LINC will ignore plain text and will not pass those texts into EOM printer. See “Printing Enterprise Output Manager Reports” in your Developer online help for further details of Enterprise Output Manager output. See the Enterprise Output Manager Configuration and Operations Guide for detailed instructions on setting up Enterprise Output Manager for printing.

Note: The GLB variables in LDL will override report’s input argument. For example, at command console you type – “RUN DPCStLst DE VD” to set the report to Video mode and in the LDL you set the GLB.DEVICE = LP, the final report destination will use Device = LP.

The following table summarises the destination of the Enterprise Output Manager Report output based on the values in the Glb.Device, Glb.Stn, and Glb.Title.

Recovering Reports If a report terminates unexpectedly, details of any errors are written to either the event log or the system.log file in your Data directory. If a report persistent attributes, recovery information is saved based on the last CriticalPoint for the report.

Glb.Device (at runtime) Glb.Stn Glb.Title Destination

LP, DP or Default

ALIAS key to define Depcon Printer Name

n/a If ROC is not installed, Depcon PrinterName = GLB.STN value.

If ROC is installed:

Depcon PrinterName=ROCDB.ALIAS[GLB.STN]

For example,

GLB.STN=DEPCONPTR

ROC ALIAS:[DEPCONPTR]=”EOMPrinter”

VD n/a n/a Screen display in plain text. No Depcon process.

TP ALIAS key n/a Set ALIAS = “linclp –S<EOMServer> -P <EOMQueue>” to pipe output to configured EOM Queue.

EX n/a Fila name ~\Data\private\Temp\

3826 5856-005 9–13

Report Operations

Recovery of the report depends on:

• How the report was initiated:

– From an Ispec logic with the Run logic command

– From the Windows Server command line

– From the NOF interface using :RUN.

• The value of the Extended Report Recovery option in Developer.

If Extend Report Recovery is set to False, normal report recovery is used. Two attempts are made to restart the report, after which recovery information is discarded and the report must be run again from the beginning.

If Extended Report Recovery is set to True, extended report recovery is used. There is no limit on the number of times the report is restarted using the recovery information. The recovery information is deleted when the report terminates successfully, or you can choose to delete the recovery information and run the report from the beginning.

Use the :REP administration command to obtain a list of recoverable reports.

Recovering Reports Initiated with the Run Logic Command

Reports initiated from ispec logic using the Run command are restarted automatically. Two attempts are made to restart the report, after which recovery information is discarded and the report must be run again from the beginning.

Use the administration command :REP to obtain the report’s session identifier. Use that session identifier with the :RUN command to recover the report.

Recovering Reports Initiated from a Command Prompt Window

Reports run from a Windows server command prompt line are not automatically restarted. You must re-issue the command to attempt to recover the report. You can make two attempts to recover the report. If parameter information was included with the command, you must include the information with the new command.

If the application is using extended report recovery after normal recovery, the report can be restarted using the saved recovery information. From a server command prompt window, enter the following:

Runrep <report> [RECOVER <key>] [<device>] [TR] [LA <language>] [PA <parameter>]

Use the system command :REP RECOVER to obtain a value for key. See Running Asynchronous Reports from a Command Prompt Window for details of the other options.

9–14 3826 5856-005

Report Operations

You can use the value returned by the report to determine if the report failed. For more details, refer to Using Returned Values from a Report (Glb.Task).

Recovering Reports Initiated with the :RUN Command

If the report terminates unexpectedly during initiation, Presentation Client displays the :RUN administration command used to initiate the report.

If the report terminates during execution, the :RUN command is not displayed.

To attempt recovery of the report, reissue the command. You can make two attempts to recover the report. If parameter information was included with the :RUN command, you must include the information with the new command.

If the application is using extended report recovery after normal recovery, the report may be restarted using the saved recovery information. Use the following administration command (see Report Administration Commands for further details):

:RUN report [RECOVER key ] [ device ] [TR] [PA params]

Use the administration command :REP [RECOVER] to obtain a value for key. See Running Asynchronous Reports from a Command Prompt Window for details of the other options.

Extended Report Recovery

To ensure that failed reports store their recovery information, set the Extended Report Recovery option to True in the Runtime Behavior section of the segment build and deployment configuration properties.

If a report using extended recovery terminates unexpectedly, the Report Session Manager attempts to restart the report until it either finishes successfully or the recovery information is deleted.

When recovering reports that use extended report recovery:

• Use the administration command :REP [RECOVER] from a Presentation Client workstation to list reports with recovery information.

• Use the administration commands :DEL or :TER DISCARD to remove recovery information.

Note: The command, :TER NO.RECOVERY removes recovery information if extended report recovery is not enabled (even if the report is not running).

Report Output Control (ROC) Report Output Control (ROC) manages output for standard reports.

3826 5856-005 9–15

Report Operations

Control information is stored in the ROC database, while output is stored in COBOL text files.

You can view reports using the ROC client interface through any of the following clients:

• Standalone Presentation Client

• Presentation Client as a Browser Applet

• ASP.NET Web Forms

• VB.NET Winforms

Procedures for browsing reports are given in the ROC help file.

When a client sends a ROC request to the Windows Runtime, the Windows Runtime returns a Switch message to the client, and performs a switch to the ROC system. Switching to ROC is considered to be the same as an application switch. To enable the switching, you must configure the client environment for application switching. Remember the following points while switching between applications on Component Enabler (CE):

• When the Runtime sends the Switch message, the system name being switched to is transferred with the message. This enables the client to execute the correct CE application. For example, Sample.

• The generated bundle name for all the applications being switched to must be the same for all the applications. The Switch message that the Runtime sends does not contain information about the CE bundle name. Therefore, the CE client application assumes that the bundle name is same for all the applications being switched between.

The bundle name is established when the CE client connects to the first application.

Notes:

1. You should ensure that the ROC system for Windows is installed properly. Refer to the Agile Business Suite Installation and Configuration Guide for information on installing the Report Output Control system.

2. The ROC system is installed successfully, only if the installation ends with the following message, “ROC deployment completed with status 0”.


• Initiating ROC

• Defining a ROC Alias

• Managing Expired Reports

• Accessing ROC from Ispec Logic

• Accessing ROC from standalone Presentation Client

• Accessing ROC from Presentation Client as a Browser Applet

• Accessing ROC from ASP.NET Web Forms

9–16 3826 5856-005

Report Operations

• Accessing ROC from VB.NET Winforms

Initiating ROC

Report Output Control (ROC) can be run by a user who is not already signed on to ROC.

There are two ways to initiate ROC:

• From Presentation Client, on the System menu, select Select Screen, ROC.

• From logic, execute the Roc command.

For detailed information on the ROC client interface, refer to the ROC help file.

Notes:

1. When you initiate ROC from a Presentation Client workstation, you switch to the ROC system from the current System. To return to your System, close ROC by typing BY at the Action line.

2. If you are already running a report from Presentation Client, and wish to run ROC concurrently, you need to launch a separate Presentation Client session and log on as a different user in order to initiate ROC. This allows the report to continue to receive input to the Accept command.

Defining a ROC Alias

A ROC alias can be any of the following:

• A command to which report output is piped when the device type for the output request is TP (terminal printer). For example, you can direct reports to an alias for a text only output printer or formatted output printer using the LincLp command. See Defining a TCP Printer for Text Only Output and Defining a TCP Printer for Formatted Output for information. In this case, you should consider redirecting standard output to NUL: to suppress program messages

• A file to which report output is directed when the device type for the output request is EX (extract file).

• An association between the ROC pack and the directory in which ROC output files are written. See Standard Report Output for more information.

• A UNC printer name. Glb.Stn can reference a printer with a UNC name. However, most UNC names will exceed the maximum length of Glb.Stn (which is 17). Use a ROC alias to map a logical printer name with a UNC name. As you can run reports that do not direct their output through ROC, the mapping of logical printer names with UNC names is allowed by adding environment variables.

Before listing the ROC alias, you should first confirm that you are able to print with your alias from a simple application such as Notepad.

3826 5856-005 9–17

Report Operations

Managing Expired Reports

You can use the following ROC reports to clean up any expired report requests:

RocDelExpird

This report performs the same functionality as the startup logic in ROC, which is to check for expired report requests. If a report is expired, then it is checked for any pending output requests. If there are no output requests for the report or the output request status is C for Completed or D for Deleted, then the report is deleted along with the output requests.When a report entry is deleted, the system deletes the following:

1. HEADR entries – Report output record which contains the report information when the report had been run and produced output.

2. One or more OHEAD entries (1 record for each print) – Output Request record that contains one entry to describe the output process when a report output is outputted in different devices (LP – printed, VD – displayed, EX – written to a file).

3. The flat file (roc file) of text contents – This file contains all output (printing) text and their attributes and is in XML format.

RocDAllExp

This report deletes all report requests that have expired, irrespective of any pending output requests. That is, all expired reports are deleted and all corresponding output requests are deleted no matter what their status.

Accessing ROC from Ispec Logic

The Roc logic command enables the Report Output Control (ROC) system to be accessed from ispec logic. All logic following the Roc command in the ispec is ignored and is not executed.

If an ispec name is included with the Roc logic command, the construct method for that ispec is invoked when ROC is terminated. If no ispec is included, the construct method for the calling ispec is invoked.

If an ispec name is specified, you can also include a command to be passed to ROC. The passed command is executed by ROC.

For more details of the ROC logic command, refer to your Developer online help.

9–18 3826 5856-005

Report Operations

Accessing ROC from standalone Presentation Client

Notes:

• Before accessing an AB Suite application for the first time on Presentation Client, ensure to update the Path environment variable by right-clicking My Computer in File Explorer > Properties > Advanced system settings > Environment Variables > System variables with the path where the JRE is installed on your machine.

• Presentation Client is supported on Sun J2RE v1.4.2_05 and above.

Perform the following steps to access the ROC application using the Presentation Client:

1. Build an AB Suite application, for example Sample, with the User Defined View Generator property set to Presentation Client in the bundle folder Property Pages window.

For example, set the following parameters for the single AB Suite host application as below.

• Package Prefix: com.unisys

• CE Application Name: Sample

• CE bundle folder name: PClient

2. Import the ROC application that you want to access in AB Suite Developer.

For example, you can import the ROCCLR.model.

Note: Since the name of the Windows Runtime ROC system in Agile Business Suite 4.0 is ROC40, the segment name for a ROC application in Agile Business Suite Developer should also be ROC40. If your model displays the segment name as ROC18, you must change the segment name and the ROC Alias name to ROC40.

3. Generate a bundle of the folder that contains the Ispecs of the ROC application.

Notes:

1. Ensure that the name of the bundle folder is same as the CE bundle folder for the AB Suite application. For example, PClient.

2. To generate a bundle folder, you must set all the properties that are required to build an application.

3. If the default pre-built Presentation client forms for ROC are used such as, ROC18CE.jar, the user system bundle name must be “Ispecs“.

4. Create a view for the AB Suite and ROC applications using the Runtime Administration Tool.

See Creating Views in Runtime Administration, for information on creating a view.

5. Configure the Presentation Client for the AB Suite and ROC applications.

Refer to Agile Business Suite Component Enabler User Guide, Section 8, “Using the Configuration Assistant” for information on configuring the Presentation Client.

6. Open the Presentation Client and connect to the AB Suite application.

3826 5856-005 9–19

Report Operations

The Select a Screen dialog box is displayed.

Notes:• If you specify an Ispec as the Fireup Ispec in the Segment properties, the

application displays the same Ispec instead of the Select a Screen dialog box.

• You can access ROC separately by connecting to the ROC application after opening the Presentation Client. To access ROC from the AB Suite application, complete the following step.

7. Click the ROC button in the Select a Screen dialog box to access the ROC application.

Note: If the application opens with the Ispec specified as the Fireup Ispec, select System > Select Screen and click the ROC button to access the ROC application.

Accessing ROC from Presentation Client as a Browser Applet

Perform the following steps to access the ROC application using the Presentation Client as a browser applet:

1. Perform steps 1 to 4 as mentioned in Accessing ROC from standalone Presentation Client.

2. Create a folder in a preferred location on your machine.

For example, C:\pclient.

3. From <root folder>:\NGEN_CE\classes, copy the com folder, its subfolders, and all the files related to the AB Suite and ROC applications to the folder you created in step 2.

For example, after you copy the com folder, the complete folder structure of the AB Suite application looks like: C:\pclient\com\unisys\<AB Suite application name>\<bundle folder name>\views\lang1033.

Note: After you copy the com folder, ensure that the hierarchical structure of the com folder is preserved.

4. Create a virtual directory using Internet Information Services (IIS) and point it to the folder created in step 2.

Refer to Agile Business Suite Component Enabler User Guide, Section 11 “Using the ASP.NET Generators” for information on creating a virtual directory.

5. Copy the following files from <root folder>:\ NGEN_CE to the folder created in step 2.

• config.xml

• home_page.html

6. Copy the following files from <root folder>:\NGEN_CE\Lib to the folder created in step 2.

• jh.jar

9–20 3826 5856-005

Report Operations

• ViewerHelp.jar

• xercesImpl.jar

• xmlParserAPIs.jar

• LincViewer.jar

Note: Copy the LincViewer.jar file from <root folder>:\NGEN_CE\Lib\signed.

7. Configure the config.xml file present in the folder created in step 2.

Refer to Agile Business Suite Component Enabler User Guide, Section 8 “Using the Configuration Assistant” for information on configuring the config.xml file.

8. Configure the home_page.html file present in the folder created in step 2.

Refer to Agile Business Suite Component Enabler User Guide, Section 7 “Using the Agile Business Suite Presentation Client” for information on configuring the home_page.html file.

9. Open Internet Explorer and type the path of home_page.html file in the address bar.

For example: http://<host name>/pclient/home_page.html.

The Component Enabler Presentation Client window appears in Internet Explorer.

10. In the Component Enabler Presentation Client window, click the AB Suite application through which you want to access ROC in the Available Systems list.

The Presentation Client window appears as an applet with the Open a Session dialog box displayed.

Note: You can access ROC separately after this step by connecting to the ROC application in the Open a Session dialog box. To access ROC from the AB Suite application, complete the following steps.

11. Connect to the AB Suite application.

The Select a Screen dialog box is displayed.

Note: If you specify an Ispec as the Fireup Ispec in the Segment properties, the application displays the same Ispec instead of the Select Screen dialog box.

12. Click the ROC button in the Select a Screen dialog box to access the ROC application.

Note: If the application opens with the Ispec specified as the Fireup Ispec, select System > Select Screen and click the ROC button to access the ROC application.

Accessing ROC from ASP.NET Web Forms

Perform the following steps to access the ROC application from ASP.NET Web Forms:

1. Open an AB Suite application in the Developer Environment.

For example, Sample.

2. Add an Ispec and set the following properties for the Ispec in the Properties window.

3826 5856-005 9–21

Report Operations

• PresentationType: Graphical & Fixed

• MemberVisibility and Visibility: Public

3. Add a Main method to the Ispec.

4. Enter the following syntax in the Logic tab of the Main method.DoWhen (SWSYS = GLB.SPACES) Message Error "Enter system name"EndExit:: Build up switch commandDoWhen (SWSYS <> GLB.SPACES)SwitchTo SWSYSEndExit

5. Add a Label in the Painter tab of the Ispec and set the Text property as appropriate.

For example, you can set the Text property of the Label to “Enter the application name you want to switch to”.

6. Add a TextField in the Painter tab of the Ispec, so that the user can enter the application name to switch to.

7. Set the required Length for the Attribute of the TextField in the Properties window.

8. Rename the TextField Attribute to SWSYS.

9. Build the AB Suite application with the User Defined View Generator property set to ASP.NET Web Forms in the bundle folder Property Pages window.

For example, set the following parameters for the single AB Suite host application as below.

• Package Prefix: com.unisys

• CE Application Name: Sample

• CE bundle folder name: ASPNET

10. Import the ROC model that you want to access in Agile Business Suite Developer.

For example, you can import ROCCLR.model.

Note: Since the name of the Windows Runtime ROC system in Agile Business Suite 4.0 is ROC40, the segment name for a ROC application in Agile Business Suite Developer should also be ROC40. If your model displays the Segment name as ROC18, you must either change the Segment name or the ROC Alias name to ROC40.

11. Generate a bundle of the folder that contains the Ispecs of the ROC application.

Notes:

• Ensure that the name of the bundle folder is same as the CE bundle folder for the AB Suite application. For example, ASPNET.

• To generate a bundle folder, you must set all the properties that are required to build an application.

12. Create a view of the AB Suite and ROC applications separately, using the Runtime Administration Tool.

See Creating Views in Section 2, “Runtime Administration”, for information on creating a view.

9–22 3826 5856-005

Report Operations

13. Create a virtual directory for the AB Suite and ROC applications using the SetupASPNet.vbs file located in the path, <root folder>:\NGEN_CE\ASP.NET Generator\Utilities\Setup.

Refer to Agile Business Suite Component Enabler User Guide, Section 11, “Using the ASP.NET Generators” for information on creating a virtual directory.

14. Run CompileASPNet.bat from the <root directory>\NGEN_CE\ classes\com\ unisys\<AB Suite application name>\<bundle folder name>\views folder.

15. Run CompileASPNet.bat from the <root directory> \NGEN_CE \classes\com\ unisys\<roc40>\<bundle folder name>\views folder.

16. Configure the Web.config file present in the views folder of both the applications.

Refer to Agile Business Suite Component Enabler User Guide, Section 11, “Using the ASP.NET Generators” for information on configuring a Web.config file.

17. Create a folder structure in a preferred location on your machine, as shown in the following diagram.

For example, C:\switch\…

*N represents the language or locale number. For example, lang1033 for English.

Here, switch is the top level folder containing sub-folders for each application that will be switched between.

18. Copy the following files from the <root directory>\NGEN_CE\ASP.NET Generator\bin folder to the switch\bin folder.

• UniCombo.dll

• UniMenu.dll

• CEWebFormRenderer.dll

19. Copy the contents of <root directory>\NGEN_CE\classes\com\unisys\<AB Suite application name>\<bundle folder name>\views\langN* to the langN* folder under switch\<AB Suite application name>_<bundle folder name>.

3826 5856-005 9–23

Report Operations

20. Copy the contents of <root directory>\NGEN_CE\classes\com\unisys\ <roc40>\<bundle folder name>\views\langN* to the langN* folder under switch\<roc40>_<bundle folder name>.

21. Copy the following infrastructure files from the <root directory>\NGEN_CE \classes\com\unisys\<AB Suite application name>\<bundle folder name>\views folder to the switch\<AB Suite application name>_<bundle folder name> folder.

• Close.ascx

• Close.ascx.cs

• Close.ascx.designer.cs

• IspecView.cs

• Login.ascx

• Login.ascx.cs

• Login.ascx.designer.cs

• SessionErr.aspx

• SessionErr.aspx.cs

• SessionErr.aspx.designer.cs

• TimeOut.ascx

• TimeOut.ascx.cs

• TimeOut.ascx.designer.cs

• UserConrolView.cs

22. Copy the above-mentioned infrastructure files from the <root directory>\ NGEN_CE \classes \com\unisys\<roc40>\<bundle folder name>\views folder to the switch\<roc40>_<bundle folder name> folder.

23. Copy the following files from the <root directory>\NGEN_CE\ASP.NET Generator\Common\User folder to the switch folder.

• BrowserCaps.cs

• BrowserClose.aspx

• BrowserClose.aspx.cs

• BrowserClose.aspx.designer.cs

• CEASPNETWebForm.csproj

• CEASPNETWebForm.sln

• CEWFRCommonScript.js

• Default.aspx

• Default.aspx.cs

• Default.aspx.designer.cs

• ErrorStrings.cs

• Global.asax

9–24 3826 5856-005

Report Operations

• Global.asax.cs

• UniMenuScript.js

24. Copy the following files from the <root directory>\NGEN_CE\classes\com\ unisys\<AB Suite application name>\<bundle folder name>\views folder to the switch folder.

• CompileASPNet.bat

• Web.config

25. Run CompileASPNet.bat from the switch folder.

26. Configure the Web.config file present in the switch folder and ensure that “ApplicationSwitching” is set to true.

Refer to Agile Business Suite Component Enabler User Guide, Section 11, “Using the ASP.NET Generators” for information on configuring a Web.config file.

27. Create a virtual directory called switch using Internet Information Services (IIS), and point it to the switch folder location. For example, C:\switch.

28. Type the following in the address bar of Internet Explorer. “http://<deployment host name>/switch/default.aspx”.

The AB Suite application is displayed in the browser with a list of Ispecs.

Note: If you specify an Ispec as the Fireup Ispec in the Segment properties, the application displays the same Ispec, instead of a list of Ispecs.

29. Select the Ispec that you created at the beginning of the procedure, and click Ok.

The Ispec opens and prompts you to enter the ROC application name you want to switch to.

Notes:

• If the application opens with a Menu Ispec, right-click > Select a Form and open the Ispec that you created at the beginning of the procedure.

• If the application opens with the Ispec that you created at the beginning of the procedure, perform step 30 to switch to the ROC application.

30. Enter the ROC application name in the Ispec text field and press Enter.

The ROC application is displayed.

Accessing ROC from VB.NET Winforms

Perform the following steps to access the ROC application from VB.NET Winforms:

1. Perform steps 1 to 12 as mentioned in Accessing ROC from ASP.NET Web Forms by setting the User Defined View Generator property to VB.NET Client when building the AB Suite application and generating the ROC Ispec bundle folder.

2. Double-click the SetupVBNETClient.vbs file from the following path: <root folder>:\NGEN_CE\VB.NET Client\Utilities\Setup and click OK.

The VB.NET Client Application Setup Script dialog box appears and prompts you to specify the AB Suite application name.

3826 5856-005 9–25

Report Operations

3. Specify the AB Suite application name in the VB.NET Client Application Setup Script dialog box and click Ok.

4. Click Yes to confirm the creation of a directory with the AB Suite application name.

The VB.NET Client Application Setup Script dialog box appears confirming the initialization of VB.NET Application directories.

5. Click OK in the VB.NET Client Application Setup Script dialog box.

A directory is created in the following path <root folder>:\NGEN_CE\VB.NET Client with the AB Suite application name.

6. Navigate to the location where the directory is created and double-click the <AB Suite application name>.vbproj file.

The Microsoft Visual Studio environment opens with the AB Suite application name displayed in Class View window. You can also see errors listed in the Error List.

7. Switch to the Solution Explorer window, right-click the AB Suite application name and select Properties.

The properties window appears.

8. Click the References tab in the properties window and click the Reference Paths... button.

The Reference Paths dialog box appears.

9. Specify the path for the bin folder of the Component Enabler installation directory in the Folder box of the Reference Paths dialog box.

For example: C:\NGEN_CE\bin\

10. Click the Add Folder button in the Reference Paths dialog box.

The path for the bin folder appears in the Reference Paths box.

11. Click Ok to close the Reference Paths dialog box.

This resolves all the errors and clears the Error List window.

12. Right-click the solution node in the Solution Explorer window, and select Build Solution.

The Save File As dialog box appears with <AB Suite application name>.sln displayed in the Object name box.

13. Click Save in the Save File As dialog box to save the solution.

14. Navigate to <root folder>:\NGEN_CE\classes\com\unisys\<AB Suite application name>\<bundle folder name>\views and double-click the <AB Suite application name>.sln file.

The Microsoft Visual Studio environment opens with all the Ispecs present in the AB Suite application listed in the Class View window.

15. Switch to the Solution Explorer window, right-click the solution node and select Build Solution.

All the Ispecs in the AB Suite application are built.

16. Repeat steps 2 to 15 to build the Ispecs for the ROC application.

9–26 3826 5856-005

Report Operations

17. Configure the config.xml present in the bin folder of AB Suite and ROC applications respectively.

Refer to Agile Business Suite Component Enabler User Guide, Section 10, “Using the Visual Basic.NET Client Generators” for information on configuring a config.xml file.

Note: You can access ROC separately after this step. To access ROC from the AB Suite application, complete the following steps.

18. Navigate to <root folder>:\NGEN_CE\VB.NET Client\<AB Suite application name>\bin and double-click the <AB Suite application name>.exe file.

The AB Suite application opens with the Select Form window.

Note: If you specify an Ispec as Fireup Ispec in the Segment properties, the application displays the same Ispec instead of the Select Form window.

19. In the Select Form window, select the Ispec that you created at the beginning of the procedure and click Ok.

The Ispec opens and prompts you to enter the ROC application name you want to switch to.

Notes:

• If the application opens with a Menu Ispec, select System > Select Form and open the Ispec that you created at the beginning of the procedure..

• If the application opens with the Ispec that you created at the beginning of the procedure, perform step 20 to switch to the ROC application.

20. Enter the ROC application name in the Ispec text field and press Enter.

The ROC application is displayed.

Printing Reports Runtime for Windows Operating Systems uses Report Output Control (ROC) to print text only output from reports on TCP printers, including PostScript-compatible printers. In addition, you can print formatted output on TCP printers that use control characters in reports.

If you print to a text only output printer, no special fonts, effects (for example, bold), or characters are available.

If you print to a formatted output printer, special fonts, effects, and characters are available. The CODES and CODESASSN files can be used to hold the output control codes and associations between report output and specific printers respectively. These files can be modified for your specific requirements. They are transferred to the runtime location as part of the generation process.

By default, output is sent without formatting.

3826 5856-005 9–27

Report Operations

If you are using Enterprise Output Manager Reports, your report output is automatically detected and routed to the Enterprise Output Manager print queue. It is then redirected to the printer or output format specified in the print queue. See “Printing Enterprise Output Manager Reports” in your Developer online help for detailed instructions on setting up Enterprise Output Manager print queues.


• Defining Printers

• Assigning Report Destinations

• Printing Special Attributes

• Formatting CODES File Records

• Example of Defining an Output Control Code

Defining Printers


• Using a Windows (Standard) Printer

• Defining a TCP Printer for Text Only Output

• Defining a TCP Printer for Formatted Output

Using a Windows (Standard) Printer

The report output device LP supports native Windows (standard) printing rather than TCP/IP printing. To configure the default LP device, log on to the machine as the Application User and perform the following steps.

1. Go to Control Panel > Hardware and Sound.

2. Double-click Device and Printers.

3. Right-click the printer and click Set as Default Printer.

Before printing, you should first confirm that you are able to print from a simple application such as Notepad on the computer to which the printer is attached.

Defining a TCP Printer for Text Only Output

Use the following process to define a TCP printer when output is to be text only:

1. From Presentation Client, define each report destination as an alias in ROC. See Defining a ROC Alias to for details. For example:

LincLp -S <server> -P <printer> [-J <jobname>] [-O <option>]

Where:

• <server> specifies the name or IP address of the computer to which the printer is attached.

9–28 3826 5856-005

Report Operations

• <printer> specifies the name of the printer to which the print queue is directed.

• <jobname> specifies the name of the print job.

• <option> indicates the type of file.

For example:

LincLp -S finance -P finance_pr

This command directs all your print jobs to the printer called finance_pr, which is attached to the server called finance.

2. If necessary, add any control codes required by the printer to the CODES file. Refer to your printer documentation for information on control codes.

Note: Printing Services for UNIX (also known as TCP/IP printing services) must be installed and running on the server to which the printer is attached before a user can print. The printer can be attached to the user's workstation; in this configuration, the workstation acts as the print server. If you experience difficulties printing reports, check that TCP/IP printing services have been installed and started with your Environment administrator.

Defining a TCP Printer for Formatted Output

If you print to a non-standard printer, the following special attributes and controls may be available, depending on the printer type:

• BIG data attribute

• BRIGHT data attribute

• Formdepth Calculations

• OUTPUT.CONTROL data attribute

• PITCH data attribute

• UNDER data attribute

If your printer is not qualified, you need to define the output control codes. See Example of Defining an Output Control Code.

Associate printers with Report destinations in the CODESASSN file. See Modifying a CODESASSN File.

Add any special output control codes that are required by the printer to the CODES file. See Modifying a CODES File.

From Presentation Client, define each report destination as an alias in ROC. See Defining a ROC Alias for details. For example:

LincLp -S <server> -P <printer> [-C <class>] [-J <jobname>] [-O <option>]

Where:

• <server> specifies the name or IP address of the computer to which the printer is attached.

3826 5856-005 9–29

Report Operations

• <printer> specifies the name of the printer to which the print queue is directed.

• <jobname> specifies the name of the print job.

• <option> indicates the type of file.

For example:

LincLp -S finance -P finance_pr

This command directs all your print jobs to the printer called finance_pr, which is attached to the server called finance.

Note: Printing Services for UNIX (also known as TCP/IP printing services) must be installed and running on the server to which the printer is attached before a user can print. The printer may be attached to the user's workstation; in this configuration, the workstation acts as the print server.

Assigning Report Destinations

Defining a CODESASSN File

An empty CODESASSN file is created in the public data directory when you install the runtime software. You can modify the CODESASSN file using a text editor.

Each line of the file associates a report destination with a printer model, as outlined in the following table:

There must be at least one space between the values. Entries are case-sensitive.

In addition to defining the CODESASSN file, you must also:

• Ensure the printer models and any output control codes are included in the CODES file.

• Define each report destination as an alias in ROC. See Modifying a CODES File for details.

Example CODESASSN File

The following example shows lines from a CODESASSN file:

printer1 DIABLO630 printer2 PROPRINTER

Value Size Description

Report Destination 17 ROC alias; reports set the built-in attribute Glb.Stn to this value.

Printer Model 10 Actual name by which the printer is defined on your host in the CODES file.

9–30 3826 5856-005

Report Operations

In addition to defining the CODESASSN file, you must also:

1. Ensure DIABLO630 and PROPRINTER are defined in the CODES File. These printers are included in the default CODES file and will be present unless the file has been edited.

2. Define printer1 as a ROC alias for the Diablo 630 printer.

3. Define printer2 as a ROC alias for the Proprinter printer.

When you run a standard report with Glb.Stn set to printer1 and Glb.Device set to TP, output is sent to the Diablo 630 printer using output control codes defined in the CODES file for a printer model DIABLO630.

Printing Special Attributes

Different types of output devices use different instruction sequences to produce similar output (for example, printing in red).

When creating a specification, output control codes can be used to indicate that special output is to be produced.

The CODES file contains the association of model, output control code, and instruction sequence. It is used by ROC to produce output for standard reports.

Note: The CODES file must be saved in Unicode format and then be used by ROC, else a warning stating "Printer control code alias 'CODE1' not found in printer CODES file” is displayed.

For example, you might use the output control code RED in a standard report. To produce output on three different types of printer, three records are required in the CODES file, each with the appropriate instruction sequence.

Modifying a CODES File

Modify the default CODES file if you need to define an output control code for your reports, or you want to add a new printer model.

To modify the CODES file:

1. Make changes to the records in the file using the information in Formatting CODES File Records.

Notes:

• Do not remove output control code names beginning with bldc, as these correspond to data attributes (for example, bldcunder corresponds to UNDER).

• Do not include tab characters in the CODES file.

3826 5856-005 9–31

Report Operations

2. Place the CODES file in the public data directory.

Example CODES File

The following example is part of the default CODES file. Lines containing an ellipsis (. . .) indicate that records have been removed for clarity:

001 bldcbig 002 bldcreverse 003 bldcunder . . . 011 bldcforms1 012 bldcforms2 013 bldcblink 014 bldcbright 020 bldcoc# AP9215000PRINTER AP92150011B4Fbldcbig AP92150031B45bldcunder . . . AP9215012bldcforms2 NOFORM000VIDEO svt1210000VIDEO esvt12100021B5B376Dbldcreverse svt12100031B5B346Dbldcunder svt12100041B5B306Dbldcreset svt12100131B5B356Dbldcblink svt12100141B5B316Dbldcbright . . . DIABLO630000P DIABLO6300031B45bldcunder DIABLO6300041B261B52bldcreset . . . DIABLO6300111B511B12443120%bldcforms1 DIABLO6300121B0C(B1)1B12533020bldcforms2 DIABLO6300141B571B4Fbldcbright

Parts of this file are explained below:

• The following line is the availability record for the data attribute BIG. The unique number for this record is 001.

001 bldcbig

• The following line is the device header record for the printer type AP9215. AP9215000PRINTER

• The following line is the output code record that defines the characters (1B4F) to be sent to the printer AP9215 for Data Attribute BIG, which is attribute 001.

AP92150011B4Fbldcbig

• The following lines are output control records for the printer type DIABLO360. This is an example of a continued record. The continuation is indicated by the percent (%) sign at the end of the code in the first record. The continuation record requires its own availability and unique number.

DIABLO6300111B511B12443120%bldcforms1 DIABLO6300121B0C(B1)1B12533020bldcforms2

The previous lines are an example of the inclusion of a formdepth formula. Notice how two formdepth formulas have been used to produce the required sequence of characters. The full formdepth formula is:

1B511B124431201B0C(B1)1B12533020

9–32 3826 5856-005

Report Operations

Formatting CODES File Records

The CODES file contains records in the format specified in the following table:

When including an output control code or formdepth:

• Do not include spaces in the output control code or formdepth.

• Always include hexadecimal digits in pairs. Single digits are ignored.

• Always use uppercase values (A through F) in hexadecimal values.

• You can extend an output control code or formdepth formula over two records in the CODES file. To do this, append a percent character (%) to the end of the first record and continue the remainder starting in the code section of the next record. Continuation lines must include unique numbers.

Types of CODES File Records

The CODES file contains the following types of records:

Output control code availability records

The output control code availability records appear at the beginning of the CODES file. There is one record for each output control code used by any device. Each record consists only of the unique number and the output control code name.

Device header records

The records for each device must appear after the availability records. The first output device record is the device header record. It consists of the model and the number 000. Any additional characters in the record are treated as comments, and it is usual to include PRINTER (for a printer) or VIDEO (for a terminal) to indicate the type of device.

Output control code records

The output control code records for the device follow the device header record. These records have the model, unique number (which are defined in the availability records), hexadecimal sequence, and output control code name.

Name Size Description

Model 20 Model of output device

Number 3 Unique number to identify the output control codes

Code 20 Required hexadecimal code

Name 20 Name of the output control code

3826 5856-005 9–33

Report Operations

The hexadecimal sequence for an output control code is a sequence of two-digit hexadecimal numbers that are output to a printer. The hexadecimal sequence may be replaced with a formdepth formula.

Note: Do not remove output control code names beginning with bldc, as these correspond to data attributes (for example bldcunder corresponds to UNDER).

You can use a formdepth formula to define an output sequence to be sent to your output device for the output control code specified.

A formdepth formula is an extension of the sequence of hexadecimal values in the usual output control code.

Example of Defining an Output Control Code

This example demonstrates the creation and use of an output control code on a non-qualified printer type.

The senario for this example involves the printing of certain data in red on a special type of passbook printer, model PBP989. This requires an output control code to be created. The control sequence to make this type of printer use the red portion of the printer ribbon is ESC Q 3 $ (hexadecimal 1B 51 33 24).

Note: You also need an output control code (for example, BLACK) to set the printer back to its normal black color.


• Editing and Preparing a CODES File

• Defining a ROC Alias

• Modifying a CODESASSN File

• Using a New CODES File

Editing and Preparing a CODES File

Edit the default CODES file as follows:

1. After the record for bldcoc#, add a record that defines the name of the new output control code RED, as shown in the following example:

020 bldcoc# 022 RED AP9215 000PRINTER

2. Add a record defining the new printer model PBP989, and then add records that define the existing output control codes (for example, bold and underline). The following example shows a record that defines the new printer model:

DIABLO630 0141B571B4F bldcbright PBP989 000PRINTER

3. Add a record that defines the output control code RED, as shown in the following example:

DIABLO630 0141B571B4F bldcbright

9–34 3826 5856-005

Report Operations

PBP989 000PRINTER PBP989 0221B513324 RED

Note: Using this CODES file, only the RED output control codes have any effect when printing on the PBP989 printer. (Other output control codes can be defined as required.)

4. When you have finished modifying the CODES file, ensure that its format is correct by running the fixlen utility see Modifying a CODES File for further details.

5. Prepare the new CODES file for generation using Developer and ROC. See your Developer online help for details of using control codes when creating reports.

Defining a ROC Alias

1. Sign on to ROC through Prestenation Client.

2. Access the Alias screen, by entering AL in the command line.

3. Enter a ROC alias name and alias value.

Modifying a CODESASSN File

A CODESASSN file associates a report destination (as defined in Glb.Stn) with a model of printer, enabling the correct printer control codes to be used when you run a report to output device TP (as defined in Glb.Device), or when you print report output from ROC using the output device TP.

Add the ROC alias that you previously defined (Defining a ROC Alias) to the CODESASSN file. In the following example, the alias PBP989-ALIAS has been added to the file:

printer1 DIABLO630 printer2 PROPRINTER PBP989-ALIAS PBP989

Note: As per the instructions in Assigning Report Destinations entries are case-sensitive. The printer model must start at position 18 with at least one space between the values.

Using a New CODES File

1. In Developer, create a report.

2. Add a label to the report frame in Painter.

3. Add the output control code RED, to the ControlCodes property of the label.

4. You can then use the output control code of RED, as shown in the following example:

DATA; CREDITAMT ED; $ LE; 9 DE;2 Give it a direction of "Out" Use the painter to add a control code of ôREDö to it.

For automatic printing, the logic of the report must define Glb.Device and Glb.Stn, as shown:

MOVE "TP" Glb.Device MOVE "PBP989-ALIAS" Glb.Stn

3826 5856-005 9–35

Report Operations

5. Generate and run the report. Output of this frame will print the value of CREDITAMT in red on your printer named PBP989.

Note: You also need an output control code (for example, BLACK) to set the printer back to its normal color.

Overriding the Default FormDepth or PageDepth

FormDepth (or PageDepth) is a read-writable built-in outputstream attribute that is set to the number of printable lines of output on a page. For more information, see FormDepth topic in Developer Online help.

The default value of this attribute is dependent upon the device type chosen for the Report. Default values for each device type are listed in the following table:

You set the default for the FormDepth attribute for a Report by selecting the nominated device type. After the default is assigned, you can override the value of the FormDepth attribute programmatically using "MOVE" statements in their logic.

In the Windows Runtime application, you can also override the default FormDepth value using the Admin Tool.

To configure a number to override default FormDepth for your server:

1. Right-click the required server node, and select All Tasks > Set Form Depth. The Set Form Depth dialog box is displayed.

2. Select the Override Default Form Depth check box.

3. Enter a value in the Form Depth: box. This value overrides the default value of the FormDepth attribute.

4. Click OK.

Deleting ReportsBy using the following option from the Administration tool, you can delete all the reports that are no longer used in the application.

Device Type Default From Depth

LP 60 lines

TP 66 lines

VD (not IBM 3270) 48 lines

spaces 60 lines

9–36 3826 5856-005

Report Operations

Delete Obsolete Reports: Deletes all the obsolete reports and updates the runtime system for the current reports available in the model. To delete the obsolete reports, right-click the system in the Administration Tool, and select All Tasks > Delete Obsolete Reports.

3826 5856-005 9–37

Report Operations

9–38 3826 5856-005

Section 10 Using SQL Views


• About SQL Views

• Generating and Maintaining SQL Views

• What SQL Views are Created

• Using SQL Views

• Limits and Performance Issues with SQL Views

About SQL Views When you generate your System, you can choose to include SQL Views of your database. These views give you a logical view of the database structures, enabling you to make SQL queries (through SQL Server) by using the names of Profiles and Events, without requiring detailed knowledge of the structure of the database. In particular, Conditional Profile views are created so that joins are performed correctly and efficiently.

Data values used internally in your database are hidden, so that they do not interfere with terminal operation.

The database may not be updated using these views.

Generating and Maintaining SQL Views You can generate SQL Views by setting the Deploy SQL Views folder configuration property to True. See the Agile Business Suite Developer User Guide for details.

Maintenance of views will occur automatically during reorganization.

As part of the generation, SQL Views are created or dropped, as appropriate:

• If a System without SQL Views is generated with SQL Views selected, all SQL Views are created.

• If a System with SQL Views is generated with SQL Views selected, existing SQL Views are created, replaced, or dropped as appropriate.

3826 5856-005 10–1

Using SQL Views

• If a System with SQL Views is generated with SQL Views unselected, existing SQL Views are dropped.

Note: Generation time and disk usage will increase if you choose to generate SQL Views.

Files containing view maintenance commands are created in the system directory. The files are described in the following table:

The files VIEWS.sql, VIEWS.dsid.sql, and EVENTS.ext are removed if you choose not to generate SQL Views. Otherwise the files are retained.

What SQL Views are Created SQL Views are created for all the persistent classes which have Deploy SQL Views folder configuration property set to True. The naming convention that is followed for naming the views is its name of the class suffixed with "_V". For example, if there is a class by name CUST, the name of the view that will be created is CUST_V. The same applies for events and profiles.

Refer also to the descriptions in the following subsections.

• Keyed Classes

• Non-Keyed Classes

• Events

• Profiles

• Attribute

Keyed Classes

SQL Views of Keyed Classes are accessed using the index that is created for the class ordinate. These views enable you to perform the equivalent of the following logic command:

LookUp From start ClassNon-Keyed Classes

Views of View Name

VIEWS.sql Used for creating views in SQL Server.

VIEWS.dsid.sql Used for dropping views in SQL Server.

EVENTS.ext Stores events and its dependencies.

10–2 3826 5856-005

Using SQL Views

Non-Keyed Classes

SQL Views of Non-Keyed Classes do not use an index. These views enable you to perform the equivalent of the following logic command:

Determine Actual Class

To access a Class with a Default Profile, use the view over the Default Profile.

Events

SQL Views of individual Events and the view of the Event Set do not use an index.

The views for individual Events return only the attributes defined for those Events plus the Built-in Attributes Ispec, ActMth, GLB_REPORT, INPUT_DATE, XLAST_LINE, and XTRANNO. The view for Event Set returns all attributes, plus all Built-in attributes.

Profiles

SQL views of Event Profiles return all attributes declared in all events relevant to the Profile. Views over conditional Profiles select all the columns from the base table. Access is made using the conditional Profile index, so that records are automatically returned in Profile order.

Views over unconditional Profiles are the same as views over the Class, with the access made using the Profile index exceptions.

Attribute

Keywords are returned as a single group item when returning attribute values.

Using SQL Views

Logging in

To use SQL Views, log in as inquiry schema user in the MSSQL Query Analyser.

Normal Inquiry

In this example, a Profile CUSTPRO has an alphanumeric Profile Ordinate CUSTNAME. To access all records with the value SMITH for CUSTNAME enter:

select * from custpro_v where custname = “SMITH”;

Note: ORDER BY clauses are not necessary to achieve ordering in Profile Ordinate or Class Ordinate order, and may in fact degrade performance if used.

3826 5856-005 10–3

Using SQL Views

This is equivalent to the following logic command:

Determine Every CUST.CUSTPRO ("SMITH")

Inquiries over Events

Views over Events do not use a predefined index. If views over Events are used frequently or the Event Set population is large, you may get improved performance by creating an index over Event Set. For example, take the Event Set named “event”:

create index fispec over event (ispec);

If you usually sort in a particular order, add more keys after the key Ispec. For example:

create index fispec over event (ispec, invoicenum);

Note: If the Event Set table in the database is reorganized, this index may be dropped. You should ensure that the index is present following changes to persistent Event Built-in Attributes with persistence set to true, changes to Event Profiles, or garbage collections of the Event Set table.

Inquiries Using Descending Numeric Key

In this example, a Profile CUSTDESC has a numeric Profile Ordinate CUSTNUM. The Profile Ordinate is stored in descending order. To access all records from the value 47 for CUSTNUM, enter:

select * from custdesc_v where custnum <= 47;

The Profile Ordinate, CUSTNUM, is used in the WHERE clause, and the index will be defined as descending on the CUSTNUM column to get the correct ordering.

This SQL command is equivalent to the logic command:

Determine From CUST.CUSTDESC ( 47 )

Inquiries Using Descending Alphanumeric Key

In this example, a Profile CUSTINV has an alphanumeric Profile Ordinate CUSTNAME. Values of the Profile Ordinate are stored in descending order.

To access all records from the value JONES for CUSTNUM, key in the following:

select * from custinv_v where custname <= ’JONES’


Determine From CUST. CUSTINV ( "JONES" )

In the SQL command:

• The Data Item name used is custname.

10–4 3826 5856-005

Using SQL Views

• To find records where CUSTNAME is blank, key in the following: select * from database_custinv_v where custname is null;

where, database is the database name in the system specification.


DETERMINE; EVERY CUSTINV (GLB.SPACES)

Limits and Performance Issues with SQL Views

The following limits apply to SQL Views:

• To minimize the impact of runaway transactions, use the inquiry schema user. You can also test new queries on smaller populations.

• All views are created within the inquiry schema user as owner. Inquiry schema user is granted inquiry-only access over all tables and views, including those owned by deployment schema user.

• Views are not created for the stn tables. Views are not provided for ROC17 tables.

The following constructs may significantly degrade performance:

• Using ORDER BY clauses to achieve ordering in Profile Ordinate or Class Ordinate order (this order is automatic).

• Using WHERE clauses with Non-Keyed Class or Event views, where the population of the Non-Keyed Class or Event Set is large, but few records meet the condition.

• Using Keyed Class or Profile views with a WHERE clause including non-key items, or including lower-order keys without the higher-order keys.

3826 5856-005 10–5

Using SQL Views

10–6 3826 5856-005

Section 11 Migrating Data

The EAE DBMigrate Utility and LANGUAGE Migration Tool offer convenient ways to transfer and modify your application's data into a form that can be used in Agile Business Suite.

The EAE DBMigrate Utility consists of two sub features; DBMigrate for SQL 2008 and DBMigrate for SQL 2012.

Note: SQL Server Integration Service (SSIS) is required for installing EAE DBMigrate Utility. For more information on SSIS version and installation instructions, refer to the Agile Business Suite Installation and Configuration Guide.

To access EAE DBMigrate Utility and LANGUAGE Migration Tool:

Go to Start > Apps > Agile Business Suite 4.0 > (EAE DBMigrate Utility SQL 2008 or EAE DBMigrate Utility SQL 2012) or LANGUAGE Migration Tool.

Note: The name of the DBMigrate Utility depends on the version(s) of SQL Server and respective SSIS version installed in the machine. For example, if SSIS 2008 or SSIS 2012 is available, then the utility name will be either EAE DBMigrate Utility SQL 2008 or EAE DBMigrate Utility SQL 2012, whereas if both SSIS 2008 and SSIS 2012 are available, then the utility name will appear as EAE DBMigrate Utility SQL 2008 and EAE DBMigrate Utility SQL 2012 in the Start menu.

The following information includes:

• EAE Data Migration Wizard - EAE DBMigrate Utility opens this wizard

• Addressing Migration Issues

• LANGUAGE Migration Utility - LANGUAGE Migration Tool opens this wizard

EAE Data Migration Wizard The EAE Data Migration Wizard migrates data from an Enterprise Application 3.x application to an Agile Business Suite application.

Note: Before running the EAE Data Migration Wizard, your Agile Business Suite application must be deployed to a runtime server. The database needs to be empty, to avoid potential conflicts that can cause the migration process to fail.

It is recommended that the source and target databases be on the same machine. If necessary, copy the source database over to the migration machine.

3826 5856-005 11–1

Migrating Data

Database Migration Options • Source Database settings

• Target Database settings

• Options settings

• Advanced Migration Techniques

Source Database Settings

Specify details of the Enterprise Application 3.x database you are migrating from.

Source DB Type

This field displays the tab that is selected.

Source Machine

Enter the data source for an Enterprise Application MS SQL/Oracle database. If you are using the default instance, then local/localhost can be entered. You can specify a different named instance if you have one setup. The named instance could point to another machine, but that is dependent on SQL Server/Oracle's internal network support, rather than the EAE Data Migration Wizard.

Database

Enter the database (catalog) for an MS SQL database/Oracle database.

User Name

Enter a user name that has sufficient privileges to read the source database. The user account should be one that can connect to the database server using database authentication.

Password

Enter the corresponding password for the user name entered.

Schema and Logical DB

Enter the Schema, and Logical DB. The Schema is the 'owner' of the system application tables. If you look in Enterprise Manager, you will see the 'owner' of the SAMPLE tables is dbo.

The Logical DB is the table prefix used in the Enterprise Application Environment 3.3 tables. Examine the SAMPLE tables in Enterprise Manager, and you will notice the tables are prefixed with "SAMPLE". For example, SAMPLE_PROD and SAMPLE_PAUDT. You would enter SAMPLE for the Logical DB field in this case.

11–2 3826 5856-005

Migrating Data

Schema and Logical DB are derived from a table's name in the source database. For example, if the table name is LINC.DD_CUSTOMER, then Schema is "LINC", and the Logical DB is "DD".

Target Database settings

Specify details of the Agile Business Suite database you are migrating to.

Target DB Type

This field displays the tab that is selected.

Data Source

Enter the data source for an AB Suite MS SQL database. If you are using the default instance, then local/localhost can be entered. You can specify a different named instance if you have one setup. The named instance could point to another machine, but that is dependent on SQL Server internal network support, rather than the EAE Data Migration Wizard.

Database

Enter the database (catalog) for an MS SQL database, this is the deployed but empty Agile Business Suite application.

Schema

The Schema here also refers to the 'owner'. Once again, if you look in Enterprise Manager, you will see the 'owner' of the SAMPLE tables in Agile Business Suite is actually SAMPLE, not dbo. This is because the table names are no longer prefixed by the schema name. So you would enter SAMPLE in this field.

Schema is derived from a table's name in the source database. For example, if the table name is LINC.DD_CUSTOMER, then Schema is "LINC".

Options settings

Parallel Threads

Enter the number of parallel threads to be run during migration. The EAE Data Migration Wizard can use up to one thread per CPU on the migration machine.

3826 5856-005 11–3

Migrating Data

Advanced Migration Techniques

For larger databases (100s of GB), the following additional precautions may ensure adequate migration performance:

Pre-Migration 1. Deploy your Agile Business Suite model with an empty database. For the sake of

these instructions "SAMPLEDB" will represent the Sample Runtime Database in Agile Business Suite and "SP" the Sample Runtime Database in EAE.

2. Ensure the SQL Server Database Transaction Logging is set to Simple.

3. In the SQL Enterprise Manager, right-click on the Target database. For example, "SAMPLEDB". Select Properties > Options. Change "Recovery Model:" to Simple instead of Full, this is very important otherwise you will run out of disk space if the database is very large

If you wish to speed up migration create scripts for dropping and recreating all views as described below.

1. In the SQL Enterprise Manager, right-click the Target database. For example, "SAMPLEDB". Select All Tasks/Generate SQL Scripts. This will generate scripts that will create all tables and indexes. You can create your own scripts to drop views using the generated script as a guide. You can also create your own scripts to create table views and view them using the generated script as a guide. Only look at those areas in the generated scripts concerning views.

2. Drop all views using appropriate scripts.

See Sample Scripts for examples of each case.

3. Open up SQL Query analyzer. From menu select Tools/object browser/show/hide to ensure you can see the databases.

4. Look at <database name>/views. This is an example of what is to be dropped.

After executing the scripts you should have no more indexes or views.

Data Migration

Run DBMigrate as described above. This will take some time to complete for a large database and should say either "Successfully completed" or "Successfully completed with warnings". If anything goes wrong check the DBMlogs in C:\AB Suite 4.0\Data\public\log and search for "ERROR".

Note: DBMigrate relies on SQL Server's Data Transformation Services. This needs to be installed seperately from the SQL Server CDs. In SQL Server 2008, this is a separate installable on the CD. Refer to the note during Installation or during the Prerequisite Check in the AB Ready Tool.

Rebuilding Views

Recreate table views and view using scripts created above.

11–4 3826 5856-005

Migrating Data

After executing the scripts all required table view and views should be restored.

Sample Scripts DROP VIEW --------- if exists (select * from dbo.sysobjects where id = object_id(N’[TWHTUI].[ADGRPEXT]’) and OBJECTPROPERTY(id, N’IsView’) = 1) drop view [TWHTUI].[ADGRPEXT] GO CREATE TABLE INDEXES -------------------- CREATE UNIQUE INDEX [_XI_] ON [TWHTUI].[ADDRS]([_Id]) ON [PRIMARY] GO CREATE UNIQUE INDEX [ADDRSBDTP] ON [TWHTUI].[ADDRS]([DATAOWNR], [ADDRKEY], [TYPBODYIN], [TYPADRIN]) ON [PRIMARY] GO CREATE VIEWS AND THEIR INDEXES ------------------------------ SET QUOTED_IDENTIFIER ON GO SET ANSI_NULLS ON GO setuser N’TWHTUI’ GO CREATE VIEW "TWHTUI"."ADGRPEXT" WITH SCHEMABINDING AS (SELECT "ADGRP"."DATAOWNR", "ADGRP"."ADVERTID", "ADGRP"."HIERLVLP1", "ADGRP"."PRDGRP", "ADGRP"."_Id" FROM "TWHTUI"."ADGRP" "ADGRP" WHERE (( ISNULL("ADGRP"."DAYEXT", 0) = 0 ))) GO setuser GO SET QUOTED_IDENTIFIER OFF GO SET ANSI_NULLS ON GO set ANSI_PADDING,ANSI_WARNINGS,CONCAT_NULL_YIELDS_NULL,ARITHABORT,QUOTED_IDENTIFIER,ANSI_NULLS on GO set NUMERIC_ROUNDABORT off GO CREATE UNIQUE CLUSTERED INDEX [_XU_] ON [TWHTUI].[ADGRPEXT]([_Id]) ON [PRIMARY] GO set NUMERIC_ROUNDABORT off set arithabort OFF GO SET QUOTED_IDENTIFIER OFF SET ANSI_NULLS ON GO set ANSI_PADDING,ANSI_WARNINGS,CONCAT_NULL_YIELDS_NULL,ARITHABORT,QUOTED_IDENTIFIER,ANSI_NULLS on GO set NUMERIC_ROUNDABORT off GO CREATE UNIQUE INDEX [_XR_] ON [TWHTUI].[ADGRPEXT]([DATAOWNR], [ADVERTID], [HIERLVLP1], [PRDGRP]) ON [PRIMARY] GO set NUMERIC_ROUNDABORT off set arithabort OFF GO

Addressing Migration Issues While importing a data from Enterprise Application Environment release 3.3 to Agile Business Suite, you may encounter some issues and behavioral differences. You must follow the guidance given below for some of the migration issues:

3826 5856-005 11–5

Migrating Data

Migrating Profiles with Duplicates Not Allowed

In Enterprise Application Environment for Windows, a profile may be defined with duplicates not allowed, but nevertheless at runtime duplicated rows can be inserted. Agile Business Suite does not allow duplicated rows in such profiles.

This means that if duplicated rows are passed to Agile Business Suite during migration, they will be rejected.

To avoid migration problems, you should inspect all “duplicates not allowed” profiles in your Enterprise Application Environment data. There should be no duplicated rows in them. If there are, then either correct the data, or change the profile to allow duplicates.

Migrating User Maintained Tables

A user-maintained table provides database performance features that may not be available with System Modeler. The custom nature of user-maintained tables makes it impossible to migrate these tables automatically.

It is your responsibility to ensure that user-maintained tables are consistent and reorganized with corresponding class definitions.

LANGUAGE Migration Tool Language Migration Tool option in Start > Apps > Agile Business Suite 4.0 opens LANGUAGE Migration Utility.

The LLANGUAGE file contains internationalized versions of system messages that are sent from LDL.

This utility converts existing Enterprise Application 3.x LLANGUAGE files into equivalent language.rc files, suitable for use in Agile Business Suite.

LLANGUAGE Migration Options

To convert an existing Enterprise Application 3.x LLANGUAGE file into an Agile Business Suite language.rc file, complete the settings below, then click Convert.

Source File

Enter, or browse for, the name of an existing Enterprise Application 3.x LLANGUAGE file.

Output File

Enter, or browse for, the directory path Agile Business Suite language.rc file will be saved.

11–6 3826 5856-005

Migrating Data

Process to convert language.rc to language.dll

The language.rc file has to be converted to a language.dll to be used in AB Suite. Also, before converting the language.rc file to Language.dll there are a few steps that need to be followed in order to update the language.rc so that it is same as the latest file in AB Suite.

The following steps need to be followed:

1. The language.rc is obtained from the LLanguage file using the LLanguage Migration Tool.

2. Copy the strings from the file “ABSRuntimeMessages.txt” (which is available in the bin folder) at the end of the language.rc file i.e. after the line MSG_CLR_1500 "*".

3. Copy the following files to a working folder.

• Language.rc where in the latest strings are added.

• Latest resource.h file(available in bin folder)

• Existing Language.dll.

• rlman.exe (available in bin folder)

4. Create a Language.res file (compiled resource script) by running the command rcLanguage.rc

Note: The /i parameter may be required if the INCLUDE environmental variable is not defined.

The following headers are required. By default these are located at:

• afxres.h – C:\Program Files\Microsoft Visual Studio 11.0\VC\atlmfc\include

• winresrc.h – C:\Program Files\Microsoft Visual Studio 11.0\VC\PlatformSDK\Include

So the final command will be:

rc /i "C:\Program Files\Microsoft Visual Studio 10.0\VC\atlmfc\include" /i"C:\Program Files\Microsoft Visual Studio 10.0\VC\PlatformSDK\Include" Language.rc

5. Finally, create a new Language.dll by running the command rlman -r Language.dll Language.res Language.dll

This will replace the contents of the new resource file into the existing Language.dll

3826 5856-005 11–7

Migrating Data

11–8 3826 5856-005

Appendix A Related Product Information

The following publications contain information relevant to the definition and operation of a system. These publications are reference sources for users who have completed Agile Business Suite training courses. See your local Unisys representative for information on available training courses.

These documents are published by Unisys Corporation and are available on the Internet at http://www.support.unisys.com. Order hardcopy documents online through the Unisys Book Store at http://unisysbookstore.cgxsolutions.com/Home.aspx.

In addition to these documents, you may require documentation specific to your host to describe the operation of related software.

Unisys Agile Business Suite Installation and Configuration Guide

This document describes the installation of Agile Business Suite in standalone or multiuser environments and the administration of its working environment, including database administration, security and other issues.

Unisys Agile Business Suite Developer User Guide

This document provides information on using Developer System Modeler to design, develop, build and test systems on workstations.

Unisys Agile Business Suite LDL+ Programming Reference Guide

This document contains reference material for developers, such as logic commands and System Data items used in creating systems.

Unisys Agile Business Suite Runtime for Windows® Operating System Administration Guide

This document describes the generation and operation of systems and Reports and the general administration of systems on the Windows host.

Unisys Agile Business Suite Runtime for ClearPath MCP Operating System Administration Guide

This document describes the generation and operation of systems and Reports and the general administration of systems on the ClearPath MCP host.

3826 5856-005 A–1

Related Product Information

Unisys Agile Business Suite Component Enabler User Guide

This document describes how to configure your system for a Component Enabler application, how to configure the Component Enabler Generator and clients, and how to generate Component Enabler applications for use on client workstations or using the Web.

Unisys Agile Business Suite Component Enabler Class Reference

This document lists the different packages of objects generated by Component Enabler. Within each package, it describes the classes and interfaces, with a detailed description of the syntax and methods. To access the Component Enabler Class Reference, double-click the classref.exe file in the Component Enabler Client installation directory. The default installation directory is C:\NGEN_CE\Doc\classref. Once installed, double-click index.html to launch the Component Enabler Class Reference.

Unisys Agile Business Suite Component Enabler Class Reference Summary

This reference card is supplied in Acrobat PDF format to provide a quick reference by task to the common methods you would use to log on to a system using Component Enabler and retrieve data. It also lists the common response and error codes.

A–2 3826 5856-005

Index

A

AB Suite System Deployment Utility, 5–10access restriction to views, 2–15accessing

reports, 9–19adding

database, 2–8database server registration, 2–6runtime server, 2–6views, 2–13

administration commands, 3–1application related, 3–1DEL, 3–12HAM, 3–2HUB, 3–6HUB-, 3–8HUB+, 3–7LAM, 3–3LIS, 3–5REP, 3–9report related, 3–9RUN, 3–10SLA, 3–4SMG, 3–4STO, 3–6STR, 3–12TER, 3–13

administration security, 2–17Administration Tool, 2–1

navigation tree, 2–2anonymous user for views, 2–15APIs

Runtime, 6–1Application Administration Commands, 5–23applications

configuration options, 2–18deleting, 2–27disabling, 2–26enabling, 2–26stopping, 2–26, 3–6

asynchronous reports, 9–1, 9–5, 9–6, 9–8,9–18

B

built-in attributes and reports, 9–4

C

calling segment methods, 6–20COM+ interface

GenericClass, 6–9segment, 6–1

COM+ propertiesapplication related, 3–1DeleteReportRecovery, 3–12GetRecoverableReports, 3–9GetRunningReports, 3–9HighAccountMonth, 3–2IsHubEnabled, 3–7, 3–8ListIspecs, 3–5LowAccountMonth, 3–3RecoverReport, 3–10report related, 3–9RunReport, 3–10SendAMessage, 3–4SetLanguage, 3–4StopReport, 3–12StopSystem, 3–6

COM+properties, 3–1application related, 3–1GetHubStatus, 3–6

Command Line Utilities, 5–1command prompt

recovering reports initiated from, 9–14runnig reports from, 9–6running reports from, 9–7

configuration options, 2–18customize, 2–18HUB, 2–21multilanguage, 2–21

Configure Log Files Utility, 5–2Configure Protocol Adapters Utility, 5–5configuring

a system, 2–18protocol adapters, 2–12

3826 5856-005 Index–1

Index

views, 2–14connect method, 6–1CreateInstance method, 6–2creating

a new database, 2–9reports, 9–1views, 2–13

CriticalPoint logic command, 9–4

D

databaseadding, 2–8, 2–9, 2–10creating new, 2–9deleting, 2–11detaching, 2–11preparing, 2–10removing, 2–10, 2–11

database server registrationadding, 2–6removing, 2–7

database structure, 8–1events, 8–3profiles, 8–3tables, 8–1, 8–2

defining a ROC alias, 9–17defining report printers, 9–28deleting

a database, 2–11a system, 2–27report recovery information, 3–12

DEPCON reports, 9–3, 9–13deployed applications, 2–16Deployment Package Manager Utility, 5–14detaching a database, 2–11direct reports, 9–3, 9–12disabling a system, 2–26Disconnect method, 6–2

E

enabling a system, 2–26External Automatic Entries

disabling, 2–21, 3–8enabling, 2–21, 3–7immediate commit, 7–7limitations, 7–3overview, 7–2security issues, 7–7

sending, 7–5series of, 7–7status, 2–21, 3–6TCP/IP ports, 7–4two-phase commit, 7–7

F

field namesGenericClass, 6–10

FormDepthoverride, 9–36

G

Generalized Interface (See GLI), 7–19GenericClass COM+ interface, 6–9GetArrayValue method, 6–11GetMessage method, 6–11GetNumMessages method, 6–11GetValue method, 6–11Glb.ASCPrt, 9–4Glb.Destination, 7–9Glb.Device, 9–4Glb.Priv, 7–9, 7–28, 9–4Glb.Source, 7–28Glb.Status, 7–9Glb.Stn, 7–28, 9–4Glb.Task, 9–4Glb.Work, 7–28GLI

data records, 7–19definition status, 7–19DESTINATION attribute, 7–19ERROR.MSG attribute, 7–19finish record, 7–19formatted data requirements, 7–19header record, 7–19input records, 7–19Ispec record format, 7–19LOG attribute, 7–19ORIGIN attribute, 7–19output records, 7–19overview, 7–19recovery, 7–19REQD.ACK attribute, 7–19running, 7–19SOURCE attribute, 7–19transaction status, 7–19

Index–2 3826 5856-005

Index

unformatted data records, 7–19unformatted data requirements, 7–19

GLI.EXE, 7–19GLI.SETUP.DATA attribute, 7–19

H

header record GLI, 7–19High account month

administration command, 3–2Administration tool, 2–18COM+ property, 3–2

HUBconfiguration, 2–21disabling, 2–21, 3–8enabling, 2–21, 3–7

HUB(see External Automatic Entries), 7–2

I

IConfigureRuntime Interface, 5–44IIspecCycle interface, 6–15immediate commit HUB, 7–7initiating ROC, 9–17interface

GenericClass COM+, 6–9IIspecCycle, 6–15ISegmentCycle, 6–9segment COM+, 6–1

invoking NOF, 7–10ISegmentCycle interface, 6–9ispec, 1–1ispec logic

accessing report from, 9–18running reports from, 9–6

ispec messagesprocessing, 6–16

ispecsdata for GLI, 7–19finish record data for GLI, 7–19formatted data requirements for GLI, 7–19listing, 3–5unformatted data records for GLI, 7–19unformatted data requirements for GLI,

7–19

L

labels.costomizing for RATL, 2–14language


listing ispecsadministration command, 3–5COM+ property, 3–5

listing reportsadministration command, 3–9COM+ properties, 3–9

login labels.customizing for RATL, 2–14Low account month


M

managingapplications, 2–16expired reports, 9–18

method, 1–1Connect, 6–1CreateInstance, 6–2Disconnect, 6–2GetArrayValue, 6–11GetMessage, 6–11GetNumMessages, 6–11GetValue, 6–11ProcessMsg, 6–3SetArrayValue, 6–11SetValue, 6–10

Microsoft Management Console, 2–37migrating

database, 11–1LANGUAGE, 11–6

monitoring performance, 2–37MOVE.AUTO command, 7–5

N

NOFformat for sending program, 7–10input data, 7–10invoking, 7–11Overview, 7–10

3826 5856-005 Index–3

Index

Non Formatted Input/Output (See NOF), 7–10

O

OFF.EXE, 7–28running, 7–28

Offline Inputclient program, 7–28executing program, 7–28formatting for, 7–28how it works, 7–28recovery, 7–28

output locations for reports, 9–9, 9–10, 9–12,9–13

P

Page Depthoverride, 9–36

passing parameters to reports, 9–8performance monitoring, 2–37preparing a database, 2–10printers, 9–28

TCP for formatted text, 9–29TCP for text only, 9–28Windows (standard), 9–28

printingreports, 9–27

processing ispec messages, 6–16ProcessMSG method, 6–3Programmatic Access to Runtime, 5–43programming interfaces

Runtime, 6–1protocol adapter, 1–1, 7–1protocol adapters

configuring, 2–12GLI, 7–19HUB, 7–2NOF, 7–10OFF, 7–19RATL, 7–2SOAP, 7–1USER, 7–8views, 2–13, 7–30

R

RATL, 7–2

over MSMQ, 7–2over TCP/IP, 7–2

RATL login labelscustomizing, 2–14

reconfiguing external persistent class utility,5–41

Reconfigure External Persistent Class Utility,5–41

recoveringGLI, 7–19Offline Input, 7–28reports, 2–37, 3–10, 9–13, 9–14, 9–15

removinga database, 2–10a server, 2–6database server registration, 2–7

reportoutput locations, 9–13

Report Administration Commands, 5–33Report Output Control (See ROC), 9–15reports, 1–1, 9–1

accessing from ASP.NET Web Forms, 9–21accessing from ispec logic, 9–18accessing from Presentation Client, 9–19accessing from VB.NET Winforms, 9–25asynchronous, 9–1, 9–5, 9–6, 9–8, 9–18built-in attributes, 9–4creating, 9–1CriticalPoint command, 9–4deleting recovery information, 2–35, 3–12DEPCON, 9–3, 9–13direct, 9–3, 9–12enabling recovery, 9–4listing, 3–9output locations, 9–9, 9–10, 9–12passing parameters to, 9–8printing, 9–27recovering, 2–37, 3–10, 9–13, 9–14, 9–15recovering parameter data, 9–8redirecting, 9–7replying to input request, 9–7Report Session Manager, 9–5running, 2–35, 9–5, 9–6, 9–8standard, 9–2, 9–10stopping, 2–35, 3–12synchronous, 9–1, 9–5terminating active, 3–13terminating running, 2–35, 3–12using returned values, 9–8viewing properties, 2–36

return values for reports, 9–8ROC, 9–15

Index–4 3826 5856-005

Index

ASP.NET Webforms, 9–21defining alias, 9–17expired reports, 9–18initiating, 9–17logic command, 9–18

runningGLI program, 7–19Offline Program, 7–28reports, 2–35, 3–10, 9–5, 9–6, 9–7, 9–8

Runtime Operations Utility, 5–22Runtime overview, 1–1, 4–8

S

scale-out, 2–12security

administration, 2–17External Automatic Entries, 7–7views, 2–15

segment COM+ interface, 6–1segment method

interface, 6–23segment methods

calling, 6–20sending a message

administration command, 3–4COM+ property, 3–4

sending external Automatic Entries, 7–5server

adding, 2–6servers

removing, 2–6scale-out, 2–12

SetArrayValue method, 6–11settings

Source Database, 11–2SetValue method, 6–10SOAP, 7–1

over HTTP, 7–1over MSMQ, 7–1

SQL ViewsAttributes, 10–3Events, 10–3Keyed Classes, 10–2Non-Keyed Classes, 10–3Profiles, 10–3

standard reports, 9–2, 9–10station data file, 2–4stopping

reports, 2–35, 3–12

systems, 2–26, 3–6synchronous reports, 9–1, 9–5System Monitor, 2–37systems

configuration options, 2–18deleting, 2–27disabling, 2–26enabling, 2–26reports, 2–35stopping, 2–26, 3–6

T

TCP/IP ports, 7–4terminating

active Report, 3–13running Reports, 2–35, 3–12

Troubleshooting Runtime API Operations,5–77

two-phase commitExternal Automatic Entries, 7–7

U

USER (See User Interface), 7–8User Interface

how it works, 7–8sample program, 7–9sending a transaction, 7–9

USERRTN.CBL, 7–9Using SQL Views, 10–1

About SQL Views, 10–1Generating and Maintaining SQL Views,

10–1Limits and Performance Issues with SQL

Views, 10–5Using SQL Views, 10–3What SQL Views are Created, 10–2

utility, 11–6

V

views, 7–30anonymous user, 2–15creating, 2–13defining access, 2–15general configuration, 2–14SQL server, 8–3

3826 5856-005 Index–5

Index

W

wizard, 11–1wizards, 2–1, 3–1, 6–1, 7–1, 10–1, 11–1

Index–6 3826 5856-005

Unisys

*38265872-003*3826 5856-005