Configuring and Starting the Object Spawner on z/OS

On a z/OS server machine, the spawner starts a SAS object server session in response to a request from a client. The client communicates first with the spawner, and then with the object server, using TCP/IP. The object spawner runs as a started task; before it can handle client requests, you must start it using a started task procedure.

The following setup tasks are required:

1. Configure TCP/IP
2. Create the object spawner started task
3. Create a SAS startup command

Note: This page is intended to serve as an outline of the process, rather than a step-by-step guide, for setting up a spawner on a z/OS platform.

Task 1: Configure TCP/IP

The overall configuration of TCP/IP is outside the scope of this discussion. Assuming that a functioning TCP/IP link is already in place between the client and the z/OS server, the following additional step is required to support the object spawner:

• Make sure that the SAS/C Transient Runtime Library (CTRANS), IBM TCPIP.DATA, and TCP/IP SERVICES configurations are available to both the object spawner and its object servers.

If you specify TCP/IP service names rather than ports in the spawner configuration, you must define the services in the TCP/IP services file. For example, the default spawner operator listen service name is sasobjoper and the default spawner server listen service name is sasobjspawn. To define these in the TCP/IP services file, add the following two lines:

sasobjoper       8582/tcp
sasobjspawn      8581/tcp

Task 2: Create the Object Spawner Started Task

The object spawner runs as a started task (STC). Its job is to listen for requests from clients and pass them to the startup command associated with the service/port in which there is activity. The startup command will start a server session. You must create a procedure in a system PROCLIB library (SYS1.PROCLIB, for example).

Create the Procedure

Because z/OS Job Control Language has a parameter line length restriction of 100 characters, you can use DDNames to identify filenames in object spawner parameters. When a file pathname is 8 characters or less, the file pathname is first checked to see if it matches a DDName. If so, the DDName is used. If DDNames are not used for the config file and log file, you need to specify a config file and log file in the UNIX file system.

If you need to specify more than 100 characters for command line parameters, put the additional parameters in a z/OS data set or UNIX file and reference it using the =<//DDN:PARMS parameter.

The following procedure explicitly specifies the pathname for the config file and uses a DDName to reference the log file in the command line parameters for the object spawner.

//OBJSPAWN PROC PROG=OBJSPAWN,
//  OPTIONS='-CONFIGFILE /usr/lpp/SAS/objspawn.cfg ',
//  OPT2='-SASVERBOSE -SASLOGFILE LOGFILE'
//OBJSPAWN EXEC PGM=&PROG,REGION=512M,
//        PARM='&OPTIONS &OPT2 =<//DDN:PARMS'
//STEPLIB  DD DISP=SHR,DSN=SYS2.SAS.LIBRARY
//CTRANS   DD DISP=SHR,DSN=SYS2.SASC.TRANSLIB
//PARMS    DD DISP=SHR,DSN=SYS2.OBJSPAWN.PARMS
//TKMVSJNL DD PATH='/tmp/objspawn/JNL.&LYYMMDD..&LHHMMSS..txt',
//         PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH),
//         PATHOPTS=(OWRONLY,OCREAT,OTRUNC)
//LOGFILE  DD PATH='/tmp/objspawn/LOG.&LYYMMDD..&LHHMMSS..txt',
//         PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH),
//         PATHOPTS=(OWRONLY,OCREAT,OTRUNC)

Remember that the STC has access to the SAS/C Transient Runtime Library (CTRANS).

The -CONFIGFILE parameter identifies the LDIF format configuration file that the spawner is to use.

The -SASVERBOSE and -SASLOGFILE options in the STC procedure provide useful information for diagnosing connection problems. It is a good idea to include these options until you are satisfied that everything is working correctly.

Create the LDIF Configuration File

The DDname support does not allow for empty lines in the LDIF configuration file. Instead of using an empty line in the LDIF file, use a line containing at least one blank.

The following LDIF configuration file is a generic template:

dn: sasSpawnercn=MySpawner
objectClass: sasSpawner
sasSpawnercn: MySpawner
sasMachineDNSName: localhost
sasOperatorPort: 5306
sasOperatorPassword: sasobjspawn

# This is a comment line!
dn: sasServercn=MyServer
objectClass: sasServer
sasCommand: /usr/bin/startsas.sh --
sasPort: 5307
sasProtocol: bridge
sasMachineDNSName: localhost
sasServercn: MyServer

In the previous configuration file:

• the first paragraph provides the definitions for the object spawner (the STC). It contains the name of the operator service that is defined in the TCP/IP services file, and the operator password.
• the second paragraph defines the object server. It gives details about the TCP/IP port that it is listening to, and the command to use to launch an object server.

