1 Configuring and Initializing the Subsystem

This chapter describes how you create a z/OS subsystem for OSDI. The following topics are included:

Overview
Choosing a Subsystem Name and Command Prefix
The Subsystem Parameter File
OSDI Commands in the Subsystem Parameter File
Initializing the Subsystem
Examples

1.1 Overview

To run any Oracle products under OSDI, you must first create a z/OS subsystem. The subsystem provides the internal interfaces that OSDI uses to process operator commands, to manage the execution of database and network services, and to manage connections between address spaces. One OSDI subsystem can support any number of distinct database instances and network services.

Chapter 17, "Migration and Upgrade Considerations", covers issues related to compatibility of OSDI with previous releases of Oracle Database for z/OS.

1.2 Choosing a Subsystem Name and Command Prefix

The subsystem name is a one-character to five-character identifier. z/OS requires that subsystem names begin with an alphabetic or national character, while subsequent characters can be alphanumeric or national. The name must be unique.

The subsystem requires a unique character string prefix to distinguish commands issued to it from system consoles and other system command sources. By default, OSDI will use the subsystem name as the command prefix. You can override this default if you wish, and specify a special character or a different alphanumeric string. Any character string prefix that you choose must not duplicate, or be a leading subset of, the command prefix of any other subsystem. Also, the character string prefix must not match any native z/OS system command name or abbreviation. Oracle Corporation recommends using the subsystem name for the command prefix.

1.3 The Subsystem Parameter File

During initialization, the subsystem opens and reads a sequential data set to obtain bootstrap initialization parameters and, optionally, any OSDI commands that are to be issued immediately after the subsystem is initialized. The file is usually a member of a PDS, and is created, viewed, and edited with ISPF or a similar tool. It can have either fixed-length or variable-length records. If fixed-length records are used, then sequence numbers in the rightmost record positions (for example, columns 73-80 of 80-byte records) are ignored.

Oracle Corporation recommends creating a PDS specifically for OSDI parameters and using it for subsystem parameters as well as for parameter files that are used by other components. Ten tracks of primary disk space, three tracks of secondary space, and eight directory blocks should be sufficient for most installations. This data set must be accessible for the subsystem to initialize, so it should not be subject to HSM migration or similar involuntary moves.

Only a single record, called the INIT record, is required in the subsystem initialization file. The INIT record has the following format:

INIT (ORASSI[,cmd-prefix][,cmd-class][,bind-class])

INIT

The word INIT can begin in position 1 or can be preceded by one or more blanks. It must be followed by one or more blanks and then by one to four positional parameters separated by commas and enclosed in a single pair of parentheses. The parentheses are required even if only the first positional parameter is coded. Do not include blanks in or among the positional parameters. If an optional positional parameter is not used, but a following one is, then a comma must be included for the unused parameter.
First positional parameter

The first positional parameter is the name of the OSDI subsystem load module that was copied to a system linklist library during installation. This will normally be ORASSI, exactly as shown. This parameter is required.
Second positional parameter (cmd-prefix)

The second positional parameter is the command prefix for the subsystem. Any characters that are legal in a command prefix (except the comma and the left or right parenthesis) can be included. Do not enclose the prefix in apostrophes or quotes unless those are part of the prefix. The command prefix can be up to eight characters in length. If you omit this parameter, then the command prefix is assumed to be the subsystem name.
Third positional parameter (cmd-class)

The third positional parameter is the System Authorization Facility (SAF) resource class name that is to be used when authorizing access to OSDI commands. This parameter should be specified if you have created a specific resource class for command authorization as discussed in Oracle Database Installation Guide for IBM z/OS. If you omit this parameter, then OSDI uses the FACILITY class for command authorization requests.The following INIT record provides an example in which the SAF resource class names have been specified while the command prefix is allowed to default:
```
INIT (ORASSI,,$ORACMD,$ORACONN)
```
Fourth positional parameter (bind-class)

The fourth positional parameter is the SAF resource class name that is to be used when authorizing client address spaces during bind to a service and when authorizing a local database connection with SYSOPER or SYSDBA privileges. This parameter should be specified if you have created a specific resource class for bind and connect authorization as discussed in the Oracle Database Installation Guide for IBM z/OS. If you omit this parameter, then OSDI uses the FACILITY class for bind and connect authorization requests.

The following INIT record provides an example in which the SAF resource class names have been specified while the command prefix is allowed to default:

INIT (ORASSI,,$ORACMD,$ORACONN)

1.4 OSDI Commands in the Subsystem Parameter File

The INIT record is the only item that is required to be in the subsystem initialization file. As a convenience, however, you can include OSDI commands in the initialization file immediately after the INIT record. Usually, you will have a number of OSDI DEFINE commands there. You might also have OSDI START commands for any services that you always want started as soon as possible during an IPL. Oracle Corporation recommends that you place into the parameter file both the DEFINE SERVICEGROUP command and the DEFINE SERVICE commands for commonly-used services.

The purpose and complete syntax of all OSDI commands is covered in Appendix A, "OSDI Subsystem Command Reference". You should consider the following items regarding commands that are supplied in the subsystem parameter file:

Do not include the subsystem command prefix. All commands in the subsystem parameter file apply to the subsystem which is being initialized and is reading the file.
Each command must begin on a new record. The command verb can begin in position 1 or it can be preceded by blanks.
A command can be continued by including a hyphen (or minus sign) as the last non-blank character on a record (excluding any sequence number). The continuation can begin in position 1 of the next record or it can be preceded by blanks. You cannot continue (split across records) a command parameter that is enclosed in apostrophes. The continuation hyphen is not interpreted as part of the command.

As commands in the parameter file are processed by the subsystem, the command images are not displayed on the console log, but the subsystem response messages appear as if the commands were entered at a console.

1.5 Initializing the Subsystem

Before attempting to initialize the subsystem, the required OSDI subsystem modules must reside in the system linklist library. For more information, refer to the Oracle Database Installation Guide for IBM z/OS.

The subsystem can be initialized in either of two ways:

At system IPL, based on an entry that you add to the IEFSSNxx member of SYS1.PARMLIB
At any other time by using the SETSSI ADD system operator command

Oracle Corporation recommends that you add regularly-used subsystems to the IEFSSNxx member so that they are initialized correctly and automatically at every IPL. Use the SETSSI ADD system operator command when necessary, such as when you first install OSDI and want to try bringing up a subsystem without having to IPL.

Because OSDI uses z/OS dynamic subsystem interfaces, the IEFSSNxx entry for an OSDI subsystem must use the newer keyword parameter format, not the old positional format.

Assuming that you have chosen ORSS as your OSDI subsystem name and that the subsystem parameter file is member SSP01 of the data set ORACLE.ORA1.PARMLIB, an appropriate IEFSSNxx entry would be similar to the following:

SUBSYS SUBNAME(ORSS) INITRTN(ORASSINI)
  INITPARM('ORACLE.ORA1.PARMLIB(ORSS)')

In the above example, ORASSINI is the name of the subsystem's initialization routine. This module was copied to a system linklist library during OSDI installation. It must be specified exactly as shown.

The subsystem parameter string (INITPARM keyword) must specify the data set name and, if applicable, the member name of the subsystem parameter file containing the INIT record and optional commands. If no member name is supplied, then this must be a sequential (DSORG=PS) data set.

After updating IEFSSNxx, an IPL is necessary to process the added entry. If you do not want to wait for an IPL, or if other circumstances exist in which a subsystem must be created without an IPL, then you can use a SETSSI ADD system operator command equivalent to the following:

SETSSI ADD,S=ORSS,I=ORASSINI,P='ORACLE.ORA1.PARMLIB(ORSS)'

This example uses the minimal keyword abbreviations. The longer forms, SUBNAME (for S), INITRTN (for I), and INITPARM (for P), can be used if desired.

Caution:

Oracle Corporation recommends that you use caution when entering the SETSSI ADD command. If you make a mistake in the parameter string (such as misspelling the data set or member name), then the subsystem will fail to initialize, and the subsystem name that you specified will be unusable until the next IPL.

1.6 Examples

The following code represents the contents of a subsystem initialization file that includes OSDI commands to define the service group and several services. The file ends with an OSDI SHOW command that will display the definitions in the system log.

INIT (ORASSI,ORSS)
DEFINE SERVICEGROUP SSID(ORSS) DESC('Oracle OSDI Subsystem')
DEFINE SERVICE ORAPROD  DESC('Oracle Production DB') -
  TYPE(ORA) PROC(ORADB01) JOBNAME(OPROD*)  MAXAS(8) -
  SID(ORA1) PARM('ORACLE.ORA1.PARMLIB(ORAPROD1)')
DEFINE SERVICE ORATEST DESC('Oracle Test DB') TYPE(ORA) -
  PROC(ORADB01) SID(ORAT) -
  PARM('ORACLE.ORA1.PARMLIB(ORATEST)')
DEFINE SERVICE ORANET DESC('Oracle Net') -
  TYPE(NET) PROC(ORANET01)  -
  PARM('HPNS PORT(1521)')
SHOW SERVICEGROUP LONG

Consider this file to be member SSP01 of ORACLE.V10G.PARMLIB as in the earlier examples, and assume that the subsystem will be initialized with a SETSSI ADD command using subsystem name ORSS. The z/OS system log that results from the SETSSI ADD command would be similar to the following:

SETSSI ADD,S=ORSS,I=ORASSINI,P='ORACLE.ORA1.PARMLIB(ORSS)'
MIS0020I Initialization of Oracle subsystem ORSS complete
MIS0196I Service group ORSS defined
MIS0198I Service ORAS10    defined
MIS0198I Service ORAN10    defined
MIS0195I Service group ORSS (OSDI Oracle 10G Subsystem - ORSS)
         Mode=*SYS   , Systems=*ALL
         Service ORAN10    Type NET  (Oracle V10G Net Service)
         Service ORAS10    Type ORA  (Oracle V10G RDBMS Service)
MIS0193I Service ORAN10    starting
MIS0193I Service ORAS10    starting

At this point, a subsystem has been initialized, and three services have been defined. Configuring and operating a database service and network service are described in Chapter 3, "Configuring a Database Service and Creating a New Database" and Chapter 8, "Oracle Net".

1.7 After Initializing the Subsystem

When you have successfully initialized the subsystem, you can proceed to configure and start Oracle products that will run under its control. Before doing so, you may want to enable security mechanisms that the subsystem provides. These security mechanisms control access to subsystem commands, and they control program access to the services that you define in the subsystem. Refer to Chapter 9, "Security Considerations", for information about these and other security features.