"New and Improved" CHGPF

his article was started before I had a chance to read "Tips from Jackie" in our May 1997 issue. It was started on the basis of an internal presentation and it is now here for your perusal. It is a little bit more detailed than Jackie’s piece but essentially covers the same material.

As Programmers, most of us like to think we are good enough systems designers. When we decide to put “n” number of fields in a file, we usually don’t expect to have to change that in the immediate future. Of course, in the real world, business requirements change, legacy applications are a fact of programming life, and changes in file format is something we will have to face sooner or later.

Changing the format of a widely used file, with a number of logical views and a few more bells and whistles can be a lot of work. In the most complicated case, the to-do list involved in the change of a physical file would look like this:

Rename AFILE to OLDFILE or move it to an archive library.
Add new field to OLDFILE source DDS.
Recreate OLDFILE (call it now NEWFILE) using modified DDS.
Copy data from OLDFILE to NEWFILE.
Re-create logical files (if there were any) that spanned OLDFILE to span NEWFILE.
Re-grant appropriate authority to NEWFILE so that authorities are now same as OLDFILE.
Re-add referential constraints (if there were any) to NEWFILE.
Re-add triggers (if there were any) to NEWFILE.
Re-start journaling (if there were any) to NEWFILE.
Re-start object auditing (if there were any) for NEWFILE.
Delete OLDFILE and all OLDFILE logicals.
Re-compile all programs that touch the modified physical file and/or logicals affected.

For those who are not yet aware (I was part of that bunch until recently), CHGPF has changed a lot. Figure 1 shows what the “old” CHGPF did in V3R1.


(Figure 1)
Change Physical File (CHGPF)    (V3R1)                     
                                                                               
 Type choices, press Enter.                                                    
                                                                               
 Physical file  . . . . . . . . . > FILENAME      Name                         
   Library  . . . . . . . . . . . >   LIBNAME     Name, *LIBL, *CURLIB         
 System . . . . . . . . . . . . .   *LCL          *LCL, *RMT, *FILETYPE        
 Expiration date for member . . .   *NONE         Date, *SAME, *NONE           
 Maximum members  . . . . . . . .   1             Number, *SAME, *NOMAX        
 Access path maintenance  . . . .   *SAME         *SAME, *IMMED, *REBLD, *DLY  
 Access path recovery . . . . . .   *SAME         *SAME, *NO, *AFTIPL, *IPL    
 Force keyed access path  . . . .   *SAME         *SAME, *NO, *YES             
 Member size:                                                                  
   Initial number of records  . .   10000         1-2147483646, *NOMAX, *SAME  
   Increment number of records  .   1000          0-32767, *SAME               
   Maximum increments . . . . . .   3             0-32767, *SAME               
 Allocate storage . . . . . . . .   *NO           *NO, *YES, *SAME             
 Preferred storage unit . . . . .   *ANY          1-255, *SAME, *ANY           
 Records to force a write . . . .   *NONE         Number, *SAME, *NONE         
 Maximum file wait time . . . . .   *IMMED        Number, *SAME, *IMMED, *CLS  
                                                                                
Maximum record wait time . . . .   60            Number, *SAME, *IMMED, *NOMAX 
Share open data path . . . . . .   *SAME         *SAME, *NO, *YES              
Max % deleted records allowed  .   *NONE         1-100, *NONE, *SAME           
Reuse deleted records  . . . . .   *NO           *SAME, *YES, *NO              
Record format level check  . . .   *YES          *SAME, *YES, *NO              
Text ‘description’ . . . . . . .   ‘Text for Filee.
Coded character set ID . . . . .   37            *SAME, *HEX

Starting at Version V3R2 however, CHGPF can do a lot more for you. If you are changing a physical file with a lot of logical views, specific authorities and special features attached; CHGPF can now help you in a big way. With the new features offered in CHGPF, there is no need to delete and re-create physical files or any of the associated logical files when changing the number of fields or altering fields in an existing physical file. Authorities are taken care of, trigger programs are automatically re-attached, as are journals and everything else that was hooked up to the old file.

All you have to do now, is to change the DDS, call CHGPF and stand back! First, lets review the DDS changes supported by CHGPF:

Change of field Attributes,
Change of field Data Type,
Change of field Length,
Change of field Decimal Positions,
Change of field Column Headings or Text,
Changes of field Edit Codes,
Changes of field Key Fields,
Changes of field Omit Fields,
Delete an existing field,
Add a new field.

How is it all done?

Simply by providing CHGPF with the modified DDS source file and member, with the file creation parameters. (See shaded area in figure 2).

With these new parameters in the CHGPF command, the to-do list to modify a file becomes:

Copy or back-up FILE,
Add, change or delete fields in DDS source,
Run CHGPF command using modified DDS,
Go get a coffee!

Note: The File Level Identifier will change when the following features change:

