Chapter 6 Managing Application Engine Programs

管理应用程序引擎程序

Running Application Engine Programs

运行应用程序引擎程序

This section provides an overview of program run options and discusses how to:

本节提供程序运行选项的概述，并讨论如何：

• Create process definitions.
• 创建进程定义。
• List process definition parameters.
• 列出过程定义参数。
• Start programs with the Application Engine Process Request page.
• 使用“应用程序引擎进程请求”页面启动程序。
• Use PeopleCode to invoke Application Engine programs.
• 使用PeopleCode调用应用程序引擎程序。
• Use the command line to invoke Application Engine programs.
• 使用命令行调用应用程序引擎程序。

Understanding Program Run Options

了解程序运行选项

You run Application Engine programs in one of the following modes: batch using PeopleSoft Process Scheduler, online using a PeopleCode function, or manually using the command line. The following table lists some differences between online and batch programs:

您可以以下列模式之一运行应用程序引擎程序：使用PeopleSoft进程计划程序进行批处理、使用PeopleCode函数联机或使用命令行手动运行。下表列出了在线程序和批处理程序的一些区别：

Online Execution	Batch Execution
Started by the CallAppEngine function from PeopleCode.	Started through PeopleSoft Process Scheduler.
Program runs quickly, synchronously, and at random times.	Programs run for longer amounts of time, asynchronously, and at scheduled times.
Potential for simultaneous runs.	Can be designed for parallel runs for performance.
Uses the online temporary table pool.	Uses the batch/dedicated temporary table pool.

Batch Programs Using PeopleSoft Process Scheduler

使用PeopleSoft进程调度器的批处理程序

The most typical run mode is batch. You invoke programs that run in this mode using PeopleSoft Process Scheduler or the Application Engine Process Request page. Batch mode is also referred to as an asynchronous run, meaning that it runs independently in the background. Application Engine runs on any operating system that Oracle supports as an application server. If your site uses an operating system that is not supported for Application Engine, you must run Application Engine programs on the application server.

最典型的运行模式是批处理。使用PeopleSoft进程计划程序或“应用程序引擎进程请求”页调用在此模式下运行的程序。批处理模式也称为异步运行，这意味着它在后台独立运行。应用引擎运行在任何操作系统上，甲骨文支持作为一个应用服务器。如果站点使用应用程序引擎不支持的操作系统，则必须在应用程序服务器上运行应用程序引擎程序。

To run Application Engine programs on the batch server, you must install BEA Tuxedo. This condition applies to both UNIX and Microsoft Windows NT batch servers. If you run your batch server on the same server machine as your application server, then the application server and the batch server can share one BEA Tuxedo installation. If your batch server is separate from your application server, then you must install BEA Tuxedo on your batch server.

要在批处理服务器上运行应用程序引擎程序，必须安装BEA Tuxedo。这个条件-适用于UNIX和微软Windows NT批处理服务器。如果你的批处理服务器运行在同一个服务器机器作为您的应用服务器，那么应用服务器和批处理服务器可以共享oneBEA Tuxedo安装。如果您的批处理服务器与应用程序服务器是分开的，那么您必须在批处理服务器上安装BEA Tuxedo。

The TOOLBINSRV parameter in the PeopleSoft Process Scheduler configuration file determines where PeopleSoft Process Scheduler invokes an Application Engine program. For high-volume batch environments, specify the PS_HOME\bin\server\winx86 directory that exists on the same machine where the Application Engine program runs.

PeopleSoft Process Scheduler配置文件中的TOOLBINSRV参数确定PeopleSoft Process Scheduler在何处调用应用程序引擎程序。对于大容量批处理环境，请指定PS_HOME\bin\server\winx86目录，该目录与运行应用程序引擎程序的计算机相同。

Online Programs Using PeopleCode

使用PeopleCode的在线程序

Application Engine programs that run online are typically run from a page with the CallAppEngine PeopleCode function. Such online processes are synchronous, meaning that subsequent processes wait for the results. For instance, a page may be frozen until the online process returns the necessary results. With the CallAppEngine function, no Commit statements are issued. However, if you use the asynchronous online PeopleCode option, ProcessRequest, Commit statements are allowed.

