Wed, Apr
0 New Articles

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 This email address is being protected from spambots. You need JavaScript enabled to view it.. 

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

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 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. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • 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 company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY 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. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) 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:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. 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:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot 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:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business 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.

  • 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:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic 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.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? 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: