6
Command Line Interface

This chapter contains general instructions on how to use the command-line interface. It also contains an entry for each command available in the command-line interface. Each command is followed by a brief description of its purpose. In addition, the proper syntax, keywords, and command parameters are provided.

This chapter contains the following topics:

• OESCTL
• OESMON
• OESUCR
• OESDL
• OESRL
• OESCHART

OESCTL

The oesctl command enables an Oracle Email administrator to perform some configuration and control operations on Oracle Email services.

This command is used from within a command shell, such as /bin/csh on Unix systems, and provides a subset of the functionality available on Oracle Enterprise Manager pages for Oracle Email. For example, oesctl can be used by an administrator to start an Oracle Email IMAP4 server, but it cannot be used to modify IMAP service parameters.

Getting Usage Information

Without arguments, oesctl prints out the following usage information:

% oesctl 
oesctl  [ [<command>] [<target>|<instance>] ] 

Where commands can be any of the following:

Table 6-1

Command	Description
startup	Starts all the processes associated with the target or instance.
shutdown	Shuts down all the processes associated with the target or instance.
create instance	Creates an instance on a target.
delete instance	Creates an instance on a target.
refresh	Causes the target or instance to reload parameters from Oracle Internet Directory.
show targets	Displays a list of possible targets.
show status	Displays the status of the target.
show processes	Displays the status of the processes associated with the target.

OESCTL Syntax

The syntax of <target> is <host>:<installation>:<service>

<host> is the host name of the computer on which server processes run

<installation> is always um_system for the this release

<service> is one of the following: gc, list, smtp_in, smtp_out, imap, pop

The syntax of <instance> is <target>:<instance_id>

The meaning of the different service names are:

• gc: housekeeper service
• list: secure list service
• smtp_in: inbound SMTP service
• smtp_out: outbound SMTP service
• imap: IMAP service
• pop: POP service

<instance_id> is a number assigned to an instance when it is created. These numbers are selected automatically at instance creation time. Instance numbers cannot be configured by administrators.

Examples

The following examples are executed from a command shell running on a host named mail server.

OESCTL Configuration Operations

The configuration operations query or update the current configuration.

The query operations are:

% oesctl show targets 
% oesctl show processes <target> 
% oesctl create instance <target> 
% oesctl delete instance <target>

Getting the List of Available Targets

% oesctl show targets 
TARGET: mailserver:um_system:gc 
TARGET: mailserver:um_system:imap 
TARGET: mailserver:um_system:list 
TARGET: mailserver:um_system:pop 
TARGET: mailserver:um_system:smtp_in 
TARGET: mailserver:um_system:smtp_out

Getting the List of Process Instances for a Target

In the following examples, there is one process instance configured for the IMAP service running on the host mail server, and there are no process instances for the POP service. A service must have at least one process instance before it can be started. From the above example we know that the POP service cannot be started on the host mail server.

% oesctl show processes mailserver:um_system:imap 
mailserver:um_system:imap:101771055406040653 

% oesctl show processes mailserver:um_system:pop 
No processes for mailserver:um_system:pop

Creating a Process Instance

% oesctl show processes mailserver:um_system:gc 
No processes for mailserver:um_system:gc 

% oesctl create instance mailserver:um_system:gc 
Succesfully created a new instance for a total of: 1 

% oesctl show processes mailserver:um_system:gc
mailserver:um_system:gc:101778964029981136

The list of process instances for the target mailserver:um_system:gc was checked prior to instance creation, and it was empty. The create command was used to create a new process instance for the target, after which the process instance list was checked again and found to contain the new instance.

Deleting a Process Instance

% oesctl show processes mailserver:um_system:gc 
mailserver:um_system:gc:101778964029981136 

% oesctl delete instance mailserver:um_system:gc 
Succesfully deleted an instance for a total of: 0 

% oesctl show processes mailserver:um_system:gc 
No processes for mailserver:um_system:gc

The list of process instances for the target mail server: um_sytem: gc was checked prior to instance deletion. The delete command was used to delete the process instance found, after which the process instance list was checked again and found to contain no processes.

OESCTL Control Operations

The control operations display or alter the operational state of targets and instances.

The control operations are:

% oesctl show status <target> 
% oesctl startup <target> 
% oesctl startup <instance> 
% oesctl shutdown <target> 
% oesctl shutdown <instance> 
% oesctl refresh <target> 
% oesctl refresh <instance>

Starting and Stopping a Target

% oesctl show processes mailserver:um_system:gc 
mailserver:um_system:gc:101779027179112257 
mailserver:um_system:gc:101779029537864556 

% oesctl show status mailserver:um_system:gc 
mailserver:um_system:gc:101779027179112257 <stopped> 
mailserver:um_system:gc:101779029537864556 <stopped> 

% oesctl startup mailserver:um_system:gc 
ok 
ok 

% oesctl show status mailserver:um_system:gc 
mailserver:um_system:gc:101779027179112257 is alive. Message from console: null 
mailserver:um_system:gc:101779029537864556 is alive. Message from console: null 

% oesctl shutdown mailserver:um_system:gc 
mailserver:um_system:gc:101779027179112257 Housekeeper is terminated.  Message 
from console: null 
mailserver:um_system:gc:101779029537864556 Housekeeper is terminated.  Message 
from console: null 
% oesctl shutdown mailserver:um_system:gc 
No processes configured to be running for mailserver:um_system:gc

If oesctl is used to start a target, each configured process instance is started.

Starting and Stopping an Instance

% oesctl startup mailserver:um_system:gc:101779027179112257 
ok 

% oesctl show status mailserver:um_system:gc 
mailserver:um_system:gc:101779027179112257 is alive. Message from console: null 
mailserver:um_system:gc:101779029537864556 <stopped> 

% oesctl shutdown mailserver:um_system:gc:101779027179112257 
ok:Housekeeper is terminated.  Message from console: null

In some situations administrators may want to start or stop only a particular process instances. In this case, oesctl startup <instance> and oesctl shutdown <instance> are used.

Refreshing Targets and Instances

% oesctl refresh mailserver:um_system:gc:101779027179112257 
ok:is refreshed. Message from console: null 

% oesctl refresh mailserver:um_system:gc 
mailserver:um_system:gc:101779027179112257 is refreshed.  Message from console: 
null 
mailserver:um_system:gc:101779029537864556 is refreshed.  Message from console: 
null

Refreshing a process instance sends the instance a message to reload its process parameters from Oracle Internet Directory.

Refreshing a service target refreshes each started process instance.

The refresh functionality can be used to change a process parameter and have the change take effect without having to stop and restart running processes. For example, IMAP service log level can be changed in Oracle Internet Directory and refreshed without disconnecting any users that are currently connected to the IMAP service. Executing a shut down followed by a startup changes the logging behavior, and temporarily disconnect users.

OESMON

The oesmon command enables customers to obtain raw metric data from the Oracle Email server processes. The output of the oesmon command uses ASCII characters.

A metric is a string or a number. Every metric is associated with a managed object. Managed objects are associated with other managed objects in a parent-child relationship, forming a hierarchical tree structure of managed objects and metrics. The metrics are always leaves of the tree.

A numeric metric is a gauge or a counter. A gauge measures the current amount of an object and is characterized by a value going up and down. A counter measures an accumulated value and is characterized by the value remaining the same or becoming larger. If the value of a counter goes past the maximum supported number, the value wraps around to 0.

Handling of Units

The integer values tracked by numeric metrics measure quantities in some unit of measure. The unit of measure for a given metric is not maintained internally and is not printed out by the oesmon command. Instead, the units are defined by the server-specific product documentation.

See Also: Appendix A, "Server Statistics" for more information on server-specific statistics

Metric Names

All metrics and all managed objects have names that are case-sensitive and contain only alphanumeric characters, including the underscore character. A name cannot contain spaces or dot characters. The full name of object O is formed by connecting all the names along the path from the tree root to O. In this case, O may be a metric or a managed object.

For example:

.MTA is the full name of a managed object named MTA. It is at located directly under the root of the tree.

.MTA.connections is the full name of a managed object named connections that is a child of the MTA object.

.MTA.connections.out.current is the full name of a numeric metric that tracks the number of currently active outbound SMTP connections.

.MTA.connections.out.total is the full name of a metric that tracks the number of outbound SMTP connections created since startup.

Examples

Getting the Usage Message

Running oesmon without any arguments, it shows the command type:

Output

% oesmon 
Usage: oesmon targets | names <target> | get <target> <name> 

Getting the List of Available Service Targets

Command

oesmon targets 

Purpose

Shows all possible service targets that can be polled with oesmon:

Output:

% oesmon targets 
TARGET: mailserver:um_system:gc 
TARGET: mailserver:um_system:imap 
TARGET: mailserver:um_system:list 
TARGET: mailserver:um_system:pop 
TARGET: mailserver:um_system:smtp_in 
TARGET: mailserver:um_system:smtp_out 

Showing Metric Names for a Given Service Target

Command

oesmon names mailserver:um_system:smtp_in 

Purpose

This command queries each process instance for the metric names it currently has defined.

Output

% oesmon names mailserver:um_system:smtp_in 
.DUMP.OIDStatus.Connection 
.DUMP.Threads.dump 
.ES_SPS.socket.currload 
.ES_SPS.socket.sockmax 
.ES_SPS.thread.currthreads 
.ES_SPS.thread.thrmax 
.MTA.uptime 
.MTA.connections.in.current 
.MTA.connections.in.total 
.MTA.msgs.deferred.current 
.MTA.msgs.deferred.total 
.MTA.receive.kbytes 
.MTA.receive.messages 
.MTA.receive.recipients 
.MTA.receive.time 
.MTA.transmit.bytes 
.MTA.transmit.bytes_local 
.MTA.transmit.messages 
.MTA.transmit.messages_local 
.MTA.transmit.recipients 
.MTA.transmit.recipients_local 
.um.admin.os_pid 
.um.admin.uptime 

The oesmon names mailserver:um_system:imap command contacts each process instance that belongs to the service mailserver:um_system:imap and determines which metrics are currently defined for the process.

Many metrics are defined as soon as the process starts up, but some are created dynamically during operation, and are not available at all times. Therefore, the output from using the oesmon names command does not always give the same list of metric names. For example, an IMAP server process does not have any metrics available about particular user until that user logs in at least one time.

Querying a Metric Value from a Running Server

Command

oesmon get mailserver:um_system:smtp_in.MTA.connections.in.total

Purpose

This command queries each SMTP in-bound process to find out how many connections it has accepted.

Output

% oesmon get mailserver:um_system:smtp_in .MTA.connections.in.total 
.MTA.connections.in.total = 352 
.MTA.connections.in.total = 0 

The output can determine that the smpt_in service for mailserver: um_system has two process instances configured and running. The first process has received 352 connections and the second has not received any.

The metric given to the command was the complete name of a single metric. It is possible to retrieve values for all metrics associated with a managed object, as is shown in the following example.

Query Multiple Related Metrics for a Managed Object

Command

oesmon get mailserver:um_system:smtp_in .MTA.transmit 

Purpose

This command queries in-bound SMTP processes to find out transmission metrics.

Output

% oesmon get mailserver:um_system:smtp_in .MTA.transmit 
.MTA.transmit.bytes = 3282806 
.MTA.transmit.bytes_local = 3282806 
.MTA.transmit.messages = 330 
.MTA.transmit.messages_local = 330 
.MTA.transmit.recipients = 698 
.MTA.transmit.recipients_local = 698 
.MTA.transmit: metric not found 

The name.MTA.transmit is the name of a managed object, not a metric. In this case, oesmon returns all metrics and children managed objects associated with.MTA.transmit.

The output can determine that the smpt_in service for mail server: um_system has two process instances configured and running. The first process has transmitted a number of e-mail messages, and the second process has not transmitted any.

Error Output

The oesmon command returns error results if a metric cannot be found or if a process instance cannot be contacted.

Example of output for undefined metric:

% oesmon get mailserver:um_system:smtp_in .nosuchmetric 
.nosuchmetric: metric not found 

Example of output for process that does not respond:

% oesmon get mailserver:um_system:smtp_in .MTA.connections.in.total 
<no response> 

OESUCR

The oesucr command does the following:

• Creates and deletes Oracle Email users
• Changes e-mail addresses
• Specifies a real domain for users
• Supports different character encoding types
• Creates users directly through command line

OESUCR takes a file as an input. For user creation, the file should contain a list of records, separated by an empty line. Each record contains information above a user to be created. Each line in a record is a name-value pair for an attribute for the e-mail user in the directory. Each record must have at least three mandatory attributes

• mail
• orclmailquota
• baseuserdn

For user deletion, the file should contain one line listing all the users to be deleted, separated by a comma.

This command only creates and deletes e-mail users, not corresponding public users. For user creation, the public users must exist prior to creating the corresponding e-mail users. For user deletion, after running the tool, the users are no longer valid e-mail users, but they are still users in the directory.

Usage

% oesucr <file> [-v] [-d]

<file> is the path to the file containing the user records of the users to be created or the list of users to be deleted.

The -v flag prints out debug messages. The -d flag deletes users. -v and -d can be used together.

oesucr <filename> -change

<filename> is a text file with the following format:

<old email address1>=<new email address1>

For example:

[e-mail]=[e-mail]
 

After running the command, [e-mail] becomes [e-mail].

esucr <filename> -encoding=UTF-8

The file is read as UTF-8. The file must be saved in the corresponding encoding.

Examples

Creating Users

The example file user_file contains the following records:

mail=[e-mail] 
orclmailquota=400000000 
baseuserdn=cn=testuser1,cn=users,o=oracle,dc=com 

mail=[e-mail] 
orclmailquota=400000000 
baseuserdn=cn=testuser2,cn=users,o=oracle,dc=com

Running the % oesucr user_file creates two e-mail users called testuser1 and testuser2. Each record in the file contains only the three mandatory attributes.

Note: : The corresponding public users must exist before running the OESUCR.

Creating Users with Optional Attributes

For a file user_file containing the following records:

mail=[e-mail] 
orclmailquota=400000000 
userpassword=welcome 
orclMailDomainControlAci=domain

mail=[e-mail]
orclmailquota=400000000
baseuserdn=cn=testuser2,cn=users,o=oracle,dc=com 

Running % oesucr user_file creates two-e-mail users called testuser1 and testuser2. The role of the first user is set to domain administrator.

Deleting Users

The example file user_file contains the following line:

mail=[e-mail],[e-mail],[e-mail]

Running % oesucr user_file -d deletes the e-mail users: [e-mail], [e-mail], and [e-mail].

Note:: Corresponding public users are not deleted by OESUCR

Creating a User Through Command Line

The following is an example of how to create a user through command line, with out creating a new file. Only one user can be created at a time:

oesucr -cmd mail=[e-mail]  
baseuserdn=cn=user1,cn=users,dc=us,dc=acme,dc=com orclmailquota=400000000 <other 
optional attributes>

All parameters are separated by a space and have the same names as those used in the file. All mandatory attributes must be specified, and can take any valid optional attributes.

Specifying a Real Domain for Users

The following is an example of how to specify a real domain for users:

mail=[e-mail]
realdomain=acme.com
baseuserdn=......
orclmailquota=......

The e-mail address of the user becomes [e-mail], in Oracle Internet Directory, company1.com may not exist, because the user is created under acme.com

OESDL

OESDL is the command line tool for adding users to and removing users from distribution lists.

The oesdl tool takes a file as an input. The file should contain a list of records, separated by an empty line. Each record contains information to manipulate one distribution list. Each record must have the name of the list and a list of users.

For adding users to a list, the user type must be indicated. A regular user , a distribution list, an alias, or a foreign user to a distribution list can be added.

When adding users to a list, you can create the list at the same time if it does not exist. To create a new list, the owner must be specified.

Usage

% oesdl <file> [-v]

<file> is the path to [-v] the file containing the list records.

The -v flag prints out debug messages.

Examples

Adding Users to a Lists

The example file list_file contain the following records:

listname=[e-mail] 
action=add 
newlist=n 
usertype=U 
users=[e-mail],[e-mail],[e-mail] 

listname=[e-mail] 
action=add 
newlist=n 
usertype=L 
users=[e-mail] 

Running % oesdl list_file adds user1, user2, and user3 to [e-mail], list1 must already exist. It also adds [e-mail] to another list called [e-mail].

The usertype can be one of the following:

• U for regular user
• F for foreign user
• L for a distribution list
• A for an alias

Adding Users to a New List

The example file list_file contains the following records:

listname=[e-mail] 
action=add 
newlist=y 
owner=[e-mail] 
usertype=U 
users=[e-mail],[e-mail] 

Running % oesdl list_file, creates a new list called [e-mail], set its owner to [e-mail], and then adds users: [e-mail], and [e-mail] to the new list.

Removing Users from a Distribution List

The example file user_file contains the following lines:

listname=[e-mail] 
action=delete 
usertype=U 
users=[e-mail],[e-mail] 

listname=[e-mail] 
action=add 
newlist=y 
owner=[e-mail] 
usertype=U 
users=[e-mail],[e-mail] 

Running % oesdl list_file removes user1 and user2 from [e-mail]. It then creates a new list called list2, sets the owner [e-mail], and then add user1, and user2 to the new list [e-mail].

OESRL

The oesrl command enables administrators to create and manage server side rules from a command line.

oesrl can create server side rules specified in a text file or list server side rules to the standard output. When creating rules, two formats of text file are accepted, the Java properties file format and the XML format. When listing rules, only the XML format is listed.

Usage

% oesrl
Usage: oesrl [-c <file> | -x <file> | -p <ruleowner>]

-c <file>: create rules based on property <file>.

-x <file>: creates rules based on XML <file>.

-p <ruleowner>: prints <ruleowner> rules in XML.

File Formats

Property file

Property files are text files with name-value pairs. Names can be organized hierarchically and separated by periods. The following are the top-level property names used in the file:

• Ruleowner: The qualified name of the rule owner. If the rules are owned by a user, it is the user's e-mail address. If the rules are domain specific, the rule owner should be a domain name such as acme.com. If the rules are system wide, the rule owner is the system installation name stored in Oracle Internet Directory. One file can contain only rule owner.
• Ruletype: Describes the rule owner types. The rule types are:
  • User
  • Domain
  • System
• Debug: If this parameter is set to true, the oesrl utility prints out debugging messages. This property is optional.
• Event#: There are up to six distinct events that can be defined in this file. Each event can only appear once. The events defined should have a sequence number starting from 1, such as event1. The events are:
  • Relay
  • Reception
  • Deliver
  • Copy
  • Flag change
  • Expunge

Under each event, one can define unlimited number of rules using property name <eventname>.rule#, where <eventname> is one of the six events and # is a sequence number starting from 1. For example, the property deliver.rule1 defines the name of the first rule under the deliver event. All attributes of this rule can be further defined under the prefix deliver.rule1.

Under each rule, one can define actions and their parameters. Often times rules come with conditions that need to be defined. The following is a list of property names corresponding to each rule attribute:

Note: # means it can be replaced by a sequence number starting from 1.

• <eventname>.rule#.action#: the sequence of actions that can be defined under <eventname>.rule#.

  The choices of values are listed in Oracle Email Java API documentation under Java class CommandType.

• <eventname>.rule#.action#.param#: the parameter sequence needed for the action <eventname>.rule#.action#.
• <eventname>.rule#.active: an optional property that can be set to true or false indicating whether <eventname>.rule# is active.
• <eventname>.rule#.attr#, <eventname>.rule#.op#, <eventname>.rule#.operand#: together they represent a condition associated with the rule <eventname>.rule# as long the same sequence number is used.

  The choices of values for <eventname>.rule#.attr# are listed in Oracle Email Java API documentation under Java class AttributeType. The choices of values for <eventname>.rule#.op# are listed in Oracle Email Java API documentation under Java class OperatorType.

