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 all users of the server, for a specific user
profile, or by IP address
.
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.
![Start of change](./delta.gif)
- For all users of the server.
- 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.
![End of change](./deltaend.gif)
Routing will possibly be attempted for one entry from each of the three re-routing
methods. First, it will consider an entry for all users of the server and attempt to route
according to that entry. Then it will immediately attempt to route by IP address, if there is an
appropriate entry. Finally, it will use a configuration option for a specific user profile and
attempt to route to that 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.
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 |
DDM | QRWTSRVR | QUSRWRK | Yes | Yes |
DRDA | QRWTSRVR | QUSRWRK | Yes | Yes |
File server | QPWFSERVSO | QSERVER | Yes | Yes |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
Network print server | QNPSERVS | QUSRWRK | Yes | Yes |
Remote command server | QZRCSRVS | QUSRWRK | Yes | Yes |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
For more information on these servers see DRDA and DDM overview and Host servers by function.
![Start of change](./delta.gif)
- 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.
![End of change](./deltaend.gif)
- When authorization-name specifies a user profile:
- The user calling this procedure must have *SECADM special authority.
- *OBJMGT and *USE authority is required to the user profile.
When authorization-name is *ALL, *IOSYSCFG special authority is required
- authorization-name
- A character or graphic string expression that identifies an existing user or group profile name.
Can contain the following special value:
- *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:
- QNPSERVS
- QPWFSERVSO
- QRWTSRVR
- QZDASOINIT
- QZHQSSRV
QZLSFILE
- QZRCSRVS
- QZSCSRVS
QZSOSIGN
- 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.
- 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.
When routing for all users of the server (authorization-name is *ALL),
the following parameters are allowed:
![Start of change](./delta.gif)
- 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.
- 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.
- subnet-mask
- A character or graphic string expression that identifies the IPv4 subnet mask.
- 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.
- 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.
- 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.
- 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.
- text-description
- A character or graphic string expression describing this configuration.
![End of change](./deltaend.gif)
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')
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 that are routed to a subsystem NEWSBS.
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')