98396640 PPF Developer Docu

SAP®

Internal and Confidential Developer Handbook

Release: 6.40Author:Bollmeier, Thomas;Drollinger, Dirk

Parallel Processing Framework

Developer Handbook

History

Version Status Date

1.0 Released 6.40

Storage place of this documents: \\...

© 2012 SAP AGNeurottstr. 16D-69190 Wall-dorf

Title: Parallel Processing FrameworkVersion: 6.40Date: 6.40

Page 1 of 34

PPF Developer Handbook Internal and Confidential

Content1 Glossary ......................................................................................................... 4 2 Overview ........................................................................................................ 4 2.1 General Functions ....................................................................................................... 5

2.1.1 Events ....................................................................................................................... 6

2.2 Architectural Context ................................................................................................... 8 3 Implementation Guide ................................................................................... 9 3.1 Step by Step Instructions ............................................................................................ 9

3.1.1 Application Type and Object Type ........................................................................... 9

3.1.2 Logical Definitions .................................................................................................... 9 3.1.2.1 Package Formation Category ............................................................................. 10 3.1.2.2 Restart Procedure ............................................................................................... 11

3.1.3 Global Application Parameter ................................................................................ 13

3.1.4 Events / Callback Modules ..................................................................................... 13 3.1.4.1 0205 – Create Package Templates .................................................................... 14 3.1.4.2 1000 – Initialize Package .................................................................................... 15 3.1.4.3 1100 – Selection per Range ............................................................................... 16 3.1.4.4 1200 – Selection for Known Object List .............................................................. 17 3.1.4.5 1300 – Edit Objects ............................................................................................. 17

3.1.5 Start Report ............................................................................................................ 18

3.2 Configuration (Customizing) ...................................................................................... 19

3.2.1 Developers (Application) ........................................................................................ 19

3.2.2 User (Customer) ..................................................................................................... 20

3.3 Enhancement Options ............................................................................................... 21 3.3.1.1 0BANK010 – Create Work Packages ................................................................. 21 3.3.1.2 0BANK011 – Specify Job Distribution ................................................................ 21

3.4 Complex Scenarios ................................................................................................... 21

3.4.1 Multi-Step Processing ............................................................................................ 21

3.4.2 Special Parameters for Package Formation .......................................................... 22

3.4.3 Object Locks – Dependencies Between Application Types .................................. 22 3.4.3.1 Set Locks – BANK_MAP_PP_LOCKS_SET ...................................................... 23 3.4.3.2 Read Locks – BANK_MAP_PP_LOCKS_GET_MLT ......................................... 24 3.4.3.3 Delete Locks – BANK_MAP_PP_LOCKS_RELEASE ....................................... 25 4 Documentation for Central Interfaces ........................................................ 26 4.1 BANK_MAP_PP_START .......................................................................................... 26 5 Examples ..................................................................................................... 28 6 Tips und Tricks ............................................................................................ 28 6.1 Debugging ................................................................................................................. 28

6.1.1 Synchronous Start in Dialog Mode ........................................................................ 28

6.1.2 Parameters BANK_JC_DBG_MODE in the User Data (from release 6.40) ......... 29 7 Other Important Aspects ............................................................................ 29 7.1 Error Log .................................................................................................................... 29

7.2 BANK_PP_SETTINGS .............................................................................................. 30



Page 2 of 34


7.3 Job Distribution .......................................................................................................... 30

7.3.1 Degree of Parallelization ........................................................................................ 30

7.3.2 Distribution .............................................................................................................. 31

7.4 Repeat – Retry - Restart ........................................................................................... 31 8 Tools for Developer Support ...................................................................... 33 8.1 Generation of Module Holders .................................................................................. 33

8.2 Demo Application ...................................................................................................... 33 9 Index 34



Page 3 of 34


1 Glossary

English Term English Abbrev.

German Term

German Abbrev.

Definition

Application Anwendung In this document, this signifies the user of the PPF.

Application Type

Anwen-dungsart

The application type identifies an application that is using the PPF

End of Day Processing

Tagesende-verarbeitung

TEV Identifies programs or processes that:

• Process mass data

• Run in batches

• Run at the end of a post-ing day

Parallel Pro-cessing Framework

PPF Parallel Pro-cessing Framework

PPF Name of the tool described here; synonyms are parallelization or parallel processing

Resub-mis-sion

Restart of a mass run that was canceled or had individual (busi-ness) errors

2 OverviewThe Parallel Processing Framework (PPF) enables applications to process mass data efficiently. Performance is improved by processing the data in several processes. The framework takes over all control functions but the application must prepare the business logic.



Page 4 of 34


2.1 General Functions

The basic principle of the PPF is to divide up processing into individual processing steps or events, in which business or application-specific logic is run. The application prepares this logic in function modules (“callback modules”).From a technical point of view, each event is optional. The absence of an event does not lead to an error. Section 2.1.1 describes a suggested combination of events.

The prerequisite for the implementation of the PPF is that the data to be processed is stored in the database This does not apply for application processes that create data.

The application is identified by the PPF using a unique application type, which must be en-tered in Customizing and transferred when the Framework is started. You enter the relevant callback modules for the application type in Customizing.

To start the PPF from the application, you call up the function module BANK_MAP_PP_START.

You can divide processing into three areas:• Preparation• Parallel processes (threads / jobs)• End processing

From the main process’s point of view, the parallel process run asynchronously in batch jobs. This means that:

• It is usually possible to transfer data to this process using database tables or persis-tent saves only.

• The callback functions assigned to this area cannot access any data that the application stored previously in global areas.



Page 5 of 34


2.1.1 Events

The following overviews shows the assignment of the events described above to the three processing areas. Event 205 (in bold type) is compulsory. The events in the middle section are executed in a loop for each package of a parallel process.



Page 6 of 34

