Appendix: Configuring Batch Processes

This appendix discusses:

• Batch process configuration.

• Payroll-related tables.

• Processes.

• High-level processes.

• Process detail.

• Payroll for North America COBOL program types.

• PeopleSoft SQL application programming interface (API) for batch COBOL.

• Flexible field lengths.

Batch Process Configuration

This section lists prerequisites and discusses:

• Batch process configuration considerations.

• True configuration costs.

• Payroll for North America system capabilities.

• The vanilla PeopleSoft system.

• Your modification requirements.

• List of required modifications.

• Proposed modifications review with PeopleSoft.

• Contact with other customers.

Prerequisites

Do you really need to configure Payroll for North America?

Configuration is not to be performed lightly. Before you start to think about adding, deleting, or modifying code, ensure that everyone in the organization understands what configuration entails. Your goal should be to modify the system as little as possible, and preferably not at all.

Remember that companies decide to acquire a software package such as Payroll for North America because it is a package. It’s a coherent and self-contained system, already designed and delivered. It runs, it works, it satisfies the demands made upon it, and it does this best—and with the least problem and expense—when you work with the package as it exists.

Before you make a list of required modifications to Payroll for North America, perform the following prerequisite activities:

• Understand what configuration may cost—and this includes hidden maintenance expenses that might not be immediately obvious.

• Understand Payroll for North America system capabilities and design from a functional point of view. For what tasks are you trying to use it?

• Use the vanilla Payroll for North America system extensively; both with the PeopleSoft-supplied Demonstration data and with your own realistic test data.

• Revisit your configuration requirements thoroughly.

• Produce a list of your required modifications.

• Review your proposed modifications with PeopleSoft.

• Contact other PeopleSoft customers to discuss configuration issues you may have in common.

Batch Process Configuration Considerations

Before you modify Payroll for North America batch processes, make a thorough analysis of the business requirements that you’re trying to address through configuration and seriously consider the possibility of addressing those requirements through reengineering the payroll department procedures rather than through changing PeopleSoft COBOL source code. It is almost always more cost-effective to reduce the list of required changes to an absolute minimum. When you configure batch processes, you incur a variety of ongoing maintenance expenses and possible conflicts as the effects of the changes move through the system.

An important configuration consideration is how the system processes the various dates in Payroll for North America: effective dates, begin and end dates, dates on the job record, dates on the General Deduction table, and dates on the Pay Calendar table.

Note. In providing information on this topic, we assume that you have a basic understanding of PeopleSoft online processing flow, PeopleTools, relational databases, and COBOL programming.

See Also

Understanding Pay Calendar Date Fields

True Configuration Costs

This section discusses the cost of configuring your batch processes such as upgrading, further documentation, and support limitations.

Future Ongoing Liability: Upgrades

After you configure the PeopleSoft system, upgrades inevitably become more difficult, with the degree of difficulty directly proportional to the extent of the modifications that you make.

You must retrofit all the configured code to the new PeopleSoft application. We supply you with a new, upgraded system, and you’ve modified the old one. You’re going to have to make a careful analysis of the old and new systems, relying to some extent on the documentation you’ve (hopefully) produced to go along with the configured code. Additionally, you need to decide which modifications to keep (and how to keep them), which to delete, which to record from scratch, and so on.

PeopleSoft maintains our application features from release to release. We may alter the manner in which we provide certain functions. When we do, we deliver the upgraded feature as part of the new system release. When the change requires a new structure for data, we provide you with specific, rigorously tested procedures to change your data or programs to conform to the new release. This, in itself, is a powerful argument against configuration and its associated maintenance costs, because when you make modifications, you may have to reimplement the modifications whenever a new release comes out.

This might be fairly straightforward process: You just add your old modified code into the new system. On the other hand, PeopleSoft may have changed the way we do things from release to release, so you have to look at each modification and technically assess whether it works the way it used to or not. After you make the decision to configure, you have to continue to modify the package each time you implement a new release.

Future Ongoing Liability: Documentation

For every configured feature that you implement, you must produce your own documentation. You have to decide whether to merge the documentation with PeopleSoft’s or to keep them separate. And documentation must be maintained. Each time a new release comes out, you have to go through the same process all over again, merging or adapting the documentation as necessary. It’s expensive. And this expense will continue. Documentation isn’t just a part of your initial configuration project. It’s part of your upgrade process with every new release.

Possible Support Limitations

After you modify the system, you face another dilemma: If something in the system doesn’t seem to work properly, is the problem due to PeopleSoft or to your configurations? Is the alleged bug in PeopleSoft code or yours?

Can PeopleSoft duplicate the problem you’re having? After you’ve modified the system, PeopleSoft might not be able to do so. It’s important to be able to duplicate a given problem, to satisfy yourself that there is indeed a problem, and to know whether you’ve fixed it.

For PeopleSoft to help you solve the problem, we must be able to duplicate the problem, fix the source code, and rerun the process. This is sometimes very difficult to do, even if you haven’t modified the system in any way. We might not be able to do this at all, after you configure the system.

It might be difficult, depending on what you modify, to help you. Such inherent support limitations constitute just one more reason to stay with the core application as much as possible, and if you’re going to modify it, to modify only minor aspects.

Payroll for North America System Capabilities

To configure Payroll for North America you must have a rigorous understanding of the system. How is the system put together? What is its component tables, programs, and pages? What is its system architecture and what is it really designed to do? And, of equal importance: How is your organization using it or planning to use it?

The following section provides some tips for training the appropriate people in your organization with Payroll for North America.

Combine Functional and Technical Personnel into One Team

When you’re learning about Payroll for North America, the functional and technical personnel should be in close communication with each other, to the point of becoming a single team. Your functional people know how your business runs; your technical people know how your current system is put together. And between the two groups, they can act as an effective team.

Ensure That Team Receives Training

Make sure that the whole team receives training in the PeopleSoft system, as a team, everybody together.

Run PeopleSoft Vanilla Payrolls at Your Site

Before rushing to configure, or even to formulate a list of configuration requirements, PeopleSoft recommends that you install the standard Payroll for North America demonstration software without changes. Have your team start using the demonstration companies, employees, pay groups, pay calendars, deductions, and so on; have everyone read Payroll for North America Business Processes; run Payroll for North America. In this way, everyone becomes familiar with such critical concepts as what paysheets are and what the Create Paysheet COBOL SQL process (PSPPYBLD) is; what the Pay Calculation COBOL SQL process (PSPPYRUN) does, and what checks are in Payroll for North America; what the Pay Confirmation COBOL SQL process (PSPCNFRM) does, what balances are, and so on.

The Vanilla PeopleSoft System

Everyone in the team should be familiar with how Payroll for North America works, because the next step is to try to duplicate your company’s payroll with the vanilla Payroll for North America system.

Build Real Earnings/Benefit/Deduction Table Entries

Start configuring your Earnings table, Benefits tables, and Deduction table by creating entries tailored exactly to support your company’s payroll operations. As you do this, you will, of necessity, start making some real decisions on how to define the actual earnings, deductions, and benefits that you need, according to the PeopleSoft vanilla style.

Set Up Realistic Test Cases

Set up some realistic employee test data; then use all parts of the system. Hire employees through the normal PeopleSoft Human Resources paths; set them up with realistic earnings, general deductions, and benefits; enable them to be paid; then go ahead and pay them.

Keep the Demonstration System Available

Be sure to keep the original Payroll for North America demonstration system data available, so that as you’re going through and modifying earnings, deductions, employees, and other data, you can always refer back to some of our test cases to see how they were set up. Many of the demonstration employees are paid, for example, with fairly complex benefit setups. And if you purge all the PeopleSoft demonstration data, you won’t know how they were originally set up. By keeping the demonstration system available, you always have a reference point as you continue to build tables for your own company’s real-life needs.

Your Modification Requirements

After you’ve gone through these exercises, and everyone on the team has a thorough understanding of PeopleSoft system capabilities, we encourage you to go back to your original list of requirements, whether this is in the form of a request for proposal or something else. Based on your new knowledge of the PeopleSoft system, you may find you can significantly refine your requirements, and that some might actually disappear. The following section provides some key questions to ask when revisiting your requirements.

Where Did We Get This Requirement? Is It Real?

Is it really a company requirement that we do payroll in this particular manner? Do we want to do it that way just because we’ve always done it that way? And, if so, is that sufficient reason to continue with this practice? Or is there another way that’s just as easy, just as good, and doesn’t require modification of Payroll for North America?

How Much Have Operational Characteristics of the Existing System Influenced Requirements?

When companies revisit and analyze their payroll requirements, they sometimes discover that particular requirements were actually formulated in response to operational characteristics or restrictions in their current (or old) system. A particular procedure came about that was really a compromise or a work-around. Some payroll department procedures may have no basis in any real payroll requirements; they might just reflect some operational characteristic of the current or old system. If so, this is an argument for reengineering some of your business procedures and practices and not configuring Payroll for North America.

Whose Standards Should We Use, Ours or PeopleSoft’s?

Because of your company’s in-house standards and conventions, you might discover a discrepancy between the way you ordinarily do things and the way PeopleSoft has delivered the system.

One reason your company decided to use the PeopleSoft system is the high degree of fit between your requirements and our features. Your selection team determined that Payroll for North America has attributes that your company could use.

A system your company builds in-house will in all likelihood conform to your company’s standards; but if you bring in a package, it might be more reasonable to adopt the standards set by the vendor of the package.

Decisions having to do with standards start right at the beginning, when you install Payroll for North America. We require a database to be set up, and the tables all have to be named. A database administrator might say, “Our Company does not name tables this way,” and suggest renaming all 8000 and some odd PeopleSoft tables and views. Keep in mind the ramifications of renaming all 8000 tables and just how extensive a change that really is.

List of Required Modifications

Now that you’ve assessed the costs of configuration, acquired a deep understanding of Payroll for North America system capabilities, used the vanilla system extensively both with the DEMO data and your own test cases and thoroughly examined your requirements—you are in a position to come up with a list of required modifications. What remains should consist of changes you absolutely have to make to the Payroll for North America system to make it acceptable for production.

After you’ve come up with such a list, separate it into two parts:

1. Changes that can be addressed through business reengineering.

2. Changes that require configuration of the PeopleSoft system.

Examine your list very carefully with the goal of having an absolute minimum of changes that require configuration.

Proposed Modifications Review with PeopleSoft

After compiling your list of modifications, work with your PeopleSoft Account Executive on these proposed changes.

Remember that there might be another way, short of rewriting code, to do what you want to do. It’s always useful to reconsider the functional and technical issues, with the help of an experienced expert in the system. Often, they can suggest another way of achieving the functionality that you want, ideally, through the standard system.

And it may be that PeopleSoft is already planning and designing, for a future release, a feature similar or identical to what you have in mind. Particularly if your requirement doesn’t represent something unique to your company’s individual way of doing things, but is rather a genuine functional requirement typical of many payroll departments, we might have other customers who have requested we add such a feature to our standard system.

PeopleSoft may have already designed the feature that you need. If this is the case, you can work with PeopleSoft, through your Account Executive, so that we can jointly get that feature into your system.

It’s always to your advantage to remain in close contact with PeopleSoft on configuration issues. For example, even if you do all the work on designing and implementing a modification, if PeopleSoft subsequently takes it over and makes it part of our standard application, then you’ll be free from the ongoing maintenance liability.

Contact with Other Customers

Your company probably has payroll requirements that overlap to a considerable extent with those of other PeopleSoft customers. Another PeopleSoft customer may have requested the same modification that you are contemplating; they might have gone ahead and designed the feature on their own. This might occur even if you think the requirement is absolutely pure or unique to your circumstances.

Other customers might have similar requirements and built it into their systems. By trading design ideas back and forth with other customers, you might be able to come up with a great solution more effectively and efficiently than either of you could on your own.

Use Customer Connection to Communicate

Customer Connection, PeopleSoft’s web-based communications service consisting of updates and fixes, discussions and SIGs, and news and information about PeopleSoft applications and development plans, is an ideal tool for communicating with other customers about configuration issues.

Payroll-Related Tables

This section discusses:

• Payroll-related tables.

• Employee data input tables.

• Effect of database changes.

• Payroll process input tables.

• Paycheck output tables.

Payroll-Related Tables

Payroll for North America is a set of input tables, processes, and output tables. You set up your input tables, run a process, and the process—in turn—writes new data to the output tables. Here’s an example:

Note. This chart doesn’t list actual table names, but are generic classifications for the various tables in the system.

Running Payroll for North America processes might be labeled a quiet task. The processes start, run, and stop, rarely putting out more than five or ten lines of output, which typically consist of messages to the effect that the process began at a certain time, a certain pay group is being processed, and finally, that the run has finished.

The system writes all results of the Payroll for North America processes back into the database. Any tangible outputs from these processes, such as paychecks, are all reports based on database tables. To get the physical paychecks, for example, you run an Structured Query Report (SQR) against the database.

So what does a typical Payroll for North America process do? It reads some input from various tables, writes new data back into the database, and goes away. A process might send a message that says “Check Messages!!!”; that means it wrote at least one message into the message table. In that case, you need to go back and run a report against the message table to get the messages, or view the messages online on the Paysheets page, Payroll Messages page.

Employee Data Input Tables

As shown in the preceding chart, the employee data input tables can be classified as employee jobs, benefits, and deductions. Online, some of these tables are found in the Workforce Administration menu, others in the Employee Pay Data menu, and some in the Benefits menu.

You hire employees and set up their job data; enroll them in benefits programs and set up their benefits data; set them up for general deductions and enter this information on the database. You insert rows into their various job, benefits, and deduction tables:

Employee data tables all have EMPLID as a key, so if you need to find them all, a good way to start is to look at those tables containing EMPLID. To do this, use the Records and Fields PeopleTools Cross Reference Report (XRFFLRC).

Effect of Database Changes

One of the advantages of Payroll for North America is that you can use PeopleTools to easily configure the payroll tables. However, you keep in mind how any changes you make might move through the database, particularly considering the interdependency not only of tables, but also of the batch processes that call them.

Suppose you decide you have to add a column (a field) to PERSONAL_DATA. PeopleSoft batch processes never issue a SQL SELECT statement against a table. The system always selects only the columns that it wants from the table. If it wants to retrieve or update rows of the employee names, for example, it specifically asks for the NAME. It never makes an assumption about what columns are on that table.

Consequently, if you add a column to PERSONAL_DATA, it doesn’t affect batch payroll processes, because if a batch process wants something from PERSONAL_DATA, such as the employee’s address, it asks for the address by column name. So, in effect, you can add multiple columns, and if you do not need or want your new columns to affect batch processing, that’s OK, because the processes ignores them. Any tables that you modify, of course, are maintained by the online system, so you need to modify and store the appropriate records (and possibly pages).

You must be more careful when modifying existing columns that are used by the batch processes. For example, you might decide to alter the HOURLY_RT column on the JOB table. You need seven decimal places instead of the six provided in PeopleSoft. Now, the batch Payroll system is set up to read the HOURLY_RT column from the JOB table; and when it does so, it makes the assumption that it’s reading the HOURLY_RT as defined in the standard application. In this case, modifying an existing column affects payroll processing, because the COBOL programs must know the format of the data to be mapped. Because the HOURLY_RT column is used by Payroll, you also have to modify some of the batch processes.

Remember also that if you change the name of the HOURLY_RT column, the batch processes won’t be able to find it unless you modify the batch processes accordingly.

Some of the tables—particularly the output tables—are maintained by batch processes (DEDUCTION_BAL, the Deduction Balance table, for example). During normal processing, the system inserts, updates, and possibly even deletes individual rows. When you add new or modify existing columns on these tables, you have to make the corresponding COBOL changes.

Payroll Process Input Tables

For payroll process input tables, you set up much of the controlling information for running payrolls, information having to do with the specifics of particular earnings, deductions, or taxes. You can find these tables online in the Set Up HRMS, Product Related, North American Payroll menu, unless otherwise indicated.

The fact that an employee works in the state of New York is employee-level data stored in the employee data input tables. But to calculate that employee’s taxes, the system checks the appropriate pay process input table that defines tax rates for employees who work in New York:

Paycheck Output Tables

Paycheck output tables are result tables written to and maintained by the batch processes. Some paycheck output tables are, in turn, inputs to other batch processes:

The tables on the left are payroll input tables. Often, they are populated with data during the Create Paysheet process, so in that sense they are output tables. But after they are created, they serve as inputs to the other payroll batch processes, such as Pay Calculation and Pay Confirmation. Create Paysheet is a process that goes through the database and forms a proposal to pay someone; it creates the paysheets. When you view paysheets online, you’re looking at data from the payroll input tables. When you make one-time tax, deduction, or garnishment changes to an employee’s paysheet, you are writing data to these tables, data that the batch processes uses in the next step of converting input to output.

The tables on the right are payroll output tables; most of them also have corresponding balance tables. These tables are the result of running one of the payroll batch processes. These tables are maintained by the Payroll for North America system. That is, these are tables that the system uses to write back to the database during processing.

Notice that the PAY_EARNINGS table functions both as a payroll input table and as a payroll output table. The Create Paysheet process initially generates information in PAY_EARNINGS. Your online users might then update the table. However, the Pay Calculation and Pay Confirmation processes subsequently write results back into PAY_EARNINGS, because PAY_EARNINGS also serves as the history record of the employee’s earnings.

PAY_EARNINGS before and after pay confirmation is the same table, but there is a difference. The PeopleCode behind the data-entry paysheets pages doesn’t read any data that you’ve already confirmed. That is, the system considers information on a confirmed PAY_EARNINGS row ineligible to display on a paysheet. The information, however, is still there; it exists until you purge it.

PAY_OTH_EARNS is treated in a similar fashion.

See Also

Maintaining Payroll Data

Cross-Reference Reports

Processes

This section discusses:

• Upper-level programs.

• Cross-reference (.XRF) files.

• Cross-reference reports.

• One set of COBOL source.

Upper-Level Programs

Having briefly discussed the tables that are either required for online input to Payroll or written to by Payroll, the next step is to discuss the processes by which the system maintains the output tables. This table provides a general view of the upper-level programs of Payroll for North America:

So, for example, PAYSHEET is a high-level process; its online name is Create Paysheet. If you run DOS, you use the PAYSHEET.BAT file to initiate the process; if you run MVS/DB2, there’s a PAYSHEET JCL PROC.

Note. The run control processes on the preceding chart are the only programs that are initiated at the operating-system level. All other programs—including everything to the right of the Run Control Programs column on the chart—are initiated by the high-level process programs through call statements.

Cross-Reference Reports

For further views of the architecture of the application, you can use the PeopleTools cross-reference reports. These are actually predefined SQR reports, not unlike the standard reports that are delivered with the PeopleSoft system. The cross-reference reports scan the PeopleTools tables containing the definitions for application objects, then print them out in a report designed specifically as a PeopleTools configuration reference tool.

As with our other standard reports, you can easily identify cross-reference reports by their three-character prefix: XRF. So, for example, XRFFLPN is the Fields and Pages cross-reference report, which lists all fields in alphabetical order.

One Set of COBOL Source

Payroll for North America has only one set of COBOL source for all platforms. Our COBOL source is ANSI-85-compatible, and it is becoming strictly ANSI-85-compatible.

Note. Each platform does have a few COBOL programs written expressly for that platform, notably a batch API program and a PeopleSoft Process Scheduler program.

High-Level Processes

This section discusses:

• Benefit processes.

• Payroll processes.

Benefits Processes

The following table lists the benefits processes.

*These constitute PeopleSoft Enterprise Payroll Interface, an interface application for companies using PeopleSoft HRMS for benefits without Payroll for North America.

Payroll Processes

We classify Payroll for North America processes into three types: those that you use on a regular basis, those that you run occasionally, and those that you need only in emergency situations.

Regular Processes

Payroll for North America includes six processes that you run repeatedly as part of your normal payroll procedures:

(E&G) PeopleSoft Human Resources Processes for Education and Government

This table describes the four PeopleSoft Human Resources processes for education and government:

Occasional Processes

Four Payroll for North America processes are for occasional use:

Emergency Processes

These three processes are for emergency use only:

Process Detail

This section discusses:

• Operating systems.

• One common command (PSRUN) referenced by all processes.

• Process example for MVS/DB2.

Operating Systems

How are processes—Create Paysheet, Pay Calculation, and so on—actually implemented in Payroll for North America? At the user level, the user defines process parameters, clicks the Run button, and then tells the system when and where to run the process in the Process Scheduler Request page.

For each process, no matter what the environment, the PeopleSoft system uses operating system-stored commands. PeopleSoft uses whatever method the operating system uses to store operating system commands.

If you run Payroll for North America under environments other than Microsoft Windows (NT):

See Also

PeopleTools PeopleBook: PeopleSoft Process Scheduler

One Common Command (PSRUN) Referenced by All Processes

These stored commands have one thing in common: They start another stored procedure called PSRUN. PSRUN, in turn, is the procedure that actually starts the process, initiating a run control COBOL program. (PAYUNSHT, being an SQR, is an exception).

Process Example for MVS/DB2

The following example, delivered in the JCL Library, shows how PeopleSoft implements the Pay Calculation process under MVS:

//*
//********************************
//* RUN PS PAYROLL CALCULATION
//********************************
//*
//PROCLIB DD DISP=SHR,DSN=PROCLIB
//CALCPAY EXEC PSRUN,PSLOAD = 'PSLIB'
//SYSTSIN  DD  *
 DSN SYSTEM (DDD) RETRY (O) TEST (0)
 RUN PROGRAM (PSPPYRUN) - 
   PLAN (PLANRT)
 END