• <eventname>.rule#.negate#: an optional property value that can be set to true or false, indicating whether the condition number should be negated
• <eventname>.rule#.param#: in case when <eventname>.rule#.attr# requires a parameter (such as xheader), use this property to specify the parameter value.
• <eventname>.rule#.case#: an optional property value that can be set to true or false, indicating whether <eventname>.rule#.op# is case sensitive .
• <eventname>.rule#.cond: if multiple conditions are needed, use this property to specify whether and or or should be used to combine the conditions.

  Oracle Corporation recommends listing rule properties in order, so that readability of the property file is maximized. When running the oesrl utility, listing rule properties in order is not required.

XML

XML is used as the storage format of server side rules. An XML rule representation can be created directly and oesrl can be used to load the rules into the system. The XML file specified needs to a valid XML file according to the rules XML schema. To obtain the XML schema for rules, extract the schema file oracle/mail/sdk/rule/mail_rule.xsd from the Java SDK library esmail_sdk.jar under $ORACLE_HOME/jlib.

Examples

Creating User Rules Using Property File Input

This example demonstrates how to use property files to specify rules for a user, and how to use the oesrl utility to save the rules.

% cat > rules.properties
ruleowner=[e-mail]
ruletype=user
event1=deliver
deliver.rule1=Moving private messages
deliver.rule1.cond=or
deliver.rule1.attr1=rfc822to
deliver.rule1.op1=contains
deliver.rule1.operand1=[e-mail]
deliver.rule1.attr2=rfc822cc
deliver.rule1.op2=contains
deliver.rule1.operand2=[e-mail]
deliver.rule1.action1=moveto
deliver.rule1.action1.param1=/user1/Private
^D

% oesrl -c rules.properties

Creating User Rules Using XML File Input

This example demonstrates how to use XML files to specify rules for a user, and how to use the oesrl utility to save the rules.

% cat > rules.xml
<account qualifiedName=[e-mail]>
 <rulelist event=deliver>
  <rule description=Moving private messages>
   <condition junction=or>
   <condition>
    <attribute tag=rfc822to/>
    <operator op=contains/>
    <operand>[e-mail]</operand>
   </condition>
   <condition>
    <attribute tag=rfc822cc/>
    <operator op=contains/>
    <operand>[e-mail]</operand>
   </condition>
   </condition>
   <action>
    <command tag=moveto/>
    <parameter>/user1/Private</parameter>
   </action>
  </rule>
 </rulelist>
</account>
^D

% oesrl -x rules.xml

Retrieving Rules

This example demonstrates how to use list rules for a user in XML format.

% oesrl -p [e-mail]
<account qualifiedName=[e-mail]>
 <rulelist event=deliver>
  <rule description=Moving private messages>
   <condition junction=or>
   <condition>
    <attribute tag=rfc822to/>
    <operator op=contains/>
    <operand>[e-mail]</operand>
   </condition>
   <condition>
    <attribute tag=rfc822cc/>
    <operator op=contains/>
    <operand>[e-mail]</operand>
   </condition>
   </condition>
   <action>
    <command tag=moveto/>
    <parameter>/user1/Private</parameter>
   </action>
  </rule>
 </rulelist>
</account>

OESCHART

OESCHART is a charting utility that enables administrators to create graphs illustrating the system's current load and performance. Upon invocation it reads the values necessary in the .ini file to connect to an Oracle database, query the mail statistics tables, and then creates an image file. Other metrics plug into one of the standard display types, such as showing the rate or current values. The images are only created when the program is run, therefore to have dynamically updated charts administrators need to schedule periodic invocations of the program, such as with cron on UNIX systems or WinAT for Windows or as a DBMS job.

Usage

oeschart <property file>

File Formats

Mechanism

When a mail process starts up and is retrieving runtime attributes from Oracle Internet Directory there is an attribute <attribute name> that specifies how often the process should place statistics in the repository database.

When the processes startup they initialize a number of counters to zero and update these internal counters every time an associated operation is performed. There is a separate thread which keeps track of these counters and inserts them into the statistics database at the time interval specified in the Oracle Internet Directory. All of the counters held in the e-mail server processes are started up and are not reset. Because the processes keep track only of counters, the memory over head is minimal.

To disable the insertion of statistics, the insert period should be set to zero seconds. For the processing servers, the collection of statistics is a relatively light operation in terms of CPU and memory consumption.

Schema

