Restoring IBM i Libraries to Different Names Can Be Tricky!

Restoring IBM i Libraries to Different Names : The Hidden Problems (and How to Fix Them)

Cross-Logical Files • SQL Temp Objects • Triggers • Procedures • Journals • Plus the DFRID(YES) Solution

Today we’re diving deep into one of those IBM i gotchas that trips up even experienced admins: restoring a library to a completely different name. It sounds harmless ‘Just RSTLIB SAVLIB(PRODLIB) RSTLIB(TESTLIB)’ but it quietly breaks things like logicals, SQL objects, triggers, stored procedures, and journals.

This is a really common gotcha in IBM i operations. You know how tempting it is to restore a library to a fresh name for testing or cloning – ‘Hey, let’s just change LIB from PROD to TESTLIB on the RSTLIB command.’ Sounds simple, right? But it can quietly break things in ways that bite you later. Today we’ll walk through the main headaches, cross-logical files, SQL temporary objects failing to restore, and the sneaky issues with triggers, stored procedures, and journals.

We’ll cover exactly what goes wrong and, most importantly, the powerful fix called DFRID(*YES) that solves a ton of these headaches. This is practical, real-world stuff you can use tomorrow. Let’s jump in!

Why Do We Restore Libraries with Different Names?

Testing environments • Cloning for dev or QA • Migration projects • Disaster recovery drills

First, let’s talk “why?”

Well… we rename on restore all the time, building a test copy of production, spinning up a new project environment, or recovering after a problem. The RSTLIB command makes it easy with that RSTLIB parameter.

But here’s the catch: the system doesn’t magically rewrite every internal pointer or catalog entry to the new library name. Objects remember where they came from, and that’s where the problems start.

Ready for the first big one?

Problem #1 – Cross-Logical Files

LF in OLD LIB → points to PF in PROD; after restore → LF in TESTLIB still points to old PF

Okay, classic headache: cross-logical files. Your logical file lives in Library A and is based on a physical file in Library B. When you restore Library A to a brand-new name (TESTA), the logical file’s description still says “My physical is in the original Library B.”

Result? You get CPF3204 errors, or worse, your test reports start pulling live production data!

So now you’ve got this ‘cross’ situation, where the LF is happily pointing at production data instead of your test copy, or worse, it fails with CPF3204 because the system can’t find the based-on file in the expected spot.

I’ve seen teams scratch their heads for hours wondering why their test reports are showing live customer data! The fix usually involves recompiling the logical (or using CHGLF/DFRID on restore), but prevention is better than experiencing this pain: Plan your restores so all related libraries move together or use CRTDUPOBJ with care.

This is exactly where our hero parameter comes in, but we’ll get to that in a minute.

First, let’s visualize this problem.

On the left you see the normal, happy setup. Your logical file in ORDERLIB is nicely based on the physical file sitting in PRODLIB. Everything works perfectly. Now look at the right side. You run RSTLIB and restore that library to a brand-new name called TESTLIB for your test environment. The logical file moves over, but inside its definition it still has the old library name baked right in. So, it keeps pointing back to the original PRODLIB instead of your nice new test copy.

This is exactly why we’re going to talk about DFRID(*YES) – it’s the trick that fixes this kind of cross-library headache automatically during the restore.

Problem #2 – SQL Temporary Objects Fail to Restore

Global temp tables • SQL views/indexes/MQTs • DB2 catalog (QSYS2) gets out of sync

SQL temporary objects are the sneaky ones, like global temporary tables (SESSION.*), SQL views, or materialized query tables that live inside your schema. When you restore the library with a different name, the DB2 for i catalog (those SYS tables in QSYS2) doesn’t always get the memo that the schema just moved.

You’ll see restore messages saying the object couldn’t be created or the SQL collection metadata is out of sync. When the library name changes, the DB2 catalog doesn’t always update. Temporary objects especially hate this because they’re often tied to the original library name in the catalog. You’ll see restore errors saying objects couldn’t be created, or they restore but throw SQLSTATE errors when you try to use them. The catalog still thinks everything lives in the old schema. Result? Failed restore or objects that look restored but throw SQL errors when you try to use them.

Super frustrating, especially in modern SQL-heavy apps.

Always check Reclaim DB Cross-Reference (RCLDBXREF)

After the restore, run a quick RCLDBXREF or recreate the SQL objects from source to get everything happy again.

RCLDBXREF 

The Reclaim Database Cross-Reference (RCLDBXREF) command swoops in like a librarian with a superhero cape, rescuing the database cross-reference catalog data for one lucky library. It’s basically the leaner, sassier cousin of the Reclaim Storage (RCLSTG) command, pulling off the same SELECT(*DBXREF) trick without forcing the whole system into lockdown. Plus, it’s picky, but in a good way, targeting just one library instead of redecorating the entire system.

