SET_SERVER_SBS_ROUTING procedure

The SET_SERVER_SBS_ROUTING procedure provides the ability to configure a server to use an alternate subsystem. This can be for Start of change all users of the server, for a specific user profile, or by IP address End of change .

This procedure allows an administrator to reposition certain connections to a server into an alternate, non-default, subsystem. When configured, new incoming TCP/IP server connections will use the alternate subsystem.

Connections to be re-routed can be defined three ways.

A server's default subsystem for all connections.
For an IP address or a range of IP addresses.
For a specific user profile. The user profile can be a group profile or a supplemental group profile. Some servers do not support routing by specific user profile; refer to Table 1 for details.

Start of change To select the subsystem for a connection, the routing logic first looks for an IP address routing entry for the server. If there is not one, it will route according to the defined default. The routing process will then immediately check for a configured entry for the specific user profile and attempt to route to its subsystem. For example, if a server is configured to route to a user-specified subsystem by incoming TCP/IP address as well as by user profile, the job will first attempt to route to the subsystem configured for that TCP/IP address and then immediately attempt to route to the subsystem configured for the connecting user profile. Understanding this order of processing is key to recognizing failures that may occur. End of change

By default, all users for the following servers use the listed default subsystem:

Table 1. Servers and default subsystems
Server Description	Server Name	Default subsystem	Supports routing by user	Supports routing by IP address
Central server	QZSCSRVS	QUSRWRK	Yes	Yes
Database server	QZDASOINIT	QUSRWRK	Yes	Yes
Data queue server	QZHQSSRV	QUSRWRK	Yes	Yes
Db2® Mirror server	QDBMSRVR	QUSRWRK	Yes	Yes
DDM	QRWTSRVR	QUSRWRK	Yes	Yes
DRDA	QRWTSRVR	QUSRWRK	Yes	Yes
File server	QPWFSERVSO	QSERVER	Yes	Yes
IBM® i NetServer	QZLSFILE	QSERVER	No	Yes
Network print server	QNPSERVS	QUSRWRK	Yes	Yes
Remote command server	QZRCSRVS	QUSRWRK	Yes	Yes
Sign-on server	QZSOSIGN	QUSRWRK	No	Yes

For more information on these servers see DRDA and DDM overview and Host servers by function.

Routing information set by this procedure can be queried using the following views:

For routing for a specific user, see SERVER_SBS_ROUTING view.
For routing that applies to all users and IP addresses, see SERVER_SBS_CONFIGURATION view.

Authorization:

When authorization-name specifies a user profile, the caller must have:
- *SECADM special authority, and
- *OBJMGT and *USE authorities to the user profile.
When authorization-name is *ALL, the caller must have *IOSYSCFG special authority.

The schema is QSYS2.

authorization-name

A character or graphic string expression that identifies an existing user or group profile name. Can contain the following special value: Start of change

*ALL: This configuration applies to all users of the server unless a specific alternate subsystem is defined for the user. To route using an IP address, *ALL must be specified.

server-name

A character or graphic string expression that identifies the name of the server job that will be rerouted to subsystem-name for all users or for authorization-name whenever a connection is initiated to this server job. Valid server-name values are:

QDBMSRVR
QNPSERVS
QPWFSERVSO
QRWTSRVR
QZDASOINIT
QZHQSSRV
QZLSFILE
QZRCSRVS
QZSCSRVS
QZSOSIGN

The special value of *ALL can be used to indicate all of the server-name values that support routing by user, listed in Table 1. *ALL is not allowed if authorization-name is *ALL.

subsystem-name

A character or graphic string expression that identifies the name of the subsystem that will be used, instead of the default subsystem, whenever a connection is initiated to the specified server job. No validation is done on subsystem-name to make sure it is a valid and active subsystem.

If subsystem-name is the null value:

When authorization-name is not *ALL, the configuration entry for the server-name for this authorization-name will be cleared. The default subsystem will revert to the system supplied default as shown in Table 1.
When authorization-name is *ALL:
- If ip-address-start is not specified, the configuration entry for the server-name will be removed, reverting incoming connections to use the default subsystem.
- If ip-address-start is specified, the configuration entry identified by the server-name and the specified ip-address-start will be removed.

allow-rollover

A character or graphic string expression that indicates the action to take if the specified subsystem is not active. Valid values are:

NO: If the alternate subsystem cannot be used, the connection request will fail.
YES: If the alternate subsystem cannot be used, the connection request will succeed by using a batch immediate job in the default subsystem.

If this parameter is not specified, the default is YES.

Start of change When routing for the server (authorization-name is *ALL), the following parameters are allowed: End of change

ip-address-start

A character or graphic string expression that identifies an IPv4 or IPv6 address for a single client.

If ip-address-end is not specified, this is a specific IPv4 or IPv6 address.
If ip-address-end is specified, this is the start value for a range of IPv4 or IPv6 addresses for a group of clients. When more than one range of addresses is defined for a server, the IP address ranges cannot overlap.

When ip-address-start is specified, either subnet-mask or prefix-length can be specified.

This parameter can only be specified when authorization-name is *ALL. If this parameter is not specified, the default is the null value, meaning that the connection will not be routed by IP address.

ip-address-end

A character or graphic string expression that identifies the end value for a range of IPv4 or IPv6 addresses for a group of clients. This parameter can only be specified if ip-address-start is specified.

This parameter can only be specified when authorization-name is *ALL. If this parameter is not specified, the default is the null value.

subnet-mask

A character or graphic string expression that identifies the IPv4 subnet mask.

This parameter can only be specified when authorization-name is *ALL. subnet-mask cannot be specified if prefix-length is specified.

prefix-length

An integer value that defines how many bits of the IPv6 address are in the prefix. When this parameter is specified with a non-zero value, the IP address parameters are treated as IPv6 addresses. It is required for an IPv6 address.

This parameter can only be specified when authorization-name is *ALL. prefix-length cannot be specified if subnet-mask is specified.

server-position

An integer value that indicates the position for this entry for server-name in the list returned by the QSYS2.SERVER_SBS_CONFIGURATION view in the SERVER_SEARCH_ORDER column. This value represents the search order to be used when determining which entry to use for routing.

This entry will be added at the specified position in the list for server-name. An existing entry at this position and all later entries will have their search order position incremented by one. If this value is greater than the current number of entries for the server, this entry will be added to the end of the server's list.

This parameter can only be specified when authorization-name is *ALL. If this parameter is not specified, the default is the null value. This means that a new entry will be added to the end of the list, and a change to an existing IP address entry will remain in its current position.

replacement-ip-address-start

A character or graphic string expression that identifies a replacement IPv4 or IPv6 address for the specified ip-address-start address. ip-address-start must already be configured for this server.

This parameter can only be specified when authorization-name is *ALL. If this parameter is not specified, the default is the null value.

replacement-ip-address-end

A character or graphic string expression that identifies a replacement IPv4 or IPv6 address for the specified ip-address-end address. ip-address-end must already be configured for this server.

This parameter can only be specified when authorization-name is *ALL. If this parameter is not specified, the default is the null value.

text-description

A character or graphic string expression describing this configuration.

This parameter can only be specified when authorization-name is *ALL. If this parameter is not specified, the default is the null value.

Notes®

The prestart job entry must specify the subsystem-name.

When ALLOW_ROLLOVER is YES: if, for any reason, the alternate subsystem cannot be used to establish the connection, the connection will run in the default subsystem (or the last subsystem it was successfully routed to) as a batch immediate job. An example of this would be if the authorization-name does not have *USE authority to the subsystem description for subsystem-name.

If routing has been configured for a user profile, the user profile configuration will always be used, regardless of any group profile configuration or a subsystem configuration for *ALL. A group profile configuration will take precedence over any supplemental group profile configuration.

Examples

Set new incoming DRDA and DDM TCP/IP server connections for user profile TIM to route to subsystem TIMSUBSYS.
```
CALL QSYS2.SET_SERVER_SBS_ROUTING('TIM','QRWTSRVR','TIMSUBSYS')
```
Reset incoming DRDA and DDM TCP/IP server connections for user profile TIM back to the original default subsystem.
```
CALL QSYS2.SET_SERVER_SBS_ROUTING('TIM','QRWTSRVR',NULL)
```
Configure group profile ADMIN to use an alternate subsystem for all of the servers supported by this procedure. Do not permit a connection request to rollover to use QUSRWRK.
```
CALL QSYS2.SET_SERVER_SBS_ROUTING('ADMIN','*ALL','ADHOCSBS','NO')
```
Set new incoming Database server TCP/IP connections for user profile BOB to route to subsystem BOBSUBSYS.
```
CALL QSYS2.SET_SERVER_SBS_ROUTING('BOB','QZDASOINIT','BOBSUBSYS')
```

Construct a subsystem that will constrain the amount of system resources available to users who are known to execute expensive queries.

CRTSBSD SBSD(QGPL/ADHOCSBS) POOLS((1 *BASE)) TEXT('Adhoc DRDA users SBS')

CRTCLS CLS(QGPL/ADHOCCLS) RUNPTY(55) TIMESLICE(100) TEXT('Adhoc DRDA users class')

ADDPJE SBSD(QGPL/ADHOCSBS) PGM(QSYS/QRWTSRVR) JOBD(QGPL/QDFTSVR) CLS(QGPL/ADHOCCLS)

STRSBS SBSD(QGPL/ADHOCSBS)

CALL QSYS2.SET_SERVER_SBS_ROUTING('SLFUSER','QRWTSRVR','ADHOCSBS')

Set all Db2 Mirror connections to run in subsystem QDBMWRK. This separates the jobs from the default QUSRWRK subsystem. Make sure the pool for the subsystem description has sufficient memory available.

CRTSBSD SBSD(QSYS/QDBMWRK) POOLS((1 *BASE))

ADDPJE SBSD(QDBMWRK) PGM(QSYS/QDBMSRVR) USER(QUSER) STRJOBS(*YES) INLJOBS(50) THRESHOLD(20) 
    ADLJOBS(40) MAXJOBS(*NOMAX) JOB(*PGM) JOBD(QSYS/QDBMSRVR) MAXUSE(*NOMAX) WAIT(*YES) 
    POOLID(1) CLS(QSYS/QSYSCLS20 *CALC *NONE *CALC)

STRSBS QSYS/QDBMWRK

CALL QSYS2.SET_SERVER_SBS_ROUTING('*ALL','QDBMSRVR','QDBMWRK')

Define a complete block of IP addresses to be routed to subsystem NEWSBS for QZDASOINIT jobs. The range includes all addresses in the address block of 192.168.1.0-255

CALL QSYS2.SET_SERVER_SBS_ROUTING(AUTHORIZATION_NAME => '*ALL',
                                  SERVER_NAME => 'QZDASOINIT',
                                  IP_ADDRESS_START => '192.168.1.0', 
                                  SUBNET_MASK => '255.255.255.0' 
                                  SUBSYSTEM_NAME => 'NEWSBS')

Define a range of IP addresses for QZDASOINIT jobs to be routed to a subsystem NEWSBS.

CALL QSYS2.SET_SERVER_SBS_ROUTING(AUTHORIZATION_NAME => '*ALL',
                                  SERVER_NAME => 'QZDASOINIT',
                                  IP_ADDRESS_START => '192.168.1.10', 
                                  IP_ADDRESS_END => '192.168.1.30', 
                                  SUBSYSTEM_NAME => 'NEWSBS')

Change the range of IP addresses for QZDASOINIT jobs that are routed to a subsystem NEWSBS.

CALL QSYS2.SET_SERVER_SBS_ROUTING(AUTHORIZATION_NAME => '*ALL',
                                  SERVER_NAME => 'QZDASOINIT',
                                  IP_ADDRESS_START => '192.168.1.10', 
                                  IP_ADDRESS_END => '192.168.1.30', 
                                  REPLACEMENT_IP_ADDRESS_START => '192.168.1.10', 
                                  REPLACEMENT_IP_ADDRESS_END => '192.168.1.100', 
                                  SUBSYSTEM_NAME => 'NEWSBS')

Remove a range of IP addresses for QZRCSRVS jobs.

CALL QSYS2.SET_SERVER_SBS_ROUTING(AUTHORIZATION_NAME => '*ALL',
                                  SERVER_NAME => 'QZRCSRVS',
                                  SUBSYSTEM_NAME => NULL,
                                  IP_ADDRESS_START => '192.168.1.10', 
                                  IP_ADDRESS_END => '192.168.1.100')

Add a new entry in the first position in the prioritized list of IP address routing entries for the QPWFSERVSO server.

CALL QSYS2.SET_SERVER_SBS_ROUTING(AUTHORIZATION_NAME => '*ALL',
                                  SERVER_NAME => 'QPWFSERVSO',
                                  SUBSYSTEM_NAME => 'SBS1',
                                  IP_ADDRESS_START => '192.168.2.20', 
                                  SERVER_POSITION => 1,
                                  TEXT_DESCRIPTION => 'Top rule for QPWFSERVSO')