The data is held in a small number of tables, with one view that summerizes the data. Administrators of this component should query the tables directly after a few processes have entered their initial data. OESChart is only one mechanism of mining this data. For more specific information, administrators should query the schema.

There is no automated clean up functionality. The tables grow until historical folders are deleted or exported . It is important to occasionally monitor the esperftbl tablespace.

es_perf_process

Name	Value	Description
process_id	Number not null	An internal assigned unique number for each process.
process_dn	Varchar2 (500)	The dn of the process in Oracle Internet Directory

es_perf_metric

Name	Value	Description
metric_id	Not Null	An internal assigned unique number for each metric.
metric_name	Varchar2 (100)	The name of the metric.
metric_type	Not Null

es_perf_timestamp

Name	Description
timestamp_id	An internal assigned unique number for each time period that a process inseted int statistics time stamp.
Date	The time the data was inserted.

es_perf_sample

Name	Value	Description
process_id	Number not null	S.A.
metric_id	Varchar2 (100)	S.A.
timestamp_id	Number not null	S.A.
nvalue	Number	The numberical value of the metric (if the metric is numeric)
Svalue	Varchar2 (1000)	The String value of the metric (if the metric is a string)

es_perf_data

Name	Value
es_perf_data	(view)
process_dn	Varchar2 (500)
metric_name	Varchar2 (100)
metric_type	Number not null
timestamp	Date
nvalue	Number not null
Svalue	Varchar2 (1000)

Graph Styles

The oeschart utility enables four types of graphs to bespecified , three are variations on a xy scatter graph and the fourth is a bar chart illustrating IMAP command statistics.

xy_current

This charts whatever current value was entered in the database, there is no data manipulation done on the entries. It should be used on metrics such as, .ES_SPS.socket.currload which is a point in time metric.

xy_rate

This chart calculates the difference between two data points and divides the resulting value by the time differencee, which gives the rate of the transaction. All times are standardized on seconds. The graphed value becomes Y transactions per second, such as in the metric .ESPROTO.transmit.bytes. And by using the xy_rate graph displays the outgoing number of transmitted bytes per second.

xy_cummulative

This chart illustrates the total amount of work performed in a given period and shows the cumulative counters for a metric, while taking into account process restarts. This only works on metrics that are cumulative counters. It does take into account additional processes that were added or deleted, and any process restarts.

Mandatory Entries

The .ini file specifies all the necessary information to create the charts. The following tables describe mandatatory entries and optional values:

Table 6-2

Parameter	Description
Server	The database host name containing the statistics
port	The listener port for that database
sid	The sid or service name for that server.
username	Username to access the account
password	Password for that account
process_dn	The query used to gather statistics, such as process_dn='%<value in ini file>% used to retrieve all processes that follow this dn pattern. This enables administrators to graph a specific process, a set of processes, or the entire system by specifying the level of detail entered for this parameter.
metric_name	The metric to query.
graph_type	Possible values are xy and bar
Image_file_name	The name of the file to be generated
image_title	The title to display on the graph.
number_of_hours	Specifies the number of hours since the present to graph.

Optional Parameters

Table 6-3

Parameter	Default	Description
encode_type	gif	Possible values are gif & png
image_dir	./
aggregate_time_period	600	This is the time span in which multiple processes logging will be grouped together and the metrics combined to show the aggregate value. For example, suppose we had 2 IMAP servers running, IMAP1 & IMAP2. IMAP1 logged its statistics at 3:00pm and IMAP2 at 3:02 pm. (The servers log their statistics every x seconds (specified in ldap) relative to when they started, so in this case, IMAP2 must have been started 2 minutes after IMAP1) When showing the total number of sockets on the system we need to combine the values from IMAP1 and IMAP2. The aggregate_time_period metric defines what is an acceptable window for different processes statistics to be combined. This should be the same as the submit period specified in LDAP for this process type.
max_lifetime	300	The number of seconds until the program terminates.
show_statistics	FALSE	Displays at the bottom of the graph the number of data points, the min, max, average, meadian, stddev and 95%
debug	FALSE	Provides a detailed output of the utility.

Examples

.ini File

The following is an example of the .ini file that graphs the number of sockets connected to an IMAP server.

