10 Managing the Control Center Agent

This section describes how to start and stop the Control Center Agent (CCA), and how to administer it using the cca_admin utility. The CCA manages deployment and execution of the mappings that are based on Code Templates. CCA is not part of the Control Center service hosted within the Oracle Database.

This section contains the following topics:

"Starting and Stopping the Control Center Agent"
"About the cca_admin Utility"
"Starting the cca_admin Utility"
"cca_admin Commands"

Starting and Stopping the Control Center Agent

This section describes how to start and stop the CCA.

When you invoke the ccastart for the first time, it prompts you to enter a password for the OC4J administrator account. The default user name for this account is oc4jadmin.

To start the CCA:

On UNIX, in the directory OWB_HOME /owb/bin/unix/, run the script ccastart.
On Windows, in the directory OWB_HOME\owb\bin\win32\, run the script ccastart.bat.

To stop the CCA:

On UNIX, in the directory OWB_HOME /owb/bin/unix/, run the script ccashut. This script accepts an optional argument password..
On Windows, in the directory OWB_HOME\owb\bin\win32\, run the script ccashut.bat. This script accepts an optional argument password.

For a representation of architectural structures of this installation, see Figure 1-5, "Control Center Agent Topology".

For procedures that modify installation defaults, see Chapter 7, "Configuring Repository Browser, Control Center Agent, and Other Components".

About the cca_admin Utility

The cca_admin utility changes Control Center Agent settings dynamically, without the requirement to shut down and subsequently restart the run-time environment. cca_admin commands retrieve the values of various environment attributes, set these to new values, and invoke the operations of JRTAdministratorMBean, introduced in section "JRTAdministratorMBean".

The typical cca_admin session includes the following steps:

Running the cca_admin script, as described in "Starting the cca_admin Utility".
Connecting to an MBeanServer using the connect command described in "connect".
Issuing one or more commands to view or update run-time environment attributes or invoke cca_admin commands described in "cca_admin Commands".
Disconnecting from the server using the command "disconnect" or the command "exit".

Starting the cca_admin Utility

The cca_admin tool is delivered as a shell script on Linux or a batch file on Windows.

On UNIX, use the following command:

OWB_HOME /owb/bin/unix/cca_admin
On Windows, use the following command:

OWB_HOME\owb\bin\win32\cca_admin.bat.

Before activating the JRTAdministratorMBean, your can use only the basic commands: help, connect, disconnect, and exit. The full range of commands is available after you connect to an MBean server and start using the JRTAdministratorMBean.

cca_admin Commands

This section provides a complete list of the cca_admin commands as follows:

"cleanUpJobLogFilesForGivenTimeInterval"
"cleanUpNLeastRecentJobLogFiles"
"connect"
"disconnect"
"exit"
"getCacheJobStatusSize"
"getCacheLogNo"
"getKmPermissionsFile"
"getLogRoot"
"getMaxAbortTimeout"
"getMaxRuntimeFileSizeMB"
"getMaxRuntimeLogSizeMB"
"getRuntimeLogEncoding"
"getRuntimeLogFileLocation"
"getRuntimeLogLevel"
"help"
"isKmSecurityNeeded"
"isLogToAuditTable"
"isLogToOdl"
"isShowRuntimeLoggerLogHostAddr"
"isShowRuntimeLoggerLogHostId"
"isShowRuntimeLoggerLogMsgClassPath"
"isShowRuntimeLoggerLogMsgLogLevel"
"isShowRuntimeLoggerLogUserId"
"readSettings"
"reset"
"setCacheJobStatusSize"
"setCacheLogNo"
"setKmPermissionsFile"
"setKmSecurityNeeded"
"setLogRoot"
"setLogToAuditTable"
"setLogToOdl"
"setRuntimeLogEncoding"
"setMaxAbortTimeout"
"setMaxRuntimeFileSizeMB"
"setMaxRuntimeLogSizeMB"
"setRuntimeLogLevel"
"setShowRuntimeLoggerLogHostAddr"
"setShowRuntimeLoggerLogHostId"
"setShowRuntimeLoggerLogMsgClassPath"
"setShowRuntimeLoggerLogMsgLogLevel"
"setShowRuntimeLoggerLogUserId"
"settingsToString"
"showAllJobLogFiles"

cleanUpJobLogFilesForGivenTimeInterval

This command removes all log files that were modified during the specified time range, between startDate and endDate, and returns the total number of files removed. Both parameters are expressed in the format DD-MM-YYYY HH:MM:SS. If the specified startDate is null, no records are deleted. If endDate is null, all log files created after the startDate are purged.

Example 10-1 Using cleanUpJobLogFilesForGivenTimeInterval Command

