Services on z/OS

Creating a Service

The configuration utility provided for z/OS is a batch job. It is installed as a member named INETCFG in the CNTL data set that you created as the first step in the installation of your SAS software. To use the utility, you must edit the parameter file, member INETEDTP in the CNTL data set, edit the INETCFG job, and then submit the INETCFG job. The INETEDTP member contains the parameters necessary for creating a service. You can read the comments provided and change the default values to the values required for your service.

To create a service under z/OS:

Edit the INETEDTP member.
Specify the name of the service that you are creating. The service name can be a maximum of eight characters. Locate the line containing ISVC= and replace the default value with the name of the service that you are creating.
Specify the type of service that you are defining. Uncomment the appropriate line containing ISVCTYP=:
- If you want a socket service, uncomment %SOCKETTYP.
- If you want a pool service, uncomment %POOLTYP.
Ensure that the line containing the other service type is commented out by placing an asterisk in the first column.
For socket services, specify the TCP/IP port number or network service name for each server in the service. You must specify at least one port, but you can specify up to ten. Port numbers or names are not used for pool services. To specify the TCP/IP port, locate the line containing I$PORT1. Change the value 5001 to the correct port number or network service name for the first server in your service. If you want to use more than one server for this service, remove *NO* from the desired number of I$PORT entries and change the value to the appropriate value for each server in the service.
If you are creating a pool service, you must install the Application Load Manager. You might also want to install the Load Manager if you have a socket service with more than one server. See About the Load Manager for more information. If you want to use the Load Manager on your z/OS system, you must install the SAS/IntrNet CGI Tools for the Web Server package. Verify the settings for the Load Manager in INETEDTP:
- Choose a TCP port number or network service name for the Load Manager. Supply this value on the line containing I$LDMPORT=.
- Supply the entire UNIX System Services file path to the Load Manager executable on the line containing I$LDMPROG=. The Load Manager is named LOADMGR and is installed in the directory corresponding to the URL http://yourserver/sasweb/IntrNet9/tools/.
- Determine where the Load Manager should write its log file. Supply the entire UNIX System Services file path for the log file on the line containing I$LDMSOUT.
Save and close INETEDTP.
Edit INETCFG to verify the job header information and the name of the service that you are defining. The service name in this Job Control Language (JCL) should match the value that you supplied for ISVC in INETEDTP. If you make changes, be sure to save them. Do NOT change SASEDITP to INETEDTP. This filename refers to your original SAS installation parameters file.
Submit the INETCFG JCL job for processing. The INETCFG job submits another job (INETCFGA). Verify that both jobs completed with a return code of 0. If they completed successfully, you now have the data sets and members necessary for running your service. If the INETCFG job failed, examine the messages and sysprint members for error messages. If you see the following message:
```
ERROR: THIS REPLACEMENT CAUSES RESULT TO EXCEED OUTPUT LRECL
```
you might have supplied a pathname in one of your INETEDTP parameters that is too long. Try shortening this pathname and rerun INETCFG.
Note: Before you run INETCFG again, you must delete any data sets created by the previous failure of INETCFG. You can find these data sets by looking in the namespace determined by your original SAS install. For example, if your SAS software was installed with the prefix name SYS.SAS and your failed INETCFG was trying to create the default service, then delete all data sets beginning with the name prefix SYS.SAS.WEB.DEFAULT before running INETCFG again.
The configuration utility creates a server root in a partitioned data set (PDS) named prefix.WEB.service-name, where prefix is the data set prefix that you supplied during your SAS installation and service-name is the name of the service that you just created. The PDS contains any JCL procedures and server start-up code required for starting the service. Find the following members:

APSTRTn

contains the JCL necessary to run the corresponding @APSTXn file as a started task. These members exist only for socket services. You should move these files to your started task library and enable them as started tasks.

@APSTXn

contains the SAS code that invokes the server. This file is called by the JCL in the corresponding APSTRTn file for socket services and by the Spawner for pool services. These SAS programs must remain in the PDS where they were created.

LOADMGR

contains the JCL necessary to run the Load Manager. You should move this file to your started task library and enable it as a started task.

In addition to the server root PDS, the configuration utility creates an empty PDS named prefix.WEB.service-name.TDIR, where prefix is the data set prefix that you supplied during your SAS installation and service-name is the name of the service you just created. All of the servers in the service use this PDS as a scratch location. Each server also has its own scratch SAS library. These libraries are named TBLIB1 through TBLIBn.
You must modify the permissions for the data sets created above so that the server can write to them as necessary. To modify the permissions, create a special RACF data set profile that applies to all the data sets in this service (prefix.WEB.service-name.*). The RACF data set profile should also grant write access to the user ID of the Application Server.
If you are creating a pool service, you must install the SAS Spawner. Refer to the SAS/CONNECT documentation for installation instructions for the SAS Spawner.

