Managing Analytic Servers

This chapter provides an overview of the analytic server framework and batch processing of analytic instances and discusses how to:

• Configure and start analytic servers.

• Administer analytic servers.

• Administer analytic tables.

• Create, delete, and copy analytic instances.

• Load and unload analytic instances.

Understanding the Analytic Server Framework

This section discusses:

• Analytic server framework overview.

• Analytic server process flow and behavior.

Analytic Server Framework Overview

When a program doesn't “maintain state” or when the infrastructure of a system prevents a program from maintaining state, it's known as a stateless program or system. It can't take information about the last session into the next session, such as settings the user makes or conditions that arise during processing.

For example, the HTTP protocol is stateless. Additional schemes, such as cookies, are necessary to maintain state in the HTTP (web) environment.

PeopleTools is architected primarily around a stateless model of client/server connectivity. This model enables users' application sessions to be preserved even if servers are shut down or rebooted. All session state is maintained by the client and is transferred to the server with each request. As long as an application server is up and running, a user’s session remains active and functional, and any application server can perform requested transactions.

However, with some products, such as Analytic Calculation Engine or PeopleSoft Optimization Framework, running a calculation on a multi-dimensional model is likely to produce far more data than is reasonable to shuttle between a client and server to maintain a stateless connection. For performance reasons, the calculations are performed completely in memory. If these calculations were to be synchronized and stored in the database so that a stateless connection could be maintained, performance would suffer significantly.

The analytic server framework provided by PeopleSoft is a general server infrastructure designed to meet the needs of PeopleSoft products that process large amounts of data in memory. It provides a stateful model of client/server connectivity that these products require to be part of the PeopleTools system, by keeping track of configuration settings, transaction information, and other data for a session.

For example, client software could request that an analytic model or optimization model be recalculated in one transaction, then retrieve the results of the calculation on that model at a later time. A server process handles these requests, and maintains the model state and calculated data in memory between the requests. Additional transactions can then modify the model and perform recalculations on it without shuffling all of the data between the client and the server or dumping all the data to a database, thus preserving in-memory performance.

A large model might take a long time to load. In the event that a user’s session times out and is terminated, the loading and calculation of the model continues, and enables the user to return to the model at a later time in a new session.

The elements of the analytic server framework are:

• PSANALYTICSRV server.

  PSANALYTICSRV is a Tuxedo managed PeopleSoft application server process, like PSAPPSRV. It contains both the analytic calculation engine and the optimization engine. Multiple instances of PSANALYTICSRV can run in an application server domain. The current condition of each PSANALYTICSRV instance is tracked in system tables.

• Analytic server administration pages.

  The Analytic Domain Summary page provides current information about the application server domains with PSANALYTICSRV running that are attached to the current database.

  The Analytic Servers page enables you to inspect the individual analytic server instances within the running domains, with information about their analytic types and analytic instances, operations, and timeout intervals. You can also halt processes individually on this page.

• Analytic table administration pages.

  The Purge Delete Tables page displays the names of delete tables relevant to an analytic type or analytic instance, and enables you to clear the data from the tables.

  The Synchronize Table Versions page enables you to resynchronize versions of analytic type or analytic instance data and the PSOPTSYNC table that are out of synchronization after you use PeopleSoft Data Mover to move data from one database to another.

• Pages for creating, deleting, and copying analytic instances.

  The Create Analytic Instance, Delete Analytic Instance, and Copy Analytic Instance pages enable you to define and manage analytic instances that you can then load to inspect and debug your analytic models.

• The Analytic Instance Load/Unload page.

  The Analytic Instance Load/Unload page enables you to load analytic instances so you can view them within the Analytic Model Viewer, then unload the analytic instances that you no longer need.

• Various supporting enhancements in several PeopleTools products.

  These products include Analytic Calculation Engine, PeopleSoft Optimization Framework, Crystal Reports, PeopleSoft Performance Monitor, PeopleSoft Process Scheduler, PeopleSoft Application Engine, PSADMIN, and PeopleCode.

  Note. Information about the role that the analytic server framework plays in these products can be found in the documentation for each product.

Analytic Server Terms

The following terms are useful in understanding analytic server technology:

Analytic Server Features

The analytic server framework has the following features:

• It's dedicated to the storage and management of large models.

• It's supported on all PeopleTools application server platforms.

• It runs PSANALYTICSRV as a Tuxedo managed server.

• You can configure the minimum and maximum number of analytic server instances per domain that are running at one time.

• You can specify a timeout for a loaded analytic instance. If the analytic instance isn't referenced within the timeout interval, it's discarded.

• Multiple domain environments are supported, in which an analytic instance can be loaded in one Tuxedo domain, and a user can access the analytic instance from another domain.

• You install, configure, and administer analytic servers using the same facilities as with other servers.

