srcstrt Subroutine

Base Operating System and Extensions Technical Reference, Volume 2

srcstrt Subroutine

Purpose

Starts a System Resource Controller (SRC) subsystem.

Library

System Resource Controller Library (libsrc.a)

Syntax

#include<spc.h>

srcstrt (Host, SubsystemName, Environment, Arguments, Restart, StartFrom)

char *Host, *SubsystemName;

char *Environment, *Arguments;

unsigned int Restart;
int StartFrom;

Description

The srcstrt subroutine sends a start subsystem request packet and waits for a reply from the System Resource Controller (SRC).

Parameters

Host	Specifies the foreign host on which this start subsystem action is requested. If the host is null, the request is sent to the 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.
SubsystemName	Specifies the name of the subsystem to start.
Environment	Specifies a string that is placed in the subsystem environment when the subsystem is executed. The combined values of the Environment and Arguments parameters cannot exceed a maximum of 2400 characters. Otherwise, the srcstrt subroutine will fail. The environment string is parsed by the SRC according to the same rules used by the shell. For example, quoted strings are passed as a single Environment value, and blanks outside a quoted string delimit each environment value.
Arguments	Specifies a string that is passed to the subsystem when the subsystem is executed. The string is parsed from the command line and appended to the command line arguments from the subsystem object class. The combined values of the Environment and Arguments parameters cannot exceed a maximum of 2400 characters. Otherwise, the srcstrt subroutine will fail. The command argument is parsed by the SRC according to the same rules used by the shell. For example, quoted strings are passed as a single argument, and blanks outside a quoted string delimit each argument.
Restart	Specifies override on subsystem restart. If the Restart parameter is set to SRCNO, the subsystem's restart definition from the subsystem object class is used. If the Restart parameter is set to SRCYES, the restart of a subsystem is not attempted if it terminates abnormally.
StartFrom	Specifies whether the srcstrt subroutine is to display start results to standard output. If the StartFrom parameter is set to SSHELL, the start results are displayed to standard output, and the srcstrt subroutine always returns successfully. If the StartFrom parameter is set to SDAEMON, the start results are not displayed to standard output but are passed back to the caller.

Return Values

When the StartFrom parameter is set to SSHELL, the srcstrt subroutine returns the value SRC_OK. Otherwise, it returns the subsystem process ID.

Error Codes

The srcstrt subroutine fails if any of the following are true:

SRC_AUDITID	The audit user ID is invalid.
SRC_DMNA	The SRC daemon is not active.
SRC_FEXE	The subsystem could not be forked and execed.
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_INPT	The subsystem standard input file could not be established.
SRC_MMRY	An SRC component could not allocate the memory it needs.
SRC_MSGQ	The subsystem message queue could not be created.
SRC_MULT	Multiple instance of the subsystem are not allowed.
SRC_NORPLY	The request timed out waiting for a response.
SRC_OUT	The subsystem standard output file could not be established.
SRC_PIPE	A pipe could not be established for the subsystem.
SRC_SERR	The subsystem standard error file could not be established.
SRC_SUBSOCK	The subsystem communication socket could not be created.
SRC_SUBSYSID	The system user ID is invalid.
SRC_SOCK	There is a problem with SRC socket communications.
SRC_SVND	The subsystem is unknown to the SRC daemon.
SRC_UDP	The SRC port is not defined in the /etc/services header file.
SRC_UHOST	The foreign host is not known.

Examples

To start a subsystem passing the Environment and Arguments parameters, enter:
```
rc=srcstrt("","srctest","HOME=/tmpTERM=ibm6155",
"-z\"thezflagargument\"",SRC_YES,SSHELL);
```
This starts the srctest subsystem on the local host, placing HOME=/tmp, TERM=ibm6155 in the environment and using -z and thezflagargument as two arguments to the subsystem. This also displays the results of the start command to standard output and allows the SRC to restart the subsystem should it end abnormally.
To start a subsystem on a foreign host, enter:
```
rc=srcstrt("MaryC","srctest","","",SRC_NO,SDAEMON);
```
This starts the srctest subsystem on the MaryC machine. This does not display the results of the start command to standard output and does not allow the SRC to restart the subsystem should it end abnormally.

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, srcsrqt subroutine, srcstat subroutine, srcstathdr subroutine, srcstattxt subroutine, srcstop 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.