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:
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.
Note: All subsystems, regardless of communication type, must define a signal-catcher routine to handle the SIGTERM request.
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.
Use the following guidelines when programming sockets subsystems to receive SRC request packets:
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.
See "Programming Subsystems to Process SRC Request Packets" for the next step in establishing subsystem communication with the SRC.
Use the following guidelines when programming message queue subsystems to receive 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:
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.
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.
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 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:
struct statcode { short objtype; short status; char objtext [65]; char objname [30]; };
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.
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.
To program a subsystem reply, use the following procedure:
Note: The last packet from the subsystem must always have END specified in the Continued parameter to the srcsrpy subroutine.
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.
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 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.
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.
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:
System Resource Controller (SRC) Overview for Programmers
Understanding SRC Communication Types
Defining Your Subsystem to the SRC
Understanding the Network Systems (NS) Protocol Family
List of Additional SRC Subroutines
srcmstr daemon, traceson command, tracesoff command, refresh command
srcsbuf subroutine, srcsrpy subroutine, srcstathdr subroutine, srcstat subroutine
spc.h file