• You can shut down an analytic server and discard any loaded analytic instances.

• You use the standard PeopleTools mechanisms to troubleshoot, trace, log and debug analytic servers.

See Also

Using the Quick-Configure Menu

Setting Application Server Domain Parameters

PeopleSoft Optimization Framework Preface

Performance Monitor Preface

Analytic Server Process Flow and Behavior

PeopleSoft session activity, such as a user action, a component interface operation, or a message subscription, launches PeopleCode that requires the application server to invoke the analytic calculation engine or the optimization engine to process an analytic instance.

The database maintains a list of all the available PSANALYTICSRV (analytic server) instances, their status, and any analytic instances currently loaded, so it can properly select analytic server instances for new analytic instances, and direct subsequent requests to the proper analytic server instance. When an analytic server instance starts, the database is updated.

When a running program requests the creation of an analytic instance, the analytic server framework considers all available PSANALYTICSRV instances in the same application server domain and allocates one of them from the pool of idle server instances to handle this particular analytic instance. Any further load or recalculate operations requested by the application for this analytic instance are directed back to the same analytic server instance for processing.

Note. If there are no idle server instances, the analytic server framework can spawn additional server instances up to a maximum limit that you can define in the application server domain configuration. If this maximum is reached, the system attempts to allocate a server instance from a running analytic server in another domain.

Analytic server architecture

After an analytic server instance takes over processing the analytic instance, that processing becomes independent of the status of the application server. The core functionality provided by the analytic server framework is the ability to host analytic instances for an indeterminate amount of time in an environment where that data can persist across multiple sessions, and where that data can be accessed without requiring its entire content to be transferred from server to client and back.

Analytic Instance Access

Access to the analytic instances maintained by the analytic server environments is supported only through PeopleCode programs. The environments in which PeopleCode can run include:

• The application server (PSAPPSRV).

• PeopleSoft Application Engine accessed by PeopleSoft Process Scheduler (PSAESRV or psae)

• PeopleSoft Application Engine run from the command line (psae).

An allocated server instance doesn't need to be running in the same Tuxedo domain or on the same server machine as the application server. Once it's allocated, the initiating user is redirected to an application server that's running on the same domain and server machine as the analytic server.

PeopleCode that's running in any PSAPPSRV process can access analytic instances that were loaded by any other PSAPPSRV process, regardless of the Tuxedo domain in which it's running. When the program requests access to such an analytic instance, the running PeopleCode program is restarted and the web server is notified to redirect the request back to an application server within the Tuxedo domain where the analytic instance is loaded. This application server is then able to directly contact the PSANALYTICSRV server with the loaded analytic instance.

Note. PeopleCode that's running in a given Application Engine environment can access only analytic instances that were loaded in the same process.

Secondary Database Connection

A secondary database connection is used to prevent unexpected table locks when you run an analytic calculation. The secondary connection isn't opened until an analytic instance is referenced in a PeopleCode program. A secondary connection is required regardless of whether the analytic calculation is run by an application engine program as a batch process or directly by an online application.

By default, the secondary connection is persistent for improved performance. If you find that the persistent connection imposes too much overhead, you can change it to an on-demand connection by setting bit eight of the DbFlags application server and process scheduler domain parameter.

Note. A non-persistent connection can significantly affect system performance, so consider this setting carefully.

You can use DbFlags bit four to disable the secondary connection altogether, but analytic instance processing requires it, so ensure that DbFlags does not have bit four set.

Errors and Abnormal Process Termination

Any errors that occur while processing an analytic server request result in the PeopleCode program returning an error code or throwing a PeopleCode exception.

If an analytic server instance that's hosting an analytic instance terminates unexpectedly, the loaded analytic instance is lost and unrecoverable. However, the analytic instance status still appears on the Analytic Server Administration pages. The domain monitor (PSMONITORSRV) discovers the unexpected termination and cleans up the status information.

See Also

DbFlags

Load

PeopleSoft Process Scheduler Preface

Understanding Batch Processing of Analytic Instances

The analytic server framework integrates with and works with PeopleSoft Process Scheduler using PeopleSoft Application Engine, because PeopleSoft Application Engine can access the analytic calculation engine and the optimization engine directly.

When PeopleSoft Process Scheduler launches an Application Engine job to process an analytic instance, PeopleSoft Application Engine handles the entire job directly by loading the analytic engine within its own process rather than using a server.

This is true whether PeopleSoft Process Scheduler submits the job to the PSAESRV process, or launches PeopleSoft Application Engine using the psae command.

See Also

PeopleSoft Optimization Framework Preface

Configuring and Starting Analytic Servers

This section discusses how to:

• Enable PSANALYTICSRV.

• Specify analytic server instance quantities.

• Start PSANALYTICSRV.