server=testdb.us.oracle.com
sid=test 
port=1521
username=es_mail
password=es
process_dn=test1:um_system:imap:
metric_name=.ES_SPS.socket.currload
graph_type=xy_current
image_file_name=socketcount
image_title=Socket count on test1 
image_dir=./
number_of_hours=24

encode_type=png
show_statistics=true
aggregate_time_period=600
debug=false
max_lifetime=120

Selecting Graphs to Display in Oracle Enterprise Manager

Administrators can schedule graphs illustrating information to be created and placed in their own custom HTML page or in the Oracle Enterprise Manager, such as the number of connected sockets, the response time to log in, and the number of queued outbound messages.

Displaying Graphs into Oracle Enterprise Manager

Perform the following steps to display graphics in Oracle Enterprise Manager:

1. Modify target metadata definition

Under the $ORACLE_HOME/emdw/sysman/admin/metadata directory is a list of target metadata definition files. For a particular target definition, the following elements must be added under the <InstanceProperties> section:

      <!--This property specifies the total number of statistic charts to be 
displayed -->
      <InstanceProperty NAME="totalNumberOfStats" CREDENTIAL="FALSE"
       OPTIONAL="TRUE">
         <Display>
            <Label NLSID="totalnumberofstats">Total Number of Statistics</Label>
         </Display>
      </InstanceProperty>

     <!--This property specifies the header title for the first charting picture 
-->
      <InstanceProperty NAME="Title0" CREDENTIAL="FALSE"
       OPTIONAL="TRUE">
         <Display>
            <Label NLSID="stat0">Statistic Number 0</Label>
         </Display>
      </InstanceProperty>

     <!--This property specifies the tool tips string for the first charting 
picture, coded to Section 508 standards-->
      <InstanceProperty NAME="ToolTips0" CREDENTIAL="FALSE"
       OPTIONAL="TRUE">
         <Display>
            <Label NLSID="tooltips0">This is tooltips 0 for ADA</Label>
         </Display>
      </InstanceProperty>

     <!--This property specifies the relative picture path under the servlet for 
the first charting pictyre.-->
      <InstanceProperty NAME="PicPath0" CREDENTIAL="FALSE"
       OPTIONAL="TRUE">
         <Display>
            <Label NLSID="picpath0">Picture Path 0</Label>
         </Display>
      </InstanceProperty>

     <!--This property specifies the physical path for the first charting 
picture. The admin code will test if the file exists according to the path 
below-->
      <InstanceProperty NAME="PicPhysicalPath0" CREDENTIAL="FALSE"
       OPTIONAL="TRUE">
         <Display>
            <Label NLSID="picphysicalpath0">Picture Physical Path 0</Label>
         </Display>
      </InstanceProperty>

To increase the number of charts displayed, the property value of <totalNumberOfStats> must to be changed accordingly under the targets.xml file and the addition picture properties must be defined under the naming standard:

Title[N], ToolTips[N], PicPath[N], PicPhysicalPath[N]

Where N is a non negative natural number.

2. Modify targets.xml file to specify the property instance values.
3. Add the following property to the specific target section, under the $ORACLE_HOME/emdw/sysman/emd/targets.xml:

     <Property NAME="totalNumberOfStats" VALUE="1"/>
     <Property NAME="ToolTips0" VALUE="My First Statistic Tool Tips"/>
     <Property NAME="PicPhysicalPath0" 
   VALUE="<...>/sysman/webapps/emd/ias/umsg/es/images/pic1.gif"/>
     <Property NAME="PicPath0" VALUE="/emd/ias/umsg/es/images/pic1.gif"/>
     <Property NAME="Title0" VALUE="My First Statistic Header"/>
   
   

If any of the following situations occur, the charting picture is skipped and not displayed on Oracle Enterprise Manager.

• totalNumberOfStats is missing, zero, or ,not a number
• Title[N] is missing for the particular chart
• ToolTips[N] is missing for the particular chart
• PicPath[N] is missing for the particular chart
• PicPhysicalPath[N] is missing for the particular chart
• The chart picture file specified under PicPhysicalPath[N] does not exist.