Configuring IBM i to start the RTC Build agent automatically

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
      IBM I Web Console: Create user-defined server
    4. In the New Server wizard, select Next. Enter a server name for the agent. Click Next.
      New Server wizard: server name
    5. Enter a server description. Click Next.
      New Server wizard: server description
    6. Enter a server job type. Click Next.
      New Server wizard: server job type
    7. Enter a Server ID. Click Next.
      New Server wizard: server ID
    8. Enter the Server program and it’s library, i.e. the program you compiled in step 2. Click Next.
      New Server wizard: server program
    9. If you want the server to be started when TCP/IP starts up, select Yes for Autostart. Click Next.
      New Server wizard: Autostart
    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
      IBM I Console: Get User-Defined Servers
    2. By your server name, click the arrow and select Start.
      IBM i Console: Start server
    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.
    RTC Client: Test connection to build agent

For more information:

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.


Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.
Feedback
Was this information helpful? Yes No 1 person rated this as helpful.