Configuring and Starting the Object Spawner on z/OS

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

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 eight characters or less, the file pathname is first checked to see whether it matches a DDName. If so, the DDName is used. If DDNames are not used for the configuration file and a log file, you need to specify a configuration file and a 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. Reference the data set or file by using the =<//DDN:PARMS parameter.

The following procedure explicitly specifies the pathname for the configuration 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='-LOGCONFIGLOC /usr/lpp/SAS/logconfig.xml' 
//OBJSPAWN EXEC PGM=&PROG,REGION=512M, 
//         PARM='&OPTIONS &OPT2 =<//DDN:PARMS' 
//STEPLIB  DD DISP=SHR,DSN=SYS2.SAS.LIBRARY 
//PARMS    DD DISP=SHR,DSN=SYS2.OBJSPAWN.PARMS 
//TKMVSENV DD DISP=SHR,DSN=SYS2.OBJSPAWN.TKMVSENV 
//TKMVSJNL DD PATH='/tmp/objspawn/JNL.&LYYMMDD..&LHHMMSS..txt', 
//         PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIROTH), 
//         PATHOPTS=(OWRONLY,OCREAT,OTRUNC)

The -XMLCONFIGFILE parameter identifies the SAS Metadata Server system configuration file that the spawner is to use.

The -LOGCONFIGLOC parameter identifies the file for configuring the logging of useful information for diagnosing connection problems. It is a good idea to include logging until you are satisfied that everything is working correctly.

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 load library that is 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

You must also define your server and spawner by 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/lpp/SAS/SAS_9.3/startsas.sh 

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

The start-up command is meant to build a parameter string that is capable of launching SAS. Here is a sample shell script (startsas.sh):

#!/bin/sh
#
#  Initialize SAS startup command...
#
cmd="/bin/tso -t %SASTREXX \
-sasrxsysconfig '&prefix.SASRXCFG(ENW0NO)'"

#
#  Quote arguments with embedded blanks
#
Quoteme() {
   if [ $# -gt 1 ]; then
      quoteme="\"$*\""
   else
      quoteme=$1
   fi
}
for arg in "$@" ; do
   Quoteme $arg
   tmp="$quoteme"
   cmd="$cmd $tmp"
done

#
# pass the metadata authentication strings to SAS
#
if [ -n "$METAUSER" ] ; then
   cmd="$cmd -metauser \"$METAUSER\""
fi
if [ -n "$METAPASS" ] ; then
   cmd="$cmd -metapass \"$METAPASS\""
fi

#
#  Set additional environment variables...
#  SYSPROC specifies the data set containing the SAS REXX
#
export SYSPROC=&prefix.SASRX
export STEPLIB=
export TSOOUT=

#
#  Start SAS
#
exec $cmd

The sample invokes the /bin/tso UNIX command to execute the REXX exec SASTREXX. Replace the REXX exec data set name &prefix.SASRX in the SYSPROC environment variable with the data set name that is appropriate for your site. The SASTREXX exec should be invoked with the following parameter, which you can specify in metadata on the command line to launch the server:

NOSASUSER

NOSASUSER allows more than one concurrent SAS session per user. NOSASUSER suppresses allocation of a SASUSER data set.

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 that 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 box):

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

For more information about using accounting information with USS processes, defining WLM service classes with appropriate characteristics, and specifying classification rules to use these classes, see your IBM documentation.

Because you might define different IOM servers, in order to separate 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 that is associated with each server.