C.1 Preparation for using an embedded database

This appendix describes the preparation for using an embedded database as the JP1/AJS3 - Manager scheduler database.

Organization of this subsection

(1) Procedure for installing and setting up an embedded database
(2) Examining the embedded-database operating environment and operating method

(1) Procedure for installing and setting up an embedded database

The following figure shows the procedure for installing and setting up an embedded database.

Figure C‒1: Procedure for installing and setting up an embedded database

To Page Top

(2) Examining the embedded-database operating environment and operating method

(a) Operating environment

Carefully consider the following environment conditions related to operation of the embedded database:

System configuration
Environment scale
System file area
Operating environment

■ System configuration

Decide whether to configure the embedded database in a non-cluster configuration (physical host) or in a cluster configuration (logical host). The environment conditions consist of both those related to embedded databases and those related to the overall JP1/AJS3 service configuration.

■ Environment scale

Based on the scale of JP1/AJS3 operations, select small, medium, or large as the scale of the embedded database environment. The following table provides a guideline for selecting the scale.

Table C‒1: Guideline for selecting the scale of the embedded database environment to be set up
Scale	Number of units	Number of jobs and jobnets executed per day	Number of logs to keep
Small	5,000 or less	5,000 or less	5 or less
Medium	5,000 to 48,000	5,000 to 30,000	5 or less
Large	48,000 to 240,000	30,000 to 120,000	5 or less

Note:: If you execute the ajsembdbsetup command with the -e sjis option specified to set up the database for the scheduler service, use the guideline in the following table to determine the scale.

Table C‒2: Guideline for selecting the scale of the embedded database environment to be set up (when the -e sjis option is specified for the ajsembdbsetup command)
Scale	Number of units	Number of jobs and jobnets executed per day	Number of logs to keep
Small	4,000 or less	4,000 or less	4 or less
Medium	4,000 to 38,400	4,000 to 24,000	4 or less
Large	38,400 to 192,000	24,000 to 96,000	4 or less

If the scale of the operation is larger than the large scale in the table, create the embedded database environment as large scale, and then expand the environment.

For details about how to expand an embedded database environment, see ajsembdbaddarea in 2. Commands in the manual Job Management Partner 1/Automatic Job Management System 3 Command Reference 1.

■ System file area

Decide whether it is necessary to duplicate the system files used for the embedded database. If you choose to duplicate the system files, although the required disk space will increase, you will be able to restore the embedded database to the point of a disk failure if one occurs.

The following table shows the required disk space for each type of embedded database operating environment. Select one of the possibilities.