For a list of all of the available options, refer to the Attributes for Spawner and Attributes for Server. In general, simple procedures work best. Any option can become the source of problems, so include only the options that you need.

After you have created the STC procedure, you can start the object spawner by issuing an operator command:

Define the Object Spawner System Security Configuration

The z/OS system considers the object spawner a daemon process. Therefore, if the BPX.DAEMON profile of the RACF Facility class is active and RACF program control is enabled, then the SAS and SAS/C load libraries specified in the STC procedure must be program controlled. However, the userid under which the object spawner runs does not require RACF READ access to the BPX.DAEMON profile.

If the following messages appear in the z/OS system log when a client attempts to connect, then a necessary library is not program controlled.

ICH420I  PROGRAM program-name [FROM LIBRARY dsname]
         CAUSED THE ENVIRONMENT TO BECOME UNCONTROLLED.
BPXP014I ENVIRONMENT MUST BE CONTROLLED FOR DAEMON (BPX.DAEMON)
         PROCESSING

Start the Object Spawner

START OBJSPAWN

For a list of all available spawner invocation options, see Spawner Invocation Options. If there are no configuration errors, the object spawner will assume a listening state by entering a detected wait state (DW).

Task 3: Create a SAS Startup Command

Create the Startup Command

The startup command is meant to build a parameter string that is capable of launching SAS. The startup command in the spawner configuration must end with '--' to indicate the end of the user specified parameters. Here is a sample shell script (startsas.sh):

#!/bin/sh
#
#  foundDashDash is a boolean.  When TRUE,
#  we found the string "--" in our arguments.
#
foundDashDash=0

#
#  Construct our arguments
#
args=''
for arg in "$@" ; do
   if [ "$arg" != "--" ]; then
      tmp="$arg ";
   else
      tmp="SRVOPTS(''";
      foundDashDash=1;
   fi
   args="$args$tmp"
done

#
#  If we found a "--", we need to close the SRVOPTS
#  option.
#
if [[ $foundDashDash -ne 0 ]]; then
   args="$args '')"
fi

#
#  Construct the command line...
#
cmd="/bin/tso -t EX 'SYS2.TSO.CLIST(SPWNSAS)'"
cmd="$cmd 'nosasuser $args'"

#
#  Set environment variables...
#  Account data can be used to place SAS in the correct
#  WLM service class. SYSPROC specifies the data set
#  containing the SAS CLIST/REXX.
#
export _BPX_ACCT_DATA=MYNAME1
export SYSPROC=SYS2.TSO.CLIST

#
#  Start up SAS
#
exec $cmd

The sample invokes the /bin/tso/ UNIX command to execute the CLIST SYS2.TSO.CLIST(SPWNSAS). Replace the CLIST data set name SYS2.TSO.CLIST with the name appropriate to your site. The control (CNTL) data set that you created for your SAS install contains an example CLIST for use in launching IOM server sessions.

Note: The SAS CLIST requires the following parameters:

• NOSASUSER to allow more than one concurrent SAS session per user. NOSASUSER suppresses allocation of a SASUSER data set.
• SRVOPTS() in order to pass in the objectserver options.

Specify Account Data

The IOM spawner on z/OS uses the UNIX System Services spawn function to initiate a process to run an IOM server. This process runs in a USS initiator (BPXAS). By default, the process runs with the default Work Load Manager (WLM) service class that was assigned to OMVS work during installation. The default service class might have been defined with a goal of providing USS shell commands with good response times. This default service class assumes the requests are relatively short. Because work associated with IOM requests might require more time, it might be desirable to assign IOM servers to a different service class.

You can use MVS accounting data to assign the work to a specific Work Load Manager service class. To set the accounting data, use the _BPX_ACCT_DATA environment variable in the startsas.sh script that starts that SAS IOM server session. The server session then runs with the accounting data. For example:

export _BPX_ACCT_DATA=MYNAME1

To assign a Work Load Manager service class based on the accounting data, use the WLM AI classification rule. For example (in the WLM ISPF dialog):

           Qualifier                    Class
   Type       Name     Start            Service   Report
                              DEFAULTS: OMVSSHRT  ________
1  AI         MYNAME1                   OMVSLONG  ________

For more information about using accounting information with USS processes, consult UNIX System Service Planning. For information about defining WLM service classes with appropriate characteristics, and for information about specifying classification rules to use these classes, see MVS Planning: Workload Management.

Because you might define different IOM servers, in order to segregate different work loads, you may also specify that these servers run in different service classes. To specify different service classes, create a separate server definition for each class of work in the spawner config file, and assign client requests to the listen port associated with each server.