Chapter 5: Server
This chapter describes the Databridge Server Accessory and how to use it.
How the DBServer Works
Databridge Server (DBServer) is installed automatically on the host when you install the Databridge software. On the Unisys MCP server, it interacts with DBEngine. On a remote system, DBServer interacts with the Databridge Client. DBServer supports communications over TCP/IP, and can support up to 100 simultaneous connections to Databridge Clients. DBServer is required for all Databridge Clients (including the DMSII Client and Databridge Twin). It is not required for Databridge host Accessories such as Span or Snapshot.
The following describes how DBServer works with other Databridge components in the replication and update process:
- The Client calls DBServer to retrieve layout information for a DMSII database by calling DBEngine.
- DBServer calls DBEngine to clone the database, and DBEngine accesses the DMSII database via DMSII access routines.
- DBServer receives the records from DBEngine, calls the filter and format in the Support library, and then sends the records to the Client.
- DBServer then calls DBEngine to retrieve updates that occurred during and following the extraction.
- The DBEngine reads the audit trail and sends the information to DBServer, which calls the filter and format in the Support library.
- DBServer sends the changed information from the audit file to the Client.
Databridge Client Access
DBServer must be running for a Databridge Client to connect to it. If it is not running, the Databridge Client tries to connect until it eventually times out.
Run DBServer
Follow these steps to edit the Databridge Server parameter file before you run Databridge Server.
To run DBServer
- Edit DBServer parameter file (DATA/SERVER/CONTROL) and save the file when you're finished. See DBServer Parameter File.
- Make sure that the DMSII database security attributes are set to give the Engine read access to the DMSII database and DMSII DESCRIPTION, CONTROL, and audit files. See the Databridge Installation Guide for information about configuring guard files.
-
From the usercode that contains the DBServer files, start DBServer as follows:
START WFL/DATABRIDGE/SERVER
After DBServer starts, it will sit idle in the mix until it receives a request from a Databridge Client. If DBServer fails to start, check the system messages on the host for the reason. 4. To check the status of a DBServer client process or to take DBServer out of the mix, see DBServer Commands.
DBServer Parameter File
The DBServer parameter file (DATA/SERVER/CONTROL) is a SEQDATA file type with 72 characters and a sequence number.
Typically, you would use only one DBServer parameter file for all DMSII databases that Databridge Clients are replicating from a particular host. The SOURCE declaration is what identifies each database. If you want to run Databridge Server in a test environment as well as a production environment, you could use multiple DBServer parameter files. (Do this by changing the name of DBServer control file from within DBServer WFL.) Each DBServer parameter file would then specify a different listening port and different databases and usercodes.
When a Databridge Client connects, Databridge Server automatically reloads the parameter file if it has been modified. You do not have to bring Databridge Server down to modify the parameter file unless you are changing network parameters, like the port number.
Note the syntax carefully:
- The literal SOURCE and the source name are followed by a colon (:).
- Commas and semicolons are interchangeable and optional. SOURCE declarations do not have to end with a semicolon.
- There is no termination character.
- There is no continuation character.
- The comment character is the percent sign (%). The comment character can appear anywhere on a line and anything after the comment character is ignored.
- To enter a value that is the same as a keyword (such as AUDIT) in the parameter file, enter that value in quotation marks.
- Boolean values can be expressed as follows:
- TRUE, YES, or no value (empty) which defaults to TRUE
- FALSE, NO
Global Options
You can use the following global options to customize the DBServer Parameter file.
AFTER COPY JOB
Syntax: AFTER COPY JOB "WFLtitle"
where WFLtitle is the name of the WFL job to run after DBEnterprise performs a file transfer. Since file transfers run under the usercode alias associated with the Windows user name, the title of the WFL job should include a usercode and family name. The job will run under the usercode specified in the file title. For example, the following will job will run under the ADMIN usercode:
`after copy job "(ADMIN)WFL/XFER/MONITOR ON SYSTEM"`
The WFL job must take two parameters. The first is the title of the MCP file that was copied. The second is a boolean that is true if the file was uploaded to the MCP environment and false if it was downloaded from the MCP environment.
AUTHORIZED CLIENT IP
Syntax: AUTHORIZED CLIENT IP "ipaddress1" [, "ipaddress2" ...]
The AUTHORIZED CLIENT IP option restricts client connections to certain IP addresses. This is a “global” option in that it applies to all sources. (See also the source option CLIENT HOST.)
Examples:
AUTHORIZED CLIENT IP "192.168.0.99"
AUTHORIZED CLIENT IP "10.10.1.45", "172.27.172.9", "10.17.1.2"
If the option is omitted, clients can connect from any IP address (but are still subject to any CLIENT HOST restrictions specified for the particular source).
Changes to this option require DBServer to be restarted to take effect.
AUTO CONNECT
Syntax: AUTO CONNECT "hostname" PORT portnumber
where hostname is the name of the host where the Databridge DMSII Client resides and portnumber is the port number that Databridge Server uses to connect to the Databridge DMSII Client. Note that you can list any number of AUTO CONNECT entries in the global section (before the first SOURCE declaration) of the DBServer parameter file.
Note
The Databridge DMSII Client is the only Databridge Client that supports the AUTO CONNECT feature. To use this feature, you must also configure the Databridge DMSII Client for AUTO CONNECT. Refer to your Databridge DMSII Client Administrator’s Guide.
This option enables Databridge Server to notify a Databridge DMSII Client when additional audit file information becomes available. When notified, the Databridge DMSII Client will then establish a connection with Databridge Server to receive the additional audit file information.
The first time Databridge Server runs, it connects to the specified ports. If successful and the Databridge DMSII Client initiates contact with Databridge Server, Databridge Server will note the database the client uses and contact the Databridge DMSII Client when audit file information becomes available for that database.
PORT
When DBServer initializes, it ensures that no other program is already using the specified port. This prevents multiple copies of DBServer from using the same port.
TCP/IP |
TCP/IP Port = number [BUFFER size messagesize] [KEYCONTAINER = key container name] where number is the port number on which DBServer will listen for incoming requests from Databridge Clients. The port number must match what the Databridge Clients use. This value must be an integer between 1024 and 65535 that defines the TCP/IP port number. A range of port numbers is pre-allocated for TCP/IP and therefore cannot be used by DBServer. To avoid any conflicts, do not use any of the well-known sockets predefined for TCP/IP. Most of the well-known sockets are 500 and below. Most port numbers (sockets) over 1024 are available for use, but you should check with your TCP/IP administrator before setting the portnumber. TIP: Many sites use the Databridge release number, such as 7000, as the port number, toisolate and simplify testing and integration of new releases while the earlier Databridge release continues to run. For BUFFER SIZE messagesize, enter a port file record size (in bytes) that matches the message size in use by your network. In some situations, matching the message size to your network can improve throughput. In addition to setting the port file record size, this entry also sets the size of the buffer. Optimally, the buffer size should be a multiple of the TCP/IP segment size. By default, BUFFER SIZE is set to 8736 bytes. Uncomment KEYCONTAINER and enter a key container name to enable TLS encryption. To obtain a key container, use Security Center to create a new trusted key in the MCP Cryptographic Services->Other Keys section. When creating a new key, the key container name is formed by concatenating the application and service names separated by an underscore. For example, an application of DATABRIDGE and service of SSLKEY will form a key container name of DATABRIDGE_SSLKEY. The usercode for the new key must match the usercode where Databridge is installed. Enter the other fields as appropriate for your organization and create a certificate request. When a certificate authority has processed the request, install the certificate into the key. |
PRINT STATISTICS
Syntax: PRINT STATISTICS [ = ] [ TRUE | FALSE ]
If specified before the first SOURCE, this is the default setting for each SOURCE. See the AX STATISTICS command in DBServer Commands.
WORKERS
Syntax: WORKERS nn
where nn is a number from 1–100.
Note
This option is not related to or affected by the DBEngine WORKERS setting.
This option enables you to set the total number of DBServer Worker stacks that can be active at one time. Each DBServer Worker stack enables one Databridge Client to retrieve information. So, if you want five Databridge Clients to be able to connect to DBServer simultaneously, set DBServer WORKERS option to 5.
When Enterprise Server is in “browse” mode (that is, it is initiated by users for viewing the various servers and sources), it may use several Workers. Generally, Enterprise Server will use one Worker for each source the user is actively browsing. Therefore, you may want to set the number of WORKERS to a large value, such as 20.
You can change this setting at run time by using the AX WORKERS command. See DBServer Commands.
Each Worker’s task name includes an ON clause identifying the remote workstation by either its IP address or host name. You can view this information by viewing active entries. If you are using guard files, you can enter the remote workstation’s ID in the title of an allowed Worker in your guard file. This enables you to allow specific workstations to access specific databases.
You can also determine the name of the remote workstation by using the workertasknumber AX STATUS
command.
SOURCE Options.
Use the following SOURCE options to customize individual sources.
SOURCE
Syntax: SOURCE sourcename
Databridge Clients connect to DBServer by using the specified port number. During the initial handshake, the client specifies which database to use by passing a source name to DBServer.
Enter a unique name for identifying the database, filter, etc., you are using. All sources must have a unique name. The actual source definition is provided by settings defined in the remainder of this section.
Your entry for SOURCE is the name the Databridge Client uses to request the layout information to define a data source.
AUDIT JOB
Syntax: AUDIT JOB "(usercode)WFLname ON pack"
The quotation marks are required.
Use this parameter to specify the name (and optional usercode and pack) of a WFL that you want DBServer to start after DBEngine has processed an audit file. DBServer passes the WFL an integer, which is the AFN (audit file number).
AUDIT JOB takes effect when both of the following circumstances are met:
- The AFN changes.
- There is a COMMIT.
You might use AUDIT JOB, for example, to initiate the Audit Remove WFL to remove an audit file from a secondary pack. For information, see Audit Remove Utility.
Note
You can combine the AUDIT ON and AUDIT JOB options as follows:
AUDIT ON packname JOB "WFLname"
AUDIT ON
Syntax: AUDIT ["fileprefix"] ON media [OR media] [NO WAIT]
where media is one of the following:
[ PRIMARY | SECONDARY ] alternatepack
[ PRIMARY | SECONDARY ] ORIGINAL FAMILY
[ PRIMARY | SECONDARY ] TAPE
The optional fileprefix parameter can specify a title prefix, enclosed in quotes. This enables processing of audit files that have been renamed. PRIMARY refers to the primary audit (for example, BANKDB/AUDIT1234) and SECONDARY refers to the secondary audit (for example, BANKDB/ 2AUDIT1234). If you don’t specify PRIMARY or SECONDARY, then Databridge will look for both if the database is declared to have a duplicated audit.
Use one of the AUDIT ON parameters to specify where the audit files are stored. This parameter overrides the audit pack specified in the DMSII CONTROL file. This parameter does not specify where audit files are created; it specifies only where Databridge will look for audit files. During cloning, however, Databridge ignores the AUDIT ON parameter and reads from the active audit file on the original family where it is being written.
When the optional NO WAIT parameter appears, DBEngine will not wait when an audit file is missing. Instead, it will return DBM_AUD_UNAVAIL(7).
Note
You can combine the AUDIT ON and AUDIT JOB options as follows:
AUDIT ON packname JOB "WFLname"
Examples
In these examples, the database is called BANKDB and 1234 is the stored audit file. The DASDL has the following statement:
AUDIT TRAIL ATTRIBUTES (PACK = PAUDIT, DUPLICATED ON PACK = SAUDIT).
Modify the following examples to meet your specific needs:
AUDIT ON ORIGINAL FAMILY
% BANKDB/AUDIT1234 ON PAUDIT, or
% BANKDB/2AUDIT1234 ON SAUDIT
AUDIT ON SECONDARY SPARE
% BANKDB/2AUDIT1234 ON SPARE only
AUDIT ON PRIMARY ORIGINAL FAMILY
% BANKDB/AUDIT1234 ON PAUDIT
AUDIT ON SPARE OR ORIGINAL FAMILY
% BANKDB/AUDIT1234 ON SPARE, or
% BANKDB/2AUDIT1234 ON SPARE, or
% BANKDB/AUDIT1234 ON PAUDIT, or
% BANKDB/2AUDIT1234 ON SAUDIT
Note
If you want Databridge to look for the audit file on alternatepack and on the original family and on tape, you must use AUDIT ON alternatepack OR ORIGINAL FAMILY OR TAPE.
AUTHORIZED USERCODE
Syntax: AUTHORIZED USERCODE [ = ] usercode1 [OR usercode2 ...]
The AUTHORIZED USERCODE source option specifies which usercodes are allowed to access the source. For Windows clients, the user name of the person or process running the client must be a valid usercode on the MCP system or mapped to a usercode using the REMOTEUSER construct.
Usercodes should be in quotes if they could be confused with reserved words.
Example
source Bank:
database = DESCRIPTION/BANKDB
authorized usercode = BILLSMITH or "SUPPORT";
If an unauthorized user attempts to use a source, DBServer will return error 1003:
username at clienthost not authorized for source sourcename.
CLIENT HOST
Syntax: CLIENT HOST = "host1" [OR "host2" ...]
where host is either a valid client host name or IP address.
This option restricts Client access to DMSII databases. Only Databridge Clients running on the listed server(s) will be allowed to connect to this source. Otherwise, error 1033 is returned:
Invalid client host host for source.
CLONE
Syntax: CLONE [ OFFLINE | ONLINE ]
Use this parameter to specify whether Databridge should do an online extraction (the database is open for updates) or an offline extraction (the database is not open for updates). If you do not specify OFFLINE or ONLINE, DBServer will do an online clone. You might want to clone offline to avoid having to apply any fixup records to the extracts file. Note that if the database has INDEPENDENTTRANS set, DBEngine will use SECURE STRUCTURE to enforce an offline clone, which allows other programs to update the data sets not being cloned. Otherwise, an OPEN SINGLE UPDATE is performed to prevent other programs from updating the database at all during the clone.
If you specify OFFLINE, there will not be a fixup phase in the replication process since there will be no updates to the cloned data sets during the extract phase.
Note
When using Databridge Enterprise to clone a dataset, the CLONE OFFLINE option will be ignored if it is reading the dataset in Direct or Indirect mode. In this case Databridge Enterprise always performs an online clone.
DATABASE
Syntax: DATABASE [ logicaldatabase OF ] description_title
Enter the actual name of the DMSII database DESCRIPTION file or a logical database within a DESCRIPTION file. Include the usercode and the disk family on which the DESCRIPTION file resides if different from the usercode DBServer is running under.
Examples
DATABASE DESCRIPTION/BANKDB ON DISK
DATABASE LDB2 OF (ABC)DESCRIPTION/BANKDB
FILTER
Syntax: FILTER filtername
where filtername is the name of a GenFormat filter routine. To create your own filtering routine, see Creating a Filter.
This option specifies the name of a filtering procedure, which is an entry point in DBSupport. DBServer calls the filtering procedure for each data set record. Your entry for SUPPORT determines which library DBServer calls.
KEY
Syntax: KEY "password"
Entering a key (password) is optional. You can enter a password with a maximum of 17 alphanumeric characters. If you do enter a password, Databridge Client users must enter this password in addition to the source name.
In DBServer, if the key is specified with quotes it will retain the case exactly. Without the quotes, the key will be uppercase.
Example:
KEY = Secret (Client must use - SECRET)
KEY = "Secret" (Client must use - Secret)
Caution
The password is stored in the file without encoding or encryption. Therefore, make sure you limit access to the DBServer parameter file.
NOTIFY
Syntax: NOTIFY "ipaddress" PORT number
where ipaddress is the IP address of Enterprise Server and number is the port number on the Enterprise Server computer where the Databridge Director service will listen for notifications from DBServer.
This option enables DBServer to notify the Client via Enterprise Server when audit files become available. You can define multiple NOTIFY options and multiple SOURCEs can NOTIFY the same PORT.
Note
This feature works in conjunction with the Notify WFL and the Copy Audit Utility.
PRINT STATISTICS
Syntax: PRINT STATISTICS [ = ] [ TRUE | FALSE ]
If part of a SOURCE declaration, this option determines whether a statistics report is printed for a Worker using that source. See the AX STATISTICS command in DBServer Commands.
PRIORITY
Syntax: PRIORITY [=] number
where number is between 0 and 99.
This option enables you to specify the priority a Worker should have when serving this source. When stacks compete for CPU resources, a stack with a higher priority will get the CPU before one with lower priority.
Example
SOURCE BANKDB:
...
PRIORITY = 65
...
READER
Syntax: ["readerprogram"] USING "directory"
where directory is the directory containing the flat files you want to replicate.
This option is only used with Databridge FileXtract and does not appear in the sample DBServer parameter file. It does appear in DATA/SERVER/SAMPLE/FILEBRIDGE/CONTROL however, and you can insert all or part of that file in DATA/SERVER/CONTROL.
SOURCE LIKE
Syntax: SOURCE sourcename LIKE sourcename: attribute_overrides;
A SOURCE can use another SOURCE for default values. This is useful when you want to declare several SOURCEs with similar attributes. The following is a sample entry:
SOURCE KPMDB:
DATABASE = DESCRIPTION/KPMDB ON DISK,
USERCODE = HRD,
FILTER = KPROP,
SUPPORT = OBJECT/DATABRIDGE/SUPPORT/KPMDB;
SOURCE KPMDBONLYBANK1 LIKE KPMDB:
FILTER = ONLYBANK1;
In this example, KPMDBONLYBANK1 has all of the same options as KPMDB except that it uses a different filter.
If the target source is not found, DBServer displays the following error message:
DBServer: Source not found (at line nnn): targetname
STOP
Syntax: STOP { BEFORE | AFTER } { timedate | "taskname" }
Enter this command to stop Databridge from returning updates beyond a specified quiet point. The quiet point can be before or after a specified time, day, program, or a specific program on a specific date. For example, if you wanted to limit daily transactions to only those processed before 4:00 p.m., you would configure the STOP command to stop processing at the last quiet point before 4:00 p.m.
Time in the STOP command refers to the time the update occurred on the primary system, not the current time of day.
The “+/- days” are in relation to the DBServer Worker start date. For example, when the Worker starts, it calculates an audit file STOP date based on the current date plus or minus the “+/- days” parameter. The replication stops when it reaches an audit location with this calculated date.
The following table explains the STOP parameters:
STOP Options | Description |
---|---|
STOP { BEFORE | AFTER } hh:mm [ AM | PM ] |
Replication stops at either the last quiet point before or the first quiet point after the designated time. Note that the time entry hh:mm can be either 24-hour time format (22:30 for 10:30 p.m.) or 12-hour format (10:30 p.m.) For example, the following command informs replication to stop at the last quiet point before 10:30 p.m. STOP BEFORE 10:30 PM |
STOP { BEFORE | AFTER } { hh:mm [AM | PM] } ON [+ | -] days |
Replication stops at either the last quiet point before or the first quiet point after the designated time and after the designated number of days. Note that the time entry hh:mm can be either 24-hour time format (22:30 for 10:30 p.m.) or 12-hour format (10:30 p.m.). Also note that a days entry of zero indicates the current day. For example, the following command causes replication to stop processing at the last quiet point that occurs tomorrow before 10:30 p.m. STOP BEFORE 22:30 ON + 1 |
STOP { BEFORE | AFTER } { hh:mm [AM | PM] ON mm/dd/yyyy } |
Replication stops at either the last quiet point before or the first quiet point after the designated time on the designated day. Note that the time entry hh:mm can be either 24-hour time format (22:30 for 10:30 P.M.) or 12-hour format (10:30 P.M.). For example, the following command causes replication to stop at the first quiet point after 1:30 p.m. on December 9, 2009. STOP AFTER 13:30 ON 12/9/2009 |
STOP { BEFORE | AFTER } { "taskname" } |
Replication stops processing at either the last quiet point before the BOT or the first quiet point after the EOT of the designated task name. If you specify a usercode, Databridge looks for a task name match under the specified usercode. Otherwise, Databridge looks for task name match under any usercode. For example, the following command causes replication to stop at the first quiet point after the EOT of task name "OBJECT/SAVINGS/POSTING". STOP AFTER "OBJECT/SAVINGS/POSTING" |
STOP { BEFORE I AFTER } { "taskname" I { BEFORE I AFTER } hh:mm [AM | PM] ON mm/dd/yyyy } |
Keep in mind the following when using the STOP
command:
- If you do not specify a usercode on the taskname, replication will stop at a task with any usercode in the task name.
- If a
STOP BEFORE "taskname"
command is specified, replication stops at the last quiet point before the task opened the database. - If a
STOP AFTER "taskname"
command is specified, replication stops at the first quiet point after the task closed the database. - If more than one task name is specified, only the last one specified is used. Similarly, if more than one time/date is specified, only the last time/date specified is used.
SUPPORT
Enter the filename of the support library, using the following table as a guide.
Library | Entry |
---|---|
Non-tailored support library | OBJECT/DATABRIDGE/SUPPORT |
Tailored support library | OBJECT/DATABRIDGE/SUPPORT/dbname |
If a Worker is unable to link to the DBSupport Library for any reason, the Worker will try to recompile it.
Note
If you make any changes to the SUPPORT entry, you must run the redefine
command on the Client. For instructions, see the Databridge Client Administrator’s Guide.
TRANSFORM
Syntax: TRANSFORM transformname
where transformname is the name of a GenFormat transform routine. To create a transform routine, see Transforms.
This option specifies the name of a transform routine, which is an entry point in the DBSupport Library. DBServer calls the transform routine in DBSupport for each data set record. Your entry for SUPPORT determines which DBSupport library DBServer calls.
USERCODE
Syntax: USERCODE worker_usercode
This entry specifies the usercode (and any associated FAMILY substitution) under which the DBServer Worker stack will run. DBServer initiates the stack as a process when the Databridge Client connects to DBServer and then the Worker calls DBChangeUser to change the usercode of the stack prior to opening the DMSII database.
DBServer Commands
Use the following commands when running DBServer. The servertasknumber in these commands is the task number of the main DBServer (OBJECT/DATABRIDGE/SERVER) stack. A workertasknumber is the task number of one of the DBServer Workers (DBSERVER/WORKER/n). Each DBServer Worker is connected to exactly one Databridge client.
Command | Description |
---|---|
AX BUFFER |
Displays or sets the TCP/IP buffer size. See comments on BUFFER SIZE.servertasknumber AX BUFFER [nn] The nn value is the size of the TCP/IP buffer new Workers will use. |
AX HELP |
To display the AX commands that you can use with DBServer, enter the following command:servertasknumber AX HELP -or- workertasknumber AX HELP |
AX QUIT |
Typically, most sites leave DBServer in the mix. That way, DBServer is available for the Databridge Clients. However, to quit DBServer, use the following command:servertasknumber AX QUIT [source] where the optional source is the particular SOURCE to be terminated, in which case all Workers using that source will be terminated. If source is not specified, DBServer terminates after all of the Workers have completed. If needed, you can terminate individual Worker stacks without terminating the DBServer. workertasknumber AX QUIT The Worker terminates after the next commit. |
AX SIZES |
Displays various size-related statistics: network read and write, audit record, and transaction group. The number in parentheses is the count of samples of that category. The four numbers at the end of the displayed line are the minimum, maximum, average, and total.workertasknumber AX SIZES |
AX STATISTICS |
Displays or sets the option enabling or disabling printing the statistics report when a Worker finishes.workertasknumber AX STATISTICS [ TRUE |
AX STATUS |
You can use the AX STATUS command to display status information for either the main DBServer stack or a Worker stack.
|
AX TIMES |
Displays various time-related statistics: Network read and write, DBRead wait, thread lock waits, and total processor time.workertasknumber AX STATUS The number in parentheses is the count of samples of that category. The four numbers at the end of the displayed line are the minimum, maximum, average, and total. |
AX WORKERS |
Displays or limits the current number of active Worker stacks. To display the limit, enter: servertasknumber AX WORKERS To limit the number of active Worker stacks, enter: servertasknumber AX WORKERS nn where nn is a number from 1 to 100. This command will not terminate any active Workers. DBServer uses this number only when it is considering whether to offer additional subports for new client connections. |
Troubleshooting DBServer Usercodes
Ensure that OBJECT/DATABRIDGE/CHANGEUSER has the TASKING attribute set. This is required for DBServer to change the usercode as specified in DBServer parameter file.
For information on how the usercode under which you run DBServer can affect the usercodes for the stack initiated for each Databridge Client, see USERCODE.
If a DBServer Worker is unable to connect to the proper database, check this USERCODE entry. This usercode must ensure that DBEngine has visibility to the DBEngine parameter file (DATA/ENGINE/ CONTROL).