Payroll for North America COBOL Program Types
This topic discusses:
COBOL program naming conventions.
Run control programs.
Main programs.
Table access programs.
Input programs.
Utility programs.
Processing programs.
Output programs.
All Payroll for North America COBOL programs have eight-character names that begin 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, as described below:
COBOL Prefixes
PSP = COBOL source (P stands for Program).
PSC = Regular COBOL Copy code.
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 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:
|
Run Control Program |
Online Process Name |
|---|---|
|
PSPPYBLD |
Create Paysheet |
|
PSPPYRUN |
Calculate Payroll |
|
PSPDCRUN |
Calculate Deductions |
|
PSPCNFRM |
Confirm Payroll |
|
PSPDCCNF |
Confirm Deductions |
|
PSPUNCNF |
Unconfirm Pay |
|
PSPDCUNC |
Deductions Unconfirm |
|
PSPCLBLD |
Calendar Build |
|
PSPDLBAL |
Delete Balances (U.S.) |
|
PSPDLBLC |
Delete Balances (Canada) |
|
PSPRPRNT |
Reprint Checks |
|
PSPPYREV |
Reversal Processing |
|
PSPACCRL |
Leave Accrual |
|
PSPPFUND |
Actuals Distribution |
|
ENC_CALC |
Batch Encumbrance Calculation Process |
|
EGPPRCTL |
Tenure/Flexible Service Calc'n |
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).
The main COBOL programs are called by most run control programs to process one pay calendar:
|
COBOL Program |
Run Control Program |
|---|---|
|
PSPPYSHT |
Create Paysheet |
|
PSPPYCAL |
Pay Calculation (U.S.) |
|
PSPCPCAL |
Pay Calculation (Canada) |
|
PSPDCCAL |
Calculate Deductions |
|
PSPPYUPD |
Pay Confirmation |
|
PSPPYUNC |
Unconfirm Pay |
|
PSPCKREV |
Reversal Processing |
|
PSPACCPR |
Leave Accrual (U.S.) |
|
FGPACCRL |
Leave Accrual (USF) |
|
PSPPFDST |
Actuals Distribution |
|
No main program |
Tenure/Flexible Service Calc'n |
|
No main program |
Savings Management Balances |
|
No main program |
Batch Encumbrance Calculation Process |
|
No main program |
Confirm Deductions |
|
No main program |
Calendar Build |
|
No main program |
Delete Balances (U.S.), Delete Balances (Canada) |
|
No main program |
Check Reprint |
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.
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:
|
Table Access Program |
Description |
|---|---|
|
PSPERNTB |
Earnings Table Manager |
|
PSCERNTB |
Earnings Table Copy Section Manager |
|
PSPDEDTB |
Deduction Table Manager |
|
PSCDEDT1 through PSCDEDT6 |
Deduction Table Copy Section Manager |
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-TABLEOCCURS 500 INDEXED BY DEDTB-IDX DEDTB-NEXT-IDX. 03 PLAN-TYPEPIC 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.
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 1000. That is, you can have up to 1000 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 1000.02 EARNS-LIMIT-COUNT PIC 99COMP. 88 EARNS-LIMIT-COUNT-MAX VALUE 25. 02 EARRY-ERNTB-START-PTR PIC 9999 VALUE 1 COMP.02 EARNINGS-DATA OCCURS 1000 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 1000 up to 9999.
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 topic discusses:
PTPDTWRK utility
PSPANNLZ utility
PTPDTWRK Utility
PTPDTWRK is a date manipulation routine used for various date functions:
|
Date Function |
Description |
|---|---|
|
D |
Date difference. How many days between? |
|
A |
Add days to a date. |
|
G |
Age. How old is this employee? Used for deduction calculations. |
|
W |
Days of week. Used for Canadian weeks/calendar build. |
|
K |
Work days. |
|
M |
Month difference. Used for deduction calculations. |
|
C |
Converts microseconds to hours, minutes, seconds, and microseconds. |
|
L |
Calculates leap days. |
|
T |
Calculates the difference between two date/time entries in seconds. |
|
I |
For future use. |
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 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:
|
Processing Program |
Description |
|---|---|
|
PSPECALC |
Earnings Calculator |
|
PSPDEDTN |
Deduction Calculator |
|
PSPTCALC |
U.S. Tax Calculator (PeopleSoft-maintained) |
|
PSPXCALC |
Canadian Tax Calculator (PeopleSoft-maintained) |
Special Deduction Calculation Routines
To write your own code to calculate a deduction:
On the General Deduction table, select Special Deduction Calculation in the Deduction Calculation Routine field.
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-CALCEND-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 selected 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.
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:
|
Output Program |
Description |
|---|---|
|
PSPCBUPD |
Maintains balance table |
|
PSPDBUPD |
Maintains balance table |
|
PSPCUPDT |
Maintains current pay result table |
|
PSPTUPDT |
Maintains current pay result table (PSPXUPDT for Canada) |
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.