6.2 IdcCommand Utility

6.2.3.1 Command File Syntax

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.

• For example, the following command file executes the ADD_USER service and defines attributes for two new users:

  <?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
  [email protected]
  @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
  [email protected]
  @end
  @ResultSet UserAttribInfo
  2
  dUserName
  AttributeInfo
  pwallek
  role,contributor,15,account,marketing,7
  @end
  <<EOD>>
  

6.2.3.2 Precedence

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.

6.2.3.3 Special Tags and Characters

These special tags and characters can be used in a command file:

6.2.4.1 Command 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. See "Command File" for more information.

6.2.4.2 User

You must specify a Content Server user name. This user must have permission to execute the services being called.

6.2.4.3 Log File

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.

6.2.4.4 Connection Mode

You can specify the connection mode for executing the IdcCommand services.

6.2.6.1 Quoting

The Launcher uses Bourne Shell-like quoting rules. A string can be quoted inside double quotes (") 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 non-quoted spaces. Each string is then unquoted and used as an entry in the argv array for the command.

6.2.6.2 Computed Settings

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

  • Examples:

    TYPE_PASSWD_FILE=file
    PASSWD_FILE_sys5=/etc/passwd
    PASSWD_FILE_bsd=/etc/master.passwd
    

  The 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

  • Examples:

    TYPE_JDK=directory
    JDK_java_home=$JAVA_HOME
    OS_DIR=$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 id 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 Content Server. 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

  • Examples:

    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

  • Examples:

    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

  • Examples:

    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 classpath 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 JAVA_CLASSPATH is set to a very long classpath.

• lookupstring

  • Examples:

    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 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 quoted and assigned to VDK_PLATFORM.

• lookuplist

  • Examples:

    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 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 quote the final value. In this example, assume the current value of STARTUP_CLASS is version. STARTUP_CLASS is replaced with the value Installer --version.

6.2.6.3 Launcher Environment Variables

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 may 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 timeout used for waiting for a Java process to successfully start on win32.

  Tip:

  By using the 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 the many ways you could configure the Launcher.

6.2.6.4 User Interface

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 given 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.

6.2.6.5 Configuring the Launcher

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 or IntradocApp.exe.

6.2.6.6 Configuration File Example

Configuration file example entries:

<?cfg jcharset="Cp1252"?>
#Content Server Directory Variables
IntradocDir=C:/domain/idcm1/
BASE_JAVA_CLASSPATH_source=$IdcResourcesDir/classesBASE_JAVA_CLASSPATH_serverlegacy=$SharedDir/classes/server.zipBASE_JAVA_CLASSPATH_server=$JLIB_DIR/idcserver.jar

This is sufficient to launch nearly all Content Server applications. Others, such as the Inbound Refinery, require additional classes in the classpath. 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. See the source code for IdcServer.java or IdcAdmin.java for more details on how to make any Java application run as a Windows service with the Launcher.

The COMPUTEDCLASSPATH is used to add class files to the CLASSPATH that the Launcher uses. To add class files, override this flag.

For example, to run Content Server with IBM's virtual machine on a Windows system, the command line would look like:

#customized for running IBM's VM
JAVA_EXE=full path

When using a custom JVM, use the full path to the Java executable file to be used.

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 or another similar value.

The following are commonly used command line options. Those options noted with an asterisk (*) are available on Windows platforms only. Unmarked options are available for Windows or UNIX platforms:

IDC_LIBRARY_PATH_customfiles=/path-to-customfiles

If you want to load custom .dlls, you should put them in the IdcHomeDir/native/win32/lib/ directory.