Tag: RPG

I have previously mentioned the ON-EXIT operation code, and now it’s the turn of something I should have known about years ago.

Back in the old days, handling files was simple. All of the files you declared would be opened when the program starts and closed again when the program ends.

Now, however, the RPG Cycle is no longer used and all code is (or should be) broken out into discrete procedures. This means that we should also be manually opening and closing files as and when needed. The impact of this is that we need to ensure that any open files are closed when we exit a procedure.

The ON-EXIT opcode helps here, but it’s still a bit of a grind if you have to manually check and close every file that may still be open. It turns out, however, that you don’t need to as the CLOSE operation allows you to close all of the globally defined files at once.

Here’s an example. Run it in debug and watch those files magically close themselves when the program ends.

        ctl-opt dftactgrp(*no) actgrp(*new) main(Main);

        dcl-f LSM101P rename(LSM101P: LSM101R) usropn;
        dcl-f LSM102P rename(LSM102P: LSM102R) usropn;

        dcl-proc Main;

            dcl-pi *n end-pi;

            if not %open(LSM101P);
                open LSM101P;
            endif;

            if not %open(LSM102P);
                open LSM102P;
            endif;

            // Do some processing here
            read LSM101P;
            dsply DESC101;

            return;

        on-exit;
            close *all;

        end-proc;

This post stems from recent conversation on the subject of prototyped parameters. I always pass parameters as read only (using the const keyword) in order to ensure that no unexpected changes in the called procedure can impact the calling procedure.

With this approach, the only value you need to worry about is the value explicitly returned by the procedure and this enforced simplicity makes life much, much easier for whoever ends up maintaining the application.

But, my colleague wanted to know, what do you do if you want your procedure to return multiple values? It doesn’t make much sense, for example, to call a separate procedure for each line of a customer address.

The answer is to use a data structure.

As an example, here’s a main procedure that, among other things, retrieves a customer address. As should be clear, I am using a data structure (ADR) to hold the address and using the procedure getAddress to populate this data structure.

     p Main            b
     d Main            pi

     d ADR             ds                  qualified
     d  Street                       50a   inz
     d  House                         5s 0 inz
     d  Postcode                      4s 0 inz
     d  City                         50a   inz
      /free

        // Some loop reading customers
        // ...

            // Retrieve the customer address
            ADR = GetAddress(CustomerNumber);

            // Continue
            // ...


        return;

      /end-free
     p Main            e

And this is what the getAddress procedure looks like:

     p getAddress      b
     d getAddress      pi                  likeds(ADR)
     d  Customer                     10p 0

      
     d ADR             ds                  qualified
     d  Street                       50a   inz
     d  House                         5s 0 inz
     d  Postcode                      4s 0 inz
     d  City                         50a   inz
      /free


        // Populate the ADR fields
        ADR.Street = 'SomeStreet';
        ...

        // And return the data structure
        return ADR;

      /end-free
     p getHistory      e

As you can see, as long as the ADR data structure is locally defined in both procedures you can easily pass the contents of the data structure from one procedure to the other.

Footnote

I know I am using fixed format definitions here, but the box we were looking at while discussing this is only on 7.1.

I have talked about service programs in the past and, at the time, I mentioned that you need a binding source without really saying why. So, to revisit the subject, using the binding language allows you to change your service program without needing to recompile all of the programs that reference it.

It all comes down to signatures.

You can display the signature of a service program using the following command (adjust for your own library and service program, obviously):

DSPSRVPGM SRVPGM(LSCLIB/LSSUTIL) DETAIL(*SIGNATURE)

This will display a screen similar to the one below:

                      Display Service Program Information
                                                                 Display 1 of 1
 Service program  . . . . . . . . . . . . :   LSSUTIL
   Library  . . . . . . . . . . . . . . . :     LSCLIB
 Owner  . . . . . . . . . . . . . . . . . :   QPGMR
 Service program attribute  . . . . . . . :   RPGLE
 Detail . . . . . . . . . . . . . . . . . :   *SIGNATURE

                                  Signatures:

 62C9C0FAA16B653C4359413F3E9CEB81

Now take a look at any program that references the service program:

DSPPGM PGM(LSCLIB/LS0190R) DETAIL(*SRVPGM)

Will something like this:

                          Display Program Information
                                                                 Display 1 of 1
 Program  . . . . . . . :   LS0190R       Library  . . . . . . . :   LSCLIB
 Owner  . . . . . . . . :   QPGMR
 Program attribute  . . :   RPGLE
 Detail . . . . . . . . :   *SRVPGM


 Type options, press Enter.
   5=Display

      Service
 Opt  Program     Library     Activation  Signature
      LSSUTIL     *LIBL       *IMMED      62C9C0FAA16B653C4359413F3E9CEB81
      QRNXIE      QSYS        *IMMED      D8D9D5E7C9C540404040404040404040
      QRNXIO      QSYS        *IMMED      D8D9D5E7C9D640404040404040404040
      QLEAWI      QSYS        *IMMED      44F70FABA08585397BDF0CF195F82EC1

Note that the signqture of the service program needs to match the signature the referencing program expects, and if they don’t you will waste a day dealing with signature violation errors.

So if I want to add a procedure to a service program (which will change the service program’s signature) without having to identify and recompile every program that refers to it, I need to make use of the binder language.

I generally create the binder language source manually but, if you don’t have this, you can use the RTVBNDSRC command. To retrieve the source for service program LSSUTIL in library LSCLIB you would do this:

RTVBNDSRC SRVPGM(LSCLIB/LSSUTIL) SRCFILE(LSCLIB/QSRVSRC) MBROPT(*ADD)

Then go and look at your binder source and you will a listing of all your exported procedures in a format that looks see something like this:

STRPGMEXP PGMLVL(*CURRENT) SIGNATURE(X'62C9C0FAA16B653C4359413F3E9CEB81')
/********************************************************************/
/*   *MODULE      LSSUTIL      LSCLIB      08/02/18  10:49:27      */
/********************************************************************/
   EXPORT SYMBOL("GETCORRECTION")
   EXPORT SYMBOL("GETERRTEXT")
ENDPGMEXP

Just to tidy things up a bit, move the comment lines to the top and get rid of the SIGNATURE keyword (it’s the PGMLVL that you really need) so that the source now looks like this:

/********************************************************************/
/*   *MODULE      LSSUTIL      LSCLIB      08/02/18  10:49:27      */
/********************************************************************/
STRPGMEXP PGMLVL(*CURRENT)
  EXPORT SYMBOL("GETCORRECTION")
  EXPORT SYMBOL("GETERRTEXT")
ENDPGMEXP

Now you want to tell it that this is the old version and the new current version of the service program contains your shiny new procedure. This is how:

/********************************************************************/
/*   *MODULE      LSSUTIL      LSCLIB      08/02/18  10:49:27      */
/********************************************************************/
STRPGMEXP PGMLVL(*CURRENT)
  EXPORT SYMBOL("GETCORRECTION")
  EXPORT SYMBOL("GETERRTEXT")
  EXPORT SYMBOL("GETSHINY")
ENDPGMEXP
/********************************************************************/
STRPGMEXP PGMLVL(*PRV)
  EXPORT SYMBOL("GETCORRECTION")
  EXPORT SYMBOL("GETERRTEXT")
ENDPGMEXP
/********************************************************************/

Then create your service program using:

CRTSRVPGM SRVPGM(LSCLIB/LSSUTIL) MODULE(LSCLIB/LSSUTIL) SRCFILE(LSCLIB/QSRVSRC) SRCMBR(LSSUTIL)

And display the service program signatures:

DSPSRVPGM SRVPGM(LSCLIB/LSSUTIL) DETAIL(*SIGNATURE)

And here’s what you should have:

                      Display Service Program Information
                                                                 Display 1 of 1
 Service program  . . . . . . . . . . . . :   LSSUTIL
   Library  . . . . . . . . . . . . . . . :     LSCLIB
 Owner  . . . . . . . . . . . . . . . . . :   QPGMR
 Service program attribute  . . . . . . . :   RPGLE
 Detail . . . . . . . . . . . . . . . . . :   *SIGNATURE

                                  Signatures:

 2C9C0F7DED8A1897F656D6C9CBB17DDD
 62C9C0FAA16B653C4359413F3E9CEB81

The service program now has two signatures. The new one is at the top of the list and the previous one is below it. What’s more, I can specify PGMLVL(*PRV) as many times as I need to.

When a program uses the service program, it will look down the list until it finds a signature that matches to identify the list of modules it can use. And this means that you can change your service program as much and as many times as you like without needing to worry about any of the programs that uses it.

A final note

You only need to change your binding source when you change the list of exported procedures (generally by adding a new procedure). Changing an existing procedure won’t impact your signatures.

A final final note

When you do add a new procedure, always add it to the bottom.

Here’s handy:

The ON-EXIT operation code begins the ON-EXIT section. The ON-EXIT section contains code that runs every time that the procedure ends, whether it ends normally or abnormally. The ON-EXIT section runs under the following conditions:

• The procedure reaches the end of the main part of the procedure.
• The procedure reaches a RETURN operation.
• The procedure ends with an unhandled exception.
• The procedure is canceled, due to the end of the job or subsystem, or due to an exception message being sent to a procedure higher in the call stack.

By placing your clean-up code, such as deleting temporary files and deallocating heap storage, in the ON-EXIT section, you ensure that it is always run, even if your procedure ends with an unhandled exception, or if it is canceled.

As someone who likes to exit procedures as quickly as possible, this opcode has a great deal of potential when it comes to simplifying the structure of my code, and for reducing the number of things I have to think about. This is always a good thing.

ON-EXIT was introduced in version 7.2 and is well worth investigating.

So here’s a really simple little program that puts the first five characters of a ten character field into a five character field. So why doesn’t it work?

      **Free

        // Fun with variable length fields

        ctl-opt dftactgrp(*no) actgrp(*new)
            main(Main);

        dcl-proc Main;
            dcl-pi *n end-pi;

            dcl-s LongString varchar(10) inz('123');
            dcl-s ShortString char(5) inz;
                                                             
            shortstring = %subst(longstring: 1: 5);                 
            dsply shortstring;                                      
                                                             
            return;                                                 
        end-proc;

If you compile and run this program, it will return an RNX0100 error: “Length or start position is out of range for the string operation”.

The reason, of course, is that LongString is a varying length field. The ten character length in the field definition defines the maximum size but, because the field is initialised with a three character value, the length of the field when the program starts is only three characters. And using the %subst bif to find the first five characters of a three character field will, of course, return an error.

The above program is so simple that the problem probably leapt out at you but when you are dealing with a bunch of externally defined fields, gotchas like this are less immediately apparent. So take this as a reminder to be wary of documentation and to familiarise yourself with the DSPFFD command.