The Application Broker must know about this service so that you can access it. Open the Broker configuration file on your Web server in an editor and add a service definition block. Example service definitions are found in the template configuration file installed with the Application Broker. The following examples also show service definitions.

The following code is an example of a socket service definition:

# This service contains one server (port 5801) on yourserver.
SocketService service-name
   ServiceDescription "text-desc"
   ServiceAdmin "administrator-name"
   ServiceAdminMail "administrator-email-address@host"
   Server yourserver
   Port 5801

The following code is an example of a pool service definition:

# Start up to 5 servers on node  yourserver using the spawner
# started at port 7777. All servers are started with the
# specified username/password. At least 1 server will not time out
# and is kept running.
PoolService service-name
   ServiceDescription "text-desc"
   ServiceAdmin "administrator-name"
   ServiceAdminMail "administrator-email-address@host"
   ServiceLoadManager load-manager-host:port
# Spacing shown in the example command is important.
   SasCommand "/your/bin/poolstart.sh SASTREXX -SASRXSYSCONFIG +
      \"'userid.dataset.SASRXCFG(REXCW0)'\" NOSASUSER -NOTERMINAL +
      -RSASUSER -NOPRINT -SYSIN \"'yourserver(POOLSTRT)'\" -NOLOG +
      \'-SYSPARM\' "
   Server yourserver
   Port 6000-6004
   Username your-username
   Password your-password
   SpawnerPort 7777
   MinRun 1

Note: The SasCommand line contains six double quotation marks (") and six single quotation marks ('). Ensure that these are placed correctly. Also note that the SAS Spawner must be installed and configured for scripted signons in order for this command to work. If you are creating a pool service, you must have a poolstart.sh file. This is a shell script that is used to start an Application Server. The following code is an example of a poolstart.sh file:

#
# Set additional environment variables...
# SYSPROC specifies the data set containing the SAS CLIST/REXX
# STEPLIB of null required to prevent propagation of spawner's
# STEPLIB
#
export STEPLIB=
export tsoout=
export SYSPROC=userid.dataset.SASRX
#
#
# Start SAS
#
exec /bin/tso -t "$@"

Starting the Service

As stated above, the APSTRTn files for a socket service should be moved from your server root PDS to your started task library and enabled as started tasks. To start the service, issue a START command from the system console for each server in the service.

Pool services are started automatically by the Application Load Manager. If you installed the Load Manager on your z/OS system, the LOADMGR started task can be started by a START command from the system console. See About the Load Manager for more details.

Once a service is started, you can test it from a Web browser. The URL depends on the platform and path where your Application Broker is installed. For typical installations, use one of the following URLs to test (or "ping") a service:

UNIX and z/OS:

http://yourserver/cgi-bin/broker?_service=service-name&_program=ping

Windows:

http://yourserver/scripts/broker.exe?_service=service-name&_program=ping

You must specify your Web server name in place of yourserver and your service name in place of service-name. You might need to use a different URL path if you chose a different path when you installed the Application Broker. If the service is running, an HTML page is returned stating that the Application Server is functioning.

Stopping the Service

Socket or pool services can be stopped from a Web browser. The URL depends on the platform and path where your Application Broker is installed. For typical installations, use one of the following URLs to stop a service:

UNIX and z/OS:

http://yourserver/cgi-bin/broker?_service=service-name&_program=stop

Windows:

http://yourserver/scripts/broker.exe?_service=service-name&_program=stop

You must specify your Web server name in place of yourserver and your service name in place of service-name. You might need to use a different URL path if you chose a different path when you installed the Application Broker.

Service Log Files

Log files for socket services are saved as JES spool files. Log files for pool services are named prefix.WEB.service-name.mmddyy.port-no.LOG, where prefix is the data set prefix that you supplied during your SAS installation, mmddyy is the current date (represented as a six-digit number), and port-no is the TCP/IP port number of the server. Log files are not automatically deleted. You must manually delete them to recover the disk space.

Removing a Service

A service can be removed by deleting all data sets beginning with the name prefix.WEB.service-name, where prefix is the data set prefix that you supplied during your SAS installation. For example, if you want to remove the SVC2 service and your SAS software was installed with the prefix name SYS.SAS, then delete all data sets beginning with the name prefix SYS.SAS.WEB.SVC2.