Files Reference

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:

`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:

`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:

`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:

`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:

`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:

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:

Respawn action:

RESPAWN=1

ONCE=2

Contact options:

SRCIPC=1

SRCSIGNAL=2

SRCSOCKET=3

Multiple instances of a subsystem are allowed:

SRCYES=1

SRCNO=0

Display subsystem status under certain conditions:

SRCYES=1

SRCNO=0

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*/
};

Related Information

The srcobj.h file.

The srcrrqs subroutine, srcsrpy subroutine, srcsrqt subroutine, srcstat subroutine, srcstathdr subroutine, srcsbuf subroutine, srcstattxt subroutine, src_err_msg subroutine.

System Resource Controller (SRC) Overview for Programmers in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

Programming Subsystem Communication with the SRC in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.