daqctl v1 library (Part 1)

void ksnmp_init_network_map ()
------------------------------

This function initializes the list containing the network map.

void ksnmp_close_private_sessions ()
------------------------------------

This function closes all the private (or public) sessions on the "KLOE nodes".

void ksnmp_close_sessions ()
----------------------------

This function closes all the snmp sessions opened, both on KLOE nodes and on the gigaswitch and arp_server.

void ksnmp_free_network_map ()
------------------------------

This function is used to free the memory allocated by the network map.

void ksnmp_print_network_map (FILE *output, struct network_map *map)
--------------------------------------------------------------------

This function is useful for debugging or writing the network map to the disk.

    output :
        pointer to the output file descriptor.
        stdout and stderr can be used.
    map :
        pointer to the list containing the network map.

void ksnmp_getenv()
-------------------

This function tests the environmental variables */ that can superseed the default values of the parameters. */

struct snmp_session *ksnmp_find_session(char *hostname, char *community)
----------------------------------------------------------------------

This function allows the user to retrieve (if it does exist) the snmp session corresponding to the node hostname in the map and the specified community.

    hostname :
        name (or address in the form xxx.yyy.www.zzz) of host
    community :
        community related to the requested session

    return value :
        pointer to the snmp_session or NULL if it does not exists

struct snmp_session *ksnmp_session_init(char *hostname, char *community,
                                        int port)
----------------------------------------------------------------------

This function initializes an snmp session on an host with the given community name.

    hostname:
        name of the host on which the user
        wants to open the SNMP session.
    community:
        community name used. Using the public community,
        only get and getnext functions can be performed;
        however, private communities allow to perform
        set functions.
    port:
        the remote port can be redefined to overwrite the
        standard port, otherwise 0.

    Return value:
        pointer to the snmp session. It is a structure
        identifying the session and must be used when a
        set or get command are issued to identify the remote
        host.

void ksnmp_init_knode_list()
----------------------------

This function reads, if it exists, the KLOE node authorization file, putting the addresses of that nodes in a vector.

void ksnmp_init_srvs()
----------------------

This function creates two snmp sessions on the gigaswitch and on the arp server.

void ksnmp_init()
-----------------

This function initializes SNMP for KLOE. It creates two snmp sessions on the gigaswitch and on the arp server. These sessions will be used to test or retrieve the actual network map.

struct snmp_pdu *ksnmp_get_next(struct snmp_session *ss,
                                char *varname, int rootlen)
-----------------------------------------------------------

This function sends a GETNEXT_REQ_MSG request to an SNMP daemon on a remote host.

    ss:
        pointer to the SNMP session
    varname:
        name of the actual variable
    rootlen:
        length of the string containing the root of the
        desired MIB subtree

    return value:
        pointer to the pdu structure containing the
        next variable name and value

struct snmp_pdu *ksnmp_get(struct snmp_session *ss,
                           char **names, int n_names)
-----------------------------------------------------

This function retrieves the values of n_names variables (whose names are in the vector names) using the SNMP session ss

    ss:
        pointer to the SNMP session
    names:
        pointer to a vector of strings containing the names of
        the required variables
    n_names:
        number of required variables.

    return value:
        pointer to the pdu structure containing a list of
        variable names and values

struct snmp_pdu *ksnmp_set(struct snmp_session *ss,
                           char **names, int n_names,
                           int *vartype, char **values)
-------------------------------------------------------

This function sets n_names variables (whose names are in the vector names) to the values in the vector values using the SNMP session ss. It can be used to send run control commands and requires ss to be a private SNMP session; in the KLOE standard environment it is called by the ksnmp_send_message.

    ss:
        pointer to the SNMP session
    names:
        pointer to a vector of strings containing the names of
        the required variables
    n_names:
        number of required variables
    vartype:
        type of variables to be set
    values:
        pointer to a vector of strings containing the values of
        the required variables to be set

    return value:
        pointer to the pdu structure containing a list of
        variable names and values

int ksnmp_parse_message (char *message, char *command, char *args)
------------------------------------------------------------------

This function separates a command from the string containings its arguments.

    message:
        a message containing a command and its arguments
    command:
        command to send
    args:
        a string containing the arguments of the command

    return value:
        length of the command string

int ksnmp_parse_procname (char *process, char *procname, char *node)
--------------------------------------------------------------------

This function separates a process name from a node name (process is in the form <procname>@<node> or <procname>).

    process:
        the address of a process in the form <procname>@<node>
        or <procname>
    procname:
        the process name
    node:
        a string containing the node name or address

    return value:
        length of the process name string.

int ksnmp_wait_for_var_val (struct snmp_session *ss, char *var,
                            char *val, int type, char *exit_cond)
-----------------------------------------------------------------

