05
Thu, Dec
6 New Articles

Dynamic Data

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

As you begin taking advantage of ILE and breaking your applications into small pieces, another problem may start to appear. Procedures start to reference, and become referenced by, so many other procedures that a simple change ends up affecting dozens of other procedures. A Mediator is a design pattern that helps to reduce this interdependence by providing a middle layer that prevents procedures from referring to each other directly.

If you were asked to write a set of easy-to-use I/O procedures with the flexibility and power of embedded SQL, you might respond, “I’ll have it for you as soon as we get that Y10K problem licked.” After you finish reading this article, you can optimistically reply, “Sure, I’ll use a Mediator.” The key is in the Mediator, which takes requests from an application program and delegates them to supporting procedures. Mediators are not limited to supporting I/O; they can also be used to simplify functions such as editing numbers and display processing.

Mediators, as described in the book Design Patterns: Elements of Reusable Object- Oriented Software (see “References” below for publication information), define how objects interact with one another. When a Mediator is used, objects do not refer to each other directly. Instead, they refer to the Mediator that passes requests on to the object that supports the requested function. ILE and the dynamic linking program APIs make it much easier to create Mediators on the AS/400. These APIs allow you to create service programs that are referred to only at runtime. These service programs provide the same function that Dynamic Link Libraries (DLLs) provide to Windows programs.