Preparation

0205: Create Package Templates

0206: Save Param. for Packages

0100: Start Mass Run

0120: Set Appl. Parameters

0160: Checks Before Start

Parallel Process(Jobs)

0110: Get Appl. Parameters

1400: Start Parallel Process

1000: Initialize Package

1100: Selection per Range

1200: Selection for Obj.List

1260: Check Object Locks

1270: Delete Obj. from Appl. Data

0140: Compare Parameters

1300: Process Objects

1410: End of Parallel Process

1350: End of Package

Callback Function Modules

Run Data


Diagram 1: Events

As you can see from diagram 1 and as mentioned above, the only compulsory event is event 0205. However, parallel processing is of very little use without processing (event 1300). For an implementation to serve any purpose, it should contain at least the following events:

• 0205 – Create Package Templates • 1000 – Initialize Package• 1100 – Selection per Range or• 1200 – Selection for Known Object List• 1300 – Edit Objects

Events 1100 or 1200 (selection) could also be completed at the start of event 1300. We rec-ommend that you execute them separately however, so that the events can be maintained and monitored. If an application does not require data selection, you can leave out these events as well.



Page 7 of 34

End Processing

0300: End of Mass Run

0207: Delete Package Parameters

0130: Delete Appl. Parameters


Run Data


2.2 Architectural Context

The following graphic shows an overview of the structure of the PPF and integration by the application.

Graphic 2: Architecture



Page 8 of 34

PP Framework

Application

Appl. Data

Appl.Cat.

Customizing

Process Layer

Start Report


Basis Job Control

Mass Run Layer

Process Events

Process Layer

Process Data

WorklistData

Run Data


3 Implementation GuideDescription of the procedure for integrating and using the tool. This “cookbook” describes what must be done to integrate the tool in the application.

3.1 Step by Step Instructions

The procedure for integration of PPF has four steps:

1. Preparationsa. Application typeb. Object typec. Package formation categoryd. Resubmission yes / noe. (Lock procedure; see section 3.4.3 Object Locks)

2. Definition of structure for global application parameters

3. Implementation of callback modules

4. Implementation of start report by calling up the module BANK_MAP_PP_START

3.1.1 Application Type and Object Type

The definition of the application type in Customizing for the PPF is an organizational activi-ty.

You must enter the application type, as the callback functions for the applications are creat-ed under this key (as described above).

You only need to assign the object type if you want to enable object list management (pack-age formation) or resubmission.

3.1.2 Logical Definitions

The definitions described below influence the design of some callback modules. They do not necessarily contain or require technical transactions, rather they are a note to the appli-cation developer to clarify the required procedure before the corresponding modules are im-plemented.



Page 9 of 34


3.1.2.1 Package Formation Category

The package formation category determines the procedure used to divide the objects to be processed into packages.

Affected events:

• 0205 – Create package templates (poss. 206, 207)• 1000 – Initialization of package• 1100 – Selection per range• 1200 – Selection for object list / resubmission

The following options exist for package formation:• Range formation

o Specification of range limits from DBo Calculation of range limits

• Object list

You can also use special attributes.

Specification of Range Limits from DB

If the objects cannot be divided into ranges using the calculation described above, you can divide them using the objects in the database or using business criteria.In this case, the range limits are specified for each case in the callback module at event 0205. The tool stores them for each package. The application module at event 1000 then transfers the specified ranges for each package from the PPF and stores them in global vari-ables.As before, the objects are retrieved from the database in the callback module at event 1100 (as described above).

Calculation of Range LimitsIn this procedure, the callback module only returns the number of packages at event 205. The range limits for each package are defined in the callback module at event 1000, and the values are stored in the global variables of the application.At event 1100, the relevant application module can then get the objects that belong to the range from the database and store them in a global data area.

This procedure is used if the objects to be processed are subdivided into ranges using an al-gorithm.



Page 10 of 34


Example:The unique key of the objects is a GUID. You can distribute the existing object keys equally across the complete GUID area from 0000000000000000 to FFFFFFFFFFFFFFFF to calcu-late corresponding ranges.

Object List

In this procedure, the objects are selected for each package according to business criteria. However, the callback module does not transfer a range with upper and lower limits to the PPF at event 0205, rather it transfers a list of specific objects. The PPF stores these objects for every package in a DB table.For this procedure, no object selection is necessary at initialization event 000.Event 1200 is the selection event in this case. The relevant callback module of the applica-tion receives the object list that is valid for the current package. It can then get the relevant data from the database and store it in a global data area.This procedure is used automatically for restarted runs, as the objects are from the worklist of the first run and are known already.

Special Attributes

The application may want to use attributes in addition to those described in the procedure above to construct the worklist, i.e. to select the objects for each package. You can do this using the export parameter E_STR_PACKPARAM in the callback module at event 0205. The attributes are then returned to the application at event 1000.For example, you can use a list of bank posting areas or products to further restrict a range of accounts.

For more information, see section 3.4.2.

3.1.2.2 Restart Procedure

The application must decide whether it is possible to restart canceled runs. To restart a can-celed run, the application must flag the relevant packages, and the thus whole run, by confirming the objects with the status “RESTART“ to the PPF at event 1300. De-pendent on how the application processes the objects, the application must either confirm the status of each object, or flag the package by confirming a dummy object with the status “RESTART”. To help with the decision, you can use the following rule of thumb for the rollback:

• The application executes rollback itself if the package has errors, which means either all or no objects in a package are processed No status for object



Page 11 of 34


• The application does not execute rollback if the package has errors, which means that the “good” objects are in the database Individual status must be confirmed to enable restart of the incorrect objects

• Application wants to restart the exact package (for example, with exactly the same range limits), but does not want to confirm individual objects Confirm a dummy object.

To manage the status of individual objects, you must have switched on this option in Cus-tomizing for the PPF.

The possible scenarios are described below:

No Restart

• Canceled runs are not restarted, rather new start is made.• The application does not need to manage any status information about the processed

objects and packages

“Normal Restart”

• Canceled runs can be restarted• The application returns status information about each object to the PPF• The PPF flags individual packages that have incorrect objects as being incorrect• For restarted runs, the list of objects to be processed in each package is transferred to

the application

Restart Without Object Status

• Canceled runs can be restarted• The application returns a dummy object with the status “incorrect” for each

incorrect package, so that the package is flagged for restart• Incorrect packages can be reprocessed using your selection values, for example

range limits, without having to enter a status for each individual object• After the successful run, the dummy object must be returned with the status

“completed“.

If status values are saved for each object, the change to the status of the objects should be made in the same LUW as the change to the object itself. If the application does not execute its own commits, they are executed by the PPF. This is the recommended method.If the application must trigger a commit in a package, it must first use the module BANK_MAP_PP_CONFIRM_OBJECTS to confirm the status to the PPF of the objects that have been processed already.



Page 12 of 34


3.1.3 Global Application Parameter

If the application wants to transfer data from your start report to your callback modules us-ing the PPF without going via a database table, a “global application parameter” can be used. This is a data structure that is transferred to the PPF when you call up the PPF start module BANK_MAP_PP_START. The PPF then transfers the data to the application at cer-tain events.

Usually, the data from the selection screen of the start report is transferred in the structure to the application. The data could be criteria for package creation, such as the posting area, product, or number of packages.Below is an example of a structure for the parameters of the application “accountsettlement“.

Field Category DescriptionMASSRUN_ID BANK_DTE_MR_MASS-

RUN_IDInternal identification for mass runs- technical ID

SELECT_PARAMS IBKKM10 BCA: Additional parameter for calling up account settlement

RNG_SETTLEMENT_TYPE BCA_RNG_SETTLE-MENT_TYPE

Range table type for settlement type

TAB_BPARE BCA_TAB_BPARE Table type for bank posting areaTAB_PRODINT BCA_TAB_ACBAL_PROD

_SEL_OPTIONSelection table for settlement of sev-eral products

PRODTYPE FIPR_PRODTYPE Product categoryCNT_GUID_RANGES BCA_DTE_ACBAL_CNT_

GUID_RANGESNumber of packages for parallel pro-cessing

3.1.4 Events / Callback Modules

The following describes the five most important obligatory events. The application must provide modules for these events.



Page 13 of 34


3.1.4.1 0205 – Create Package Templates

At this event, the application must specify the method for package creation (the "package template“).

Parameter Type MeaningI_APPLCATG BANK_DTE_PP_PAAPPLCATG Application type

I_STR_PARAM Global application parameter

I_STR_PACKAGE_KEY BANK_STR_PP_PACKAGEKEY Key for package template

E_LIMIT_HIGH BANK_DTE_PP_OBJNO Upper limit for package

E_LIMIT_LOW BANK_DTE_PP_OBJNO Lower limit for package

E_TAB_OBJKEY BANK_TAB_OBJKEY Object list

E_CNT_PACKAGES BANK_DTE_PP_CNT_PACKAGES Number of packages

E_STR_PACKPARAMSpecial application parameters for package

E_FLG_NO_PACKAGE XFELD

E_PACKDEFCATG BANK_DTE_PP_PACKDEFCATG

NOT_FOUND Exception Package no longer exists (obsolete)

FAILED Exception Error

Implementation Notes

• This event is not executed for a restart.• The PPF calls up the module in a loop until the export parameter e_flg_no_package

is set or the exception FAILED is triggered. An exception is made for package for-mation category 3 (calculation of range limits), for which the module returns the number of packages and is called up once only.

• If the flag e_flg_no_package is set, no more packages exist. It replaces the exception NOT_FOUND, which still exists in the module interface for compatibility reasons.

• The exception FAILED indicates that an error occurred during formation of the package template.

• You can define a package template by specifying a range, a list of correct objects, or the number of packages (see above: Package formation category). The relevant range limits E_LIMIT_LOW / E_LIMIT_HIGH, object list E_TAB_OBJKEY, or number of packages E_CNT_PACKAGES must be returned.



Page 14 of 34


Enhancements

• If the application requires parameters for each package template in addition to the global parameter I_STR_PARAM, they can be returned in the structure E_STR_PACKPARAM. The structure of this export parameter must be exactly the same as the row structure of the table type in the Data Dictionary, which is defined in Customizing for package-related application data. The structure must contain the package template key, so that it is possible to use this key to access the parameters for the package during later processing. The current values for eachpackage are contained in the parameter I_STR_PACKAGE_KEY.

3.1.4.2 1000 – Initialize Package

This event is the first step in processing a package of work. The application gets all the pa-rameters that are required for the following processing steps - selection, checking and pro-cessing application data.

Parameter Type MeaningI_APPLCATG BANK_DTE_PP_PAAPPLCATG Application type

I_PROGN BANK_DTE_PP_PROGNName of program/report for application process

I_PROGDATE BANK_DTE_PP_PROGDATE Date of program run

I_PROGNO BANK_DTE_PP_PROGNO Sequential number of program run

I_CURRSTARTNO BANK_DTE_PP_RUNSTARTNOCurrent start number ofmass run = number of starts

I_XSIMULATION BANK_DTE_PP_XSIMULRUN Simulation indicator

I_CURRSTEPNO BANK_DTE_PP_STEPNO Current step number

I_STR_PARAM Global application parameter

I_STR_PACKAGE_KEY BANK_STR_PP_PACKAGEKEY Key of package template

I_STR_PACKATTR

I_LIMIT_LOW BANK_DTE_PP_OBJNO Lower limit

I_LIMIT_HIGH BANK_DTE_PP_OBJNO Upper limit

I_XRESTART XFELD Restart run

I_FLG_ABORTED XFELDCancellation in this package in previous start



Page 15 of 34



• The transferred parameters need to be stored in global data areas of the application for use at later events.

• The indicator I_XRESTART means that the current package has been processed once already. Object data exists already in the application tables in the database.

• You can use the key I_STR_PACKAGE_KEY to access application-specific data for package template, which was stored at the event 0205 – Create Package Templates .

• The parameter I_STR_PACKATTR contains a reference to application-specific data about the package template, which was stored later by the PPF rather than at event 205.

• At this event, you should delete the buffers of the application that contain the data for the objects of a work package.

Enhancements

• If there are dependencies between the objects being processed (for example, settlement of subordinate accounts for reference accounts), processing may be executed in several steps. Each step is processed in parallel. The step number I_CURRSTEPNO is required if the processing step is to be used to select the processing step. Example: Only subordinate accounts are selected from a package template in step 1, only the reference accounts are selected in step 2.

3.1.4.3 1100 – Selection per Range

Reading data for a work package.

Parameter Type MeaningE_TAB_OBJKEY BANK_TAB_OBJKEY Selected objects

NOT_FOUND Exception No objects found


• The selection criteria were transferred when the work package was started (event 1000) and should be available in the global database for the application.



Page 16 of 34


• The objects selected must be buffered in global data areas of the application for later processing.

• The selected objects can be returned in the table E_TAB_OBJKEY. They must be

converted from the application format to the format required for parallel processing. The function module BANK_API_PPOBJ_CONV can be used for the con-version.

3.1.4.4 1200 – Selection for Known Object List

This event is run instead of event 1100 if the objects to be processed are known already. This is the case if it is a restart run, or if the objects were specified already in a previous se-lection, such as event 205.

Parameter Type MeaningI_TAB_OBJKEY BANK_TAB_OBJKEY Selected objects

E_TAB_OBJKEY_NOT_VALID BANK_TAB_OBJKEY Invalid objectsE_TAB_OBJKEY_NEW BANK_TAB_OBJKEY New objects


• The objects transferred in the table I_TAB_OBJKEY are in the format valid for PPF. They must be converted into the correct format if they are to be processed by the ap-plication. This can be done using the function module BANK_API_PPOBJ_CONV.

• For a restart, it may be that the worklist of objects to be processed has changed. The changes must be communicated to the PPF by making entries in the two export tables. You can use the module BANK_API_PPOBJ_CONV to convert the objects into PPF format. The following two changes are possible:

o Some of the objects selected for the first start are no longer valid and cannot /should not be processed. The invalid objects must be returned to the PPF in the table E_TAB_OBJKEY_NOT_VALID.

o New objects have been added. PP control must be notified of the new objects using the export parameter E_TAB_OBJKEY_NEW.

3.1.4.5 1300 – Edit Objects



Page 17 of 34


Processing of objects specified in previous events for the current package.

Parameter Type MeaningE_TAB_STATUS_CHANGE BANK_TAB_PP_STATUS_CHANGE Selected objects

Implementation Notes• The processing status of the objects can be returned in the export table E_TAB_STA-

TUS_CHANGE. If you want to run a restart, return is obligatory. The following ta-ble shows all possible status values and effects.

Value Meaning Effect0 Selected1 Flagged for restart Object no longer processed in this run, package

flagged for restart2 Processing running in background3 Processing completed successfully Object deleted from the restart worklist4 Reset Object is reprocessed if the whole step is repeated5 Invalid Object deleted from the restart worklist6 Processing repeated directly The current package is repeated immediately

• Note the following when setting the status values:o Objects that have status 4 may sometimes lead to the whole level being

reprocessed (see section 3.4.1 ). The success of the restart also depends on the settings in Customizing (see below), where you can set the number of re-peat runs that are allowed.

o Objects that have status 6 lead to direct reprocessing of the whole package. You cannot enter an upper limit for the number of runs inCustomizing, which means that the package is reprocessed until no objects exist that have status 6.

o You must also set the status for the “good” objects (successfully processed), else it may lead to problems when repeating or restarting a run.

• During processing of this event, some applications must trigger Commit Work commands. To avoid inconsistencies in the status update, you must first confirm the status of the objects processed up to the Commit Work. To do this, you call up the module BANK_MAP_PP_CONFIRM_OBJECTS.

3.1.5 Start Report

From the application’s point of view, the start report is the starting point of a parallel mass run.You have the following options on the selection screen:

• Business criteria for package formation and data selection• Technical information for control of the PPF



Page 18 of 34


You start the PPF by calling up the function module BANK_MAP_PP_START (for interface, see section 4.1).

Important: The current version of the PPF predefines that an application log object is opened in the start report with the functions of the message class EMSG (package BMESSAGE). Also, the error messages that were triggered before the start of parallel processing are output directly or written to the job log, which can lead to immediate cancellation without the application retaking control. The PPF opens a log object in each of the parallel processes.

3.2 Configuration (Customizing)

Customizing for the PPF consists of three parts:• System settings – events and interfaces (can be changed only by those responsible

for PPF)• Application developers – event modules and technical settings for application type • User – customer settings for behavior of the PPF

3.2.1 Developers (Application)

You can make the Customizing settings for developers using the transaction BANK_CUS_PP. You can make the following entries:

• Application type and dependent entrieso Callback modules for the eventso Reason for lock (should no longer be used)o Technical settingso Supported lock owner sessions

• Object type with conversion modules

The technical settings have the following meanings:

• “All objects persistent“ forces the save of all selected objects to the DB, including those that have “initial“ status

• The value entered for “% postponed“ defines the highest permitted share of objects that can be postponed in relation to the total number of objects still to be processed



Page 19 of 34


• The “number of repeat runs“ defines how many times a step can be repeated for postponed objects

• “Application for BTE“ – the PPF enables you to use the BTE 0BANK010 to con-trol package formation. You must enter the application that is entered for the BTE in the table TPS34.

• The value entered for the “number of sequential repeat runs” defines whether ad-ditional runs are to be made in a sequential session once the ”number of repeat runs“ has been reached. If so, a batch job is created for processing.

Supported lock owner sessions are used to define the lock procedure. You can enter the following values for each application:

• Lock by application only – the owner of the locked object is the application (type), other runs of the same application can process the objects; RECOMMENDED!

• Lock by mass run only – the owner of the locked objects is the relevant run, only this run can process the objects

• No locks

This transaction is also used to maintain the entries for the events and the relevant interface parameters. This is done by the developers responsible for the PPF.

The similar transaction BANK_CUS_PPC exists for connecting customer application types.

3.2.2 User (Customer)

The customer has the following options for making settings and enhancements for the PPF:

• Transaction BANK_CUS_PPC – customer applicationso Customers can enter their own application types and relevant methods

• IMG or SM30/V_TBANK_PP_DISTR – define job distribution for each applicationo You can define the level of parallelization (the number of parallel jobs per

run) for each application. The default value is one job per run.• IMG – Customer settings for application types

o Corresponds to the “technical settings” above. The customer can make set-tings for his/her own applications as well as for the SAP applications. If both SAP and customer settings are made for a value, the PPF decides which set-ting has precedence as follows:

“All objects persistent” – Set indicator has precedence “% postponed“ – Minimum has precedence “Number of repeat runs“ – Maximum has precedence “Application for BTE“ – Only customer setting is relevant “Number of sequential repeat runs“ – Maximum has precedence

• IMG - Relevant locks for other application types



Page 20 of 34


o For each application type, the customer can define which other application types can prevent the start if canceled or active runs exist.

The first two points are described in detail in the previous section. Note the following when entering relevant locks for other application types:

• If nothing is entered for an application, all applications are relevant• The setting only affects applications that call these other application types during the

start checks. Unfortunately, it is not possible currently to identify these applications in Customizing.

3.3 Enhancement Options

1.1.1 BTEs

3.3.1.1 0BANK010 – Create Work Packages

Customers can implement this BTE to replace the standard routine for forming work pack-ages with their own logic. This is useful if the customer wants to divide objects into pack-ages using criteria not contained in the SAP standard.

3.3.1.2 0BANK011 – Specify Job Distribution

Customers can implement this BTE to overwrite the parallel job distribution executed by the PPF and to specify the server and server groups for scheduling the jobs.

3.4 Complex Scenarios

3.4.1 Multi-Step Processing

Some applications need to process their objects in two or three steps. In account settlement for Banking for example, the subordinate accounts are processed in the first step. The settlement results from this first step are then accessible for the settlement of the higher-level accounts, which is executed in a second step.

The application uses the parameter I_MAX_STEPNO when calling up the start module BANK_MAP_PP_START to notify the PPF of the number of steps that are to be processed. As it is not possible to define a callback module for every step, multi-step processing is a re-peat call of the application by specifying the current step number. The application must then separate the processing of each step in its modules.



Page 21 of 34


Processing of a new step is essentially the same as starting a new run, as new parallel pro-cesses are formed and executed in relevant batch jobs.The event 100 and the final processing events 300, 130 and 207 are run once per run only, rather than once per step.

3.4.2 Special Parameters for Package Formation

In addition to “normal” package formation, it is also possible to use additional parameters to define special attribute values for each package. You can save these parameters either in your own database table or using the PPF. The procedure is as follows:

• Create a structure in the DDIC that contains the additional attributes. The key of the structure must contain the package key to make it possible to read the attributes of each package later. To do this, you can include the structure BANK_STR_PP_PACK-AGEKEY

• Create a relevant table type in the DDIC

• Enter the table type in PPF Customizing for the application type:BANK_CUS_PP->Application Type->Parameter Type

• At event 0205, transfer the created structure with the relevant attribute values in ex-port parameter E_STR_PACKPARAM to the PPF for each package

• At event 1000, the PPF transfers the relevant parameters for each package to the ap-plication

3.4.3 Object Locks – Dependencies Between Application Types

This topic deals with the interaction of different mass runs when errors and cancellations oc-cur, both for different runs of the same application type and different runs of different appli-cation types.The use of object locks should ensure that the processing of objects by one run must be completed before they can be processed by subsequent or dependent runs. To make this pos-sible for several runs or different application types, you must make some cross-application settings:

• Which application types depend on each other?o Which application type sets locks?o Which application type reads locks?

• Which objects are locked?



Page 22 of 34


You can define the other application types on which each application type depends either in Customizing or in the transaction BANK_PP_APPLREL (maintenance view V_TBANK_APPLREL).

Note: If you enter the dependencies in Customizing, it does not mean that the check is saved automatically. You must do this for each application type.

The following scenario should make things clearer:

A Banking component has three applications: Mass run account settlement, bank statement and account closure.The master object for account settlement and bank statement is the account.The corresponding order is the master object for account closure, but it also processes ac-counts.The bank statement cannot process the account until account settlement has been completed successfully.Account closure cannot process the account until account settlement has been completed successfully. Account settlement must set locks, lock object is the account. Bank statement and account closure must read locks. Enter account settlement as relevant for statement and closure in the view

V_TBANK_PP_APPLREL.

Note: Interaction only works if the application types refer to the same lock object.In the above example, settlement sets account locks, so the account closure must read ac-count locks even though its master object is the order.

The locks are set and deleted in the LUW in which the relevant objects are processed, in the callback module of event 1300.

3.4.3.1 Set Locks – BANK_MAP_PP_LOCKS_SET

Name Type Meaning Opt.I_PROGN BANK_DTE_PP_PROGN Mass run key, field 1 XI_PROGDATE BANK_DTE_PP_PROGDATE Mass run key, field 2 XI_PROGNO BANK_DTE_PP_PROGNO Mass run key, field 3 XI_APPLCATG BANK_DTE_PP_PAAPPLCATG Force new run XI_TAB_LOCKS BANK_TAB_PP_LOCK Object list



Page 23 of 34


INTERNAL_ERROR Exception

3.4.3.2 Read Locks – BANK_MAP_PP_LOCKS_GET_MLT

This module gets locks for the relevant application types.

Name Type Meaning Opt.I_OBJCATG BANK_DTE_PP_OBJCATG Object type in parallel

processing (key)X

I_OBJNO BANK_DTE_PP_OBJNO Number of object in parallel processing (key)

X

I_TAB_OBJECTS BANK_TAB_OBJKEY Object key XI_TAB_RNG_RELEV_APPL BANK_TAB_RNG_APPLCATG Area of application types to be

checkedX

I_FLG_EXCL_CURR_RUN XFELD Indicator: Ignore entries for cur-rent run

X

I_STR_CURR_RUN BANK_STR_RUNKEY ID of current mass run XI_CURR_APPLCATG BANK_DTE_PP_PAAPPLCATG Application type in parallel pro-

cessingX

I_FLG_IGNORE_SUCCEED-ING_LOCKS

XFELD Indicator: Ignore subsequent locks

X

I_MAXCOUNT BANK_DTE_PP_MAXCOUNT Maximum number of data records to be read

X

I_FLG_IGNORE_LOCKEDBY XFELD No check of lock owner XE_TAB_LOCKED BANK_TAB_PP_LOCK Object locksE_TAB_LOCKING_RUNS BANK_TAB_PP_RUNKEY_APP

LRuns that cause locks

E_TAB_OWN_LOCKS BANK_TAB_PP_LOCK Object locksE_RCD SY-SUBRC =1: Selection limit reachedCURR_RUN_NOT_QUALI-FIED

Exception

Implementation Notes• The parameter I_FLG_EXCL_CURR_RUN defines that the locks set by own runs or

application types are to be ignored. They are returned in E_TAB_LOCKED rather than in E_TAB_OWN_LOCKS.

• The parameter I_FLG_IGNORE_SUCCEEDING_LOCKS defines whether locks from other runs are to be taken into account if they were set after the last lock set by your own run.



Page 24 of 34


3.4.3.3 Delete Locks – BANK_MAP_PP_LOCKS_RELEASE

Name Type Meaning Opt.I_PROGN BANK_DTE_PP_PROGN Mass run key, field 1 XI_PROGDATE BANK_DTE_PP_PROGDATE Mass run key, field 2 XI_PROGNO BANK_DTE_PP_PROGNO Mass run key, field 3 XI_APPLCATG BANK_DTE_PP_PAAPPLCATG Force new run XI_TAB_TO_RELEASE BANK_TAB_OBJKEY Object keyI_TAB_LOCKS_TO_REL BANK_TAB_PP_LOCK Object locks

Implementation Notes• The table I_TAB_LOCKS_TO_REL contains locked objects whose locks are to be

deleted• The table I_TAB_TO_RELEASE can contain locking objects. If the table

I_TAB_LOCKS_TO_REL does not contain entries, then all the locks are deleted that were caused by the objects contained.

• If neither table contains entries, all the locks of the specified mass run are deleted



Page 25 of 34


4 Documentation for Central Interfaces

4.1 BANK_MAP_PP_START

Name Type Meaning Opt.I_PROGN BANK_DTE_PP_PROGN Mass run key, field 1 XI_PROGDATE BANK_DTE_PP_PROGDATE Mass run key, field 2 XI_RUNID_EXT BANK_DTE_PP_RUNID_EXT External ID of mass run XI_FLG_FORCE_NEW_RUN XFELD Force new run XI_FLG_UNIQUE_EXTID XFELD Check external ID is unique XI_APPLCATG BANK_DTE_PP_PAAPPLCATG Application typeI_PACKMAN_ID BANK_DTE_PP_PMID_EXT Key of (standard) package for-

mation to be usedX

I_TAS_PACKCR_PARAM BKPP_TAS_PP_PACKCR_PARAM_EXT

Parameters for package formation

I_XSIMULRUN BANK_DTE_PP_XSIMULRUN Indicator: Simulation run XI_MAXSTEPNO BANK_DTE_PP_STEPNO Maximum number of parallel

processing stepsX

I_STR_APPL_PARAM Application parameters XI_STR_PRINT PRI_PARAMS Print parameters XI_XLOG XFELD Indicator: Do not create

application log X

I_LOGEXTNUMBER BALNREXT External ID for application log XI_TAB_LOG BANK_TAB_JC_APPL_LOG_DA

TAData for opening message ob-jects in a process

X

I_X_SYNC XFELD Indicator: Synchronous call up XI_X_USE_DIALOG_WP XFELD Indicator: No background

processingX

I_X_TRIGGER_START_BY_COMMIT

XFELD Indicator: Trigger start of PP by COMMIT WORK

X

I_TAB_JOBDIST BANK_TAB_GRP_SRV Jobs per server group and server XE_STR_RUNKEY BANK_STR_RUNKEY Key of mass runE_RUNSTATUS BANK_DTE_PP_RUNSTATUS Status of mass runE_RCD_APPL SY-SUBRC Return code of applicationE_TAB_LOGH BAL_T_LOGH List of handles for application

logsE_LOGEXTNUM BALNREXT External ID of application logsE_TAB_JOBS BANK_TAB_JC_JOBKEY List of generated background

jobsNO_OUT_OF_SYNC ExceptionNO_EXPORT_ALLOWED ExceptionPACKMAN_INVALID ExceptionPREPARE_FAILED ExceptionSTART_FAILED Exception

Information on individual parameters:



Page 26 of 34


• The parameters I_PROGN, I_PROGDATE are obsolete.

• I_RUNID_EXT

• I_FLG_FORCE_NEW_RUN

• I_FLG_UNIQUE_EXTID

• I_APPLCATG: Application type

• I_PACKMAN_ID: ID of existing package division that is to be used by the new mass run that is to be started. (See also: Error: Reference source not found).

• I_XSIMULRUN: Mass run executed as simulation. It is not possible to restart runs that are started in this mode.

• I_MAXSTEPNO: Number of parallel processing steps (See also: Error: Referencesource not found).

• I_STR_APPLPARAM: This parameter contains the global application parameters.

• I_STR_PRINT: Print parameters. If no parameters are entered, then system applies the print settings of the user who called up the function module.

• I_XLOG: Indicator that the PP tool should create an application log (for each parallel job). You must specify the object and subobject of the application log in Customizing of the application type (See also: Error: Reference source not found), or enter the settings for the creation of message object in the table I_TAB_LOG.

• I_LOGEXTNUMBER: You can enter an external ID for the application log generat-ed by the PP tool. This parameter is obsolete. You should enter the log data in the ta-ble I_TAB_LOG.

• I_TAB_LOG: List of message objects to be created. The transfer structure is ex-plained in more detail in Error: Reference source not found

• I_X_SYNC: If this indicator is set, the FB is run synchronously, which means that the FB is not left until the end of all parallel jobs. If the Start FM is run from a report that is part of a job net in the area IBS Financial Services, you must set this indicator.

• I_X_USE_DIALOG_WP: If you set this parameter, then no background jobs are started, rather processing is in a sequential dialog work process. This mode should only be used for debugging.

• I_X_TRIGGER_START_BY_COMMIT: You use this indicator to control whether parallel processing is to be triggered by a COMMIT WORK (’X’) or not (SPACE). If you call up a function module using a BAPI, then a COMMIT WORK is used. PP is not started by the BAPI, rather all database entries for processing control are marked in the update task. You call up the function module API_TRANSACTION_COMMIT to trigger the



Page 27 of 34


writing of data to the database. To start the run, you call up the MAPI module BANK_MAP_PP_START_TRIGGER.

• I_TAB_JOBDIST:

• E_STR_RUNKEY: Key used to identify the new mass run.

• E_RUNSTATUS, E_RCD_APPL: (Technical) run status and return code of the application at the end of parallel processing. You cannot request these parameters for asynchronous runs (I_X_SYNC=’X’) (Exception: O_EXPORT_ALLOWED).

5 ExamplesA demo application is delivered with the PPF (see section 8.2), which displays an example of the implementation of the PPF and the functions of the callback modules.

6 Tips und Tricks

6.1 Debugging

As the PPF uses batch jobs for the processing of parallel processes, debugging is possible at the start of this job only. If you want to analyze processing for each process, there are two possible options.

6.1.1 Synchronous Start in Dialog Mode

Procedure:• Set the flags I_X_SYNC and I_X_USE_DIALOG_WP when you call up

BANK_MAP_PP_START• The PPF does not create jobs, rather the processes/packages are processed sequen-

tially in dialog mode.



Page 28 of 34


6.1.2 Parameters BANK_JC_DBG_MODE in the User Data (from release 6.40)

Possible values:• DBG_OFF• DBG_DIA• DBG_BTC• DBG_BTC_DIA

Prerequisites:• DEBUG authorization and change authorization in debugger

If DBG_BTC is set, an endless loop is run in the two reports RBANK_PROC_START and RBANK_PROC_END (start of parallel job), which makes it possible to capture each job or process in the process overview SM50. You can then set extra stop points in the debugger. To end the endless loop and run the report as “normal”, you must set the l_flg_exit flag to ‘X’ in the debugger.

Warning about Debug Mode: If the flag is set, an endless loop is run in every parallel job and in every related end job and must be ended by setting the flag in the debugger. Therefore, you must ensure that you do not set a high degree of parallelization in job distribution.

7 Other Important Aspects

7.1 Error Log

The PPF uses the standard application log to log errors by “message class”. The components are found in the function group EMSG of the package BMESSAGE. The log must differenti-ate between the areas of preparation and parallel processes.

The parallel processes are run in batch jobs started by the PPF. The PPF serves as a channel and creates log objects at this event. When BANK_MAP_PP_START is called up, the ap-plication can transfer one or more log objects, which can be opened in the corresponding se-quence. If nothing is transferred, the PPF opens the log objects FS_EXC and FS_PROT. This means that there are two logs for each parallel process in the application log.



Page 29 of 34


The system writes any error messages that were issued before parallel processing to the ap-plication log with the functions of the message class, which not only writes the messages to the log but also triggers a MESSAGE … RAISING command. As the PPF does not serve as a channel at this point, it does not open a log, rather it waits for the application to do so. If no open log exists, the messages are output. If processing is running in the back-ground, then the job is canceled.

Important: The application must open at least one log object using the message class (function group EMSG) before the start module BANK_MAP_PP_START is called.

For an example of the creation of log objects, see the routine init_messages in the start report RBANK_PP_DEMO_START, in which the module MSG_OPEN creates two logs.

7.2 BANK_PP_SETTINGS

The transaction BANK_PP_SETTINGS is used to set special parameters for the PPF. At the moment, one parameter is available:

• Indicator whether the process data is to be deleted automatically after the current process.

7.3 Job Distribution

“Job distribution” groups together two connected issues or processes in the PPF:• Degree of parallelization (number of parallel processes to be created)• Distribution of processes to batch jobs / server

7.3.1 Degree of Parallelization

The PPF creates a process for every application type. To define the degree of parallelization for each application type or run, you have the following options:

• Entry in Customizing or maintenance view (see section 3.2.2 )• Transfer as parameter at start• Implementation of BTE 0BANK011 (see section 3.3.1.2 )



Page 30 of 34


To transfer the desired job distribution when you call up the PPF, you specify the parameter I_TAB_JOBDIST of type BANK_TAB_GRP_SRV. The fields of the corresponding structure type are shown in the following table.

Field Type DescriptionSERVERGROUP RZLLI_APCL Name of logon/server groupSERVER BANK_DTE_JC_SERVERNAME Name of application serverCNT_JOBS BANK_DTE_CNTJOBS Number of background jobs

The description of the fields and procedure for distribution is contained in the next section.

7.3.2 Distribution

The distribution of the required jobs is executed in several steps. Internal distribution is exe-cuted using a table that has the format described above, irrespective of the definition method.

• Entries exist with server name Desired number of jobs scheduled on this server• Entries with server group Distribution of corresponding number of jobs to

server in this group• Entries with number only Distribution to desired number of available servers

During distribution, the system checks whether the server is active, whether batch processes exist on the relevant server, and whether free processes exist.

Job Distribution in the Current System:The PPF can cannot hand over job distribution (also known as Load Balancing) to SAP Job Control at the start event of the processes, rather it must execute job distribution itself at an earlier stage. This is necessary for initial assignment of work packages to specific servers – when the packages are created, the servers for each process must already be known. This can sometimes mean that no free batch processes are available on one or more of the planned servers when the processes are due to start. In each case, you must check whether parallel processes can be corrected if necessary.

7.4 Repeat – Retry - Restart

This section defines the terms Repeat, Retry and Restart.

Repeat – Repetition of a PackageThis term refers to immediate repetition of a package in the processing loop for the pack-ages. As soon as the package is finished, it is reprocessed by the application in the parallel job. One possible use is for a temporary lock of one or more objects, by dialog locks for exam-ple. It is hoped that the lock will be set for a short time only and that the package will be re-



Page 31 of 34


processed immediately. From method 1300, the application returns the affected objects (with status 6) to the PPF. As described above, the application must cancel the repeat runs. The next package cannot be processed until no objects have status 6. The application can in-corporate this function using a repeat loop in the module for event 1300.

Retry – Repetition of Whole StepThis term refers to repetition of a whole step in the current mass run. The objectives are the same as before, but note that you could remove all the object locks in the time required to stop and restart the whole step.The application triggers the repeat by returning objects with the status 4. The exact proce-dure of the PPF is influenced by the settings made in Customizing (see section 3.2).

You must note the following when using this procedure:• Reprocessing the whole step can lead to a lot of lost time because all parallel pro-

cesses must be restarted, starting from the original job distribution. • As it is not possible at the moment to form packages of objects that are still open, it

can occur that more parallel processes are run than are required. This can block oth-er applications.

• You enter the maximum number of repeats in Customizing. If the number is too high, it can lead to extremely long runtimes

RestartThis term refers to restart of a canceled mass run. The procedure is described elsewhere.



Page 32 of 34


8 Tools for Developer Support

8.1 Generation of Module Holders

You can use the report RBANK_PP_GENERATE_APPL to generate the relevant callback modules for all events. The interfaces are created using the information in Developer Cus-tomizing.

Note the following:

• Before you start the report, you must create a function group for storage of the gen-erated modules. You must specify this group on the selection screen of the report.

• The report generates modules for all existing events. You must delete all the modules not required by the relevant application and remove the corresponding en-try in Developer Customizing.

• The “customer application“ flag defines whether the application type and modules are to be entered in the table of customer application types.

8.2 Demo Application

The demo application is delivered with the PPF. It is a fictitious application that shows the integration of the PPF. It consists of the following elements:

• Function group BANK_API_PP_DEMO contains the callback modules for the PPF events

• RBANK_PP_DEMO_START – Report for starting the demo application

• RBANK_PP_DEMO_RESTART – Report for restarting a canceled run of the demo application

• RBANK_PP_DEMO_GENERATE_DATA – Report for generating test data

• RBANK_P_DEMO_CREATE_PACKMAN – Report for creating a package administrator



Page 33 of 34


9 IndexAAnwendungsart.................................................................

Abhängigkeiten........................................................22

BBANK_MAP_PP_CONFIRM_OBJECTS...................18BANK_MAP_PP_START...............................19, 26, 28BTE...............................................................................21

CCallback Bausteine..................................................13, 33Commit Work...............................................................18

DDebugging...............................................................28, 31

EEvents..............................................................................6

FFehlerprotokoll..............................................................29Funktionsbausteine...........................................................

BANK_MAP_PP_LOCKS_GET_MLT.................24BANK_MAP_PP_LOCKS_RELEASE..................25BANK_MAP_PP_LOCKS_SET............................23

HHinweise............................................................................

Fehlerprotokoll..................................................19, 30Jobverteilung im laufenden Betrieb.........................31Warnung zum Debugmode......................................29

J

Jobverteilung...........................................................20, 30

OObjektsperren................................................................22

PPaketbildungstyp...........................................................10Pflegeviews.......................................................................

V_TBANK_APPLREL...........................................23V_TBANK_PP_DISTR..........................................20

RRestart...........................................................................11

TTransaktionen....................................................................

BANK_PP_APPLREL............................................23BANK_PP_SETTINGS..........................................30

WWiederholung................................................................18

Repeat......................................................................31Restart......................................................................32Retry........................................................................32

ZZeitpunkte.........................................................................

0205.........................................................................141000.........................................................................151100.........................................................................161200.........................................................................171300...................................................................17, 23



Page 34 of 34

Documents

98396640 PPF Developer Docu