Programming subsystem communication with the SRC

System Resource Controller (SRC) commands are executable programs that take options from the command line.

After the command syntax has been verified, the commands call SRC run-time subroutines to construct a User Datagram Protocol (UDP) datagram and send it to the srcmstr daemon.

The following sections provide more information about SRC subroutines and how they can be used by subsystems to communicate with the SRC main process:

Programming subsystems to receive SRC requests

The programming tasks associated with receiving SRC requests vary with the communication type specified for the subsystem. The srcmstr daemon uses sockets to receive work requests from a command process and constructs the necessary socket or message queue to forward work requests. Each subsystem needs to verify the creation of its socket or message queue. Read the following sections for information on communication type-specific guidelines on programming your subsystem to receive SRC request packets.

Note: All subsystems, regardless of communication type, must define a signal-catcher routine to handle the SIGTERM request.

Receiving SRC signals

Subsystems that use signals as their communication type must define a signal-catcher routine to catch the SIGNORM and SIGFORCE signals. The signal-catching method used is subsystem-dependent. Following are two examples of the types of subroutines that can be used for this purpose.

Receiving SRC request packets using sockets

Use the following guidelines when programming sockets subsystems to receive SRC request packets:

• Include the SRC subsystem structure in your subsystem code by specifying the /usr/include/spc.h file. This file contains the structures the subsystem uses to respond to SRC commands. In addition, the spc.h file includes the srcerrno.h file, which does not need to be included separately. The srcerrno.h file contains error-code definitions for daemon support.
• When a sockets subsystem is started, the socket on which the subsystem receives SRC request packets is set as file descriptor 0. The subsystem should verify this by calling the getsockname subroutine, which returns the address of the subsystem's socket. If file descriptor 0 is not a socket, the subsystem should log an error and then exit. See "Reading Internet Datagrams Example Program" in Communications Programming Concepts for information on how the getsockname subroutine can be used to return the address of a subsystem socket.
• If a subsystem polls more than one socket, use the select subroutine to determine which socket has something to read. See "Checking for Pending Connections Example Program" in Communications Programming Concepts for more information on how the select subroutine can be used for this purpose.
• Use the recvfrom subroutine to get the request packet from the socket.

  Note: The return address for the subsystem response packet is in the received SRC request packet. This address should not be confused with the address that the recvfrom subroutine returns as one of its parameters.

  After the recvfrom subroutine completes and the packet has been received, use the srcrrqs subroutine to return a pointer to a static srchdr structure. This pointer contains the return address for the subsystem's reply. This structure is overwritten each time the srcrrqs subroutine is called, so its contents should be stored elsewhere if they will be needed after the next call to the srcrrqs subroutine.

Receiving SRC request packets using message queues

Use the following guidelines when programming message queue subsystems to receive SRC request packets:

• Include the SRC subsystem structure in your subsystem code by specifying the /usr/include/spc.h file. This file contains the structures the subsystem uses to respond to SRC commands. In addition, the spc.h file includes the srcerrno.h include file, which does not need to be included separately. The srcerrno.h file contains error-code definitions for daemon support.
• Specify -DSRCBYQUEUE as a compile option. This places a message type (mtype) field as the first field in the srcreq structure. This structure should be used any time an SRC packet is received.
• When the subsystem has been started, use the msgget subroutine to verify that a message queue was created at system startup. The subsystem should log an error and exit if a message queue was not created.
• If a subsystem polls more than one message queue, use the select subroutine to determine which message queue has something to read. See "Checking for Pending Connections Example Program" in Communications Programming Concepts for information on how the select subroutine can be used for this purpose.
• Use the msgrcv or msgxrcv subroutine to get the packet from the message queue. The return address for the subsystem response packet is in the received packet.
• When the msgrcv or msgxrcv subroutine completes and the packet has been received, call the srcrrqs subroutine to finish the reception process. The srcrrqs subroutine returns a pointer to a static srchdr structure that is overwritten each time the srcrrqs subroutine is called. This pointer contains the return address for the subsystem's reply.

Programming subsystems to process SRC request packets

Subsystems must be capable of processing stop requests. Optionally, subsystems may support start, status, trace, and refresh requests.

Processing request packets involves a two-step process:

Reading SRC request packets

SRC request packets are received by subsystems in the form of a srcreq structure as defined in the /usr/include/spc.h file. The subsystem request resides in the subreq structure of the srcreq structure:

struct subreq
   short object;         /*object to act on*/
   short action;         /*action START, STOP, STATUS, TRACE,\
                           REFRESH*/
   short parm1;          /*reserved for variables*/
   short parm2;          /*reserved for variables*/
   char objname;         /*object name*/

The object field of the subreq structure indicates the object to which the request applies. When the request applies to a subsystem, the object field is set to the SUBSYSTEM constant. Otherwise, the object field is set to the subserver code point or the objname field is set to the subserver PID as a character string. It is the subsystem's responsibility to determine the object to which the request applies.

The action field specifies the action requested of the subsystem. Subsystems should understand the START, STOP, and STATUS action codes. The TRACE and REFRESH action codes are optional.

The parm1 and parm2 fields are used differently by each of the actions.

The START subserver and REFRESH actions do not use the parm1 and parm2 fields.

Programming subsystem response to SRC requests

The appropriate subsystem actions for the majority of SRC requests are programmed when the subsystem object is defined to the SRC. The structures that subsystems use to respond to SRC requests are defined in the /usr/include/spc.h file. Subsystems may use the following SRC run-time subroutines to meet command processing requirements:

Status-request processing requires a combination of tasks and subroutines.

When subsystems receive requests they cannot process or that are invalid, they must send an error packet with an error code of SRC_SUBICMD in response to the unknown, or invalid, request. SRC reserves action codes 0-255 for SRC internal use. If your subsystem receives a request containing an action code that is not valid, your subsystem must return an error code of SRC_SUBICMD. Valid action codes supported by SRC are defined in the spc.h file. You can also define subsystem-specific action codes. An action code is not valid if it is not defined by the SRC or your subsystem.

Note: Action codes 0-255 are reserved for SRC use.

Processing SRC status requests

Subsystems may be requested to provide three types of status reports: long subsystem status, short subserver status, and long subserver status.

Note: Short subsystem status reporting is performed by the srcmstr daemon. Statcode and reply-status value constants for this type of report are defined in the /usr/include/spc.h file. The Status Value Constants table lists required and suggested reply-status value codes.

Reply status value codes

The SRC lssrc command displays the received information on standard output. The information returned by subsystems in response to a long status request is left to the discretion of the subsystem. Subsystems that own subservers are responsible for tracking and reporting the state changes of subservers, if desired. Use the srcstathdr subroutine to retrieve a standard status header to pass back at the beginning of your status data.

The following steps are recommended in processing status requests:

1. To return status from a subsystem (short or long), allocate an array of statcode structures plus a srchdr structure. The srchdr structure must start the buffer that you are sending in response to the status request. The statcode structure is defined in the /usr/include/spc.h file.

   struct statcode
   {
      short objtype;
      short status;
      char objtext [65];
      char objname [30];
   };

2. Fill in the objtype field with the SUBSYSTEM constant to indicate that the status is for a subsystem, or with a subserver code point to indicate that the status is for a subserver.
3. Fill in the status field with one of the SRC status constants defined in the spc.h file.
4. Fill in the objtext field with the NLS text that you wish displayed as status. This field must be a NULL terminated string.
5. Fill in the objname field with the name of the subsystem or subserver for which the objtext field applies. This field must be a NULL terminated string.

   Note: The subsystem and requester can agree to send other subsystem-defined information back to the requester.

Programming subsystems to send reply packets

The packet that a subsystem returns to the SRC should be in the form of the srcrep structure as defined in the /usr/include/spc.h file. The svrreply structure that is part of the srcrep structure will contain the subsystem reply:

struct svrreply
{
   short rtncode;        /*return code from the subsystem*/
   short objtype;        /*SUBSYSTEM or SUBSERVER*/
   char objtext[65];     /*object description*/
   char objname[20];     /*object name*/
   char rtnmsg[256];     /*returned message*/
};

Use the srcsrpy subroutine to return a packet to the requester.

Creating a reply

To program a subsystem reply, use the following procedure:

1. Fill in the rtncode field with the SRC error code that applies. Use SRC_SUBMSG as the rtncode field to return a subsystem-specific NLS message.
2. Fill in the objtype field with the SUBSYSTEM constant to indicate that the reply is for a subsystem, or with the subserver code point to indicate that the reply is for a subserver.
3. Fill in the objname field with the subsystem name, subserver type, or subserver object that applies to the reply.
4. Fill in the rtnmsg field with the subsystem-specific NLS message.
5. Key the appropriate entry in the srcsrpy Continued parameter. See "srcsrpy Continuation Packets" for more information.

   Note: The last packet from the subsystem must always have END specified in the Continued parameter to the srcsrpy subroutine.

srcsrpy continuation packets

Subsystem responses to SRC requests are made in the form of continuation packets. Two types of continuation packets may be specified: Informative message, and reply packets.

The informative message is not passed back to the client. Instead, it is printed to the client's standard output. The message must consist of NLS text, with message tokens filled in by the sending subsystem. To send this type of continuation packet, specify CONTINUED in the srcsrpy subroutine Continued parameter.

Note: The STOP subsystem action does not allow any kind of continuation. However, all other action requests received by the subsystem from the SRC may be sent an informative message.

The reply packet is passed back to the client for further processing. Therefore, the packet must be agreed upon by the subsystem and the requester. One example of this type of continuation is a status request. When responding to subsystem status requests, specify STATCONTINUED in the srcsrpy Continued parameter. When status reporting has completed, or all subsystem-defined reply packets have been sent, specify END in the srcsrpy Continued parameter. The packet is then passed to the client to indicate the end of the reply.

Programming subsystems to return SRC error packets

Subsystems are required to return error packets for both SRC errors and non-SRC errors.

When returning an SRC error, the reply packet that the subsystem returns should be in the form of the svrreply structure of the srcrep structure, with the objname field filled in with the subsystem name, subserver type, or subserver object in error. If the NLS message associated with the SRC error number does not include any tokens, the error packet is returned in short form. This means the error packet contains the SRC error number only. However, if tokens are associated with the error number, standard NLS message text from the message catalog should be returned.

When returning a non-SRC error, the reply packet should be a svrreply structure with the rtncode field set to the SRC_SUBMSG constant and the rtnmsg field set to a subsystem-specific NLS message. The rtnmsg field is printed to the client's standard output.

Responding to trace requests

Support for the traceson and tracesoff commands is subsystem-dependent. If you choose to support these commands, trace actions can be specified for subsystems and subservers.

Subsystem trace requests will arrive in the following form: A subsystem trace request will have the subreq action field set to the TRACE constant and the subreq object field set to the SUBSYSTEM constant. The trace action uses parm1 to indicate LONGTRACE or SHORTTRACE trace, and parm2 to indicate TRACEON or TRACEOFF.

When the subsystem receives a trace subsystem packet with parm1 set to SHORTTRACE and parm2 set to TRACEON, the subsystem should turn short tracing on. Conversely, when the subsystem receives a trace subsystem packet with parm1 set to LONGTRACE and parm2 set to TRACEON, the subsystem should turn long tracing on. When the subsystem receives a trace subsystem packet with parm2 set to TRACEOFF, the subsystem should turn subsystem tracing off.

Subserver trace requests will arrive in the following form: the subserver trace request will have the subreq action field set to the TRACE constant and the subreq object field set to the subserver code point of the subserver to send status on. The trace action uses parm1 to indicate LONGTRACE or SHORTTRACE, and parm2 to indicate TRACEON or TRACEOFF.

When the subsystem receives a trace subserver packet with parm1 set to SHORTTRACE and parm2 set to TRACEON, the subsystem should turn subserver short tracing on. Conversely, when the subsystem receives a trace subserver packet with parm1 set to LONGTRACE and parm2 set to TRACEON, the subsystem should turn subserver long tracing on. When the subsystem receives a trace subserver packet with parm2 set to TRACEOFF, the subsystem should turn subserver tracing off.

Responding to refresh requests

Support for subsystem refresh requests is subsystem-dependent. Subsystem programmers that choose to support the refresh command should program their subsystems to interact with the SRC in the following manner:

• A subsystem refresh request will have the subreq structure action field set to the REFRESH constant and the subreq structure object field set to the SUBSYSTEM constant. The refresh subsystem action does not use parm1 or parm2.
• When the subsystem receives the refresh request, the subsystem should reconfigure itself.