Wed, Apr
0 New Articles

Library Operations Through Service Programs

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

RPG and COBOL were not designed for library list operations, so working with library lists in these languages requires calling a CL program or the QCMDEXC API. The subprocedures described in this article were designed to work directly from RPG and COBOL programs. They do everything the CL library list commands do, and more!

Many of us have grown accustomed to calling a CL program or the QCMDEXC API to perform operations such as adding or removing a library from a library list. This usually results in cumbersome and unreadable code that someone will have to maintain in the future. One solution to this problem is to create a host of subprocedures that you can use directly in your RPG or COBOL programs to perform these options. For library list functions, using subprocedures instead of a CL program or the QCMDEXC API not only makes the code more readable, but also enforces code reuse for commonly used operations.

To further explain this concept, I have created a service program with a host of subprocedures that perform library list operations. (The code for this program and for the subprocedures can be found on the MC Web site at www.midrangecomputing. com/mc/99/02.) The subprocedures range from adding a library to the library list to returning the current system, product, current, or user library list.

These subprocedures will come in handy in most applications that require changing the library list. For example, an application that installs new software requires that the library or libraries containing the old program objects and data (as well as the libraries containing the new information) be in the library list. If multiple machines are used, these libraries could have different names. A single job description containing an initial library list is all that is needed to change the library list to the one needed for the software installation.

Another example of when these subprocedures might come in handy would be the times when you use certain applications that are needed only for limited operations. These applications could range from any external tools you may have installed to fax software that is required only when faxing takes place in the application. If the tool or fax software exists

in a separate library, you can use these tools to first verify that the library in question is in the library list. Then, if you find that it is not, add the library to the library list. And, finally, after the specific operation is performed, you can remove the library from the library list.

Once you’ve downloaded the code from MC’s Web site, take a close look at the subprocedures. I will discuss a few keywords that you may not have used before, as well as discuss how each of the subprocedures works. Hopefully, these subprocedures will be of use to you. But, more importantly, every bit of code that you can read and understand will help you build your skills for programming in the ILE environment.

The #PushLib and #PopLib Subprocedures

The #PushLib and #PopLib subprocedures are simple. If you are familiar with the Push and Pop operations used with “stacks” in operations programming, you have probably already guessed what the #PushLib and #PopLib subprocedures do. #PushLib will place the library passed to it onto the top of the library list. #PopLib will either remove the library on the top of the library list or remove the library name specified in the incoming library name parameter.

The #PopLib procedure uses the *NOPASS keyword on the library name parameter. This allows us to call #PopLib without any parameters. You will notice in the code for the #PopLib procedure that if no parameters are passed or if the library to remove equals the special value of *FIRST, #PopLib calls another procedure, #RtvLibL, to retrieve the user library list information and place it into an array. Then #PopLib puts the value of the first element of that array into the library name parameter to be used on the Remove Library List Entry (RMVLIBLE) command.

The #AddLibLE Procedure

The #AddLibLE procedure is used as a good example of replacing something that usually would have been coded as a QCMDEXC in a program with a simple procedure call. The parameters passed to this procedure are the same as the parameters on the Add Library List Entry (ADDLIBLE) command. Again, the keyword *NOPASS is used on the position parameter and the reference library parameter. I would guess that most of the time when you use the ADDLIBLE command you specify only a library. There are cases, however, when you want to place the library somewhere in the middle of the library list, and that is why the position and reference library parameters are optional.

In the first few statements of the #AddLibLE procedure, you will again see the use of another existing procedure, #PushLib. If only a library name is specified, or if the position of the library is the special value *FIRST, you simply call the #PushLib procedure, which already accomplishes this task. This is a simple example of breaking subprocedures down to perform the most basic operation and using the already existing procedure in another procedure.

If a position and reference library are specified in the #AddLibLE procedure, you will simply call QCMDEXC with the ADDLIBLE command, specifying the data passed in. Again, this procedure makes your code much more readable, as you code only the QCMDEXC API call in the procedure itself.

The #ChgLibLJD Procedure

The #ChgLibLJD procedure may be a little confusing at first. The #ChgLibLJD procedure uses a job description that is passed to it and changes the job’s user library list to the initial library list specified in the job description.

This procedure uses the QWDRJOBD API to determine the number of libraries and the initial library list entries contained within the job description. This information is loaded into an array, which QLICHGLL uses to change the user library list.

This procedure could be used when data from different systems is contained in different libraries. When a user is moving from one system to another, a call to this procedure with the name of a job description set up for a specific system would immediately set up the library list for use with that system.

The #RtvLibL Procedure

The #RtvLibL procedure retrieves the system library list, product library, current library, or user library list and returns a pointer to the data structure that contains the library list information. There are four different data structures set up within this procedure, one for each different library list. Depending on the library list type value passed into the procedure, the #RtvLibL procedure will fill and return the location of the data structure containing the library list information requested. On the receiving side of the procedure, a simple generic data structure may be used with the BASED keyword.

This #RtvLibL procedure was used in the #PopLib procedure. This is one working example of how to use the #RtvLibL procedure. Referring back to the #PopLib procedure, you will see that the data structure LibData and the pointer variable LibPtr are declared in the D-specs. The LibData data structure uses the BASED keyword. This keyword tells the system that the location of the data is found at the location referenced by the LibPtr pointer variable type. The LibPtr variable is set by calling the #RtvLibL procedure. If the call is successful, the pointer will contain a reference to where you will find the library list information. If the call is unsuccessful, the #RtvLibL procedure returns *NULL, telling us that an error occurred.

Returning to the #RtvLibL procedure, you will notice another difference in the variable declarations. Each of the four data structures used to retrieve and return the data contains the STATIC keyword. This keyword is used because the data structures are local only to the #RtvLibL procedure. If you had omitted the STATIC keyword, the pointer returned would reference the information that used to contain the information requested during the procedure call.

By the time you get back to the calling program, the particular part of memory that held this information during the call could have already been reused, possibly corrupting the data you had wanted. The STATIC keyword tells the system that the memory holding this information should be made available to all programs and subprocedures in the call stack. Another way around this problem would have been to move the data structures to the global variable definitions.

The #VerLib Procedure

The #VerLib procedure is another simple procedure that lets the calling program know if a specific library is already included in the library list and the position that it is in. The two input parameters required for this procedure are the library name you wish to verify, and which library list to look in. The library list could be the system, product, current, or user library list denoted by *SYSTEM, *PRODUCT, *CURRENT, or *USER respectively. This procedure also makes use of the #RtvLibL procedure, returning the specified library list into a data structure and performing a simple LOOKUP operation—yet another example of using a procedure already created to perform an option instead of reinventing the wheel.

If the library is found in the library list, a number greater than zero is returned. This number tells the position of the library that you have requested verification for in the library list. A value of zero means the library was not found in the library list. A value of negative one indicates that an error occurred somewhere in the process. This error most likely would occur while retrieving the specified library.

The More You Know...

The purpose of my showing you these library functions is twofold. First, I am giving you some code that could help you in your system development. Second, and more important, I am trying to show you that using service programs will simplify your job.

When you reach a point in a program where you realize that a QCMDEXC must be used, chances are that this isn’t the first time you’ve come to such a realization, and that there are other programs that have also used the same QCMDEXC statement. By combining these heavily used commands into a service program and building the command using parameters passed into the procedure, your coding will be easier to maintain and

more readable. Start with one procedure that calls only the QCMDEXC API with the command as the only parameter. If this is the first procedure you create, it will be simple to code, but it will be enough to show you how subprocedures work. You will find that those once-cryptic statements are now nothing more than simple EVAL or CALLP statements.

The use of subprocedures within your system is limited only by your imagination and creativeness. Using subprocedures effectively also takes practice. It is a good idea to create subprocedures that perform smaller tasks and use these smaller subprocedures in other subprocedures. Breaking an operation into simpler operations not only reduces the chance of error, but also limits certain code to one spot on the system. This will make maintenance a much easier proposition in the long run.


AS/400 ILE Concepts V4R2 (SC41-5606-01, CD-ROM QB3AQ701)



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: