            EMPLOYER SPONSORED PENSION BENEFIT PLANS
                                
                                
                                
                                
                                
                                
            PENSION ESTIMATION PROGRAM DOCUMENTATION
                       Richard T. Curtin
                                
                  Modified for use with PCs by
                          Jody Lamkin
                                
                                
                                
                                
                                
                                
                                
                                
                     Survey Research Center
                     University of Michigan
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                THE UNIVERSITY OF MICHIGAN, 1996
                                                                
                       TABLE OF CONTENTS
                                
                                
Program Overview  .  . .  . .  . .  . .  . .  . .  . .  . .  . .      1

Program Execution Commands  .  . .  . .  . .  . .  . .  . .  . .      2

Input Files  .  . .  . .  . .  . .  . .  . .  . .  . .  . .      6
     Participant Data  .  . .  . .  . .  . .  . .  . .  . .  . .  . .      6
     Estimation Parameters  .  . .  . .  . .  . .  . .  . .  . .  . .      9
     Pension Plans   . .  . .  . .  . .  . .  . .  . .  . .  . .     14
     Valid Ranges .  . .  . .  . .  . .  . .  . .  . .  . .  . .     15

Output Files .  . .  . .  . .  . .  . .  . .  . .  . .  . .     18
     Data Files . .  . .  . .  . .  . .  . .  . .  . .  . .  . .     18
 
Pascal Program Source Files .  . .  . .  . .  . .  . .  . .     22
     PP4.0 Source Code .  . .  . .  . .  . .  . .  . .  . .  . .     22
     Procedures Source Code .  . .  . .  . .  . .  . .  . .  . .     22
     Utilities Source Code  .  . .  . .  . .  . .  . .  . .  . .  . .     22

Documentation Files  . .  . .  . .  . .  . .  . .  . .  . .  . .     23

System Requirements and Limits . .  . .  . .  . .  . .  . .  . .  . .     24

Enhancements and Fixes .  . .  . .  . .  . .  . .  . .  . .  . .     25

Calculation Error Codes.  . .  . .  . .  . .  . .  . .  . .  . .     28

Availability of the Pension Provider  .  . .  . .  . .  . .  . .  . .     29

                         LIST OF TABLES
                                
Table 1. Participant Data . .  . .  . .  . .  . .  . .  . .  . .  . .      6

Table 2.  Estimation Parameters  .  . .  . .  . .  . .  . .  . .  . .      9

Table 3.  Valid Ranges for Input Parameter Settings  .  . .  . .  . .  . .     16

Table 4.  Valid Ranges for Participant Data Variables   . .  . .  . .  . .     17

Table 5.  Output Data File for Entitlement Estimates Based on Actual Participant Data
                with Given Quit Date  .  . .  . .  . .  . .  . .  . .  . .     20

Table 6. Output Data File for Entitlement Estimates Based on Simulated Participant
               Data  . .  . .  . .  . .  . .  . .  . .  . .  . .  . .     20

Table 7. Output Data File for Entitlement Estimates Based on Actual Participant Data
               Using All Potential Quit Dates . .  . .  . .  . .  . .  . .  . .     21

                        PROGRAM OVERVIEW
                                
     This program is designed to estimate the pension entitlements held by respondents in
the 1989 Survey of Consumer Finance (SCF), the 1989 National Longitudinal Study of Mature
Women (NLS) and the Wave 1 Health and Retirement Study (HRS), based on the plan
formulas and benefit provisions obtained from the linked sample of pension providers.  The
pension program uses systems of equations to represent each of the pension plans, including all
benefit formulas and payment  provisions.  These equations, in turn, use as input the work and
income histories of the  respondents.  When combined with assumptions needed for the
estimation of the present  value of future benefit flows, the program calculates the appropriate
pension entitlements,  and prepares output data files for subsequent analysis.
     Program users have complete control over the input data and estimation parameters, 
providing the capability of a wide array of analytic strategies.  Estimates can be made for  any
set of respondent employment characteristics, whether based on the actual survey data or 
simulated profiles.  The pension entitlements due from any one or from every pension plan 
can be calculated.  The program provides estimates of all types of retirement benefits-normal 
retirement, early retirement, late retirement, disability retirement, and surviving spouse 
benefits.  Care should be exercised in the interpretation of disability benefits.  These are
benefits paid solely from the pension plan.  The firm may have other longterm disability plans,
and these are not analyzed in arriving at the stated disability benefit.  The date of employment
termination-which must be assumed for most participants  since they were still working at the
time of the survey-can be set or limited to any given age  range or calendar dates.  In addition
to estimates based on a single quit date, the program  can also produce an estimate of the
benefit amount due at every age from the time of the  survey until the participant reaches the
maximum quit age allowed.  These yearly estimates  cover all types of retirement, disability
and survivor benefits.
     This document describes the program, and defines user commands and analysis 
options.
                   PROGRAM EXECUTION COMMANDS
     The Pension Provider application is actually 2 computer programs that work together. 
1) the pension plans procedures generation program (Gen95.exe) and 2) the pension plan
calculation program (Calc95.exe).  There is also a third program used to integrate the
Gen95.exe output into the Calc95.exe source code, this is Integ95.exe.
     The Gen95 program has 2 required command line parameters, 1) the Osiris dictionary
file name (DictFileName) and 2) the pension data survey file name (DataFileName).  The
included OSIRIS dictionary file, PENDAT.NEW, is applicable to the SCF, the NLS and the
HRS studies.  The command line syntax for the Generate program is:
     Gen95 DictFileName DataFileName
From the dictionary and data files Gen95.exe produces two Pascal cases lists (Cases.pas and
Cases2.pas) and one Pascal procedures (Procedur.pas) files.  These three files are Pascal
source code statements.
     The program Integ95.exe is used to insert the Cases.pas and Cases2.pas files into the
source code of the evaluation unit of the Calculate source code.  It also splits the procedures in
the file Procedur.pas into units (files) that are small enough to be compiled by Borland Pascal
and adds the names of the procedure files to the list of compilation units. 
The Integ95.exe command line syntax is:
     Integ95 OriginalEvalUnitName OutputEvalUnitName ProceduresFileName
     CasesFileName Cases2FName
Since all of the files used by the Integ95.exe program are produced by the Gen95.exe or used
by the Calc95.exe program, unless the user changes the Gen95.exe output file names and
modifies the Calc95.exe source code files the following call to Integ95.exe can always be used:
     Integ95 Eval95.pas Evalu95.pas Procedur.pas Cases.pas Cases2.pas
Once Integ95.exe has been run the calculation program source code can be compiled to create
Calc95.exe.
     The Calc95 program uses 6 or 7 command line parameters, 1) the run type value, 2) the
participant characteristics data file, 3) the parameters file, 4) the pension plans file (RUNTYPE
4.2 ONLY), 5) output data file, 6) the output table file and 7) the output errors file.  Valid
values for parameter #1, the run type (RUNTYPE) are:
     1.2  when the input is actual respondent and spouse data, which is to be matched to 
          the specific employer sponsored pension plans in which they participate, with all
          estimates based on an assumed quit date.  This run type produces present values
          and annuities, the others produce only annuities.

     3.2  when the respondent and spouse data is matched to the specific plans in which
          they  participate, but no single quit date is assumed.  Instead of one estimate,
          this program option produces the estimated pension entitlement that would
          accrue if the participant quit for each year from the minimum quit date to the
          maximum quit date.  The min and max quit date ranges are calculated from the
          quit age and date ranges and the survey date set in the INPARM file, and the
          date the participant reaches age 80, with a maximum of 55 quit date years of
          calculations.  This output thus gives the profile over time of potential pension
          entitlements depending on the date of  job termination.

     4.2  when the input data is for simulated participant income and work histories.  The
          simulated data (participant characteristics) in the INDATA.SIM file may include
          up to 5 data sets to run the plans on.  For each set of simulated participant
          characteristics, the benefit entitlement that would be due under every pension
          plan included in the INPLAN file is calculated. This option requires an assumed
          quit date.  Any number of plans may be used, provided that the plans listed
          were compiled into the Calulate program.

Parmeter #2, is the participant input data file (INDATA[.SIM]).  Parameter #3 is the user
defined parameters file (INPARM).  Parameter #4, the pension plans file is only used for and
is required for run type 4.2 (INPLAN).  Parameters #5, #6 & #7 are the output files
(OUTDATA, OUTTAB, & OUTERR).
The Calc95.exe command line syntax is, [ ] signify the optional parameter:

     Calc95 RunType InputDataFile InputParameterFile [InputPlanFile] OutputDataFile
     OutputTableFile OutputErrorFile

Later in the documentation you will see the Calc95.exe parameters defined, the names used for
these parameters will be RUNTYPE, INDATA, INPARM, INPLAN, OUTDATA, OUTTAB
and OUTERR.  RUNTYPE is defined above, the others are files.
     The following is an example of the commands needed to run a complete session
(Generate, Integrate, Compile and Calculate for each runtype):
     GEN95 DICTFILE.SCF DATAFILE.SCF
     INTEG95 EVAL95U.PAS EVALU95U.PAS PROCEDUR.PAS CASES.PAS CASE2.PAS
     BPC /GD /B /CP /$N+ /$E+ CALC95
     DEL EVLP*.*
     CALC95 1.2 INDATA.SCF INPARM.SCF OUTDATA1.SCF OUTTAB1.SCF OUTERR1.SCF
     CALC95 3.2 INDATA.SCF INPARM.SCF OUTDATA2.SCF OUTTAB2.SCF OUTERR2.SCF
     CALC95 4.2 INDATA.SCF INPARM.SCF OUTDATA3.SCF OUTTAB3.SCF OUTERR3.SCF

Descriptions of the previous example command lines:
1) Run the generate program with dictionary file DictFile.scf, and data file DataFile.scf.
2) Run the program to integrate the Pascal source code output by Gen95.exe into the calculate
program source code.
3) Compile the calculate program with Borland Pascal as a DOS Protected Mode program.
4) The DEL EVLP*.* command deletes the unit (.pas) and object (.tpp) files that were created
from Procedur.pas by Integ95.exe and the Borland Pascal compiler BPC.exe, respectively.   
5, 6 & 7) These are runs of the calculate program Calc95.exe, for the 3 run types, 1.2, 3.2 and
4.2.  See run type descriptions above.
The Evlp*.* files and the files Procedur.pas, Cases.pas and Cases2.pas may be deleted after
compilation of the calculation program for the current data set, which will free up some disk
space.  If they are deleted before the calculate program, Calc95.exe, is successfully compiled
the generate program (Gen95.exe) will need to be rerun on the same files to create them again. 
Any questions regarding printing of these output files should be directed to the users computer
support person.  The input and output file names for both the generate and calculate programs
are unimportant as long as they meet the DOS file name requirements, see your computer
support person if you do not know the DOS file name requirements.  Bear in mind that if you
run multiple calculate sessions at a time, as in the previous example, you should name the
output files differently for each session to avoid having the earlier files be overwritten.  Unlike
the MTS version of the calculate program, multiple data sets cannot be stored in 1 file with
Calc95.exe being instructed to start processing at a specified line number.
           CALCULATE PROGRAM (CALC95.EXE) INPUT FILES
Participant Data
     INDATA represents the file name where participant input data is stored.  The program
expects the input data to be in free format (data values separated by blanks), with one
participant/plan combination per line.  If a respondent was covered by more than one pension
plan, the data should appear on two or more separate lines, each associated with its own unique
pension plan ID.  And since pension entitlements were recorded for both the respondent and
the spouse, a single household record is often the basis of multiple input lines.
     The program treats each line in the INDATA file as a separate case (see Wage History
special case below), and will only calculate estimates for those cases included in this file.  The
number of cases included in the INDATA can be as few as one or as many as the full sample
of participants.  Any subset of participants, in any order, can be selected for inclusion in the
INDATA file.
     The program option RUNTYPE determines the type and order of input data expected
by the program.  When the analysis uses the actual household data, the program expects each
data line to begin with the IDs which identify the specific pension plan which covers the
participant.  When the program uses simulated participant data, these ID variables are not
allowed since estimates are calculated for all pension plans listed in the INPLAN file.
     In addition to the data necessary to calculate pension entitlements, the input data file
can also contain additional variables that will be added to the output data set.  These "pass
through" variables can be entered in any format, but can not exceed 132 columns in total,
counting blanks.  This option facilitates the easy analysis of the output data file, since there is
often no need to remerge the output data files with the original SCF data files.  The additional
variables are "passed through" to the output data set only when the RUNTYPE is designated
for actual household data with a given quit date (RUNTYPE 1.2). The other RUNTYPEs
ignore the presence of the "pass through" data in the input files.
     Each line in the INDATA file must list the input variables in a fixed order, separated
  by blanks.  If Wage Histories for the participants are used the INDATA file will have 2 or
more lines per participant.  The first line is the standard data and "pass through" variables, the
second and subsequent lines, until the terminator code is reached, are the wage histories.  The
required order and variable definitions are given in Table 1. The first three variables are
optional, depending on the RUNTYPE specified.  These linking IDs are needed when actual
participant data are matched with the specific pension plans under which they are covered
(RUNTYPE 1.2 or 3.2), but are not needed when simulated data is used (RUNTYPE 4.2). The
next to the last variable listed is also optional, and is used to define the "pass through"
variables.  "Pass through" variables are values that are only read in from the INDATA file and
written out to the OUTDATA file.  They affect no other output or calculations.  The "pass
through" variables must fit into 32 characters.  If Wage Histories are used, they will appear on
the next line.

                            Table 1
                        Participant Data
                         (INDATA File)

 Order            
Ĵ   Var               Definition
Act Sim    Name  

 1       HHIDX     SCF household ID.
 2       CODEID    Pension plan ID.
 3       SEQ#      ID of pension plan/provider.
 4   1   SPOUSEBD  Birth date of spouse, if married.
 5   2   SEX       Sex of the participant.
 6   3   BIRTHD    The participant's date of birth.
 7   4   HIRED     The date the participant was hired.
 8   5   QUITD     Date the participant terminates employment.
 9   6   WKHRS     Average annual paid work hours.
 10  7   WAGE      Annual dollar amount of salary and wages.
 11  8   WAGEG     Differential wage growth rate.
 12  9   CRVOL    ...Voluntary contributions.
 13 10   BETA1     Wage growth equation coefficient. NEW '95
 14 11   BETA2     Wage growth equation coefficient. NEW '95
 15      PT        Pass through variables.
 16 12   WAGEHSTS  Optional Wage Histories,max yrs=97.NEW '95


     The SPOUSEBD variable is defined as the marital status of the participant at the
  time of retirement.  If the participant is single at the time of retirement, this variable should
be set equal to zero; if married, the variable should be set equal to the birth date of the spouse. 
The participant's date of birth, date of hire., and quit date are defined as BIRTHD, HIRED,
and QUITD, respectively.  All date variables are entered as real numbers, using decimals to
indicate fractions of years.  For example, April 1, 1965 would be entered as 1965.25, and July
1, 1983 would be entered as 1983.50. The sex of the participant was defined as one for males,
and two for females.
     The WKHRS variable is defined as the average annual number of paid work hours
  over the relevant horizon for pension calculations.  The major impact of the WKHRS variable
is in determining the accrual rate for service credit.  This variable should be set to the average
number of hours worked per year, counting all paid vacation, holiday, and sick time.  For a
full time worker, this would usually be 2,080 hours per year.
     The WAGE variable is defined as the annual amount of salary and wages covered under
the pension plan as of the time of the survey if the participant was still employed, or wage
level in the final year of employment if the participant had already terminated employment but
had not yet begun to receive retirement benefits.  From this base level, two separate income
growth factors are applied to calculate the level of WAGE over time.  The first income growth
factor is specified in the input parameter file.  This parameter is defined as the overall average
real rate of growth in wages, and is applied to all participant data.  The second income growth
factor, specified in the input data file, is designed to capture differences in growth rates across
population groups.  The input variable WAGEG is defined as the deviation from the overall
mean for specific participants, given their age, income and employment histories, and other
factors.  Since the WAGEG variable can be constructed so as to sum to zero across all
participants included in the analysis, the overall total rate of income growth can be fixed via
the input parameter file.
     The CRVOL variable is defined as the amount of voluntary contributions made by the
participant, expressed as a percentage of the participant's annual wages.  For participants that
do make voluntary contributions, the CRVOL variable defines the average yearly contribution
rate over the time horizon used for pension calculations.  For pension plans that require
contributions from participants, the mandatory contribution rates are built into the pension
program, and thus do not need to be specified in the input data file.
     The BETA1 and BETA2 values are the coefficients to be plugged into the new wage
calculation formula.  The new wage model can be in the Enhancements and Fixes section of
this document.
     The WAGEHSTS variables are optional, a new flag is provided in the INPARM file to
define if wage histories are being used.  The wage history ALWAYS starts on a new line
following the participant data values, this allows for the pass through variables to remain
where they currently exist, at the end of the main data line.  The format for the wage histroy
variables is as follows:  the first value is the year the wage history starts, the second value is
the year the wage histroy ends, the wages for the years included come next, the end of history
marker is a negative number.  If wage histories are supplied, they are expected for all
respondents.  A full wage history for the pension plan firm is not required, the minimum is one
year.  If no history is available for a respondent, the survey date year and the survey date wage
can be used.  See the examples in Enhancements and Fixes section of this document.The wage
history can span more than 1 line.  The end of history marker negative value is required. 
Wage histories are expected to cover only those years the respondent worked for the firm
whose pension plan is being used.  If the first year a wage is supplied for is the hire date year,
the wage is expected to be ONLY the wages earned from the pension plan firm.

Estimation Parameters
     INPARM represents the name of the file which contains the user defined parameters
needed in the estimation process.  The parameter settings must be given in a fixed order on
each line.  Each line must start with the parameter settings and may be followed by a
comment.  Only the parameter settings on each line are read by the program, the rest of the
line is ignored.  The required contents of the INPARM file are shown in Table 2.

                            Table 2
                     Estimation Parameters
                         (INPARM File)


Line   Name         Default                      Definition

  1  SURVEYD          1989.50  Date of survey observations
  2  TODAYD           1989.50  Base date for present value calculations
  3  CPIrate             0.00  Annual inflation rate
  4  INTrate             1.00  Real interest rate
  5  INCrate             0.00  Real wage and salary growth rate
  6  SSWB                0.00  SS wagebase (as of survey date)
  7  SSWBrate            0.00  Real SS wagebase growth rate
  8  SSrate              0.00  Real SS benefit growth rate
  9  QAGErng          16   80  Quit age range (min, max)
 10  QDATErng       1925 2075  Quit date range (min, max)
 11  BENMAX     500000 500000  Maximum benefits (age55, age65)
 12  PROFCON1      5.00  0.50  Contributions (profits, forfeitures)
 13  PROFCON2      5.00  0.50  Contributions (profits, forfeitures)
 14  PROFCON3      5.00  0.50  Contributions (profits, forfeitures)
 15  DISCRE1             0.00  Maximum % discretionary contributions
 16  DISCRE2             0.00  Maximum % discretionary contributions
 17  DISCRE3             0.00  Maximum % discretionary contributions
 18  NACONrate     5.00  5.00  NA contributions (other, mandatory)
 19  NAVOLrng      0.00  0.00  NA CRVOL range (min, max)
 20  NAMATCH    100.00 100.00  % NA matching (MMAN, MVOL)
 21  ANNTYPE       3.00 50.00  Annuity type / % of payment continued
 22  VESTYPE       0.00  5.00  New vesting (1=on/0=off) / Yrs to vest
 23  MRAGE               0.00  Plan maximum retirement (1=on/0=off)
 24  PENTYPE             0.00  Pension type (0=NRT/ERT/VDT/LRT,1=DRT,2=DST)
 25  FYA_PV              0.00  1stYrAnnuity/PresentValue flag, 0=FYA, 1=PV
 26  WAGEHIST            0.00  Wage histories flag, 0=no, 1=yes
 27  NOMIDX              0.00  Nominal Amounts indexing flag, 0=no, 1=yes
 28  BENCOLA      0.00 100.00  Benefits COLA, 0=no, 1=yes; % of CPIrate
 29  TODAYPV             0.00  TODAYD Present Value flag, 0=no, 1=yes


     The first two parameters, SURVEYD and TODAYD, are dates used to set the
program's time reference. The first date, SURVEYD, is used to set the time frame for all input
variables. This date defines the base period data values to which all growth factors are applied
to estimate future trends. The second date, TODAYD, defines the year on which to base the
discounted present value calculations. For most purposes, both these dates should be set to
equal the actual date of the household survey.  If the date for present value calculations is set to
a date later than the survey date, this would result in estimates of the present value of
entitlements for subsequent years.  All growth factors are annual percentage rates of change,
and are defined as the average rate over the relevant horizon for pension calculations. Setting
the nominal rate of inflation along with the real rates of change in the other variables, gives
users the ability to set the overall level of nominal rates of change while preserving real growth
rates. In setting these values, the most important consideration involves the comparative size of
the selected real growth rates for wages and interest rates. The former rate is used to increase
amounts over time, while the latter is used to discount amounts back to the present. Although it
is usually assumed that the former is lower that the latter, the selected size of the difference
will have an important impact on the estimated results.
     All growth rates are entered as average annual percentage amounts-for example, an
annual growth rate of 3.5% is entered as 3.5. A zero real rate of growth yields a nominal
growth rate equal to the rate of inflation. Growth rates may be set to either positive, zero, or
negative values for the rate of inflation, income, and the Social Security wagebase and benefit
amounts; the real interest rate, however, must be set to a value of greater than zero.  This
combination of optional settings allows the easy manipulation of the estimation assumptions, in
a format that focuses the selection on both the nominal and real rates. As part of the program
output, all the nominal rates are calculated and displayed in the file OUTTAB.
     The inflation rate is intended as a common yardstick for assessing changes in all dollar
values over time. The inflation rate selected represents the average rate of price increases over
the entire relevant horizon for pension calculations. The real interest rate variable is defined as
the appropriate rate of discount to use in present value calculations.  The real growth rate of 
income is defined as the average annual increase in salaries and wages received by plan
participants, adjusted for inflation.  Thus, all three variables are similar in that they signify
general concepts, and are not identified with any specific price or wage index, or with a
particular interest rate.  Since an estimate for an extended future time period is often
needed-say over the next 10 to 50 years-these rates should be chosen carefully.  A needlessly
high inflation rate, holding constant real growth rates, will only result in needlessly high
nominal dollar values as the estimation time period lengthens.
     The program options concerning the permissible quit age and date ranges are distinctive
parameters in that they permit the censoring of the input data.  When the maximum specified
quit age is 65, the program will automatically cause all pension estimates to be based on a quit
age of no higher than 65.  If any of the  input data records include a QUITD later than age 65,
the data record will automatically be revised to reflect this age limit.  Similarly, a limit on the
quit date of 1983.5 would cause all pension estimates to be based on quitting as of the date of
the survey.  The minimum quit age/date option can be used to adjust the input data to restrict
the minimum QUITD to age 55, or age 62 for example.  The combined use of minimums and
maximums can adjust all quit dates so that everyone retires at a certain age or on a certain
date.  For example, if all participants were assumed to retire at age 65, both the age minimum
and maximum would be set equal to this age.  Or if all pension entitlements were to be
calculated as though all participants terminated employment as of the date of the survey, the
minimum and maximum dates would be set equal to the survey date.  Various combinations of
quit age and date ranges can be selected to reflect any desired restrictions on the time of
employment termination.  This program option allows greater flexibility in data analysis since
separate input data files are not needed to analyze differences in quit dates.
     The Social Security variables formerly defined the level of the wagebase and benefit
levels as of the date of the survey, as well as the real annual rates of growth in these amounts
over time.  They now only define the level of the wagebase,SSWB; the growth rate of that
base, SSWBrate; and the benefit growth rate,SSrate.  The Social Security wagebase variable is 
the maximum wage and salary income subject to Social Security taxation.  The wagebase
growth rate is the percentage rate of increase for the SS wagebase.  The benefit growth rate is
the benefit COLA adjustment percentage for the SS benefits.  The variables that defined the
benefit levels are no longer needed with the new SS benefit calculation algorithm.  The Social
Security benefit is now calculated using an algorithm supplied by The Wyatt Company.  This
algorithm calculates benefit amounts for those same conditionals -- early/normal,
primary/joint, etc -- as were previously calculated.  The output is no longer based on an
"average" benefit, but based on the respondents wage history.  A list of the INPARM Social
Security variables that are no longer used is the Enhancements and Fixes section.
     The input parameter BENMAX controls the maximum benefit that the program will
allow before truncation.  The maximum is entered in two steps, the first applies to the
maximum amount that can be received at age 55, the second applies to the maximum annual
pension benefit that can be received at age 65.  If the latter maximum exceeds the former, the
maximum is interpolated for retirement ages between 55 and 65.  Of course, both could be set
to a very large value to avoid the use of this truncation parameter.
     For defined contribution pension plans that base contributions on measures of
profitability, the input parameter PROFCON can be used to set the average rate of
contributions over the time period used for pension calculations.  Since some pension plans
incorporate more than one formula that is based on contributions linked to profits, three
separate values can be assigned.  Pension plans with only one profit based contribution formula
would use the variable PROFCON1.  If a second profit based formula was included in the
same plan, PROFCON2 would also be used.  Similarly, PROFCON3 would only be used for
the third profit based formula included in any single pension plan.  Each of the variables is
defined in terms of the proportion of annual wages that these contributions represent.  In
addition, many defined contribution plans also provide for the allocation of forfeitures to
current plan participants.  The amount of contributions from forfeitures can be set in the
INPARM file.  As with the profit link contributions, three separate rates can be set, each
defined in terms of the proportion of annual wages the contributions represent.
     The discretionary contributions, DISCRE1, DISCRE2 and DISCRE3 are matching
contributions, but unlike the profit sharing are based on non financial criteria.
     A few defined contribution plans provided insufficient information to determine the
basis and amount of employer contributions.  For these plans, the variable NACON can be
used to set the rate of contributions expressed as a proportion of annual wages.  A few other
plans had mandatory contributions, but failed to specify the required contribution rate-usually
because the mandatory contribution had been discontinued at some distant point in the past. 
For these plans, the unascertained mandatory contribution rate can be set, using the second
value on the NACON line, defined as a proportion of annual wages.  For plans that did not
specify the permissible range of voluntary contributions, the minimum and maximum rates of
voluntary contributions are determined by the NAVOLrng variable in the INPARM file.  The
minimums and maximums are expressed as proportions of annual wages.  Lastly, a few plans
did not specify the rate at which they would match mandatory or voluntary contributions.  The
matching rates can be set via the NAMATCH variables in the INPARM file.  The rates are
given in percentage terms, with dollar-for-dollar matching expressed as 100.
     The INPARM variable ANNTYPE selects the type of pension annuity the program
calculates.  When ANNTYPE is set to 1, all pension benefits are calculated as single life
annuities; when set equal to 2, all benefits are calculated as two-life annuities; and when set
equal to 3, benefit annuities are calculated as either single or joint life annuities depending on
whether the participant is married-as given in the INDATA file.  If joint life annuities are
selected, the variable CONTPMT gives the proportion of the initial annuity payment continued
after the first death.  All annuity calculations are based on yearly survival probabilities, which
are determined by the sex and birth date of the participant and spouse given in the INDATA
files.
     To allow for changes in pension plan provisions since these data were collected, two
additional options are provided.  The variable VESTYPE in the INPARM file controls the
vesting formulas.  When this variable is set equal to 0 the program uses the original plan
provisions; when set equal to 1, the program substitutes a "cliff" formula, defined by the
VESTYRS variable.  The VESTYRS variable gives the number of years until full vesting
occurs.  The second option allows users to determine whether the plan specified mandatory
retirement age is used.  When the variable MRAGE is set equal to 1 the plan provisions are
used, and when set equal to 0, no mandatory retirement age is used in the calculations.
     The final parameter in the INPARM file selects the type of pension benefit to calculate.
In most instances the PENTYPE variable should be set equal to 0, allowing the plan provisions
to determine the type of retirement benefit based on age, years of service, and so forth.  For
the special cases of disability and survivor benefits, this parameter allows estimation of
benefits under those circumstances.  When the PENTYPE variable is set equal to 1, the
program calculates disability retirement benefits, using the quit date as the date of disablement. 
When the PENTYPE variable is set equal to 2, the program calculates survivor benefits, using
the quit date as the date of the death of the participant.  The PENTYPE option does not affect
RUNTYPE 3.2, since this RUNTYPE is designed to generate estimates of all pension types.
     There are 6 new parameters in the new system, FYA_PV is a flag for the vested
benefits amount output type, the First Year Annuity (the original output type) or the Present
Value.  WAGEHIST is the flag to the use of wage histories. NOMIDX is the flag to Index
Nominal dollar amounts to inflation.  BENCOLA represents two variables, one is the flag to
allow Cost Of Living Adjustment to those plans which do not include a built in COLA, and the
other is the percentage of annual inflation rate (CPIrate) to use in the adjustment.  TODAYPV
is the flag for adjustment to the Present Value calculation in relation to the Today's Date
variable, see the description of enhancement #5 in the Enhancements and Fixes section of the
documentation for more detail.

Pension Plans
     When analysis is based on simulated data cases, the program will generate estimates
under every pension plan listed in the INPLAN file.  The file Inplan.scf  includes all of the
pension plans included in the SCF sample.  Any subset of 5 plans can be included in INPLAN
for use in calculating with run type 4.2.  Using both the INDATA and INPLAN files allows
the user to limit estimates to just one participant under one pension plan, to as many simulated
participant histories as desired under all of the plans included in the study.
     The IDs included in the file INPLAN are the CODEID and the SEQ#.  Each line in the
file must begin with the number "9" in column 1 and any unique four digit index starting in
column 2.  Separated by blanks, the CODEID and the SEQ# follow.  All defined benefit
pension plans have CODEID numbers under 3000, defined contribution plans have IDs
numbered in the 3000s, and plans that combine both features have IDs starting at 5000.
Valid Ranges
     The program checks all input data and parameter settings for valid ranges.  The check
for valid ranges will only detect gross errors in the input data.  The program allows for a wide
range of data, including levels that would be thought be many to be extreme values.   This
check in no way insures the reasonableness or accuracy of the input data and parameters.  For
example, the valid date ranges often cover 100 years or more, and only values outside this
extended period are flagged by the program as invalid.  When the program encounters an
invalid data value or parameter setting, that value is automatically recoded to a default value
that lies within the valid range.  When this occurs, the program notes this problem in the
OUTERR file.  The valid ranges for the parameter settings are given in Table 3, and the valid
ranges for the input participant data are given in Table 4.  Both tables include the recoded
values the program automatically assigns to input data falling outside of the valid range.
                            Table 3
           Valid Ranges for Input Parameter Settings

͸
                        Valid Range            Outside Range  
  Variables      Ĵ      Program     
                    Minimum      Maximum      Recode Value   
Ĵ
  SURVEYD            1980.00      2000.00          1983.50   
  TODAYD             1980.00      2000.00          1983.50   
  CPlrate            - 25.00        25.00             0.00   
  INTrate               0.00        20.00             1.00   
  INCrate            - 20.00        20.00             0.00   
  SSWB                  1.00    200000.00             1.00   
  SSWBrate           - 20.00        20.00             0.00   
  SSrate             - 20.00        20.00             0.00   
  QAGE MIN             16.00        80.00            16.00   
  QAGE MAX             16.00        80.00            80.00   
  QDATE MIN          1925.00      2075.00          1925.00   
  QDATE MAX          1925.00      2075.00          2075.00   
  BENMAX 55             0.00    500000.00        500000.00   
  BENMAX 65             0.00    500000.00        500000.00   
  PROFVOL1              0.00        30.00             5.00   
  FORTVOL1              0.00        10.00             0.50   
  PROFVOL2              0.00        30.00             5.00   
  FORTVOL2              0.00        10.00             0.50   
  PROFVOL3              0.00        30.00             5.00   
  FORTVOL3              0.00        10.00             0.50   
  NACON                 0.00        30.00             5.00   
  NAMAN                 0.00        30.00             5.00   
  NAVOLrng MIN          0.00        30.00             0.00   
  NAVOLrng MAX          0.00        30.00             0.00   
  NAMATCH MAN           0.00       200.00           100.00   
  NAMATCH VOL           0.00       200.00           100.00   
  ANNTYPE               1.00         3.00             3.00   
  CONTPMT               0.00       100.00            50.00   
  VESTYPE               0.00         1.00             0.00   
  VESTYRS               0.00        25.00             5.00   
  MRAGE                 0.00         1.00             0.00   
  PENTYPE               0.00         2.00             0.00   
  FYA_PV                0.00         1.00             0.00   
  WAGEHIST              0.00         1.00             0.00   
  NOMIDX                0.00         1.00             0.00   
  BENCOLA               0.00         1.00             0.00   
  BENCOLA PCTCPI        0.00       100.00             0.00   
  TODAYPV               0.00         1.00             0.00   

                            Table 4
          Valid Ranges for Participant Data Variables

͸
                        Valid Range            Outside Range  
  Variables      Ĵ      Program     
                    Minimum      Maximum      Recode Value   
Ĵ
  SPOUSEBD              0.00      2000.00          BIRTHD    
  SEX                   1.00         2.00            1.00    
  BIRTHD             1880.00      1970.00         1950.00    
  HIRED            BIRTHD+16    BIRTHD+65       BIRTHD+20    
  QUITD                HIRED    BIRTHD+80       BIRTHD+65    
  WKHRS                 1.00      2080.00         2080.00    
  WAGE                  1.00   1000000.00            1.00    
  WAGEG                20.00        20.00            0.00    
  CRVOL                 0.00        30.00            0.00    

                          OUTPUT FILES

Generate Program Output Files
Source Code Files
     Procedur.pas   --   Plan procedures source code file.
     Cases.pas --   All plans case statements source code file.
     Cases2.pas     --   Integrated plans case statements source code file.
Plan Variables Information Files
     PassFail.txt   --   Pass/Fail results for the plans.
     Notefile.txt   --   Notes on the plan variables.
     Problems.txt   --   Problem notes on the plan variables.
     Formfile.txt   --   Form notes, also contains PassFail.txt.
     Formulas.lst   --   A listing of the pension plans formulas.

Calculate Program Output Data Files
     OUTDATA represents the name of the file where the program will write output in free
format, with one participant/plan combination per line.  As with the input data file, each line
represents the estimated pension entitlements from a single plan.  The total household pension
entitlement is thus the sum of entitlements due under all plans in which the respondent or
spouse participates.  For estimates of household pension wealth holding, estimates for the
respondent and the spouse must also be combined.
     The type and order of variables that are written into the OUTDATA file are defined by
the RUNTYPE specified.  For analyses based on actual participant data with given quit dates
(RUNTYPE 1.2), the output variables are shown in Table 5.  The output variables from
analyses of simulated data (RUNTYPE 4.2) are given in Table 6. Since each run allows up to
five simulated data cases, this basic set is repeated up to five times on each data output line. 
When the program calculates the pension entitlements due at all possible future quit dates
(RUNTYPE 3.2), the output variables are as shown in Table 7. Note that, unlike the above
output data sets written one case per line, this data set is written in blocks, giving all the data
for a particular case in a series of contiguous lines.  When printed, the output will occupy one
page per case.  The output file from this RUNTYPE is very large, especially when generated
for the full sample of cases.
     All the data entries in the OUTDATA file are numeric.  While most of the output
variables are coded in natural units (dollars and years), the variable that represents the type of
pension for defined benefit plans is coded 1 for normal retirement, 2 for late retirement, 3 for
early retirement, 4 for vested deferred, 5 for disability, and 6 for survivor benefits.  For
defined contribution plans, the variable is coded 7. For those pension plans that had a
combination of defined benefit and defined contribution provisions, the code 11 was used for
  normal retirement, 12  for late retirement, 13 for late retirement, 14 for vested deferred, 15
for disability, 16 for survivor benefits, and 19 if only the contribution formulas were used.  If
the participant did not qualify for any type of retirement benefit, this variable was set equal to
9. The program assigns the missing data code of - 1 to any plan that generates errors in
calculations when combined with the input data and assumptions.
     OUTTAB represents the name of the output file to which the program will write a
summary of the estimation parameters that were used in that particular replication, and text
headings for the output data file.  This file is suitable for obtaining a printed copy of the
estimated pension benefits for each case.
     OUTERR represents the file name to write the program produced summary of any
suspect dollar figure calculations in any portion of the estimation procedures.  The file contains
short messages about potential problems, indicating the case IDs and a list of the data values. 
That a case has been flagged for inclusion in the problem file does not necessarily mean that
the calculated value for the participant is incorrect, but that in the calculation process there
were some suspect intermediate results.
     All of the output files are created new or emptied if the already exist for each run of the
