Concepts Guide

Man Pages for SRS

TCP-based resolver services for UM messaging products are provided by SRS.

For more information on TCP-based TR, see TCP-Based Topic Resolution Details. For more information on Topic Resolution general, see Topic Resolution Description.

There are two executables for the SRS, each with it's own man page:

- SRS Man Page - Unix and Windows command-line interface.
- Srsds Man Page - Windows Service interface.

Note that these executables are not in the same "bin" directory as the platform native UM executables. Since it is a Java program, it has its own directory sub-tree, "SRS", with sub-directories "bin" and "lib". For example, the UMS SRS executables are under "UMS_6.17.1/SRS/bin". For instructions on using a different directory structure, see the "Usage Notes" sections in SRS Man Page and Srsds Man Page.

Note also that the SRS uses the underlying platform-specific UM library, so your proper paths should be set up.

# SRS Man Page <-

Unix and Windows command-line interface.

    Usage: SRS [options] [configfile]
    Available options:
      -d, --dump             dump the user configuration to stdout and exit
      -D, --Debug=PATH:MASK  set debug PATH and MASK
      -h, --help             display this help message and exit
      -j, --java             print Java properties to the SRS log file (-j -j = print more Java properties)
      -v, --validate         validate config file and exit
      -x, --xsd              dump the configuration XSD to stdout and exit

Description
  The `SRS` command runs the Stateful Resolver Service (SRS). It can be run interactively from a shell or command prompt, or from a script or batch file. (For use as a Windows Service, see Srsds Man Page.)

  The "configfile" parameter is optional. If supplied, it specifies the file path for the SRS's XML configuration file. if omitted, the SRS defaults all configurable options. See SRS Configuration File for configuration details.

  The "-D" option sets enables debugging output. This output is intended primarily for Informatica Support, not end-users.

  The "-j" option prints Java properties to the SRS log file. It can be repeated ('-j -j') to increase the output. This output is intended primarily for Informatica Support, not end-users.

  The "-d" option dumps (prints) to standard out the full SRS configuration. After printing, the SRS exits. (Note, this is different from other UM daemons in which "-d" dumps the daemon's DTD. But the SRS does not use a DTD, it uses an XSD. See the "-x" option below.)

  The "-x" option prints the XSD which is used to validate the configuration file. After printing, the SRS exits.

  The "-v" validates the XML structure of the given configuration file against the SRS's XML XSD. After validating the configuration file's XML structure, SRS exits with status 0 for no errors, or non-zero if errors were found. For example:
  SRS -v /um/srs_cfg.xml

  Note that valid XML structure does not guarantee that the configuration file is completely correct. It must be tested on a running SRS.

  The "-h" option prints the man page and exits.

Exit Status
  The exit status from SRS is 0 for success and some non-zero value for failure.

Usage Notes

- When shutting down a Unix-based SRS Process, use a SIGINT to trigger a clean shutdown, which attempts to cleanly finish outstanding IO requests before shutting down.

- Given how the SRS was implemented, there are scripts, binary executables, and Java JAR files associated with the service. By default, the scripts and executables assume a certain directory structure, with the scripts and executables stored in a "bin" sub-directory, and JAR files stored in a "lib" sub-directory. This corresponds to how the UM package installation structures the files.

  Starting with UM version 6.17, the user can adopt a different directory structure. To assist the scripts and executables in finding the JAR files, the user can define an environment variable, "UM_SRS_DIR", which contains the full path for the directory containing the JAR files.

# Srsds Man Page <-

Windows Service interface.

See UM Daemons as Windows Services for general information about UM daemons as Windows Services.

Note
  In the descriptions below, three different log files are referenced: "service log", "process log", and "SRS log". It is important that all three of these be specified, and that they be separate files. In normal use, only the "SRS log" will be written to; the other two are only necessary to record unusual error conditions.

    Usage: srsds [options] srs_cfgfile_name
    Available options:
      -h, --help                  display this help and exit
      -l, --service-log=FILE      set a logfile name for the service log.
      -p, --process-log=FILE      set a logfile name for the srs process output.
      -s, --service=request       Install, remove or add a configuration file.
                                  Examples: '-s install' to install the service with no config file
                                    '-s install cfgfile.xml' to install the service with a configuration file of cfgfile.xml
                                    '-s remove' to remove the service
                                    '-s config cfg2.xml' to change or add a configuration file
      -e, --event-log-level       Update/set service logging level.  This is the minimum logging
                                  level to send to the Windows event log.  Valid values are:
                                    NONE - Send no events
                                    INFO
                                    WARN - default
                                    ERROR
      -E, --env_var_file          update/set the environment Variable File
      -f, --flatdir               specify that binaries and java libraries are in the same directory
                                    Note: This sets UM_SRS_DIR environment variable to the directory path of this executable
      -U, --noenv_var_file        unset env_var_file (-E) entry
                                    Note: -U and -E are not supported on the same command line

Description
  The `srsds` command has two functions:
  - First, it lets the user supply Windows Service operating parameters, which the command saves into the Windows registry. Those operating parameters are subsequently used by the SRS Service. See Configure the Windows Service.
  - Second, it provides Windows with the SRS daemon executable to run as a Service.

  The "srs_cfgfile_name" parameter specifies the file path for the SRS's XML configuration file. It is supplied in conjunction with the "-s config" option (see below). See SRS Configuration File for configuration details.

  The "-l" option specifies a "service" log file path, which is saved in the Windows registry and subsequently by the Windows Service. Under normal circumstances, this log file will never be written to. It will be written if the SRS is unsuccessful in starting up as a service. (The normal SRS log file is configured differently, using the <log> element in the configuration file.)

  The "-p" option specifies a "process" log file path, which is saved in the Windows registry and subsequently by the Windows Service. Under normal circumstances, this log file will never be written to. It will be written if the Java JVM writes to standard out or standard error, of if the SRS is not able to write to its configured log file.

Warning
  By default, the SRS's configuration file uses <log type="console">. In this case, normal SRS logs are written to standard out and will be captured in the "process" log file. This is not recommended as it leads to unbounded growth of the log file. Users should set <log type="file"> and related attributes to control the log file sizes.

  For "-s install" see Install the Windows Service.

  For "-s remove" see Remove the Windows Service.

  For "-s config" and "-e", see Configure the Windows Service.

  The "-h" option prints the man page and exits.

  The "-E env_var_file" option provides a convenient method to specify environment variables for the service without having to modify the system-level environment. The SRS service will read this file and define variables in its own environment.

  The "-U" option removes a previously set "env_var_file" ("-E") so that the next time the Windows service is started, that file will not be read. (New in UM version 6.17)

  The "-f" option is a short cut for telling the SRS that its JAR files are in the same directory as the executables, without the need to define the "UM_SRS_DIR" environment variable. (New in UM version 6.17)

Exit Status
  The exit status from SRS is 0 for success and some non-zero value for failure.

Usage Notes

- When installing the SRS as a Microsoft Windows service, use only local disk devices and fully qualified path names for all filenames. This is because Windows services run by default under a Local System account, which has reduced privileges and is not allowed access to network devices.

- Given how the SRS Windows service was implemented, there are binary executables and Java JAR files associated with the service. By default, the executables assume a certain directory structure, with the executables stored in a "bin" sub-directory, and JAR files stored in a "lib" sub-directory. This corresponds to how the UM package installation structures the files.

  Starting with UM version 6.17, the user can use their own directory structure. To assist the executables in finding the JAR files, the user can define an environment variable, "UM_SRS_DIR", which contains the full path for the directory containing the JAR files. This environment variable can either be made at the system level, or can be defined in a disk file, specified by the "-E" command-line option to `mcsds`.

  Alternatively, if you plan to store the executables in the same directory as the JAR files, you can instead use the "-f" command-line option to `mcsds`.

- Stopping the SRS service triggers a clean shutdown, which attempts to cleanly finish outstanding IO requests before shutting down.

Attention
  Do not use the task manager or the "kill" command to stop a UM daemon running as a Windows service. Use the Windows service control panel to stop the service.