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.
- 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.
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
- 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
- In System i Navigator, expand .
- To create a new server, right-click User-Defined and select New Server.
- To view or change the properties of an existing server, right-click the server and click Properties.
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.
/* 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. */
/*-------------------------------------------------------------------*/
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;
}