Creating and registering a Windows agent service

This topic describes the basic steps used to create, register, and distribute a IBM Director agent extension. To better understand the steps and requirements of IBM Director server-to-agent communication, read the topics listed below in "Related topics."

Subtopics

Related topics

Related sample code

Creating an agent service

You can create an agent program (agent) that runs on a IBM Director managed system and provides services for IBM Director server tasks (server tasks). To provide services, an agent must accept, process, and respond to requests initiated by a server task. An agent program is structured as follows:

Steps Description
Initialization Create a service node, etc.
Command processing loop Receives and processes requests, provides response
Cleanup and completion Possibly terminates

Refer to Communication sample or File Explorer sample for sample code that demonstrates how a IBM Director agent communicates with a Director server task.

Note:  If an agent service is started multiple times by the same server or by different servers, only one instance of the program is actually started. All other starts are use counted on the managed system where the agent resides. Your agent service program must be able to handle this condition.

Registering a Windows agent service

Before a IBM Director Server task can use a IBM Director agent, the new IBM Director agent service extensions must be registered in the svcmgr.ini file. Make sure you save existing IBM Director agent registrations by backing up the svcmgr.ini file in the Program Files\IBM\Director\bin directory. Registering an agent service is a two step process:

Step 1: Create a new file named svcmgr.ini
  1. Run TWGSVCEE.EXE in a directory other than the one which contains svcmgr.ini. TWGSVCEE.EXE is installed with the IBM Director SDK in the itdsdk21\bin directory. When you run TWGSVCEE.EXE, you will see a window similar to the following:

    TWGSVCEE Screen

  2. Enter the appropriate information in the fields, save (Add) the information, and exit. (The window shown in this document contains information for the File Explorer sample.)
    Service Connection Name
    Specifies the name of the service node this agent will use to receive requests.
    Application Base Name
    Specifies the name of the agent program (for example, myagent.exe).
    Application base parameters
    Specifies the command line parameters for the agent program, if any.

    Note:  The agent service cannot be sensitive to command line parameter order.

    Auto-start and stay loaded
    Specifies to launch the agent program when the Director IPC is started. The command line parameter /INIT is appended to the command line parameters specified above.
    Start on demand
    Specifies to launch the agent program on demand.
    Start initially and on demand
    Specifies to launch the agent program when the Director IPC is started, and also on demand.
    Prevent Suspend Mode
    When checked, the IPC will endeavor to inhibit suspension of the agent program after it is started.
    Run base in its own session
    This option has different meanings for different operating system platforms:
    Windows
    Starts the agent program in minimized mode
    OS/2
    Starts the agent program using DosStart
    Novell
    N/A
    Run base detached
    This option has different meanings for different operating system platforms:
    Windows
    Starts the agent program in hidden mode
    OS/2
    Starts the agent program using DosEXE
    Novell
    N/A
  3. When running TWGSVCEE.EXE, a new svcmgr.ini file is created in the same directory as TWGSVCEE.EXE. Rename this new svcmgr.ini to newsvmgr.ini and copy it to the directory containing the original svcmgr.ini (typically x:\Program Files\IBM\Director\bin, where x: is the drive on which Director server is installed).

Step 2: From the \Program Files\IBM\Director\bin directory, run twgmrgsi.exe to merge the new file with the copy of the original file.
The syntax is:

TWGMRGSI   merge   new_file.ini where new_file is the name of the file you created from svcmgr.ini. In this procedure the filename used is newsvmgr.ini.

The new entry is merged into the svcmgr.ini file. The new service entry will not be recognized until the IBM Director agent is restarted.

Deploying an agent

A new agent service can be packaged and distributed using the Custom Package Editor feature of the IBM Director software distribution task. The following steps demonstrate how to build an agent distribution package:

  1. Create a simple batch or command file which contains the TWGMRGSI merge command, for example, twgmrgsi merge newsvmgr.ini.
  2. Create a custom software distribution package:
  3. Distribute the software package to a managed system. When the targeted system is restarted, the new service should be available.