[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs

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.

See the "List of SRC Subroutines" for a task-oriented list of the SRC interfaces. Read the following sections to learn more about how 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. See "SRC Communication Types" for a description of the SRC communication types. Read the following sections for information on communication type-specific guidelines on programming your subsystem to receive SRC request packets.

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.

sigaction, sigvec, or signal subroutine Specifies the action to take upon the delivery of a signal.
sigset, sighold, sigrelse, or sigignore subroutine Enhances the signal facility and provides signal management for application processes.

See "Signals Communication" in "Understanding SRC Communication Types" for more information.

Receiving SRC Request Packets Using Sockets

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

See "Programming Subsystems to Process SRC Request Packets" for the next step in establishing subsystem communication with the SRC.

Receiving SRC Request Packets Using Message Queues

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

See "Programming Subsystems to Process SRC Request Packets" for the next step in establishing subsystem communication with the SRC.

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.

Action parm1 parm2
STOP NORMAL or FORCE
STATUS LONGSTAT or SHORTSTAT
TRACE LONGTRACE or SHORT-TRACE TRACEON or TRACEOFF

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. See "SRC Objects" and "Defining Your Subsystem to the SRC" for more information. 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:

srcrrqs Allows a subsystem to store the header from a request.
srcsrpy Allows a subsystem to send a reply to a request.

See "Responding to Trace Requests" and "Responding to Refresh Requests" for information on how to program support for these commands in your subsystem.

Status-request processing requires a combination of tasks and subroutines. See "Processing SRC Status Requests" for more information.

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. See "Programming Subsystems to Return SRC Error Packets" for more information.

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
Value Meaning Subsystem Subserver
SRCWARN Received a request to stop. (Will be stopped within 20 seconds.) X X
SRCACT Started and active. X X
SRCINAC Not active.

SRCINOP Inoperative. X X
SRCLOSD Closed.

SRCLSPN In the process of being closed.

SRCNOSTAT Idle.

SRCOBIN Open, but not active.

SRCOPND Open.

SRCOPPN In the process of being opened.

SRCSTAR Starting.
X
SRCSTPG Stopping. X X
SRCTST TEST active.

SRCTSTPN TEST pending.

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 which 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.
  5. Fill in the objname field with the name of the subsystem or subserver for which the objtext field applies.
    Note: The subsystem and requester can agree to send other subsystem-defined information back to the requester. See "srcsrpy Continuation Packets for more information on this type of response.

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 second form of continuation, 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 objnam e 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 the rtncode field of the svrreply structure 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:

Related Information

System Resource Controller (SRC) Overview for Programmers.

Understanding SRC Objects.

Understanding SRC Communication Types.

Defining Your Subsystem to the SRC.

SRC Request Structure Example.

Understanding the Network Systems (NS) Protocol Family.

List of SRC Subroutines.

The srcmstr daemon, traceson command, tracesoff command, refresh command.

The srcsbuf subroutine, srcsrpy subroutine, srcstathdr subroutine, srcstat subroutine.

The spc.h file.


[ Previous | Next | Contents | Glossary | Home | Search ]