7.2.12 Operands and options related to the client-group facility (command format)

This subsection explains the operands and options that are related to the client-group facility.

The client-group facility enables you to set the following groups:

Client groups
Command groups

To set each group, specify the adbcltgrp operand in the server definition. You can specify multiple adbcltgrp operands that set client groups. Note that you can specify only one adbcltgrp operand that sets a command group.

Note: You can use the adbls -d cltgrp command to check the groups that have been set with the adbcltgrp operand. For details about the adbls -d cltgrp command, see adbls -d cltgrp (Display Information on Client Groups and Command Groups) in the manual HADB Command Reference.

The maximum number of adbcltgrp operands that can be specified is determined by the following formula.

Formula (count)

[Figure]

Multi-node function: If you will be using the multi-node function, specify the same value in this operand for all nodes. However, you can specify different values for the -r and -e options. If you specify different values for nodes, determine the values of the -r and -e options according to the adb_sys_rthd_num operand value in the server definition.

Note

For details about client groups and command groups, see 2.12.1 Overview of the client-group facility.
For details about the adb_sys_max_users operand in the server definition, see the description of the adb_sys_max_users operand in 7.2.1 Operands related to system configuration (set format).
For details about the adb_sys_rthd_num operand in the server definition, see the description of the adb_sys_rthd_num operand in 7.2.2 Operands related to performance (set format).

The following subsections explain the adbcltgrp operand and options in the server definition for each group that is set.

[52] adbcltgrp (for setting a client group)

Sets a client group. You can specify for the client group the numbers of connections and processing real threads that can be used by the HADB clients that belong to that group.

-g client-group-name

~<character string> ((1 to 30 bytes))

Specify a name for the client group that is unique within the HADB server.

The permitted characters include single-byte numeric characters, single-byte uppercase letters, single-byte lowercase letters, and single-byte underscores (_). The first character must be a single-byte uppercase letter, a single-byte lowercase letter, or a single-byte underscore (_).

The client group name specified in this option must be specified in the adb_clt_group_name operand in the client definition.

Note: For details about the adb_clt_group_name operand in the client definition, see Operands related to system configuration in the HADB Application Development Guide.

-m maximum-number-of-concurrent-connections-for-the-specified-client-group

~<integer> ((0 to 1,024)) <<value of adb_sys_max_users - sum of the -u option values in all other adbcltgrp operands>>

Specify the maximum number of concurrent connections for the specified client group.

The value specified in this option is the maximum number of concurrent connections usable by this group. This group will not use more connections than specified in this option.

If this option is omitted, the value determined by the following formula is assumed.

Formula

[Figure]

The value from this formula is also assumed if the specified value is greater than the value obtained from the formula.

For details about the adb_sys_max_users operand in the server definition, see the description of the adb_sys_max_users operand in 7.2.1 Operands related to system configuration (set format).

Important: If 0 is specified in this option, the HADB clients belonging to this group will not be able to connect to the HADB server.

-u guaranteed-minimum-number-of-concurrent-connections-for-the-specified-client-group

~<integer> ((0 to 1,024)) <<0>>

Specify the guaranteed minimum number of concurrent connections for the specified client group.

This option determines the minimum number of concurrent connections that will always be made available to this group. The specified number of concurrent connections are usable by the local group regardless of the connection status of other HADB clients and commands.

Specify in this option a value that does not exceed the value of the -m option. Note also that the specified value must satisfy the condition shown below (if these conditions are not satisfied, an error will occur when the HADB server starts).

Formula

[Figure]

For details about the adb_sys_max_users operand in the server definition, see the description of the adb_sys_max_users operand in 7.2.1 Operands related to system configuration (set format).

Important

If the total-of-the-values-specified-for-the--u-option-of-the-adbcltgrp-operand-in-all-server-definitions is the same as the value-specified-for-the-adb_sys_max_users-operand-in-the-server-definition, the following HADB clients will not be able to connect to the HADB server:

HADB clients belonging to a group for which 0 is specified in the -u option of the adbcltgrp operand in the server definition
HADB clients that belong to no group

-r maximum-number-of-processing-real-threads-usable-by-the-specified-client-group

~<integer> ((0 to 4,096) <<value of adb_sys_rthd_num - sum of the -e option values in all other adbcltgrp operands>>

Specify the maximum number of processing real threads usable by the specified client group.

The value specified in this option is the maximum number of processing real threads usable by this group. This group will not use more processing real threads than specified in this option.

If this option is omitted, the value determined by the following formula is assumed.

Formula

[Figure]

The value from this formula is also assumed if the specified value is greater than the value obtained from the formula.

For details about the adb_sys_rthd_num operand in the server definition, see the description of the adb_sys_rthd_num operand in 7.2.2 Operands related to performance (set format).

Important

If 0 is specified in this option, 0 is assumed for the value of the adb_sql_exe_max_rthd_num operand that is applied to the HADB clients belonging to this group. This means that those HADB clients will be able to use only connection threads to execute SQL statements.

For details about the adb_sql_exe_max_rthd_num operand in the server definition, see the description of the adb_sql_exe_max_rthd_num operand in 7.2.2 Operands related to performance (set format).

For details about the adb_sql_exe_max_rthd_num operand in the client definition, see Operands related to performance in the HADB Application Development Guide.

-e guaranteed-minimum-number-of-processing-real-threads-usable-by-the-specified-client-group

~<integer> ((0 to 4,096)) <<0>>

Specify the guaranteed minimum number of processing real threads usable by the specified client group.

This option determines the minimum number of processing real threads that will always be made available to this group. The specified number of processing real threads are always usable by the local group regardless of other HADB clients' and commands' processing real thread usage status.

Specify in this option a value that does not exceed the value of the -r option. Note also that the specified value must satisfy the condition shown below (if these conditions are not satisfied, an error will occur when the HADB server starts).

Formula

[Figure]

For details about the adb_sys_rthd_num operand in the server definition, see the description of the adb_sys_rthd_num operand in 7.2.2 Operands related to performance (set format).

Important

If the total-of-the-values-specified-for-the--e-option-of-the-adbcltgrp-operand-in-all-server-definitions is the same as the value-specified-for-the-adb_sys_rthd_num-operand-value-in-the-server-definition, 0 is assumed as the value of the adb_sql_exe_max_rthd_num operand for the following HADB clients:

HADB clients belonging to a group for which 0 is specified in the -e option of the adbcltgrp operand in the server definition
HADB clients that belong to no group

These HADB clients will always use only connection threads to execute SQL statements.

For details about the adb_sql_exe_max_rthd_num operand in the server definition, see the description of the adb_sql_exe_max_rthd_num operand in 7.2.2 Operands related to performance (set format).

For details about the adb_sql_exe_max_rthd_num operand in the client definition, see Operands related to performance in the HADB Application Development Guide.

-w output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-the-specified-client-group[,reset-threshold-for-warning-message-output]

Specify this option to output the warning message KFAA40020-W when the number of concurrent connections approaches the maximum number of concurrent connections specified in the -m option.

The value specified for the -w option is invalid if you specify 0 in the -m option (this includes situations in which 0 is assumed).

output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-specified-client-group:

~<integer> ((0 to 100)) <<0>> (percent)

Specify the output threshold for the warning message KFAA40020-W as a proportion of the value specified for the -m option (the maximum number of concurrent connections applied to the client group). For example, if you specify 20 for the -m option and 90 as the output threshold, a warning message is output when the number of connections to the HADB server reaches 18 (which is 90% of 20).

If you specify 0 as the output threshold, the warning message will not be output.

Important: When groups share their freely usable number of connections with other groups (when different values are specified for the -m option and the -u option), those connections might be in use by the other groups. In this situation, an error resulting from the maximum number of concurrent connections being exceeded might occur before the warning message is output.

reset-threshold-for-warning-message-output:

~<integer> ((0 to 99)) (percent)

Specify the threshold for resetting the output state of the warning message KFAA40020-W as a proportion of the value specified for the -m option (the maximum number of concurrent connections applied to the client group). When the warning message has been output once, HADB registers a state in which the warning message has been output. In this state, the warning message is not output again until the number of connections to the HADB server has fallen below a specific value.

Note

The relationship between the value specified for the -w option and output of the warning message is as follows:

adbcltgrp -g ...
          -m 20
          -w 90,70

When the -m option and the -w option are specified in this way, the warning message is output when the number of connections to the HADB server reaches 18 (90% of 20). Subsequently, if the number of connections to the HADB server falls to 17 before rising again to 18, HADB will not output the warning message again.

However, if the number of connections to the HADB server falls to 14 (70% of 20) or below, the state in which the warning message has been output is reset. This means that subsequently, the warning message will be output again when the number of connections to the HADB server reaches 18 or higher.

Notes regarding the threshold for resetting the warning message output state are as follows:

If you do not specify a reset threshold, a value equivalent to output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-specified-client-group - 30 is assumed. If this results in a negative value, 0 is assumed.
Specify the operand so that output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-specified-client-group > reset-threshold-for-warning-message-output. If this condition is not satisfied, the reset threshold specification is invalid (the warning message KFAA41000-W is output). In this case, a value equivalent to output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-specified-client-group - 30 is assumed.
If you specify 0 for output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-specified-client-group, the reset threshold specification is invalid.
HADB clients that do not belong to a client group are subject to the value specified for the adb_sys_max_users_wrn_pnt operand.
If you define client groups, a warning message is not output even if the system as a whole exceeds the ratio specified in the adb_sys_max_users_wrn_pnt operand. The warning message is only output when a client group exceeds the ratio specified for that client group.

Multi-node function: The warning message KFAA40020-W is output on the master node.

[53] adbcltgrp (for setting a command group)

Sets a command group. You can specify for the command group the numbers of connections and processing real threads that can be used by the commands belonging to that group. This operand can be specified only once (only one command group can be set).

-g command

Sets a command group.

When an adbcltgrp operand that includes this option is specified, all commands that connect to the HADB server will belong to the command group that is set up. For details about the commands that connect to the HADB server, see List of commands in the manual HADB Command Reference.

Note

In addition to the commands that connect to the HADB server, HADB clients can also belong to the command group. To specify an HADB client as a member of the command group, specify command in the adb_clt_group_name operand in the client definition.

For details about the adb_clt_group_name operand in the client definition, see Operands related to system configuration in the HADB Application Development Guide.

-m maximum-number-of-concurrent-connections-for-the-specified-command-group

~<integer> ((0 to 1,024)) <<value of adb_sys_max_users - sum of the -u option values in all other adbcltgrp operands>>

Specify the maximum number of concurrent connections for the specified group.

The value specified in this option is the maximum number of concurrent connections usable by this group. This group will not use more connections than specified in this option.

If this option is omitted, the value determined by the following formula is assumed.

Formula

[Figure]

The value from this formula is also assumed if the specified value is greater than the value obtained from the formula.

For details about the adb_sys_max_users operand in the server definition, see the description of the adb_sys_max_users operand in 7.2.1 Operands related to system configuration (set format).

Important: If 0 is specified in this option, the commands belonging to this group will not be able to connect to the HADB server.

-u guaranteed-minimum-number-of-concurrent-connections-for-the-specified-command-group

~<integer> ((0 to 1,024)) <<0>>

Specify the guaranteed minimum number of concurrent connections for the specified command group.

This option determines the minimum number of concurrent connections that will always be made available to this command group. The specified number of concurrent connections are usable by the command group regardless of the connection status of other HADB clients and commands.

[Figure]

For details about the adb_sys_max_users operand in the server definition, see the description of the adb_sys_max_users operand in 7.2.1 Operands related to system configuration (set format).

Important

If the total of the values specified for the -u option of the adbcltgrp operand in all server definitions is the same as the value specified for the adb_sys_max_users operand in the server definition, the following commands will not be able to connect to the HADB server:

Commands belonging to a group for which 0 is specified in the -u option of the adbcltgrp operand in the server definition
Commands that belong to no group

-r maximum-number-of-processing-real-threads-usable-by-the-specified-command-group

~<integer> ((0 to 4,096) <<value of adb_sys_rthd_num - sum of the -e option values in all other adbcltgrp operands>>

Specify the maximum number of processing real threads usable by the specified command group.

The value specified in this option is the maximum number of processing real threads usable by this group. This group will not use more processing real threads than specified in this option.

If this option is omitted, the value determined by the following formula is assumed.

Formula

[Figure]

The value from this formula is also assumed if the specified value is greater than the value obtained from the formula.

For details about the adb_sys_rthd_num operand in the server definition, see the description of the adb_sys_rthd_num operand in 7.2.2 Operands related to performance (set format).

When you set a command group and you will be executing commands listed under Targeted commands in the explanation of the adb_sys_rthd_num operand in 7.2.2 Operands related to performance (set format), specify a value in this option that is at least the minimum number of processing real threads required. If you do not specify a value at least equal to the minimum number of processing real threads required, execution of the command might result in an error. For details about the minimum number of processing real threads required to execute each command, see Table 6‒28: Operands and command options for specifying the number of processing real threads to be used for command execution in (2) Operands and command options for specifying the number of processing real threads to be used for command execution under 6.23.2 Points to consider about the number of processing real threads to be used during command execution.

Important: If 0 is specified in this option, 0 is assumed for the value of the adb_sys_rthd_num operand that is applied to the commands belonging to this command group. This means that an error will result when those commands are executed, due to insufficient processing real threads.

-e guaranteed-minimum-number-of-processing-real-threads-usable-by-the-specified-command-group

~<integer> ((0 to 4,096)) <<0>>

Specify the guaranteed minimum number of processing real threads usable by the specified command group.

Formula

[Figure]

For details about the adb_sys_rthd_num operand in the server definition, see the description of the adb_sys_rthd_num operand in 7.2.2 Operands related to performance (set format).

Important

If the total of the values specified for the -e option of the adbcltgrp operand in all server definitions is the same as the value specified for the adb_sys_rthd_num operand value in the server definition, 0 is assumed as the value of the adb_sys_rthd_num operand for the following commands:

Commands belonging to a group for which 0 is specified in the -e option of the adbcltgrp operand in the server definition
Commands that belong to no group

An error will result if these commands are executed, due to insufficient processing real threads.

-w output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-the-specified-command-group[,reset-threshold-for-warning-message-output]

Specify this option to output the warning message KFAA40020-W when the number of concurrent connections approaches the maximum number of concurrent connections specified in the -m option.

The value specified for the -w option is invalid if you specify 0 in the -m option (this includes situations in which 0 is assumed).

output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-specified-command-group:

~<integer> ((0 to 100)) <<0>> (percent)

Specify the output threshold for the warning message KFAA40020-W as a proportion of the value specified for the -m option (the maximum number of concurrent connections applied to the command group). For example, if you specify 20 for the -m option and 90 as the output threshold, a warning message is output when the number of connections to the HADB server reaches 18 (which is 90% of 20).

If you specify 0 as the output threshold, the warning message will not be output.

Important: When groups share their freely usable number of connections with other groups (when different values are specified for the -m option and the -u option), those connections might be in use by the other groups. In this situation, an error resulting from the maximum number of concurrent connections being exceeded might occur before the warning message is output.

reset-threshold-for-warning-message-output:

~<integer> ((0 to 99)) (percent)

Specify the threshold for resetting the output state of the warning message KFAA40020-W as a proportion of the value specified for the -m option (the maximum number of concurrent connections applied to the command group). When the warning message has been output once, HADB registers a state in which the warning message has been output. In this state, the warning message is not output again until the number of connections to the HADB server has fallen below a specific value.

Note

The relationship between the value specified for the -w option and output of the warning message is as follows:

adbcltgrp -g ...
          -m 20
          -w 90,70

Notes regarding the threshold for resetting the warning message output state are as follows:

If you do not specify a reset threshold, a value equivalent to output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-specified-command-group - 30 is assumed. If this results in a negative value, 0 is assumed.
Specify the operand so that output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-specified-command-group > reset-threshold-for-warning-message-output. If this condition is not satisfied, the reset threshold specification is invalid (the warning message KFAA41000-W is output). In this case, a value equivalent to output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-specified-command-group - 30 is assumed.
If you specify 0 for output-threshold-for-warning-message-regarding-maximum-number-of-concurrent-connections-for-specified-command-group, the reset threshold specification is invalid.
Commands that do not belong to a command group are subject to the value specified for the adb_sys_max_users_wrn_pnt operand.
If you define a command group, a warning message is not output even if the system as a whole exceeds the ratio specified in the adb_sys_max_users_wrn_pnt operand. The warning message is only output when the command group or a client group exceeds the specified ratio.

To Page Top