ibmi-brunch-learn

Announcement

Collapse
No announcement yet.

Chgpf

Collapse
X
 
  • Filter
  • Time
  • Show
Clear All
new posts

  • Chgpf

    Many people don't realize that they can use the Change Physical File command to alter the field and key definitions of a physical file without having to recompile that file or to save and restore their data. This command can enlarge or shrink existing file fields, add new fields, delete old fields, or change file keys. This week, I'll explore this hidden feature of CHGPF, and discuss its advantages and its disadvantages.

    Why We CHGPF

    The Change Physical File (CHGPF) command's life purpose is to change the attributes of a physical file and all its members. The Change Physical File command (CHGPF) can be run either through a 5250 terminal session (green-screen) or through iSeries Navigator's (OpsNav) Run Command facility, which allow you to run green-screen commands through a Windows interface. (For more information on using Run Command, see the articles in the Related Stories section at the bottom of this article.)

    CHGPF can be used to change several significant file attributes, including the maximum number of members the file can contain, the member size, some performance parameters, and the source file member that the file's field and key descriptions are based on. By using CHGPF's Source file (SRCMBR) and Source Member (SRCMBR) parameters, you can easily change the specifications that define the characteristics of a physical file's defined fields or its record keys. In the right situation, these parameters are useful for modifying file field lengths and characteristics, adding or deleting a physical file field, or changing your file key. Here's how it works.

    Adding, Changing, and Deleting Fields

    Let's say that I have a file called TEST that was compiled by using the following DDS specifications:
    PHP Code:
    A          R TEST                                          
    A            FIELD1        10A         TEXT
    ('FIELD ONE')    
    A            FIELD2        10A         TEXT('FIELD TWO')    
    A          K FIELD1 
    If I found that the field size for FIELD1 was too small and that I wanted to change it to twenty characters instead of ten, I can create a new DDS specification file called TEST1 in my QDDSSRC file. This file would look like this:
    PHP Code:
    A          R TEST                                          
    A            FIELD1        20A         TEXT
    ('FIELD ONE')    
    A            FIELD2        10A         TEXT('FIELD TWO')    
    A          K FIELD1 
    I could then change my TEST file to use the record format and field specifications in my new TEST1 source member by executing the following CHGPF command:

    CHGPF FILE(*LIBL/TEST) SRCFILE(*LIBL/QDDSSRC) SRCMBR(TEST1)

    After execution, the system would change the size of FIELD1 in the file to be twenty characters (as designated in the TEST1 source member), and it would right-fill the additional characters with blanks. All the existing data would be retained and moved back to the newly redesigned file after the conversion was finished, so no file data would be lost. All existing file authorities are also saved and reapplied to the reconfigured file.

    Conversely, if I wanted to reduce the size of FIELD1 in my file from ten characters to five, I would change my TEST1 source to look like this:
    PHP Code:
    A          R TEST                                          
    A            FIELD1         5A         TEXT
    ('FIELD ONE')    
    A            FIELD2        10A         TEXT('FIELD TWO')    
    A          K FIELD1 
    When I again run the CHGPF command listed above, it will attempt to reduce the size of this field. However, it will also provide the following error message, because changing the file in this manner will cause some of the data (five characters) in FIELD1 to be lost.

    Change of file TEST may cause data to be lost. (C I)

    If my intent is to really reduce the size of my field, I would enter an 'I' (ignore) for this message and the command would reduce the field size. When you use CHGPF to reduce a character field's size, field data is truncated from the right side of the field, precisely at the point where the data overflows the new field.

    Going further with my example, I can add a new field to my file if I change the TEST1 source like this:
    PHP Code:
    A          R TEST                                          
    A            FIELD1        10A         TEXT
    ('FIELD ONE')    
    A            FIELD2        10A         TEXT('FIELD TWO')    
    A            FIELD3         9P 0       TEXT('FIELD THREE')
    A          K FIELD1 
    After running CHGPF with this source member, the program would add a new packed numeric field called FIELD3 to the file and it would insert zeros into that field for all file records.

    Things get a little trickier when you try to alter numeric fields in a file. If I decided that I wanted to shrink FIELD3 from a packed 9-digit numeric field (9P 0) to a packed 5-digit numeric field (5P 0), I could try changing my source member to this specification and run the CHGPF command again.
    PHP Code:
    A          R TEST                                         
    A            FIELD1         5A         TEXT
    ('FIELD ONE')   
    A            FIELD2        10A         TEXT('FIELD TWO')   
    A            FIELD3         5P 0       TEXT('FIELD THREE'
    A          K FIELD1 
    However, there may be a problem with this source change because CHGPF will not let you shrink a numeric field in a physical file if any existing data will not fit into the altered field. This is because when CHGPF attempts to shrink a numeric field, it copies the data out of the old file, recreates the file with its new format, and then tries to copy the data back into the modified fields.

    The problem with doing this when you are shrinking the size of a numeric field is that (because the target field is smaller than the original field) the CHGPF command may receive a conversion error if old field data will not fit into the new field size. If CHGPF experiences an error, the command will halt and the file will not be changed. So you may or may not be able to shrink a numeric field by using the CHGPF command. You may also run into problems if you're trying to change the decimal designation of a numeric field where the new field structure is impossible to map existing data to from the old field structure.

    The other cool thing that you can do with a changed source member is to use CHGPF to change the key structure of your physical file. All of the source files I've used so far use FIELD1 as their only file key. If I wanted to change the key fields on my test file to add FIELD2 as a secondary key in my file, I could alter my replacement source file to the following:
    PHP Code:
    A          R TEST                                            
    A            FIELD1         5A         TEXT
    ('FIELD ONE')      
    A            FIELD2        10A         TEXT('FIELD TWO')      
    A            FIELD3         9P 0       TEXT('FIELD THREE')    
    A          K FIELD1                                           
    A          K FIELD2                                           A 
    In this example, CHGPF would alter the key structure of the file as it was rebuilt when using this now familiar command:

    CHGPF FILE(*LIBL/TEST) SRCFILE(*LIBL/QDDSSRC) SRCMBR(TEST1)

    So my rules of thumb for modifying field sizes and file keys through CHGPF's SRCFILE and SRCMBR parameter are the following:

    Character fields can be increased or decreased. When decreasing the size of a character field, overflowing characters will be right-truncated in the new field.
    Field sizes should only be increased for existing numeric fields. Attempts to reduce a numeric field size by using CHGPF will probably fail due to conversion errors, and the file will not be changed. It's usually best to avoid reducing numeric field sizes at all.
    Both numeric and character fields can be added to a file at will. New numeric fields will be zero-filled while new character fields will be blank-filled.
    Fields can be deleted from a file by removing them from your source member. Deleting a field will also remove any data from the file that was contained in that field.
    File key specifications can be altered to change the key to another file field or to add a secondary key to the file's key stack.
    But As Always, There Are a Few Flaws to This Technique

    While using CHGPF can successfully alter a physical file by modifying a field or file key definition, there are some definite downsides to the technique. If you use this technique, be sure to check the following three items to insure that the file is ready to use with your applications.

    First, if the file is exceedingly large and the size of one of the key fields is changed or a key field definition is changed, i5/OS will need to build a new access path. Depending on how large the file is, the system could take a significant amount of time to rebuild that access path.

    Second, if you are changing a field size or definition, be sure to recompile all associated logical files to insure they are properly built over your reconfigured file. Again, be aware that the access path rebuild could take a long time for large files.

    Finally, you must check and recompile any native RPGLE programs, modules, service programs, and so forth that use the modified physical file as an externally defined file or as a module in their program. This will help you avoid level check situations when your users call or submit a program.

    A Useful Tool for Specific Situations

    As you can see, this CHGPF technique is effective, but it may not be useful in every situation. For files that are used in native i5/OS programs running RPGLE, it's more problematic because you would have to recompile any program that references the changed file as an externally described file. But for files that are accessed remotely through SQL statements over ODBC, JDBC, OLE DB, or .NET connections, it may be more useful for changing files on the fly because those programs may not be as dependent on the old source file definitions. It's handy to know how to use CHGPF this way for those special situations where a file needs to be quickly changed.

    About Our Testing Environment

    All configurations described in this article were tested by using the Change Physical File command on an i5 550 box running i5/OS V5R3.
Working...
X