This week I’m going to review the support IBM i has for "server jobs." Most of this is not new, but I'm not sure this is widely known. There are three parts to this:
- How to identify a job as a server job
- How you can define a custom TCP application server
- IBM's documentation on server jobs
When you think of "server jobs" you may think of TCP application servers, such as Telnet or FTP. While these are certainly servers, "server jobs" as IBM has defined them have a broader definition - a server job is a job that provides any sort of service or background capability. They include the traditional TCP application servers, but also include jobs that provide general system services such as clustering or the job log server.
How to identify a job as a server job
It's quite easy to identify a job as a server job. The Change Job API has a parameter called "server type" - this parameter is simply a 30-character string that identifies the server. All IBM-supplied server jobs have this string starting with QIBM. During the server job initialization process, the Change Job API is called to appropriately identify the server job. Using either IBM i Navigator (aka iSeries Navigator) or IBM Systems Director Navigator, you can then use Work Management -> Server Jobs to display the server jobs. All jobs that have a server type specified are displayed. For IBM-supplied server jobs, the GUI knows how to map from the QIBM_xxx strings to a descriptive name that is displayed on the user interface. The networking tasks in the GUI also support managing server jobs.
If you write a server application, you can use the Change Job API to identify your job as a server job. However, the IBM-provided GUI will not know about your server type string, so whatever you put into the server type field will be displayed on the GUI - that is, unless you define your server as a custom application server, which allows you to specify the text that is displayed on the GUI.
How you can define a custom TCP application server
By defining your custom TCP application server to IBM i, you can allow your server application to be managed and controlled just like any IBM-supplied server application. That is, you can then start your server with STRTCPSVR and end it with ENDTCPSVR, and the GUI will display descriptive text for your server rather than the server type string.
Three commands, Add TCP Server (ADDTCPSVR), Remove TCP Server (RMVTCPSVR), and Change TCP Server (CHGTCPSVR) let you integrate your custom server application as if it were one of the IBM-supplied server applications. The command interface to add a TCP server is fairly simple and I won't go into the details of the parameters.
The GUI also has a Create User-Defined Server wizard that will lead you through the steps of creating your custom server, so you’re not required to use the command interface. In the Web console, this wizard is found through the “All Network Tasks” panel.
IBM's documentation on server jobs
There is a well-hidden table in the IBM i Information Center that summarizes the IBM-supplied server jobs. Unless you know about it, it's unlikely that you’d ever stumble upon this. It's hidden deep within the TCP/IP Troubleshooting section! It’s referenced from the Work Management section, but that too, is pretty well hidden.
So what is this Server Table? It’s a table that lists every server application that runs on IBM i, along with key characteristics - such as the job name, the subsystem in which it runs, how to start and end the server job, and so on.
For example, if you need to change the job description of a server job so you can change job-logging settings, you can go to this table and find the job description that the server job uses.
I’d like to share a couple additional tidbits of information regarding server jobs.
First, the Change Job API has a parameter to specify the Client IP Address for IPv4. Don’t use this field as it is obsolete. The operating system stores the IP address implicitly for all server jobs. The Retrieve Thread Attributes API returns the IP address for the thread (if applicable).
Netstat 'connections' has support to show you the jobs associated with the remote port. Option 8, display jobs, allows you to see the jobs for that connection. From the job, you can then get to all the typical work management options for working with a job. This same support is also in the GUI.