Table C‒3: Disk space required for the embedded database operating environment
No.	Operating environment				Required disk space (in megabytes)
No.	System configuration	Environment scale	Using RAW files^#1	System files duplicated	System area^#2	Data area	System file area	Work area	Total^#3
1	Non-cluster	Small	No	No	170^#4	200	320	--	520
2			No	Yes			640	--	840
3			Yes	No			320	40	560
4			Yes	Yes			640	40	880
5		Medium	No	No		1,400	2,800	--	4,200
6			No	Yes			5,600	--	7,000
7			Yes	No			2,800	40	4,240
8			Yes	Yes			5,600	40	7,040
9		Large	No	No		6,700	14,000	--	20,700
10			No	Yes			28,000	--	34,700
11			Yes	No			14,000	40	20,740
12			Yes	Yes			28,000	40	34,740
13	Cluster	Small	No	No	170^{#4, #5}	200	320	40 x 2^#6	600
14			No	Yes			640		920
15			Yes	No			320		600
16			Yes	Yes			640		920
17		Medium	No	No		1,400	2,800		4,280
18			No	Yes			5,600		7,080
19			Yes	No			2,800		4,280
20			Yes	Yes			5,600		7,080
21		Large	No	No		6,700	14,000		20,780
22			No	Yes			28,000		34,780
23			Yes	No			14,000		20,780
24			Yes	Yes			28,000		34,780

Legend: --: The work area is not necessary
#1: Applicable in UNIX only
#2: The system area is created on the disk on which JP1/AJS3 is installed or in the directory specified in the -i option of the ajsembdbinstl command. For details about the ajsembdbinstl command, see ajsembdbinstl in 2. Commands Used during Setup in the manual Job Management Partner 1/Automatic Job Management System 3 Command Reference 2.
#3: This value does not include the system area amount.
#4: This value varies according to the OS.

OS	Size (MB)
Windows	170
HP-UX (IPF)	400
Solaris	260
AIX	200
Linux	210

#5: In a cluster system, the embedded database must be installed on both the primary and secondary nodes.
#6: In a cluster configuration, work areas must be created on both local disks, and must not be created on a shared disk. That is, you must create a work area on both the primary node and the secondary node.

■ Operating environment

Take into consideration the following operating environment items related to the embedded database:

System definitions

The operands in the following system definitions are described below.

System common definition
Single server definition

Note that if the embedded database is used in JP1/AJS3, normally you do not need to change the system definition for the embedded database. Therefore, change the system definition settings only if a problem occurs.

• System common definition

The following describes the operands in the system common definition, the values of which can be changed by the embedded database system administrator.

The path name of the system common definition file is as shown below. You (the embedded database system administrator) can change the values of operands specified in this file.

Windows: embedded-database-practical-directory\conf\pdsys
UNIX: embedded-database-practical-directory/conf/pdsys

Note that the operands in the following table that are enclosed in square brackets ([ ]) are not written when the embedded database is set up. Add the operands if necessary.

Important note: To ensure correct JP1/AJS3 operation, do not change the values of any operands that are not described here.

No.	Format
1	`set pd_max_users =` `maximum-number-of-concurrently-connectable-users`
2	`[set pd_service_port =` `client-connection-port-number]`
3	`set pd_mode_conf =` `embedded-database-start-method`
4	`[set pd_utl_exec_time =` `execution-monitoring-time-of-a-command-for-operating-the-embedded-database]`
5	`putenv TZ` `timezone`

(1) pd_max_users = maximum-number-of-concurrently-connectable-users

~ <unsigned integer> ((1 to 2000))

This operand specifies the maximum number of users who can connect to the embedded database. If you want to change the maximum number of users who can connect to the embedded database, change the value of this operand. If connection to the embedded database is requested when the number of users who have already been connected to the embedded database has reached the maximum, the embedded database does not accept the request (the request results in an error). In JP1/AJS3, the default value of this operand is 128.

Cautionary note:

For embedded-database operation commands, each command is counted as a single connection to an embedded database.

The number of connections to the embedded database is counted as shown in the following table.

JP1/AJS3 behavior	Number of connections
Startup of JP1/AJS3 - Manager	2
Startup of a scheduler service	4
Execution of a command that performs an operation on a unit	1
Connection from JP1/AJS3 - View	The number of viewed scheduler services
Execution of a command that performs an operation on the embedded database	2

Note that, when a JP1/AJS3 command is executed from JP1/AJS3 - View, 1 connection is used from JP1/AJS3 - View to the embedded database, and 1 connection is used for executing the command.

If you set a value larger than 500 for pd_max_users, you need to expand the space for the sink point dump files. Execute the ajsembdbaddlog command three times with the -s 7 and -r spd options specified to expand the space for the sink point dump files.

The following shows an example of specifying the ajsembdbaddlog command:

ajsembdbaddlog -s 7 -r spd -id _JF0 -d directory-name

For details about the option of the ajsembdbaddlog command, see ajsembdbaddlog in 2. Commands in the manual Job Management Partner 1/Automatic Job Management System 3 Command Reference 1.

(2) pd_service_port = client-connection-port-number

~ <unsigned integer> ((5001 to 65535))

If there is a firewall on the embedded database server side, specify the client connection port number. Note that the port number you specify must satisfy the following condition:

Port number that is unique on the host

Explanation:

Specify this operand as necessary if you use a product that links to JP1/AJS3. You do not need to specify this operand in JP1/AJS3 - Manager because it is not available in JP1/AJS3 - Manager.
If you start multiple servers or units on the same computer, specify a separate port number for each embedded database.

Cautionary note:

Make sure that the port number you specify is outside the range of port numbers assigned automatically by the OS. This differs depending on the OS. If another program is already using a port number in the range and you specify that port number, you will not be able to start the embedded database.

(3) pd_mode_conf = starting-the-embedded-database

Specify how the embedded database starts. You can set the values below for pd_mode_conf. The default is MANUAL2. You usually do not need to change the default.

AUTO

When the OS starts, the embedded database is started automatically. If the embedded database terminates abnormally, it is restarted automatically.
MANUAL1

When the OS starts, the embedded database is not started automatically. The embedded database is restarted automatically only if it terminates abnormally.
MANUAL2

When the OS starts, the embedded database is not started automatically. Unlike MANUAL1, if the embedded database terminates abnormally, it is not restarted automatically.

(4) pd_utl_exec_time = execution-monitoring-time-of-a-command-for-operating-the-embedded-database

~ <unsigned integer> ((0 to 35791394)) <<0>> (unit: second)

If you monitor the execution time of the following commands that operate the embedded database, specify the monitoring time in minutes.

ajsembdbreclaim command
ajsembdbrorg command

If the command does not complete execution within the time specified in this operand, a message (KAVS2117-E) is output to the standard error output and the command terminates abnormally.

Advantage:

If the command does not send any response during execution in a nighttime batch job because of a problem such as a communication error or disk error, you can allow the command to terminate abnormally at the specified time.

Guideline for specifying a value

The purpose of this operand is to handle a non-response error, not to monitor the maintenance processing time of the database. Therefore, specify a value for the operand that includes a margin for the maximum value of the actual performance value for the command execution time. For example, if the maximum execution time of the ajsembdbreclaim command is about 60 minutes and the maximum execution time of the ajsembdbrorg command is about 90 minutes, specify 120 for pd_utl_exec_time to provide the margin. The reason for this value is that a non-response error might occur if processing that always finishes in 90 minutes fails to send a response after an additional 30 minutes has elapsed. Note that the time of 30 minutes added to the maximum command execution time is based on the assumption that maintenance is being performed on a scheduler database and the agent management database. If a different type of database access is being performed (for example, access for execution of a job or unit operation command) during the maintenance processing, the maintenance processing waits one minute for the processing to be completed. Accordingly, as a guideline for the time to be added, specify a value that includes a margin obtained from the expression number-of-processing-target-tables x 2 x 1 (in minutes).

For details about the tables that are created in the embedded database, see 2.6.3 JP1/AJS3 database tables in the Job Management Partner 1/Automatic Job Management System 3 System Design (Configuration) Guide.

(5) TZ timezone

~ character-string

Specify the time zone of the date and time information for messages about embedded databases (messages beginning with KFP). The default is JST-9.

For this operand, specify the same value as the time zone of the OS.

• Single server definition

The following describes the operands in the single server definition, the values of which can be changed by the embedded database system administrator. The path name of the single server definition file is as shown below. You (the embedded database system administrator) can change the values of operands specified in this file.

Windows: embedded-database-practical-directory\conf\ajs2
UNIX: embedded-database-practical-directory/conf/ajs2

Important note: To ensure correct JP1/AJS3 operation, do not change the values of any operands that are not described here.

No.	Format
1	`set pd_lck_pool_size =` `size-of-pool-used-for-locking`

(1) pd_lck_pool_size = size-of-pool-used-for-locking

~ <unsigned integer> (unit: KB) ((1 to 2000000))

Specify, in kilobytes, the size of the shared memory area in the embedded database.

In JP1/AJS3, the default differs depending on the scale specified by the ajsembdbbuild, jajs_setup, or jajs_setup_cluster command.

Scale	Command option	Lock pool size
Large	`-l`	60,000
Medium	`-m`	37,500
Small	`-s`	15,000

Operation method:

If units are to be operated by using commands or JP1/AJS3 - View, the size of memory area used for locking changes based on the number of units to be operated. For this reason, estimate and set the appropriate memory area size in advance.

If many units are operated at the same time, the memory area for locking might become insufficient, causing the following problems:

The message KAVS0902-E is output to the integrated log, syslog, or Windows event log, and the message KFPA11912-E is output as maintenance information for the message KAVS0902-E. The operations being performed end abnormally.

If insufficient memory area for locking prevents scheduler services from normally accessing the database, the following problems might occur:

The message KAVS0902-E is output, and jobs and jobnets cannot be executed normally.
The message KAVS0230-E is output to the integrated log, syslog, or Windows event log, and scheduler services end abnormally.

If the above problems occur, the memory area for locking might be insufficient. Check the following items:

The total number of top-level units and their subordinate units in the unit definition that is created by using the command ajsdefine or that is deleted by using the command ajsdelete or JP1/AJS3 - View
The number of units (including subordinate units) specified as the copy sources for unit copy operations performed with the ajscopy command or JP1/AJS3 - View
The number of units (including subordinate units) to be restored by restore operations performed with the ajsrestore command or JP1/AJS3 - View
The total number of root jobnets (including subordinate units) specified as the release sources for release operations performed with the ajsrelease command or JP1/AJS3 - View
The number of root jobnets (including subordinate units) specified, or the number of root jobnets (including subordinate units) defined under the job group specified, for execution registration operations performed with the ajsentry command or JP1/AJS3 - View
The number of jobnets (including subordinate units) specified for re-execution operations performed with the ajsrerun command or JP1/AJS3 - View
The number of units added to the root jobnet, the suspend status of which was released with the ajssuspend command or JP1/AJS3 - View

Compare the value specified for pd_lck_pool_size with the value obtained with the applicable expression below. If the value of pd_lck_pool_size is smaller, change the value to the obtained value.

If the obtained value is smaller, because the amount of memory required for JP1/AJS3 might be insufficient, you need to re-estimate the amount of required memory. For details about how to estimate the amount of required memory, see 3. Estimates in the Job Management Partner 1/Automatic Job Management System 3 System Design (Configuration) Guide.

In cases 1, 2, 3, or 4 above

(a + b + c + d) / 4 x 1.2

a: (total-number-of-job-groups x 2) + total-number-of-years-in-the-calendar-defined-for-job-groups

b: (total-number-of-jobnets x 2) + total-number-of-schedule-rules-defined-for-all-jobnets

c: total-number-of-jobs x 2

d: total-number-of-relations-defined-for-jobs-and-jobnets
In cases 5, 6, or 7

e / 4 x 1.2

e: total-number-of-jobs-and-jobnets x 3

If the jobnets used in the calculation use the jobnet release function, perform the calculation by using the jobnet definition as the target of operation.

Cautionary note:

If you change the specified value of this operand to a larger value and then concurrently operate more units than the guideline for the database scale suggests, a message (KFPS01220-E) is output to the event log or to syslog and the embedded database might terminate abnormally. In such cases, reduce the number of units that are operated concurrently or consider configuring the embedded database on a larger scale.

For details about the guideline for the number of units, see B.1 Estimating the amount of required database area.
If you increase the value of this operand, the amount of memory used by the embedded database also increases proportionally. Before you change the value, make sure that there is sufficient memory.

In addition, if you change the specified value of this operand to a larger value in UNIX, adjust the system resources accordingly. For details about the system resources that need to be adjusted, see the Release Notes.

If the value of this operand is too small, an attempt to access JP1/AJS3 might result in an error.
The maximum value that can be specified for this operand is 2,000,000. However, if OS memory management cannot secure a continuous area, startup of the embedded database fails. If a continuous area cannot be secured, adjust the value so that a continuous area can be secured.

• Changing the system definition

To change the system definition:

Stop the JP1/AJS3 services.
Check the status of the target embedded database.
```
ajsembdbstatus -s ust -id _JF0^#
```
If the target embedded database is running, stop it normally. If the target embedded database is not running, start it, and then stop it normally.

Example of the command used to start an embedded database:
```
ajsembdbstart -id _JF0^#
```
Example of the command used to stop an embedded database normally:
```
ajsembdbstop -id _JF0^#
```
Using a text editor, open the system common definition file or a single server definition file.

Before performing this operation, create a backup of the file in case a problem occurs.
Change the value of the operand.
Save the change made in step 5, and then close the file.
In a cluster configuration, copy the changed system common definition file or the single server definition file to the standby host.
Start the JP1/AJS3 services that you stopped.

The embedded database is also started at this time.

#:: For the -id option, specify the setup identifier of the target embedded database. To start the embedded database in Windows, start the JP1/AJS3 Database _JFn (n: 0 to 9 or A to Z) service in advance.

Important note: If you use a multi-byte space or character, or add an unnecessary line-feed or space character in the system common definition or single server definition, startup of the JP1/AJS3 services fails.

(b) Database operations

Consider the following items related to embedded database operations:

Use of the system log data
Times at which the embedded database is backed up
Point up to which the embedded database is restored from the backup
Method for restoring the embedded database from the backup

■ Use of the system log data

The following describes operation when the system log is used for restoration. You can ignore this item if you do not use the system log for restoration.

Operation that uses unloading: In this method, the data output to a system log file is unloaded (that is, backed up) to another file. The contents of the system log files are unloaded automatically by the embedded database, at which time the system log file becomes available for reuse. However, since disk space is required to store the unloaded log files (called unload log files), available disk space must be monitored. In addition, when the system is restored, the unload log files must be specified in the correct order.

■ Times at which the embedded database is backed up

The embedded database can be backed up at either of the following times:

While the JP1/AJS3 service is stopped (while no jobs or jobnets are being executed): In this case, you must stop JP1/AJS3 when you back up the embedded database. This is the basic backup method. With this method, you can restore the status of the embedded database at the time it was backed up by using the obtained backup data only.
While the JP1/AJS3 service is running (when jobs and jobnets are being executed): In this case, it is not necessary to stop JP1/AJS3 when you back up the embedded database. However, the unload log file that has been output by the embedded database, together with the data you backed up, is necessary for restoration.

■ Point up to which the embedded database is restored from the backup

The embedded database can be restored from the backup up to the following times:

Time when the embedded database was backed up: In this case, you can restore the embedded database to the state existing at the time the embedded database was backed up. However, any updates made after the backup was acquired will not be restored.
Latest synchronization timepoint following backup of the embedded database: In this case, in addition to restoring the embedded database to the state existing at the time of the backup, you can also restore updates occurring after the backup, thereby restoring the database to the latest state.

■ Methods for restoring the embedded database from a backup

This subsection describes how you can restore the embedded database from backup data.

By using the backup data only: In this case, you use only the backup data to restore the embedded database. The embedded database is restored to the state existing at the time it was backed up.
By using the backup data and the system log data: In this case, you use the backup data and the system log information output after the backup to restore the embedded database. This method also restores any updates made to the database after the backup. Use this method to restore the embedded database if you use backup data obtained while JP1/AJS3 was running.

The following table shows the methods of embedded database operation.

Table C‒4: Methods of embedded database operation
No.		Method of operation
No.		System log	Time that the embedded database is backed up	Time up to which the embedded database is restored from the backup data	Method for recovering the embedded database from the backup data
A		Not used	While the JP1/AJS3 service is stopped	Up to the time when the embedded database was backed up	Backup data only
B	B-1	Unloading used	When the JP1/AJS3 service is stopped	Up to the time when the embedded database was backed up	Backup data only
	B-2		When the JP1/AJS3 service is stopped	Latest synchronization point	Backup data and system log data
	B-3		While the JP1/AJS3 service is running	Latest synchronization point	Backup data and system log data

The following table shows the advantages and disadvantages of each method of operation. Study this table before you select a method from Table C-4.

Table C‒5: Advantages and disadvantages of each method of operation
No.^#		Advantages and disadvantages
No.^#		Advantages	Disadvantages
A		Monitoring the status of the system log file is not required.	The embedded database can be restored only up to the time when it was backed up. The JP1/AJS3 service must be stopped during the backup.
B	Common	Monitoring the status of the system log file is not required.	The operating status of the automatic log unload functionality must be monitored. An unload log file creation directory must be created.
	B-1	If an error occurs in the system log file, the embedded database can be restored by using the backup data only.	The embedded database can be restored only up to the time when the database was backed up. The JP1/AJS3 service must be stopped during the backup.
	B-2	If an error occurs in the system log file, the embedded database can be restored by using the backup data only. The embedded database can be restored to the latest state in which updates made after the backup are reflected.	The JP1/AJS3 service must be stopped during the backup.
	B-3	The JP1/AJS3 service need not be stopped during the backup. The embedded database can be restored to the latest state, which includes updates made after the backup.	If the unload log file is lost, the embedded database cannot be recovered by using the backup data only.

#: The numbers in this table correspond to the numbers in Table C-4.

For details about the backup and how to restore the database from the backup data only, see the following:

5.4.1(1) Restoring the scheduler database from unload log files in the Job Management Partner 1/Automatic Job Management System 3 System Design (Configuration) Guide
5.4.1(2) Restoring the scheduler database without using the system log in the Job Management Partner 1/Automatic Job Management System 3 System Design (Configuration) Guide

When using a method you have selected in Table C-4, you need to use the following commands to set up the environment for the embedded database, back up the embedded database, and restore the embedded database from the backup data only:

ajsembdbbuild command (sets up the embedded database environment)
ajsembdbbackup command (backs up the embedded database)
ajsembdbrstr command (restores the embedded database from the backup data only)

The following table shows the options required when you execute these commands.

Table C‒6: Specifiable command options
No.^#		Duplicating system files	Options related to the restoration method and use of system log data
No.^#		Duplicating system files	ajsembdbbuild (-bs, -br, -bl)	ajsembdbbackup (-s)	ajsembdbrstr (-ld, -l)
A		Not available	Not available	Not available	Not available
B	B-1		`-bs -bl`	Not available	Not available
	B-2			Not available	`-ld` or `-l`
	B-3			`-s`	`-ld` or `-l`
A		Available	--	--	--
B	B-1		`-br -bl`	Not available	Not available
	B-2			Not available	`-ld` or `-l`
	B-3			`-s`	`-ld` or `-l`

Legend: --: Not applicable.
#:: The numbers in this table correspond to the numbers in Table C-4.

For details about the ajsembdbbuild command, see 2. Commands Used during Setup in the manual Job Management Partner 1/Automatic Job Management System 3 Command Reference 2.

For details about the ajsembdbbackup and ajsembdbrstr commands, see 2. Commands in the manual Job Management Partner 1/Automatic Job Management System 3 Command Reference 1.

(c) Setting a scheduler service environment

The advanced setup of an embedded database requires that you set the environment setting parameters associated with the scheduler service. To set the required environment setting parameter for a scheduler service to be added, execute the jajs_setup command with the -S option specified.

For details about the jajs_setup command, see jajs_setup in 2. Commands Used during Setup in the manual Job Management Partner 1/Automatic Job Management System 3 Command Reference 2.

For details on the environment setting parameters, see 2.2 Setting up the scheduler service environment in the Job Management Partner 1/Automatic Job Management System 3 Configuration Guide 2.

For example, execute the command as follows to set an environment for scheduler service AJSROOT2:

jajs_setup -F AJSROOT2 -a -n 2 -p jp1ajs2report2
 -d /var/opt/jp1ajs2/database/schedule/AJSROOT2
 -t /var/opt/jp1ajs2/tmp/schedule2
 -j /var/opt/jp1ajs2/jobinf2
 -b /var/opt/jp1ajs2/backup/schedule2 -S

To Page Top