Coming to terms with call back

Paul Tuohy

I want to give you a practical example of using a call back along with a couple of procedures that might be of use when displaying lists of information on a Web page using CGIDEV2.

But let's get started with the concept of call back. Call back is where a program issues a call to a procedure that, in turn, issues a call back to a procedure in the calling program. Clear as mud, right? Figure 1 should make it a little easier to understand. Your program issues a call to a standard procedure in a service program. But there is a little bit of logic that must be performed by this standard procedure that may be different on every call, depending on the caller. Instead of coding a lot of complex if/else logic, the standard procedure will call a procedure back in the calling program. Of course, the "call back" procedure does not have to be back in the calling program just as long as it is accessible as a bound call (i.e. it can be in another module or service program).

Figure 1: Call back

Usually, the call back technique is used at a fairly low level of programming, such as using the C functions qsort and bsearch, both of which are extremely well documented in the Redbook "Who Knew You Could Do That with RPG IV?". But you do not need to go to a very low level to make use of the technique. Let's look at an example.

An Example

Figure 2 shows a web page that displays a list of products. Above the list are a couple of options where the user can select whether the list should be displayed by row or by column and how many columns should be displayed. They simply select the two radio buttons and click the change button. All of the logic for handling and processing the selection is written in a couple of subprocedures: all you have to do is write a procedure that places the information for a product and follow a couple of rules with your HTML.

Figure 2: List manipulation on a Web page

Figure 3 shows the code for the called program. The main points to note are:

  • The program uses the CGIDEV2 procedure "gethtmlIFSMult" to load multiple documents for the construction of the Web page. This is very much the same as constructing a 5250 screen from many record formats but here you have the benefit of being able to use the same format for multiple Web pages.

  • One of the standard formats that are loaded is StandardFormatSelect.html. This contains the form used for the selection by row or column and the number of columns. This is standard for all Web pages and you do not need to amend it in any way for an individual program.

  • The program loads all information to be displayed into a data structure array – LoadArray. The field NumRows indicates the number of rows that are loaded in the array.

  • Calls are made to the two standard procedures FormatSelect and FormatList. FormatSelect constructs and displays the selection options and FormatList constructs and displays the list -- more about these in a moment.

  • Coded at the very end of the program is a subprocedure named SetColumnData. This is the "call back" procedure. The procedure is passed an integer which indicates which row should be placed in the document. The procedure used the updHTMLvar procedure to update values for the required product code and description.

    The HTML

    There are a few rules that you must follow when defining the HTML (shown in Figure 4) for the list to be displayed. Remember, this list is going to be written by a standard routine.

    The HTML must contain seven sections that are written by the FormatList procedure:

  • StartFormatTable contains the table definition tag. The width of the table is set by the variable TableWidth (this value is calculated by FormatList).

  • StartHeaderRow contains the tag to start the definition of a table row.

  • HeaderColumn contains the tags and text for the header information for one entry in the list: a product code and description in this case. This section is repeated for the number of selected columns.

  • EndHeaderRow contains the tags for the end of the header row.

  • StartDataRow contains the tags for the start of a data row (i.e. this is the start of one row on the page).

  • DataColumn contains the tags and variables for one entry in the list. These are the variables that will be updated by the called back procedure (SetColumnData in Figure 3). This section is repeated for the number of selected columns.

  • EndDataRow contains the tags to mark the end of a data row on the page.

    HeaderColumn and DataColumn are the two sections that require all the work. The rest of the sections will, for the most part, remain the same unless you need to customize any of the table or row attributes.

    The procedures

    Figure 5 shows the prototypes for the two standard procedures and the call back procedure.

    D FormatSelect    PR                  ExtProc('FORMATSELECT')
    D  ProgramName                  10A   Const
    D  AllColumns                   10I 0 Const Options(*NoPass)
    D FormatList      PR                  ExtProc('FORMATLIST')
    D  NumberOfRows                 10I 0 Const
    D  CallProc                       *   ProcPtr Const
    D  ColumnWidth                  10I 0 Const Options(*NoPass)
    D SetColumnData   PR
    D  ForColumn                    10I 0 Const 

    Figure 5: Prototypes for the procedures

    These are the main points to consider:

  • FormatSelect is the procedure that processes the standard selection format. The first parameter indicates the name of the program that is called when the Change button is selected i.e. the name of the program you are writing. Back in Figure 3 the program name is picked up from the program status data structure. The optional second parameter allows you to specify the maximum number of columns that may be selected -- it defaults to six.

  • FormatList is the procedure that constructs and writes the list. The first parameter indicates the number of entries in the list. The second parameter is a procedure pointer to the call back procedure. Back in Figure 3 the %PAddr built in function is used to pass the address of the SetColumnData subprocedure. The optional third parameter allows you to define the width of a list entry in pixels -- it defaults to 250.

  • SetColumnData is the call back procedure. The name of the procedure is irrelevant since the procedure is called based on a procedure pointer -- but the prototype must define a ten digit integer as the sole parameter. This integer indicates the item in the list that should be added to the document.

    And the rest

    And then there is the code for the standard procedures and HTML documents. But one of the great things about ILE is that you do not care about the code as long as it works – just as you know that all those CGIDEV2 procedures work. So all you have to do is download the code and install it .

    And finally

    Now you have an idea of how call backs can be used and you have added another tool to your programming tool belt.

    And you have the basis of a little utility that allows your users to customize lists the way they want.

    About the author: Paul Tuohy is CEO of ComCon, an iSeries consulting company. He is the author of Re-Engineering RPG Legacy Applications and is one of the quoted industry experts in the IBM Redbook "Who Knew You Could Do That With RPG IV?"

    This was first published in February 2006

  • There are Comments. Add yours.

    TIP: Want to include a code block in your comment? Use <pre> or <code> tags around the desired text. Ex: <code>insert code</code>

    REGISTER or login:

    Forgot Password?
    By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy
    Sort by: OldestNewest

    Forgot Password?

    No problem! Submit your e-mail address below. We'll send you an email containing your password.

    Your password has been sent to:

    Disclaimer: Our Tips Exchange is a forum for you to share technical advice and expertise with your peers and to learn from other enterprise IT professionals. TechTarget provides the infrastructure to facilitate this sharing of information. However, we cannot guarantee the accuracy or validity of the material submitted. You agree that your use of the Ask The Expert services and your reliance on any questions, answers, information or other materials received through this Web site is at your own risk.