• The Four Hundred
  • Subscribe
  • Media Kit
  • Contributors
  • About Us
  • Contact
Menu
  • The Four Hundred
  • Subscribe
  • Media Kit
  • Contributors
  • About Us
  • Contact
  • Guru: Flexible Interfaces

    November 1, 2021 Ted Holt

    The details are murky, it’s been eons ago. Probably the mid-1990’s. I was working on an AS/400 that ran a mixture of System/36 and native applications. I needed to call a program that had been written in the latest version of RPG from both S/36 RPG II and native RPG III (a.k.a. RPG/400) programs. I hope I’m remembering this correctly. It’s been so long.

    The problem I ran into was rooted in a numeric parameter. S/36 programs passed numeric parameters in zoned decimal format, whereas native RPG and CL programs used packed decimal. The called program defined the parameter as packed decimal. I could have changed the called program and the native callers to use data structures to define the parameter as zoned decimal, but the idea didn’t thrill me. I ended up changing the called program to accept the parameter in either packed decimal or zoned decimal format.

    Such was my introduction to flexible interfaces, and it was only an introduction. Through the years, I’ve had to provide interface alternatives from time to time. Fortunately, it is not difficult.

    The First Decision

    When faced with the need for more than one interface into a routine (program or subprocedure), the first choice you must make is whether or not to use a wrapper. A wrapper is a routine that stands between a caller and another, incompatible routine.

    I’ll stick to the same example to illustrate. Here’s part of program CUS004R, which accepts a seven-digit customer account number as packed decimal.

    dcl-pi *n;
        inCustomer    packed(7)   const;
    end-pi;
    
    // Use inCustomer to do something.
    

    I need to call this program from an RPG II program, which cannot pass packed-decimal parameters.

    Here are the salient pieces of wrapper program CUS005R, which bridges the gap between the two.

    **free
    dcl-pi *n;
        inCustomer    zoned(7)   const;
    end-pi;
    
    dcl-pr  CUS004R   extpgm;
        inCustomer    packed(7)   const;
    end-pr  CUS004R;
    
    dcl-s Customer    packed(7);
    
    Customer = inCustomer;
    CUS004R (Customer);
    
    return;
    

    CUS005 receives the customer number in zoned decimal format, reformats the value into packed decimal, and calls CUS004R.

    In this the case, the parameter is passed as input only. That is, CUS004R does not change it. If there were input-output (updateable) or output-only parameters, wrapper program CUS005R would have reformat them from packed to zoned decimal before returning to caller CUS006R.

    Finally, here’s caller program CUS006R, which passes zoned-decimal parameters. (I don’t have access to a system with the S/36 environment at present, so I use RPG III instead.)

    I            DS
    I                                        1   70CUSTNO
     *
    C                     CALL 'CUS005R'
    C                     PARM           CUSTNO
    

    Voilà! CUS006R calls CUS004R indirectly using wrapper CUS005R.

    Using a wrapper is a perfectly good programming technique. If you look through the alphabetic list of APIs in the API Finder, you’ll often see two names — a short one in all caps and a longer one in mixed case — for an API. An example is QSYRTVFI/QsyRetrieveFunctionInformation. I understand that in many (most? all?) cases, the short name is a program wrapper over a procedure of the longer name. In other words, you can access the same routine as a program call or a subprocedure call. If you use the Display Program (DSPPGM) command to view information about QSYRTVFI, you’ll find procedure QsyRetrieveFunctionInformation inside service program QSYFNUSG.

    But you may prefer not to use a wrapper. Instead, you can make CUS004R receive a customer account number in either packed or decimal format.

    dcl-ds   CustomerParm      qualified  based(P1);
       Packed     packed(7)    pos(1);
       Zoned      zoned (7)    pos(1);
    end-ds   Customerparm;
    
    dcl-pi *n;
        inCustomer    char(8);
    end-pi;
    
    dcl-s  SelectedCustomer     packed(7);
    dcl-s  IsValid              ind         inz(*on);
    
    P1 = %addr(inCustomer);
    
    monitor;
       SelectedCustomer = CustomerParm.Packed;
    on-error;
       IsValid = *off;
    endmon;
    
    if not IsValid;
       monitor;
          SelectedCustomer = CustomerParm.Zoned;
       on-error;
          IsValid = *off;
       endmon;
    endif;
    
    if not IsValid;
       // handle the error
    endif;
    

    And that’s what I did those many years ago. IBM had not yet given us the MONITOR op code, so I used something, probably the TESTB opcode, to figure out which type of data I had. The principle is the same.

    If you decide not to use a wrapper, you come to . . .

    The Second Decision

    Will the parameter format be implicit or explicit? Implicit means that the called routine itself determines how the parameter is formatted. Explicit means that the caller must tell the called routine what the parameter looks like. Both methods are valid, and I don’t consider one any better than the other.

    In the last example, the parameter format was implicit. For an example of an explicit definition, I once again turn to IBM APIs. The Retrieve Object Description API (QUSROJBD) can return data in four formats. The caller uses the third parameter to tell the API which format to use — OBJD0100, OBJD0200, OBJD0300, or OBJD0400. If new data formats are needed someday, IBM will have no trouble adding them.

    That’s not the only explicit parameter definition in that API. The sixth parameter, error code, supports various formats, and the caller loads the bytes-provided subfield of a data structure to specify how to handle an exception.

    Do You Really Need It?

    To write a wrapper or not, to explicitly or implicitly describe the data, these are not life-or-death questions. Whatever you decide, the result will probably work fine. Either way you get less duplicated source code, and your routine can adapt more easily to organizational changes.

    However, don’t forget the YAGNI principle. Perhaps you’re writing a new Web API. Should you support every data format you can think of — XML, JSON, CSV, pipe-delimited, ad infinitum ad nauseum? I don’t think so. I would suggest supporting only the one(s) you know you’ll need and wait for the users of your API to request others. Who knows? A few years from now, you might have to add support for data formats that have not been invented yet.

    According to Bernard Ighner, Everything Must Change. As much as we might like to freeze the status quo at a pleasant equilibrium, the world doesn’t work that way. This applies to information systems as much as anything, and like life in general, the skill we need is not to predict the future but to design our applications to be open to change. Allowing for flexibility in the passing of parameters can be part of that design.

    RELATED STORIES

    Everything Must Change (Oleta Adams)

    Everything Must Change (Quincy Jones)

    Alphabetic List of APIs

    Retrieve Object Description (QUSROBJD) API

    Guru 2020: Suggested Resolutions, One Prediction

    APIs Sometimes Fail (But Programmers Don’t Have To)

    Share this:

    • Reddit
    • Facebook
    • LinkedIn
    • Twitter
    • Email

    Tags: Tags: 400guru, API, AS/400, CL, CSV, FHG, Four Hundred Guru, IBM i, JSON, RPG, RPG/400, S/36, XML

    Sponsored by
    UCG Technologies

    CYBER-ATTACKS ON THE RISE. PROTECT WITH THE TRIPLE PLAY.

    COVID-19 has not only caused a global pandemic, but has sparked a “cyber pandemic” as well.

    “Cybersecurity experts predict that in 2021, there will be a cyber-attack incident every 11 seconds. This is nearly twice what it was in 2019 (every 19 seconds), and four times the rate five years ago (every 40 seconds in 2016). It is expected that cybercrime will cost the global economy $6.1 trillion annually, making it the third-largest economy in the world, right behind those of the United States and China.”1

    Protecting an organization’s data is not a single-faceted approach, and companies need to do everything they can to both proactively prevent an attempted attack and reactively respond to a successful attack.

    UCG Technologies’ VAULT400 subscription defends IBM i and Intel systems against cyber-attacks through comprehensive protection with the Triple Play Protection – Cloud Backup, DRaaS, & Enterprise Cybersecurity Training.

    Cyber-attacks become more sophisticated every day. The dramatic rise of the remote workforce has accelerated this trend as cyber criminals aggressively target company employees with online social engineering attacks. It is crucial that employees have proper training on what NOT to click on. Cyber threats and social engineering are constantly evolving and UCG’s Enterprise Cybersecurity Training (powered by KnowBe4) is designed to educate employees on the current cutting-edge cyber-attacks and how to reduce and eliminate them.

    A company is only as strong as its weakest link and prevention is just part of the story. Organizations need to have a quick response and actionable plan to implement should their data become compromised. This is the role of cloud backup and disaster-recovery-as-a-service (DRaaS).

    Data is a company’s most valuable asset. UCG’s VAULT400 Cloud Backup provides 256-bit encrypted backups to two (2) remote locations for safe retrieval should a cyber-attack occur. This is a necessary component of any protection strategy. Whether a single click on a malicious link brings down the Windows environment or an infected SQL server feeds the IBM i, once the data is compromised, there is no going back unless you have your data readily available.

    Recovery is not a trivial task, especially when you factor in the time sensitive nature of restoring from an active attack. This leads to the third play of the Triple Play Protection – DRaaS.  Companies have myriad concerns once an attack is realized and a managed service disaster recovery allows employees to keep focus on running the business in a crisis state.

    The combination of training employees with secure backup and disaster recovery offers companies the best chance at avoiding financial disruption in an age of stronger, more frequent cyber-attacks.

    Reach out to UCG Technologies to discuss your company’s security needs and develop a data protection plan that fits you best.

    ucgtechnologies.com/triple-play

    800.211.8798 | info@ucgtechnologies.com

    Share this:

    • Reddit
    • Facebook
    • LinkedIn
    • Twitter
    • Email

    As I See It: Home Work PHP Is Here To Stay: PHP 8 And Beyond

    2 thoughts on “Guru: Flexible Interfaces”

    • Russ Khoury says:
      November 1, 2021 at 9:33 am

      Hi Ted, I’ve used the wrapper technique for this as well. If you ever need something checked on a S36 EE system, I can do that for you as while I’m in my semi-retired stage I’m still doing work for a couple of clients who operated in a mixed environment. All the best.

      Reply
    • Ted Holt says:
      November 2, 2021 at 3:23 pm

      Thanks, Russ. That’s very kind of you. It’s been a L-O-N-G time since I used the S/36 environment.

      Reply

    Leave a Reply Cancel reply

