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 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
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.
Upon completion, commands must set the exit code. All commands should return:
Command return codes should have the following characteristics:
For example, if a command targeted at ten objects fails for one object and succeeds for the other nine, then the return code should:
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;
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:
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.)
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 names should following these guidelines:
Note: According to the POSIX guidelines, command names should contain no more than nine characters.
To be able to create a more understandable command names, the upper limit is fifteen alphanumeric characters.
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.