Table Of Contents
Full Uploads and Incremental Updates
WANDEST Client
The WANDEST client resides on the OSS application side to facilitate the flow of data from the WANDEST server. The client keeps the OSS application database synchronized with the CWM database on the server side. Multiple clients can run on different workstations and communicate with the server concurrently.
The following WANDEST client configuration is supported with the following platform requirements:
•
WANDEST 2.7 client without Informix bundle.
•
Features
The WANDEST client provides the following features:
•
–
–
–
–
–
Note
•
•
•
•
A typical processing flow of the WANDEST client is shown in Figure 3-1.
Figure 3-1 Typical WANDEST Client Processing
Full Upload
For a full upload of the CWM database, the client issues a full upload command through the socket interface (see Socket Interface). When the full upload is received, the client returns a status to the OSS application. The OSS application can then retrieve the data files from the client for processing.
Incremental Update
For an incremental update, the OSS application issues the incremental update command. The WANDEST client receives the incremental update files from the server. When the files are received, the WANDEST client returns a status to the OSS application for processing.
Note
Socket Interface
The WANDEST client uses the generic client socket interface (GCSI) to communicate with the WANDEST Admin Utility and the OSS application (see ). For information about the Admin Utility, see Admin Utility.
Figure 3-2 WANDEST and OSS Application
The client socket interface is employed between the WANDEST client and OSS application. The OSS application starts the WANDEST client. The client reads the Control and client Configuration files and connects to the specified servers. The OSS application can then send requests to the WANDEST client through the client socket interface.
The client socket uses the TCP protocol to ensure reliability and a socket port number. The port number is passed as a command line argument. When multiple clients are configured on the same workstation, each client must have a unique socket port number.
You must program your OSS application to interface with WANDEST using a socket interface. There is no graphical user interface for the socket interface. However, Cisco provides the Admin Utility, which can be used to communicate with the WANDEST client. You can also program your application to use WANDEST IDL to interface with the WANDEST server directly, bypassing the client. See "Server IDL Interface Definition."
Socket Interface Protocol
The WANDEST client acts as a concurrent server that can accept socket connections from multiple clients, for example the Admin Utility and an OSS application. When WANDEST starts, the client waits for a socket connection at a preconfigured port. Once a connection request is received from the client or the Admin Utility, the client generates a new socket for establishing a connection, freeing the original socket for serving other connection requests.
After a connection is established with the WANDEST client, the Admin Utility or the OSS application can start sending its requests to the client through the socket. Upon receiving the request from the socket, the client parses the request and performs the corresponding operation. All incoming requests from the OSS application or pending requests from the Admin Utility are queued. When the operation is complete, the client sends a response back to the OSS application or the Admin Utility. Based on the return code in the response message, the OSS application or the Admin Utility determines whether the requested operation was successful.
Sample Client Operations
This section illustrates all of the valid client operations. The server uploads only one group per upload or update request. For complete information on groups, see "Data Files."
The OSS application sends the WANDEST client a start full upload message. The client then receives all of the files it requested from the server. Once the files are uploaded, the client responds to the OSS application with a 0 status code, indicating that the full upload operation completed successfully.
Figure 3-3 Start Full Upload
The OSS application sends the WANDEST client the incremental update message. The client then gets the requested incremental update files from the server. When all the requested files are uploaded, the client then notifies the OSS application with a 0 status code, indicating that the incremental update was successful.
Note
Figure 3-4 Start Incremental Update
The OSS application or Admin Utility informs the WANDEST client to gracefully shut down without deregistering from the server. The client rejects all incoming upload requests from the OSS application and finishes the current task (either a full upload or incremental update) before disconnecting from the server. The client process continues running.
The client response to a shutdown request is sent back to either the OSS application or the Admin Utility once the WANDEST client has entered shutdown mode.
After the WANDEST client is shut down, the server continues accumulating all incremental changes. When the client restarts, it can upload all of the accumulated incremental changes from the server without losing any data.
Figure 3-5 Shutdown
The OSS application or the Admin Utility informs the WANDEST client to gracefully shut down and deregister from the server. The client rejects all incoming upload requests, completes the current task, and then deregisters from the server.
The server deletes all information related to this client and stops accumulating table changes for the client. The client sends a response message to the OSS application or the Admin Utility and disconnects from the server.
Figure 3-6 Shutdown and Deregister
Execute the revert command when the WANDEST client terminates or hangs after executing an incremental update command. Use the following guidelines:
a.
b.
The server is tracking both the last sync time and any incremental changes. This incremental update command ensures that no data is lost during any client down time.
Figure 3-7 revert Command
The shuti command immediately shuts down the WANDEST client without deregistering from the server. All current tasks are aborted, so incomplete or inconsistent data can exist in the database or the data files. See the "Recovery Procedures" section.
Figure 3-8 Shutdown and Deregister
Services
The following section discusses the WANDEST client services. These services are listed in the order that they occur when the OSS application or the Admin Utility issues a start command to the client. (See Figure 1-2.)
Control File Verification
When the WANDEST client connects to the server, the client reads the Control file and forwards it to the WANDEST server. The client parses, verifies, and formats the file. The server does not receive the entire Control file. Having the client format the Control file into a predefined structure relieves the server from processing different types of Control files from various client workstation environments.
When a parsing syntax error occurs, the client writes the error to a log file.
Registration
Registration provides the method for the client to send the host name and application name to the server.
Version Verification
The WANDEST client requests the CWM, WANDEST, and IDL versions from the server for version verification. When the CWM version requested is not the same as the CWM version on the server, an error is logged into the log file. However, when the Control file information is valid for the version on the CWM server, normal processing continues.
When the WANDEST and IDL versions on the client are different than what the server is expecting but are supportable by the server, processing continues. The server logs a warning into the log file.
CWM Schema Verification
The client sends the current CWM master schema for the tables noted in the Control file to the server. When an error occurs, the server generates an exception, and the WANDEST client logs the error into the log file. Unless all of the information is valid, the client does not start the full upload or incremental update.
Full Uploads and Incremental Updates
The time interval for full uploads and incremental updates is specified through the OSS application.
The client passes the FTP user name and password to the WANDEST server to indicate how to login and where to place the files. These parameters are specified in the client Configuration file. The directory names and structures are based upon group and sequence number. Only one group is uploaded per request. For information about groups and sequence numbers, see "Data Files."
An error on the server side or during the FTP transmission causes the server to raise an exception, and the client logs an entry in the log file.
The WDCLIENT_DBPOPULATE parameter in the client Configuration file specifies the temporary database for loading the data files.
Client Database
The client creates a database when the WDCLIENT_DBPOPULATE parameter in the client Configuration file is set to Yes. The client creates or updates a database table corresponding to each table in the Control file. The client creates the database during the full upload.
In an incremental update, the client performs the following actions:
•
The client reads each record sequentially in the insert/update file. When a particular row exists in the corresponding table in the client database, the client updates that record with the data from the insert/update file. When the row from the insert/update file does not exist in the client database table, the client inserts the record.
•
The client reads each record sequentially in the delete file. When a particular row exists in the corresponding table in the client database, the client deletes the row from the WANDEST client database. When no corresponding row exists, no processing occurs.
DB Loader
DB Loader is a utility that loads the data files from either a full upload or an incremental update into a temporary database. To view the tables in the temporary database, use the Informix utility, DBAccess.
To run DB Loader, specify the following arguments at the command line prompt:
wddbloader -C <Control file pathname> -P <directory name where files reside> -N <database name into which files are copied> -D <delimiter character used in the Control file> -FdThe first four arguments are required to run DB Loader. The last argument, -Fd, is optional and drops the database (the one into which files are copied). All uncompressed data files in the directory named in the command line are loaded into the database.
The table names in the temporary database are listed in Table 3-1.
Note
Client Archive Directory
When the WANDEST client issues a command that was previously used, for example a full upload for Group5, sequence6, the client looks at the destination directory to see if are any files are present. Previously issued commands result in files being deposited in the destination directory. Thus, the client moves the older files in the destination directory to the archive directory to make room for the results of the current command.
The client moves the older files to the archive directory specified by the WDCLIENT_ARCHIVEDIR parameter in the client Configuration file. The default directory is /usr/users/wandest/client/data/save. The client takes no action other than appending the files in the archive directory.
Note
Control File
Each WANDEST client must have a Control file to specify the data WANDEST is to collect. Unless a different directory is specified, the installation program places a default Control file in the following client directory: /usr/users/wandest/client/ctrl/wdclient.ctrl
The default Control file might be different than the database schema of the CWM version on the WANDEST server workstation. To prevent this mismatch, copy the Control file—generated by the server installation—to the client. This file is generated in $WANDEST_HOME/wdclient.ctrl.
The WANDEST client can run using the default Control file. In this file, specify the data WANDEST is to collect.
Note
Formatting
Program the Control file to contain the names of the groups, tables, and columns of the data to be collected. The client parses the Control file, formats the information, and passes it to the server. For information on groups, see "Data Files."
Format the Control file according to the following example:
--WANDEST client control file
<table name> | <group id> | <column name >:p | <data type> | <column name >:p | <data type> |<column name > | <data type> | .......
--
<table name> | <group id> | <column name >:p | <data type> | <column name > | <data type> |......
......A where clause might be added to the end of each table, using two pipes (||) as a delimiter. The syntax is the same as Informix SQL.
Each table name is followed by the group ID to which that table belongs.
Caution
One group can have several tables, or all tables can belong to one group. The group name is followed by the column names to be extracted. Specify the name and data type of each column. Data types are provided in Table 3-2. If no data is needed from a particular table, do not include a table name.
Provide all of the unique key columns for each table included in the Control file, so each row can be uniquely identified. Other key columns might also be included. Identify each key column by appending :p to the column name, shown in the previous example. The data type of the column follows the key column name.
Note
The key column(s) must immediately follow the table name and group ID. Non-key columns cannot be in between the key columns.
The number of rows in this file must never exceed the total number of tables in the CWM database. Any line in the file that begins with -- is treated as a comment line.
For information on configuring the Control file to run multiple clients from the same workstation, see Running Multiple Clients.
The following example shows a portion of a Control file.
systemmaintlog|0|rec_tag:p|i|network|c(8)|node_name|c(10)|ntime|i|edate|d|etime|c(8)|time_ zone|c(4)|class|c(5)|msg|c(256)|act_flag|s|reserved|i|sv_system|0|name:p|c(8)|val|c(20)|network|0|netw_id:p|s|ipx_netw_id|s|netw_name|c(8)|active|s|upgrade_status|s|mgmt_comm|s|r eserved|i||where active=1user_info|0|user_name:p|c(33)|insync_primary|i|profile_name|c(33)|sec_profile|0|profile_name:p|c(33)|insync_primary|i|cmgui|i|sctgui|i|nwtopology|i|smsgui|i |scm|i|imagedownload|i|noderesync|i|configsave|i|configrestore|i|wingz|i|nwbrowser|i|newre port|i|smadmin|i|node|0|node_id:p|i|netw_id|s|node_name|c(10)|ipx_netw_id|s|ipx_node_id|s|net_ip_address|i| lan_ip_address|i|nw_ip_address|i|model|i|alarm_state|s|gateway|s|active|s|platform|s|subty pe|s|release|c(11)|fs_inc_rate|s|fs_dec_rate|s|fs_fdec_rate|s|rst_timeout|s|mode|s|mgmt_st ate|s|manager|s|protocol|s|reserved|i|packet_line|0|pln_obj_id:p|i|l_node_id:p|i|l_network_id|s|l_line|s|l_slot|s|l_port|s|l_vtr k|s|l_num_phy_line|s|l_primary_phy_line|s|l_phy_line_bitmap|s|card_type|s|interface|s|line _load|i|r_network_id|s|r_node_id|i|r_line|s|r_slot|s|r_port|s|r_vtrk|s|r_num_phy_line|s|r_ primary_phy_line|s|r_phy_line_bitmap|s|aps_flag|s|alarm_state|s|commentc|c(20)|active|s|st atus|s|stat_reserve|i|b_bq_depth|i|b_bq_efcn|i|clp_h_thresh|s|clp_l_thresh|s|time_load|i|n on_time|i|v_load|i|bursty_a_load|i|bursty_b_load|i|bursty_a_cmax|s|bursty_b_cmax|s|max_cha n_per_port|i|protocol|s|pnni_status|s|reserved|i|circuit_line|0|cln_obj_id:p|i|l_node_id:p|i|l_network_id|s|l_slot|s|l_line|s|l_port|s|card _type|s|interface|s|commentc|c(20)|active|s|status|s|line_info|s|reserved|i|frp|0|l_node_id:p|i|frp_obj_id:p|i|l_network_id|s|shelf|i|l_slot|s|l_port|s|port_speed|i|c ommentc|c(20)|active|s|status|s|port_type|s|queue_depth|i|ecn_thresh|i|de_thresh|s|logical _port|s|line|s|timeslot_num|s|timeslot_speed|s|port_bitmap|i|port_equ|s|port_flag|s|protoc ol_type|s|asyn_upd|s|link_timer|s|poll_timer|s|poll_counter|s|err_thresh|s|event_count|s|x mt_timer|s|rcv_timer|s|cllm_ena|s|signal_state|i|elmi|s|subrate_speed|s|interface|s|encodi ng|s|role|s|max_frame|s|retry_cnt|s|ack_wait_time|i|vmac|c(15)|poll_cycle|s|poll_intv|s|gr oup|s|reserved|i|connection|0|l_node_id:p|i|con_obj_id:p|i|rcon_obj_id|i|lcon_obj_id|i|master_flag|s|l_netw ork_id|s|shelf|i|termination|s|l_slot|s|l_line|s|l_channel|s|l_dlci|s|l_vci|i|r_network_id |s|r_node_id|i|r_slot|s|r_line|s|r_channel|s|r_dlci|s|r_vci|i|con_type|s|rate_info|s|l_loa d_unit|s|r_load_unit|s|min_bw|i|dax_con|s|txr_card|s|commentc|c(20)|active|s|status|s|qir| i|pir|i|vc_q_depth|i|vc_q_thresh|i|vc_de_thresh|i|eg_q_depth|i|eg_q_de_thresh|i|eg_q_ecn_t hresh|i|de_tag_ena|i|cmax|s|lper_util|s|rper_util|s|con_info_flag|s|cir|i|a_bit_status|s|i bs|i|bc|i|be|i|eg_q_select|s|card_type|s|channel_type|s|fecn|s|de_to_clp_map|s|clp_to_de_m ap|s|rate_type|s|rate_fctr|s|smpl_per_pckt|s|retry_cnt|s|ack_wait_time|i|par_subtype|s|par _rout_pri|s|par_max_cost|s|par_res_trk_typ|s|par_chan_pcr|i|par_chan_mcr|i|qbin_num|s|lcn| i|reserved|i|Client Configuration File
One client Configuration file exists for each WANDEST client. The installation program sets the Configuration file based upon responses to the installation program prompts. The default name and location for the file is /usr/users/wandest/client/config/wdconfig.conf. The Configuration file path must be specified in the environment variable WDCONFIG before the client starts. The environment variable is set in the .cshrc file for user WANDEST during installation. The correct syntax to change the variable is setenv WDCONFIG <pathname>
To modify the Configuration file, complete the following steps from the wdadmin utility or your OSS application:
Step 1
Step 2
Step 3
Step 4
host% wdclient <serverworkstationname> <socket port number>
Note
The following example shows a configuration file:
WDCLIENT_ROOTDIR /usr/users/wandestWDCLIENT_OUTDIR /usr/users/wandest/client/dataWDCLIENT_LOGLEVEL 2WDCLIENT_LOGFILE WDClient.logWDCLIENT_DBNAME WDWDCLIENT_CTRLDIR /usr/users/wandest/client/ctrlWDCLIENT_CTRLFILE wdclient.ctrlWDCLIENT_TABLEDELIMITER |WDCLIENT_MAXTHREADNUM 5WDCLIENT_FTPUSERNAME wandestWDCLIENT_FTPPASSWORD ******WDCLIENT_DBPOPULATE NWDCLIENT_ONEFTP YWDCLIENT_DISKSPACE_WARNING 5WDCLIENT_DISKSPACE_CRITICAL 1WDCLIENT_ARCHIVEDIR /usr/users/wandest/data/saveWDCLIENT_CWMVERSION rel150WDCLIENT_COMMRETRY 10WDCLIENT_APPNAME WDCLTTable 3-3 lists all client Configuration file parameters and definitions.
Table 3-3 Client Configuration File Parameters
WDCLIENT_ROOTDIR
/usr/users/wandest
Root directory where the WANDEST client is installed. The destination path for both the WANDEST server and client is /usr/users/wandest. This path cannot be changed during or after installation.
WDCLIENT_OUTDIR
/usr/users/wandest/
client/dataOutput directory prefix. For information about the output directory structure, see "Data Files."
WDCLIENT_MAXDIRSEQ
300
Maximum number of directories for the incremental update.
WDCLIENT_CTRLDIR
/usr/users/wandest/
client/ctrlDirectory that contains the Control file.
WDCLIENT_CTRLFILE
wdclient.ctrl
Name of the Control file.
WDCLIENT_LOGLEVEL
2
Log level at which the debug messages are written to the log file. See "Exceptions and Errors."
WDCLIENT_LOGFILE
WDClient.log
Name of the log file. Log files are saved in WDCLIENT_ROOTDIR/log directory.
WDCLIENT_DBNAME
wandest
Name of the WANDEST client database. When multiple clients exist on the same workstation, this name must be unique.
WDCLIENT_MAXTHREADNUM
5
Maximum number of threads that the WANDEST client can execute.
WDCLIENT_TABLEDELIMITER
| (pipe)
One-character delimiter that separates text in the Control file.
WDCLIENT_FTPUSERNAME
wandest
User name for the login to the client machine for the ftp command.
WDCLIENT_FTPPASSWORD
****** (encrypted)
Password for the login to the client machine for the ftp command.
Note
WDCLIENT_DBPOPULATE
N
(Optional) When set to Y, the WANDEST client maintains a database that is synchronized with the CWM database. The client processes the full upload and incremental data files to this WANDEST client database. Leave this set to N.
Note
WDCLIENT_CWMVERSION
rel151
CWM version on the WANDEST server.
WDCLIENT_ARCHIVEDIR
/usr/users/wandest/
client/data/saveDirectory where all of the previously processed data files are stored.
WDCLIENT_ONEFTP
Y
(Optional). When set to Y, the data files of all tables are zipped into one file. See "Data Files."
WDCLIENT_COMMRETRY
10
Retry count for CORBA communication between the client and server.
WDCLIENT_APPNAME
WDCTL
The user OSS application name. When more than one client exists on the same workstation, this name must be unique.
WDCLIENT_UPDATEMETHOD
M (manual update)
Update method for incremental update. The choices are A for automatic or M for manual.
Automatic incremental update is not currently supported. Please leave this as the default (M for manual).
WDCLIENT_UPDATEINTERVAL
N/A
This parameter is not currently supported.
WDCLIENT_DISKSPACE_WARNING
5
The disk space threshold in megabytes. If the available disk space on the client side drops below this number a warning message appears.
WDCLIENT_DISKSPACE_CRITICAL
1
The critical disk space threshold in megabytes. If the available disk space on the client side drops below this number a critical warning message appears.
Error Handling
When the WANDEST server detects an error, it raises an exception and sends it to the client. The client handles the exception and logs the error into the log file. For a list of client errors, see "Exceptions and Errors."
Shut Down
This section discusses how the WANDEST client gracefully shuts down.
Three different shut downs exist for the client.
1.
Use this option to stop client processing but allow the server to continue collecting the incremental changes. When the client reconnects after a short time, it can still get incremental updates.
The client checks to see whether any tasks are currently running. When the client returns a status code indicating that a request is pending, complete one of the following options:
a.
b.
2.
Shut down the client and tell the server to stop accumulating changes for this client. When the client reregisters, it must ask for a full upload.
The client performs the same procedure as described in option 1 and calls the deregistration function to the server to deregister before it exits.
3.
Immediately shut down the client, regardless of any pending processes.
Running Multiple Clients
Depending on the OSS application, multiple WANDEST clients can coexist on the same workstation. Each client communicates with a different CWM that manages different networks. Each client shares the same binaries in /usr/users/wandest. All Control files may reside in the same directory; all client Configuration files may reside in the same directory.
At start up, each client reads the Configuration file (given as a specified parameter) and completes the following processes:
•
•
•
•
Note
Table 3-4 lists important parameters affecting multiple clients.
Admin Utility
The Admin Utility is used to issue commands to the WANDEST client. The available commands are listed in Table 3-5.
Modes
Two modes exist for the Admin Utility: interactive and non-interactive. Use the interactive mode when issuing several commands. Use the non-interactive to issue just one command.
Interactive
When the interactive mode is started, the wdadmin prompt is displayed and remains until the Admin Utility is terminated.
To start the Admin Utility in interactive mode, specify the following syntax at the command prompt:
host% wdadmin -S<server> -P<port> -E<errorfile>Table 3-6 describes the interactive variable syntax.
Table 3-6 Interactive Variables
<server>
Machine name where wdclient is running.
<port>
Port to which wdclient is listening.
<errorfile>
Name of the error file provided.
The wdadmin prompt appears. Type in the desired commands, listed in the table below, and at the end of the session, enter the quit command to exit Admin Utility. All commands issue return a status code, along with the date and time.
Non-interactive
To enter one command through the Admin Utility in non-interactive mode, specify at the command prompt:
host% wdadmin -S<server> -P<port> -E<errorfile> -C<AdminUtilComd>Table 3-7 describes the non-interactive variable syntax.
An optional argument, -E, can be included in the command line. This optional argument augments any returned status codes with the text title of the status code.
Recovery Procedures
If the WANDEST client terminates or hangs, the OSS application does not receive the return status from the previous command, and the socket times out. To recover the previous command, the OSS application must repeat certain commands after the client restarts.
Table 3-8 lists the error conditions and recovery procedures.
