Examples:

API For ETA-Comm Switches

This note describes the API functions used to control ETA-Comm switches from compiled Software.

Introduction
ETA-Comm switches are controlled through a Remote Procedure Call mechanism rather than a text based command interface. User programs are integrated with this RPC mechanism using a small portable library that is statically linked to that program. This note described the stub library that implements these RPC calls. Other libraries such as those that add scripting support incorporate this library.

To use the library the application program first establishes contact with the switch unit. Each switch can be referenced by name rather than a static IP address if necessary. Additional switch units can be associated with the first unit if the configuration uses linked switch boxes, the
resulting configuration behaving like one large switch.

Once connected to the switch a user may ask for an inventory of cards and current connections and may setup and tear down connections. The switch can accommodate multiple users – currently a maximum of 7 – so the switch enforces a loose ownership mechanism to allow these users to share the switch without interfering with each other.

Note that all chassis, card and port (end point) numbers are based from one. The current versions of the API libraries are not thread-safe and are only designed to work with a single end unit. The library is small and is intended to be statically linked with a user program, a program that supports a single instance of a user. Other instances of the program can be run, though since the library is self-contained (it doesn’t use resources in a shared / dynamic library).

Function Return Codes

All function calls return an integer code. If the number is negative then this signals an error. Return codes are:

TCL Calls for the ETA-Comm Switches

This note describes the TCL interface to the ETA-Comm switches

TCL support for the ETA-Comm switch is provided through a dynamically loaded library. This version of the library is not thread-safe – it should not be used by more than one user on a system – and is designed to support communicating with only one switch at a time.

The library is built in two forms – etacomm_tcl.so for Linux (x86) and etacomm_tcl.dll for Windows. Windows users will also need oncrpc.dll, a DLL that provides ONC-RPC support. The TCL support library, etacomm_tcl, is usually placed in the directory where the TCL scripts are running from (but could be anywhere on TCL’s Library path). The ONC support library, if used, is usually placed in the %Windows%/System32 directory. The library is loaded as one of the first calls in a script (or from the TCL prompt) using this call:-
load etacom_tcl.so etacomm
(For Windows substitute ‘dll’ for ‘so’)

Once loaded TCL may connect to a switch using
ETconnect “unit_location” “username”

This will return the user’s key or an error code. Like all calls to this library a zero or positive result is a success code and a negative number is a failure code. Error codes can be turned into strings that describe the error using the call:-
ETerror <errornumber>

The unit location will be either a unit name or its IP address. The username may be any string up to a maximum of 24 characters. A successful call will return the ‘user number’ of a user which is used internally to track resources owned by that user. The call:-
ETuser <usernumber> will return a string identifying a user.

The user can ask for the server version number using this string:-
ETversionNumber

After using the switch the user will disconnect from the switch using
ETdisconnect

Disconnect will not only break the connection but also tear down any connections that were being used by this program (except if the user is ‘debug’). If the user wants to temporarily disconnect then the call is:-
ETtempDisconnect

This will return and integer, a token that is used when reconnecting with this call:-ETreconnect “unit_location” token

The user gets card and connection inventory information in a two stage process. For the card inventory the first request is to get the inventory cached in the library:-ETgetcardlist <switch unit number>

The switch unit number is an integer 1 through 4. The default box is 1 – everything is numbered from 1 in this system. The function ETgetcardcount will also tell you how many cards were found. Once this call is successful the the user makes repeated calls to get the card information as a new ETcardInfo object – the ‘new’ part of the object makes the call to actually get the information.

Typically this would be in a loop with the objects added to an array:-

set numcards [ ETgetcardlist 1 ]
%% Check numcards for an error code here
set i 0
while { $i < $numcards } {
ETcardInfo etc($i) 1 0
incr i } 

The ETcardInfo object has these methods:-
cardtype – returns the card type number
currentslot – returns the slot that the card is in
currentbox – returns the chassis that the card is in
revision_number – returns the revision number as a four character string
serial_number – returns the serial number as a 24 character string

Connections are managed using two objects, ETconInfo and ETnode. Connections are made and broken in a two stage process where calls are made to establish routes and then either executed or abandoned. During the connection process where a user is making a series of connections other users are temporarily prevented from establishing routes in the switch. This ends when the connections are either executed or abandoned or if the requesting user stops talking to the switch for a period of about 30 seconds (in which case all pending connections will be abandoned).

The ETconInfo object has these methods:-
owner – returns a string containing the name of the owner
fromBox
fromCard
fromPort
toBox
toCard
toPort – integers showing the box, card and port at each end of a connection

The corresponding calls to get connection information are:-
ETgetConList
ETgetPendingList

This generates information that’s used to generate ETconInfo objects. The ETconInfo object is created with a parameter which is either 0 to indicate that the information is from the connection list or not zero to indicate that it is from the pending list. Successive calls step through the list. The information is cycled at the end of the list so the user should keep track of the number of calls to be made to avoid getting duplicate objects (as the list cycles an INVALID_CARD error will be reported, then the next call will be back to the beginning of the list so the user could just keep making the calls until an error is reported).

Since getting and processing connection information is quite a complex operation there is a helper function that can be used to tell whether any connections have changed since the last time this user had requested connection information.

The function:-
ETconPoll
Returns an integer that is 1 if any connections have changed since the last poll or inventory call, zero otherwise. This is a relatively efficient call and is intended for applications that display connection lists to users that want to modify those lists by periodically polling to see if its necessary to refresh the connection lists.

Connections are manipulated using an ETnode object. ETnode is created with three parameters, the chassis, card and port, and these parameters can be read back using these fields. New connections are specified with ETmake <node1> <node2> Connections are torn down with ETbreak <node> (either end of a connection may be used) Pending connections are activated using ETexecute or abandoned with ETabandon.

Sample Program

This sample program is used to open a connection to unit and read the inventory of cards in that unit.

#include <studio.h>
#include "etclient.h"
extern int eta_start( char *location, char *user );
extern int eta_stop( void );
extern char *eta_errorcode( int errnumber );
extern int eta_inventory( int box, cardList **clist );
extern int eta_cardname( int cardnumber, char *nstring );
int main()
{
int result, i, j;
cardList *cl;, *clp;
char name[24];
if( eta_start( NULL, "test" ) < 0 )
return( -1 );
result = eta_inventory( 1, &cl );
if( result < 0 )
{
(void) eta_stop();
return( -1 );
}
if( result == 0 )
{
printf( "No cards found\n" );
(void) eta_stop();
return( 0 );
}
printf( "%d Cards Found\n", result );
for( i = 0, clp = cl; i < result; i++, clp++ )
{
if( eta_cardname( clp->type, name ) == ETA_OK )
{
printf( “Slot %2d Type %2d (%20s) Revision %c%c Serial”,
clp->slot,
clp->type,
name,
(clp->revision >> 8) & 0x7F,
clp->revision & 0x7F );
for( j = 0; j < 10; j++ )
printf( "%1d", clp->serial[j] );
printf( "\n" );
}
}
free( cl );
(void) eta_stop();
return( 0 ) }