This chapter describes how you create a z/OS subsystem for OSDI. The following topics are included:
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.
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 uses the subsystem name as the command prefix. You can override this default if you want, 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 recommends using the subsystem name for the command prefix.
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 recommends creating a PDS specifically for OSDI parameters and using it for subsystem parameters and 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 on System z. If you omit this parameter, then OSDI uses the FACILITY class for command authorization requests.
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 on System z. 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)
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 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 must 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.
Before attempting to initialize the subsystem, the required OSDI subsystem modules must reside in the system linklist library. For more information, refer to Oracle Database Installation Guide for IBM z/OS on System z.
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 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 ORSS of the data set ORACLE.ORA1.PARMLIB on volume ORA001, an appropriate IEFSSNxx
entry would be similar to the following:
SUBSYS SUBNAME(ORSS) INITRTN(ORASSINI) INITPARM('ORACLE.ORA1.PARMLIB(ORSS),VOL=ORA001')
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. The optional VOL parameter must be specified if the data set is cataloged in a user catalog. It is not required if the data set is cataloged in the master catalog. 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),VOL=ORA001'
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.
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 displays the definitions in the system log.
INIT (ORASSI,ORSS) DEFINE SERVICEGROUP SSID(ORSS) - DESCRIPTION('OSDI Oracle 10G Subsystem - ORSS') DEFINE SERVICE ORAS10 PROC(ORA1S10) TYPE(ORA) MAXAS(1) - DESCRIPTION('Oracle V10G RDBMS Service') - SID(ORA1) PARM('ORACLE.ORA1.PARMLIB(ORSSPARM)') DEFINE SERVICE ORAN10 PROC(ORA1N10) TYPE(NET) - DESCRIPTION('Oracle V10G Net Service') - SID(ORAN) PARM('HPNS PORT(1501) ENCLAVE(SESS)') SHOW SERVICEGROUP LONG START ORAS10 START ORAN10
Consider this file to be member ORSS of the data set ORACLE.ORA1.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),VOL=ORA001' MIS0020I Oracle subsystem ORSS initialized. Version:1.2.00 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."
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.