6.0 Creating a Simple TL1 Agent

6.1 Creating a New Project and Loading the TCS in TL1 Compiler.

6.2 Configuring the Project.

6.3 Generating Code for the TCS Using TL1 Compiler

6.4 Compiling the Generated Code

6.5 Starting and Stopping the Agent

6.6 Saving the Project

6.0 Creating Simple TL1 Agent- An Overview

Following are the steps involved in building a TL1 Agent using the WebNMS Agent Toolkit.

1. Creating a TL1 Command Set (TCS) file and the corresponding Data Set (dat) file using TL1MessageBuilder

2. Generating Code for the TCS file using TL1 Compiler

3. Compiling the Code using TL1 Compiler

4. Testing the TL1 agent using TL1 Browser

6.1 Creating a New Project and Loading the TCS

Follow the steps given below to create a new project for a standalone TL1 Agent.

1. Start the TL1 Compiler by executing the TL1Compiler.bat/ TL1Compiler.sh file available inside the <Agent Toolkit Home>/bin directory.

2. Choose the File>>New Project option from the File Menu or using the shortcut key CTRL+SHIFT+N 

3. Enter the details of the Workspace, Project Name, and the directory of the project in the Project Settings Dialog Box.

4. Click OK after entering the details.

A new project is now created.

Follow the steps given below to load a TCS for the project created above.

1. Choose TCS>>Load TCS File from the Menu Bar.

2. Choose the tl1sample.tcs file from the<Agent Toolkit Home>/tcs directory.

3. Click the Load TCS button after selecting the TCS file. The TCS file will be loaded to the TL1 Compiler. You can view the TCS file tree in the TCS View of the Workspace panel.

6.2  Configuring the Project

You can configure the various project settings such as the General settings, Code Generation Settings and Security Settings, from the TL1 Compiler UI as explained in the following sections. These settings have to be configured according to your requirements before code generation.

6.2.1 Configuring General Settings

Follow the steps below to configure the General Settings of the project

1. Choose Project >> Settings from the Menu Bar or using the shortcut key CNTRL+SHIFT+S. A Dialog Box will appear with Settings tree on the left frame of the box.

2. Choose the node General from the Settings tree. Here, the various General settings can be configured.

Following options are available in the General settings.

1. Craft Interface: TL1 managed devices can be managed both locally by craft interface and remotely over any transportation protocol by an OSS. Craft enables the user to have contact with the agent through STD I/O methodology and it follows TL1 Transport provider framework. 

2. TCP/IP Interface: If this option is selected, then the TL1 agent has TCP/IP interface on startup. This option is selected by default

3. Self-Monitoring: Selecting this option enables the self monitoring feature in the TL1 Agent.

4. Built-In-Commands: Selecting this option adds the Built-in Commands support in the TL1Agent.

5. TCP Port Number: The TCP Port option is used to specify the port at which the TL1 agent is running. By default, the TL1 agent runs at default port number 9099. Users can specify the port number where they want the agent to be started.

6. Keep Alive Timeout: Specify the keep alive time for the TL1 Agent in seconds. The default value specified is 900 seconds.

7. Debug Level: When the agent is running, it will generate debug information to know about the agent processing. There are seven levels of debug statements provided in the debug options of the TL1 Compiler.  Each of these option is explained below:
   
   Disabled (0) : The log messages do not get stored in the text file when this option is chosen.
   
   Fatal (1) : Fatal level indicates that the application has encountered a severe error that may make the system unstable. These errors need to be attended to immediately. When this level is chosen, only critical messages such as details on Agent crash, Authentication errors, Agent already open in another session,  etc., get stored in the log file.
   
   Error (2) : Error level indicates that an error has occurred and the application cannot handle the request as designed. This may be automatically corrected during execution or the application should be capable of handling those situations when a similar request comes again. Selecting this level will store all the Error and Exception messages in the log file along with the fatal messages.
   
   Warn (3) : Warning messages indicate that the application has met with an expected error. All Warning messages get stored in the log file when debug level is Warn. Log messages corresponding to log levels 1 and 2 are also stored in the log file.
   
   Info (4) : The Info level does not signify the occurrence of any error but logs all important events. Any information that might be required for reference gets stored in the log file under this info level.
   
   Debug (5) : On choosing this log level, the application moves into the debug mode. It is used for generating debugging information and should not be used in general cases.
   
   Trace (6) : In this mode, the application logs every activity from entering a method to exiting and thus selecting this level may affect performance. The Trace level should be used only to solve any complex problem.
   Default Debug level is 5(Debug).

8. Asynchronous Message Processing: The TL1 Agent usually handles one request at a time. Selecting this option of Asynchronous Message Processing mode allows the agent to handle more than one request simultaneously using multiple threads.
   
   Number of Threads: This option is enabled only when the Asynchronous mode is selected. It specifies the number of messages an agent can handle simultaneously in this mode. By default, the number of threads is configured as 5. You  can specify any other value. The maximum  number of requests the agent can handle is 20.

6.2.2 Configuring Code Generation Settings

Before configuring Code Generation Settings, add the TCS or the Node for which code is to be generated by Right-Clicking on any node of the TCS in the TL1 Tree of the TCS view panel. You will find the following options.

i. Add Whole Node: Selecting this option adds the whole TCS for code generation code will be generated for all the nodes in the TCS.

ii.Add Selected Node: By default, code will be generated for the whole TCS file. Selecting this option, generates code only for the selected nodes displayed in the "Selected nodes" panel of  the TCS View tab.  For example,  if AGENT-SAMPLE-MIB.tcs  is loaded and the GET command is added to the selected nodes list, this option generates code only for the GET command of the AGENT-SAMPLE-MIB.tcs file.

Note: To remove a node from the selected nodes panel, select the node to be removed and right-click it. Then choose the Remove Node  from the pop-up menu. It is also possible to generate source for more than one TCS file using the selected node option.

After selecting and adding the Nodes for which code is to be generated, follow the steps below to configure the Code Generation Settings of the project.

1. Choose Project >> Settings from the Menu Bar or using the shortcut key CNTRL+SHIFT+S. A Dialog Box appears with Settings tree on the left frame of the box.

2. Choose the node Code Generation from the Settings tree. Here, the various Code Generation settings can be configured.

Following options are available in the Code Generation Settings.

1. Generate Source
   Merge with previous stub files: On regenerating the code, new stub files are created. Thus the instrumentation added to the stub files gets overwritten. In order to avoid this, select the Merge with previous stub files option. Now, the new stub files are generated with the instrumentation from the previous stub files.

2. Agent Name
   The Agent Name provided in the Code Generation panel of Project >> Settings option refers to the Main File Name. The default name is WebNMSTL1Agent.java. You can specify any other name other than the default name provided.

3. Package Name: The Package Name option provided in the Code Generation panel of Project >> Settings menu is taken as the package name for the generated Java files. The default package name provided is com.myCompany.myPackage. You can specify any other name other than the default name provided.

6.2.3 Configuring Security Settings

The various security views and their details can be configured in the Security Settings. Follow the steps below to configure the TL1 Security-related Settings of the project.

1. Choose Project >> Settings from the Menu Bar or type CNTRL+SHIFT+S. A Dialog Box will appear with Settings tree on the left frame of the box.

2. Choose the node Security  from the Settings tree. Here, the various Security-related settings can be configured.

Following options are available in the Security settings.

1. Enable Security: If you do not require security for your project, do not enable this option. If this option is enabled, User Security gets enabled by default. It is mandatory, if security is enabled. The other securities namely Command, Channel, Operation, and resource can be enabled here if required. By default Security is enabled.

2. Log File Size: This is the size of the log file in Number of Records which logs the security-related information. Default Log File size is 60.

