Extending the IBM Director command line interface

The IBM Director command line interface (CLI) consists of specialized server bundles. Each bundle contains a set of executable commands. Executing the CLI client from the command prompt accesses the bundles. These bundles exist and execute from the IBM Director Server. The commands are invoked by providing the desired bundle and command combination along with the necessary command arguments.

Bundles are the means for extending and enhancing the IBM Director MP command line interface. Bundles can be created and designed to provide any set of accessible functionality with the IBM Director Server. Bundles can provide access to core IBM Director areas as well as be installed with any IBM Director extension. Bundles are also free to implement as many or as little commands as needed to suit the purpose of the bundle. The CLI bundle collection is the definition of the CLI components functional capabilities.

The basic steps

  1. Create the necessary java files
  2. Compile the files and copy the files to IBM Director Server directories
  3. Register the extension with IBM Director using a (.TWGExt) file.
  4. Restart the IBM Director Server

What you’ll need

  1. An extension file

    The Extension file (.TWGExt) is a required file; it tells the IBM Director Server what extensions are available. The general format of an extension file for defining CLI bundles is as follows:

    For example:

    #Extension name
    twg.extension.classname	= extension_class_name
    # CLI	Bundle/command registrations
    twg.extension.cli.1 = bundle_name_1 qualified_java_class_1
    twg.extension.cli.2 = bundle_name_2  qualified_java_class_2
    twg.extension.cli.N = bundle_name_N  qualified_java_class_N
    

  2. An extension definition and bundle implementation file.

    The extension file is subclass of an IBM Director’s TWGExtension class. For more information on the TWGExtension class refer to the documentation available at:

    your_sdk_dir\dirsdk\files\docs\javadoc\java\com\tivoli\twg\engine\TWGExtension.html.

    CLI bundles are implemented through Java classes and the commands are implemented through public class methods. To start with, every IBM Director CLI bundle must implement the Java interface com.tivoli.twg.cli.TWGCLIBundle. This tag interface defines a set of common command return codes and identifies the Java class as a IBM Director CLI bundle.

    The command interfaces define the functionality of a bundle. CLI bundle commands are created by implementing Java class methods with the below method signature.

    public int commandName(	java.util.Locale clientLocale,
    				java.lang.String[] args,  
    				java.lang.String[] fileBuffers,
    				java.io.Writer client_stdout,
    				java.io.Writer client_stderr
      				java.io.Reader client_stdin)

    The CLI Service inspects each bundle during the extension registration process with Java reflection to identify the methods which will be exported as CLI commands. A bundle can contain one or more command definitions. All methods with the above signature are exported as commands. The name of the CLI command will be the same as the method name which cannot be redefined or aliased. Command names will be case sensitive.

    When the command is executed, the corresponding bundle method is invoked with the method parameters configured by the CLI Service for the execution.

Return/exit codes

Upon completion, commands must set the exit code. All commands should return:

Command return codes should have the following characteristics:

For further information about exit codes, refer to the Open Group documentation:

http://www.opengroup.org/onlinepubs/007908799/xcu/chap2.html

Reserved codes

The exit code range from 2 to 10 and then 125 are reserved and can only be used by the CLI framework and infrastructure. These codes are used to deliver CLI framework errors. The CLI framework CLI return codes are listed below:

02 Command and/or bundle not found error

03 Unauthorized CLI access error

04 Reserved

05 Reserved

06 Reserved

07 Reserved

08 Command error. Invalid return code used.

09 Invalid or unsupported locale specified/detected

10 File not found error

125 Command terminated while executing (Uncaught Java exception from command)

The exit codes 1 and 11 to 49 are for the definition of common values that could have applicability across many commands. Commands should only return these codes in the context of the common error definition. Exit codes specific to a particular command should not be defined in this range. Common values are defined in the following file and should be referenced directly from there: com.tivoli.twg.cli.TWGCLIBundle

Below is a partial list of common codes. This is a list that grows as needed. For the most up-to-date value list, see the: com.tivoli.twg.cli.TWGCLIBundle file.

/** Syntax and/or usage error */
public static final int RC_USAGE = 1;
/** Managed Object Not Found */
public static final int RC_MO_NOTFOUND = 20;
/** Group Not Found */
public static final int RC_GP_NOTFOUND = 21;
/** Task Not Found */
public static final int RC_TASK_NOTFOUND = 22;
/** Object ID or Number formatting error */
public static final int RC_NUMBER_FORMAT = 25;
/** Invalid objectType Specified */
public static final int RC_ID_INVALID  = 26;
/** Invalid Attribute Specified */
public static final int RC_ATR_INVALID = 27;

Command-specific codes

The exit codes 50 to 100 should be used for command-specific codes and codes not defined in the common range.

Internal error codes

You should use exit codes 101 to 124 for internal execution errors that you do not expect to happen and you do not ever expect the user to see, but will be a debug aid in the event that error that was never supposed to happen actually does occur.

The following suggested codes are defined in the com.tivoli.twg.cli.TWGCLIBundle file:

/** Internal error 120:  Development error which shouldn't happen */
public static final int RC_INTERNAL_120 = 120;
/** Internal error 121: CLIOptionNotSpecifiedInArgvException */
public static final int RC_INTERNAL_121 = 121;
/** Internal error 122: CLIOptionNotInUsageException */
public static final int RC_INTERNAL_122 = 122;
/** Internal error 123:  Development error which shouldn't happen */
public static final int RC_INTERNAL_123 = 123;
/** Internal error 124:  InvalidObjectID  */
public static final int RC_INTERNAL_124 = 124;

Guidelines to follow when writing CLI bundle extensions

Simplicity is essential to the creation of new commands. The goal is to make commands that are easy to use and remember. Therefore the optimal set of commands is a small number of commands each taking a small number of flags. When designing new commands please keep the following in mind:

  1. Keep the number of new commands to a minimum -- too many commands can be confusing to users and hard to remember.
  2. In order to reduce the number of commands, combine like functions into one command and use flags to specify the different options.

    For example: chgp can change task groups, static groups and group categories. (In this case, instead of using different flags to determine the behavior, chgp determines what do to based on the group type.)

  3. Conversely, you should limit the amount of function you should put into one command; you do not want to create a command with so many flags that the command is hard to use, or the syntax is complicated. Therefore, diverse function or operations should be broken out into multiple commands.

    Example: lsmo, chmo, rmmo, and mkmo are all separate commands and, while they all work with managed objects, they do different things to managed objects. Therefore it makes sense to have them as separate commands.

Command name policy

Command names should following these guidelines:

Common prefixes

The common prefixes (to indicate action) to use with commands are:

This is not an exhaustive list. Applications will likely need additional action prefixes. But if the application supports any of the actions listed above, it should use the associated common prefix. More common action prefixes might be added in the future.