C.2 Designing the Cluster CLI

The following sections describe the design of the Perl-based CLI:

For additional information about programming Perl, see the following references:

C.2.1 Establishing CLI Architecture

  • Extensible Snap Ins: The CLI uses Perl modules to implement individual CLI commands. Each CLI command is represented by a single Perl module. These Perl modules also are referred to as snap ins in this document. This snap in architecture allows the CLI to be flexible and very extensible. If a new CLI command is needed, a snap in can be written quickly and placed in the appropriate directory for use when the CLI is next executed.

  • Snap In Directory: The CLI snap ins must reside in a specific snap ins directory relative to the main Cluster CLI Perl script (ClusterCLI.pl). Snap ins must be a child directory of the directory where ClusterCLI.pl resides.

    For example, on a Windows workstation, assume the ClusterCLI.pl Perl script file resides in c:\perl\Novell\cli, then the snap ins must exist in c:\perl\Novell\cli\Snapins. On NetWare, the default directory structure for the main Perl script and snap in modules is sys:\Perl\scripts and sys:\Perl\scripts\Snapins, respectively. The following illustration shows the directory layout on a Windows workstation..

    Windows Perl Script Directory

  • Snap in Naming Convention: To be recognized as a valid Perl-based CLI snap in, use the following naming convention 

     ClusterCliSnapin_xyz.pm

    where xyz is the name of the command the snap in implements. For example, the snap in ClusterCliSnapin_View.pm implements the Cluster View CLI command.

  • Snap In Package Name: A snap in must exist in a package with the same base name as its file name, including case. For example, the snap in ClusterCliSnapin_View.pm must exist in the package ClusterCliSnapin_View, otherwise executing the CLI script will result in an error.

    IMPORTANT:The package name is case sensitive.

C.2.2 Implementing Required Programming Interfaces

The Perl-based CLI uses an object oriented design approach. Consequently, each snap in must inherit from the ClusterCliSnapinInterface base class, otherwise executing the CLI script will result in an error. In addition, you must implement the following methods when writing CLI snap ins:

IMPORTANT:To ensure your snap ins perform properly, use each of these methods.

Param Method

The Param() method simply returns a string with the name of the CLI command that the snap in implements. The Perl-based CLI uses this method to determine which snap in to call to execute a particular CLI command and to display a list of valid CLI commands to the end user.

For example, the following is the Param() method for the ClusterCliSnapin_View snap in:

 sub Param(){
    return("view");
 }

Execute Method

The Execute() method performs the work of the CLI snap in and is called when the end user invokes a CLI command. All of the parameters that were passed in on the command line are passed to this command.

For example, the Execute() method for the ClusterCliSnapin_View snap in will query NCS through the _ADMIN volume interface and display the status of the given cluster.

Help Method

The Help() method displays help to the end user and is invoked when the end user types the command "Perl ClusterCLI.pl help <command>," where <command> is the CLI command they want help with.

HINT:The user can type the command "Perl ClusterCLI.pl help" to get a listing of all the valid commands that have been implemented by the installed snap ins.

C.2.3 Using Utility Functions

You can use several utility functions aid in writing CLI snap in modules. Some of these exist in the ClusterCliSnapinInterface base class, and others exist in a separate package named ClusterCliUtils. These utility functions include:

ClusterCliSnapinInterface Methods

The methods discussed in this section exist in the base class ClusterCliSnapinInterface. These convenience methods are available to every CLI snap in module:

To access these functions, the snap in developer must get a reference to the object instance. This reference is passed as the first parameter to the Param(), Execute(), and Help() methods. The following code snippet shows how this is done.

 my ($self, $param) = @_;
 my $host;
 
 # Get the host, querying the user if necessary
 $host = $self->GetHost();

In the above code, the $self variable is the reference to the object instance (similar to the "this" pointer in C++).

ClusterCliSnapinInterface::GetHost()

The GetHost method returns the host where the VFS files are located. If the Perl script is being ran on a NetWare server then the GetHost method will return the location of the ADMIN volume on the local host. Otherwise, if the ClusterCli.cfg configuration file exists, it will be queried as to the location of the host. This is convenient if the administrator want to run the CLI on a Windows or Linux workstation. Finally, if neither of the two previous attempts return a host, the method will prompt for the appropriate host.

ClusterCliSnapinInterface::OpenVfsFile()

Opens a VFS file and returns the file handle to the appropriate file. This method is guaranteed to open the file in a way appropriate for working with files on the NetWare _ADMIN volume (VFS files).

ClusterCliSnapinInterface::CloseVfsFile()

Closes a VFS file that was previously opened with the OpenVfsFile method.

ClusterCliSnapinInterface::ReadVfsFile()

Reads a specified amount of data from a VFS file that was previously opened with the OpenVfsFile method. This method is guaranteed to read the data in a manner appropriate for VFS files.

ClusterCliSnapinInterface::WriteVfsFile()

Writes the specified data to a VFS file that was previously opened with the OpenVfsFile method. This method is guaranteed to write the data in a manner appropriate for VFS files.

ClusterCliUtils Functions

The following functions are available for use by all functions and methods in the Perl-based CLI. This is in contrast to the previous section which documented methods only available in the snap in classes.

ClusterCliUtils::PrintToCliScreen() Function

The purpose of this function is to display output on the System Console screen in a NetWare environment. This is necessary because the Perl implementation on NetWare displays all output to a separate Perl screen, which is not conducive to a CLI type of environment. In a non-NetWare environment, this function reverts to a standard Perl print() function call.

NOTE:As of NetWare 6.5 SP1, this method has not been fully implemented. Because it will be implemented in a future release of the Perl-based CLI, snap in writers should still use this method. At that time, you will automatically gain the features exposed by this method.