One area that can benefit from the use of Mediators is I/O processing. Included in this article is an example of a simple I/O processing Mediator. (The code for the example in this article can be found on MC’s Web site at http://midrangecomputing.com /mc/98/12.) Using this example as a base, a complete I/O processing subsystem can be created. A Mediator can help you exploit other areas, such as messaging, data validation, error handling, and display interaction.

My Applications Get Along; Why Do They Need a Mediator?

You do not need to use an object-oriented language to benefit from Mediators. A Mediator provides a single interface that encapsulates the behavior of many objects. The Mediator replaces many-to-many relationships that typically exist between clients and servers, with one-to-many relationships, which are simpler and more extensible. Many clients refer to the Mediator, which passes the requests on to many servers. This extra level of abstraction allows the clients and servers to vary independently.

Because clients and servers are independent, client procedures can be enhanced, or have their interfaces changed, without affecting server procedures. Conversely, server procedures can be enhanced without affecting client procedures. Another reason to use a Mediator is to reduce the interaction complexity between clients and servers. The complexity is moved to the Mediator, which prepares client input or combines and enhances server functions.

Mediated I/O

Mediators that are used to support I/O can map input and output buffers, set error flags, and return messages. The dynamic data modules demonstrate how a Mediator can be used to support I/O tasks. In this example, the tasks are OpnFil and GetRcd. These tasks can be used as a base to create a comprehensive I/O system.

Normally, there would be many clients and servers connected by a Mediator. The I/O server modules would be similar, containing the same procedures. The I/O server modules could even be generated using a description of the file that each server module supports. The dynamic data example contains a single client and server procedure. They are called DDClient and DDQDBFDEP. The Mediator in this example is DDMediator. The server could be used to support more than one file as long as the file’s formats are the same, but I have included only one file in this example.

Several of the procedures and prototypes included in the Mediator module in this example could be moved to a module that better fits their purpose. I placed them in the Mediator to make it easier to create and run the dynamic data example. When you begin to create your own Mediators, you should move the subprocedures that are not related to I/O processing into a general-purpose service program.

Because the Mediator has no idea how many files will be opened and what fields will be requested, this information is stored in memory that is dynamically allocated. Because dynamically allocated memory is lost when an activation group is reclaimed, you may want to explore using a user space and user indexes created in QTEMP. When an open request is made, a handle is assigned. The handle is used to set an occurrence of a multiple- occurrence data structure that contains pointers to format, file, and field information.

One of the Mediator’s tasks is the mapping of data between the client and I/O server procedure. When the Mediator is called, key values that are passed are updated in the server’s I/O buffer. If a record is read, the field values returned in the server’s I/O buffer are mapped to the area passed by the client. To support this mapping, the server has a procedure that returns field and key information for the format and files that are supported.

Dynamically Importing Data and Procedures

The server itself stores information about the record format and files supported by the server. The server module uses the Export keyword on procedures and fields that are made available to the Mediator. Normally, exported procedures and data elements are copied or linked together when a program is compiled. This linking can also be done dynamically at runtime through the use of APIs. Runtime linking slows down the speed of calls, but in typical business applications, which are usually I/O bound, the impact of a dynamic call is very slight.

To access the server’s exported variables, the server service program is activated by calling the Activate Bound Program (QleActBndPgm) API. One of the parameters passed to this API is a system pointer to a program or service program. The Mediator uses one of the C MI library functions, Resolve System Pointer (RSLVSP), to set the system pointer. Prior to calling this API, you must convert the object type *SRVPGM to its hex equivalent.

To do this, I call procedure CvtObjTyp, which uses the Convert Type (QLICVTTP) API. After the program is activated, the Get Export (QleGetExp) API is called to retrieve pointers to the exported variables and procedures used by the Mediator. The first time a format or file is used, the Mediator initializes information about the format and files that the server supports by calling the server’s BufInf and KeyInf procedures. This information is reused on subsequent opens for the same format or file. (In this example, it is used only for the specific activation group. In the Mediator I created here, I store this information in user spaces/indexes in QTEMP, which crosses activation groups.)

Mapping the Buffers

Ideally, the formats of the input buffers in the client and I/O server would not have to match. Also, the client application should be able to select fields. The client should also determine to where data will be placed on input, and from where it will be taken on output.

In the I/O example, the Mediator maps the server’s I/O buffer to the area passed from a client. When the Mediator receives an OpnFil request, the field buffer information is loaded into a table that contains each field’s offset in the buffer and its size. This information is used to map data from the I/O buffer to the area provided by the client, which allows the client to pass a list of fields and receive their values at the location the client specifies. A table is also built that contains offsets and sizes for the file’s key fields.

To allow the format of the client and server buffers to vary independently, the I/O buffer in the server is based on an exported pointer, which allows the assignment to be made by the Mediator and simplifies the server program. Also, because the Mediator maps the buffer, the format of the buffer passed from the client does not have to match the format of the buffer as defined in the server. The Mediator retrieves a description of the file buffer from the server by calling a procedure that returns the available fields and their sizes.

When the Mediator receives a request to read a record, it first determines whether the client specified all fields (special value *) on the open and if the buffer is long enough for all fields. If these conditions are met, the Mediator assigns the server’s I/O buffer directly to the area passed from the client. The server’s I/O buffer can be the same size as or larger than the record format being serviced. Consequently, if a subset of fields was requested or the area passed from the client will not hold an entire record, the Mediator allocates dynamic storage and assigns that storage to the server’s I/O buffer.

To assign the server buffer to the area passed from the client or to the allocated storage, the Mediator sets the exported pointer that the server’s I/O buffer is based on. The Mediator then changes the exported pointer to point to the area passed from the client or the allocated storage. You might be thinking, “Golly (or something else). Pointers are hard enough to understand; now, we have pointers to pointers!” Don’t worry. Once you have this code working, you won’t need to worry about pointers in either your client applications or your server procedures.

After assigning the server buffer, the Mediator updates the buffer with the key values passed from the client. A C library function, MemCpy, is used to update the buffer using the key field information that was gathered when the file was opened.

After calling the server, the Mediator has to map the returned values to the area passed from the client. The table of field offsets and sizes that was built when the file was opened is used to update the area passed from the client with the values returned from the server. This mapping is not necessary if the Mediator mapped the server I/O buffer directly to the area passed from the client.

Using the Client

The DDClient demonstrates the use of a Mediator by opening a file and then reading several records. Information from the records that are read is displayed using the DISPLAY op code. The client calls the Mediator’s OpnFil and GetRcd procedures. Because RPG IV does not support variable-type parameters, key values are passed using pointers. Instead of passing the key directly, the client passes a pointer to the key value. To do this, use %ADDR(KeyFld). Another limitation of RPG IV is the inability to pass variable-sized data

structures (because operational descriptors are not supported for data structures). To get around this limitation, I defined a field that is based on a pointer that is initialized to the address of a data structure.

To create the client, you need to create the DDClient and DDMediator modules. You will also need to create the MSGTKT service program (see “RPG Building Blocks: ILE Message Handling,” MC, November 1998). Use the Create Program (CRTPGM) command with modules DDClient, DDMediator, service program MSGTKT, and the binding directory QC2LE. After you have created the client program, you will need to create the server service program. Use the Create Service Program (CRTSRVPGM) command and specify module DDQDBFDEP and EXPORT(*ALL).

After the client program and server service program are created, you can run the DDClient program. The library that contains the server service program needs to be in your library list. When you call the DDClient program, you should see a list of fields related to the file QADBFDEP. To better understand how the Mediator works, you may want to start Debug and step through the program as it executes.

One thing you may notice when you step through the Mediator in Debug is that some of the variables cannot be displayed using the debugger’s EVAL operation. This is caused by a debugger limitation. Fields based on pointers that are contained in data structures cannot be displayed directly. To display their value, you need to EVAL the basing pointer and specify :X or :C followed by a length. In most cases, this step is not a big problem, but some variables cannot be displayed at all, which can make debugging more difficult.

The Dynamic Duo

After seeing how the dynamic data Mediator uses dynamically imported procedures and data to support I/O tasks, you will probably think of other areas that could benefit from this technique. Mediators can simplify your client applications and help you to create systems that are easily enhanced and modified. Writing a Mediator can be a complex task, but, by writing one, you are moving the complexity from your applications into a single area.

I hope you find Mediators as useful as I have. The ILE and RPG IV are what make Mediators practical. Mediators are a challenge to write, but when you’re done, you may just the find time to take that vacation you’ve been putting off because your applications can be written much more quickly.

References

Design Patterns: Elements of Reusable Object-Oriented Software. Gamma, Erich, Richard Helm, Ralph Johnson, and John M. Vlissides. Reading, Massachusetts: Addison- Wesley Computer and Engineering Publishing Group, 1995

ILE C/C++ MI Library Reference V3R7 (SC09-2418-00, CD-ROM QBJADR00) ILE C for AS/400 Programmer’s Reference V4R2 (SC09-2514-00, CD-ROM QB3AG100)

System API Reference OS/400 Object APIs (SC41-5865-01, CD-ROM QB3AMQ01)

System API Reference OS/400 Program and CL Command APIs V4R2 (SC41- 5870-01, CD-ROM QB3AMV01)

DAVID MORRIS
David Morris has worked with and written about a variety of technologies, including ILE, RPG, business intelligence, SQL, security, and genetic programming. Today, David is developing Web applications that run on the iSeries using RPG, Java, and XML as well as writing about these technologies for technical journals.

MC Press books written by David Morris available now on the MC Press Bookstore.

 

XML for eServer i5 and iSeries XML for eServer i5 and iSeries

In this book, you will learn about Extensible Markup Language (XML), but with an IBM eServer i5/iSeries twist.

List Price $64.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: