User-defined servers

The System i® platform supports user-defined servers. With this support, you can add custom servers and perform administrative tasks for these custom servers. For example, you can stop, start, or monitor a custom server in the same way as you administer servers that are included with the operating system.

You can also start or end the server instances of a user-defined server using the Start TCP/IP Server (STRTCPSVR) command or End TCP/IP Server (ENDTCPSVR) command, and the Instance (INSTANCE) parameter of these commands. When you start or end a user-defined server, the data structure that is passed to the server exit program includes the following fields:
  • Action. The action for the server exit program to perform (to start or to end the server or server instances).
  • Instance name. The name of the server instance.
  • Instance startup values. The additional startup values to be used for this server instance.
  • Length of instance startup values. The length, in bytes, of the instance startup values.

The following table illustrates how the system sets the main fields of the data structure (the Action field and the Instance name field) in various situations.

Table 1. How the system sets the Action and Instance name fields of the data structure
Action Value for the SERVER parameter on the STRTCPSVR or ENDTCPSVR command Value for the Action field Value for the Instance name field
Auto-start servers during IPL or by the STRTCP command N/A *START *AUTOSTART
Auto-start servers by the STRTCPSVR command *AUTOSTART *START *AUTOSTART
Start all application servers by the STRTCPSVR command *ALL *START *ALL
Start a specific server by the STRTCPSVR command without specifying the INSTANCE parameter *server application *START *DFT
Start a specific server instance by the STRTCPSVR command *server application *START Server instance specified for the INSTANCE parameter on the STRTCPSVR or ENDTCPSVR command
End all application servers by the ENDTCP command N/A *END *ALL
End all application servers by the ENDTCPSVR command *ALL *END *ALL
End a specific server by the ENDTCPSVR command without specifying the INSTANCE parameter *server application *END *DFT
End a specific server instance by the ENDTCPSVR command *server application *END Server instance specified for the INSTANCE parameter on the STRTCPSVR or ENDTCPSVR command

Defining a server

You can use the User-Defined Servers wizard to define servers to be integrated with the server applications. The wizard requires the following information about a user-defined server:

  • Name
  • Description
  • Server job type
  • Program name
  • Server ID
When designing a server and its server exit program, consider the following points:
  • Server jobs or the server exit program must not attempt to start TCP/IP without first checking the TCP/IP status using the Retrieve TCP/IP Attributes (QtocRtvTCPA) API.
  • Server jobs must be able to implement retry logic if a needed resource, such as a TCP/IP interface, is not available.
  • The server exit program must not perform any long-running operations. A long-running operation can prevent other servers from starting or ending. Any necessary long-running operations must be performed by server jobs instead.
  • When designing your server jobs, consider the user profile and job description used, the subsystem where the server jobs run, and the authority to necessary resources (such as files, job descriptions, commands, configuration objects, and so on).

Accessing user-defined servers

To create, view, or manage user-defined servers in System i Navigator, follow these steps:
  1. In System i Navigator, expand your system > Network > Servers > User-Defined.
  2. To create a new server, right-click User-Defined and select New Server.
  3. To view or change the properties of an existing server, right-click the server and click Properties.
Note: To add, change, or remove a user-defined server, you need input/output system configuration (*IOSYSCFG) special authority. To start or stop a user-defined server, you need all object (*ALLOBJ) special authority, or specific authority to the Start TCP/IP Server (STRTCPSVR) command or the End TCP/IP Server (ENDTCPSVR) command.

Making the job appear as a server job

You can use the Change Job (QWTCHGJB) API to set the server job type for a server that is configured in System i Navigator. After you have configured the application's jobs to appear as server jobs, you can monitor the application's server jobs in .

Here is an example in C code of how to set the server job type using the QWTCHGJB API. Run the program that is used for the server or client application as a job. Use the Submit Job (SBMJOB) command to run your client or server application.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
/* Change job API - server type */
#include <qusec.h>
#include <QWTCHGJB.h>
#include <stdio.h>

typedef struct jobChangeInfo
{
    Qus_Job_Change_Information_t fieldNum;
    Qus_JOBC0100_t format;
    char data[31];
} jobChangeInfo_t;

int main (int argc, char *argv[])
{
  Qus_EC_t     EcStruc;
  Qus_EC_t*    PtrEcStruc;   /* iSeries structure for API errors.      */
  jobChangeInfo_t chg =      /* Job change information for QWTCHGJB    */
{
1,                            /* Number of variable length records.    */
46,                           /* Length of attribute information       */
1911,                         /* Key - Server Type.                    */
'C',                          /* Type of Data - Character.             */
0X40,0X40,0X40,               /* Reserved                              */
30,                           /* Length of data with server name.      */
"YOUR_UNIQUE_SERVER_NAME       "};

  PtrEcStruc = &EcStruc;                 /* API error code structure.  */
  PtrEcStruc->Bytes_Provided = 16;       /* Initialize bytes provided. */
  PtrEcStruc->Bytes_Available = 0;
  /*-------------------------------------------------------------------*/
  /* API used for defining a server name in the job.                   */
  /*-------------------------------------------------------------------*/
Note: The string in the second line of the following example is padded with blanks to the full 30 characters.
QWTCHGJB("*                         ",
         "                              ",
         "JOBC0200",
         &chg;,
         PtrEcStruc);

  if ( EcStruc.Bytes_Available != 0 ) {
    printf("Error changing job server name.  Application ended.");
    printf("Error message id %s sent from QWTCHGJB API.",
            EcStruc.Exception_Id);
    exit(-1);
  }
  return 0;
}