[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, Volume 2
srcsbuf Subroutine
Purpose
Gets status for a subserver or a subsystem and returns
status text to be printed.
Library
System Resource Controller Library (libsrc.a)
Syntax
#include <spc.h>
intsrcsbuf(Host,Type,SubsystemName,
SubserverObject,SubsystemPID, StatusType,StatusFrom,StatusText,Continued)
char * Host, * SubsystemName;
char * SubserverObject, ** StatusText;
short Type, StatusType;
int SubsystemPID, StatusFrom, * Continued;
Description
The srcsbuf subroutine gets the status of a subserver
or subsystem and returns printable text for the status in the address pointed
to by the StatusText parameter.
When the StatusType parameter is SHORTSTAT and the Type parameter is SUBSYSTEM, the srcstat subroutine is called to
get the status of one or more subsystems. When the StatusType parameter is LONGSTAT and the Type parameter is SUBSYSTEM, the srcrsqt subroutine is called to get the long status of one subsystem.
When the Type parameter is not SUBSYSTEM, the srcsrqt subroutine is called to get the long
or short status of a subserver.
Parameters
Host |
Specifies the foreign host on which this status action is requested.
If the host is null, the status request is sent to the System Resource Controller
(SRC) on the local host. The local user must be running as "root". The remote
system must be configured to accept remote System Resource Controller requests.
That is, the srcmstr daemon (see /etc/inittab) must be started with the -r flag
and the /etc/hosts.equiv or .rhosts file must be configured to allow remote requests. |
Type |
Specifies whether the status request applies to the subsystem or
subserver. If the Type parameter is set to SUBSYSTEM, the status request is for a subsystem. If not, the status
request is for a subserver and the Type parameter
is a subserver code point. |
SubsystemName |
Specifies the name of the subsystem on which to get status. To get
the status of all subsystems, use the SRCALLSUBSYS constant.
To get the status of a group of subsystems, the SubsystemName parameter must start with the SRCGROUP constant,
followed by the name of the group for which you want status appended. If you
specify a null SubsystemName parameter, you must specify
a SubsystemPID parameter. |
SubserverObject |
Specifies a subserver object. The SubserverObject parameter modifies the Type parameter. The SubserverObject parameter is ignored if the Type parameter is set to SUBSYSTEM. The use of
the SubserverObject parameter is determined by the
subsystem and the caller. This parameter will be placed in the objname field of the subreq structure that is passed
to the subsystem. |
SubsystemPID |
Specifies the process ID of the subsystem on which to get status,
as returned by the srcstrt subroutine. You must specify
the SubsystemPID parameter if multiple instances of
the subsystem are active and you request a long subsystem status or subserver
status. If you specify a null SubsystemPID parameter,
you must specify a SubsystemName parameter. |
StatusType |
Specifies LONGSTAT for long status or SHORTSTAT for short status. |
StatusFrom |
Specifies whether status errors and messages are to be printed to
standard output or just returned to the caller. When the StatusFrom parameter is SSHELL, the errors are
printed to standard output. |
StatusText |
Allocates memory for the printable text and sets the StatusText parameter to point to this memory. After it prints the text,
the calling process must free the memory allocated for this buffer. |
Continued |
Specifies whether this call to the srcsbuf
subroutine is a continuation of a status request. If the Continued parameter is set to NEWREQUEST, a request
for status is sent and the srcsbuf subroutine then waits
for another. On return, the srcsbuf subroutine is updated
to the new continuation indicator from the reply packet and the Continued parameter is set to END or STATCONTINUED by the subsystem. If the Continued
parameter is set to something other than END, this field
must remain equal to that value; otherwise, this function will not be able
to receive any more packets for the original status request. The calling process
should not set the value of the Continued parameter
to a value other than NEWREQUEST. The Continued parameter should not be changed while more responses are expected. |
Return Values
If the srcsbuf subroutine succeeds,
it returns the size (in bytes) of printable text pointed to by the StatusText parameter.
Error Codes
The srcsbuf subroutine fails
if one or more of the following are true:
SRC_BADSOCK |
The request could not be passed to the subsystem because of some
socket failure. |
SRC_CONT |
The subsystem uses signals. The request cannot complete. |
SRC_DMNA |
The SRC daemon is not active. |
SRC_INET_AUTHORIZED_HOST |
The local host is not in the remote /etc/hosts.equiv file. |
SRC_INET_INVALID_HOST |
On the remote host, the local host is not known. |
SRC_INVALID_USER |
The user is not root or group system. |
SRC_MMRY |
An SRC component could not allocate the memory it needs. |
SRC_NOCONTINUE |
The Continued parameter was not set to NEWREQUEST, and no continuation is currently active. |
SRC_NORPLY |
The request timed out waiting for a response. |
SRC_NSVR |
The subsystem is not active. |
SRC_SOCK |
There is a problem with SRC socket communications. |
SRC_STPG |
The request was not passed to the subsystem. The subsystem is stopping. |
SRC_UDP |
The SRC port is not defined in the /etc/services file. |
SRC_UHOST |
The foreign host is not known. |
SRC_WICH |
There are multiple instances of the subsystem active. |
Examples
- To get the status of a subsystem, enter:
char *status;
int continued=NEWREQUEST;
int rc;
do {
rc=srcsbuf("MaryC", SUBSYSTEM, "srctest", "", 0,
SHORTSTAT, SSHELL, &status, continued);
if (status!=0)
{
printf(status);
free(status);
status=0;
}
} while (rc>0);
This gets short status of the srctest subsystem on the MaryC machine and prints
the formatted status to standard output.
- To get the status of a subserver, enter:
char *status;
int continued=NEWREQUEST;
int rc;
do {
rc=srcsbuf("", 12345, "srctest", "", 0,
LONGSTAT, SSHELL, &status, continued);
if (status!=0)
{
printf(status);
free(status);
status=0;
}
} while (rc>0);
This gets long status for a specific subserver belonging to
subsystem srctest. The subserver is the one having
code point 12345. This request is processed on
the local machine. The formatted status is printed to standard output.
Files
/etc/services |
Defines sockets and protocols used for Internet services. |
/dev/SRC |
Specifies the AF_UNIX socket file. |
/dev/.SRC-unix |
Specifies the location for temporary socket files. |
Related Information
The srcrrqs (srcrrqs Subroutine) subroutine, srcsrpy (srcsrpy Subroutine)
subroutine, srcsrqt (srcsrqt Subroutine) subroutine, srcstat (srcstat Subroutine) subroutine, srcstathdr (srcstathdr Subroutine) subroutine, srcstattxt (srcstattxt Subroutine) subroutine, srcstop (srcstop Subroutine) subroutine, srcstrt
(srcstrt Subroutine) subroutine.
List of SRC Subroutines 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.
System Resource Controller (SRC) Overview for
Programmers in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]