IBM Support

Isolating a Client Connection to a Specific Subsystem for Debug Purposes

Troubleshooting


Problem

This document describes how to isolate a client so that its connections are serviced by jobs in a subsystem separate from those jobs used by others on the system.

Symptom

It may be necessary to gather diagnostic materials for a specific client connection while the system is in production. This scenario may benefit from isolating the specific client in its own custom subsystem. This allows diagnostics to be running over a job before the client makes the connection and prevents the gathering of diagnostic materials over unrelated production workloads.
Presently, the IBM i NetServer, DDM, DRDA, and host server programs can take advantage of features that allow for the connection to be routed to its own subsystem.

Resolving The Problem

The steps are:
  • Create a custom subsystem
  • Modify the TCP/IP server to use this subsystem
To create a custom subsystem, it is easiest to copy the subsystem description for the subsystem that is presently used for all users. For the host servers, other than the file server, that subsystem is QUSRWRK. For the file server and IBM i NetServer, the subsystem description to copy is QSERVER. Then, you must modify the subsystem to remove items that would conflict with the present systems and modify the prestart job entry or entries for the jobs that you need to service.

Step 1: Create a debug job description that we can use to ensure that job logs get printed for our debug purposes. We do not want every user leaving job logs on the system so we create a new job description to control this behavior rather than modify the job description that others are using. Use the following command to create a debug job description: 
CRTDUPOBJ OBJ(QDFTJOBD) FROMLIB(QGPL) OBJTYPE(*JOBD) TOLIB(QGPL) NEWOBJ(DEBUGJOBD)
Modify it using the following command: 
CHGJOBD JOBD(QGPL/DEBUGJOBD) LOG(4 00 *SECLVL) LOGCLPGM(*YES)

Step 2: Copy the QUSRWRK or QSERVER subsystem.

To copy the QUSRWRK subsystem, do the following:
1. Create the object by typing the following command:

CRTDUPOBJ OBJ(QUSRWRK) FROMLIB(QSYS) OBJTYPE(*SBSD) NEWOBJ(DEBUGSBS)

Press the Enter key.
2. Remove the job queue entry so that there are no conflicts caused by the new subsystem starting before QUSRWRK:

RMVJOBQE SBSD(DEBUGSBS) JOBQ(QUSRNOMAX)

Press the Enter key.
3.
Modify a prestart job entry so that the prestart jobs start with your custom subsystem and to reduce the number of jobs in PSRW to one at a time. Tracing is easier when you can predict which job a connection will be attached to. Display the prestart job entry and identify the program name for the prestart job entry that must be modified.

For our example, I am selecting the program for the file host server for TCP/IP connections, QPWFSERVSO. The command to modify that prestart job entry follows:

CHGPJE SBSD(DEBUGSBS) PGM(QPWFSERVSO) STRJOBS(*YES) INLJOBS(1) THRESHOLD(1) ADLJOBS(1)  + JOBD(DEBUGJOBD)

To copy the QSERVER subsystem, do the following:
1. Create a copy of the original subsystem description:

CRTDUPOBJ OBJ(QSERVER) FROMLIB(QSYS) OBJTYPE(*SBSD) NEWOBJ(DEBUGNETS)

Press the Enter key.
2. The QSERVER subsystem has a job queue entry that must be removed to prevent problems with the host servers. To remove this entry, use the RMVJOBQE command. For our example, the command follows:

RMVJOBQE SBSD(DEBUGNETS) JOBQ(QPWFSERVER)

Press the Enter key.
3. Modify the prestart job entries for the file server or iSeries NetServer prestart jobs. Depending on which server it is that you are going to route here and debug, the command varies. For this example, we are routing the file server (used by the IBM i Navigator file system and IBM i Access Client Solutions IFS function) and IBM i NetServer prestart jobs by typing the following commands:

CHGPJE SBSD(DEBUGNETS) PGM(QZLSFILE) STRJOBS(*YES) INLJOBS(1) THRESHOLD(1) ADLJOBS(1)

CHGPJE SBSD(DEBUGNETS) PGM(QPWFSERVSO) STRJOBS(*YES) INLJOBS(1) THRESHOLD(1) ADLJOBS(1)
4. If you are debugging other connections (which is not likely), you will be told which other modifications must be made to your new subsystem description by IBM support personnel.

Step 3: Start your new subsystem by using the STRSBS command. For our example subsystem, the complete command is STRSBS SBSD(QSYS/DEBUGSBS) or STRSBS SBSD(QSYS/DEBUGNETS). Because the prestart entries were modified to start the prestart jobs along with the subsystem, no other action is required to start the jobs.

Step 4: Determine the TCP/IP address of the client machine. Do the following:
  • The easiest way to get the TCP/IP address if the client is a Microsoft Windows based machine is to run the command IPCONFIG from a command prompt (DOS prompt) on the client machine.
  • If there is more than one interface defined and you cannot determine which one is used to connect to IBM i, you can make a customization for each of the TCP/IP addresses on the client machine.
  • Another option is to make a connection to the IBM i with something like a Telnet or FTP connection and then use the command NETSTAT *CNN to see which TCP/IP address the connection came from. The F17 (Position To) option can be used to quickly search for the TCP/IP address of the client.
Step 5: Customize the operating system so that it routes the connections from the re-create machine to the jobs in our customized subsystem. Now that we know the TCP/IP addresses for our clients, we are ready to perform this last step in the customization. This work is done through the IBM i Navigator tool:
1. Start IBM i Navigator and expand (click the plus sign next to) your system.
2. Expand the Network option.
3. Expand Servers.
4.
Select Alternative Subsystem Routing
IBM i Navigator Network, Servers
5.
Locate the server that you are trying to customize; right-click on it. Select Routing Properties from the resulting pop-up menu.
IBM i Navigator, selecting Database server routing properties
6.
In the server subsystems window, select the radio button for Specific clients and click the Add button.
IBM i Navigator modifying the database server
7. In the Add Client window, define the specific settings for a TCP/IP address or a range of TCP/IP addresses.

Note the default Subnet mask must be changed so that the last value is also 255 (as shown). If this change is not made, every TCP/IP address starting with the first 3 octets in your address (1.2.3 in the example) is affected by the customization.

You must type the name of the custom subsystem into the combination box labeled Subsystem, and you can choose Reject or Use default subsystem for the alternate action. The alternate action is what happens when your custom subsystem is not available when a connection request comes from this TCP/IP address.

Click OK to close the Add Client window.

IBM i Navigator adding client IP address information for customization
8. When you close the Add Client window, the server Subsystems window displays your new customization

IBM i Navigator server Subsystem window with customization added
9. Click OK to close the server Subsystems window; the customization is saved. This change happens immediately after you click OK.

[{"Type":"MASTER","Line of Business":{"code":"LOB68","label":"Power HW"},"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000000CHZAA2","label":"Data Access"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions"}]

Historical Number

451390188

Document Information

Modified date:
11 April 2025

UID

nas8N1014359

Page Feedback