You can specify whether an application server domain includes the PSANALYTICSRV Tuxedo managed application server process, and specify the maximum number of analytic server instances that you want the domain to support. You use the Quick-Configure menu of the PSADMIN utility to enable, configure, and start analytic server instances.

Enabling PSANALYTICSRV

You access the Quick-Configure menu of PSADMIN by selecting Configure This Domain from the Domain Administration menu.

On the Quick-Configure menu, enter the menu item number for Analytic Servers to toggle the setting for that entry to Yes, so the domain will include instances of PSANALYTICSRV when it boots.

See Also

Using the Quick-Configure Menu

Specifying Analytic Server Instance Quantities

Before you boot the application server domain, specify the appropriate minimum and maximum number of allowed analytic server instances. The values you specify depend on your assessment of how many users you expect to be using applications that process analytic instances.

Consider the typical number of analytic instances in a domain that are being processed at any given moment as your minimum, and the possible total number of analytic instances that might simultaneously require processing as your maximum. The most appropriate values produce the fastest system response without unused server instances consuming memory unnecessarily.

To specify analytic server instances:

1. On the Quick-Configure menu for the domain, enter the menu number for Custom Configuration.

   The Custom Configuration environment launches, and prompts you to indicate whether you want to change any configuration values.

2. Enter y to indicate that you want to change configuration values.

   Custom Configuration prompts you to decide whether to change any values for each configuration item in turn.

3. Press Enter to accept the default answer for each item presented, until the following entry appears:

   Values for config section - PSANALYTICSRV

4. Enter y to change the values for PSANALYTICSRV.

   You're prompted for each value in turn.

5. Specify the minimum number of instances.

   This defines the number of analytic server instances that start when you boot the application server domain. There are always at least this number of instances running. The default value of this parameter is 3.

6. Specify the maximum number of instances.

   This defines the maximum number of analytic server instances that can result from spawning new processes. The default value of this parameter is 3.

7. Press Enter to accept the default answer for each subsequent item presented. When you respond to the last item, PSADMIN loads the new configuration and the PeopleSoft Domain Administration Menu appears.

   You now can boot the domain normally.

Notice that one analytical server can load only one analytic instance. If no analytical server is available to access analytical instance, you may experience one of these two scenarios:

• Only one tuxedo domain is available.

  This scenario happens when analytical instance accesses 'n+1' th analytical server where n is the maximum number of analytical servers configured. In this scenario, a message appears to alert you that no analytical server is currently available.

• More than one tuxedo domains are available.

  This scenario happens when analytical instance accesses 'n+1' th analytical server. Analytical instance checks for available tuxedo domains and redirects the request to the domain where analytical server is available. If no analytical server is available in these tuxedo domains, a message appears to alert you that no analytical server is currently available.

See Also

Using the Quick-Configure Menu

PSANALYTICSRV Options

Starting PSANALYTICSRV

If you enabled analytic servers on the Quick-Configure menu, when you boot the application server domain, the PSANALYTICSRV process starts with the minimum number of instances that you specified.

When an application running under this domain requests an analytic instance, the analytic server framework allocates an available idle analytic server instance for that analytic instance. If no idle server instance is available, the framework spawns and allocates an additional server instance, up to the maximum that you defined.

Administering Analytic Servers

This section discusses how to:

• Administer analytic server domains.

• Administer analytic server instances.

Administering Analytic Server Domains

In a browser, select PeopleTools, Utilities, Administration, Analytic Server Administration to access the Analytic Server Administration - Analytic Domain Summary page.

This page displays the current status of the application server domains with PSANALYTICSRV running that are attached to the current database. Each active domain is listed, along with the following information:

Click a domain's Clear button to remove that row from the display when the domain has been unexpectedly terminated.

Warning! Use the Clear button with caution, and only if you're certain that the domain has been unexpectedly terminated. Clearing the domain information for servers that are still running produces errors in those servers.

Click the Refresh button to retrieve information about any newly started domains that have PSANALYTICSRV running.

Administering Analytic Server Instances

In a browser, select PeopleTools, Utilities, Administration, Analytic Server Administration, Analytic Servers to access the Analytic Server Administration - Analytic Servers page.

Click the Search button to retrieve status information about all analytic server instances that are running in application server domains that are attached to the current database. You can use the Search Criteria section to limit the information returned based on various criteria.

Search Criteria

Analytic Servers

This section displays a row of status information retrieved for each analytic server instance that's returned by the search. In addition to the fields documented in the previous section, each row displays the following information:

Administering Analytic Tables

This section discusses how to:

• Purge delete tables.

• Synchronize table versions.

Purging Delete Tables

In a browser, select PeopleTools, Utilities, Administration, Analytic Server Administration, Purge Delete Tables to access the Analytic Server Administration - Purge Delete Tables page.

