IBM provides some APIs that let specific system functions be performed from within a program, as opposed to, for example, from the iSeries Navigator GUI. And sometimes IBM provides new APIs through a PTF, so that the API becomes immediately available for current or previous releases.

Today's API by Example covers an API that falls into both categories: Change IPv4 Interface (QTOCC4IF). This API, part of the V5R4 base install and available to V5R2 and V5R3 through a couple of PTFs, lets you change selected parameters for an IPv4 network interface.

The V5R2/V5R3 versions of this API support only a subset of what's available in the V5R4 API. This fact is revealed by comparing the documentation in the V5R4 Information Center with the documentation in APAR 19172.

In the V5R4 API documentation, notice that the IFCH0100 API parameter includes a couple of parameters that the APAR documentation lacks. There's an Interface Name as well as a Preferred Interface List parameter, neither of which is described in the APAR version of the API documentation. However, I tested the full parameter list on a V5R3 system, and apparently it does work (at least in V5R3), even though it's not listed in the APAR documentation. When I tried it, the test completed normally and returned a TCP2659 message to the job log: "TCP/IP interface changed successfully."

I have, however, included both versions with the example code that I provide with this article. For the V5R2/V5R3 version, which (according to the documentation) supports only the "Enable Proxy ARP" setting, I wrote the Enable Proxy ARP (ENBPXYARP) command. For the V5R4 version, I wrote the Change IPv4 Interface (CHGIP4IFC) command. Here's how the two command prompts look:

                    Enable Proxy ARP (ENBPXYARP)               
 Type choices, press Enter.                                      
 Interface internet address . .                                  
 Enable . . . . . . . . . . . .   *SAME         *SAME, *YES, *NO 

                  Change IPv4 Interface (CHGIP4IFC)         
 Type choices, press Enter.                                      
 Interface internet address . .                                 
 Enable proxy ARP . . . . . . .   *SAME         *SAME, *YES, *NO
 Preferred interface  . . . . .   *SAME                         
             + for more values                                 
 Text 'description' . . . . . .   *SAME                         

As usual, I provide help text panel groups for both commands, and if you do a little investigation, you'll notice that much of the help text is simply copied and adapted from the API documentation of the various parameters. This is a quick and accurate way to include online documentation with this type of API command interface programming.

The QTOCC4IF API has only three parameters, and the primary IFCH0100 input parameter data structure is pretty straightforward to code. Combined with a CL command definition, it offers a quick and simple way to create a consistent, direct, and speedy interface to access the services available with this API. I'm sure that you can find many other APIs that would benefit from a command interface.

If you would like to know when IBM introduces new APIs through PTFs, use this view that lets you display the online PTF lists by date, so that you can easily check only the most recent PTFs:
http://www-912.ibm.com/a_dir/as4ptf.NSF/PTFBYDATE?OpenView

As an example of an interesting new API currently under development and soon to be distributed by a couple of PTFs, check out the Retrieve Program Interface Information (QBNRPII) API.

The PTF numbers have not been included in the APAR yet, but IBM told me that the following PTF numbers have been assigned:

• R530 SI23536
• R540 SI23544

Interestingly, the API documentation has already been added to the Info Center API manuals. Here's the V5R3 version:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qbnrpii.htm

Happy API hunting!

This APIs by Example includes the following sources:

CBX1641  -- Change IPv4 Interface - CPP  
CBX1641H -- Change IPv4 Interface        
CBX1641V -- Change IPv4 Interface - VCP  
CBX1641X -- Change IPv4 Interface        

CBX1642  -- Enable Proxy ARP - CPP       
CBX1642H -- Enable Proxy ARP             
CBX1642V -- Enable Proxy ARP - VCP       
CBX1642X -- Enable Proxy ARP

Compilation instructions are in the source headers, as usual.

For releases V5R2 and V5R3, IBM made the QTOCC4IF API available by the following PTFs:

  Rel.  PTF       CUM                                        
  R520  SI17485   5263                                       
  R530  SI17284   5207

You can retrieve the source code for this API example from http://www.pentontech.com/IBMContent/Documents/article/53438_134_ChgIp4Ifc.zip.