/*
//

You can see that the program is executing a PROC called PSRUN. In this startup routine, the procedure passes the SYSTSIN input file to the PSRUN procedure, and it indicates that the program to start is PSPPYRUN. PSPPYRUN is the run control program, the driving program for Pay Calculation.

Payroll for North America COBOL Program Types

This section discusses:

• COBOL program naming conventions.

• Run control programs.

• Main programs.

• Table access programs.

• Input programs.

• Utility programs.

• Processing programs.

• Output programs.

COBOL Program Naming Conventions

All Payroll for North America COBOL programs have eight-character names beginning with PS (for PeopleSoft):

In general, the five letters following the prefix are an abbreviated form of the program’s functional name. These abbreviations are typically formed by removing the vowels.

Table Access Program Names

After PSP or PSC come three letters identifying the table, and then TB (for table):

PSP ERN TB = Earnings table manager (looks up and loads earnings types)

Input Program Names

After PSP or PSC comes one letter identifying the program, and then ARRY (for array):

PSC E ARRY = Earnings Array Input Program (loads the earnings array)

Utility Program Names

After PSP or PSC comes five letters that abbreviate the function of the program:

PSP DTWRK = Date manipulation routine

PSP ANNLZ = Annualizes/deannualizes amounts

Processing Program Names

Processing programs typically end in -CALC, with one letter identifying the type of calculation:

PSP E CALC = Earnings Calculator

PSP D CALC = Deduction Calculator

PSP T CALC = U.S. Tax Calculator (PeopleSoft-maintained)

PSP X CALC = Canadian Tax Calculator (PeopleSoft-maintained)

Output Program Names

Output programs have descriptive names such as the following:

PSP CB UPD = Maintains check balance table (UPDates Check Balances)

PSP DB UPD = Maintains deduction balance table (UPDates Deduction Balances)

PSP C UPDT = Maintains current pay result table (UPDaTes earnings data)

PSP T UPDT = Maintains current pay result table (UPDaTes Tax data)

PSP X UPDT = Maintains current pay result table (UPDaTes Canadian TaX data)

Run Control Programs

Run control programs are the top-level programs started from the stored operating system command files. These are the programs that PSRUN starts. The run control programs fetch parameters from the run control table, which you set up online through the pages in the Paysheets page (or, for benefits processes, the Benefits Tables pages). In the example of process detail in the previous topic, the job of the run control program PSPPYRUN is to read the run control for Pay Calculation that you enter into the database.

Run control programs usually call a main program to initiate the process for the pay calendar or calendars that are associated with a particular pay run ID. The main program then loops through all of the pay calendars in a run.

Here’s a list of the run control programs, each with its associated online process name:

In most cases, these run control programs call a main program, but there are some exceptions. For example, the Confirm Deductions process is so simple that everything is processed within the run control program, PSPDCCNF, itself so there’s no need for a main program, and PSPDCCNF doesn’t call anything else. PSPCLBLD (Calendar Build), PSPDLBAL (Delete Balances (U.S)), PSPDLBLC (Delete Balances (Canada)), and PSPRPRNT (Check Reprint) are processed the same. Other than these exceptions, the run control programs call main programs to do the actual work, or at least to control it.

PSPPYWKS

Three of the run control programs—PSPPYRUN, PSPCNFRM, and PSPUNCNF—call a special controlling program, PSPPYWKS. The purpose of PSPPYWKS is to hold working storage. In the compiler we use, any given section can be a maximum of 64K. To pass more than 64K of data between our programs, PSPPYWKS owns working storage for the programs and passes it to them through linkage.

The arrays owned by PSPPYWKS are EARRY (the Earnings Array), DARRY (the Deduction Array), and DEDT1-6 (the Deduction Table Arrays).

Main Programs

The main COBOL programs are called by most run control programs to process one pay calendar:

The run control program for Pay Calculation, PSPPYRUN, must call one of the main pay calculation business processes to do the actual work. If PSPPYRUN finds that the pay groups to be calculated is a U.S. pay group, then it calls PSPPYCAL, which is the pay calculation business process for U.S. pay groups. If the pay group to be calculated is Canadian, PSPPYRUN calls PSPCPCAL, the pay calculation business process for Canadian pay groups.

The main programs are thus second-level down in the call tree.

Table Access Programs

PeopleSoft table access programs are designed to keep all pay process table information for each pay calendar in memory for the entire run. All the table access programs are identically configured; they’re all clones of each other.

Selected Table Access Programs

This table describes selected table access programs:

Understanding Table Access Programs

To understand the function of the table access programs, let’s look at how a process as Pay Calculation actually works. As Pay Calculation is calculating a pay group, it needs certain information. Among other things, it needs to know who needs to be paid. Pay Calculation bases the answer to the question of who needs to be paid on what earnings and deductions it finds on the database. At the employee level, it takes in all the earnings and all the deductions for a particular employee.

In addition, Pay Calculation must know the details about those deductions and earnings. It gets this information from the Earnings table and the Deduction table. These are pay-process-level tables, not employee-level tables, and when you run a process, they’re managed by subroutines in the payroll system, the table access programs.

When Pay Calculation sees an earnings come in for an employee, it reads the employee-level data, and sees, for example, that this employee is going to be paid some regular pay. It then goes to the Earnings table to find out the details of regular pay, reads the information about regular pay once, and stores it in a table array in memory. When the next employee comes along and also has regular pay, it doesn’t have to read the Earnings table again.

After the first few checks are calculated, the table access programs typically have all the details about all the earnings and deductions for that particular pay run. Ideally, Pay Calculation reads the Earnings table only once for each earnings type during a given run.

The key to running a process like Pay Calculation quickly is to reduce the number of hits on the database tables. This is why, if you have an Earnings table on the database containing 300 earnings types, we do not want Pay Calculation to read the Earnings table 300 times. For a particular pay group, you might use only 20 earnings types, so the table access programs reads them into the table array once, as they’re first encountered.

Increasing the Occurs Count on Table Access Programs

If your company requires it, one fairly safe and easy modification you can make is to increase the occurs count on your table access programs.

The table access programs allocate a specified, limited amount of memory space to store in a table array all the details of particular pay process tables typical for one of your pay runs.

The table access program that manages the Earnings table is called PSPERNTB. What happens if the array it stores earnings data in is allocated to 50 earnings types, and your typical pay run requires more than 50? PSPERNTB attempts to go find some information about this new earnings code, and get its, but there’s no more room in the array.

In this situation, PSPERNTB moves something else out of the array and replaces it with the information for the new earnings code. It does this without comment. It replaces one of the entries with a new one.

In this manner, you can encounter problems with the Earnings table, or other tables, on the database, if the amount of storage isn’t enough. There are two ways to determine whether you’re doing this:

• The easy way.

  Make a performance analysis of the payroll process and check the table accesses on particular tables. If the Earnings table, for example, is being hit more than you would expect—more than the number of entries in your Earnings table—then you know that you’re starting to stress it.

• The more difficult way.

  Insert a display into PSPERNTB into the particular piece of code that actually does move one of the earnings codes out and send a message to yourself, saying something to the effect of, “I’m starting to replace entries in the Earnings table, you might want to look at this.”

Note. It’s important to recognize that this kind of table destruction might be costing you a lot of processing time.

If you determine you’re destroying a table, you can increase the occurs count in the appropriate table access program. For example, let’s look at a piece of the unmodified code in PSCDEDTB, the Deduction Table Manager

02  DEDUCTION-COUNT        PIC 9999  VALUE ZERO  COMP.
    88  DEDUCTION-COUNT-MAX          VALUE 500.
02  DED-CLASS-TABLE-MAX    PIC 9999  VALUE 6     COMP.
02  DEDUCTION-TABLE                  OCCURS 500
                                       INDEXED BY
                                       DEDTB-IDX
                                       DEDTB-NEXT-IDX.
  03  PLAN-TYPE            PIC XX.
      88  PLAN-TYPE-DEDUCTION       VALUE '00'.
      88  PLAN-TYPE-HEALTH          VALUE '10' THRU '19'

...
  03  DEDCD                 PIC X(10).

This is saying that you can have 500 deductions total for a pay run for any pay calendar. And if you exceed the 500, PSCDEDTB is going to start quietly replacing them. If you require a larger number of deductions, you want to replace the DEDUCTION-COUNT-MAX VALUE and DEDUCTION-TABLE OCCURS values of 500 with larger values.

PeopleSoft has built the Payroll system so that it runs under DOS; and with DOS there are severe memory constraints. Under MVS/DB2, OS/2, or UNIX, the memory constraints effectively go away. Increasing these two 500s to 999s, for example, isn’t going to cost you anything other than storage, and on non-DOS platforms, storage is usually readily available.

This type of modification is not particularly difficult to deal with when you upgrade to a new Payroll for North America release. When you upgrade, PeopleSoft delivers a whole new set of source. At that point, you use your installation Compare utility to compare the new source we send you with the old source.

The code in the previous example is a piece of the copy section called PSCDEDT1, and when you run the Compare utility, you’ll see that the new incoming source for PSCDEDT1 contains different values. You’ll probably just decide to retain your change to the code.

Input Programs

PeopleSoft input programs are similar to the table access programs. The input programs access employee-level payroll data and store it in arrays. For example, during pay calculation, an input program called PSPEARRY fetches all pay earnings records for an employee and stores them in an array called EARRY.

Understanding Input Programs

The situation is a little different than with the table access programs, because here, to take earnings as an example, before the system can process a given pay run for an employee, it needs to store all the employee’s earnings for that payroll in memory. These earnings are taken from the PAY_EARNINGS table and the PAY_OTH_EARNS table.

It’s similar with deductions and with a number of other types of employee-level data. All the relevant employee data must be stored in memory for processing to take place.

Such data is stored in Employee Storage Arrays. As delivered in vanilla Payroll for North America, these arrays, as the ones for pay process data, might not be sufficiently large to run your processes. But if they’re too small and you overflow the array, the system creates a message for that check, to the effect of, “We haven’t got enough space to store the earnings for this employee.” And the system bypasses processing of that check.

Increasing the Occurs Count

If you need more memory space in your Employee Storage Arrays, you can perform a modification similar to the modification of the table access programs we’ve already discussed.

For example, we deliver the Earnings Array with an EARNINGS-COUNT-MAX of 300. That is, you can have up to 300 pay earnings and other earnings for an employee on a check; if you need more, you’ve got to increase the number.

Here’s the relevant code from PSCEARRY:

EARNINGS-COUNT          PIC 9999                COMP.
    88  EARNINGS-COUNT-MAX              VALUE 300.
02  EARNS-LIMIT-COUNT       PIC 99                  COMP.
    88  EARNS-LIMIT-COUNT-MAX           VALUE 25.        
02  EARRY-ERNTB-START-PTR   PIC 9999    VALUE 1     COMP.
02  EARNINGS-DATA                       OCCURS 300
                                            INDEXED BY
                                            EARRY-IDX
                                            EARRY-SPEC-IDX
                                            EARRY-PREV-IDX
                                            EARRY-NEXT-IDX.
    03  ERNTB-PTR           PIC 9999                COMP.
    03  ERNCD               PIC X(10).
    03  ADDL-NO             PIC 999                 COMP.

You can increase the values of 300 up to 999.

Utility Programs

Payroll for North America includes a series of utility programs that are called by the COBOL business processes that make up the payroll processes.

This section discusses:

• PTPDTWRK utility

• PSPANNLZ utility

PTPDTWRK Utility

PTPDTWRK is a date manipulation routine used for various date functions:

PSPANNLZ Utility

PSPANNLZ annualizes and deannualizes amounts. The input consists of:

• Amount. What amount is for (for example, weekly, or monthly).

• Old frequency type (for example weekly, or monthly).

• Old frequency factor.

  If this value is supplied as zero, then the value will be determined from the old frequency type.

• New frequency type (for example weekly, or monthly.

• New frequency factor.

  If this value is supplied as zero, then the value will be determined from the new frequency type.

The output is the amount relating to the output format.

Processing Programs

Processing programs do the actual work. PeopleSoft strongly recommends that you limit your modifications of processing programs to the following types:

• Inserting special earnings and deduction calculation routines in the specific places we’ve allotted for them.

• Cloning standard PeopleSoft code and using it as the basis for any modifications that you have to make.

Selected Processing Programs

This table describes selected processing programs:

Special Deduction Calculation Routines

To write your own code to calculate a deduction:

1. On the General Deduction table, select Special Deduction Calculation in the Deduction Calculation Routine field.

2. Insert the code in the SPECIAL-DEDUCTION-CALC section of PSPDEDTN.

The following example shows the SPECIAL-DEDUCTION-CALC section from the Deduction Calculator, PSPDEDTN:

IF CALC-DED-YES OF W-SW
     EVALUATE TRUE
           WHEN DED-CALC-AMOUNT
              ...
           WHEN DED-CALC-PCT-TTL
           ...
           WHEN OTHER
               PERFORM DG200-SPECIAL-DEDUCTION-CALC
      END-EVALUATE
      ...
/***********************************************************
        DG200-SPECIAL-DEDUCTION-CALC SECTION.
 *SPECIAL CALCULATION ROUTINES IDENTIFIED BY DEDUCTION CODE*
/***********************************************************
           MOVE ZERO TO WK-AMT OF W-WORK.
     SPECIAL-DEDUCTION-CALC-EXIT.

Notice that we’ve taken out a number of pieces of code for this example (indicated by the ellipses, “...”). Essentially, the first part consists of a series of WHEN statements that typically take care of all the PeopleSoft radio buttons on the General Deduction Table page. Then, if none of the radio buttons are true, PSPDEDTN goes ahead and performs the special deduction calculation routine DG200.

Further on in the program, the example shows the DG200 special deduction calculation routine supplied with vanilla Payroll for North America: MOVE ZERO TO WK-AMT OF W-WORK. (If, before modifying PSPDEDTN, you’ve ever clicked on Special Deduction Calculation and run a pay calculation just to see what happens, you know that it always comes out with a zero. Now you know why).

So this is where you put all your special deduction calculation routines.

Special Earnings Calculation Routines

To write your own code to calculate an earnings type:

• On the Earnings Table - Calculation page, select the Special Calculation Routine check box.

• Insert the code in the SPECIAL-EARNINGS-CALC section of PSPECALC.

Cloning Code for Your Modifications

If you’re thinking of inserting special calculations for deductions or earnings, PeopleSoft recommends that you first make a thorough study of DEDTN and ECALC, so that you get a feel for how these programs make their calculations, read flags, get their amounts, and so on.

The easiest way of implementing a special routine is to clone some piece of PeopleSoft code. For example, take out the health insurance calculation, play with it all you want, then plug it back into the Special Deduction Calc section. Ideally, when the time comes to do an upgrade, all your modifications are isolated in this section. Then, assuming that the way we did the new DEDTN is the same as the way we did the old DEDTN, make your special calculation routine and insert it into the Special Deduction Calc section in the new release.

Alternatively, of course, instead of cloning some of our code, modifying it, and inserting it into the Special Deduction Calc section, you can modify the appropriate section of our code that actually performs a given calculation. Just be sure to document your modifications carefully and clearly, with plenty of comments that document your reasoning behind the modification. As long as you ensure that the modified code stands out clearly when you do an upgrade, you’re usually able to post the same change into our new application.

See Also

Defining Deductions

Defining Earnings Codes and Earnings Programs

Output Programs

PeopleSoft output programs typically maintain balance tables, including year-to-date balance tables; they also maintain current pay result tables.

Selected Output Programs

This table describes selected output programs:

Do You Really Want to Modify the Output Programs?

If you’re looking at modifying some of the output programs, we recommend you take another look at that requirement. Changing deduction and earnings calculation rules is one thing. It is reasonable to expect that you might have business requirements necessitating such modifications. But changing the balances the system maintains is another thing. If you’re seriously contemplating that type of change, then talk with your PeopleSoft Account Executive.

PeopleSoft SQL API for Batch COBOL

This section discusses:

• PeopleSoft SQL API for batch COBOL.

• Interface.

• Setup list.

• Data list.

• SQL restrictions/limitations.

• Interface data.

• Dynamic SQL interface.

PeopleSoft SQL API for Batch COBOL

The purpose of PeopleSoft SQL API is to enable PeopleSoft batch COBOL programs to execute SQL commands and control the SQL environment.

Features

These are the features:

• Predefined SQL statements are stored outside of the COBOL program and are identified by name.

• SQL statements are executed dynamically.

• Multiple (up to 254) SQL cursors are available.

• The SQL interface is invoked from the application COBOL program from CALL with parameters.

• Support is provided for SQL statements built dynamically by COBOL programs.

Functions

These are the functions:

• Process Select Statement.

• Fetch Row.

• Process Update Statement: DELETE, INSERT, and UPDATE.

• Commit Run Unit.

• Clear Common Statement (after program CANCEL).

• Disconnect Cursor.

• Disconnect All Cursors.

• Process Fatal Application Error.

Interface

SQL API services are provided through CALLs to program PTPSQLRT, which provides a consistent application interface for COBOL programs running on a variety of database platforms. The call has this general form:

CALL 'PTPSQLRT' USING action,
                      sqlrt,
                      cursor,
                      statement,
                      bind-setup,
                      bind-data,
                      select-setup,
                      select-data

The actual list of parameters that are needed depends on the action requested. For example, a SELECT statement requires all of the previous parameters, while a FETCH action requires only the first three. Only the first two parameters are required in every case. The following table identifies the parameters, the order coded, and the functions for which they are required:

Note. Parameter descriptions are provided in the next topic in this section.

Communication Area

To use the SQL interface, copy PTCSQLRT into the WORKING-STORAGE topic of the main program and pass this 01-level data to all sub-programs using the SQL interface. This member defines data needed by the SQL interface and supports communication between the SQL interface and the application program.

Parameter Descriptions

The following is a list of parameter descriptions.

1. Action

This is a one-character code representing one of the eight functions supported. Use one of the data names with pattern “ACTION-” from copy member PTCSQLRT.

Example

ACTION-SELECT OF SQLRT

These are the actions provided:

2. SQLRT

This is the 01-level of data division copy member PTCSQLRT and is used to send and return several sub-parameters and to provide work space.

The individual elements in PTCSQLRT are described in the topic Interface Data.

3. Cursor

This is a four-digit computational number representing a resource connection unit. Copy data division SQLRT contains a common cursor for use when resources do not have to be saved for reuse.

Examples

SQL-CURSOR-COMMON OF SQLRT
SQL-CURSOR OF S-CHECK

4. Statement

The 18-character name of a stored SQL statement must conform to the following pattern:

Example

01  S-CHECK.
  02  STMT-NAME      PIC X(18)   VALUE ‘PSPRPRNT_S_CHECK’.


CALL ‘PTPSQLRT’ USING ACTION-SELECT OF SQLRT
                      SQLRT
                      SQL-CURSOR-COMMON OF SQLRT
                      STMT-NAME OF S-CHECK
....

5. Bind-Setup

This is a list of descriptors for the data that is used by the SQL statement in the WHERE, HAVING, SET, and VALUES clauses. These descriptors tell the API the sizes and types of the corresponding bind variables. The descriptors exactly match the memory layout of the bind variables themselves. Setup strings are the same for both bind and select setup lists.

For details, see the topic Setup List.

Example

BIND-SETUP OF S-CHECK

6. Bind-Data

This is a list of data elements defined by BIND-SETUP and is described subsequently for both bind and select data lists.

Example

BIND-DATA OF S-CHECK

7. Select-Setup

This is a list of specifications for the data that is returned by the SQL statement - SELECT.

For details on both bind and select setup lists, see the topic Setup List.

Example

SELECT-SETUP OF S-CHECK

8. Select-Data

This is a list of data elements defined by SELECT-SETUP. Setup lists are described in the following section for both bind and select data. Select-Data is the buffer area into which data is returned by the Fetch action. Be sure to initialize this area before each Fetch, because character fields are not blank-filled on all platforms. If you do not clear the buffer, a short character value might only partially replace a longer value from a previous fetch.

Example

SELECT-DATA OF S-CHECK

Setup List

A setup list is a string of codes, terminated with a “Z,” fully specifying both the logical and physical characteristics of the data elements in a Data List. Specifications include data type, physical data storage bytes, and decimal places for decimal numbers. Each data element is specified with a character string whose length represents the actual bytes of storage the data element occupies and whose value includes data type codes and decimal positions. All data types except decimal numbers use alphabetic characters preceded a number or special character. Consecutive data elements of the same type alternate one of the two characters representing the data type.

The following table summarizes information for the data types supported:

Examples:

Data List

This is a list of data elements with COBOL name and pictures. The list must be concluded with a one-character filler containing the value “Z.” The Setup List and the Data List must be equal in length.

SQL Restrictions/Limitations

SQL statements must conform to a subset of ISO/ANSI standards common to all vendors. The basic standard used is DB2:

• Use only statements SELECT, DELETE, INSERT, and UPDATE.

• Always use the Fetch Function following a Select Statement, even when only one row is expected.

• No SELECT INTO.

• No SELECT FOR FETCH ONLY.

• LONG VARCHAR columns are not supported.

• Program (Host) variables must be preceded by a colon (“:”) and represented by numbers ascending from 1 (one) without gaps in the order of specification within the statement and without repetition of any number.

• Code the stored SQL name for the select as the cursor name when using DELETE or UPDATE with positioning. For example: WHERE CURRENT OF CURSOR PSPRPRNT_S_CHECK

  Note. A separate SQL select with FOR UPDATE OF must be coded for DELETE and UPDATE with positioning in DB2.

• The internal (COBOL) select list might be shorter than the external (SQL) select list. Only those columns identified internally are retrieved. An example where this is useful is the requirement that ORDER BY columns be included in the select list. Add the columns to the end of the SQL select list, but do not include in the COBOL source.

Interface Data

COPY member PTCSQLRT contains the following sub-parameters:

Dynamic SQL Interface

If it is necessary for the application program to construct SQL statements on the fly at run time, the BIND-SETUP and SELECT-SETUP methods of describing bind and select data are not appropriate. For this case, the SQL API provides an alternative interface in which the bind and select data items are passed in arrays of descriptors, with a data type, length, and pointer for each item. When using this interface, the CALL interface is different:

CALL ‘PTPSQLRT’ USING action,
                      sqlrt,
                      cursor,
                      statement,
                      bind-table,
                      bind-table[place-keeper],
                      select-table

The parameters correspond to the CALL used for executing predefined statements, but different values and formats for the following parameters indicate that this is a dynamic statement.

1. Action

This is a one (1) character code that indicates the type of statement. Use one of the data names with pattern “ACTION-” from copy member PTCSQLRT.

Example

ACTION-SELECT OF SQLRT

These are the dynamic actions provided:

Other actions, such as ACTION-FETCH, use the same calls as for predefined SQL, as documented previously.

2. SQLRT

This is the 01-level of copy data division PTCSQLRT used to send and return several sub-parameters and to provide work space.

The individual elements in PTCSQLRT are described in the “Interface Data” topic previously.

3. SQL-Cursor

A four (4) digit computational number that represents a resource connection unit. Copy data division SQLRT contains a common cursor for use when resources do not have to be saved for reuse.

Examples

SQL-CURSOR-COMMON OF SQLRT
SQL-CURSOR OF S-CHECK

4. Statement

The first three characters of the statement parameter are used to determine if the current statement is a dynamic statement, rather than the name of a predefined statement.

These are the allowable dynamic statements:

SELECT
INSERT
UPDATE
DELETE

5. Bind-Table

Use this parameter to specify a table form of bind setup information. This has the same format as the following Select-Table.

6. Bind-Table (place-keeper)

Because the bind data is supplied through pointers, the address of a bind data area is not applicable to dynamic calls. However, you must pass a parameter as a place-keeper, so provide the bind table a second time.

7. Select-Table

Use this parameter to specify the table form of select setup information. The first character indicates that the table form of setup list is in use. The SETUP-COUNT variable gives the number of entries, that is, the number of bind or select items. Each SETUP-ENTRY gives the address, length, scale (number of decimal places), and type of the corresponding data field.

       01  SQLSI.
           02  SETUP-FORM            PIC X.
               88  SETUP-FORM-TBL               VALUE 'Y'.
           02  SETUP-COUNT           PIC 999              COMP.
               88  SETUP-COUNT-MAX              VALUE 100.
           02  SETUP-ENTRY                      OCCURS 100
                                                    INDEXED BY
                                                    SQLSI-IDX.
               03  SETUP-DATA-PTR                           POINTER.
               03  SETUP-LENGTH      PIC 999              COMP.
               03  SETUP-SCALE       PIC 99               COMP.
               03  SETUP-TYPE        PIC X.
                   88  SETUP-TYPE-CHAR          VALUE 'C'.
                   88 SETUP-TYPE-SMALLINT       VALUE 'S'.
                   88 SETUP-TYPE-INT            VALUE 'I'.
                   88 SETUP-TYPE-DEC            VALUE 'P'.
                   88 SETUP-TYPE-DATE           VALUE 'D'.
                   88 SETUP-TYPE-TIME           VALUE 'T'.

Flexible Field Lengths

This section discusses:

• Flexible field lengths.

• Character fields.

• Number fields.

Flexible Field Lengths

Payroll for North America provides some flexibility of redefining the lengths of certain fields. Whenever you redefine field lengths, you should exercise caution. Because the batch programs used by the system expect certain fields to be the lengths defined in the standard as-shipped application, you should be careful not to increase those field sizes beyond the maximums allowed. Otherwise, you might have to modify the batch programs to reflect the changes.

This section provides a list of the maximum field sizes expected by specific PeopleSoft applications.

Note. For fields that aren’t listed here, the applications are programmed to process the length defined in the standard product as the maximum length.

Character Fields

In many cases, Payroll for North America batch programs are designed to process larger-than-standard character field sizes. They can always process smaller-than-standard field sizes. Here’s an alphabetical list of the maximum field sizes allowed for character fields used by Payroll for North America programs:

Number Fields

As with character fields, with certain decimal fields the batch programs in Payroll for North America can accommodate field sizes larger than those defined in the standard application. Here’s an alphabetical list of the maximum field sizes allowed for decimal fields:

Data Input Requirements for a Paysheet Update Source of Other Sources

When you use the Load/Reset Paysheet Trans COBOL SQL process (PSPPSHUP) to load paysheet entries from the record PSHUP_TXN with a paysheet update source (PU_SOURCE) of Other Sources (OT), the following transaction types are supported:

• C - Canadian tax override

• D - deduction override (benefit/general deduction overrides; excludes garnishments)

• E - earnings

• T - U.S. tax override

• G - total gross

• N - net pay

The Load/Reset Paysheet Trans process bypasses paysheet transactions for inactive employees.

The paysheet load holding record (PSHUP_TXN) must contain valid transactions that do not result in payroll error messages. For example, when a manual check is loaded with a paysheet update source of Other Sources, transactions for the related total gross and net pay transaction types must also be provided as follows:

• A total gross transaction for each manual check when the total gross is not zero.

• A net pay transaction for each manual check when the net pay is not zero.

The following table provides the data input requirements for a paysheet update source (PU_SOURCE) of Other Sources for each of the supported transaction types. Failure to follow the recommended setup may result in unpredictable pay data.

See Also

Loading Paysheet Transactions