The API Corner: Renaming and Moving Objects Doesn't Have to Be Difficult

  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

The Rename Object API offers flexibility above and beyond just renaming.


In last month's article, Deleting Objects, we reviewed a rather general-purpose API: Delete Object (QLIDLTO). This month, we'll look at another general purpose API: the Rename Object (QLIRNMO) API, which is documented here and has been available since V2R3. The Rename Object API, as you might expect, allows you to rename an object. Not as obvious, the QLIRNMO API also allows you to move an object. As with QLIDLTO, using the Rename Object API allows you to directly operate on an object without having to run a CL command from your RPG application program under the covers.


The Rename Object API defines seven parameters: five that are required, two that are optional.


The first parameter is a standard 20-byte qualified object name with the first 10 characters identifying the name of the object to be renamed and the second 10 characters the library associated with the object. Though it's not a feature you are likely to use very often, I will mention that the qualified object name does not have to conform to the standard naming conventions of the i. You can, for instance, identify an object with a name of all lowercase characters or a name containing special characters such as imbedded blanks, and then you can rename the object to a standard name so that it can be referenced by other applications on your system. This ability to use non-standard object names is fairly common to system APIs but, in most cases, is a feature to be avoided. In the case of QLIRNMO, this feature can, when you find an object on your system with an "unusual" name (typically an object coming from another system), save you from a lot of grief.


The second parameter is the type of object you want to rename. The value specified is prefixed by an asterisk as in *FILE, *DTAARA, *DTAQ, *PGM, etc. Note that there is no special value for this parameter such as *ALL. You must explicitly identify the type of object to be renamed by the API.


The third parameter identifies the new name of the object and provides the ability to also move the object to another library. While CL commands such as RNMOBJ allow only a simple (non-qualified) name for the NEWOBJ parameter, the QLIRNMO API supports the standard 20-byte qualified object name with the first 10 characters identifying the name of the object to be renamed and the second 10 characters the library to be associated with the renamed object. Change the library portion of the qualified object name and you have moved the object (in addition to optionally renaming the object, assuming you also change the object name portion) from the library identified by the first parameter of the Rename Object API to the library identified by the third parameter of the API.


If you want to have some fun with an understanding colleague (one who enjoys a joke and is not under any deadlines), you can also rename an object in a co-worker's personal library from a "good" name such as MYSRC (which should not have a large number of members if it's a file) to a rather difficult name to use such as BAD SOURCE (where there's a blank between the words BAD and SOURCE) or MYSRC? using the object name portion of the third parameter. Your co-worker will quickly find that commands such as STRSEU, CRTBNDRPG, etc. do not like these object names. To correct the situation, simply use the Rename Object API to rename the file back to MYSRC (and make sure you are available to perform this recovery action in a hurry!).


The fourth parameter allows you to control what action should be taken if the qualified object identified by the third parameter already exists. This parameter is a 1-byte character variable and defines three values. A value of '0' causes the API to return an error message if an object already exists with the object type identified by parameter two and the name identified by parameter three. A value of '1' instructs the API to replace the object identified by parameters two and three with the object identified by parameter one. A value of '2' has the API replace the object identified by parameters two and three with the object identified by parameter one and log a message to the job log if the object identified by parameters two and three was moved as part of the replacement. This movement can occur, for instance, if a *PGM object is being replaced and the system moves the replaced object to the QRPLOBJ library. If no movement took place, then no message is logged.


The fifth parameter is the standard API error code parameter, which allows you to control whether error situations should be returned as escape messages or as data within the error code parameter.


The sixth and seventh optional parameters, not used by this article, allow you to identify the auxiliary storage pools associated with the libraries identified by the first and third parameters, respectively.


Below is a sample program utilizing the QLIRNMO API. The sample program demonstrates both the rename and move capabilities of the API.


h dftactgrp(*no)                                                 


dRnmObj           pr                  extpgm('QLIRNMO')         

d FrmQualObj                    20    const                     

d ObjTyp                        10    const                     

d ToQualObj                     20    const                     

d RplObj                         1    const                     

d ErrCde                              likeds(QUSEC)             

d FrmASPDevice                  10    const options(*nopass)    

d ToASPDevice                   10    const options(*nopass)    


dSndPgmMsg        pr                  extpgm('QMHSNDPM')        

d MsgID                          7    const                     

d QualMsgF                      20    const                     

d MsgDta                     65535    const options(*varsize)   

d LenMsgDta                     10i 0 const                     

d MsgTyp                        10    const                    

d CSE                           10    const                    

d CSE_Counter                   10i 0 const                    

d MsgKey                         4                             

d ErrCde                              likeds(QUSEC)            

d LenCSE                        10i 0 const options(*nopass)   

d QualCSE                       20    const options(*nopass)   

d PgmMsgWait                    10i 0 const options(*nopass)   

d CSETyp                        10    const options(*nopass)   

d MsgDtaCCSID                   10i 0 const options(*nopass)   


dObjTyp           s             10                             

dLenMsgDta        s             10i 0                          

dMsgKey           s              4                             


dFrm              ds                  qualified                

d Obj                           10                             

d Lib                           10                          


dTo               ds                  qualified             

d Obj                           10                          

d Lib                           10                          


dArchive          ds                  qualified     

d Obj                           10                  

d Lib                           10    inz('ARCHIVE')


dRplOpt           s              1                          

dRplNo            c                   '0'                    

dRplYes           c                   '1'                   


dQualMsgF         ds                                        

d MsgF                          10    inz('QCPFMSG')        

d MsgL                          10    inz('*LIBL')          


 /copy qsysinc/qrpglesrc,qusec                              


dErrCde           ds                  qualified             

d Hdr                                 likeds(QUSEC)         

d MsgDta                       512                          


dEscErrCde        ds                  qualified             

d Hdr                                 likeds(QUSEC)         




  ErrCde.Hdr.QUSBPrv = %size(ErrCde);                       

  EscErrCde.Hdr.QUSBPrv = 0;                                


  Frm.Obj = 'FILE1';                                         

  Frm.Lib = 'BHVLIB';                                       

  ObjTyp = '*FILE';                                         


  To.Obj = 'FILE1A';                                         

  To.Lib = 'BHVLIB';                                        


  RplOpt = RplNo;                                            


  RnmObj(Frm :ObjTyp :To :RplOpt :ErrCde);                   



     when ErrCde.Hdr.QUSBAvl = 0;                             

          // Everything is fine, the object was renamed      

     when ErrCde.Hdr.QUSEI = 'CPF3201';                          

          // Already have :To file object. Archive to ARCHIVE    

          // library, replacing any current archived instance    


          Archive.Obj = To.Obj;                                  

          RnmObj(To :ObjTyp :Archive :RplYes :EscErrCde);        

          RnmObj(Frm :ObjTyp :To :RplOpt :EscErrCde);            



          if ErrCde.Hdr.QUSBAvl <= %size(QUSEC);             

             LenMsgDta = 0;                                   


             LenMsgDta = (ErrCde.Hdr.QUSBAvl -               




          SndPgmMsg(ErrCde.Hdr.QUSEI :QualMsgF              

                    :ErrCde.MsgDta :LenMsgDta :'*DIAG'      

                    :'*' :0 :MsgKey :EscErrCde);            




  *inlr = *on;                                               





The application attempts to rename the file object FILE1 to FILE1A in library BHVLIB. When the object is a *FILE (which it is in the provided sample program) and the new object name (FILE1A in the example) already exists in BHVLIB, then the current instance of the new object name (FILE1A) is moved to a library named ARCHIVE. This move to ARCHIVE replaces any previous version of the new object name in the ARCHIVE library. The original object (FILE1) of BHVLIB is then renamed to the new name (FILE1A), still in BHVLIB.


If the object being renamed is not a *FILE and the new object name already exists in BHVLIB, then the application program does not use the ARCHIVE library. Instead, the program logs a diagnostic message to the job log indicating that the new object name currently exists and continues.


For demonstration purposes of how the Error code parameter can be used (an area of confusion that I receive lots of email about), the distinction in how different object types (*FILE vs. non-*FILE) are handled by the application program will be accomplished by examining the message ID field of the Error code parameter.


When the Bytes provided field of an error code structure (QUSBPrv) is set to a value of eight or more (the ErrCde instance of the error code parameter used by the sample application), then APIs do not return escape messages when an error situation is encountered. Rather, the message ID, and the replacement data associated with the message, can be returned in the API Error code parameter. This information can then be examined by the application program and various recovery actions can be implemented.


When the Bytes provided field of an error code structure is set to a value of zero (the EscErrCde instance of the error code parameter used by the sample application), then APIs will return escape messages when an error is encountered. The application program can then monitor for the escape message (which is not as efficient as simply examining an error code structure such as ErrCde) in order to implement recovery actions or, more often the case, end due to the un-monitored escape message being received by the application.


As seen in the sample application program, you can decide on an API call-by-call basis which version of the Error code parameter (ErrCde with no escape messages or EscErrCde with escape messages) you want to use. For a more extensive discussion of the Error code parameter see System API Basics.


When initially calling the QLIRNMO API, the sample program sets the first parameter to the qualified name FILE1 in library BHVLIB, the second parameter identifies the object type as a *FILE, the third parameter indicates that the new object name should be FILE1A in BHVLIB, the fourth parameter passed to the API is set to '0' (do not replace any object found with the name specified by the third parameter), and the fifth parameter indicates that errors encountered by the API should be returned as data within the fifth parameter (ErrCde).


If the object identified by the third parameter currently does not exist in BHVLIB, the API will rename the object and return to the application program. No error was encountered and the Bytes available (QUSBAvl) field of the ErrCde parameter will be set to zero.


If an error was encountered in the running of the API, then the Bytes available (QUSBAvl) field of the ErrCde data structure will be set to a non-zero value. The application program can determine what error was encountered by then examining the exception ID (QUSEI) field of the ErrCde parameter.


If the object identified by the third parameter currently exists in BHVLIB, and the object type is *FILE, the system will return CPF3201 - File &1 in library &2 already exists. Other object types, such as *PGMs, *DTAQs, etc., will return other messages. These messages may include CPF2112 - Object &1 in &2 type *&3 already exists, CPF2132 - Object &1 already exists in library &2, etc.


In the case of CPF3201 being returned to the sample program, the QLIRNMO API is called two additional times as part of the error recovery. The first call is to move the currently existing object (FILE1A in BHVLIB) to the ARCHIVE library. In this case, the fourth parameter is set to '1' (replace any existing instances of FILE1A in ARCHIVE) and the fifth parameter is specified as being the EscErrCde error code data structure. If any error is encountered during the move (for instance, the ARCHIVE library doesn't exist or the user is not authorized to replace the object in ARCHIVE), an escape message is to be sent by the API. As this escape message is not being monitored, the sample program will end abnormally, allowing the developer (or support personnel) to clearly see what went wrong. If the move request was successful, then the next call to the API attempts to rename the original object (FILE1) to the new name (FILE1A). Here, the EscErrCde error code data structure is also used as no error recovery is being attempted if this rename fails.


If any other error is encountered by the initial call to the QLIRNMO API, that is QUSEI is not 'CPF3201', then the program uses the Send Program Message (QMHSNDPM) API to send the error as a diagnostic message to the job log. The program does not end due to the error but does log the error for problem-determination purposes. When calling the QMHSNDPM API, the sample program again uses the EscErrCde error code parameter so that any error in logging the message will result in an escape message.


In this article, we've looked at how you can rename and move objects, a capability that is sure to be of use in some application programs. We've also reviewed how the API error code structure can be used to control how errors are returned to an application program, an essential tool when using system APIs.


As usual, if you have any API questions, send them to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.


Bruce Vining

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at 

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

IBM System i APIs at Work IBM System i APIs at Work
Leverage the power of APIs with this definitive resource.
List Price $89.95

Now On Sale



Support MC Press Online





  • White Paper: Node.js for Enterprise IBM i Modernization

    SB Profound WP 5539

    If your business is thinking about modernizing your legacy IBM i (also known as AS/400 or iSeries) applications, you will want to read this white paper first!

    Download this paper and learn how Node.js can ensure that you:
    - Modernize on-time and budget - no more lengthy, costly, disruptive app rewrites!
    - Retain your IBM i systems of record
    - Find and hire new development talent
    - Integrate new Node.js applications with your existing RPG, Java, .Net, and PHP apps
    - Extend your IBM i capabilties to include Watson API, Cloud, and Internet of Things

    Read Node.js for Enterprise IBM i Modernization Now!


  • Profound Logic Solution Guide

    SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation.
    Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects.
    The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the companyare not aligned with the current IT environment.

    Get your copy of this important guide today!


  • 2022 IBM i Marketplace Survey Results

    Fortra2022 marks the eighth edition of the IBM i Marketplace Survey Results. Each year, Fortra captures data on how businesses use the IBM i platform and the IT and cybersecurity initiatives it supports.

    Over the years, this survey has become a true industry benchmark, revealing to readers the trends that are shaping and driving the market and providing insight into what the future may bring for this technology.

  • Brunswick bowls a perfect 300 with LANSA!

    FortraBrunswick is the leader in bowling products, services, and industry expertise for the development and renovation of new and existing bowling centers and mixed-use recreation facilities across the entertainment industry. However, the lifeblood of Brunswick’s capital equipment business was running on a 15-year-old software application written in Visual Basic 6 (VB6) with a SQL Server back-end. The application was at the end of its life and needed to be replaced.
    With the help of Visual LANSA, they found an easy-to-use, long-term platform that enabled their team to collaborate, innovate, and integrate with existing systems and databases within a single platform.
    Read the case study to learn how they achieved success and increased the speed of development by 30% with Visual LANSA.


  • Progressive Web Apps: Create a Universal Experience Across All Devices

    LANSAProgressive Web Apps allow you to reach anyone, anywhere, and on any device with a single unified codebase. This means that your applications—regardless of browser, device, or platform—instantly become more reliable and consistent. They are the present and future of application development, and more and more businesses are catching on.
    Download this whitepaper and learn:

    • How PWAs support fast application development and streamline DevOps
    • How to give your business a competitive edge using PWAs
    • What makes progressive web apps so versatile, both online and offline



  • The Power of Coding in a Low-Code Solution

    LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed.
    Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

    • Discover the benefits of Low-code's quick application creation
    • Understand the differences in model-based and language-based Low-Code platforms
    • Explore the strengths of LANSA's Low-Code Solution to Low-Code’s biggest drawbacks



  • Why Migrate When You Can Modernize?

    LANSABusiness users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
    In this white paper, you’ll learn how to think of these issues as opportunities rather than problems. We’ll explore motivations to migrate or modernize, their risks and considerations you should be aware of before embarking on a (migration or modernization) project.
    Lastly, we’ll discuss how modernizing IBM i applications with optimized business workflows, integration with other technologies and new mobile and web user interfaces will enable IT – and the business – to experience time-added value and much more.


  • UPDATED: Developer Kit: Making a Business Case for Modernization and Beyond

    Profound Logic Software, Inc.Having trouble getting management approval for modernization projects? The problem may be you're not speaking enough "business" to them.

    This Developer Kit provides you study-backed data and a ready-to-use business case template to help get your very next development project approved!

  • What to Do When Your AS/400 Talent Retires

    FortraIT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators is small.

    This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:

    • Why IBM i skills depletion is a top concern
    • How leading organizations are coping
    • Where automation will make the biggest impact


  • Node.js on IBM i Webinar Series Pt. 2: Setting Up Your Development Tools

    Profound Logic Software, Inc.Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. In Part 2, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Attend this webinar to learn:

    • Different tools to develop Node.js applications on IBM i
    • Debugging Node.js
    • The basics of Git and tools to help those new to it
    • Using as a pre-built development environment



  • Expert Tips for IBM i Security: Beyond the Basics

    SB PowerTech WC GenericIn this session, IBM i security expert Robin Tatam provides a quick recap of IBM i security basics and guides you through some advanced cybersecurity techniques that can help you take data protection to the next level. Robin will cover:

    • Reducing the risk posed by special authorities
    • Establishing object-level security
    • Overseeing user actions and data access

    Don't miss this chance to take your knowledge of IBM i security beyond the basics.



  • 5 IBM i Security Quick Wins

    SB PowerTech WC GenericIn today’s threat landscape, upper management is laser-focused on cybersecurity. You need to make progress in securing your systems—and make it fast.
    There’s no shortage of actions you could take, but what tactics will actually deliver the results you need? And how can you find a security strategy that fits your budget and time constraints?
    Join top IBM i security expert Robin Tatam as he outlines the five fastest and most impactful changes you can make to strengthen IBM i security this year.
    Your system didn’t become unsecure overnight and you won’t be able to turn it around overnight either. But quick wins are possible with IBM i security, and Robin Tatam will show you how to achieve them.

  • Security Bulletin: Malware Infection Discovered on IBM i Server!

    SB PowerTech WC GenericMalicious programs can bring entire businesses to their knees—and IBM i shops are not immune. It’s critical to grasp the true impact malware can have on IBM i and the network that connects to it. Attend this webinar to gain a thorough understanding of the relationships between:

    • Viruses, native objects, and the integrated file system (IFS)
    • Power Systems and Windows-based viruses and malware
    • PC-based anti-virus scanning versus native IBM i scanning

    There are a number of ways you can minimize your exposure to viruses. IBM i security expert Sandi Moore explains the facts, including how to ensure you're fully protected and compliant with regulations such as PCI.



  • Encryption on IBM i Simplified

    SB PowerTech WC GenericDB2 Field Procedures (FieldProcs) were introduced in IBM i 7.1 and have greatly simplified encryption, often without requiring any application changes. Now you can quickly encrypt sensitive data on the IBM i including PII, PCI, PHI data in your physical files and tables.
    Watch this webinar to learn how you can quickly implement encryption on the IBM i. During the webinar, security expert Robin Tatam will show you how to:

    • Use Field Procedures to automate encryption and decryption
    • Restrict and mask field level access by user or group
    • Meet compliance requirements with effective key management and audit trails


  • Lessons Learned from IBM i Cyber Attacks

    SB PowerTech WC GenericDespite the many options IBM has provided to protect your systems and data, many organizations still struggle to apply appropriate security controls.
    In this webinar, you'll get insight into how the criminals accessed these systems, the fallout from these attacks, and how the incidents could have been avoided by following security best practices.

    • Learn which security gaps cyber criminals love most
    • Find out how other IBM i organizations have fallen victim
    • Get the details on policies and processes you can implement to protect your organization, even when staff works from home

    You will learn the steps you can take to avoid the mistakes made in these examples, as well as other inadequate and misconfigured settings that put businesses at risk.



  • The Power of Coding in a Low-Code Solution

    SB PowerTech WC GenericWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed.
    Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

    • Discover the benefits of Low-code's quick application creation
    • Understand the differences in model-based and language-based Low-Code platforms
    • Explore the strengths of LANSA's Low-Code Solution to Low-Code’s biggest drawbacks



  • Node Webinar Series Pt. 1: The World of Node.js on IBM i

    SB Profound WC GenericHave you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.
    Part 1 will teach you what Node.js is, why it's a great option for IBM i shops, and how to take advantage of the ecosystem surrounding Node.
    In addition to background information, our Director of Product Development Scott Klement will demonstrate applications that take advantage of the Node Package Manager (npm).
    Watch Now.

  • The Biggest Mistakes in IBM i Security

    SB Profound WC Generic The Biggest Mistakes in IBM i Security
    Here’s the harsh reality: cybersecurity pros have to get their jobs right every single day, while an attacker only has to succeed once to do incredible damage.
    Whether that’s thousands of exposed records, millions of dollars in fines and legal fees, or diminished share value, it’s easy to judge organizations that fall victim. IBM i enjoys an enviable reputation for security, but no system is impervious to mistakes.
    Join this webinar to learn about the biggest errors made when securing a Power Systems server.
    This knowledge is critical for ensuring integrity of your application data and preventing you from becoming the next Equifax. It’s also essential for complying with all formal regulations, including SOX, PCI, GDPR, and HIPAA
    Watch Now.

  • Comply in 5! Well, actually UNDER 5 minutes!!

    SB CYBRA PPL 5382

    TRY the one package that solves all your document design and printing challenges on all your platforms.

    Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product.

    Request your trial now!

  • Backup and Recovery on IBM i: Your Strategy for the Unexpected

    FortraRobot automates the routine tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
    - Simplified backup procedures
    - Easy data encryption
    - Save media management
    - Guided restoration
    - Seamless product integration
    Make sure your data survives when catastrophe hits. Try the Robot Backup and Recovery Solution FREE for 30 days.

  • Manage IBM i Messages by Exception with Robot

    SB HelpSystems SC 5413Managing messages on your IBM i can be more than a full-time job if you have to do it manually. How can you be sure you won’t miss important system events?
    Automate your message center with the Robot Message Management Solution. Key features include:
    - Automated message management
    - Tailored notifications and automatic escalation
    - System-wide control of your IBM i partitions
    - Two-way system notifications from your mobile device
    - Seamless product integration
    Try the Robot Message Management Solution FREE for 30 days.

  • Easiest Way to Save Money? Stop Printing IBM i Reports

    FortraRobot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing.
    Manage your reports with the Robot Report Management Solution. Key features include:

    - Automated report distribution
    - View online without delay
    - Browser interface to make notes
    - Custom retention capabilities
    - Seamless product integration
    Rerun another report? Never again. Try the Robot Report Management Solution FREE for 30 days.

  • Hassle-Free IBM i Operations around the Clock

    SB HelpSystems SC 5413For over 30 years, Robot has been a leader in systems management for IBM i.
    Manage your job schedule with the Robot Job Scheduling Solution. Key features include:
    - Automated batch, interactive, and cross-platform scheduling
    - Event-driven dependency processing
    - Centralized monitoring and reporting
    - Audit log and ready-to-use reports
    - Seamless product integration
    Scale your software, not your staff. Try the Robot Job Scheduling Solution FREE for 30 days.