This chapter describes how to use the IdcCommand utility to access Oracle WebCenter Content Server services from other applications
This chapter includes the following sections:
The IdcCommand utility is a standalone Java application that executes Content Server services. Almost any action you can perform from the Content Server browser interface or administration applets can be executed from IdcCommand.
The program reads a Specifying a Command File, which contains service commands and parameters, and then calls the specified services. A log file can record the time that the call was executed, whether the service was successfully executed, and if there were execution errors.
Note:
The IdcCommand utility returns only information about the success or failure of the command. To retrieve information from Oracle WebCenter Content Server in an interactive session, use the Java COM wrapper IdcCommandX, available on Microsoft Windows platforms.
To run the IdcCommand utility, you must specify the following parameters on the command line or in the intradoc.cfg
configuration file:
A command file containing the service commands and parameters
A Content Server user name for a user who has permission to execute the services being called
A path and file name for a log file
The connection mode (auto
, server
, or standalone
)
Certain commands that cannot be executed in standalone
mode. In general, the server performs these commands asynchronously in a background thread. This happens in the update or rebuild of the search index.
For information about using services in custom components, see Chapter 11, "Getting Started with Content Server Components," and the Oracle Fusion Middleware Services Reference for Oracle WebCenter Content.
To set up IdcCommand, you must specify the following two things:
A Specifying a Command File, which specifies the services to be executed and any service parameters.
Specifying Configuration Options, which specify the command file and other IdcCommand information. You can set IdcCommand configuration options in two places:
In a configuration file, using name/value pairs, as Example 27-1 shows.
On the command line, when running IdcCommand, specifying option flags such as these:
Note:
Command-line configuration options override the settings in the configuration file.
IdcCommand is run from a command line. You can specify the Specifying Configuration Options either from the command line or in a configuration file. For more information, see Section 27.3, "Running IdcCommand."
The command file defines the service commands and parameters that are executed by the IdcCommand utility. Command files must follow rules for syntax, precedence, and special tags and characters.
The command file uses the HDA (hyperdata file) syntax to define service commands.
Each service to be executed, along with its parameters, is specified in a @Properties LocalData
section.
For some services, a @ResultSet
section is used to specify additional information.
Data from one section of the command file is not carried over to the next section. Each section must contain a complete set of data for the command.
Service names and parameters are case sensitive.
Example 27-3 shows a command file that executes the ADD_USER
service and defines attributes for two new users.
Example 27-3 Command File for the ADD_USER Service
<?hda version="5.1.1 (build011203)" jcharset=Cp1252 encoding=iso-8859-1?> # Add users @Properties LocalData IdcService=ADD_USER dName=jsmith dUserAuthType=Local dFullName=Jennifer Smith dPassword=password dEmail=email@example.com @end @ResultSet UserAttribInfo 2 dUserName AttributeInfo jsmith role,contributor,15 @end <<EOD>> @Properties LocalData IdcService=ADD_USER dName=pwallek dUserAuthType=Local dFullName=Peter Wallek dPassword=password dEmail=email@example.com @end @ResultSet UserAttribInfo 2 dUserName AttributeInfo pwallek role,contributor,15,account,marketing,7 @end <<EOD>>
IdcCommand uses precedence to resolve conflicts among the name/value pairs within the LocalData
section of the command file. When normal name/value pairs are parsed, they are assumed to be within the @Properties LocalData
tag. If the section contains HDA tags, the normal name/value pairs take precedence over name/value pairs within the @Properties LocalData
tag.
For example, if foo=x
is in a normal name/value pair and foo=y
is within the @Properties LocalData
tag, the name/value pair foo=x
takes precedence because it is outside the tag.
These special tags and characters can be used in a command file.
Special Character | Description |
---|---|
Each section of the command file must specify the name of the service it is calling. |
|
The end of data marker. The command file can include one or more sections separated with an end of data marker. For an example, see Section 27.2.1.1, "Command File Syntax." |
|
The pound character placed at the beginning of a line indicates that the line is a comment. |
|
The backslash is an escape character. |
|
@Include filename |
This tag enables you to include content from another file at the spot where the |
To run the IdcCommand utility, specify the following parameters on the command line or in the DomainHome
/ucm/cs/bin/intradoc.cfg
configuration file.
Parameter | Required? | Command Line Syntax | Configuration File Syntax |
---|---|---|---|
Yes |
-f name.txt |
IdcCommandFile=name.txt |
|
Yes |
-u sysadmin |
IdcCommandUserName=sysadmin |
|
No |
-l C:/logs/log.txt |
IdcCommandLog=C:/logs/log.txt |
|
No |
-c auto |
ConnectionMode=auto |
Note:
Command-line configuration options override the settings in the configuration file.
You must specify the name of the command file that contains the service commands and parameters. The command file parameter can specify a full path (such as C:/command_files/command.txt
), or it can specify a relative path. For more information, see Section 27.2.1, "Specifying a Command File."
You must specify an Oracle WebCenter Content Server user name. This user must have permission to execute the services being called.
You can specify a path and file name for an IdcCommand log file. As each command is executed, a message is sent to the log file, which records the time the command was executed and its success or failure status. If the log file already exists, it is overwritten with the new message. The log file can be used to display processing information to the user.
If the action performed is successful, a "success" message is written to the log file.
If the action performed is not successful, an error message is written to the log file.
If no log file is specified, information is logged only to the screen.
You can specify the connection mode for executing the IdcCommand services.
Connection Mode | Description |
---|---|
IdcCommand attempts to connect to the Oracle WebCenter Content Server instance. If this fails, services are executed in standalone mode. This is the default connection mode. |
|
IdcCommand executes services only through Content Server. |
|
IdcCommand executes services in a standalone session. There are certain services that cannot be executed in standalone mode. In general, these services are performed asynchronously by the server in a background thread. For example, this happens during update or rebuild of the search index. |
To run IdcCommand:
Create a new IdcCommand working directory.
Use this directory for your command file and configuration file.
Create a Specifying a Command File in the working directory to specify the desired service commands.
Copy the intradoc.cfg
configuration file from the DomainHome
/ucm/cs/bin
directory into the working directory.
Important:
Do not delete the IntradocDir
or WebBrowserPath
information.
Add IdcCommand options to the intradoc.cfg
file in the working directory, as Example 27-4 shows.
Example 27-4 IdcCommand Options in the intradoc.cfg File
IdcCommandFile=newfile.hda
IdcCommandUserName=sysadmin
IdcCommandLog=C:/domain/newlog.txt
For more information, see Section 27.2.2, "Specifying Configuration Options."
Run the IdcCommand utility from the DomainHome
/ucm/cs/bin
directory:
IdcCommand.exe
The Launcher is a native C++ application used to manage services in Windows environments and to construct command line arguments and environment settings for the Java VM.
The main operation of the Launcher is to find and read its configuration files, compute any special values, then launch an executable with a command line that it constructs. Configuration files support Bourne Shell-like substitutions, all of which start with the dollar sign ($) followed by an alphanumeric identifier or expression inside
braces ({}).
The Launcher executable is installed in
DomainHome
/ucm/native/platform/bin/Launcher
. On UNIX systems, symlinks are created in the bin
directory to Launcher.sh
, a Bourne Shell wrapper that executes the Launcher executable. The purpose of this wrapper is to locate the correct binary Launcher executable for the platform. The term Launcher is used here to refer to the native Launcher executable or to the Launcher.sh Bourne Shell script.
The Launcher or the symlink to Launcher.sh
must reside in a directory with a valid intradoc.cfg
configuration file and must have the same name as the Java class file to be launched (case sensitive). The Launcher uses this name to set the environment variable STARTUP_CLASS
.
On Windows this name is computed by calling GetModuleFileName()
. On UNIX systems, it is computed by inspecting argv[0]
. The PLATFORM
variable is set to the Content Server identifier for the platform. The variable BIN_DIR
is set to the directory where the Launcher is located.
The Launcher reads a file named intradoc.cfg from BIN_DIR
. This file should contain a value for IntradocDir
. The IntradocDir
directory is used as the base directory for resolving relative paths. Any unqualified path in this document should be taken as relative to the IntradocDir
. Future releases of Content Server may change or remove these variable names.
If the intradoc.cfg
file does not contain a value for IdcResourcesDir
, the Launcher sets IdcResourcesDir
to $IntradocDir/resources
. If the Launcher is starting a Windows service, it sets IS_SERVICE
to 1
. If it is unset, the Launcher also sets PATH_SEPARATOR
to the correct character for the platform.
The Launcher reads the intradoc.cfg
file first to find the locations of configuration files, then reads all available configuration files in this order:
$IdcResourcesDir/core/config/launcher.cfg
$BIN_DIR/../config/config.cfg
$IntradocDir/config/config.cfg
$IntradocDir/config/config-$PLATFORM.cfg
$IntradocDir/config/state.cfg
$IdcResourcesDir/core/config/launcher-$PLATFORM.cfg
$BIN_DIR/intradoc.cfg
$BIN_DIR/intradoc-$PLATFORM.cfg
All files specified on the command line, using the -cfg
option.
Tip:
You can assign variable values directly on the command line by using the -cfg
option NAME=VALUE.
The Launcher uses Bourne Shell-like quotation rules. A string can be inside double quotation marks (") to escape spaces. A backslash (\) can precede any character to provide that character. After a final command line is computed, the Launcher separates it into spaces without quotation marks. Each string is then used without quotation marks as an entry in the argv
array for the command.
After reading the configuration files, the Launcher processes variable substitutions. Some variables can have extra computations to validate directories or files, build command-line argument lists, or construct PATH
-like variables.
These special computations are performed for variables based on their type. To set a type for a variable, set TYPE_
variable
_
name
=
typename
in any of the configuration files listed previously.
The following list describes Launcher variable types:
file
Example 27-5 shows some file
type variables.
Example 27-5 file Launcher Variables
TYPE_PASSWD_FILE=file PASSWD_FILE_sys5=/etc/passwd PASSWD_FILE_bsd=/etc/master.passwd
This type looks for a file. If the value of variable_name
is a path to an existing file, it is kept. If not, every variable beginning with variable_name_
is checked. The last value, which is a path to an existing file, is used for the new value of variable_name
.
In this example PASSWD_FILE
is set to /etc/master
if /etc/master.passwd
exists, or it is set to /etc/passwd</span>
if /etc/passwd
exists. Otherwise, PASSWD_FILE
is undefined.
directory
Example 27-6 shows some directory
type variables.
Example 27-6 directory Launcher Variables
TYPE_JDK=directory JDK_java_home=$JAVA_HOME IdcNativeDir=$IdcHomeDir/native DEFAULT_JDK_DIR=$OS_DIR/$PLATFORM JDK_legacy142=$DEFAULT_JDK_DIR/j2sdk1.4.2_04 JDK_default=$DEFAULT_JDK_DIR/jdk1.5.0_07
In this example JDK
is set to the same value as the last of the JDK_
variables that is a directory. Typically, this would point at the JDK installed with Oracle Fusion Middleware. Note that JDK_java_home
references $JAVA_HOME
; if a variable is not defined in any configuration file but is in the environment, the environment value is used.
executable
Example 27-7 shows some executable
type variables.
Example 27-7 executable Launcher Variables
TYPE_JAVA_EXE=executable JAVA_EXE_default=java$EXE_SUFFIX JAVA_EXE_jdk_default=$JDK/bin/java$EXE_SUFFIX
The executable type looks for an executable. It works very much like the file type, but looks through every directory in $PATH
for each candidate value. In this example JAVA_EXE
is set to the Java executable in the JDK
if it exists. Otherwise it is set to the first Java executable in the PATH
.
list
Example 27-8 shows some list
type variables.
Example 27-8 list Launcher Variables
TYPE_JAVA_OPTIONS=list JAVA_MAX_HEAP_SIZE=384 DEFINE_PREFIX=-D JAVA_OPTIONS_BIN_DIR=${DEFINE_PREFIX}idc.bin.dir=$BIN_DIR JAVA_OPTIONS_maxheap=${JAVA_MAX_HEAP_SIZE+-Xmx${JAVA_MAX_HEAP_SIZE\}m} JAVA_OPTIONS_service=${IS_SERVICE+$JAVA_SERVICE_EXTRA_OPTIONS}
The list
type computes a list of options for an executable. Each value that begins with variable_name_
becomes a quoted option, and variable_name
is set to the entire list. In this example, JAVA_OPTIONS
is set to the string:
"-Didc.bin.dir=/intradocdir/bin/" "-Xmx384m"
path
Example 27-9 shows some path
type variables.
Example 27-9 path Launcher Variables
IdcResourcesDir=${IdcResourcesDir-$IdcHomeDir/resources} BASE_JAVA_CLASSPATH_source=$IdcResourcesDir/classes BASE_JAVA_CLASSPATH_serverlegacy=$SharedDir/classes/server.zip BASE_JAVA_CLASSPATH_server=$JLIB_DIR/idcserver.jar
The path
type computes a path-like value.The value of each variable starting with variable_name_
is appended to the value of variable_name
separated by the value of PATH_SEPARATOR
. In this example, BASE_JAVA_CLASSPATH
is set to a very long class path.
lookupstring
Example 27-10 shows some lookupstring
type variables.
Example 27-10 lookupstring Launcher Variables
TYPE_VDK_PLATFORM=lookupstring PARAMETER_VDK_PLATFORM=${PLATFORM}_${UseVdkLegacySearch+vdk27} VDK_PLATFORM_aix_vdk27=_rs6k41 VDK_PLATFORM_aix_=_rs6k43 VDK_PLATFORM_hpux_vdk27=_hpux11 VDK_PLATFORM_hpux_=_hpux11 VDK_PLATFORM_freebsd_vdk27=_ilnx21 VDK_PLATFORM_freebsd_=_ilnx21 VDK_PLATFORM_linux_vdk27=_ilnx21 VDK_PLATFORM_linux_=_ilnx21 VDK_PLATFORM_solaris_vdk27=_ssol26 VDK_PLATFORM_solaris_=_ssol26 VDK_PLATFORM_win32_vdk27=_nti40 VDK_PLATFORM_win32_=_nti40
The lookupstring
type uses a second parameter to construct a lookup key for the final value. The second parameter is the value of $PARAMETER_
variable_name
. If this value is undefined, the current value of variable_name
is used as the lookup key. In this example, PARAMETER_VDK_PLATFORM
has the value of ${PLATFORM}_
or ${PLATFORM}_vdk27
depending on the value of UseVdkLegacySearch
.
This value is then used to look up the value of the variable VDK_PLATFORM_${PARAMETER_VDK_PLATFORM}
which is then enclosed in quotation marks and assigned to VDK_PLATFORM
.
lookuplist
Example 27-11 shows some lookuplist
type variables.
Example 27-11 lookuplist Launcher Variables
TYPE_STARTUP_CLASS=lookuplist STARTUP_CLASS_version=Installer --version STARTUP_CLASS_installer=Installer STARTUP_CLASS_WebLayoutEditor=IntradocApp WebLayout STARTUP_CLASS_UserAdmin=IntradocApp UserAdmin STARTUP_CLASS_RepositoryManager=IntradocApp RepositoryManager STARTUP_CLASS_Archiver=IntradocApp Archiver STARTUP_CLASS_WorkflowAdmin=IntradocApp Workflow STARTUP_CLASS_ConfigurationManager=IntradocApp ConfigMan
The lookuplist
type uses a second parameter to construct a lookup key for the final value. The second parameter is the value of $PARAMETER_
variable_name
. If this value is undefined, the current value of variable_name
is used as the lookup key.
Unlike lookupstring
, lookuplist
does not enclose the final value in quotation marks. For this example, the current value of STARTUP_CLASS
is version
. STARTUP_CLASS
is replaced with the value Installer --version
.
After processing the computed settings, the Launcher iterates over all variables that begin with the string EXPORT_
. The value of each variable is used as an environment variable name, which has the value of the second half of the EXPORT_
variable assigned. For example, EXPORT_IDC_LIBRARY_PATH=LD_LIBRARY_PATH
exports the value of the IDC_LIBRARY_PATH
variable with the name LD_LIBRARY_PATH
.
The variable JAVA_COMMAND_LINE
is used to get the command line. Any command line arguments to the Launcher that have not been consumed are appended to the command line. On UNIX systems, the command line is parsed and quoting is undone and then execv
is called. On Windows, a shutdown mutex is created and CreateProcess
is called with the command line. Care should be taken because CreateProcess
does not undo backslash-quoting.
The principal mechanism for debugging the Launcher is to add the flag -debug
before any arguments for the final command. You can also create a file named $BIN_DIR/debug.log
which triggers debug mode and contain the debug output.
The Launcher has knowledge of the following configuration entries, which it either sets or uses to control its behavior. Note that these configuration variables might change or be removed in future releases of Content Server:
IDC_SERVICE_NAME
: the name of the win32 service used for service registration, unregistration, startup, and shutdown.
IDC_SERVICE_DISPLAY_NAME
: the display name of the win32 used for service registration.
IntradocDir
: the base directory for relative path names.
IdcBaseDir
: an alternate name for IntradocDir
.
IdcResourcesDir
: set to $IdcHomeDir/resources
if otherwise undefined.
IdcNativeDir
: defaults to $IdcHomeDir/native
if otherwise unset.
PATH_SEPARATOR
: set to either colon (:) or semi-colon (;) if otherwise unset.
STARTUP_CLASS
: set to the name of the Launcher executable.
MUTEX_NAME
: the name used to create a shutdown mutex on win32.
BEFORE_WIN_SERVICE_START_CMD
: if set, is a command line that is executed before a win32 service starts.
UseRedirectedOutput
: if set tells the Launcher on win32 to redirect the output from the Java VM to a file.
ServiceStartupTimeout
: the time out used for waiting for a Java process to successfully start on win32.
Tip:
By using Launcher.exe
, changing the status.dat file, and altering the value of the JVM command line, you could theoretically run any Java program as a Windows service. This is not recommended for normal use, but it does explain some ways you could configure the Launcher.
The UI for the Launcher is the same as the application it launches. For example, if the Launcher is renamed to IntradocApp
, the following command-line arguments are specified to launch the Web Layout Editor:
IntradocApp WebLayout
This launches the Web Layout Editor as a standalone application.
By default, the application is launched without console output. However, when launching IdcServer, IdcAdmin, IdcCommandX, or the Installer, Java output is printed to the screen. In all other cases, the output is suppressed for a cleaner interface.
For some applications, such as the Batch Loader and the Repository Manager, it is desirable to view the Java output from the application. To force the Launcher to dump the Java output to the screen, use the -console
flag in this manner:
IntradocApp RepMan -console
The output is now written to the console from which the Repository Manager was launched.
If the Launcher is renamed IdcServer, BatchLoader, SystemProperties, or any other Java class that requires no additional parameters, it can be launched with a simple double-click. In other cases, a shortcut can be used to launch them by double-clicking.
To use the Launcher, you must first rename the Launcher.exe file to an executable with the same name as the class file to be launched. Typical examples include IdcServer.exe
and IntradocApp.exe
.
Note:
If you want to make a custom application, you must create a custom directory and rename the Launcher.exe
file to the service that is to be launched. A valid intradoc.cfg
file must be in the same directory as the executable. The only required parameter is IntradocDir
; however, you can include other entries to alter the way the Java application is launched.
You can modify the configuration file for the applications you need to run. Example 27-12 shows configuration file entries that are sufficient to launch nearly all Content Server applications.
Example 27-12 Configuration File Entries for Content Server Applications
<?cfg jcharset="Cp1252"?>
#Content Server Directory Variables
IntradocDir=C:/domain/idcm1/
BASE_JAVA_CLASSPATH_source=$IdcResourcesDir/classes
BASE_JAVA_CLASSPATH_serverlegacy=$SharedDir/classes/server.zip
BASE_JAVA_CLASSPATH_server=$JLIB_DIR/idcserver.jar
Other applications, such as Oracle WebCenter Content: Inbound Refinery, require additional classes in the class path. This file can also be modified to enable Content Server to be run with different Java Virtual Machines.
The CLASSPATH
is designed to look for class files in order of the listed entries. In other words, the Launcher will search the entire DomainHome
/ucm/idc/native
directory before it looks in the resources
directory or server.zip
file. This is desirable if the users want to overload Java classes without patching the ZIP file.
Additionally, the Launcher can be used to install, uninstall, and run Java applications as Windows Services, if they follow the correct API for communicating back to the Launcher. For more details on how to make any Java application run as a Windows service with the Launcher, see the source code for IdcServer.java
or IdcAdmin.java
.
The COMPUTEDCLASSPATH
is used to add class files to the CLASSPATH
that the Launcher uses. To add class files, override this flag.
Note:
The intradoc.cfg
file is usually altered to include the locations of JDBC drivers for particular databases upon installation. If you want to use an alternate JDBC driver, place it outside of the IdcHomeDir
directory for Content Server, and alter the JDBC_JAVA_CLASSPATH_customjdbc
entry in the intradoc.cfg
file with the location of the driver.
Example 27-13 shows a command to run Content Server with the IBM virtual machine on a Windows operating system.
Example 27-13 Command for Running Content Server with a Custom JVM
#customized for running the IBM VM
JAVA_EXE=full path
When using a custom JVM, specify the full path to the Java executable file to be used.
Caution:
Avoid overriding the JVM command line. Customization is more complicated because of the custom class loader. If you do override the JVM command line, start with the $IdcHomeDir/resources/core/config/launcher.cfg
file.
You can set JAVA_COMMAND_LINE_SELECTION
entry in the configuration file to idcclassloader
or traditional
.
If you choose to change which JVM you are using, and if that VM has all the standard Sun SDK JAR files, then it is better to use the J2SDK
configuration entry to relocate the root directory of the SDK directory rather than use JAVA_EXE
to specify the location of the Java executable. (This is not applicable for the IBM VM.)
The J2SDK
variable changes the directory where the Sun SDK libraries are found (such as tools.jar
). If you change this entry without setting the JAVA_EXE
entry, then Java executables are assumed to be in the bin
directory of the path in J2SDK
. The default value for J2SDK
is ...\shared\os\win32\j2sdk1.4.2_04
.
To add a value to JAVA_OPTIONS
, use JAVA_OPTIONS_server=
-server
or another similar value.
The following table describes commonly used command-line options. Those options noted with an asterisk (*) are available on a Windows operating system only. Unmarked options are available for a Windows or UNIX operating system.
Option | Description |
---|---|
|
* Forces the Launcher to keep a Windows console window open so that the Java output and error streams are printed to the console. |
|
Shows paths and variables in use at startup, and startup errors. Also enables Java debugging in Content Server; when repeated, this increases verbosity. |
|
Similar to the |
|
* Used to install the Java application referred to by the Launcher as a Windows Service. |
|
* Similar to the |
|
* Used to uninstall the Java application referred to by the Launcher as a Windows Service. |
|
* Same as |
|
* Makes the Windows service dependent on whether the service-name service is also running. This command is useful when you want to make a dependent call for each service. For example, if you want to launch a database before starting Content Server, you can specify the Content Server startup to be dependent on the database startup. |
|
* Used with This command will check the user regardless of the credentials, but may not install the service. The credentials of the user need to extend to the service for the auto-start to run the service automatically. For certain services, such as Inbound Refinery, the last flag is required so that the service can run with higher permissions. The user name must be in the typical Microsoft format DOMAIN\User. Once users change passwords, the service will not be able to log in, and therefore will not run. |
|
Provides verbose output on Launcher use. |
|
Displays the version number for the Launcher and exits. |
|
* Used during an install to install a service as a specified user with a specific password. |
|
Overrides the argv[0] setting. Used by the Launcher.sh to specify the target path_name because the target of the symlink does not know its source. |
|
Specifies additional config files to read before determining computed settings. |
|
* Specifies the name of the Windows service. This can used with |
Tip:
To customize the class path to alter the system path to load Oracle .dll
files, you can set the path as follows:
IDC_LIBRARY_PATH_customfiles=/path-to-customfiles
Custom shared objects and .dll
files must not be installed into IdcHomeDir
.
If you want to load custom .dll
files, you should put them in the IdcHomeDir
/native/win32/lib
directory.
To use services remotely, you must have these files on the remote system:
DomainHome
/ucm/cs/bin/IdcCommand.exe
DomainHome
/ucm/cs/bin/intradoc.cfg
(same file as on Oracle WebCenter Content Server)
IntradocDir
/config/config.cfg
In addition, the following configuration entries must be defined in the #Additional Variables
section of the config.cfg file on the remote system:
IntradocServerPort=4444
IntradocServerHostName=IP or DNS