TFH Volume: 31 Issue: 72

This Issue Sponsored By

  • TL Ashford
  • Perforce Software
  • UCG Technologies
  • Connectria
  • Manta Technologies

Table of Contents

  • Expanding The Operating System Matrix For Power10
  • PHP Is Here To Stay: PHP 8 And Beyond
  • Guru: Flexible Interfaces
  • As I See It: Home Work
  • IBM to Resell DSI’s VTL In Its IBM i Cloud

Content archive

  • The Four Hundred
  • Four Hundred Stuff
  • Four Hundred Guru

Recent Posts

  • The Cloud’s Future Is So Bright, So Why Are You So Glum?
  • Most App Modernization Projects a Struggle, Survey Finds
  • COMMON Launches IBM i Security Conference
  • Four Hundred Monitor, August 17
  • A Slew Of Add-On Services For Power10 Systems
  • Power10 Midrange Machine: The Power E1050
  • IBM Puts The Finishing Touches On PowerHA For IBM i 7.5
  • Guru: Regular Expressions, Part 2
  • Get Your Security Education, And Not From The School Of Hard Knocks
  • IBM i PTF Guide, Volume 24, Number 33

Subscribe

To get news from IT Jungle sent to your inbox every week, subscribe to our newsletter.

Pages

  • About Us
  • Contact
  • Contributors
  • Four Hundred Monitor
  • IBM i PTF Guide
  • Media Kit
  • Subscribe

Search

Copyright © 2022 IT Jungle

loading Cancel
Post was not sent - check your email addresses!
Email check failed, please try again
Sorry, your blog cannot share posts by email.