This function tests the variable var on remote node until it assumes the value val. A timeout is implemented. This is useful to implement an acknowledgement mechanism. To avoid to wait the timeout, an exit condition (i.e. a "fault" value) can be passed to this function.

    ss:
        address of the snmp session opened on the remote node
    var:
        variable name
    val:
        variable value to wait for
    type:
        type of the variable var
    exit_cond:
        an exit condition for the function

    return value:
        KSNMP_ACK_OK or KSNMP_ACK_TIMEOUT.

int ksnmp_get_ack (char *message, char *process,
                   struct snmp_session *node_ss)
------------------------------------------------

This function get the acknowledgement referred to a generic message previously sent to a generic process in the DAQ system. It is useful for all the application, in particular to implement a parallel ask command or to receive acknowledgements when a command has been sent to several nodes and processes without waiting for the acknowledgement. If the sender has an snmp session opened on the remote node, it can supply it and the execution is faster; nevertheless, if the snmp session is not supplied (it can be NULL) it can be opened and closed before and after the execution of the command. If this operation fails, KSNMP_ERROR is returned. This function waits for the first-level acknowledgement and the completion of command execution on the remote node or reports an error code (KSNMP_ACK_TIMEOUT_CODE) in case of timeout. If the processing of the command failed on the remote node, KSNMP_ACK_FAULT is returned. The process address can be in the form <name> if the caller supplies node_ss or <name>@<node> otherwise. Warning: this function supports only messages to remote process. If the caller does not supply node_ss or <node> in process name it returns an error code (KSNMP_ERROR).

    message:
        the message to send to a remote process
    process:
        the address of a process in the form <procname>@<node>
        or <procname>
    node_ss:
        address of an snmp session opened on remote node

    return value:
        an error code or KSNMP_ACK_OK if success.

int ksnmp_send_message (char *message, char *process,
                        struct snmp_session *node_ss, int ackflag)
------------------------------------------------------------------

This function sends a generic message to a generic process in the DAQ system. It is useful for all the application, in particular to implement the ask command. If the sender has an snmp session opened on the remote node, it can supply it and the execution is faster; nevertheless, if the snmp session is not supplied (it can be NULL) it can be opened and closed before and after the execution of the command. If this operation fails, KSNMP_ERROR is returned. If ackflag is KSNMP_ACK_WAIT, the function waits for the completion of command execution on the remote node or reports an error code (KSNMP_ACK_TIMEOUT_CODE) in case of timeout. If the processing of the command failed on the remote node, KSNMP_ACK_FAULT is returned. The process address can be in the form <name> if the caller supplies node_ss or <name>@<node> otherwise. Warning: this function supports only messages to remote process. If the caller does not supply node_ss or <node> in process name it returns an error code (KSNMP_ERROR).

    message:
        the message to be sent to a remote process
    process:
        the address of a process in the form <procname>@<node>
        or <procname>
    node_ss:
        address of an snmp session opened on remote node
    ackflag:
        flag to ask the function to wait for acknowledgement or not

    return value:
        an error code or KSNMP_ACK_OK if success

int ksnmp_network_map()
-----------------------

This function fills a map of a "KLOE-like" network.

    return value:
        an error code (NULL) or KSNMP_OK if success

int ksnmp_network_remap()
-------------------------

This function destroys the informations in the actual network map and refills it with up-to-date informations.

    return value:
        an error code (NULL) or KSNMP_OK if success

struct network_map *ksnmp_retrieve_network_map()
------------------------------------------------

This function allows the user to retrieve the pointer to the actual network map.

    return value:
        pointer to the map

struct snmp_session *ksnmp_get_arp_ss()
---------------------------------------

This function allows the user to retrieve the pointer to the arp server session.

    return value:
        pointer to the arp server session

struct snmp_session *ksnmp_get_switch_ss()
------------------------------------------

This function allows the user to retrieve the pointer to the arp server session.

    return value:
        pointer to the gigaswitch server session

ksnmplib_protos.h

The prototypes of the KLOE DAQ snmp routines.

File name : ksnmplib_protos.h

Author : Enrico Pasqualucci

Header file containing the prototypes for the ksnmp function. Should be included in each file where a function in that library is called.

netmap.h

File name: netmap.h

Structure and constants for the KLOE network map

Author: E. Pasqualucci

This file contains the internal structure of the KLOE network map used by the run control and dfc programs. The network map is seen by the program as a list of switch ports, each port contains a list of the related connected nodes. The map structure includes also the pointers to the snmp session structures for each host.

default_parameters.h

Default parameters of the KLOE DAQ snmp library.

File name : default_parameters.h

Author: E. Pasqualucci

This file contains the default values of some constant parameters used in ksnmplib, such as the name of the gigaswitch, the arp server or the name of the KLOE community. All these values can be changed at run time by setting the appropriate environment variables.