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 Client Console to configure scheduling and other features of the service. See Configuring the Service.

Sample Client Manager Service Configuration File

sample of service configuration file

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

;
; Databridge control program version 7.1 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.1\\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.1\\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.

cfgserver_trace

Default: 0 (not displayed in the export file when 0)
Range: 0 - 0x7FFFFF
Console: Client Managers > Actions >DBClntCfgServer Trace Options

This is a debugging tool that makes the service launch DBClntCfgServer runs with the given trace options using the command line -t option. You must set this option back to turn off this trace.

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 a next line.

dbclient_trace

Default: 0 (not displayed in the export file when 0)
Range: 0 - 0x7FFFFF
Console: Client Managers > Actions >DBClient Trace Options

This is a debugging tool that makes the service launch DBClient runs with the given trace options using the command line -t option. You must set this option back to turn off this trace.

enable_status_file

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

When set to True, 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 latter causes the run to always be started, even if the data source was not active when the service was taken down.

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 Client Console or Client runs. If the default port is used by some other application on the Client machine, you can change the port.

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 might be delayed until a thread become available. To update this parameter from the Client Console, go to the Explorer view, right-click the service node, click Properties, and then modify the value.

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 and lead to failed runs. In most cases, the default value of 1 second is adequate.

userid = , ,

Default: dbridge, "", administrator Range: character string Console: Client Managers > Actions > Manage Users

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 programs continue to work they way they did in previous versions and need to provide a password in addition to the userid. The password is encoded in the same way as it was in previous versions. You can have up to 30 userids, and each can be assigned one of the following roles:

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 tables to connect to the service, as we require that the userid of the user that allowed to access the service have their userid included in the service' configuration file. If the LDAP credential of the user were good, that does not mean that he is allowed to use the console. For batch console users we still use a password, like we did in 6.6. The service can determine whether the connection originated in Administrative Console server. It will not accept a blank password from bconsole users. Password in the service's configuration file are encoded, like they were in 6.6

To manage the configured userids in the service select the desired Client Manager from the Client managers page and click on Manage Users in the Actions menu. This will allow to add, modify or remove userid in the service. The Set bconsole Password item in the Actions menu allows to set the password for a bconsole userid. If you use the same userid for both the bconsole and Administrative Console, this is not a problem as the password is not checked from Administrative Console users as they have already been 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 the 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 log file. The suffixes of K, M and G allow you specify the maximum file size in kilobytes, megabytes, or gigabytes. A value on the order 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 the parameters for each data source, open the Databridge Client Manager service and right-click the data source you wish to modify. This will activate the Client Configuration menu. Each parameter's listing below lists the clicks from here to reach its section of the dialog box. If you don't select a data source first, the menu item will be grayed out.

Each data source that is defined in the data_sources parameter of the [Control_Program] section has its own section in the configuration file by that name. The data source section name must follow the first two sections. Do not move these sections before the [Control_Program]; this will result in an error and cause the service program to exit immediately. When an error occurs, you can examine the log file to determine the cause of the problem.

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 Client 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 Client 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, Kafka, 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

Enter the times you want the service to launch a process command for the data source. You must specify 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 Client 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 connect problems to the server or the 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

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.