29
Fri, Nov
0 New Articles

Pointer Fields

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

A pointer is a type of RPG IV field, just like any other field. Pointer fields contain a specific kind of data that is interpreted as a memory address. Suppose your system has 1 GB of memory installed on it. Theoretically, a pointer in a program running on that system could have the memory address for any of those 1 billion bytes of memory. In reality, it could probably contain many more than 1 billion addresses because OS/400 uses a form of virtual storage.

In RPG IV programs, you use memory addresses today without thinking about them. For example, when you pass parameters from one program to another, you pass the address of the field you are passing, not the data itself. This is referred to as "pass by reference."

Each field declared in an RPG IV program is automatically assigned a memory address at runtime. If a character field is declared with a length of 100, 100 bytes of memory are allocated for the field. The field is assigned the address of those 100 bytes.

Suppose you had the ability to retrieve the address of that 100-byte field in that same RPG IV program. What if you could look up the address of the field and copy that address into another field in our program? Well, you can.

RPG IV has a built-in function named %ADDR that returns the memory address of any field declared in the program. The following example illustrates how you can use the %ADDR built-in function to retrieve the address of a field and then copy that address into a pointer field.

0001 D CSTNAM          S            100A
0002 D ptr             S               *
      *
0004 C                   Eval      ptr = %addr(CSTNAM)

On line 1 in this example, the CSTNAM field is declared with a length of 100 and a data-type of character. On line 2, the field named PTR is declared with a data type of pointer. When a program containing these three lines is run, storage for the CSTNAM and PTR variables is automatically allocated. One hundred bytes is allocated for the CSTNAM field, and 8 bytes is allocated for the PTR field.

On line 4, the %ADDR built-in function is used to copy the memory address assigned to the CSTNAM field to the PTR field. If, at runtime, the CSTNAM field is assigned the memory address of 0DEF5640:0001F3CA, the %ADDR built-in function (line 4) extracts that address and copies it to the PTR field. PTR is not a pointer to the memory allocated for the CSTNAM field.

What Good Is a Pointer?

In the previous example, a pointer is simply used to store the memory address of another field. That by itself isn't very interesting or useful in RPG IV. To take advantage of the pointer value stored in the PTR field, you need another variable declaration in the program. In the example below, I've added one more Definition specification to the previous example.

0001 D CSTNAM          S            100A
0002 D ptr             S               *
0003 D Buffer          S            100BASED(ptr)
      *
0004 C                   Eval      ptr = %addr(CSTNAM)

In this example, line 3 is added to declare the BUFFER field. The BUFFER field is a "based" variable; that is, it includes the BASED keyword. Whenever a field is declared with the BASED keyword, no storage (meaning no memory) is allocated at a program's start time for that variable. A based variable only provides access to the memory address stored in its associated pointer field.

This means that the memory at whatever address is stored in the PTR variable may be manipulated (viewed, copied, changed) through its based variable (the BUFFER field in this example). You can change the memory at the address stored in the PTR variable by simply modifying the content of the BUFFER field.

In the second example, the CSTNAM field is 100 bytes long, as is the BUFFER field. After line 4 is run, the PTR field contains the memory address of the CSTNAM field. Therefore, after line 4 is run, the memory automatically allocated for the CSTNAM field is also visible through the BUFFER field. In other words, they both reference the same location in memory.

Pointers are useful when you need to access a memory location through multiple based variables--for example, when you have a large, unformatted field/buffer that needs to be accessed and manipulated at runtime or when a data structure just isn't a good fit for the problem.

Pointers also provide a way for you to determine at program runtime whether or not you actually need to use a certain field. For example, if you don't need the data structure named COMPINFO (see Figure 1), why have the storage for the data structure automatically allocated? You can simply allocate the storage for COMPINFO when you need it.

 D COMPINFO        DS                  Based(myPtrField)
 D  CompName                     30A
 D  Contact                      20A
 D  Address                      30A
 D  City                         20
 D  State                         2A
 D  ZipCode                      10A
 D  Country                      20A
 D  SalesNotes                  500A   Varying      
                        
  /IF DEFINED(*V5R1M0) 
 C                   eval      myPtrField = %Alloc(%size(COMPINFO)+2)
  /ELSE 
 C                   eval      memSize  = %size(COMPINFO)+2  
 C                   Alloc     memsize       myPtrField
  /ENDIF 
  **  The rest of the app goes here...
 C                   DeAlloc                 myPtrField

Figure 1: Dynamically allocated memory

The COMPINFO data structure is a long variable. The program that uses COMPINFO does not always need to store data in it. Sometimes, when the program runs, the data structure is ignored. By basing the data structure on a pointer, the data structure becomes a based variable, and no storage for it is allocated at program runtime. Instead, when the data structure is needed, the program allocates storage for it, using the ALLOC opcode or %ALLOC built-in function depending on the version of OS/400 you compiled the program on. This technique frees up the storage for COMPINFO when it is not needed. Of course, by allocating the memory for the COMPINFO field at runtime, it is your responsibility to deallocate it using the DEALLOC operation code. This is usually done just before the program ends.

Based variables can act as a window into another field's memory, or they can have their own memory allocated for them at runtime. Pointers provide the ability to do these kinds of things, and although they are interesting data types, you should consider them only when no other natural RPG IV method is available.

"Module Where Used" Utility

As promised last time, I have posted the Module Where Used utility for download. The utility is very basic. It creates a list of modules used for a program or service program. You can generate the list using generic, full, or *ALL program names. I have written a command wrapper for the utility. The syntax for this command is as follows:

CrtModXRef OBJ( [library/] generic-object | *ALL ) OBJTYPE(*PGM | *SRVPGM)

The CRTMODXREF command generates a database of *MODULE where used information. Enter the program name (generic, full, or *ALL) along with the library name (*ALL, *ALLUSR, *USRLIBL, or *CURLIB), and specify the type of objects to add to the list. Valid choices are *PGM or *SRVPGM.

Download the source code here.

Bob Cozzi has been programming in RPG since 1978. Since then, he has written many articles and several books, including The Modern RPG Language --the most widely used RPG reference manual in the world. Bob is also a very popular speaker at industry events such as COMMON and RPG World and is the author of his own Web site, rpgiv.com.

BOB COZZI

Bob Cozzi is a programmer/consultant, writer/author, and software developer. His popular RPG xTools add-on subprocedure library for RPG IV is fast becoming a standard with RPG developers. His book The Modern RPG Language has been the most widely used RPG programming book for more than a decade. He, along with others, speaks at and produces the highly popular RPG World conference for RPG programmers.


MC Press books written by Robert Cozzi available now on the MC Press Bookstore.

RPG TnT RPG TnT
Get this jam-packed resource of quick, easy-to-implement RPG tips!
List Price $65.00

Now On Sale

The Modern RPG IV Language The Modern RPG IV Language
Cozzi on everything RPG! What more could you want?
List Price $99.95

Now On Sale

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

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: