Agile Business Suite Runtime for Windows Operating System

Agile Business Suite
Runtime for Windows Operating System
Administration Guide
Unisys
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 absuite.pi@unisys.com.
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–2
Audience .......................................................................................................................1–2
Documentation Update .............................................................................................1–2
Section 2.
Runtime Administration.........................................................2–1
Using the Administration Tool .................................................................................2–1
Using the Scope Pane ........................................................................ 2–2
Defining Network Users ..........................................................................................2–4
The Station Info (LINCIINET) File .......................................................2–4
Creating a Station Info (LINCIINET) File ........................................... 2–5
Setting Up Your Runtime Environment ................................................................ 2–6
Adding a Runtime Server .................................................................. 2–6
Removing a Server from Favorites .................................................. 2–6
Adding a Database Server Registration ......................................... 2–6
Removing a Database Server Registration ................................... 2–7
Configuring User Rights to Add or Remove a Database ............2–8
Adding a Database ..............................................................................2–8
Removing a Database ...................................................................... 2–10
Using Scale-Out ...................................................................................2–11
Configuring Protocol Adapters ............................................................................ 2–12
Configure Adapters Dialog Box ...................................................... 2–13
Creating Views .................................................................................. 2–13
Configuring Log Files .............................................................................................. 2–16
Managing Your Application ................................................................................... 2–16
Security ................................................................................................ 2–17
Working with Systems ..................................................................... 2–17
Setting Up AB Suite for Database Mirroring ...............................2–33
Reports .................................................................................................2–35
Monitoring Performance .................................................................2–37
Section 3.
Using Administration Commands ........................................ 3–1
Application Related Commands ............................................................................ 3–1
Setting or Displaying High Account Month .................................... 3–2
Setting or Displaying Low Account Month ....................................3–3
Setting or Displaying the Language .................................................3–4
Sending a Message .............................................................................3–4
Listing Ispecs ........................................................................................3–5
Stopping an Application ......................................................................3–6
Display External Automatic Entry Status ........................................3–6
Enabling External Automatic Entries ............................................... 3–7
3826 5856-005
iii
Contents
Disabling External Automatic Entries .............................................3–8
Displaying a list of active stations ...................................................3–8
Report Administration Commands ........................................................................ 3–9
Listing Running and Recoverable Reports ..................................... 3–9
Running and Recovering Reports .................................................. 3–10
Deleting Recovery Information ..................................................... 3–12
Stopping a Report .............................................................................. 3–12
Terminating an Active Report ......................................................... 3–13
Wake Up Report ................................................................................ 3–15
Admin.exe Command Line Utility ........................................................................ 3–16
Section 4.
Deployment Package Manager .............................................4–1
Prerequisites for DPM .............................................................................................. 4–1
Create Cloned MSIs of Existing MSIs ................................................................... 4–2
Update the Package Parameters of Cloned MSI ................................................4–3
Create Partial MSIs for Cloned MSIs .....................................................................4–3
Deploying MSIs or CAB Files Using Runtime Transfer .....................................4–4
Executing DPM from Command Prompt .............................................................4–5
Creating 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–1
Configure Log Files Utility (ConfigureLog.exe) .............................. 5–2
Configure Protocol Adapters Utility (ConfigureAdapter.exe) .... 5–5
AB Suite System Deployment Utility (DeployPackage.exe) .... 5–10
Deployment Package Manager Utility (ManagePackage.exe) . 5–14
Runtime Operations Utility (AdminSystem.exe) ......................... 5–22
Application Administration Commands ........................................5–23
Report Administration Commands ................................................5–33
Reconfigure External Persistent Class Utility
(EPCReconfigure.exe) .................................................................. 5–41
Programmatic Access to Runtime .......................................................................5–43
IConfigureRuntime Interface .......................................................... 5–44
IDeployPackage Interface ................................................................5–50
IAdministerSystem Interface ..........................................................5–62
Troubleshooting Runtime API Operations .........................................................5–77
Section 6.
Runtime Programming Interfaces.........................................6–1
Segment COM+ Interface ....................................................................................... 6–1
Connect() ............................................................................................... 6–1
Disconnect() ......................................................................................... 6–2
CreateInstance() ................................................................................... 6–2
ProcessMsg() ........................................................................................ 6–3
Admin() ................................................................................................... 6–3
Handling Unsolicited Messages ....................................................... 6–3
IMessages Object ................................................................................ 6–3
ICallBack Object ...................................................................................6–4
Connect() ................................................................................................ 6–5
iv
3826 5856-005
Contents
General Processing ..............................................................................6–5
Using Messages COM Object to handle Unsolicited Messages .....
6–6
Definition of ISegmentCycle Interface ............................................6–9
GenericClass COM+ Interface ................................................................................6–9
GenericClass Field Names .............................................................. 6–10
SetValue() ............................................................................................. 6–10
GetValue() ............................................................................................6–11
SetArrayValue() ....................................................................................6–11
GetArrayValue() ...................................................................................6–11
GetNumMessages() ..........................................................................6–11
GetMessage() .....................................................................................6–11
GetMaxCopies() ...................................................................................6–11
GetNumDynamicLists() ......................................................................6–11
GetDynamicList() ................................................................................ 6–12
Initialize() ............................................................................................... 6–13
CreateCopy() ....................................................................................... 6–13
GetSwitchToData() ............................................................................. 6–13
GetSwitchToData2() ........................................................................... 6–13
Definition of IIspecCycle Interface ................................................. 6–15
Processing Ispecs via the Segment COM Interface ........................................ 6–16
Processing Ispec Messages ........................................................... 6–16
Unmanaged C++ Example ............................................................... 6–17
Managed .NET C# Example ............................................................. 6–18
Calling Segment Methods .....................................................................................6–20
Unmanaged C++ Example ............................................................... 6–21
Managed .NET C# Example ............................................................. 6–21
Using 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–1
RATL over TCP/IP and RATL over MSMQ ........................................................... 7–2
HUB (External Automatic Entries) .......................................................................... 7–2
Preparing Projects in Developer ....................................................... 7–3
Communicating with Other Hosts ..................................................7–4
Sending External Automatic Entries ............................................... 7–5
How an External Automatic Entry Works ...................................... 7–5
Security Issues with External Automatic Entries ........................ 7–7
USER (User Interface) ...............................................................................................7–8
Sending a Transaction ........................................................................ 7–9
Sample User Program ......................................................................... 7–9
NOF/OFF/GLI ............................................................................................................. 7–10
Non-Formatted Input/Output (NOF) ............................................... 7–10
GLI (Generalized Interfaces) ............................................................. 7–19
Offline Input .......................................................................................7–28
Views .........................................................................................................................7–30
Security ......................................................................................................................7–30
Section 8.
3826 5856-005
Database Structure ............................................................... 8–1
v
Contents
Database Tables ......................................................................................................... 8–1
_Id Column ............................................................................................ 8–1
Ordinates ............................................................................................... 8–2
Naming Conventions .......................................................................... 8–2
Adding a new Column ......................................................................... 8–2
Profiles ........................................................................................................................8–3
Events
.........................................................................................................................8–3
User Maintained Tables ............................................................................................8–3
.......................................................................................................................................8–4
Section 9.
Report Operations..................................................................9–1
Creating Reports ........................................................................................................ 9–1
Standard Reports ................................................................................. 9–2
Direct Reports ......................................................................................9–3
Enterprise Output Manager Reports ............................................. 9–3
Built-in Attributes and Reports ........................................................9–4
Using the CriticalPoint Logic Command ........................................9–4
Running Reports ....................................................................................................... 9–5
Report Session Manager ..................................................................9–5
Running Asynchronous Reports from Ispec Logic ......................9–6
Running Asynchronous Reports from Presentation Client .......9–6
Running Asynchronous Reports from a Command Prompt
Window ............................................................................................9–6
Running Asynchronous Reports from a Client Interface or COM+
9–8
Passing Parameters to a Report ...........................................................................9–8
Recovering Parameter Data for Reports ........................................9–8
Using Returned Values from a Report
................................................................9–8
Where Report Output is Located ..........................................................................9–9
Standard Report Output .................................................................. 9–10
Location of Standard Report Output ............................................. 9–10
Security of Standard Report Output ..............................................9–11
Direct Report Output ........................................................................ 9–12
Enterprise Output Manager Report Output ................................ 9–13
Recovering Reports ............................................................................................... 9–13
Recovering Reports Initiated with the Run Logic Command . 9–14
Recovering Reports Initiated from a Command Prompt Window .
9–14
Recovering Reports Initiated with the :RUN Command ........... 9–15
Extended Report Recovery ............................................................ 9–15
Report Output Control (ROC) ................................................................................ 9–15
Initiating ROC ...................................................................................... 9–17
Defining a ROC Alias ......................................................................... 9–17
Managing Expired Reports ............................................................. 9–18
Accessing ROC from Ispec Logic ................................................. 9–18
Accessing ROC from standalone Presentation Client .............. 9–19
Accessing ROC from Presentation Client as a Browser Applet ......
9–20
Accessing ROC from ASP.NET Web Forms ................................ 9–21
Accessing ROC from VB.NET Winforms .....................................9–25
Printing Reports ......................................................................................................9–27
vi
3826 5856-005
Contents
Defining Printers ...............................................................................9–28
Assigning Report Destinations ...................................................... 9–30
Printing Special Attributes ............................................................... 9–31
Formatting CODES File Records .....................................................9–33
Example of Defining an Output Control Code ............................ 9–34
Overriding the Default FormDepth or PageDepth .......................................... 9–36
Deleting Reports ..................................................................................................... 9–36
Section 10.
Using SQL Views ..................................................................10–1
About SQL Views ....................................................................................................10–1
Generating and Maintaining SQL Views ..............................................................10–1
What SQL Views are Created .............................................................................. 10–2
Keyed Classes ................................................................................... 10–2
Non-Keyed Classes .......................................................................... 10–3
Events .................................................................................................. 10–3
Profiles ................................................................................................ 10–3
Attribute .............................................................................................. 10–3
Using SQL Views .................................................................................................... 10–3
Limits and Performance Issues with SQL Views ...................... 10–5
Section 11.
Migrating Data ...................................................................... 11–1
EAE Data Migration Wizard ................................................................................... 11–1
Source Database Settings ...............................................................11–2
Target Database settings ..................................................................11–3
Options settings ..................................................................................11–3
Advanced Migration Techniques .....................................................11–4
Addressing Migration Issues .................................................................................11–5
LANGUAGE 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 Guide
The 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.
Audience
The primary audience for this document consists of Windows administrators and
application developers who are building and deploying database-centric applications.
Documentation Update
This 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 2
Runtime Administration
The Runtime installation includes three Microsoft Management Console (MMC) snapins, 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 Tool
The 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
2–2
Name
Description
Administration Tool snap-in
The root node of the Administration Tool MMC snapin.
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.
3826 5856-005
Runtime Administration
Icon
Name
Description
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.
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.
3826 5856-005
2–3
Runtime Administration
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 following topics are covered in this section:
•
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
Runtime Administration
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>
Name
User ID or Station
name
Maximum
Size
40
Description
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.
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.
3826 5856-005
2–5
Runtime Administration
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
Runtime Administration
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
Runtime Administration
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:
2–8
•
Create a new database
•
Attach an existing database
3826 5856-005
Runtime Administration
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
Runtime Administration
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:
2–10
•
Deleting a database
•
Detaching a database
3826 5856-005
Runtime Administration
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
Runtime Administration
•
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
Runtime Administration
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
Runtime Administration
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.
•
3.
The runtime server to which the view relates.
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:
•
2–14
If you select RATL over MSMQ, you must also enter the name of the message
queue to be used.
3826 5856-005
Runtime Administration
•
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
Runtime Administration
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
Runtime Administration
The following topics are covered in this section:
•
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:
Administrative Function
Enabling/Disabling HUB
COM+Role(s)
Hub Administrators
Application Administrators
Setting High Account Month
Accountants
Application Administrators
Setting Low Account Month
Accountants
Application Administrators
Running a Report
Report Runners
Report Administrators
Application Administrators
Stopping a Report
Report Runners (Own reports only)
Report Operators
Report Administrators
Application Administrators
Working with Systems
System nodes represent the applications deployed on a selected database.
The available administration options for applications are:
•
Configuration Options
3826 5856-005
2–17
Runtime Administration
•
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
Runtime Administration
<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
Runtime Administration
<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
Runtime Administration
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
Runtime Administration
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
2–22
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.
3826 5856-005
Runtime Administration
Name
Type
Description
Default Value
Rules
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
Runtime Administration
Name
2–24
Type
Description
Default Value
Rules
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 09999. 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 09999. 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
3826 5856-005
Runtime Administration
Name
Font
Type
Combo
Box
Configure Printer
Names
Button
Description
Default Value
Select the
desired font
name for
printing. The
drop-down list
will show the
font names
available on that
particular
machine.
LincDefault New
To set the
Default Printer
name and the
EOM Printer
name
N/A
Rules
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
On clicking this button,
the “Configure Printer
Names” dialog box is
opened for configuring
the Default Printer
name and EOM Printer
Name.
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.
Name
Type
Description
Default Value
Rules
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
Runtime Administration
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:
Name
Type
Description
Default Value
Rules
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.
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.
2–26
3826 5856-005
Runtime Administration
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
Runtime Administration
2.
Select Retain existing database to reorganize the existing application database.
If this option is not selected, a new database is built.
Caution
Reorganizing 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.
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:
2–28
3826 5856-005
Runtime Administration
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
Runtime Administration
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.
The List of Deployment Packages dialog box appears.
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
Runtime Administration
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
Runtime Administration
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
Runtime Administration
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 Server
1.
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 Server
1.
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 Server
1.
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
Runtime Administration
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 principal
DB>
4. Update the login after it is created.
Query: exec sp_change_users_login ’Update_One’, ’<Schema login name>’, ’<Schema
login 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)”.
•
2–34
Mirror server database status “SAMPLEDB (Restoring...)”.
3826 5856-005
Runtime Administration
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:
3.
•
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.
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
Runtime Administration
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:
2–36
•
Recovery key (if relevant)
•
User name
•
Status
–
A – Abort
–
I – Initializing
–
X – Running
–
R – Recovering
•
Device type
•
Language
•
Parameters
3826 5856-005
Runtime Administration
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
Runtime Administration
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 3
Using 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
Description
Security
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
Command
Method/Property
Security
Required
Description
: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
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.
3–2
3826 5856-005
Using Administration Commands
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
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
Accountants
•
Application Administrators
3826 5856-005
3–3
Using Administration Commands
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
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
Application Administrators
•
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
Using Administration Commands
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
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
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
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
Application Administrators
•
Application Operators
3826 5856-005
3–5
Using Administration Commands
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
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
Application Operators
•
Application Administrators
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
Using Administration Commands
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
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
HUB Monitors
•
HUB Administrators
•
Application 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
Using Administration Commands
Security
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
HUB Administrators
•
Application Administrators
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
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
HUB Administrators
•
Application Administrators
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
Using Administration Commands
Report Administration Commands
Command
Method
Description
Security
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
Listing Running and Recoverable Reports
Use this command to display information about the reports in an application.
The information displayed includes:
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
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.
3826 5856-005
3–9
Using Administration Commands
Security
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
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
•
3–10
params is a string literal (enclosed in quotation marks) to pass to the report.
3826 5856-005
Using Administration Commands
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
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
Report Runners
•
Report Administrators
•
Application Administrators
3826 5856-005
3–11
Using Administration Commands
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
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
Report Runners (can delete the information of reports they have initiated)
•
Report Recovery Operators
•
Report Recovery Administrators
•
Report Administrators
•
Application Administrators
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:
3–12
•
report is the name of the report.
•
process is the process ID of the report.
3826 5856-005
Using Administration Commands
COM+ method
StopReport(VARIANT vtReport, StopReportFlags)
Where:
•
vtReport is the name of the report.
•
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
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
Report Runners (only able to stop reports they have initiated)
•
Report Operators
•
Report Administrators
•
Application Administrators
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.
Caution
If the report contains Sleep logic statements, transactions prior to the last
Sleep logic statement are committed to the application database.
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:
•
report is the name of the report.
•
process is the process ID of the report.
3826 5856-005
3–13
Using Administration Commands
•
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:
•
vtReport is the name of the report.
•
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
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
3–14
3826 5856-005
Using Administration Commands
•
Report Runners (only able to stop reports they have initiated)
•
Report Operators
•
Report Administrators
•
Application Administrators
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
Using Administration Commands
Security
Users must be a member of one of the following COM+ roles in order to access this
administrative function:
•
Application Administrators
•
Report Administrators
•
Report Operators
•
Report Recovery Administrators
•
Report Recovery Operators
•
Report Runners
Admin.exe Command Line Utility
Runtime 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
Using Administration Commands
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
Using Administration Commands
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 DPM
For 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 prerequisite 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 MSIs
Perform the following steps to create a cloned MSI:
1.
Go to AB Suite Installation package/CD Runtime/
DeploymentPackageManager, and double-click DPM-GUI.exe.
The Deployment Package Manager dialog box appears.
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.
4–2
Click Exit to exit the DeploymentPackageManager dialog box.
3826 5856-005
Deployment Package Manager
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:
1.
Go to AB Suite Installation package/CD Runtime/
DeploymentPackageManager, and double-click DPM-GUI.exe.
The Deployment Package Manager dialog box appears.
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.
6. Click Exit to exit the DeploymentPackageManager dialog box.
Create Partial MSIs for Cloned MSIs
DPM 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:
1.
Go to AB Suite Installation package/CD Runtime/
DeploymentPackageManager, and double-click DPM-GUI.exe.
The Deployment Package Manager dialog box appears.
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
Deployment Package Manager
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.
6. Click Exit to exit the DeploymentPackageManager dialog box.
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.
The List of Deployment Packages dialog box appears.
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.
4–4
Select the Target DB Name.
3826 5856-005
Deployment Package Manager
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 Prompt
Perform 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
Deployment Package Manager
Argument
Description
-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.
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
4–6
3826 5856-005
Deployment Package Manager
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
Deployment Package Manager
•
Database Schema Name
•
Database Name
11. Click Apply and OK.
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 Utilities
This subsection discusses about the following command line utilities.
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
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.
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
Command Line and Programmatic Access to Runtime
Parameters
Argument
Description
/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
/LL
Error|Warning|Info|Debug
/E true
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
Command Line and Programmatic Access to Runtime
Argument
/L <location>
Description
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
/?
5–4
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.
3826 5856-005
Command Line and Programmatic Access to Runtime
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.
Examples
1.
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
Command Line and Programmatic Access to Runtime
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
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
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
Argument
/TCPIP <[RATL|HUB]>
Description
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
Command Line and Programmatic Access to Runtime
Argument
Description
/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 /?
3826 5856-005
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.
5–7
Command Line and Programmatic Access to Runtime
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
Argument
/MSMQ <[RATL|SOAP]>
Description
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
Command Line and Programmatic Access to Runtime
Argument
/L <FilePath>
Description
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
/MSMQ /?
/N 1
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.
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.
3826 5856-005
5–9
Command Line and Programmatic Access to Runtime
•
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.
•
If you pass duplicate arguments, the error message “Encountered duplicate
arguments. Please address the duplicates before proceeding” 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
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 “DeployPackage.exe /?”. This displays the complete usage of the utility.
5–10
3826 5856-005
Command Line and Programmatic Access to Runtime
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
Argument
/L <DeployPackagePath>
Description
Specifies the MSI package or CAB files to be deployed along
with the complete path. You should specify the absolute file
path.
Notes:
•
This argument is mandatory.
•
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
Command Line and Programmatic Access to Runtime
Argument
/U <UserName>
Description
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:
•
This argument is mandatory.
•
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:
•
This argument is mandatory.
•
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
Command Line and Programmatic Access to Runtime
Argument
/RDB <true|false>
Description
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
<TargetDatabaseRegistratio
n>
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
Command Line and Programmatic Access to Runtime
Argument
Description
/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.
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 duplicate arguments, the error message “Encountered duplicate
arguments. Please address the duplicates before proceeding” appears.
•
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
5–14
•
Upgrade the cloned MSI
•
Create partial MSIs to generate new or updated report files for the cloned system
3826 5856-005
Command Line and Programmatic Access to Runtime
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
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 “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
Argument
/C
Description
Specifies whether you want to create a clone of the builder
generated MSI package or CAB files.
Notes:
3826 5856-005
•
This argument is mandatory.
•
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.
5–15
Command Line and Programmatic Access to Runtime
Argument
/BP
<SourcePackageLocation>
Description
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:
/DB <DBName>
The default path is "My Documents".
Specifies the target database name of the DPM generated
package.
Note:
"DB".
The default value is the Instance name appended with
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>
5–16
Specifies the Database server registration name.
Note:
The default value is the builder generated value.
3826 5856-005
Command Line and Programmatic Access to Runtime
Argument
/IN <InstanceName>
Description
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:
/C /?
•
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.
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.
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>]
3826 5856-005
5–17
Command Line and Programmatic Access to Runtime
[/DBS <DBSchema>] [/DBR <DBServerRegistration>]
[/PD <PackageDir>] [/O <true|false]>] [/?]
Parameters
Argument
/U
Description
Specifies whether you want to update the package
parameters of a cloned MSI.
Notes:
/BP
<SourcePackageLocation>
•
This argument is mandatory.
•
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.
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 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
Command Line and Programmatic Access to Runtime
Argument
/DP
<DPMGeneratedPackage>
Description
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.
Note:
/DB <DBName>
The default path is "My Documents".
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:
/U /?
3826 5856-005
•
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.
•
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.
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.
5–19
Command Line and Programmatic Access to Runtime
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
Argument
/P
Description
Specifies whether you want to create partial MSI of a cloned
MSI.
Notes:
/BP
<SourcePackageLocation>
•
This argument is mandatory.
•
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.
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 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
Command Line and Programmatic Access to Runtime
Argument
/DP
<DPMGeneratedPackageLoc
ation>
Description
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.
Note:
/IN <InstanceName>
The default path is "My Documents".
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:
/P /?
•
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.
•
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.
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.
Examples
1.
The following command creates partial clone for an MSI.
3826 5856-005
5–21
Command Line and Programmatic Access to Runtime
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 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 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
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
5–22
3826 5856-005
Command Line and Programmatic Access to Runtime
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
/S
Description
Displaying the status of an
application
Security Privileges
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Application Operators
•
Application Administrators
/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
/HAM
3826 5856-005
Enabling an Application
Setting or displaying the High
Account Month (HAM)
•
Application Operators
•
Application Administrators
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Application Operators
•
Application Administrators
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Accountants
•
Application Administrators
5–23
Command Line and Programmatic Access to Runtime
Argument
/HUB
/LAM
/LIS
/SMG
/STO
/WHO
Description
Displaying, Enabling, or
Disabling external automatic
entries (HUB)
Setting or displaying the Low
Account Month (LAM)
Listing ispecs in an
application
Sending a short message to
a user
Stopping an Application
Displaying the list of current
users or active stations
Security Privileges
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
HUB Administrators
•
Application Administrators
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Accountants
•
Application Administrators
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Application Administrators
•
Application Operators
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Message Senders
•
Message Broadcasters
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Application Operators
•
Application Administrators
Users should be a member of the Application
Administrators to access this administrative
function.
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
5–24
•
Enabled and Running
•
Disabled and Running
•
Enabled and Stopped
3826 5856-005
Command Line and Programmatic Access to Runtime
•
Disabled and Stopped
Parameters
Argument
/S <SystemName>
Description
Specifies that a valid system name must be passed as a parameter.
Notes:
•
This argument is mandatory.
•
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 Sample
The message "Sample Status: Enabled and Running" appears.
/S <SystemName> /?
Displays the usage of the utility and the utility exits without starting
the process.
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
Argument
/S <SystemName>
3826 5856-005
Description
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.
5–25
Command Line and Programmatic Access to Runtime
Argument
/CLR <UserName/
SessionId>
Description
Specifies that a valid system name must be passed as a parameter.
Notes:
•
This argument is mandatory.
•
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.exe
The 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.
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
Argument
/S <SystemName>
5–26
Description
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.
3826 5856-005
Command Line and Programmatic Access to Runtime
Argument
/LAM
<AccountMonth>
Description
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:
•
This argument is mandatory.
•
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.
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
Argument
/S <SystemName>
3826 5856-005
Description
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.
5–27
Command Line and Programmatic Access to Runtime
Argument
/HAM
<AccountMonth>
Description
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:
•
This argument is mandatory.
•
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 1402
The 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.
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
Argument
Description
/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.
/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:
/MSG <message>
This argument is mandatory.
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 Hello
The confirmation "Sent the message" appears.
/S <SystemName> /
SMG /?
5–28
Displays the command line syntax and its usage for sending a short
message, and the utility exits without starting the process..
3826 5856-005
Command Line and Programmatic Access to Runtime
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
Argument
Description
/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.
/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.
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
Argument
/S <SystemName>
3826 5856-005
Description
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.
5–29
Command Line and Programmatic Access to Runtime
Argument
/WHO
Description
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.
•
This argument is mandatory.
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.
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
Argument
Description
/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.
/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.
Disabling an Application
The syntax of the runtime operations utility for disabling an application is
5–30
3826 5856-005
Command Line and Programmatic Access to Runtime
AdminSystem /S <SystemName> /DIS
If you pass valid parameters to run the utility, the message “System disabled” appears.
Parameters
Argument
Description
/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.
/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.
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
Argument
/S <SystemName>
/ENA
Description
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.
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.
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.
3826 5856-005
5–31
Command Line and Programmatic Access to Runtime
Parameters
Argument
Description
/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.
/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 readonly.
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 /?
5–32
Displays the usage of the utility and the utility exits without
starting the process.
3826 5856-005
Command Line and Programmatic Access to Runtime
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.
Argument
/REP
/DEL
/RUN
/STR
3826 5856-005
Description
Displaying information about
the reports
Deleting Report Recovery
Information
Running or Recovering a
Report
Stopping a Report
Security Privileges
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Report Runners (only able to obtain
information on reports they have
initiated)
•
Report Monitors
•
Report Recoverers
•
Report Recovery Operators
•
Report Recovery Administrators
•
Application Administrators
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Report Runners (can delete the
information of reports they have initiated)
•
Report Recovery Operators
•
Report Recovery Administrators
•
Report Administrators
•
Application Administrators
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Report Runners
•
Report Administrators
•
Application Administrators
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Report Runners (only able to stop reports
they have initiated)
•
Report Operators
•
Report Administrators
•
Application Administrators
5–33
Command Line and Programmatic Access to Runtime
Argument
/TER
/WUP
Description
Terminating an Active Report
Reactivate a report
suspended by a previous
Sleep or CriticalPointLogic
Security Privileges
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Report Runners (only able to stop reports
they have initiated)
•
Report Operators
•
Report Administrators
•
Application Administrators
Users must be a member of one of the
following COM+ roles to access this
administrative function:
•
Application Administrators
•
Report Administrators
•
Report Operators
•
Report Recovery Administrators
•
Report Recovery Operators
•
Report Runners
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
5–34
•
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
Command Line and Programmatic Access to Runtime
Parameters
Argument
Description
/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.
/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.
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
Argument
/S <SystemName>
3826 5856-005
Description
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.
5–35
Command Line and Programmatic Access to Runtime
Argument
/RUN <ReportName>
Description
Specifies the name of a report.
Notes:
•
This argument is mandatory.
•
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
Command Line and Programmatic Access to Runtime
Argument
/PA <param>
Description
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.
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
Argument
Description
/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.
Terminating an Active Report
The syntax of the runtime operations utility for terminating an active report is
3826 5856-005
5–37
Command Line and Programmatic Access to Runtime
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
Argument
Description
/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.
/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
Command Line and Programmatic Access to Runtime
Argument
/REC
<NORECOVERY|RECOVER|
DISCARD>
Description
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.
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
Argument
/S <SystemName>
3826 5856-005
Description
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.
5–39
Command Line and Programmatic Access to Runtime
Argument
/WUP <ReportName>
Description
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.
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
Argument
Description
/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.
/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> /?
5–40
Displays the command line syntax and its usage for deleting
recovery information of a report, and the utility exits without
starting the process.
3826 5856-005
Command Line and Programmatic Access to Runtime
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 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 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
Command Line and Programmatic Access to Runtime
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 properties
EPCReconfigure.exe GETCONFIG <system name> <model class name>
•
DELETECONFIG - To delete the configuration properties
EPCReconfigure.exe DELETECONFIG <system name> <model class name>
•
SETCONFIG - To modify the configuration properties
EPCReconfigure.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
<system name>
Description
Specifies the deployed AB Suite system.
Note:
exist.
An error message appears if the system does not
<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
Command Line and Programmatic Access to Runtime
Configuration Property
<UserId>
Description
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:
table.
<Password>
The user-id is encrypted and stored in the _Config
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.
Programmatic Access to Runtime
This subsection describes the following AB Suite public interfaces that can be
implemented.
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
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.
3826 5856-005
5–43
Command Line and Programmatic Access to Runtime
Members of StatusInfo class
Name
Status
Type
StatusEnum
Description
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.
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
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.
Note: The interface enables you to perform the administration tasks required for
pre-deployed applications.
Required Security Privileges
5–44
3826 5856-005
Command Line and Programmatic Access to Runtime
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.
Syntax
ConfigureLog(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
Name
Type
Description
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
•
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:
3826 5856-005
5–45
Command Line and Programmatic Access to Runtime
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:
•
3.
Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 4.0 Installation
directory>\bin folder)
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 config
IConfigureRuntime config = RuntimeFactory.GetRuntime();
//Construct the ConfigureLogParameter
ConfigureLogParameter 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 values
StatusInfo statusInfo = config.ConfigureLog(parameter,
ModeType.Write);
Console.WriteLine(statusInfo.StatusMessage);
//Invoke configurelog to read the values
statusInfo = config.ConfigureLog(parameter, ModeType.Read);
}
}
if (statusInfo.Status == StatusEnum.Success)
{
//Prints the read values
Console.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
Command Line and Programmatic Access to Runtime
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
Name
Type
Description
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.
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
•
mode: Read or Write mode of the configuration
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:
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:
•
3826 5856-005
Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 4.0 Installation
directory>\bin folder)
5–47
Command Line and Programmatic Access to Runtime
3.
Add the following code to the Class to get and set configure adapter details for
RatlSocket into the Sample application.
namespace SampleConfigSocketAdapter
{
using System;
using Unisys.AgileBusiness.RuntimeAPI;
class Program
{
static void Main(string[] args)
{
//Get the Runtime config
IConfigureRuntime config = RuntimeFactory.GetRuntime();
//Construct the Socket parameter
SocketParameter 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 values
StatusInfo statusInfo = config.ConfigureSocketAdapter(parameter,
ModeType.Write);
Console.WriteLine(statusInfo.StatusMessage);
//Invoke ConfigureSocketAdapter to read the values
statusInfo = config.ConfigureSocketAdapter(parameter, ModeType.Read);
}
}
if (statusInfo.Status == StatusEnum.Success)
{
//Prints the read values
Console.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
{
Console.WriteLine(statusInfo.Status + statusInfo.StatusMessage);
}
4. Build the Class Library.
IConfigureRuntime.ConfigureQueueAdapter Method
This method allows you to configure the RatlQueue/SoapQueue adapter details.
Syntax
ConfigureQueueAdapter(Unisys.AgileBusiness.RuntimeAPI.QueueParameter queueParameter,
Unisys.AgileBusiness.RuntimeAPI.ModeType mode)
Arguments
5–48
3826 5856-005
Command Line and Programmatic Access to Runtime
•
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
Name
•
Type
Description
QueueType
enum QueueType
Queuename: RATL/SOAP
ServerName
string
MSMQ Server machine of the queue adapter
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
mode: Read or Write mode of the configuration
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:
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:
•
3.
Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 4.0 Installation
directory>\bin folder)
Add the following code to the Class to get and set configure adapter details for
RatlQueue into the Sample application.
namespace SampleConfigQueueAdapter
{
using System;
using Unisys.AgileBusiness.RuntimeAPI;
class Program
{
static void Main(string[] args)
{
//Get the Runtime config.
3826 5856-005
5–49
Command Line and Programmatic Access to Runtime
IConfigureRuntime config = RuntimeFactory.GetRuntime();
//Construct the Socket parameter
QueueParameter 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);
Console.WriteLine(statusInfo.StatusMessage);
//Invoke ConfigureQueueAdapter to read the values
statusInfo = config. ConfigureQueueAdapter(parameter, ModeType.Read);
}
}
}
if (statusInfo.Status == StatusEnum.Success)
{
//Prints the read values
Console.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
{
Console.WriteLine(statusInfo.Status + statusInfo.StatusMessage);
}
4. Build the Class Library.
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
Command Line and Programmatic Access to Runtime
“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.
Namespace: Unisys.AgileBusiness.RuntimeAPI
Assembly: Unisys.AgileBusiness.RuntimeAPI (in Unisys.AgileBusiness.RuntimeAPI.dll)
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
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
Note: You must have local administrator privileges to use all the methods.
IDeployPackage.PackageInstall Method
This method allows you to install the generated package.
Syntax
PackageInstall(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.
3826 5856-005
5–51
Command Line and Programmatic Access to Runtime
Members
Name
Type
Description
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
•
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
Method
CompletionStatus()
5–52
Description
Completion status
Parameter
int status
3826 5856-005
Command Line and Programmatic Access to Runtime
Method
Description
Parameter
ProgressMessage()
Receives the progress
message and message code
String message,
Unisys.AgileBusiness.RuntimeAPI.MS
GTYPE MSGTYPE
ReceiveAccept()
Receives the IAccept object
from report.
Unisys.AgileBusiness.RuntimeAPI.IAc
cept pIAccept
String prompt
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.
Method
Description
Parameter
CompletionStatus()
Completion status
int status
ProgressMessage()
Receives the
progress message
and message code
String message,
Unisys.AgileBusiness.RuntimeAPI.MS
GTYPE MSGTYPE
ReceiveAccept()
Receives the IAccept
object from report.
Unisys.AgileBusiness.RuntimeAPI.IAc
cept pIAccept
String prompt
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, MSGTYPE
MSGTYPE)
{
Console.WriteLine(theMsg);
}
protected override void CompletionStatus(int Status)
{
Console.WriteLine("Operation Completed successfully",
Status);
}
protected override void ReceiveAccept(IAccept pIAccept, string
prompt)
3826 5856-005
5–53
Command Line and Programmatic Access to Runtime
{
}
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
Name
Type
Description
CoInitializeSecurity
int
Enables setting different security parameters
apart from the default security.
SetSecurity
int
Set the default security required for deploying.
Using the IDeployPackage Interface for the PackageInstall() method
Perform the following steps to use the interface through C# example:
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:
•
3.
Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 4.0 Installation
directory>\bin folder)
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
{
using
using
using
SampleDeployer
System;
Unisys.AgileBusiness.RuntimeAPI;
System.Security;
class Program
{
static void Main(string[] args)
5–54
3826 5856-005
Command Line and Programmatic Access to Runtime
{
//Get the deployer
IDeployPackage deployer = RuntimeFactory.GetDeployer();
//GetDeployer sets the security
SecureString securePwd = new SecureString();
string pass = @"Password";
foreach (char c in pass)
securePwd.AppendChar(c);
//Construct the PackageInstallParameter
PackageInstallParameter 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);
4. Build the Class Library.
IDeployPackage.ClonePackage Method
This method allows you to create a deployment package for the new instance.
Syntax
ClonePackage(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
Name
BuilderGeneratedPackage
Type
string
Description
Absolute path, relative file path, or network path to
the builder generated package; .msi or .cab.
This member is mandatory.
For example:
3826 5856-005
•
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"
5–55
Command Line and Programmatic Access to Runtime
Name
OverWrite
Type
bool
Description
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"
PackageInstallationDirecto
ry
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"
•
callBack: RuntimeCallBack object
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.
5–56
3826 5856-005
Command Line and Programmatic Access to Runtime
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:
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:
•
3.
Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 4.0 Installation
directory>\bin folder)
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
{
using System;
using Unisys.AgileBusiness.RuntimeAPI;
class Program
{
static void Main(string[] args)
{
//Get the deployer
IDeployPackage deployer = RuntimeFactory.GetDeployer();
//Construct the ClonePackageParameter
ClonePackageParameter 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 message
CallBackHandler callBack = new CallBackHandler();
}
//Execute ClonePackage
StatusInfo statusInfo = deployer.ClonePackage(param, callBack);
}
}
4. Build the Class Library.
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.
Syntax
CreatePartialPackage(Unisys.AgileBusiness.RuntimeAPI.PartialPackageParameter
parameter, Unisys.AgileBusiness.RuntimeAPI.RuntimeCallBack callBack)
3826 5856-005
5–57
Command Line and Programmatic Access to Runtime
Arguments
•
parameter: PartialPackageParameter object
The object consists of partial package input.
The PartialPackageParameter class exposes the following list of members.
Members
Name
BuilderGeneratedPackage
Type
string
Description
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\SampleReports.msi"
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"
DpmGeneratedPackage
string
Absolute path, relative file path, or network path
to the DPM generated instance package
This member is mandatory.
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"
•
callBack: RuntimeCallBack object
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.
Using the IDeployPackage Interface for the CreatePartialPackage()
method
5–58
3826 5856-005
Command Line and Programmatic Access to Runtime
Perform the following steps to use the interface for creating a partial MSI package of
the existing instance:
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:
•
3.
Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 4.0 Installation
directory>\bin folder)
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.
namespace SampleDPM
{
using System;
using Unisys.AgileBusiness.RuntimeAPI;
class Program
{
static void Main(string[] args)
{
//Get the deployer
IDeployPackage deployer = RuntimeFactory.GetDeployer();
//Construct the PartialPackageParameter
PartialPackageParameter param = new PartialPackageParameter()
{
BuilderGeneratedPackage = @"C:\TEMP\stagingarea\SampleReports.msi",
DpmGeneratedPackage = @"C:\ClonedPackages\SampleClone.msi",
TargetPackagePath = @"C:\ClonedPackages",
InstanceName = @"SAMPLECloneReports",
OverWrite = true
};
//Get the callback object for progress message
CallBackHandler callBack = new CallBackHandler();
}
}
//Execute CreatePartialPackage
StatusInfo statusInfo = deployer.CreatePartialPackage(param, callBack);
}
4. Build the Class Library.
IDeployPackage.UpdatePackage Method
This method allows you to update the deployment package of the existing instance.
Syntax
UpdatePackage(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
Command Line and Programmatic Access to Runtime
Members
Name
BuilderGeneratedPackage
Type
string
Description
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"
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
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
This member is mandatory.
For example:
DpmGeneratedPackage =
@"C:\ClonedPackages\SampleClone.msi"
PackageInstallationDirectory
string
Absolute path to builder generated instance
package
For example:
PackageInstallationDirectory =
@"C:\ABSuite\Systems\SampleClone"
•
callBack: RuntimeCallBack object
Refer to the callback argument of the PackageInstall() method for further
information.
Return Value
5–60
3826 5856-005
Command Line and Programmatic Access to Runtime
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
Using the IDeployPackage Interface for the UpdatePackage () method
Perform the following steps to use the interface for updating the deployment package
through C# example:
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:
•
3.
Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 4.0 Installation
directory>\bin folder)
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.
namespace SampleDPM
{
using System;
using Unisys.AgileBusiness.RuntimeAPI;
class Program
{
static void Main(string[] args)
{
//Get the deployer
IDeployPackage deployer = RuntimeFactory.GetDeployer();
//Construct the UpdatePackageParameter
UpdatePackageParameter 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
};
//Get the callback object for progress message
CallBackHandler callBack = new CallBackHandler();
//Execute UpdatePackage
StatusInfo statusInfo = deployer.UpdatePackage(param, callBack);
}
}
}
4. Build the Class Library.
Definition of the IDeployPackage Interface
Following is the definition of the IDeployPackage interface.
namespace Unisys.AgileBusiness.RuntimeAPI
{
3826 5856-005
5–61
Command Line and Programmatic Access to Runtime
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.
Namespace: Unisys.AgileBusiness.RuntimeAPI
Assembly: Unisys.AgileBusiness.RuntimeAPI (in Unisys.AgileBusiness.RuntimeAPI.dll)
Syntax
You can create the IAdministerSystem object by using the
RuntimeFactory.GetSystem()method.
IAdministerSystem RuntimeSystem = Unisys.AgileBusiness.RuntimeAPI.RuntimeFactory.
GetSystem(string systemName);
The IAdministerSystem interface exposes the following methods. By default, all the
methods can be accessed by a local administrator. Non-administrative users can use
these methods only if they have the required security privileges. The security of the
methods is controlled by using the COM+ roles. Please refer to the following table for
the specific security privileges.
Methods
Method
ClearSession()
5–62
Description
Clears an existing orphan
session based on a given
station name or session id
Security Privileges
Users should be a member of the
Application Administrators.
3826 5856-005
Command Line and Programmatic Access to Runtime
Method
DeleteReportRecovery()
DisableHub()
DisableSystem()
EnableHub()
EnableSystem()
GetAccountMonth()
GetHubStatus()
3826 5856-005
Description
Deletes recovery
information of a report.
Disables HUB for an
application.
Disables an application.
Enables HUB for an
application.
Enables an application
Displays both the High and
Low Account Months of an
application
Returns the hub status
Security Privileges
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Report Runners (can delete the
information of reports they
have initiated)
•
Report Recovery Operators
•
Report Recovery
Administrators
•
Report Administrators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
HUB Administrators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Application Operators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
HUB Administrators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Application Operators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Accountants
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
HUB Monitors
•
HUB Administrators
•
Application Administrators
5–63
Command Line and Programmatic Access to Runtime
Method
GetSystemStatus()
ListIspecs()
ListRunningReports()
ListUsers()
Description
Displays the status of a
system
Lists unique ispecs in an
application
Displays information about
the active reports and
reports awaiting recovery
in an application.
Displays a list of stations
connected to a runtime
system.
Security Privileges
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Application Operators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Application Operators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Report Runners (only able to
obtain information on reports
they have initiated)
•
Report Monitors
•
Report Recoverers
•
Report Recovery Operators
•
Report Recovery
Administrators
•
Report Administrators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
Application Administrators
RunReport()
SendAMessage()
SetAccountMonth()
5–64
Initiate a report or recover
a report with recovery
information available.
Sends a short message to
other users logged onto an
application.
Sets both the High and Low
Account Months of an
application.
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Report Runners
•
Report Administrators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access this method:
•
Message Senders
•
Message Broadcasters
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Accountants
•
Application Administrators
3826 5856-005
Command Line and Programmatic Access to Runtime
Method
StopReport()
StopSystem()
TerminateReport()
WakeUpReport()
Description
Terminates or stops a
running report.
Stops a runtime system.
Terminates an active report
immediately.
Wakes up a report
Security Privileges
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Report Runners (only able to
stop reports they have
initiated)
•
Report Operators
•
Report Administrators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Application Operators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Report Runners (only able to
stop reports they have
initiated)
•
Report Operators
•
Report Administrators
•
Application Administrators
Users must be a member of one of
the following COM+ roles in order
to access the method:
•
Application Administrators
•
Report Administrators
•
Report Operators
•
Report Recovery
Administrators
•
Report Recovery Operators
•
Report Runners
IAdministerSystem.ClearSession Method
This method allows you to clear an existing orphan session from the Runtime
application based on a given station name or session id.
Syntax
ClearSession(string userOrSession)
Arguments
userOrSession: string
3826 5856-005
5–65
Command Line and Programmatic Access to Runtime
User name or Session Id of a known session, which needs to be cleared.
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.GetAccountMonth Method
This method allows you to display both the High and Low Account months.
Syntax
GetAccountMonth(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
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.GetSystemStatus Method
This method allows you to display the status of a system whether Enabled, Disabled,
Running, or Stopped.
Syntax
GetSystemStatus(out Unisys.AgileBusiness.RuntimeAPI.SystemStatus systemStatus)
Arguments
systemStatus: SystemStatus object
The object describes if the runtime system status is Stopped, Enabled, Disabled, or
Running
The SystemStatus class exposes the following members.
Members of SystemStatus class
Name
5–66
Description
Enabled
Enable an application
Disabled
Disable an application
Stopped
Stop an application
3826 5856-005
Command Line and Programmatic Access to Runtime
Name
Description
Running
Execute an application
Unknown
No known status that are
specified above
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.EnableSystem Method
This method allows you to enable an application.
Syntax
EnableSystem()
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.DisableSystem Method
This method allows you to disable an application.
Syntax
DisableSystem()
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.StopSystem Method
This method allows you to stop an application and optionally cause termination of an
application when it is idle.
Syntax
StopSystem([bool disable = false])
Arguments
disable: By default, the value is false. This argument is optional.
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
3826 5856-005
5–67
Command Line and Programmatic Access to Runtime
IAdministerSystem.GetHubStatus Method
This method allows you to get the status of an external automatic entry (HUB)
transaction of an application.
Syntax
GetHubStatus(out bool isEnabled)
Arguments
isEnabled: bool
isEnabled is set to true, to enable HUB
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.EnableHub Method
This method allows you to enable HUB for an application.
Syntax
EnableHub()
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.DisableHub Method
This method allows you to disable HUB for an application.
Syntax
DisableHub()
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.ListIspecs Method
This method lists the unique ispecs in an application.
Syntax
ListIspecs(out System.Collections.Generic.IList<string> ispecsList)
5–68
3826 5856-005
Command Line and Programmatic Access to Runtime
Arguments
ispecsList: System.Collections.Generic.IList<string>
This argument provides the list of ispecs in a system.
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.ListUsers Method
This method displays a list of stations connected to a runtime system. The information
includes a list of users logged into the system.
Syntax
ListUsers(out System.Collections.Generic.IList<string> usersList)
Arguments
usersList: System.Collections.Generic.IList<string>
This argument provides a list of connected users.
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.SendAMessage Method
This method sends a short message to other users logged onto an application.
Syntax
SendAMessage(string station, string message)
Arguments
•
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
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
3826 5856-005
5–69
Command Line and Programmatic Access to Runtime
IAdministerSystem.SetAccountMonth Method
This method sets a High Account Month (HAM) or Low Account Month (LAM) value for
a running application.
Syntax
SetAccountMonth([int highAccount = 0], [int lowAccount = 0])
Arguments
•
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
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
Using the IAdministerSystem Interface for the Application Administration
Operations
Perform the following steps to use the interface for the application administration
operations through C# example:
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:
•
3.
Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 4.0 Installation
directory>\bin folder)
Add the following code.
namespace SampleSystem
{
using System;
using Unisys.AgileBusiness.RuntimeAPI;
class Program
{
static void Main(string[] args)
{
//Get the RuntimeSystem
IAdministerSystem sample = RuntimeFactory.GetSystem("SAMPLE");
//Get the System status
SystemStatus systemStatus;
StatusInfo status = sample.GetSystemStatus(out systemStatus);
if (status.Status == StatusEnum.Success)
{
Console.Write(string.Format("Status : "));
switch (systemStatus)
{
5–70
3826 5856-005
Command Line and Programmatic Access to Runtime
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 system
status = sample.EnableSystem();
//Disable system
status = sample.DisableSystem();
//Stop system
status = sample.StopSystem();
//Get the status of the System HUB
bool isHubEnabled;
status = sample.GetHubStatus(out isHubEnabled);
//Disable Hub of the system
status = sample.DisableHub();
//Enable Hub of the System
status = sample.EnableHub();
//List users
IList<string> usersList = null;
status = sample.ListUsers(out usersList);
if (status.Status == StatusEnum.Success)
{
if (usersList.Count > 0)
{
foreach (string user in usersList)
Console.WriteLine(user);
}
else
{
Console.WriteLine("No users are logged in");
}
}
}
}
}
4. Build the Class Library.
3826 5856-005
5–71
Command Line and Programmatic Access to Runtime
IAdministerSystem.ListRunningReports Method
This method displays information about the active reports or reports awaiting recovery
in an application.
Syntax
ListRunningReports(out System.Collections.Generic.IList<ReportInformation>
reportsList)
Arguments
reportsList: System.Collections.Generic.IList<ReportInformation>
This argument provides a list of reports of type ReportInformation.
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.RunReport Method
This method allows you to initiate or recover a report with recovery information
available.
Syntax
RunReport(string reportName, Unisys.AgileBusiness.RuntimeAPI.RuntimeCallBack
callBack, [string recoveryKey = ""], [bool waitForReportCompletion = true], [string
parameter = ""], [string device = "LP"], [string language = ""], [bool trace = false])
Arguments
•
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.
•
5–72
parameter: string
3826 5856-005
Command Line and Programmatic Access to Runtime
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
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.DeleteReportRecovery Method
This method allows you to delete recovery information for a report.
Syntax
DeleteReportRecovery(int sessionID)
Arguments
sessionID: int
The Session ID or recovery key of a report
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.StopReport Method
This method allows you to terminate running reports.
3826 5856-005
5–73
Command Line and Programmatic Access to Runtime
Syntax
StopReport(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
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
processId: string
Specifies the process ID of a report. This argument is optional. By default, this
argument is set to “Null”.
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.TerminateReport Method
This method allows you to terminate an active report immediately.
Syntax
TerminateReport(string reportName, Unisys.AgileBusiness.RuntimeAPI.StopType stopType,
[string processId = null])
Arguments
•
reportName: string
Name of the report
•
5–74
stopType: StopType object
3826 5856-005
Command Line and Programmatic Access to Runtime
The object determines how any transaction in progress is handled. The stopType
class exposes the following members.
Members of stopType class
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.
•
processId: string
Specifies the process ID of a report.
This argument is optional. By default, this argument is set to “Null”.
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
IAdministerSystem.WakeUpReport Method
This method allows you to wake up a report.
Syntax
WakeUpReport(string reportName, [string wakeUpParameters = ""])
Arguments
•
reportName: string
Name of the report
•
wakeUpParameters: string
Specifies a text to be passed to the report. This argument is optional.
Return Value
If this method succeeds, it returns the StatusInfo object with success; else, it returns
an error status.
Using the IAdministerSystem Interface for the Report Administration
Operations
Perform the following steps to use the interface for the report administration
commands through C# example:
1.
Create a new C# Class Library in Microsoft Visual Studio.
3826 5856-005
5–75
Command Line and Programmatic Access to Runtime
2.
Add a reference to the following assembly that you need when calling from the
Class Library:
•
3.
Unisys.AgileBusiness.RuntimeAPI.dll (from <AB Suite 4.0 Installation
directory>\bin folder)
Add the following code.
namespace SampleReport
{
using System;
using Unisys.AgileBusiness.RuntimeAPI;
class Program
{
static void Main(string[] args)
{
//Report operations
//Get the RuntimeSystem, GetSystem sets the security
IAdministerSystem sample = RuntimeFactory.GetSystem("SAMPLE");
//Get the callback object for report callback
CallBackHandler callBack = new CallBackHandler();
//Execute report
sample.RunReport("CUSTLIST", callBack);
//List Running Reports
IList<ReportInformation> reportsList = null;
status = sample.ListRunningReports(out reportsList);
STATUS");
if (status.Status == StatusEnum.Success)
{
if (reportsList.Count > 0)
{
Console.WriteLine("USER NAME
PID
SID
REPORT
foreach (ReportInformation report in reportsList)
{
Console.WriteLine(string.Format("{0,-26}{1,-6}{2,-6}{3,17}{4,-20}",
report.UserName,
report.ProcessId,
report.SessionId,
report.ReportName, report.Status));
}
}
else
{
Console.WriteLine("No active/waiting recovery reports are
available");
}
}
}
}
}
4. Build the Class Library.
Definition of the IAdministerSystem Interface
Following is the definition of the IAdministerSystem interface.
namespace Unisys.AgileBusiness.RuntimeAPI
{
public interface IAdministerSystem
{
5–76
3826 5856-005
Command Line and Programmatic Access to Runtime
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 Operations
All 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
Command Line and Programmatic Access to Runtime
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.
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
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.
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
Runtime Programming Interfaces
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
Runtime Programming Interfaces
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
Runtime Programming Interfaces
}
//
// 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
Runtime Programming Interfaces
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_only
class 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
Runtime Programming Interfaces
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
Runtime Programming Interfaces
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
Runtime Programming Interfaces
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.
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
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.
3826 5856-005
6–9
Runtime Programming Interfaces
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
Runtime Programming Interfaces
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 zerobased, 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
Runtime Programming Interfaces
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
Runtime Programming Interfaces
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
Runtime Programming Interfaces
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 system
Try
{
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
Runtime Programming Interfaces
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
Runtime Programming Interfaces
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
Runtime Programming Interfaces
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_namespace
using namespace std;
Define main method
3826 5856-005
6–17
Runtime Programming Interfaces
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(
pInput->SetValue(
pInput->SetValue(
pInput->SetValue(
L"_UserMAINT", L"ADD");
L"AREA", L"Asia");
L"NAM", L"John Smith");
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
6–18
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,
3826 5856-005
Runtime Programming Interfaces
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:
5.
•
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)
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
Runtime Programming Interfaces
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
Runtime Programming Interfaces
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
Runtime Programming Interfaces
•
5.
<segment>.dll (from your deployed application folder)
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 nonadministrative 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
Runtime Programming Interfaces
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 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*
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]
[in]
[in]
[in]
[in]
[in]
[in,out]
[in,out]
[in,out]
[in,out]
[in,out]
[in,out]
3826 5856-005
BSTR
BSTR
DECIMAL
DECIMAL
DATE
VARIANT_BOOL
BSTR *
BSTR *
DECIMAL *
DECIMAL *
DATE *
VARIANT_BOOL *
_sg_StringIn,
_sg_WideStringIn,
_sg_NumberIn,
_sg_SignedNumberIn,
_sg_DateIn,
_sg_BooleanIn,
_sg_StringInOut,
_sg_WideStringInOut,
_sg_NumberInOut,
_sg_SignedNumberInOut,
_sg_DateInOut,
_sg_BooleanInOut);
6–23
Runtime Programming Interfaces
6–24
3826 5856-005
Section 7
Using 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.
The following topics are covered in this section:
7–2
•
Preparing Projects in Developer
•
Communicating with Other Hosts
•
Sending External Automatic Entries
•
How an External Automatic Entry Works
•
Security Issues with External Automatic Entries
3826 5856-005
Using Protocol Adapters
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
Using Protocol Adapters
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:
7–4
1.
Start Administration Tool.
2.
From the Console Root, select Component Services > Computers > My
Computer > Distributed Transaction Coordinator.
3826 5856-005
Using Protocol Adapters
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
Using Protocol Adapters
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.
Caution
The 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
Using Protocol Adapters
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 Protocol Adapters
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.
4. Click Apply and OK.
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:
7–8
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.
3826 5856-005
Using Protocol Adapters
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
Using Protocol Adapters
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:
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.
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:
7–10
3826 5856-005
Using Protocol Adapters
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.
The following syntax is used to invoke the interfaces:
NOF.exe --host[<hostname>] --view[<viewname>] [<input>]
Note: --host can be replaced with –h and --view can be replaced with –v.
Where:
Parameter
Description
<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 NOF.exe. It is possible to pipe a file
containing NOF data
3826 5856-005
7–11
Using Protocol Adapters
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
CUST
CUST
CUST
CUST
BYE
T00002524AUG999908FIR
T00002624AUG999908NEX
T00002724AUG999908INQ
T00002824AUG999908NEX
T00002924AUG999908LAS
2
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 2
Delivery 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
Using Protocol Adapters
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:
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.
Screen data for ispecs must be in the following form:
number date month [ maint ] data
3826 5856-005
7–13
Using Protocol Adapters
Details of these values are given in the following table:
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.
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
7–14
3826 5856-005
Using Protocol Adapters
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
C_DA3NOF Order=3, copied 3 times
DA 4NOF Order=4
C_DA5NOF Order=5, copied 3 times
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
Using Protocol Adapters
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:
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
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.
7–16
3826 5856-005
Using Protocol Adapters
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
S
3826 5856-005
Meaning
Start (first) buffer
7–17
Using Protocol Adapters
Sequence
Meaning
E
End (first) buffer
O
Only buffer
0
Middle buffer
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).
7–18
3826 5856-005
Using Protocol Adapters
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
Using Protocol Adapters
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:
Parameter
Description
<viewname>
The view with which you want to connect.
<input>
Command line input that is read by GLI.exe. It is possible to pipe a file
containing GLI data.
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:
Parameter
Description
--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
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:
7–20
3826 5856-005
Using Protocol Adapters
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
Using Protocol Adapters
Header
Attribute
ERROR.MSG;
Abbr.
ERM;
Description
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).
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.
7–22
3826 5856-005
Using Protocol Adapters
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:
Properties
Abbreviation
DATA;
DA;
LENGTH;
LE;
EDIT;
ED;
DECIMAL;
DE;
SETUP.DATA;
SD;
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.
3826 5856-005
7–23
Using Protocol Adapters
•
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:
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
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.
7–24
3826 5856-005
Using Protocol Adapters
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:
Digit
Replace with...
0
}
1
J
2
K
3
L
4
M
5
N
6
O
7
P
8
Q
9
R
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
3826 5856-005
7–25
Using Protocol Adapters
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
Using Protocol Adapters
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
Using Protocol Adapters
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
Caution
Offline Input has largely been superseded by the Non-Formatted Input/
Output facility (NOF). Consider developing a sending NOF program for your
data loading needs.
The following topics are covered in this section:
•
Formatting for Offline Input
•
Executing the Offline Program
•
Offline Recovery
Formatting for Offline Input
Format data according to the following rules:
7–28
3826 5856-005
Using Protocol Adapters
•
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.
The following syntax is used to invoke the interfaces:
OFF.exe --host[<hostname>] --view[<viewname>] [<input>]
Note: --host can be replaced with –h and --view can be replaced with –v.
Where:
Parameter
Descrition
<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 OFF.exe. It is possible to pipe a file
containing OFF data
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.
3826 5856-005
7–29
Using Protocol Adapters
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 8
Database 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.
The following topic is covered in this section:
•
_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 9
Report Operations
The following topics are covered in this section:
•
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 Reports
Reports 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:
9–6
•
<report> is the name of the report to be run.
•
Include RECOVERY to restart a report. <pid> is the process ID of the report.
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:
•
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.
runrep <report> > <your_directory>\Report_log
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:
9–8
•
0 – Normal report completion
•
100 – Failed report
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.
The following topic is covered in this section:
•
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:
Glb.Device
Glb.Stn
Glb.Title
Default
LP
Description
As Developer setting
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.
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:
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.
Glb.Device
Glb.Stn
Glb.Title
Default
LP
Description
stdout
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.
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).
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.
Glb.Device
(at runtime)
LP, DP or
Default
Glb.Stn
ALIAS key to
define Depcon
Printer Name
Glb.Title
n/a
Destination
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\
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.
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”.
The following topics are covered in this section:
9–16
•
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
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.
2.
•
Package Prefix: com.unisys
•
CE Application Name: Sample
•
CE bundle folder name: PClient
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.
•
7.
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.
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.
•
9–20
jh.jar
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
3.
•
PresentationType: Graphical & Fixed
•
MemberVisibility and Visibility: Public
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 command
DoWhen (SWSYS <> GLB.SPACES)
SwitchTo SWSYS
EndExit
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.
9–24
•
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
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.
The following topic is covered in this section:
•
Defining Printers
•
Assigning Report Destinations
•
Printing Special Attributes
•
Formatting CODES File Records
•
Example of Defining an Output Control Code
Defining Printers
The following topic is covered in this section:
•
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:
•
9–28
<server> specifies the name or IP address of the computer to which the printer
is attached.
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:
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.
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
printer2
9–30
DIABLO630
PROPRINTER
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 e
svt12100021B5B376Dbldcreverse
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.
•
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.
AP9215000PRINTER
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:
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
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.
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 nonqualified 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.
The following topic is covered in this section:
•
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
9–34
bldcbright
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 casesensitive. 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:
Device Type
Default From Depth
LP
60 lines
TP
66 lines
VD (not IBM 3270)
48 lines
spaces
60 lines
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 Reports
By using the following option from the Administration tool, you can delete all the
reports that are no longer used in the application.
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
The following topics are covered in this section:
•
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:
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.
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
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’
This SQL command is equivalent to the logic command:
Determine From CUST. CUSTINV ( "JONES" )
In the SQL command:
•
10–4
The Data Item name used is custname.
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.
This SQL command is equivalent to the logic command:
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
B
AB Suite System Deployment Utility, 5–10
access restriction to views, 2–15
accessing
reports, 9–19
adding
database, 2–8
database server registration, 2–6
runtime server, 2–6
views, 2–13
administration commands, 3–1
application related, 3–1
DEL, 3–12
HAM, 3–2
HUB, 3–6
HUB-, 3–8
HUB+, 3–7
LAM, 3–3
LIS, 3–5
REP, 3–9
report related, 3–9
RUN, 3–10
SLA, 3–4
SMG, 3–4
STO, 3–6
STR, 3–12
TER, 3–13
administration security, 2–17
Administration Tool, 2–1
navigation tree, 2–2
anonymous user for views, 2–15
APIs
Runtime, 6–1
Application Administration Commands, 5–23
applications
configuration options, 2–18
deleting, 2–27
disabling, 2–26
enabling, 2–26
stopping, 2–26, 3–6
asynchronous reports, 9–1, 9–5, 9–6, 9–8,
9–18
built-in attributes and reports, 9–4
3826 5856-005
C
calling segment methods, 6–20
COM+ interface
GenericClass, 6–9
segment, 6–1
COM+ properties
application related, 3–1
DeleteReportRecovery, 3–12
GetRecoverableReports, 3–9
GetRunningReports, 3–9
HighAccountMonth, 3–2
IsHubEnabled, 3–7, 3–8
ListIspecs, 3–5
LowAccountMonth, 3–3
RecoverReport, 3–10
report related, 3–9
RunReport, 3–10
SendAMessage, 3–4
SetLanguage, 3–4
StopReport, 3–12
StopSystem, 3–6
COM+properties, 3–1
application related, 3–1
GetHubStatus, 3–6
Command Line Utilities, 5–1
command prompt
recovering reports initiated from, 9–14
runnig reports from, 9–6
running reports from, 9–7
configuration options, 2–18
customize, 2–18
HUB, 2–21
multilanguage, 2–21
Configure Log Files Utility, 5–2
Configure Protocol Adapters Utility, 5–5
configuring
a system, 2–18
protocol adapters, 2–12
Index–1
Index
views, 2–14
connect method, 6–1
CreateInstance method, 6–2
creating
a new database, 2–9
reports, 9–1
views, 2–13
CriticalPoint logic command, 9–4
D
database
adding, 2–8, 2–9, 2–10
creating new, 2–9
deleting, 2–11
detaching, 2–11
preparing, 2–10
removing, 2–10, 2–11
database server registration
adding, 2–6
removing, 2–7
database structure, 8–1
events, 8–3
profiles, 8–3
tables, 8–1, 8–2
defining a ROC alias, 9–17
defining report printers, 9–28
deleting
a database, 2–11
a system, 2–27
report recovery information, 3–12
DEPCON reports, 9–3, 9–13
deployed applications, 2–16
Deployment Package Manager Utility, 5–14
detaching a database, 2–11
direct reports, 9–3, 9–12
disabling a system, 2–26
Disconnect method, 6–2
E
enabling a system, 2–26
External Automatic Entries
disabling, 2–21, 3–8
enabling, 2–21, 3–7
immediate commit, 7–7
limitations, 7–3
overview, 7–2
security issues, 7–7
Index–2
sending, 7–5
series of, 7–7
status, 2–21, 3–6
TCP/IP ports, 7–4
two-phase commit, 7–7
F
field names
GenericClass, 6–10
FormDepth
override, 9–36
G
Generalized Interface (See GLI), 7–19
GenericClass COM+ interface, 6–9
GetArrayValue method, 6–11
GetMessage method, 6–11
GetNumMessages method, 6–11
GetValue method, 6–11
Glb.ASCPrt, 9–4
Glb.Destination, 7–9
Glb.Device, 9–4
Glb.Priv, 7–9, 7–28, 9–4
Glb.Source, 7–28
Glb.Status, 7–9
Glb.Stn, 7–28, 9–4
Glb.Task, 9–4
Glb.Work, 7–28
GLI
data records, 7–19
definition status, 7–19
DESTINATION attribute, 7–19
ERROR.MSG attribute, 7–19
finish record, 7–19
formatted data requirements, 7–19
header record, 7–19
input records, 7–19
Ispec record format, 7–19
LOG attribute, 7–19
ORIGIN attribute, 7–19
output records, 7–19
overview, 7–19
recovery, 7–19
REQD.ACK attribute, 7–19
running, 7–19
SOURCE attribute, 7–19
transaction status, 7–19
3826 5856-005
Index
unformatted data records, 7–19
unformatted data requirements, 7–19
GLI.EXE, 7–19
GLI.SETUP.DATA attribute, 7–19
L
header record GLI, 7–19
High account month
administration command, 3–2
Administration tool, 2–18
COM+ property, 3–2
HUB
configuration, 2–21
disabling, 2–21, 3–8
enabling, 2–21, 3–7
HUB(see External Automatic Entries), 7–2
labels.costomizing for RATL, 2–14
language
administration command, 3–4
Administration tool, 2–21
COM+ property, 3–4
listing ispecs
administration command, 3–5
COM+ property, 3–5
listing reports
administration command, 3–9
COM+ properties, 3–9
login labels.customizing for RATL, 2–14
Low account month
administration command, 3–3
Administration tool, 2–18
COM+ property, 3–3
I
M
IConfigureRuntime Interface, 5–44
IIspecCycle interface, 6–15
immediate commit HUB, 7–7
initiating ROC, 9–17
interface
GenericClass COM+, 6–9
IIspecCycle, 6–15
ISegmentCycle, 6–9
segment COM+, 6–1
invoking NOF, 7–10
ISegmentCycle interface, 6–9
ispec, 1–1
ispec logic
accessing report from, 9–18
running reports from, 9–6
ispec messages
processing, 6–16
ispecs
data for GLI, 7–19
finish record data for GLI, 7–19
formatted data requirements for GLI, 7–19
listing, 3–5
unformatted data records for GLI, 7–19
unformatted data requirements for GLI,
7–19
managing
applications, 2–16
expired reports, 9–18
method, 1–1
Connect, 6–1
CreateInstance, 6–2
Disconnect, 6–2
GetArrayValue, 6–11
GetMessage, 6–11
GetNumMessages, 6–11
GetValue, 6–11
ProcessMsg, 6–3
SetArrayValue, 6–11
SetValue, 6–10
Microsoft Management Console, 2–37
migrating
database, 11–1
LANGUAGE, 11–6
monitoring performance, 2–37
MOVE.AUTO command, 7–5
H
3826 5856-005
N
NOF
format for sending program, 7–10
input data, 7–10
invoking, 7–11
Overview, 7–10
Index–3
Index
Non Formatted Input/Output (See NOF), 7–10
O
OFF.EXE, 7–28
running, 7–28
Offline Input
client program, 7–28
executing program, 7–28
formatting for, 7–28
how it works, 7–28
recovery, 7–28
output locations for reports, 9–9, 9–10, 9–12,
9–13
P
Page Depth
override, 9–36
passing parameters to reports, 9–8
performance monitoring, 2–37
preparing a database, 2–10
printers, 9–28
TCP for formatted text, 9–29
TCP for text only, 9–28
Windows (standard), 9–28
printing
reports, 9–27
processing ispec messages, 6–16
ProcessMSG method, 6–3
Programmatic Access to Runtime, 5–43
programming interfaces
Runtime, 6–1
protocol adapter, 1–1, 7–1
protocol adapters
configuring, 2–12
GLI, 7–19
HUB, 7–2
NOF, 7–10
OFF, 7–19
RATL, 7–2
SOAP, 7–1
USER, 7–8
views, 2–13, 7–30
R
RATL, 7–2
Index–4
over MSMQ, 7–2
over TCP/IP, 7–2
RATL login labels
customizing, 2–14
reconfiguing external persistent class utility,
5–41
Reconfigure External Persistent Class Utility,
5–41
recovering
GLI, 7–19
Offline Input, 7–28
reports, 2–37, 3–10, 9–13, 9–14, 9–15
removing
a database, 2–10
a server, 2–6
database server registration, 2–7
report
output locations, 9–13
Report Administration Commands, 5–33
Report Output Control (See ROC), 9–15
reports, 1–1, 9–1
accessing from ASP.NET Web Forms, 9–21
accessing from ispec logic, 9–18
accessing from Presentation Client, 9–19
accessing from VB.NET Winforms, 9–25
asynchronous, 9–1, 9–5, 9–6, 9–8, 9–18
built-in attributes, 9–4
creating, 9–1
CriticalPoint command, 9–4
deleting recovery information, 2–35, 3–12
DEPCON, 9–3, 9–13
direct, 9–3, 9–12
enabling recovery, 9–4
listing, 3–9
output locations, 9–9, 9–10, 9–12
passing parameters to, 9–8
printing, 9–27
recovering, 2–37, 3–10, 9–13, 9–14, 9–15
recovering parameter data, 9–8
redirecting, 9–7
replying to input request, 9–7
Report Session Manager, 9–5
running, 2–35, 9–5, 9–6, 9–8
standard, 9–2, 9–10
stopping, 2–35, 3–12
synchronous, 9–1, 9–5
terminating active, 3–13
terminating running, 2–35, 3–12
using returned values, 9–8
viewing properties, 2–36
return values for reports, 9–8
ROC, 9–15
3826 5856-005
Index
ASP.NET Webforms, 9–21
defining alias, 9–17
expired reports, 9–18
initiating, 9–17
logic command, 9–18
running
GLI program, 7–19
Offline Program, 7–28
reports, 2–35, 3–10, 9–5, 9–6, 9–7, 9–8
Runtime Operations Utility, 5–22
Runtime overview, 1–1, 4–8
S
scale-out, 2–12
security
administration, 2–17
External Automatic Entries, 7–7
views, 2–15
segment COM+ interface, 6–1
segment method
interface, 6–23
segment methods
calling, 6–20
sending a message
administration command, 3–4
COM+ property, 3–4
sending external Automatic Entries, 7–5
server
adding, 2–6
servers
removing, 2–6
scale-out, 2–12
SetArrayValue method, 6–11
settings
Source Database, 11–2
SetValue method, 6–10
SOAP, 7–1
over HTTP, 7–1
over MSMQ, 7–1
SQL Views
Attributes, 10–3
Events, 10–3
Keyed Classes, 10–2
Non-Keyed Classes, 10–3
Profiles, 10–3
standard reports, 9–2, 9–10
station data file, 2–4
stopping
reports, 2–35, 3–12
3826 5856-005
systems, 2–26, 3–6
synchronous reports, 9–1, 9–5
System Monitor, 2–37
systems
configuration options, 2–18
deleting, 2–27
disabling, 2–26
enabling, 2–26
reports, 2–35
stopping, 2–26, 3–6
T
TCP/IP ports, 7–4
terminating
active Report, 3–13
running Reports, 2–35, 3–12
Troubleshooting Runtime API Operations,
5–77
two-phase commit
External Automatic Entries, 7–7
U
USER (See User Interface), 7–8
User Interface
how it works, 7–8
sample program, 7–9
sending a transaction, 7–9
USERRTN.CBL, 7–9
Using SQL Views, 10–1
About SQL Views, 10–1
Generating and Maintaining SQL Views,
10–1
Limits and Performance Issues with SQL
Views, 10–5
Using SQL Views, 10–3
What SQL Views are Created, 10–2
utility, 11–6
V
views, 7–30
anonymous user, 2–15
creating, 2–13
defining access, 2–15
general configuration, 2–14
SQL server, 8–3
Index–5
Index
W
wizard, 11–1
wizards, 2–1, 3–1, 6–1, 7–1, 10–1, 11–1
Index–6
3826 5856-005
Unisys
*38265872-003*
3826 5856-005
Download PDF
Similar pages