srcsrqt Subroutine

Base Operating System and Extensions Technical Reference, Volume 2

srcsrqt Subroutine

Purpose

Sends a request to a subsystem.

Library

System Resource Controller Library (libsrc.a)

Syntax

#include <spc.h> srcsrqt(Host, SubsystemName, SubsystemPID,
RequestLength, SubsystemRequest, ReplyLength, ReplyBuffer, StartItAlso, Continued)

char *Host, *SubsystemName;

char *SubsystemRequest, *ReplyBuffer;

int SubsystemPID, StartItAlso, * Continued;

short RequestLength, *ReplyLength;

Description

The srcsrqt subroutine sends a request to a subsystem, waits for a response, and returns one or more replies to the caller. The format of the request and the reply is determined by the caller and the subsystem.

Note: The srcsrqt subroutine creates its own socket to send a request to the subsystem. The socket that this function opens remains open until an error or an end packet is received.

Two types of continuation are returned by the srcsrqt subroutine:

No continuation	ReplyBuffer->`srchdr.continued` is set to the END constant.
Reply continuation	ReplyBuffer->`srchdr.continued` is not set to the END constant, but to a positive value agreed upon by the calling process and the subsystem. The packet is returned to the caller.

Parameters

SubsystemPID	The process ID of the subsystem.
Host	Specifies the foreign host on which this subsystem request is to be sent. If the host is null, the request is sent to the subsystem 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.
SubsystemName	Specifies the name of the subsystem to which this request is to be sent. You must specify a SubsystemName if you do not specify a SubsystemPID.
RequestLength	Specifies the length, in bytes, of the request to be sent to the subsystem. The maximum value in bytes for this parameter is 2000 bytes.
SubsystemRequest	Points to the subsystem request packet.
ReplyLength	Specifies the maximum length, in bytes, of the reply to be received from the subsystem. On return from the srcsrqt subroutine, the ReplyLength parameter is set to the actual length of the subsystem reply packet.
ReplyBuffer	Points to a buffer for the receipt of the reply packet from the subsystem.
StartItAlso	Specifies whether the subsystem should be started if it is nonactive. When nonzero, the System Resource Controller (SRC) attempts to start a nonactive subsystem, and then passes the request to the subsystem.
Continued	Specifies whether this call to the srcsrqt subroutine is a continuation of a previous request. If the Continued parameter is set to NEWREQUEST, a request for it is sent to the subsystem and the subsystem is notified that another response is expected. The calling process should never set Continued to any value other than NEWREQUEST. The last response from the subsystem will set Continued to END.

Return Values

If the srcsrqt subroutine is successful, the value SRC_OK is returned.

Error Codes

The srcsrqt subroutine fails if one or more of the following are true:

SRC_BADSOCK	The request could not be passed to the subsystem because of a 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_REQLEN2BIG	The RequestLength is greater than the maximum 2000 bytes.
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.

Examples

To request long subsystem status, enter:

int cont=NEWREQUEST;
int rc;
short replen;
short reqlen;
struct
{
    struct srchdr srchdr;
    struct statcode statcode[20];
} statbuf;
struct subreq subreq;
 
subreq.action=STATUS;
subreq.object=SUBSYSTEM;
subreq.parm1=LONGSTAT;
strcpy(subreq.objname,"srctest");
replen=sizeof(statbuf);
reqlen=sizeof(subreq);
rc=srcsrqt("MaryC", "srctest", 0, reqlen, &subreq, &replen,
&statbuf, SRC_NO, &cont);

This entry gets long status of the subsystem srctest on the MaryC machine. The subsystem keeps sending status packets until statbuf.srchdr.cont=END.

To start a subserver, enter:

int cont=NEWREQUEST;
int rc;
short replen;
short reqlen;
struct
{
    struct srchdr srchdr;
    struct statcode statcode[20];
} statbuf;
struct subreq subreq;
 
subreq.action=START;
subreq.object=1234;
replen=sizeof(statbuf);
reqlen=sizeof(subreq);
rc=srcsrqt("", "", 987, reqlen, &subreq, &replen, &statbuf,
SRC_NO, &cont);

This entry starts the subserver with the code point of 1234, but only if the subsystem is already active.

To start a subserver and a subsystem, enter:

int cont=NEWREQUEST;
int rc;
short replen;
short reqlen;
struct
{
    struct srchdr srchdr;
    struct statcode statcode[20];
} statbuf;
struct subreq subreq;
subreq.action=START;
subreq.object=1234;
replen=sizeof(statbuf);
reqlen=sizeof(subreq);
rc=srcsrqt("", "", 987, reqlen, &subreq, &replen, &statbuf, SRC_YES, &cont);

This entry starts the subserver with the code point of 1234. If the subsystem to which this subserver belongs is not active, the subsystem is started.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

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 subroutine, srcsbuf subroutine, srcsrpy subroutine, srcstat subroutine, srcstathdr subroutine, srcstattxt subroutine, srcstop subroutine, srcstrt subroutine.

List of SRC Subroutines, Programming Subsystem Communication with the SRC, System Resource Controller (SRC) Overview for Programmers in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.