IBM Support

Routing Connections to Subsystems Based On User ID



New function allows Host Server connections to be routed to a subsystem based on the user ID being used for the connection.


The concept is similar to the functionality that allows you to route connections to different subsystems based on the originating IP address (which is referred to as routing-by-IP-address). To see details on how to set up custom routing of your connections by IP address, you should refer to technote N1019587, Host Server Customization, Routing Connections By IP address. There are a couple of important differences though.

First, this feature is configured by using the stored procedure SET_SERVER_SBS_ROUTING, which must be called through an SQL interface such as interactive SQL or run SQL scripts. Configuration is checked via SQL SELECT statement.

Second, it cannot be used for secure connections (TLS - Transaction Layer Security, formerly known as SSL - Secure Socket Layer) until IBM i version 7.5.

As with the earlier feature, you must first create a subsystem description or modify an existing one so that it has the prestart job entries to support running the jobs that you are adding to this subsystem. You can check the prestart job entries on the QUSRWRK subsystem description to see what the IBM-supplied defaults look like (DSPSBSD QUSRWRK, Option 10, then Option 5 on the specific prestart job entry).

How do I set and check the customization?

Assuming that you have already created your prestart job entries and now want to route the connections for a particular user to the subsystem that those run in, you must call the stored procedure to configure this change. The stored procedure to call is QSYS.SET_SERVER_SBS_ROUTING. It requires 3 parameters and can accept 4. The first parameter is the user profile that is to be affected. This is the user profile that is used to establish the connection to the particular server.

The second parameter is the name of the server which should be affected. The servers/program names that can be routed are:

  • QRWTSRVR - DRDA/DDM server
  • QZDASOINIT - Database host server
  • QZRCSRVS - Remote command server
  • QZHQSSRV - Data queue server
  • QZSCSRVS - Signon server
  • QPWFSERVSO - File server
  • QNPSERVS - Network print server
  • *ALL - All of the above

The third parameter is the name of the subsystem to which the connections shall be routed if prestart jobs are available in that subsystem.

The fourth, optional parameter is known as allow-rollover. It controls what will happen if a prestart job is not available within the specified subsystem. The possible values that it will accept are YES or NO. When set to YES, the behavior is to start a batch-immediate job in the subsystem that the start request came from (that is normally going to be QSYSWRK or QSERVER in the case of the Database and File servers). When set to NO the connection is rejected if the prestart job is not available in the specified subsystem. The default value if no argument is supplied for this parameter is YES.

As an example, I have created my own subsystem, MIKSBS, that has prestart job entries for all of the programs listed above. Now I start run SQL scripts in IBM i Access Client Solutions and I run the following SQL statements:


The first two statements cause connections for the MIKSWENS profile to the database host server and DDM/DRDA TCP server respectively, to be made to prestart jobs in the MIKSBS subsystem. The last statement will return the current configuration information for user profile MIKSWENS.

The result of running the SQL statement These results show that for the MIKSWENS profile, connections for database and DRDA services are served by jobs in the prestart jobs in the MIKSBS subsystem. The remaining services will use the defaults for those particular services. Notice also that for each service the rollover behavior is YES. That means that in the event that no prestart job is available in the MIKSBS, maybe because it isn't started, or a maximum number of jobs were specified, a batch-immediate job will start in the subsystem from which the start service request originated.

As another example I ran the statement:


Then queried the routing information again (see Fig. 2). Notice that all of the services subsystem values were set to the MIKSBS subsystem.

Routing data for a user after selecting *ALL servers.
If I want to update that last one so that the user is rejected from these connections when the MIKSBS subsystem is not available I could execute the statement:


And select the data again, notice that the rollover values are all set to 'NO'.

Routing data for Dummy user after setting the rollover action to NO

How do I remove a customization?

To remove a customization for a user, call the stored procedure SET_SERVER_SBS_ROUTING with a null for the subsystem value. For example, I do not want my DRDA connections to go to this subsystem, so I will remove and check the configuration. In Run SQL Scripts, I run the following two statements: the first to remove the customization for the QRWTSRVR jobs and the second to check the configuration.


To remove all the customizations that I put in place for these two users, I can run the following statements:


What happens if you use both of the customization features at once?

The route-by-IP-address function will run first and set the subsystem defined for the address as the current subsystem for the connection. If the prestart jobs in that subsystem are not available (because the subsystem is not active or for any other reason) then the reject option is imposed and the connection is rejected with no further processing. If the prestart jobs are available, then the routing by user ID functionality is checked.


Since the route-by-ip-address function takes precedence, by default, the connection will initially be to the job in QUSRWRK. The host server then passes the socket connection to the job in the custom subsystem specified for the USRPRF. This will cause a single client connection to generate two CPIAD09 messages in the QHST log - one for the route-by-ip-address into QUSRWRK and a second to route to the custom subsystem based on USRPRF.

Historical information:

The functionality was added to the operating system with 7.1 technical refresh TR10 (TR2 for 7.2) and DB2 group PTF level 38 for 7.1 or level 9 for 7.2. This functionality is built into the base of 7.3 and all subsequent operating system versions.

(note that PTFs SI59913 - 7.1; SI59914 - 7.2; SI59915 - 7.3 are required to use this functionality with the central, data queue, print and file host server jobs. - See APAR SE64267 )

[{"Type":"MASTER","Line of Business":{"code":"LOB57","label":"Power"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000000CGmAAM","label":"Host Servers"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"7.1.0;7.2.0;7.3.0;7.4.0;7.5.0"}]

Document Information

Modified date:
09 June 2022