This is scli.info, produced by makeinfo version 4.2 from scli.texinfo.

INFO-DIR-SECTION Net
START-INFO-DIR-ENTRY
* scli: (scli).		SNMP command line interface
END-INFO-DIR-ENTRY

   This file documents the `scli' SNMP command line interface.

   Copyright (C) 2001-2002 Ju"rgen Scho"nwa"lder

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: scli.info,  Node: Extending,  Next: Problems,  Prev: Modes and Commands,  Up: Top

Writing Extensions
******************

   This chapter describes the process of extending scli with new
commands.  This is relatively straight-forward and does not require any
SNMP programming skills. All you need is to be able to read and
understand MIB definitions and some C programming skills.

   The first thing you need to do in order to extend scli is to select
the set of MIBs needed to implement the new commands. Once you know the
list of required MIBs, you need to check whether there are already
stubs for these MIBs in the `stub' directory. If some are missing, you
have to create them.

   Once you have all the MIB stubs, you need to decide which scli mode
should contain your new commands. An scli mode is simply a logical
grouping of related commands (e.g. all commands that deal with layer 2
bridges). A mode is usually implemented by a single C file in the
`scli' directory which is named like the mode itself.

   Now that you know the mode for you commands, you can start writing
commands. Every command is implemented by a C function which basically
has three parts: command syntax parsing, executing the command (usually
this requires calls to other internal functions), and finally cleanup.

Creating Stubs
==============

   Compiler generated MIB stubs are used to do all the low-level SNMP
work for you. To generate MIB stubs, you need to install the `smidump'
MIB compiler which comes with the `libsmi' distribution. You need to
make sure that the `smidump' compiler version fits with the `scli'
version since there are sometimes changes between the stub interface
and the SNMP engine interface. The easiest way to ensure that you have
a suitable compiler is to check that the compiler version number
matches the scli version number contained in comments in the stub files
contained in the `scli' distribution.

Implementing Modes
==================

   Every scli mode implementation has only one externally visible entry
point which is used to initialize the mode. This name of the entry
point is by convention derived from the mode name. If we want to
implement a mode "example", the function would look like this:

     void scli_init_example_mode(scli_interp_t *INTERP)

   The declaration of the function prototype goes into the file
`scli.h' and a call of the initialization function must be added in the
file `scli.c'.

   The main purpose of the entry point is to register the mode. This is
accomplished by filling out an instance of type `scli_mode_t' which
describes the mode. The first member of the structure is the unique
name of the mode. The second member is a string describing the purpose
of the mode and which standards or proprietary MIB modules are relevant
for it. The third parameter is a NULL-terminated vector of `scli_cmd_t'
structures, one structure for each command.


void
scli_init_example_mode(scli_interp_t *interp)
{
    static scli_mode_t example_mode = {
	"example",
	"The scli example mode is only used to demontrate how you can\n"
        "extend the scli interpreter with new modes and commands.",
	NULL
    };

    scli_register_mode(interp, &printer_mode);
}

Implementing Commands
=====================

   The function below implements a `show hello world' command.  A
function implementing an `scli' command is usually referred to as a
"command procedure".  Every command procedure is called with three
arguments:

     int (*FUNC) (scli_interp_t *INTERP, int ARGC, char **ARGV);

  1. A pointer to the scli interpreter in INTERP.

  2. The number of arguments in ARGC.

  3. The command arguments as a vector of C strings in ARGV.
        Command procedures return an `scli' status code. See the file
`scli.h' for a description of the various error codes supported by the
`scli' interpreter. Below is an example which implements a `show hello
world' command.


static int
show_hello_world(scli_interp_t *interp, int argc, char **argv)
{
    if (argc > 1) {
	return SCLI_SYNTAX_NUMARGS;
    }

    if (scli_interp_dry(interp)) {
	return SCLI_OK;
    }

    g_string_sprintfa(interp->result, "hello world");

    return SCLI_OK;
}

   The first thing we have to do in a command procedure is syntax
parsing. This is important to get this right to ensure stability. In
the example above, we simply check that no arguments are present. If
there are any arguments, the command procedure returns the `scli' error
code `SCLI_SYNTAX_NUMARGS'.

   Once we have successfully parsed the command, we have to decide
whether we really have to execute it. If the interpreter is running in
dry mode, we just parse the commands but do not execute them. This is a
handy tool for validating the syntax of an `scli' script file without
actually touching any devices and can be used to test that your syntax
parsing code really works as it should.

   The next part of every command procedure implements the
functionality.  In this case, we just copy the string `"hello world"'
into the interpreter's result string. The result string is a `glib'
`GString' which can dynamically grow. You should study the `glib'
documentation on how to use `GString's effectively.

   The last part in our command procedure is responsible for freeing any
resources and to return the status code. Since the `show hello world'
command always succeeds, we simple return `SCLI_OK'.

   Once we have written a command procedure, we need to register the
command in the interpreter. This is done by filling out a data
structure which describes our command and registering this data
structure as part of the mode registration.

Adding MIB Stubs
================

   I might be necessary to add stubs for additional MIB modules. This
process is very straightforward.

  1. Edit `stubs/Makefile.am'

  2. Run `make stubs' in the `stubs' directory. Note that you need a
     version of `smidump' which is compatible with the `scli' release
     you are using.

  3. Edit `scli/scli.h' by adding the new header file(s) to the
     includes at the end of the file.

Dynamic Loading (Plugins)
=========================

   This chapter explains how you can add functionality to `scli'
programs.


File: scli.info,  Node: Problems,  Next: Concept Index,  Prev: Extending,  Up: Top

Problems
********

   If you find a bug in `scli', please send electronic mail to
`scli@ibr.cs.tu-bs.de'.  Include the version number, which you can find
by running `scli --version'. Also include in your message the output
that the program produced and the output you expected.

   If you have other questions, comments or suggestions about `scli',
contact the author via electronic mail to `schoenw@ibr.cs.tu-bs.de'.
The author will try to help you out, although he may not have time to
fix your problems.


File: scli.info,  Node: Concept Index,  Prev: Problems,  Up: Top

Concept Index
*************

* Menu:

* getting help:                          Overview.
* greetings:                             Overview.
* help:                                  Overview.
* history:                               Overview.
* how to read:                           Instructions.
* invoking:                              Overview.
* manual, how to read:                   Instructions.
* options:                               Overview.
* overview:                              Overview.
* reading:                               Instructions.
* tail recursion:                        Concept Index.
* usage:                                 Overview.
* version:                               Overview.