cleanUpJobLogFilesForGivenTimeInterval 26-12-2008 13:38:56 12-01-2009 22:15:58

cleanUpNLeastRecentJobLogFiles

This command removes the specified number n, of least recent log files from the system, and returns the number of job log files that are actually removed.

Example 10-2 Using cleanUpNLeastRecentJobLogFiles command

cleanUpNLeastRecentJobLogFiles 10

connect

This command connects the user to MBean server.

The command is of the following form, where host is the computer on which the CCA is located, port is the port number for accessing the CCA, user is the user name for accessing the CCA, password is that user's password, connection_type is one of RMI, OPMN, RMIS, OPMN_RMIS, OPMN_CLUSTER, or OPMN_CLUSTER_RMIS, application_name is the name of the application deployed to OC4J, and instance is the OC4J process that contains the CCA application:

connect host port user password connection_type application_name instance

Example 10-3 Using connect Command

connect localhost 23791 oc4jadmin welcome rmi jrt host

disconnect

This command disconnects the user from the MBean server.

Example 10-4 Using disconnect Command

disconnect

exit

This command exits the cca_admin shell when it is running in the interactive mode. If the connection to the MBean server is not closed, it first disconnects and then exits cca_admin shell.

Example 10-5 Using exit Command

exit

getCacheJobStatusSize

This command returns a value for the number (integer) MBean attribute CacheJobStatusSize, which controls the maximum number of the job status logs that can be stored by the in-memory job log cache in CCA. The attribute's value is in the range of 1 and 10000, with the default value of 3000.

Example 10-6 Using getCacheJobStatusSize Command

getCacheJobStatusSize 3000

getCacheLogNo

This command returns the value of MBean attribute CacheLogNo, which controls the maximum number of job logs that can be stored by the in-memory job log cache in CCA. Obviously the bigger this number is the more memory CCA takes up. The attribute's value is in the range of 1 and 100, with the default value of 10.

Example 10-7 Using getCacheLogNo Command

getCacheLogNo

getKmPermissionsFile

This command returns the value of MBean attribute KmPermissionsFile, which is the file system path to the ct_permissions.properties file. If this parameter is set to true, the CCA checks ct_permissions.properties to determine what system commands may be executed. This path may be either absolute or relative. The relative value refers to the $OC4J_HOME/j2ee/home directory. The default value is config/ct_permissions.properties.

Example 10-8 Using getKmPermissionsFile Command

getKmPermissionsFile

getLogRoot

This command returns the value of MBean attribute LogRoot, which is the directory that stores the CCA job log file. The attribute value may be either absolute or relative. The relative value refers to $OC4J_HOME/j2ee/home directory; the default value is $OC4J_HOME/j2ee/home/log.

Example 10-9 Using getLogRoot Command

getLogRoot

getMaxAbortTimeout

Returns the value of MBean attribute MaxAbortTimeout, the maximum amount of wait time in seconds before the execution is aborted. The attribute's value is in the range of 1 to 60; and the default value is 60.

Example 10-10 Using getMaxAbortTimeout Command

getMaxAbortTimeout

getMaxRuntimeFileSizeMB

This command returns the value of MBean attribute MaxRuntimeFileSizeMB, the maximum size of any log file, in MB. When a log file exceeds this limit, it is closed and a new log file is opened. The attribute's value is in the range of 1 MB to 15 MB, and the default value is 3 MB.

Example 10-11 Using getMaxRuntimeFileSizeMB Command

getMaxRuntimeFileSizeMB

getMaxRuntimeLogSizeMB

This command returns the value of MBean attribute MaxRuntimeLogSizeMB, the maximum size of the log file directory, in MB. When the directory exceeds this limit, log files are purged, starting with the oldest. The attribute's value is in the range of 1 MB to 20 MB, and the default value is 10 MB.

Example 10-12 Using getMaxRuntimeLogSizeMB Command

getMaxRuntimeLogSizeMB

getRuntimeLogEncoding

This command returns the value of MBean attribute RuntimeLogEncoding, which specifies the character encoding of the log file. The default value is UTF-8.

Example 10-13 Using getRuntimeLogEncoding Command

getRuntimeLogEncoding

getRuntimeLogFileLocation

This command returns the value of MBean attribute RuntimeLogFileLocation, the name of CCA job log file, a read-only attribute. This value is $OC4J_HOME/j2ee/home/log/appName.log, where appName is the name of the CCA application.

Example 10-14 Using getRuntimeLogFileLocation Command

getRuntimeLogFileLocation

getRuntimeLogLevel

This application returns the value of MBean attribute RuntimeLogLevel, the log level for run-time logger. The legal values for this attribute are: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL (default).

Example 10-15 Using getRuntimeLogLevel Command

getRuntimeLogLevel

help

This command returns help information for a specified valid command; if a command is not specified, it returns the list of valid commands.

Example 10-16 Using help Command

help
help isLogToOdl

isKmSecurityNeeded

This command returns the value of MBean attribute KmSecurityNeeded, determining whether security is enforced on system commands that are invoked by CCA script. If the value is true (which is the default), CCA checks the ct_permissions.properties file for allowable system commands, and only execute the commands defined in ALLOWED_CMD. If the value is false, CCA executes all system commands.

Example 10-17 Using isKmSecurityNeeded Command

isKmSecurityNeeded

isLogToAuditTable

This command returns the value of MBean attribute LogToAuditTable, which turns audit table logging on and off. Audit table logging is only effective for execution job logs. The attribute value is either true or false.

Example 10-18 Using isLogToAuditTable Command

isLogToAuditTable

isLogToOdl

This command returns the value of MBean attribute LogToOdl, which turns ODL logging on and off. Only effective for execution job logs. Deployment and Web service logs are always created in the ODL log format, regardless of the value of this setting. The attribute value is either true or false.

Example 10-19 Using isLogToOdl Command

isLogToOdl

isShowRuntimeLoggerLogHostAddr

This command returns the value of MBean attribute ShowRuntimeLoggerLogHostAddr, which determines whether the IP address of the host that is running CCA is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-20 Using isShowRuntimeLoggerLogHostAddr Command

isShowRuntimeLoggerLogHostAddr

isShowRuntimeLoggerLogHostId

This command returns the value of MBean attribute ShowRuntimeLoggerLogHostId, which determines whether the ID of the host that is running CCA is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-21 Using isShowRuntimeLoggerLogHostId Command

isShowRuntimeLoggerLogHostId

isShowRuntimeLoggerLogMsgClassPath

This command returns the value of MBean attribute ShowRuntimeLoggerLogMsgClassPath, which determines whether the path of the class where the message is logged is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-22 Using isShowRuntimeLoggerLogMsgClassPath Command

isShowRuntimeLoggerLogMsgClassPath

isShowRuntimeLoggerLogMsgLogLevel

This command returns the value of MBean attribute ShowRuntimeLoggerLogMsgLogLevel, which determines whether the log level of the log message is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-23 Using isShowRuntimeLoggerLogMsgLogLevel Command

isShowRuntimeLoggerLogMsgLogLevel

isShowRuntimeLoggerLogUserId

This command returns the value of MBean attribute ShowRuntimeLoggerLogUserId, which determines whether the ID of the user is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-24 Using isShowRuntimeLoggerLogUserId Command

isShowRuntimeLoggerLogUserId

readSettings

This command reads CCA settings from the CCA configuration file.

Example 10-25 Using readSettings Command

readSettings

reset

This command resets attributes to their default values, if the attributes are defined to have defaults.

Example 10-26 Using reset Command

reset

setCacheJobStatusSize

This command sets the value for MBean attribute CacheJobStatusSize, which controls the maximum number of the job status that can be stored in the in-memory job log cache in CCACCA. The attribute's value is an integer in the range of 1 to 10000; the default value is 3000.

Example 10-27 Using setCacheJobStatusSize Command

setCacheJobStatusSize 3000

setCacheLogNo

This command sets a value for MBean attribute CacheLogNo, which controls the maximum number of job logs that can be stored in the in-memory job log cache in CCA. The attribute's value is an integer in the range of 1 and 100; the default value is 10.

Example 10-28 Using setCacheLogNo Command

setCacheLogNo 10

setKmPermissionsFile

This command sets the value for MBean attribute KmPermissionsFile, which is the file system path to the ct_permissions.properties file. If the value is set to true, the CCA checks the file to determine what system commands may run. The path can be either absolute or relative. The relative refers to $OC4J_HOME/j2ee/home directory; the default value is config/ct_permissions.properties.

Example 10-29 Using setKmPermissionsFile Command

setKmPermissionsFile $OC4J_HOME/j2ee/home/config/ct_permissions.properties

setKmSecurityNeeded

This command sets a value for MBean attribute KmSecurityNeeded, which determines whether security is enforced on system commands invoked from CCA scripts. When the value is true (default), CCA checks the ct_permissions.properties file for system commands that may run, and only execute the ones defined in ALLOWED_CMD. When the value is false, CCA runs all system commands.

Example 10-30 Using setKmSecurityNeeded Command

setKmSecurityNeeded true
setKmSecurityNeeded false

setLogRoot

