News
Abstract
New function allows Host Server connections to be routed to a subsystem based on the user ID being used for the connection.
Content
The concept is similar to the functionality that enables routing 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, 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 by running an 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.
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?
Once you create your prestart job entries, you want to route the connections for a particular user to the subsystem that those jobs 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 user profile is the one that is used to establish the connection to the particular server.
The second parameter is the name of the server that is affected. The program names and servers that can be routed are:
- QRWTSRVR - DRDA/DDM server
- QZDASOINIT - Database host server
- QZRCSRVS - Remote command server
- QZHQSSRV - Data queue server
- QZSCSRVS - Central server
- QPWFSERVSO - File server
- QNPSERVS - Network print server
- *ALL - All of the previous servers
The third parameter is the name of the subsystem to which the connections are routed when prestart jobs are available in that subsystem.
The fourth, optional parameter is known as allow-rollover. It controls what happens when a prestart job is not available within the specified subsystem. The possible values 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 for the Database and File servers). When set to NO the connection is rejected when 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 created my own subsystem, MIKSBS. MIKSBS has prestart job entries for all of the programs listed previously. I start run SQL scripts in IBM i Access Client Solutions and I run the following SQL statements:
CALL QSYS2.SET_SERVER_SBS_ROUTING('MIKSWENS', 'QZDASOINIT', 'MIKSBS');
CALL QSYS2.SET_SERVER_SBS_ROUTING('MIKSWENS', 'QRWTSRVR', 'MIKSBS');
SELECT * FROM QSYS2.SERVER_SBS_ROUTING WHERE AUTHORIZATION_NAME='MIKSWENS';
The first two statements cause connections for the MIKSWENS profile to the database host server and DDM/DRDA TCP server to be made to prestart jobs in the MIKSBS subsystem. The last statement returns the current configuration information for user profile MIKSWENS.
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 use the defaults for those particular services. Notice also that for each service the rollover behavior is YES. That means that if no prestart job is available in the MIKSBS subsystem, a batch-immediate job starts in the subsystem from which the start service request originated.
As another example I ran the statement:
CALL QSYS2.SET_SERVER_SBS_ROUTING('DUMMY', '*ALL', 'MIKSBS');
Then, I queried the routing information again (see Fig. 2). Notice that all of the services subsystem values were set to the MIKSBS subsystem.
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:
CALL QSYS2.SET_SERVER_SBS_ROUTING('DUMMY', '*ALL', 'MIKSBS', 'NO');
And select the data again, notice that the rollover values are all set 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 remove the entry 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.
CALL QSYS2.SET_SERVER_SBS_ROUTING('MIKSWENS', 'QRWTSRVR', NULL);
To remove all the customizations that I put in place for these two users, I can run the following statements:
CALL QSYS2.SET_SERVER_SBS_ROUTING('MIKSWENS', '*ALL', NULL);
CALL QSYS2.SET_SERVER_SBS_ROUTING('DUMMY', '*ALL', NULL);
What happens when you use both of the customization features at once?
The route-by-IP-address function runs first and sets 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.
Note:
Since the route-by-ip-address function takes precedence, by default, the connection is initially passed to a job in QUSRWRK. The host server then passes the socket connection to the job in the custom subsystem specified for the USRPRF. This mechanism causes 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)
Related Information
Was this topic helpful?
Document Information
Modified date:
26 February 2024
UID
nas8N1021000