Configuring and Starting the Object Spawner on z/OS

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

If you used the Advanced or Personal installation's z/OS configuration script to plan, install, and define your implementation, then you already have an initial z/OS spawner configuration. For details about Advanced and Personal installations, see Getting Started With the SAS Configuration Wizard in this guide and "Installing and Configuring SAS Servers on z/OS" in the SAS Intelligence Platform: Installation Guide.

If you did not use the SAS Configuration Wizard, then 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 in place between the client and the z/OS server, the following additional step is required to support the object spawner:

• Verify 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 purpose 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='-XMLCONFIGFILE /usr/lpp/SAS/objspawn.xml ',
//  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 -XMLCONFIGFILE parameter identifies the SAS Metadata Server system 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.

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 user ID 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

Verify the Metadata Configuration File and SAS Management Console Definitions

If you have not already created a metadata configuration file, for information about creating the file, see Metadata Configuration File.

You must also define your server and spawner using SAS Management Console. When you define the server, enter the following command in the Command field of the Advanced Options Launch Commands tab:

/usr/bin/startsas.sh --

For details about using SAS Management Console to create metadata, see Creating the Metadata Using SAS Management Console.

Start the Object Spawner

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

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 installation 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 can 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 SAS Management Console configuration, and assign client requests to the listen port associated with each server.