This command sets the value of MBean attribute LogRoot, the directory of the CCA job log file. The attribute's value may be either absolute or relative. The relative value refers to $OC4J_HOME/j2ee/home directory; the default value is $OC4J_HOME/j2ee/home/log.

Example 10-31 Using setLogRoot Command

setLogRoot $OC4J_HOME/j2ee/home/log

setLogToAuditTable

This command sets the value for MBean attribute LogToAuditTable, which turns audit table logging on and off. Audit table logging is only effective for execution job logs. The attribute's value is true or false.

Example 10-32 Using setLogToAuditTable Command

setLogToAuditTable true
setLogToAuditTable false

setLogToOdl

This command sets the value for MBean attribute LogToOdl, which turns ODL logging on and off. This is only effective for execution job logs; deployment and Web service logs are created in ODL log format regardless of this setting. The attribute's value is true or false.

Example 10-33 Using setLogToOdl Command

setLogToOdl true
setLogToOdl false

setMaxAbortTimeout

This command sets the value for MBean attribute MaxAbortTimeout, the maximum wait time (in seconds) before aborting the execution. The attribute's value is an integer in the range of 1 to 60 (default).

Example 10-34 Using setMaxAbortTimeout command

setMaxAbortTimeout 60

setMaxRuntimeFileSizeMB

This command sets the value of MBean attribute MaxRuntimeFileSizeMB, the maximum size, in MB, a log file in the directory. When a log file exceeds this limit, it is closed and a new log file is opened. The attribute's value is an integer in the range of 1 MB and 15 MB; the default value is 3 MB.

Example 10-35 Using setMaxRuntimeFileSizeMB Command

setMaxRuntimeFileSizeMB 5

setMaxRuntimeLogSizeMB

This command sets the value of MBean attribute MaxRuntimeLogSizeMB, the maximum size of the log file directory, in MB. When the directory exceeds this limit, log files are purged, starting with the oldest. The attribute's value is in the range of 1 MB to 20 MB, and the default value is 10 MB.

Example 10-36 Using setMaxRuntimeLogSizeMB Command

setMaxRuntimeLogSizeMB 10

setRuntimeLogEncoding

This command sets the value of MBean attribute RuntimeLogEncoding, which specifies the character set encoding of the log file. The default value is UTF-8.

Example 10-37 Using setRuntimeLogEncoding Command

setRuntimeLogEncoding UTF-8

setRuntimeLogLevel

This command sets the value for MBean attribute RuntimeLogLevel, the log level for run-time logger. The attribute's value may be SEVERE,WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL (default).

Example 10-38 Using setRuntimeLogLevel Command

setRuntimeLogLevel ALL

setShowRuntimeLoggerLogHostAddr

This command sets the value for MBean attribute ShowRuntimeLoggerLogHostAddr, which determines whether the IP address of the CCA host is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-39 Using setShowRuntimeLoggerLogHostAddr Command

setShowRuntimeLoggerLogHostAddr true
setShowRuntimeLoggerLogHostAddr false

setShowRuntimeLoggerLogHostId

This command sets the value for MBean attribute ShowRuntimeLoggerLogHostId, which determines whether the ID of the CCA host is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-40 Using setShowRuntimeLoggerLogHostId Command

setShowRuntimeLoggerLogHostId true
setShowRuntimeLoggerLogHostId false

setShowRuntimeLoggerLogMsgClassPath

This command sets the value for MBean attribute ShowRuntimeLoggerLogMsgClassPath, which determines whether the path of the class that logged the message is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-41 Using setShowRuntimeLoggerLogMsgClassPath Command

setShowRuntimeLoggerLogMsgClassPath true
setShowRuntimeLoggerLogMsgClassPath false

setShowRuntimeLoggerLogMsgLogLevel

This command sets the value for MBean attribute ShowRuntimeLoggerLogMsgLogLevel, which determines whether the log level of the log message is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-42 Using setShowRuntimeLoggerLogMsgLogLevel Command

setShowRuntimeLoggerLogMsgLogLevel true
setShowRuntimeLoggerLogMsgLogLevel false

setShowRuntimeLoggerLogUserId

This command sets the value for MBean attribute ShowRuntimeLoggerLogUserId, which determines whether the ID of the user is included in the run-time log messages. The attribute value is either true or false (default).

Example 10-43 Using setShowRuntimeLoggerLogUserId Command

setShowRuntimeLoggerLogUserId true
setShowRuntimeLoggerLogUserId false

settingsToString

This command converts CCA setting information to String, and shows all CCA settings.

Example 10-44 Using settingsToString Command

settingsToString

showAllJobLogFiles

This command shows all job log files names.

Example 10-45 Using showAllJobLogFiles Command

showAllJobLogFiles