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 changeall users of the server, for a specific user profile, or by IP addressEnd 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.

Start of changeConnections to be re-routed can be defined three ways.
  1. For all users of the server.
  2. For an IP address or a range of IP addresses.
  3. 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

Start of changeRouting 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.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
DDM QRWTSRVR QUSRWRK Yes Yes
DRDA QRWTSRVR QUSRWRK Yes Yes
File server QPWFSERVSO QSERVER Yes Yes
Start of changeIBM i NetServerEnd of change Start of changeQZLSFILEEnd of change Start of changeQSERVEREnd of change Start of changeNoEnd of change Start of changeYesEnd of change
Network print server QNPSERVS QUSRWRK Yes Yes
Remote command server QZRCSRVS QUSRWRK Yes Yes
Start of changeSign-on serverEnd of change Start of changeQZSOSIGNEnd of change Start of changeQUSRWRKEnd of change Start of changeNoEnd of change Start of changeYesEnd of change

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

Start of change
Routing information set by this procedure can be queried using the following views:
End of change
Authorization:
  • 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.
  • Start of changeWhen authorization-name is *ALL, *IOSYSCFG special authority is requiredEnd of change
Read syntax diagramSkip visual syntax diagramSET_SERVER_SBS_ROUTING( AUTHORIZATION_NAME =>  authorization-name, SERVER_NAME =>  server-name, SUBSYSTEM_NAME =>  subsystem-name,ALLOW_ROLLOVER => allow-rollover,IP_ADDRESS_START => ip-address-start,IP_ADDRESS_END => ip-address-end,SUBNET_MASK => subnet-mask,PREFIX_LENGTH => prefix-length,SERVER_POSITION => server-position,REPLACEMENT_IP_ADDRESS_START => replacement-ip-address-start,REPLACEMENT_IP_ADDRESS_END => replacement-ip-address-end,TEXT_DESCRIPTION => text-description)
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.
End of change
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
  • Start of changeQZLSFILEEnd of change
  • QZRCSRVS
  • QZSCSRVS
  • Start of changeQZSOSIGNEnd of change
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.
  • Start of changeWhen 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.
    End of change
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 changeWhen routing for all users of the server (authorization-name is *ALL), the following parameters are allowed:End of change

Start 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.
End of change

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')
  • Start of changeDefine 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')
    End of change
  • Start of changeDefine 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')
    End of change
  • Start of changeChange 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')
    End of change
  • Start of changeRemove 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')
    End of change
  • Start of changeAdd 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')
    End of change