spc.h File

Purpose

Defines external interfaces provided by the System Resource Controller (SRC) subroutines.

Description

The /usr/include/spc.h file defines data structures and symbolic constants that are used when calling the SRC subroutines. All subsystems that are controlled by the SRC via sockets or message queues should include this header file.

The scrreq data structure in the spc.h file defines the format of requests sent to a subsystem by the srcmstr daemon. This format is also used by SRC subroutines that send requests to the srcmstr daemon.

The srcreq data structure contains the following fields:

Item Description
mtype The message type for the message queue. This field should be included only for message queue subsystems. Programs should be compiled with the -DSRCBYQUEUE flag to generate the mtype field.
srchdr The SRC header that must be included in all packets sent to and received from an SRC subsystem.
subreq The request to be processed by the SRC subsystem.

The srchdr data structure in the srcreq data structure contains the return address that is needed to reply to the request. The srcrrqs subroutine can be used to extract this information from the request. The srchdr data structure is also part of the reply structure returned by a subsystem.

The srchdr data structure contains the following fields:

Item Description
retaddr The return address
dversion The SRC packet version.
cont The continuation indicator. The possible values are:
NEWREQUEST
Used in a request to the srcmstr daemon.
CONTINUED
Used in a reply returned by a subsystem, indicating another packet follows.
STATCONTINUED
Used in a status reply returned by a subsystem, indicating another packet follows.
END
Used in a request seen by a subsystem or the last packet in reply sequence.

The subreq data structure contains the request to be processed by the subsystem. This same structure is used when calling the srcsrqt subroutine to send a request to a subsystem. The srcsrqt subroutine formats the required srchdr structure. The request is processed by the srcmstr daemon and passed on to a subsystem.

The subreq data structure contains the following fields:

Item Description
object Defines the object on which to act. The possible values are either the SUBSYSTEM constant, or a subserver code point. If the object is a subsystem, the value of this field is the SUBSYSTEM constant as defined in the spc.h file and the objname field contains either a null value or the subsystem name. If the object is a subserver, the object field value is the code point from the subserver object definition, and the objname field is subsystem-defined. The objname field can be null, the subserver name, or the subserver process ID. The object value for the subserver cannot equal the value reserved for the subsystem.
action SRC action to perform. Possible types are:
START
STOP
STATUS or SRCSTATUS
TRACE
REFRESH

The values 0-255 are reserved for use by the SRC.

parm1 Modifies the SRC action type by indicating a variable associated with an action. This field is used in a different manner by each of the actions.
parm2 Modifies the SRC action type by indicating a variable associated with an action. This field is used in a different manner by each of the actions.
objname Name of the object that the request applies to. This can be a subsystem name, a subserver object, or a subserver process ID.

The srcrep and statrep structures in the spc.h file define formats for the replies returned by a subsystem. For more information, see the srcsrpy subroutine.

The srcrep data structure must be used for replies to start, stop, refresh, and trace requests. It contains the following fields:

Item Description
srchdr Specifies the SRC request/reply (srchdr) header.
svrreply A reply structure containing the following fields:
rtncode Subsystem response to the request. This response is negative on error or subsystem unique message.
objtype The object type. This is one of the following:
  • SUBSYSTEM
  • Subserver code point
  • Error code
objtext Text description.
objname Name of the object (subsystem/subserver).
rtnmsg Subsystem unique message.

The statrep data structure is used for replies to status requests. It contains the following fields:

Item Description
srchdr Specifies the SRC request/reply (srchdr) header.
statcode A status structure containing the following fields. There may be an array of these structures. This structure contains the following fields:
objtype The object type. This is one of the following:
  • SUBSYSTEM
  • Subserver code point
  • Error code
status Status code. See the spc.h file for the symbolic constants that may be used with this field.
objtext Text description.
objname Name of the object (subsystem/subserver) this reply belongs to.

The spc.h file also defines the following constants that are useful in communicating with the srcmstr daemon:

Item Description
SRCNAMESZ The maximum length of an SRC object name (30 bytes, including the null terminator).
SRCPKTMAX The maximum packet size (8192 bytes).

There are also SRC subroutines to manage SRC objects, including subsystems and subservers. The spc.h file defines certain symbolic constants which are useful when defining object attributes. The following SRC object descriptors are defined in the /usr/include/sys/srcobj.h file:

Item Description
Respawn action:

RESPAWN=1

ONCE=2

Item Description
Contact options:

SRCIPC=1

SRCSIGNAL=2

SRCSOCKET=3

Item Description
Multiple instances of a subsystem are allowed:

SRCYES=1

SRCNO=0

Item Description
Display subsystem status under certain conditions:

SRCYES=1

SRCNO=0

Item Description
Default time limit:

TIMELIMIT=20 (seconds)

The spc.h file also includes the /usr/include/srcerrno.h file, which contains symbolic constants for the errors returned by the SRC library subroutines. The src_err_msg subroutine can be used to retrieve the corresponding error message.

SRC Request Structure Example

The following program excerpt is an example of the SRC request (srcreq) structure.

struct srcreq
{
  long mtype;     /*Contains the message type in the IPC buffer*/
                  /*This field is included if IPC is used and a
                    message queue is expected*/
 struct srchdr srchdr;    /*src header table entry - defined below*/
 struct subreq subreq;    /*the request passed to the subsystem*/
};
struct srchdr     /*srchdr structure is used by SRC routines*/
                  /*subsystems are not responsible for setting \
                    this*/
{
 struct sockaddr_un retaddr;
 short dversion;   /*the version of the data format*/
 short cont;       /*used to indicate message is continued*/
};
struct subreq
{
 short object;          /*object to act on*/
 short action;          /*action START, STOP, STATUS,TRACE,REFRESH*/
 short parm1;           /* */
 short parm2;           /*              */
 char objname[SRCNAMES];        /*object name*/
};