Note. Shut down all running analytic server processes before using this page.

Delete tables contain rows that have been deleted from analytic instance working data. These tables accumulate data when you use triggers for database level auditing, and they're not always cleaned up after the deletes have been completed. You use this page to accomplish the cleanup manually.

See Also

Employing Database Level Auditing

Synchronizing Table Versions

In a browser, select PeopleTools, Utilities, Administration, Analytic Server Administration, Synchronize Table Versions to access the Analytic Server Administration - Synchronize Table Versions page.

Note. Shut down all running analytic server processes before using this page.

Some scenario-managed optimization tables used with an analytic type have a version number field. The analytic server framework maintains a list of the tables and their version numbers. After an upgrade, the version numbers in the upgraded tables might not match the version numbers on this list. You use this page to update the list so the version numbers match.

Creating, Deleting, and Copying Analytic Instances

This section discusses how to:

• Create analytic instances.

• Delete analytic instances.

• Copy analytic instances.

  Note. You can create, delete and copy analytic instances for use with both Analytic Calculation Engine and PeopleSoft Optimization Framework.

Pages Used to Create, Delete, and Copy Analytic Instances

Creating Analytic Instances

Use the Create Analytic Instance page to create an analytic instance that you can then load and view within the Analytic Model Viewer to inspect and debug your analytic model.

Select PeopleTools, Utilities, Administration, Analytic Inst. Create/Del/Copy to access the Create Analytic Instance page.

Analytic Type	Select an analytic type from the drop-down list. See Working with Analytic Types. See Creating Analytic Type Definitions.
Analytic Instance	Enter a name for the analytic instance. Analytic instance names should consist of alphanumeric characters, can be up to 20 characters long, and cannot include spaces.
App Package Path and App Class Method	The App Package Path field displays the full name of an application class (application package name, subpackage names if applicable, and class name) that's used to execute logic before loading the analytic instance. The App Class Method field displays the name of the method in the displayed class that's called at creation time to populate the new analytic instance with data. You establish the application package class and method to use when you define the analytic type. See CreateAnalyticInstance.
Record with Parameters	Look up and select parameters to be passed to the application class method. Click the lookup button to display a list of records. Selecting any record generates a standalone record.
Populate Record Fields	Displays a secondary page that lets you populate the fields of the standalone record; the values of these fields will serve as parameters passed into the App Class Method.
Create Analytic Instance	Create the analytic instance. After the analytic instance has been successfully created, you receive a notification to that effect.

Deleting Analytic Instances

Select PeopleTools, Utilities, Administration, Analytic Inst. Create/Del/Copy, Delete Analytic Instance to access the Delete Analytic Instance page.

You can specify search criteria to filter the display of returned analytic instances based on a combination of analytic type, model name, and server state.

Copying Analytic Instances

Select PeopleTools, Utilities, Administration, Analytic Inst. Create/Del/Copy, Copy Analytic Instance to access the Copy Analytic Instance page.

You can specify search criteria to filter the display of returned analytic instances based on a combination of analytic type, model name, and server state.

Loading and Unloading Analytic Instances

This section discusses how to load and unload analytic instances:

Note. You can load and unload analytic instances for use with both the Analytic Calculation Engine and PeopleSoft Optimization Framework.

Loading and Unloading Analytic Instances

To use the Analytic Model Viewer, you must load an analytic instance of the analytic model that you want to view or debug. You load analytic instances by using:

• The Analytic Instance Load/Unload page.

• The Analytic Model Viewer.

You unload instances by using the Analytic Instance Load/Unload page (PTACEMDLLOAD).

It is quicker to load an analytic instance by going through the Analytic Model Viewer: This approach allows you to simultaneously load and view the analytic instance. However, you can use the Analytic Instance Load/Unload page if you need to modify the timeout value or attach or detach a tree. You need to attach a tree before loading an analytic instance if you want to see the tree structure while reviewing this analytic instance within the Analytic Model Viewer.

See Understanding Analytic Model Properties.

See Creating Hierarchies.

Note. You can only load one analytic instance per analytic server.

You can also load and unload analytic instances by means of PeopleCode, using the AnalyticInstance class Load or Unload methods.

See AnalyticInstance Class Methods.

Access the Analytic Instance Load/Unload page (PTACEMDLLOAD) by selecting PeopleTools, Utilities, Administration, Analytic Instance Load/Unload; and selecting the desired analytic instance on the search results page.

Note. If you don't see the desired analytic instance, you need to create it as described earlier.

If you selected a PeopleSoft Optimization Framework analytic instance, you won't see the Attach/Detach Tree portion of the Analytic Instance Load/Unload page.

See Creating, Deleting, and Copying Analytic Instances.

Attach/Detach Tree

Analytic Instance Load/Unload

See Also

Load