IBM Systems > Mainframe servers > Operating systems >

setstack

setstack is used to execute other programs which are dependent upon TCP/IP. Here are some of its features:

Run another program, limiting that program's network access to a single TCP/IP stack.
Some applications, like onetstat, already provide this capability. setstack can provide the capability to most any program.
Run another program, but only if a TCP/IP stack is active.
Run another program once any TCP/IP stack becomes active.

The _BPXK_SETIBMOPT_TRANSPORT environment variable is used to limit TCP/IP access to a single stack for C/C++ programs which are invoked from started procedures or MVS batch jobs. See UNIX System Services Planning for a description of this environment variable. The _BPXK_SETIBMOPT_TRANSPORT mechanism should be used instead of setstack when running C/C++ programs from started procedures or MVS batch jobs. Note that _BPXK_SETIBMOPT_TRANSPORT cannot be used with applications started via BPXBATCH. (But setstack can.)

Warning! This program is being made available with no promise of correctness or support. Feel free to contact the developer at the address below, but realize that prompt assistance cannot be guaranteed.

Command-line syntax

Usage: setstack [-a stackname][-w][-m seconds] [pgm args]
-a stackname: establish affinity with the specified stack, 
then run pgm
-w: wait for the stack to become active
-m n: wait no longer than n seconds for stack to become active

Notes

When run under TSO, "setstack -a stackname" will bind your TSO session to the specified stack, whether or not you specify a program for setstack to execute. This can be a useful feature. However, sometimes you will need to use "setstack -a ." to drop stack affinity after running a program which requires affinity.
When run under TSO, setstack cannot be used directly to run HFS executable files; it will run normal MVS load modules. However, if the BPXBATCH facility is used to run setstack, then HFS executables can be executed by setstack.
Certain programs, such as onetstat, always establish affinity to a particular TCP/IP stack. Any affinity established by setstack prior to running such programs will be dropped by such programs when they establish affinity.

Exit status

setstack will end with one of the following exit statuses:

0	No error occurred.
1	A command-line syntax error was encountered.
2	A system call failed.
3	A TCP/IP stack was not active or did not become active. If running under TSO and the -a option was specified to establish affinity with a particular stack, your TSO address space will still have affinity with the stack, which is not active when this error occurs. Use "setstack -a ." to drop affinity if desired.
20 + n	The invoked program exited with error code n. An error message of the following form will be displayed on stderr: exit status: n

Installation

Download the HFS executable: setstack

You will need to rename it to setstack.

After storing it in the HFS, run the following command to set the permissions:

chmod 755 setstack

If you want to run it from TSO or batch without using BPXBATCH, use the cploadmod utility to copy it to a library in your STEPLIB or link list. cploadmod is available from the Tools and Toys page.

The following command will put it in USER.LINKLIB:

cploadmod setstack 'user.linklib'

Examples

Waiting for a TCP/IP stack to become active

In some cases, it may be desirable to start a TCP/IP application, but to first wait until a TCP/IP stack is active. Some applications may not initialize properly if TCP/IP is not yet active. setstack may be used to only run the application once TCP/IP becomes active.

The following command will wait for a TCP/IP stack to become active before running server. Command-line arguments "1 1" will be passed to server.

setstack -w server 1 1

If server cannot be found via PATH, messages like the following will be displayed:

[MVS165:/u/user1/trawick/ss]$ setstack -w server
server: FSUM7351 not found
exit status: 127

Limiting a program's access to a single stack

The following command will wait for stack TCPCS to become active, then will run hostname. hostname will only have access to stack TCPCS.

setstack -w -a tcpcs hostname -g

Running an HFS executable from JCL

Here is JCL to start an HFS executable via setstack. Since the executable to be run by setstack is in the HFS, setstack must be run via BPXBATCH.

    
INETDPROCINETDEXECPGM=BPXBATCH,REGION=0M,TIME=NOLIMIT,
PARM='PGM /u/user1/trawick/setstack -w -a tcpcs /usr/sbin/inetd'

In this example, /usr/sbin/inetd is the program to be started by setstack and TCPCS is the name of the TCP/IP stack which inetd should be limited to. inetd will not be executed until stack TCPCS is active.

Feedback

Send your comments and other feedback to trawick@us.ibm.com.