Configuring IBM i to start the RTC Build agent automatically

Sean Babineau, IBM
Spencer Murata, IBM
Last updated: May 16, 2013
Build basis: Rational Team Concert 4.0.1

The purpose of this article is to walkthrough the configuration of a IBM System i server to automatically start the Build Forge agent (BFA) from an Initial Program Load (IPL).

There are multiple ways to configure processes to start automatically when an IBM i server is IPL’d.
Since the Build Agent requires TCP/IP, it makes sense for the BFA to be configured to start as a TCP/IP server. It can then be started automatically when TCP/IP starts up. That is the method described here.

Setting up IBM i TCP/IP server

1. Create a CL program to start the build agent, using CLLE source like the following example:
   /* RTCAGT sample CL program called by STRTCPSVR/ENDTCPSVR */
   
   /* DISCLAIMER: This source is an example for instructional purposes only. */
   /* It comes with no guarantee or warranty. */
   PGM PARM(&PARMSTR)
   /* &PARMSTR is a structure passed to this program from STRTCPSVR/ENDTCPSVR */
   /* as described in: */
   /* http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/index.jsp?topic=/cl/addtcpsvr.htm */
   DCL VAR(&PARMSTR) TYPE(*CHAR) LEN(368)
   DCL VAR(&ACTION) TYPE(*CHAR) LEN(10)
   
   CHGVAR VAR(&ACTION) VALUE(%SST(&PARMSTR 1 10))
   
   IF COND(&ACTION *EQ '*START ') THEN(DO)
   /* START THE RTC BUILDAGENT THROUGH QSH */
   QSH +
   CMD('/QIBM/ProdData/RTC401/Build/jazz/buildsystem/buildagent/startbfa.sh')
   ENDDO
   ELSE DO
   /* @TODO: Add code to end the server */
   /* This code would need to find the agent job and end it. */
   /* E.g. programmatically find job using Agent's port number */
   /* and end that job */
   ENDDO
   
   ENDPGM
   
2. Compile the CL source into a program, e.g.
   CRTBNDCL PGM(MYLIB/RTCAGT) SRCFILE(QCLSRC)
3. Create a User-defined TCP/IP server to call the RTCAGT program:
   
   1. Connect to the IBM i console. Direct your web browser to:
      http://{IBM-i-hostname}:2001
   2. In the navigator pane, select Network.
   3. Select Servers -> Create User-Defined Server
      
   4. In the New Server wizard, select Next. Enter a server name for the agent. Click Next.
      
   5. Enter a server description. Click Next.
      
   6. Enter a server job type. Click Next.
      
   7. Enter a Server ID. Click Next.
      
   8. Enter the Server program and it’s library, i.e. the program you compiled in step 2. Click Next.
      
   9. If you want the server to be started when TCP/IP starts up, select Yes for Autostart. Click Next.
      
   10. Review the values, and click Finish
4. Start your new user-defined TCP/IP Server (manually, if not auto-started):
   1. From the web console on your IBM i server (step 3a), select Servers -> User-Defined
      
   2. By your server name, click the arrow and select Start.
      
   Alternatively, you can start the server manually from IBM I command line using the IBM i command line:
   STRTCPSVR SERVER(*RTCAGT401)
5. Ending the server (manually):
   The sample code above does not contain code for ending the server, so the ENDTCPSVR command does nothing currently. To make ENDTCPSVR work code needs to be added to end the agent job.
   

   The build agent server can end manually by doing the following:

   1. Find the agent’s port number in the bfagent.conf, e.g. /QIBM/ProdData/RTC401/Build/jazz/buildsystem/buildagent/bfagent.conf
   2. From the IBM i command line, enter NETSTAT, then select menu option 3
   3. Scroll down through the connections and search the Local Port column matching your agent’s port number.
   4. Select option 8 (Display jobs) for this connection.
   5. Select option 5 (Work with job) for the connection’s job
   6. Enter option 41 to end the job.

Troubleshooting

• If when starting, you get an error message TCP1A0A “STRTCPSVR ended abnormally. Reason code is 0005”, it likely means that your server program/library is incorrect or that you don’t have proper authority to it.
• The web console may say the server is “Stopped”, but the agent may actually be running. You can verify this by using the RTC build engine definition Connection Test for the BFA.
  

---

For more information:

• Rational Team Concert product page
• IBM System i Support page

About the authors

Sean Babineau joined the IBM Toronto Lab in 1992, starting in the AS/400 application development tools area. He has held both management and development roles for a broad range of development tools, including compilers, debuggers, integrated development environments, application intelligence, and team tools. He is currently a Rational Team Concert architect, responsible for IBM i and enterprise deployment.

Spencer Murata currently works in the RTC Level 3 Team in Littleton MA. He can be contacted at murata@us.ibm.com.

---

Copyright © 2013 IBM Corporation