Using the Application Server Administration Menu
This section discusses how to:
Access the application server options.
Administer a domain.
Boot a domain.
Shut down a domain.
Perform a normal shutdown.
Perform a forced shutdown.
Check the domain status.
Purge the domain cache.
Configure a domain.
Edit configuration and log files.
Create a domain.
Delete a domain.
Configure an application server domain to preload cache.
Clean domain IPC resources.
Accessing the Application Server Options
To access the menu options for configuring and administering an application server, select Application Server from the PeopleSoft Server Administration (PSADMIN) menu.
-------------------------------------------- PeopleSoft Application Server Administration -------------------------------------------- 1) Administer a domain 2) Create a domain 3) Delete a domain 4) Import domain configuration q) Quit Command to execute (1-4, q) : 4
The Administer a domain menu offers numerous configuration, administration, and logging parameters that you may access frequently.
The menu options and parameters within the Create a domain andDelete a domain menus are one-time tasks (per domain).
The Import domain configuration menu enables you to import existing configurations.
Administering a Domain
To administer a domain, you must have already created a domain. After you have created a domain, specify environment-specific settings for the application server to function correctly with your system. The following sections describe all of the menus and menu options that you use to administer and configure an application server domain.
To administer a domain:
Select Administer a domain from the PeopleSoft Application Server Administration menu.
In the Select domain number to administer command line, enter the number that corresponds to the previously created domain that you want to administer that appears in the Tuxedo domain list.
Select the option that you want to perform from the PeopleSoft Domain Administration menu.
PSADMIN transparently sets several environment variables before invoking any Tuxedo administrative commands. You don't need to set these variables manually. These environment variables are:
TUXCONFIG = PS_CFG_HOME/appserv/domain_name/PSTUXCFG
APPDIR = PS_CFG_HOME/appserv/domain_name
PATH = TUXDIR/bin; PS_HOME/bin/server/winx86; PATH
APP_PW = Application Password (initialize)
Importing Domain Configurations
You import existing domain configurations by selecting the Import domain configuration option from the PeopleSoft Application Server Administration menu. From the PeopleSoft Import Application Server Configuration menu, you have the option to import a regular domain or an Integration Broker Master Configuration.
-------------------------------------------- PeopleSoft Import Application Server Configuration -------------------------------------------- 1) Import regular domain 2) Import IB Master Configuration q) Quit Command to execute (1-2, q) : 1
Importing a Regular Application Server Domain
When importing a regular application server domain, you can import from a file or from a domain.
-------------------------------------------- PeopleSoft Import Application Server Configuration -------------------------------------------- 1) Import from file 2) Import from application domain q) Quit Command to execute (1-2, q) :
To import configuration settings from a file:
From the PeopleSoft Import Application Server Configuration menu, select Import from file.
Enter the complete file path to the PSAPPSRV.CFG file containing the desired configuration settings.
c:\documents and settings\TSAWYER.DOMAINX\PSFT\PT\8.52\appserv\appserv\PT850TST
Enter a name for the new domain.
To import configuration settings from an existing domain:
From the PeopleSoft Import Application Server Configuration menu, select Import from application domain.
Enter the path to the appropriate PS_CFG_HOME.
c:\documents and settings\TSAWYER.DOMAINX\PSFT\PT\8.52\appserv
From the Tuxedo domain list, select the domain containing the desired configuration settings.
Enter a name for the new domain.
Importing an Integration Broker Master Configuration
Use this option to import a master configuration, if you are implementing a "master-slave" integration server configuration. This implementation option is documented in detail within the Integration Broker Administration PeopleBook.
Booting a Domain
This boots the Tuxedo domain (the application server) by using the tmboot command. This command will start all of the server processes that have been configured for your domain.
------------------------------- PeopleSoft Domain Boot Menu ------------------------------- Domain Name: DOC 1) Boot (Serial Boot) 2) Parallel Boot q) Quit Command to execute (1-2, q) [q]:
You have two booting options: a serial boot and a parallel boot.
Running a Serial Boot
A serial boot starts server processes in a sequential order, with one process beginning to start after the previous process has completely started.
Running a Parallel Boot
A parallel boot starts server processes at the same time, rather than having each process start sequentially. This option typically provides shorter boot durations.
Shutting Down a Domain
The PeopleSoft Domain Shutdown menu offers two options: a normal shutdown and a forced shutdown.
------------------------------- PeopleSoft Domain Shutdown Menu ------------------------------- Domain Name: psdmo 1) Normal shutdown 2) Forced shutdown q) Quit Command to execute (1-2, q) [q]:
Performing a Normal Shutdown
A normal shutdown is a quiescent shutdown that waits for users to complete their tasks and turns away new requests before terminating all of the processes in the domain.
Performing a Forced Shutdown
A forced shutdown is a nonquiescent shutdown that immediately terminates all of the processes in the domain. Normally, you use the forced shutdown only when a Bulletin Board Liaison (BBL) process encounters errors and cannot be shut down by using a normal shutdown.
Note: The BBL is a primary Tuxedo process that controls the domain.
Checking the Domain Status
Use the PeopleSoft Domain Status menu to view the status of the server, queues, or clients connected to the domain.
----------------------------- PeopleSoft Domain Status Menu ----------------------------- Domain Name: psdmo 1) Server status 2) Client status 3) Queue status q) Quit Command to execute (1-3, q) [q]:
Select Server status to invoke the Tuxedo tmadmin psr subcommand (print server processes), which displays the Tuxedo processes and PeopleSoft server processes that are currently running. For example:
> Prog Name Queue Name Grp Name ID RqDone Load Done Current Service --------- ---------- -------- -- ------ --------- --------------- BBL.exe 62645 RTDC796+ 0 42801 2140050 ( IDLE ) PSAPPSRV.exe APPQ APPSRV 1 422 21100 ( IDLE ) PSMONITORSRV.e MONITOR MONITOR 1 0 0 ( IDLE ) PSWATCHSRV.exe WATCH WATCH 1 0 0 ( IDLE ) PSAPPSRV.exe APPQ APPSRV 2 4 200 ( IDLE ) JSL.exe 00095.00200 JSLGRP 200 0 0 ( IDLE ) PSMSGDSP.exe 00098.00100 PUBSUB 100 4 200 ( IDLE ) PSSAMSRV.exe SAMQ APPSRV 100 0 0 ( IDLE ) PSMSGHND.exe MBHQ PUBSUB 101 0 0 ( IDLE ) JREPSVR.exe 00094.00250 JREPGRP 250 29 1450 ( IDLE )
The number of items appearing depends on the number of server processes that you have configured.
Select Client status to invoke the Tuxedo tmadmin pclt subcommand (printclient), which displays connected users. For example:
> LMID User Name Client Name Time Status Bgn/Cmmt/Abrt --------------- --------------- --------------- -------- ------- ------------- RTDC79623VMC NT JSH **:**:** IDLE 0/0/0 RTDC79623VMC NT JSH **:**:** IDLE 0/0/0 RTDC79623VMC JPOOL_15 dhcp-adc-twvpn+ 0:02:03 IDLE/W 0/0/0 RTDC79623VMC NT tmadmin 0:00:00 IDLE 0/0/0
Examining the status of the individual queues for each server process provides valuable tuning information. Check the queues by using the Queue status option. In the following example, the results of the Queue status option show the individual server processes, the associated queue, the number of server processes currently running, and the number of requests waiting to be processed:
> Prog Name Queue Name # Serve Wk Queued # Queued Ave. Len Machine --------- ------------------- --------- -------- -------- ------- PSAPPSRV.exe APPQ 2 - 0 - RTDC79623+ JSL.exe 00095.00200 1 - 0 - RTDC79623+ JREPSVR.exe 00094.00250 1 - 0 - RTDC79623+ BBL.exe 62645 1 - 0 - RTDC79623+ PSMONITORSRV.e MONITOR 1 - 0 - RTDC79623+ PSWATCHSRV.exe WATCH 1 - 0 - RTDC79623+ PSSAMSRV.exe SAMQ 1 - 0 - RTDC79623+ PSMSGHND.exe MBHQ 1 - 0 - RTDC79623+ PSMSGDSP.exe 00098.00100 1 - 0 - RTDC79623+
The results alert you to any bottlenecks that may be occurring on your application server. With this information, you can make more informed performance decisions. For instance, if the bottlenecks appear to be persistent, it may indicate that you need to add more instances of a particular server process, such as PSAPPSRV for example. Or the results may indicate that you need to start either a PSQCKSRV or a PSQRYSRV.
Purging the Domain Cache
A proven technique for resolving problem application server environments is to purge the application server domain cache located in PS_CFG_HOME\appserv\domain_name\CACHE.
Important! You should purge the cache only after due consideration, and in after consultation with PeopleSoft support or consultants.
Please keep the following in mind:
You cannot purge shared file cache.
You can purge the cache regardless of whether the application server domain is running; there's no need to shut it down and reboot. However, the procedure is less disruptive and runs more quickly if the domain is shut down or its activity level is low.
Purging the cache can take five minutes or more on a large or busy domain, depending on the domain configuration.
If database cache is enabled, the database cache will be purged. If the database cache is purged, it affects all domains using that cache. The database cache is shared across all domains that use the same byte-order (little-endian or big-endian).
To purge the domain cache:
On the PeopleSoft Domain Administration menu, select Purge Cache.
If the cache is currently empty, the purge operation is cancelled, and the PeopleSoft Domain Administration menu reappears.
If the cache is not empty, the following prompt appears:
Enter log comments about this purge, if any (maximum 256 characters):
Enter any information (up to 256 characters) that you want recorded explaining the circumstances of this cache purge operation, and press Enter. Your comments will be saved to a purge log file.
The following prompt appears:
Do you wish to archive the contents of the current cache? (y/n) [n] :
Enter y to archive the cache contents, orn to delete them permanently. The default response isn.
If you enter y, the following prompt appears:
Cache contents will be archived to PS_CFG_HOME\appserv\domain_name\Archive\CACHE_mmddyy_hhmm_ss. Hit Enter to continue or provide a new location:
Note: At runtime, PS_CFG_HOME and domain_name are replaced with values appropriate to your system, andmmddyy_hhmm_ss represents the date and time of the cache purge operation.
(If you chose to archive the cache contents) Enter a different archive location if desired, and press Enter.
If the location you enter is rejected, the following message appears, and you're prompted to continue:
Failed to archive cache to location.
Note: Continuing this procedure with an invalid location will purge the cache without archiving.
The default location is a unique directory name. Keep in mind that the location you enter might have been rejected for the following reasons:
The directory can't be created due to an invalid drive or network mount.
The directory can't be created due to insufficient user privileges.
The directory has insufficient space for the cache files.
When prompted to continue, enter y to continue the purge operation, orn to cancel the operation and return to the PeopleSoft Domain Administration menu.
Note: Archiving the cache increases the time required to complete the purge, because the cache files must be copied to the archive location.
If the application server domain is running, you might see INFO: messages related to version, patch level, serial number and so on. These are normal and don't require any action. When the cache is successfully purged, the following message appears:
Purge Cache operation completed successfully. You may notice that the cache directory is non-empty. Cache files have been invalidated and will be refreshed from the database.
If the cache was archived, you'll also see the following:
You may also have noticed a number of Sharing Violation messages during the Cache Purge. These messages are no cause for alarm and are expected as part of the cache archival.
If the application server domain is running, an entry is written to the application server log file to indicate that the cache has been purged.
The purge log file is saved (including any comments you entered in step 2) as PS_CFG_HOME\appserv\domain_name\LOGS\PurgeCache_mmddyy_hhmm_ss.log.
Note: At runtime, PS_CFG_HOME and domain_name are replaced with values appropriate to your system, and mmddyy_hhmm_ss represents the date and time of the cache purge operation.
Following is an example of the purge log file contents:
Date:02/17/10 11:47 User Explanation: Processes appeared to take a long time to recycle. Cache Contents archived to C:\ptservers\appserv\QEDMO\Archive\CACHE_021710_1147_01
Configuring a Domain
This option prompts you with a model configuration file to gather such parameters as port numbers, the number of various server processes that are needed, encryption enabling, and so forth. PSADMIN then invokes a subprogram, UBBGEN, which takes the configuration parameters, builds the file PS_CFG_HOME/appserv/domain-name/psappsrv.ubb, and carries out thetmloadcf - y psappsrv.ubb command to generate the following file:PS_CFG_HOME/appserv/domain-name/PSTUXCFG.
The following topics describe all of the parameters that you encounter while configuring an application server. Either read this section before you fine tune the configuration of your application server or have it available while you are doing it.
To configure a domain:
Select Configure this domain from the PeopleSoft Domain Administration menu.
Enter n (No), if you do not want to continue. This returns you to the previous menu. Otherwise, entery (Yes).
When prompted to change configuration values, enter y.
If you don't need to change any of the values, enter n. By doing so, you create a new configuration file with the same values that were previously specified. Enter n, or elect not to modify the PSADMIN parameters, if:
You have changed only the location of TUXDIR.
You would rather edit the PSAPPSRV.CFG file manually.
You installed a new Tuxedo patch.
Note: If you edit the psappsrv.cfg file directly, it is recommended to reload your domain configuration. This is necessary because some settings in psappsrv.cfg are transferred to the PSTUXCFG file for the domain. This transfer of settings can only be achieved by running UBBGEN and tmloadcf, which the "Configure this domain" option performs.
Editing Configuration and Log Files
Use the Edit Configuration/Log Files menu to view the application server and Tuxedo log files. You can also manually edit the PSAPPSRV.CFG file if you do not want to use the PSADMIN interface.
To have PSADMIN start your text editor (such as Notepad or KEDIT) so that you can manually edit or view application server configuration and log files, you must specify the text editor in the environment settings. For example, to use KEDIT, the editor environment setting should look like this:
To use Notepad, it should look like this:
Note: You can view and edit a domain's PSAPPSRV.CFG file while the domain is running, but the changes that you specify do not take effect until the next time you reconfigure the domain.
For the following options, you must enter your operator ID to view and edit the files:
Edit PSAPPSRV.tracesql (PSAPPSRV SQL trace file) Edit PSSAMSRV.tracesql (PSSAMSRV SQL trace file)
Command to execute (1-7, q) [q]: 5 Enter the operator ID : PTXYZ
Note: PeopleSoft secures the Structured Query Language (SQL) traces because, in some instances, the SQL that is traced may involve sensitive information.
Note: Server configuration files (.CFG) support the use of environment variables, such as %PS_HOME%, %TEMP%, and so on.
The PSAPPSRV.CFG file contains all of the configuration settings for an application server domain. The PSADMIN interface provides prompts so that you can edit and modify this file within a structured format. In many cases, and perhaps due to personal preference, you may opt to edit the PSAPPSRV.CFG file manually in a text editor. When editing this configuration file manually, note that it is similar to editing an INI file, because all of the parameters are grouped in sections.
This log file contains PeopleTools specific logging information.
The TUXLOG file enables you to trace the Tuxedo component for troubleshooting information.
You can specifically trace the activity of the PSAPPSRV server process by setting the PSAPPSRV.tracesql option.
You can specifically trace the activity of the PSSAMSRV server process by setting the PSSAMSRV.tracesql option.
Creating a Domain
The Create a domain option creates a subdirectory underPS_CFG_HOME/appserv using the domain name you specify as the directory name and copies the required domain files to that directory.
To create an application server domain:
Select Create a domain from the PeopleSoft Application Server Administration menu.
Enter the name of the domain that you want to create; the name must not exceed eight characters.
Select a configuration template from the Configuration template list.
The configuration templates are preconfigured sets of application server processes.
Deleting a Domain
Use the Delete a domain option to shut down the domain, if running, and delete the domain's subdirectory.
Note: Before you delete a domain, make sure that it is not running.
To delete a domain:
Select Delete a domain from the PeopleSoft Application Server Administration menu.
From the Tuxedo domain list, select the number that corresponds to the domain that you want to delete.
When prompted to continue, enter y and press Enter.
If the application server domain is currently running, PSADMIN informs you of that, and you will need to determine if you want to continue.
Domain processes are currently running. This option will shutdown and delete the domain. Do you want to continue? (y/n) [n] :
If you enter y, PSADMIN performs a forced shutdown on the domain prior to deleting the domain.
If you enter n, PSADMIN returns you to the PeopleSoft Application Server Administration menu, allowing you to shutdown the domain manually, if needed.
Configuring an Application Server Domain to Preload Cache
This section provides an overview and discusses how to:
Create cache projects.
Delete cache projects.
Preloading File Cache.
Understanding Preload Cache Projects
To improve performance, the application server uses a caching mechanism that keeps commonly used objects in memory and either file form on the application server or in a database cache. Caching reduces the need for a complete database query each time a definition is accessed. As more definitions are accessed, more data becomes stored in the cache. However, if a page, for example, has not already been accessed, it does not exist in the current cache, and the user may experience a slower response time as the system requests the page from the database for the first time. To prevent this initial performance degradation, you can preload file, database, and memory cache with commonly used definitions inserted into a cache project.
Preloading cache involves creating a project containing commonly used definitions and then referring to these projects in the PSADMIN settings PreloadMemoryCache and PreloadCache. By default, PreloadMemoryCache and PreloadCache are commented out because the two parameters need to be set to a specific name of a project that you create. You can set the parameters to reference separate projects. You use the Select Preload Objects page to select frequently used definitions and build the preload project containing the objects selected.
The cache project is intended to be used for a new domain, where the cache is not yet built. Prior to providing the domain for production use, use the Preload Cache PSADMIN option to build the cache containing the objects specified in the project. The domain starts the PSAPPSRV process, builds the cache, and shuts down.
The memory cache project is intended to be used during a server process recycle. When a the system starts a new process to replace an old one, the new process loads memory cache based on the project specified by PreloadMemoryCache so that the new process will not have delays when processing the first few service requests. Because it is desirable to have new processes start as quickly as possible, there is a timeout (or limit) of 60 seconds for PreloadMemoryCache. That is, PreloadMemoryCache preloads as many definitions as possible before the timeout of 60 seconds.
Note: In general, it is not recommended to create large projects for the PreloadMemoryCache project. For all cache projects (used for file, database, and memory cache) the optimum selections for the projects will require tuning and testing at your site.
Creating Cache Projects
To create cache projects:
In a browser, select PeopleTools, Utilities, Administration, PreLoad Cache, Select Preload Objects.
Select the Add a New Value tab, and in the Project Name edit box, enter the name of the project that will contain the definitions you select, and clickAdd.
Note: All project names used to contain definitions for preloaded cache must contain the "PLC_" prefix.
On the Select Preload Objects page, enter a Description, and select the Object Type to add.
Object Type refers to the definitions you create with PeopleTools, such as components, menus, pages, Application Engine programs, and so on.
Use the Key fields, to refine the selection of the definition as needed.
The keys will differ depending on the Object Type selected.
Note: Project definitions support up to four keys for identification, so you can use up to four keys when selecting objects for the preload cache project.
Click Build Project Definition.
On the Process Scheduler Request page, click OK.
This invokes an Application Engine program (PTCHPLC_PRJ) that creates the project definition in the database and populates it with the definitions you selected. The PTCHPLC_PRJ also automatically includes all related definitions in the project.
Note: Cache projects can be created manually in Application Designer, without running the PTCHPLC_PRJ program. The project name must include "PLC_".
Deleting Cache Projects
To delete a preload file cache project:
Select PeopleTools, Utilities, Administration, Preload Cache, Delete Preload Project.
On the Find an Existing Value page, click the appropriate project name.
On the Delete Preload Project page confirm that you have selected the appropriate project and click Delete the preload project.
Preloading Cache Projects
To preload a cache project:
Shut down the application server domain.
Edit the PSAPPSRV.CFG configuration file for the appropriate domain.
In the [Cache Settings] section, uncomment the PreloadCache= parameter, and enter the name of the pre-load project for this application server domain.
On the PeopleSoft Domain Administration menu in PSADMIN, select 9) Preload Cache.
When preloading cache, keep the following in mind:
Preload Cache does not work when shared caching is enabled.
If database caching is enabled, Preload Cache loads the cache project into the database cache.
Preloading Memory Cache
To preload the memory cache:
Edit the PSAPPSRV.CFG configuration file for the appropriate domain.
In the [Cache Settings] section, uncomment the PreloadMemoryCache= parameter, and enter the name of the preload project that should be preloaded on this application server for memory cache.
Cleaning Domain IPC Resources
Use the Clean IPC Resources of this domain option to clear the interprocess communication (IPC) resources utilized by a domain. When a domain shuts down normally, the IPC resources it was using get released as part of the shut down process. However, if a domain terminates abnormally, in many cases the IPC resources are still assigned to the previous domain instance. This option enables you to clean any orphaned IPC resources assigned to a domain.