联机运行的应用程序引擎程序通常从具有CallAppEngine PeopleCode函数的页上运行。这样的在线进程是同步的，这意味着后续进程等待结果。例如，页面可能会被冻结，直到联机进程返回必要的结果。使用CallAppEngine函数时，不会发出Commit语句。但是，如果使用异步联机PeopleCode选项ProcessRequest，Commit语句是允许的。

Manual Programs Using the Command Line

使用命令行手动程序

Usually, you use this mod only during testing or if you need to restart a program manually.

通常，您只在测试期间或需要手动重新启动程序时使用此mod。

Creating Process Definitions

创建进程定义

Select PeopleTools > Process Scheduler > Process Scheduler Processes  to access the Processes Process Definition page.

选择PeopleTools》进程计划程序》进程计划程序进程 以访问“进程-进程定义”页。

This example illustrates the fields and controls on the Processes - Process Definition page.

此示例说明了Processes-Process Definition页面上的字段和控件。

To use PeopleSoft Process Scheduler for starting Application Engine batch programs, create a process definition for each program. Running Application Engine programs is similar to running any COBOL or Structured Query Report (SQR) program that you typically invoke with PeopleSoft Process Scheduler. Use Application Engine as the generic process type definition. Each Application Engine program that you invoke using PeopleSoft Process Scheduler requires a unique process definition derived from the generic process type definition.

若要使用PeopleSoft进程计划程序启动应用程序引擎批处理程序，请为每个程序创建一个进程定义。运行应用程序引擎程序类似于运行通常使用PeopleSoft进程调度程序调用的任何COBOL或结构化查询报表（SQR）程序。使用应用程序引擎作为泛型流程类型定义。使用PeopleSoft Process Scheduler调用的每个应用程序引擎程序都需要从通用进程类型定义派生的唯一进程定义。

Note: When creating a process definition based on the Application Engine process type definition, the process name you assign must match your Application Engine program name exactly.

附注：基于应用程序引擎进程类型定义创建进程定义时，分配的进程名称必须与应用程序引擎程序名称完全匹配。

Listing Process Definition Parameters

列出流程定义参数

Select PeopleTools > Process Scheduler > Process Scheduler Processes > Process Definition Options to access the Processes - Process Definition Options page.

选择PeopleTools>进程计划程序>进程计划程序进程>进程定义选项以访问进程-进程定义选项页。

This screenshot shows the Processes - Process Definition Options page.

此屏幕截图显示了流程-流程定义选项页面。

Use this page to list parameters. The complete parameter list is:

使用此页面列出参数。完整的参数列表为：

• -ct %%DBTYPE%%
• -cd %%DBNAME%%
• -co %%OPRID%%
• -cp %%OPRPSWD%%
• -r %%RUNCNTLID%%
• -i %%INSTANCE%%
• -ai %%PRCSNAME%

Starting Programs with the Application Engine Process Request Page

使用“应用程序引擎进程请求”页启动程序

You also can start an Application Engine program by using the Application Engine Process Request page. Using this request page enables you to specify values and parameters in addition to those that appear within PeopleSoft Process Scheduler process definitions.

您还可以使用“应用程序引擎进程请求”页面启动应用程序引擎程序。使用此请求页面，除了PeopleSoft流程计划程序定义中出现的值和参数外，您还可以指定值和参数。

Most users start Application Engine programs from an application-specific request page using PeopleSoft Process Scheduler. A systems expert or power user may, at times, need to create custom process requests that require multiple programs to perform parallel processing or that need to set specific, initial values in a state record. You might use the Application Engine process request page for one of these cases.

大多数用户使用PeopleSoft Process Scheduler从应用程序特定的请求页启动应用程序引擎程序。系统专家或高级用户有时可能需要创建自定义流程请求——需要多个程序执行并行处理，或者需要在状态记录中设置特定的初始值。对于其中的一种情况，您可以使用Application Engine进程请求页面。

Note: Generally, if seed data or other Application Engine request settings are required for a particular program, the application-specific request page has SQL executables that do the work that is transparent to the user. Typically, no user should invoke programs from the generic process request page. Use this page for internal testing and as a basis for designing program-specific request pages.