Total length of record format,
Record format name,
Number or order of fields defined,
Field names,
Field data types,
Field length or size,
Number of decimal positions in a field.



(Figure 2) 
Change Physical File (CHGPF)   (V3R7)                        
                                                                               
Type choices, press Enter.                                                     
                                                                               
Physical file  . . . . . . . . . > FILENAME      Name                          
  Library  . . . . . . . . . . .     LIBNAME     Name, *LIBL, *CURLIB          
System . . . . . . . . . . . . .   *LCL          *LCL, *RMT, *FILETYPE         
Source file  . . . . . . . . . .   *NONE         Name, *NONE                   
  Library  . . . . . . . . . . .                 Name, *LIBL, *CURLIB          
Source member  . . . . . . . . .   *FILE         Name, *FILE                   
Source listing options . . . . .                 *SRC, *NOSRC, *SOURCE...      
               + for more values                                               
Generation severity level  . . .   20            0-30                          
Flagging severity level  . . . .   0             0-30                          
Delete dependent logical file  .   *NO           *NO, *YES                     
Remove constraint  . . . . . . .   *RESTRICT     *RESTRICT, *REMOVE            
Expiration date for member . . .   *SAME         Date, *SAME, *NONE            
Maximum members  . . . . . . . .   *SAME         Number, *SAME, *NOMAX         
Access path size . . . . . . . .   *SAME         *SAME, *MAX4GB, *MAX1TB       
Access path maintenance  . . . .   *SAME         *SAME, *IMMED, *REBLD, *DLY
Access path recovery . . . . . .   *SAME         *SAME, *NO, *AFTIPL, *IPL     
Force keyed access path  . . . .   *SAME         *SAME, *NO, *YES              
Member size:                                                                   
  Initial number of records  . .   *SAME         1-2147483646, *NOMAX, *SAME   
  Increment number of records  .   *SAME         0-32767, *SAME                
  Maximum increments . . . . . .   *SAME         0-32767, *SAME                
Allocate storage . . . . . . . .   *SAME         *NO, *YES, *SAME              
Preferred storage unit . . . . .   *SAME         1-255, *SAME, *ANY            
Records to force a write . . . .   *SAME         Number, *SAME, *NONE          
Maximum file wait time . . . . .   *SAME         Number, *SAME, *IMMED, *CLS   
Maximum record wait time . . . .   *SAME         Number, *SAME, *IMMED, *NOMAX 
Share open data path . . . . . .   *SAME         *SAME, *NO, *YES              
Max % deleted records allowed  .   *SAME         1-100, *NONE, *SAME           
Reuse deleted records  . . . . .   *SAME         *SAME, *YES, *NO              
Sort sequence  . . . . . . . . .   *SAME         Name, *SAME, *SRC, *JOB...    
  Library  . . . . . . . . . . .                 Name, *LIBL, *CURLIB
Language ID  . . . . . . . . . .   *SAME         Character value, *JOB, *SAME
Record format level check  . . .   *SAME         *SAME, *YES, *NO            
Node group . . . . . . . . . . .   *SAME         Name, *NONE, *SAME          
  Library  . . . . . . . . . . .                 Name, *LIBL, *CURLIB        
Partitioning Key . . . . . . . .   *SAME         Name, *SAME                 
               + for more values                                             
Text ‘description’ . . . . . . .   *SAME
Coded character set ID . . . . .   *SAME         *SAME,  *HEX...

A change to any of the above, causes the data map to change and therefore programs using the file have to be re-compiled.

All this sounds pretty good, but there are still considerations to watch out for. Do not attempt to use CHGPF without reading these:

Enough Storage must be available to make a copy of the data from the physical file.
Exclusive Use of the physical file is required.
Only users with *OBJALTER or *OBJMGT authority can run CHGPF.
When changing the data type of a field, the new data type MUST be compatible with the old one, i.e., numeric to numeric, or character to character.
File statistics are not preserved.
CHGPF will NOT recompile programs that use the physical file.
CHGPF will NOT remove deleted records from the physical file.
Some changes can cause data loss, e.g.: if a field is deleted, if a new field is shorter, or if a field is changed from being NULL-capable to not being NULL-capable. CPF will issue a message if data loss is possible.
When adding a new field, plan ahead to determine the default value of the new field.
CPF cannot apply or remove journal changes across a CHGPF journal entry.
What happens if there is an error? CHGPF returns all objects involved in their state just prior to the change occurring.
Of course, having a current backup of the file(s) involved still a good idea.

In Conclusion:

Although the new CHGPF feature does not do EVERYTHING you need when changing fields in an existing file, it will significantly reduce the tedious parts of the job. Proper planning, backups, and program re-compiling is still part of the job. Also, there is no substitute for reading the specifics in the manual. This article is more of an introduction than a detailed technical example, but I hope it helps. [Note: I would like to give credit to Skip Marchesani of Lexel-Custom Systems Corp. (Newton, NJ) for his contribution to this article.] T < G