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 member INETEDTP.
Specify the name of the service 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 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.
Make sure 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 Using 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 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 you are defining. The service name in this Job Control Language (JCL) should match the value 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 message that reads
```
   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 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. You will find these 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 data 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. Several examples are shown below. Values that may need to be changed for your site are shown in green.

The definition block for a socket service might look like the following:

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

A pool service is defined by the following:

   #  Start up to 5 servers on node yourserv.yyy.com using the spawner started
   #  at port 7777. All servers will be started with the specified username/
   #  password. At least 1 server will not timeout and be kept running.
   PoolService service-name
      ServiceDescription "text-desc"
      ServiceAdmin "administrator-name"
      ServiceAdminMail "administrator-email-address@host"
      ServiceLoadManager load-manager-host:port
   #  Change prefix in command to the SAS install prefix name.
   #  There is no closing single quote for the CLIST parameter string,
   #  because the spawner adds parameters to the end of the string.  Spacing
   #  shown in the example command is important.
      SasCommand  "/your/bin/spawnsas.sh NOSASUSER +
         O(''NOTERMINAL SYSIN=prefix.WEB.service(@APSTXn) SYSPARM '') "
      Server yourserv.yyy.com
      Port 6000-6004
      Username appdemo
      Password xyzzy
      SpawnerPort 7777
      MinRun 1

Note: The SasCommand line contains two double quotation marks (") and four single quotation marks ('). The double quotation marks are located at the beginning of the command (before /your/bin) and at the end of the entire command, after the parenthesis. Also note that the SAS Spawner must be installed and configured for scripted signons in order for this command to work.

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 Using the Load Manager for more details.

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

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 will be returned stating that the Application Server is functioning.

Stopping the Service

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

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

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.