To read data logged by SunNet Manager using a schema file not supported by IT Service Vision, you must first create IT Service Vision dictionary entries for the tables of metrics defined in the schema file using the %CSSNMSCH and %CPDDUTL macros. Run these macros iteratively to create suitable definitions in your PDB for the tables in the schema file.

See the IT Service Vision Macro Reference documentation for instructions on using %CPDDUTL.

%CSSNMSCH Syntax

The %CSSNMSCH macro takes the following parameters:

    %CSSNMSCH( schema=,
               rpcids=,
               snmnams=,
               outfile= );

where:

    schema=      Name of input schema file to read
    outfile=     Name of output file to contain CPDDUTL statements
    rpcids=      Name of input file that contains RPC ID definitions
    snmnams=     Name of input file that contains SNM schema name definitions

Creating Dictionary Definitions from a Schema File

Creating IT Service Vision table definitions from a SunNet Manager schema file cannot be totally automated because of the need for (sometimes) extensive input from the user. This input is in the form of interpretations of what the schema author had in mind when he or she wrote the schema and provision of a mapping from long, schema variable names to short (less than 8 characters) IT Service Vision variable names. This sometimes results in the user having to edit the schema file and virtually always means the user will have to manually enter the shortened variable names.

To create IT Service Vision dictionary definitions from a schema file, do the following:

1. Define RPC ids

   RPC ids are used by SunNet Manager to map numbers to names (of tables). SunNet Manager uses the /etc/rpc file on your system to determine how to log data.

   • Locate the /etc/rpc file on the host that runs SunNet Manager. Make a copy of it and edit it to make its format resemble that of the example rpc id file !SASROOT/misc/cpe/csrpc.
     
     
   • Submit the %CSSNMSCH macro from the SAS PROGRAM EDITOR window to read your schema file (presumably one not already supported by IT Service Vision) and the rpc file.
     
     
   • Again edit the copy of the rpc file to supply any missing values.
     
     
   • Loop through these steps until all ids are defined.
     
     
2. Map long variable names to short variable names

   Schema files use names for tables and metrics. These names are too long for IT Service Vision. You must supply the file that maps long names to short names and point the %CSSNMSCH macro to it.

   • Run the %CSSNMSCH macro against your schema file again. It will produce many messages about undefined variable names.
     
     
   • Create a file that maps long names to short names. Use the messages produced in the preceeding step and the table and variable name definitions in !SASROOT/misc/cpe/cssnmnam as a guide (note that the message produced by %CSSNMSCH in the SAS log are of a form that they can be cut and pasted directly into the file that maps long names to short names. Just type over UNKNOWN with a correct name. There are rules regarding table and variable names for IT Service Vision. They are:
     
     
     • User defined table names for IT Service Vision should begin with "U" and have exactly four more alphanumeric characters.
       
       
     • Both table and variable names should consist of letters and numbers only (no underscores!).
       
       
     • User-defined variables should be 7 or fewer characters long.
       
       
   • Loop through these steps until all table and variable names have been defined properly.
     
     
3. Resolve error messages produced by %CSSNMSCH

   A number of things can go wrong with converting a schema file to IT Service Vision dictionary definitions even after the names and rpc ids are resolved. These problems are principally caused by the schema file not being totally syntactically correct. To get around these problems, do the following:

   • Run the %CSSNMSCH macro against your schema file again.
     
     
   • If you get no error messages, continue with step 4.
     
     
   • If you get error messages, edit the schema file as indicated in the messages. The kinds of error messages to expect are:
     
     
     • Malformed BY list. The BY list is called the key in the schema file -- it is used to set the order of observations in the DETAIL data (useful when reporting on the data) and to recognize duplicate observations. Since SunNet Manager does not depend on the BY list being correct (or even present) for tables, it many times is not. Edit the schema file to supply the correct BY list after the "characteristics-k" statement.
       
       
     • Too many variables defined in a table. If you get a message about too many variables, change the declaration for the vnam, long, and sort arrays in the %CSSNMSCH macro to something larger and try again.
       
       
     • Schema format errors. %CSSNMSCH is more sensitive to some deviations from schema format rules than SNM is. If errors of this type occur, %CSSNMSCH issues messages on the SAS log that are usually self- explanatory if you examine the schema file carefully.
       
       
     • Unknown BY-group variable. Until all variable long names are mapped to short names (see step 2 above), this message will appear for the variables in the BY list. Once all long-to-short names have been mapped, this message probably means that the BY-list variable is misspelled in the schema file. A common misspelling involves case mismatch: "-k ifIndex" sometimes is in the BY list definition when "IfIndex" is in the variable definition. Correct the BY list spelling and rerun %CSSNMSCH.
       
       
     • Sometimes variations from standard syntax (such as unbalanced parentheses or quotes, or certain special characters) will confound %CSSNMSCH and error messages will be confusing. The easiest way to solve these problems is to examine the schema file for anomalies around the point the error messages occur.
       
       
   • Loop through these steps until messages have been resolved.

   When all messages are resolved, %CSSNMSCH will create, in the specified OUTFILE, the %CPDDUTL statements to define the tables and variables for the schema file.

4. Define the tables and examine/correct the definitions

   Despite the best efforts of %CSSNMSCH, some schema files do not convert perfectly to IT Service Vision dictionary definitions.

   • Run %CPDDUTL on the dictionary update statements created above to define the new entries in your PDB (a new PDB presumably created just for this purpose).
     
     
   • Examine the definitions using the IT Service Vision interactive interface and compare them to the schema files. Non-standard constructs or special characters can make %CSSNMSCH parse the schema file incorrectly. Either update the schema file to clarify the variable definition or remove the construct that is confusing %CSSNMSCH.
     
     
   • Loop through these steps until the definitions are right. If you changed the schema file to correct the problem, loop back through step 3.
     
     
5. Use the definitions and correct if necessary.

   The ultimate test of a table definition created from a schema file is to use the table.

   • Run %CPDDUTL on the dictionary update statements created above to define the new entries in your PDB.
     
     
   • Test the new definitions by running %CSPROCES on the values of the metrics as logged by SunNet Manager. Modify the %CPDDUTL control statements or the schema file as necessary to get the table(s) the way you want them.
     
     
   • Loop through these steps until the definitions are right. If you changed the schema file to correct the problem, loop back through step 3.
     
     
6. Keep your changes. (optional)
   
   
   • If you want to make your new table definitions available generally at your site, use the %CPDDUTL INSTALL TABLE control statement. For more details about this statement, see the Macro Reference documentation for IT Service Vision.

EXAMPLE

 * Allocate IT Service Vision libraries and the PDB;
 %CPSTART(  mode=batch,
            pdb=/u/testpdb,
            access=write );

 * Create CPDDUTL ontrol statements from your own schema file in /u/snm.ddutl;
 %CSSNMSCH( schema=/usr/snm/schema/toaster.schema,
            rpcids=!SASROOT/misc/cpe/csrpc,
            snmnams=/u/nams, /* Format like !SASROOT/misc/cpe/cssnmnam */
            outfile=/u/snm.ddutl );

 * Create table and variable definitions from the CPDDUTL control statements;
 %CPDDUTL(  filename='/u/snm.ddutl',
            list=yes );

 * Process data from the new schema file;
 %CSPROCES( /usr/snm/logfile,
            uutab1,
            collectr=SUNETMGR );