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

Item Description
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:

Item Description
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

  1. 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.

  2. 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.

Files

Item Description
/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.