附注：通常，如果特定程序需要种子数据或其他应用程序引擎请求设置，则特定于应用程序的请求页具有执行对用户透明的工作的SQL可执行文件。通常，任何用户都不应该从通用进程请求页面调用程序。使用此页面进行内部测试，并作为设计特定于程序的请求页面的基础。

Tables Used in the Process Request Page

“处理请求”页中使用的表

The Application Engine process request page inserts values into the following tables:

应用程序引擎进程请求页面将值插入到以下表中:

• AEREQUESTTBL

Contains all of the values that appear on the page except those in the Parameters group box.

包含页面上显示的所有值，但“参数”组框中的值除外。

• AEREQUESTPARM

Includes only initial state record values specified in the Parameters group box, if needed.

如果需要，仅包括在“参数”组框中指定的初始状态记录值。

Note: Inserting a row in either of the Application Engine request tables is not required to run an Application Engine program. This change is a key difference between Application Engine versions prior to PeopleTools 8, where a row in Application Engine request tables is required to start a program, regardless of how it is invoked. The run control ID is available to your program using %RunControl, whether or not a row is inserted into the AEREQUESTTBL table.

附注：运行应用程序引擎程序不需要在任一应用程序引擎请求表中插入行。这个变化是PeopleTools 8之前的应用程序引擎版本之间的关键区别，在PeopleTools 8之前，应用程序引擎请求表中的一行是启动程序所必需的，而不管它是如何被调用的。无论是否将行插入AE REQUEST BL表中，程序都可以使用%RunControl使用运行控制ID。

You need to use the Application Engine Request page to invoke Application Engine and insert a row into the Application Engine request records only if you need to perform any of the following tasks:

仅当需要执行以下任何任务时，才需要使用“应用程序引擎请求”页调用应用程序引擎并将行插入到应用程序引擎请求记录中:

• Insert initial values into the state records associated with a particular program.
• 在与特定程序相关联的状态记录中插入初始值。
• Set an as-of date for the Application Engine program to perform retroactive processing.
• 设置应用程序引擎程序执行追溯处理的截止日期。
• Set a non-default market for the program.
• 为程序设置一个非默认市场。
• Set up a temporary table image to use if you are submitting a PeopleSoft EPM process request that performs parallel processing. Refer to PeopleSoft EPM application documentation for details.
• 如果您正在提交PeopleSoft EPM过程请求-执行并行处理，请设置一个临时表映像。详情请参阅PeopleSoft EPM应用文档。

Note: Entries in the AEREQUESTTBL table do not have any effect on Application Engine programs called from PeopleCode using the CallAppEngine function.

附注：AE REQUEST BL表中的项对使用CallAppEngine函数从PeopleCode调用的应用程序引擎程序没有任何影响。

Application Engine Requests

应用程序引擎请求

Select PeopleTools > Application Engine > Submit AE Process Requests to access the Application Engine Request page.

选择PeopleTools>应用程序引擎>提交AE处理请求 以访问应用程序引擎请求页面。

This example illustrates the fields and controls on the Application Engine Request page. You can find definitions for the fields and controls later on this page.

此示例说明“应用程序引擎请求”页上的字段和控件。您可以在本页稍后找到字段和控件的定义。

Field or Control	Description
Process Origin	Displays where the program was invoked, from PeopleSoft Process Scheduler, from the command line, and so on.
Process Instance	Displays the process instance assigned to the previous program run.
Status	Displays the status of the last program run, whether it is successful, pending, and so on.
Process Frequency	Specify how long a particular process request will remain active or valid: Always: Select to run the process request as needed. Once: Select if a process request is a one-time-only request. Don’t: Select to disable a process request so that no one invokes it and potentially corrupts data.
As Of Date	If you are requesting retroactive processing, specify the appropriate as of date.
Bind Variable Name	Enter the appropriate field or bind variable for which you are inserting a value.
Value	Enter the initial value that you want to set for the specified field.

Using PeopleCode to Invoke Application Engine Programs

使用PeopleCode调用应用程序引擎程序

To call a specific Application Engine program from a page using PeopleCode, use the CallAppEngine function in SavePreChange or SavePostChange PeopleCode. The basic syntax for CallAppEngine is:

若要使用PeopleCode从页调用特定的应用程序引擎程序，请使用SavePreChange或SavePostChange PeopleCode中的CallAppEngine函数。CallAppEngine的基本语法为:

CallAppEngine(applid[, statereclist, processinstance, allowcommit]

Note: The RemoteCall function is no longer valid for invoking Application Engine programs in

PeopleCode. However, the RemoteCall function still applies to calling other COBOL functions. If you do not convert the RemoteCall PeopleCode that previously called an Application Engine program to use the new function, an error message appears.

附注：RemoteCall函数不再适用于调用PeopleCode中的应用程序引擎程序。但是，RemoteCall函数仍然适用于调用其他COBOL函数。如果不转换以前调用应用程序引擎程序的RemoteCall PeopleCode以使用新函数，则会出现错误消息。

Use CallAppEngine if the program you are invoking is a quick process. Because the process is synchronous, users must wait for any process invoked by CallAppEngine to complete before starting another process. If the called program causes an unreasonable delay, then use another alternative, such as the ScheduleProcess PeopleCode function.

如果您正在调用的程序是一个快速的进程，请使用CallAppEngine。由于进程是同步的，因此用户必须等待CallAppEngine调用的任何进程完成，然后才能启动另一个进程。如果被调用的程序导致了不合理的延迟，那么使用另一种替代方法，比如ScheduleProcess PeopleCode函数。

Use CallAppEngine when you have a complex, SQL-intensive business process that must run in batch and online, or the process requires the use of dedicated temporary tables. If this is not the case, you are usually better off writing the entire program in native PeopleCode. If you have written logic in PeopleCode, presumably for online execution, and you want to reuse it in a batch program, you may be forced into row-by-row processing. Design the batch logic first and then decide whether to have a separate online version or reuse the batch code using CallAppEngine. Consider the trade-off between code reuse and performance. It is inherently more difficult, but not impossible, to develop a common solution that performs adequately in both batch and online environments.

如果您有一个复杂的SQL密集型业务流程，且该流程必须以批处理方式联机运行，或者该流程需要使用专用的临时表，请使用CallAppEngine。如果不是这种情况，通常最好用本机PeopleCode编写整个程序。如果您已经用PeopleCode编写了逻辑，假设是为了在线执行，并且您希望在批处理程序中重用它，那么您可能会被迫进行逐行处理。首先设计批处理逻辑，然后决定是使用单独的联机版本还是使用CallAppEngine重用批处理代码。考虑代码重用和性能之间的权衡。开发一个在批处理和在线环境中都能充分执行的通用解决方案本质上更困难，但并非不可能。

If you use CallAppEngine within an Application Engine PeopleCode step, you must do so carefully and selectively. See the “Application Engine Considerations” section in “CallAppEngine” (PeopleCode Language Reference). If you need to call an Application Engine program from another Application Engine program, you can also use the Call Section action.

如果您在应用程序引擎PeopleCode步骤中使用CallAppEngine，则必须谨慎且有选择地这样做。请参阅"CallAppEngine"（PeopleCode Language Reference）中的"应用程序引擎注意事项"部分。如果需要从另一个应用程序引擎程序调用一个应用程序引擎程序，也可以使用Call Section操作。

Do not use CallAppEngine to control the commit operation. Programs called with CallAppEngine are embedded within a larger unit of work defined by the page trigger, such as a page save.

不要使用CallAppEngine来控制提交操作。使用CallAppEngine调用的程序嵌入在由页触发器定义的更大的工作单元中，如页保存。

However, the allowcommit option allows you to specify whether intermediate commits should be allowed in an online Application Engine program. Online Application Engine programs run in the context of application server. When the intermediate commits are enabled, the transactions that are in the context of the Application Engine program up to that commit are committed. None of the other transactions that are in the same Jolt request and are outside the context of the Application Engine program are committed. This is achieved by the use of a secondary connection to the database. Therefore, secondary connection must be enabled for this application server domain using the database flags (DbFlags) in the application server configuration file. Note that the secondary connections are enabled by default. If the secondary connection to the database is disabled and CallAppEngine is invoked with allowcommit set to True, the functionality will fall back to the default where all transactions are committed only at the end of an Application Engine program.

但是，allowcommit选项允许您指定在联机应用程序引擎程序中是否允许中间提交。在线应用程序引擎程序在应用程序服务器的上下文中运行。当启用中间提交时，将提交该提交之前应用程序引擎程序上下文中的事务。不会提交同一Jolt请求中以及Application Engine程序上下文之外的任何其他事务。这是通过使用到数据库的辅助连接来实现的。因此，必须使用应用服务器配置文件中的数据库标志（DbFlags）为此应用服务器域启用辅助连接。请注意，默认情况下启用辅助连接。如果禁用到数据库的辅助连接，并且在allowcommit设置为True的情况下调用CallAppEngine，则该功能将退回到默认状态，即仅在应用程序引擎程序结束时提交所有事务。

Important! There is no mechanism to rollback or clear the transactions that have been committed on behalf of online Application Engine programs. In case of an error or unexpected program termination, you are responsible for rolling back transactions if necessary.

重要的！没有机制来回滚或清除已代表联机应用程序引擎程序提交的事务。如果发生错误或意外的程序终止，您有责任在必要时回滚事务。

Note: Online PeopleCode that calls CallAppEngine should be set to run on the application server. You encounter performance issues if you run PeopleCode on the client in a three-tier configuration because every SQL statement that Application Engine issues must be serialized and then sent to the application server to be run.

注意：调用CallAppEngine的Online PeopleCode应设置为在应用服务器上运行。如果在三层配置的客户端上运行PeopleCode，则会遇到性能问题，因为Application Engine发出的每个SQL语句都必须序列化，然后发送到应用服务器上运行。

Related Links

“CallAppEngine” (PeopleCode Language Reference)

“DbFlags” (System and Server Administration)

相关链接"CallAppEngine""DbFlags"（系统和服务器管理）

Using the Command Line to Invoke Application Engine Programs

使用命令行调用应用程序引擎程序

You might invoke an Application Engine program through the command line to: 您可以通过命令行调用应用程序引擎程序以:

• Restart

重新启动

When a program abends, a system administrator might restart the program using the command line. If needed, you can locate all of the specific program and process information from Process Monitor in the Process Request Detail dialog box. Normally, users or system administrators perform a restart from the Process Monitor.

当程序中止时，系统管理员可能会使用命令行重新启动程序。如果需要，您可以在Process Request Detail对话框中的Process Monitor中找到所有特定程序和流程信息。通常，用户或系统管理员从进程监视器执行重新启动。

• Develop or test
• 开发或测试

Many developers include the command line in a batch file to launch a program they are developing or testing. This way, they can quickly execute the batch file as needed. This method also enables separation of development of the application program from its associated pages.

许多开发人员在批处理文件中包含命令行以启动他们正在开发或测试的程序。这样，他们就可以根据需要快速执行批处理文件。这种方法还使应用程序的开发与其相关的页面分离。

• Debug
• 调试

To debug a program running on the server, you can sign into the server (using telnet, for example) and invoke the program from the command line.

要调试服务器上运行的程序，可以登录到服务器（例如使用telnet）并从命令行调用程序。

To start an Application Engine program from the command line, you must specify the Application Engine executable (PSAE.EXE) followed by the required parameters, as shown in this example:

要从命令行启动应用程序引擎程序，您必须指定应用程序引擎可执行文件（PSAE.EXE），后跟必需的参数，如以下示例所示:

            psae -CT dbtype -CS server -CD database_name -CO oprid -CP oprpswd

 -R run_control_id -AI program_id -I process_instance -DEBUG (Y|N)

 -DR (Y|N) -TRACE <trace> value -DBFLAGS<flags> value -<TOOLSTRACESQL> value

 -TOOLSTRACEPC value -OT outtype -OF outformat -FP filepath

Or, if your command line options are stored in a text file, you can enter:

或者，如果您的命令行选项存储在文本文件中，您可以输入：

            psaeoptfilename

Note: For Microsoft Windows and UNIX servers, you must set the PS_SERVER_CFG environment variable before you invoke an Application Engine program from the command line. PS_SERVER_CFG must contain the fully qualified name of a correctly configured Process Scheduler PSPRCS.CFG file. When Application Engine runs from the command line, it resolves %PS_SERVDIR% to the value of the environment variable PS_SERVDIR instead of the parent directory of a Process Scheduler configuration.

附注：对于微软Windows和UNIX服务器，必须在从命令行调用应用程序引擎程序之前设置PS_SERVER_CFG环境变量。PS_SERVER_CFG必须包含正确配置的进程调度程序PSPRCS.CFG文件的完全限定名称。当应用程序引擎从命令行运行时，它将%PS_SERVDIR%解析为环境变量PS_SERVDIR的值，而不是Process Scheduler配置的父目录。

Command Line Options

Field or Control	Description
-CT	Specify the type of database to which you are connecting.  Values are ORACLE, MSSQL (Microsoft SQL Server), and DB2ODBC (Db2 for z/OS).
-CS	For platforms that require a server name as part of their signon, enter the appropriate server name. This option affects Microsoft SQL Server. However, for Microsoft SQL Server,  this option is valid but not required.
-CD	Enter the name of the database to which the program will connect.
-CO	Enter the user ID of the person who is running the program.
-CP	Enter the password associated with the specified user ID. Note: Password may also be passed in encrypted form.
-R	Enter the run control ID to use for this run of the program.
-AI	Specify the Application Engine program to run.
-I	Required for restart, enter the process instance for the program run. The default is 0, which means Application Engine uses the next available process instance.
-DEBUG	This parameter controls the Debug utility. Enter Y to indicate that you want the program to run in debugging mode or enter N to indicate that you do not.
-DR	This parameter controls restart disabling. Enter Y to disable restart or enter N to enable restart.

-TRACE	To enable tracing from the command line, enter this parameter and a specific trace value. The value you enter is the sum of the specific traces that you want to enable. Traces and values are: 1: Initiates the Application Engine step trace. 2: Initiates the Application Engine SQL trace. 128:: Initiates the Application Engine timings file trace, which is similar to the COBOL timings trace. 256: Includes the PeopleCode detail timings in the 128 trace. 1024: Initiates the Application Engine timings table trace,  which stores the results in database tables. 2048: Initiates the database optimizer explain, writing the results to the trace file. This option is supported only on Oracle and Microsoft SQL Server. 4096: Initiates the database optimizer explain, storing the results in the Explain Plan table of the current database. This option is supported only on Oracle, Db2, and Microsoft SQL Server. For example, to enable the 1, 2, and 128 traces, you would enter 131,the sum of 1, 2, and 128. To indicate that you do not want any traces, enter0. If you do not explicitly enter0,  Application Engine uses the trace value set in PeopleSoft Configuration Manager. 8192: Sets a trace for PeopleSoft Integration Broker transform programs. 16384: Initiates the statement timings trace but stores the results in the PS_AE_TIMINGS_LG and PS_AE_TIMINGS_ DT tables.
-DBFLAGS	To disable %UpdateStats meta-SQL construct, enter 1.
-TOOLSTRACESQL	Enable a SQL trace.
-TOOLSTRACEPC	Enable a PeopleCode trace.

Field or Control	Description
-OT	(Optional) Initialize the PeopleCode meta-variable %OutDestType (numeric). PeopleCode example of %OutDestType: &ProcessRqst.OutDestType = %OutDestType ⇒ ;
-OF	(Optional) Initialize the PeopleCode meta-variable %OutDestFormat (numeric). PeopleCode example of %OutDestFormat: Query.RunToFile(Record QryPromptRecord, ⇒ %OutDestFormat);
-FP	(Optional) Initialize the PeopleCode meta-variable %FilePath (string). PeopleCode example of %FilePath: If All(%FilePath) Then    &FILENAME = %FilePath | &FILENAME; &MYFILE = GetFile(&FILENAME, "E", %FileP⇒ ath_Absolute); Else   &MYFILE = GetFile(&FILENAME, "E", %Fil⇒ ePath_Relative); End-If;
optfilename	If you submit a file to Application Engine as the first parameter in the command line, Application Engine reads the contents of the file and interprets the contents as if it were parameters entered on the command line. This option is intended mainly for the Microsoft Windows or UNIX Process Scheduler server environment. For example, you might enter psae $temp/myparmfile.txt. Note: For security reasons, after Application Engine interprets the contents of the parameter file, it immediately deletes the file.
Field or Control	Description
–NOCOMMIT	(Optional) Set Y/N values for this parameter. If it is set to “Y” then it will not commit any changes to database. Note: You can only use this parameter in a developer environment. Do not use it in a product environment.