This command offers an intuitive interface for identifying catalogs with inconsistencies and the libraries impacted by them. When an auxiliary storage pool (ASP) group is assigned to the current thread, it also applies to the independent ASPs within that group, as well as to the system and basic user ASPs (ASP numbers 1–32).

Use this command only when there are issues with the database cross-reference catalogs and running RCLSTG SELECT(*DBXREF) isn’t possible due to critical business needs. Since it doesn’t have to run in restricted state, it might not always recover the cross-reference data. If that happens, you’ll need to run RCLSTG SELECT(*DBXREF) instead.

RSTLIB DFRID(YES) Explained

What it does • When to use it

Now the part you’ve been waiting for – the fix that saves the day for cross-logical files and a bunch of other dependency issues: the DFRID parameter on RSTLIB (and RSTOBJ).

DFRID stands for ‘Defer ID’ short for deferring identifier resolution. Starting several years ago in IBM i 6.1 (V6R1), the system lets you restore logical files BEFORE their based-on physical files, even if they’re in different libraries.

You simply add DFRID(*DFT) or DFRID(yourname) to the RSTLIB command. Any logical file (or MQT) that can’t find its physical right away gets ‘deferred’ instead of failing. The restore finishes successfully, and the system remembers those pending objects.

It’s brilliant for our scenario, restoring libraries to new names where dependencies cross libraries. No more order-of-restore nightmares!

How to Use DFRID(YES) in Practice + RSTDFROBJ

Here’s exactly how you use it (ps: its super easy)

First, run your restore like this:

RSTLIB SAVLIB(PRODLIB) RSTLIB(TESTLIB) DFRID(*DFT)

Any dependent logical files get deferred and you’ll see messages like CPI321E ‘File XYZ deferred’ and later CPI373B ‘All objects completed for DFRID *DFT’.

Then, once ALL your physical files are restored (even from other libraries), you finish the job with:

RSTDFROBJ DFRID(*DFT)

Boom!!

All the deferred logicals are now properly attached and ready to go. You can even name your own DFRID value to keep multiple restores separate.

This single trick eliminates most cross-library logical file headaches when you’re renaming on restore. I use it on every test environment build now!

Problem #3 – File Triggers Break

ADDPFTRG stores file + program library • Pointers point to old name

Triggers are next on the list. When you add a trigger with ADDPFTRG, it hard-codes both the physical file and the trigger program’s library.

Restore the library to a new name and suddenly the trigger can’t find its program (or vice-versa) because the file reference or the program library pointer is pointing at the old location.

You might not even notice until someone updates a record and nothing happens… or you get a big CPF message. I’ve had to go back and re-run ADDPFTRG after every test-library restore.

After any renamed restore, always check with WRKTRG (from the Projex4i Power Toolkit) or DSPFD and re-add the triggers if needed. Keep trigger programs in the same library whenever possible to make life easier.

Problem #4 – Stored Procedures Get Confused

External procedures • SQL procedures • SYSROUTINES catalog

Stored procedures can be sneaky too. External ones point to a specific program or service program, the catalog entry in SYSROUTINES still has the old library name.

After a rename restore, CALL MYPROC fails with ‘not found.’ Even SQL procedures can have hard-coded references inside them.

You often need to drop and recreate the procedure, or use CREATE OR REPLACE after the restore.

Another catalog-sync issue that DFRID doesn’t cover – but at least you know to check!

Problem #5 – Journals & Receivers Dislike Name Changes

Journaled files expect journal in specific library • Receivers have strict rules • STRJRNPF after restore

Journals round out the list. A journaled file expects its journal to live in a certain library. Restore to a new name and journaling might not re-attach automatically. Journal receivers themselves are picky! They usually want the exact same library name, or you get errors (especially with remote journals).

Use the STRJRN parameter on restore commands when you can, or manually run STRJRNPF afterward. Journals really prefer staying in the original library name.

Best Practices & Quick Fixes?

So how do we stay out of trouble?

Here’s my most common checklist:

1. Use DFRID(*DFT) on every RSTLIB where logicals might cross libraries – it’s a game-changer!
2. Restore related libraries together whenever possible.
3. After restore: Run RSTDFROBJ, then check triggers, procedures, and journaling.
4. Use RCLDBXREF for SQL catalog cleanup.
5. Recompile logicals or use CRTDUPOBJ for cleaner copies.
6. Keep a quick restore script with DFRID built in for test/dev work.

Five minutes of planning now saves hours of debugging later – trust me!

Well, my cup of tea is empty and that just about wraps this blog up.

We covered the main problems when restoring IBM i libraries to different names; cross-logical files, SQL temp objects, triggers, stored procedures, journals, and the super useful DFRID(*YES) trick that fixes so many of these issues. You now know exactly what to watch for and how to make renamed restores smooth and reliable.

Good Luck out there in IBM-i Land!