3. Security View: For the securities enabled in the Security Block, the corresponding security view can be selected here, and the values for its parameters can be added and modified from the table below the Security View. By default User Security View is enabled.

6.3  Generating Code for the TCS Using TL1 Compiler

Please follow the steps given below to generate the code for any  loaded TCS. Before following the steps given below, load the tl1sample.tcs  with the default project settings.

1. After loading the TCS file and configuring the Project, generate the code by choosing the Build >> Generate Source option in the Menu Bar. You can also use the Generate Source icon from the Toolbar.
   
   This generates the stub files in the destination project directory <Agent Toolkit Home>/tl1projects/<Your Project>/agent /src/com/myCompany/myPackage. The status of code generation can be seen in the bottom most part of the tool. The message "Code generation succeeded" means that the code has been generated successfully without any errors. If the message "Code generation failed" is received, it means that some errors have occurred during code generation.  The generated files can be viewed in the FileView tab. The stub files that are generated during the code generation will be listed in the Debug Window.

6.4  Compiling the Generated Code

After generating the code for the loaded TCS file(s), the next stage in agent development is compiling the source code. You can instrument the source code according to your requirements before compilation. This example shows how to compile the source code without any instrumentation. You can compile your project either from the UI or from the Command prompt as explained in the following sections.

6.4.1 Compiling the Code from the TL1 Compiler UI

Follow the steps given below to compile the generated code using the TL1 Compiler UI.

1. After generating the source code, compile the code by choosing the Build >> Compile Source from the File Menu or click Compile source icon in the toolbar. You can also use the CTRL + M shortcut key to compile the project.

This compiles the source files and puts them in the  <Agent Toolkit Home>/tl1projects/<Your Project>/agent

/bin/com/myCompany/myPackage directory. On successful compilation, the status "Compilation Succeeded" can be seen in the bottom most part of the tool.

6.4.2 Compiling the Code from the Command Line.

You can also compile the source from the command prompt. Please follow the steps given below to compile the source files from the command prompt.

1. Open a command prompt/terminal. 

2. Go to the <Agent Toolkit Home>/tl1projetcs/<YourProject>/ agent/bin

3. Set the class path. For this run.sh/run.bat can be used. If linux execute ". run.sh" if Windows "run.bat" 

4. Then, execute the following command 
   javac -d . ../src/*.java --> Linux 
   javac -d . ..\src\*.java --> Windows 
   
   The above command will compile all the files under src directory and if the compilation is successful, the compiled class files can be found under tl1projects/<Yourproject>/agent/bin/com/myCompany/myPackage directory.  Now all the files have been compiled and the Agent can be started.

Please note that you can also compile individual files, if any modification is done on a particular file.

6.5 Starting and Stopping the Agent

After successfully compiling the Agent, you can start the Agent either from the TL1 Compiler UI or from the Command prompt as explained in the following sections.

6.5.1 Starting and Stopping from the TL1 Compiler UI

You can start and stop the Agent from the TL1 Compiler UI by clicking the Buid >> Start Agent andBuild>> Stop Agent option in the menu bar

6.5.2 Starting and Stopping from the Commmand Line

Follow the steps given below to start and stop the Agent from the command prompt.

1. Open a command prompt/ terminal.

2. Go to the <Agent Toolkit Home>/tl1projetcs/<YourProject>/agent/bin/ com/myCompany/myPackage directory where the compiled files are available.

3. Execute the Run.bat/Run.sh command. In the console it can be seen that TL1 Server is started on 9099. You will find the following details at the end of the execution of the above command TL1 Server started on 9099 This means that the Agent has been successfully started on port 9099.

Note: For Testing the TL1 Agent created in this chapter, please refer to the next chapter on "Testing the TL1 Agent".

6.6 Saving the Project

To save the Project, select Save Project option from the File menu or use the shortcut key  CTRL+SHIFT+V.