calculate program.  If multiple runs are done be sure to name the output files with different
names for each run.
                            Table 5
                                
           Output Data File for Entitlement Estimates
     Based on Actual Participant Data with Given Quit Date
                         (RUNTYPE 1.2)
                                
͸
 Order     Name                    Definition                 
Ĵ
  1       HHIDX     SCF Household ID                          
  2       CODEID    Pension Plan ID                           
  3       SEQ#      Pension Plan/Provider ID                  
  4       SEX       Sex of participant                        
  5       SPOUSEBD  Birth date of spouse, if married          
  6       BIRTHD    Birth date of participant                 
  7       HIRED     Date participant began employment         
  8       QUITD     Date participant terminates employment    
  9       QWAGE     Annual wage or salary at quit date        
 10       QASY      Number of years covered at quit date      
 11       PENTYPE   Type of retirement benefit                
 12       PENAGE    Age benefit payments begin                
 13       %QW       Pension benefit as percent of final wages 
 14       %/YR      Proportion of final wages per service year
 15       30YR      Proportion of final wages for 30 years    
 16       ANNUALA   Initial annual pension benefit amount     
 17       PRVALUE   Present value of entitlement              
 18       A65EQVL   Equivalent annual amount if start at 65   





                            TABLE 6
                                
           Output Data File for Entitlement Estimates
              Based on Simulated Participant Data
                         (RUNTYPE 4.2)
͸
 Order     Name                    Definition                 
Ĵ
  1       CODEID    Pension plan ID.                          
  2       TYPE      Type of pension benefit                   
  3       %QW       Benefit as percent of final wages         
  4       %/YR      Percent final wages per service year      
  5       ANNUALA   Initial annual benefit amount             
  6       PRVALUE   Present value of entitlement              


                            Table 7
                                
           Output Data File for Entitlement Estimates
Based on Actual Participant Data Using All Potential Quit Dates
                         (RUNTYPE 3.2)
͸
 Order     Name                    Definition                 
Ĵ
  1       HHIDX     SCF Household ID            * new for  95 
  2       CODEID    Pension Plan ID             * new for  95 
  3       SEQ#      Pension Plan/Provider ID    * new for  95 
  4       QUITD     Date employment terminates                
  5       QAGE      Age at quit date                          
  6       QASY      Total service years at quit date          
  7       QWAGE     Wage or salary at quit date               
  8       SSB       Social Security benefit amount            
  9       PENBEN    Pension benefit amount                    
 10       PENTYPE   Type of retirement benefit                
 11       VESTED    Deferred vested benefit                   
 12       BENAGE    Age when benefits begin                   
 13       VEST65    Vested benefit if begin at 65             
 14       DABLEB    Disability pension benefit                
 15       DTYPE     Type of disability pension                
 16       NRT       Normal retirement benefit                 
 17       LRT       Late retirement benefit                   
 18       ERT       Early retirement benefit                  
 19       VDT       Deferred vested retirement                
 20       DRT       Disability retirement benefit             
 21       DST       Survivor retirement benefit               
 22       CNT       Benefit based on contributions            

                                                  PASCAL PROGRAM SOURCE FILES
                                
Gen95.exe source code files:
     Gen95.pas      -- main generate program file.
     Gen95_2.pas         -- secondary generate unit.
     Emit95u.pas         -- output unit.
     Gvar95.pas          -- global variables unit #1.
     Error95.pas         -- error output and utility functions unit.

Calc95.exe source code files:
     Calc95.pas          -- main calculate program file.
     CaVar95.pas         -- global variables unit.
     Evalu95.pas         -- evaluation unit #1.
     Eval95_2.pas        -- evaluation unit #2.
     EvalVars.pas        -- evaluation variables unit.
     EvErr95.pas         -- evaluation error unit.
     Outsid95.pas        -- utility functions unit.
     MaxReal.pas         -- secondary utility functions unit.
     Cases.pas      -- plan case statements created by Gen95.exe.
     Cases2.pas          -- integrated plan case statements created by Gen95.exe.
     Procedur.pas        -- pension plan calculation procedures to be split up by
                    Integ95.exe into EvlP*.pas.
     EvlP*.pas      -- calculation procedures created from Procedur.pas by
                    Integ95.exe.

Integ95.exe source code files:
     Integ95.pas         -- the procedures and cases integration program source code.


                      DOCUMENTATION FILES
                                
     This file, the Pension Provider documentation is available as a WordPerfect 5.2 file a
WordPerfect 6.1 file and as a DOS text file, Pen_PC95.wp5, Pen_PC95.wp6 and
Pen_PC95.txt, respectively.  The files Pen_95.hlp, a WordPerfect document, and Pen_95.txt,
a DOS text file, also come with the Pension Provider for the PC, these are basic instructions
on how to use the Pension Provider programs and a list of files included with the Pension
Provider, '95 version.  The file, Files.lst, contains a list of the files that should be extracted
from the self extracting zip file, Pen_PC.exe.   
                 SYSTEM REQUIREMENTS AND LIMITS
                                
Minimum system requirements:
     Borland Pascal version 7.0
     IBM/PC compatible computer with Intel 386 or compatible CPU
     4 Megabytes system memory
     
Recommended system requirements:
     IBM/PC compatible computer with Intel 486DX or compatible CPU
     8 Megabytes system memory

     Hard disk space requirements will depend upon the size of the data sets being
processed.  Large data sets may need to be broken down into smaller sets if the system being
used has less than the needed amount of system (RAM) memory.  A formula for the
approximate maximum number of plans that can be handled at one time is: 
MIN( ( ( FreeSysMemory - 200K  ) / 16K ), 1100 )
     Example: You have the minimum required system, with 1.5M (1500K) of free system
     memory.   MIN( ( ( 1500K - 200K ) / 16K ), 1100 ) = 93.75, you can compile and
     process data sets of approximately 93 plans.
The minimum size of the compiled Calculate program with 1 pension plan is about 175K. 
Your computer support person can show you how to determine the amount of free system
memory on your computer.  The MAXIMUM number of plans that can be handled by Borland
Pascal v.7 is approximately 1100, more than this may not compile, 1200 will not compile. 
The 1100 value is for compilation using the compiler options given in the batch file supplied
with the Pension Provider software, RunPen.bat.
     The programs have been tested on a 386/25 IBM compatible computer with 2200K
