Appendix F: Service Configuration

This appendix lists the parameters for the Client Manager service that automate most Client operations. In most cases, you'll use the Administrative Console to configure scheduling and other features of the service. See Configuring the Service.

Sample Client Manager Service Configuration File

For information about Databridge Client configuration files, see Client Configuration Files.

    ;
    ; Databridge control program version 7.0 configuration file -- generated programmatically
    ;
    [control_program]
    ipc_port                = 8001
    userid                  = "dbridge", "", administrator
    startup_delay           = 1
    sess_start_timeout      = 2
    n_scr_threads           = 1
    enable_status_file      = false
    data_sources            = BANKDB, DEMODB

    [Log_File]
    file_name_prefix        = "cp"
    ;max_file_size          = 0
    logsw_on_size           = false
    logsw_on_newday         = false
    newfile_on_newday       = true

    [BANKDB]
    working_dir             = "d:\\dbridge_work\\bankdb"
    client_dir              = "c:\\Program Files\\Micro Focus\\DATABridge\\7.0\\SQLServer"
    ;sched_delay_secs       = 0
    ;daily                  = 10:00, 14:00, 18:00
    sched_retry_secs        = 60
    max_retries             = 3
    blackout_period = 00:00, 00:00
    ;disable_on_exitcode = 93, 94
    run_at_startup          = false
    auto_redefine           = false
    auto_generate           = false
    disabled                = false

    [DEMODB]
    working_dir             = "d:\\dbridge_work\\demodb"
    client_dir              = "c:\\Program Files\\Micro Focus\\DATABridge\\7.0\\SQLServer"
    ;sched_delay_secs       = 0
    ;daily                  = 10:00, 14:00, 18:00
    sched_retry_secs        = 60
    max_retries             = 3
    sched_minwait_secs      = 18000
    run_at_startup          = false
    auto_redefine           = false
    auto_generate           = false
    disabled                = false

[Control_Program]

This section, which must always be present in the configuration file, is used to define various service parameters. It also contains a list of all the data sources that are configured for the service.

data_sources

Default: <empty list>
Range: Comma separated list of no more than 32 data sources (maximum of 256 characters)
Console: N/A (Handled Automatically)

Use the migrate utility to create the configuration during an upgrade or use the Add Data Source and Remove Data Source commands in the Administrative Console to manage this list rather than manually adding data sources to the configuration file.

If the line of data sources is long and must wrap, the export command inserts a backslash (\) after a comma to indicate that the list continues on the next line.

enable_status_file

Default: True
Range: True or False
Console: Property sheet for the service
Applies to: Clustered Windows systems

When set to True/enabled, this parameter causes the service to maintain a status file containing information about the state of the various data sources it controls. This file is named dbstatus.cfg and resides in the config sub-directory. It is used to restart runs that were active before the service was restarted. The difference between using this method and setting the configuration parameter run_at_startup to True for a data source is that the latter causes the run to always be started, even if the data source was not active when the service was taken down.

Note

If you are not on a Clustered Windows system or you have not installed the Cluster option package, this parameter has no effect as the service ignores it. The Cluster option is separately licensed from the Client software.

ipc_port

Default: 8001
Range: 16-bit unsigned integer
Console: Not yet implemented

This parameter specifies the TCP/IP port number on which the service listens for connection requests from the Administrative Console or Client runs. If the default port is used by some other application on the Client machine the port can be changed.

When the service creates a new configuration file, it sets the value for this parameter using the port number specified at the time of installation, which is then saved to the Windows Registry (or the globalprofile.ini file in UNIX). After the ipc_port value is set, the service refers only to the ipc_port parameter in the service configuration file for this value (not the Windows Registry (or the globalprofile.ini file in UNIX).

n_scr_threads

Default: 1
Range: 1 - 4
Console: Not yet implemented

This parameter specifies the size of the pool of threads the service uses to start externally launched scripts and end-of-run scripts. If all of the threads are busy, the execution of a script may be delayed until a thread becomes available.

sess_start_timeout

Default: 2 (seconds) Range: 2-10 Console: Not yet implemented

This parameter specifies the length of time that the service waits for input from a new connection before forcing a disconnect. The reason for doing this is to protect against a flood of rogue connection requests that would otherwise cripple the service. In some cases, the default value of 2 seconds might be too low. This parameter allows you to adjust the value to best suit your environment.

startup_delay

Default: 1
Range: 0-15 (seconds)
Console: Not yet implemented

This parameter ensures that process commands for all data sources do not launch simultaneously, which can result in the mainframe failing to start all workers leading to failed runs. In most cases, the default value of 1 second is adequate.

userid = , ,

Default: dbridge, "", administrator Range: character string Console: Client Managers

When an Administrative Console session connects to the service, it provides a userid that has been authenticated without a password. The batch console and BCNOTIFY will need to provide a password in addition to the userid as it did in version 6.6. The userid is not encoded, but the password is.

Role	Alternate Spelling	Access Privileges
administrator	admin	Full privileges to use the Administrative Console.
operator	oper	Can perform only tasks related to daily operations, such as starting or stopping a run.
user		Can monitor runs and perform status commands.

When an Administrative Console session connects to the service, it provides the userid of the browser user that has been authenticated. This does not guarantee that the user will be able to connect to the service, as we require that the userid of the user allowed to access the service has their userid included in the service' configuration file. If a user has LDAP credentials, access to the Client Manager will still not be given unless the user is given access to the service. For batch console users we still use a password (similar to the previous version 6.6). The service can determine whether the connection originated in the Administrative Console server. It will not accept a blank password from bconsole users. Passwords in the service's configuration file are encoded.

To manage the configured userids in the Administrative Console, select the desired Client Manager from the Client Managers page and select Manage Users from the Actions button drop-down. This page allows administrators to add, modify or remove userids in the service. The Set bconsole Password item in the Actions drop-down button allows administrators to set the password for a bconsole userid. If you use the same userid for both the bconsole and the Administrative Console, this is not a problem as the password is not checked from Administrative Console users as they are already authenticated.

[Log_File]

Use the [Log_File] section to control the various options for the log file, which is created in the logs subdirectory of the working directory.

file_name_prefix

Default: "cp"
Range: 1 to 20 characters Console: Settings > Configure > LOGGING > Service Log (File name prefix ...)

Use this parameter to change the prefix of the log files. The log files have names in the form cp*yyyymmdd*.log, or, when necessary, cp*yyyymmdd_hhmiss*.log. This command allows you to replace the prefix "cp" with any character string (up to 20 characters in length), provided that it results in a legal filename.

logsw_on_newday

Default: False
Range: True or False Console: Settings > Configure > LOGGING > Service Log (Switch log daily)

This parameter determines whether the program uses a new log file when the date changes. You may want to set this parameter to False if your log files are small and use the logsw_on_size parameter to manage log files.

logsw_on_size

Default: False
Range: True or False
Recommended value: True Console: Settings > Configure > LOGGING > Service Log (Switch log on size)

Use this parameter to control whether the program should check the log file size to see if it has reached the size defined by the max_file_size parameter. If the size of the log file exceeds this parameter, the log file is closed and a new one is opened. If the current date is different from the creation date of the old file (which is part of its name), the new log file will be of the form dbyyyymmdd.log, otherwise, the time component will be added to the filename to ensure that the name is unique.

max_file_size

Default: 0
Range: numeric value optionally followed by K, M
Recommended value: 1M Console: Settings > Configure > LOGGING > Service Log (Maximum file size)

Use this parameter to limit the size of log files. The default value of 0 indicates that no limit is imposed on the size of the log file. The suffixes of K, M and G allow you specify the maximum file size in kilobytes, megabytes, or gigabytes. A value of 1 MB is a reasonable value to use. The file size is always checked when you start the program regardless of the setting of the logsw_on_size parameter.

newfile_on_newday

Default: True
Range: True or False Console: Settings > Configure > LOGGING > Service Log (Switch log on new day)

This parameter forces the program to use a new log file when it starts up and the log file was created on an earlier date. You may want to set this parameter to False, if your log files are small and use the logsw_on_size parameter to manage the log files.

[data_source_name]

To modify global parameters for each data source, open the Databridge Administrative Console and navigate to the Client Manager service. Select the desired data source, and select Configure from the Settings drop-down options on the data source page. Use the left side menu to navigate to the desired section of the configure parameter options. Options in the list below may not be viewable or editable until a corresponding parent option is enabled.

Each data source that is defined in the data_sources parameter of the [Control_Program] section has its own section on the Configure page. To edit the global parameters for a different data source navigate back to the Client Manager page and repeat the process above for the desired data source.

auto_generate

Default: False
Range: True or False
Console: Processing > Scheduling

This parameter causes the service to automatically launch a generate command if a (service-initiated) process or redefine command gets a return status indicating that a generate command is required. This parameter is designed to be combined with the auto_redefine parameter to allow operations to continue when a DMSII reorganization is detected.

auto_redefine

Default: False
Range: True or False
Console: Processing > Scheduling

This parameter causes the service to automatically launch a redefine command after a DMSII reorganization is detected (that is, when a service-launched process gets a return status).

When combined with the auto_generate parameter, this parameter allows operations to continue after a DMSII reorganization. If the redefine command finds nothing to do, the service launches a process command and operations resume. If the return status indicates that a generate command is required, the service will launch a generate command and upon successful completion of this command, will launch a process command. If the exit status of the redefine command indicates that a reorganize command is required, no action is taken. Manual intervention is required to examine the new scripts before they're executed to make sure that they don't corrupt the relational database.

If, after an automatic redefine command, tables in the relational database need to be altered, you can customize the data source and resume processing. The redefine command is fully compatible with customization features in the Administrative Console.

blackout_period

Default: 00:00, 00:00 Range: 00:00 to 24:00 (The two time values cannot be equal.) Console: Processing > Scheduling

Use this parameter to specify a fixed block of time during which the Client cannot run. This parameter is useful for operations, such as database backups, that can only take place when the Client is inactive. For example, if you want to back up the database daily between 1:00 a.m, and 2:30 a.m. daily, define a blackout period from 0:55 to 2:30. The extra 5 minutes ensures that the Client finishes any long transactions before the database backup begins.

If the Client is running when the blackout period starts, the Client automatically stops. If the Client is waiting for an idle host to send it updates when the blackout period starts, the Client resets the TCP/IP connection and aborts the run if it hasn't received any updates after 15 seconds. If you try to run the Client during a blackout period, nothing happens.

During a blackout period the service will not start the Client. If the scheduler tries to schedule a DBClient run at a time that falls within a blackout period, the start of the run will be delayed until the blackout period ends.

When this parameter is updated using the Administrative Console or Client Configurator, it is set to the same value in both the service and Client configuration files.

client_dir

Default: none (this line must be present)
Range: Double-Quoted string
Console: N/A (Handled automatically)

This parameter contains the full filename of the Client directory. In the case of Windows, all double slashes must be represented using two double slashes. In the case of UNIX, which uses forward slashes, this is not the case as the forward slash character has no special meaning for the configuration file scanner.

The Client directory is the database-specific subdirectory of the install directory.

In the case of Windows, the registry key INSTALLDIR is the Databridge entry point to this directory. The database specific sub-directories are SQLServer, Oracle or FlatFile.

daily

Default: daily = 08:00, 12:00, 17:00, 24:00 Range: 12 entries in ascending order from 00:00 to 24:00 Console: Processing > Scheduling

Note

The daily parameter is mutually exclusive with the fixed_delay parameter. If you specify both daily and fixed_delay in a data source section of the configuration file, fixed_delay overrides daily regardless of the order in which they are specified. The service notifies you of this situation by writing a message to the log file.

Enter the times in which the service will launch a process command for the data source. You must specify a 24-hour time (for example, 5:00 for 5:00 A.M. and 17:00 for 5:00 P.M.). The range for minutes is 00-59. You can specify up to 12 times for the daily parameter. However, you must specify the times in ascending order.

The values 00:00 and 24:00 are equivalent for midnight.
24:00 is allowed only so that you can put it at the end of the list of times in ascending order.
24:01 is not allowed; instead, specify, 00:01.

disable_on_exitcode

Default: empty list
Range: a list of up to 3 exit codes
Console: Processing > Error Recovery (Disable ... )

Specify exit codes that cause the service to disable the data source. Allowable values include: 93 (stop before or after task), 94 (stop before or after time), and 2025 (stop after audit file number).

max_retries

Default: 3
Range: 0-20
Console: Processing > Error Recovery (Options)

The max_retries parameter is intended to specify the maximum number of times the service launches a Client process command after a failed process command. Not all exit conditions are recoverable. After it unsuccessfully tries to relaunch the Client the specified maximum number of times, the service disables the data source. You must enable the data source using the Administrative Console before you can launch another process command.

The max_retries parameter is ignored for a few exit codes, where the condition that causes the problem is expected to self-correct or change over time. (Retrying forever eliminates the need for manual intervention, which would be required if the data source were to be disabled.) Such situations include connection problems to the server or database, which are often symptomatic of the host, the server, or the database being down.

run_at_startup

Default: False
Range: True or False
Console: Processing > Scheduling

This command is only meaningful during startup. It indicates whether the service should launch a Client process command for the data source when the service starts. If the process returns with a "database not up" error, the service retries the launch until the database is up.

sched_delay_secs

Default: 0 (indicating that this parameter is disabled)
Range: 1-86,400 seconds (24 hours)
Console: Processing > Scheduling

Note

The sched_delay_secs parameter is mutually exclusive with the daily parameter. If you specify both daily and sched_delay_secs in a data source section of the configuration file, sched_delay_secs overrides daily regardless of the order in which they are specified.

Use the sched_delay_secs parameter to specify a fixed delay between the time a launched Client, running a process command for the data source, terminates and the launching of the next process command for the data source. To disable the sched_delay_secs parameter, comment it out or set its value to 0.

sched_minwait_secs

Default: 0
Range: 0-86,400 (24 hours)
Console: Processing > Error Recovery (Options)

This parameter ensures that a next scheduled process command is delayed by the given interval, when a process commands finishes right around the next scheduled time and would otherwise start too soon. This parameter delays the start of the next run for the specified amount of time.

working_dir

Default: none (this line must be present)
Range: A string of any length enclosed with quotation marks
Console: N/A (Handled automatically)

This parameter contains the full file name of the working directory. In the case of Windows, all double slashes must be represented using two double slashes. In the case of UNIX, which uses forward slashes, this is not the case as the forward slash character has no special meaning for the configuration file scanner.