(2.2M) free of 4Meg of system RAM and a 486/66 IBM compatible computer with 14M free
of 16Meg of system RAM.  The 386 was able to compile and process 130 plans, the 486 was
able to handle the maximum, 1100 plans.  It may be possible to run this program on a 386
computer with 2Megs of RAM, however, the number of plans that can be run will be quite
small, since the available system (RAM) memory will probably be less than 1000K (1M). 
1000K of free system memory will let you compile about 50 plans, maybe less.
                     ENHANCEMENTS AND FIXES

1)   Modification of the wage growth formula, following quadradic model is used:
     ln (E) =  + m, + 3,  1(A) +  2(A)2
     WHERE:
     E = annual earnings.
      = earnings in the year of the survey.
     m = the overall wage growth in the economy (nominal).
     A = some measure of age or tenure. We will use age.
      1,  2 = user defined coefficients for age terms.

     The betas are allowed to vary by individual so researchers can distinguish types of jobs
     which may have varying earnings growth patterns (e.g. union vs. non-union jobs). 
     These betas are to be specified in the INDATA file.
     m, the overall economy-wide growth in wages is specified in the INPARM file

2)   The new version allows users to input wage histories for individuals. A toggle switch in
the INPARM file specifies whether the program is expected to estimate wages or a user input
wage stream is being used.  A respondent data "line" will take multiple lines if a wage history
is used.  Wage histories can span multiple lines, the end of history marker, a negative number,
is required.
     HHID  CODEID  SEQ#  SPOUSEBD  SEX  BIRTHD  HIRED  QUITD  WRKHRS  WAGE  WAGEG  CRVOL  BETA1  BETA2  PASSTHRU
     StartYear EndYear StartYearWages .... EndYearWages NegativeNumber

     Ex 1 (1 wage history line): 
     1234 9999 321 1942.40 1.00 1940.60 1955.35 2080 25000.00 2.00 4.00 0.02 -0.0002
     1970.0 1973.0 5000.00 5250.00 5600.00 5900.00 -1.0

     Ex 2 (multiple line wage history): 
     1234 9999 321 1942.40 1.00 1940.60 1955.35 2080 25000.00 2.00 4.00 0.02 -0.0002
     1970.0 1973.0 5000.00 5250.00 5600.00 5900.00 6000.00 6500.00
     7000.00 8000.00 -1.0

3)   A new Social Security benefits algorithm has been incorportated.  This algorithm was
written by the Wyatt Company and converted to Borland Pascal v7.0 for use in the PPS
calculation program.  This algorithm does not require the Social Security coefficients or the SS
benefits base amount variables used in the earlier versions, so they have been removed from
the parameters file, INPARM.  The list of SS variables removed from INPARM follows:
     SS        -- SS benefit (base amount)
     SSPUrto   -- SS primary unreduced (min, mid, max)
     SSJUrto   -- SS joint unreduced (min, mid, max)
     SSPRrto   -- SS primary reduced (min, mid, max)
     SSJRrto   -- SS joint Reduced (min, mid, max)
     SSPDrto   -- SS primary disability (min, mid, max)
     SSJDrto   -- SS joint disability (min, mid, max)
     SSSSrto   -- SS surviving spouse (min, mid, max)
     SSCUTS    -- SS wage cutoffs (min, max)

4)   One of the LNG equations was written incorrectly. When "After eligible for social
security" is checked, "BGN=BIRTHD + SSAGE(l)" was written. The equation should read
have been "BGN=MAX(BIRTHD+SSAGE(l),QUITD)", which is now the case.

5)   Olivia Mitchell identified a problem with the present value calculation. If the today's
date variable in the INPARM file is a date after the onset of benefits for an individual, the
present value is the present value of the entire stream of payments rather than the present value
of future payments. Tom Steinmeier noted that for some purposes, he would like to retain the
current present value calculation. So he proposed that we incorporate a switch in the INPARM
file to specify which present value was to be calculated.  This has been incorporated into the
program.

6)   When a plan does not offer early retirement, the formula "ERQ=O" is now added to
the plan calculations. This eliminates thousands of lines that were written to the error file, none
of which represented real errors.

7)   The original Final Average Pay calculations were incomplete.  The 10 FAP types have
now been fully implemented as defined.

8)   The program now provides the option to allow the researcher to index nominal dollar
amounts in the formulas to inflation. A switch is provided in the INPARM file to turn this
feature on and off.

9)   The option to adjust those plans that do not include automatic cost of living adjustments
has been added.  A switch is provided in the INPARM file to turn this feature on and off.

10)  Previously the output in run 3.2 provided first year annuity payments over a range of
hypothetical retirement years. A switch has been added in INPARM to print present values on
this table instead.
                    CALCULATION ERROR CODES

The meanings of errors listed in the calculation output file:
INTG Invalid Seq# passed to the procedure OthCont() which calculates Integrated plans.  This
     error is paired with a following error line containing the invalid seq# in place of the
     error type.
Neg- This occurs if any of the values checked in the plan procedure are less than zero.
BTWN This occurs in the function b(), the "between" function, if the value being checked or
     the lower limit or the upper limit is less than zero.
BBTN This occurs in the function a(), the "backwards between" function, if the value being
     checked or the lower limit or the upper limit is less than zero.
UPTO This occurs in the function u(), the "upto" function, if the value being checked or the
     limit is less than zero.
OVER This occurs in the function o(), the "over" function, if the value being checked or the
     limit is less than zero.
ATBE This is a begin payments date error meaning the begin date is greater than the end date,
     this occurs in the function Anytime().
DATA This error occurs in the procedures rrange() and irange(), the input read procedures.  It
     means a respondent data value was outside of the range defined in the program for the
     variable (data value) being read.
DIV0 This means a division by zero was attempted in the pension plan procedure calculation.
AVAILABILITY OF THE PENSION PROVIDER

The Pension Provider software will be distributed through:
Catherine MP Liebowitz
University of Michigan - Institute for Social Research
Room 3249 ISR
426 Thompson Street
PO Box 1248
Ann Arbor, MI 48106-1248
phone: (313) 763-4180
fax: (313) 647-11786
email: catlieb@isr.umich.edu



Programming support:
Jody Lamkin
University of Michigan - Institute for Social Research
Survey Research Center
Room 2062
P.O. Box 1248
Ann Arbor, MI 48106
Phone: (313) 763-0418 or (313) 764-4417
e-mail: jodyl@umich.edu 

