A OSDI Subsystem Command Reference

A.1 OSDI Command Reference

OSDI provides a set of system commands for defining and controlling instances of Oracle products. This appendix is the primary reference for all OSDI commands.

A.2 Command Types and Processing

OSDI commands are broadly divided into definition commands and operating commands, as follows:

• Definition commands are used to create and manipulate data structures that describe service groups and services. These commands commonly appear in the subsystem configuration file.

• Operating commands are used to manage execution of services.

Three mechanisms exist for issuing OSDI commands:

• Subsystem configuration file, processed during subsystem initialization

• System operator command interfaces for z/OS (system consoles, SDSF, SYS1.PARMLIB (COMMNDxx), Netview, and others)

• OSDI program interface, used internally by Oracle products.

When an OSDI command is issued using a z/OS system operator command interface, the target subsystem is specified by using the command prefix associated with the subsystem. When the program interface is used to issue an OSDI command, the target is identified by its subsystem name rather than a command prefix. Commands in the configuration file always apply to the subsystem (service group) being initialized, and they must omit the prefix.

Commands generally result in synchronous response messages ranging from simple acknowledgment to multiline displays. Responses to commands that are issued via system operator facilities normally are directed to the issuing console. Various operating commands can result in subsequent, asynchronous messages. These messages are not necessarily directed to the console or session that issued the original command.

A.3 System Symbols in Commands

In order to meet the requirement that the particulars of a service (that runs on multiple systems in a sysplex) can be tailored by system, z/OS system symbols (alphanumeric names prefixed with the ampersand character, "&") can be used in the specification of certain OSDI command parameters. These command parameters resolve to system-specific or IPL-specific values set by z/OS or by the installation. If a command parameter can include system symbols, this capability is noted in the parameter description.

A.4 Definition Commands

Definition commands are used to create, modify, and display the data structures of the service group. An initial set of commands in the configuration file directs the building of these structures during subsystem initialization. Subsequent definition commands can be used to add new service definitions, modify existing definitions, and so forth. The overall data structure persists for the life of the IPL.

The definition commands operate only on data structures; they do not directly affect the operation of services.

Three definition commands are supported:

• DEFINE - Create a logical structure.

• ALTER - Modify the definition of an existing logical structure.

• SHOW - Display contents of an existing logical structure.

  Note:

  SHOW deals with definition data only and is distinct from the operating command, DISPLAY. Refer to "SHOW", "SHOW", and "DISPLAY".

A.5 Structures

The definition commands operate on the following structures:

• SERVICEGROUP - The primary structure of the subsystem.

• SERVICE - A structure representing an instance of an Oracle product.

The various parts of these structures are generally referred to as attributes. Definition commands use keywords to identify attributes being set or modified.

A.6 Service Group Definition Commands

DEFINE

DEFINE SERVICEGROUP must be the first command issued to a newly-initialized subsystem; normally it appears in the configuration file just after the bootstrap (INIT) record. DEFINE SERVICEGROUP must be processed successfully in order for any other OSDI commands or functions to be usable.

The command structure for defining a service group is shown in the following example:

DEFINE SERVICEGROUP
   [ SSID( string ) ]
   [ DESCRIPTION( string ) ]
   [ MODE( LOCAL | SYSPLEX | *SYS ) ]
   [ SYSTEMS( sysname [ sysname... ] | *ALL ) ]

Define Parameters

ALTER

ALTER SERVICEGROUP is used to modify attributes of a service group. It can be included in the configuration file and it can be issued after initialization. Not all attributes can be altered. The subsystem ID, for example, is constant for the life of the IPL.

The command structure for altering a service group is shown in the following example:

ALTER SERVICEGROUP
    [ DESCRIPTION( string ) ]
    [ MODE( LOCAL | SYSPLEX ) ]
    [ SYSTEMS( sysname [ sysname... ] | *ALL ) ]

Alter Parameters

SHOW

SHOW SERVICEGROUP is used to display the current definition of the service group. It can be included in the configuration file and it can be issued after initialization. The command for displaying a service group definition is shown in the following example:

SHOW SERVICEGROUP
   [ LONG ]

Show Parameters

The LONG show parameter specifies that the name, type, and description of each service in the service group be included in the display.

A.7 Service Definition Commands

DEFINE

DEFINE SERVICE is used to create a structure for executing an installed Oracle product. It can be included in the configuration file and it can be issued after initialization. Once a service is defined, it can be started, stopped, etc. using operating commands.

The command structure for defining a service is shown in the following example:

DEFINE SERVICE
     name
     TYPE( string )
     PROC( string )
   [ DESCRIPTION( string ) ]
   [ PARM( string ) ]
   [ MAXAS( number ) ]
   [ SID( string ) ]
   [ JOBNAME( string ) ]
   [ JOBACCT( string ) ]
   [ MODE( SYSPLEX | LOCAL ) ]
   [ SYSTEMS( sysname [ sysname... ] | *SVG ) ]

Define Parameters

Refer to "Examples" in Chapter 1, "Configuring and Initializing the Subsystem".

ALTER

ALTER SERVICE is used to modify attributes of a defined service. It can be included in the configuration file and it can be issued after initialization. The name, type, maximum address spaces, and SID of a service cannot be altered.

OSDI does not prohibit altering the definition of a running service. This enables some useful capabilities but it may also be harmful if misused. For example, changing the JCL procedure of a running multiple address space service would have unpredictable consequences when additional auxiliary address spaces are started.

The command structure for altering a service is shown in the following example:

ALTER SERVICE
      name
    [ DESCRIPTION( string ) ]
    [ PROC( string ) ]
    [ PARM( string ) ]
    [ MAXAS( number ) ]
    [ JOBNAME( string ) ]
    [ JOBACCT( string ) ]
    [ MODE( SYSPLEX | LOCAL ) ]
    [ SYSTEMS( sysname [ sysname... ] | *SVG ) ]

Alter Parameters

SHOW

The SHOW SERVICE command is used to display the current definition of a service.

The command for displaying a service definition is shown in the following example:

SHOW SERVICE
     name

Show Parameters

The name show parameter specifies the name of the service whose definition is to be displayed. It must be the name of an existing service in the service group. Name cannot contain system symbols.

A.8 Operating Commands

Operating commands manage the execution of services. They are normally issued via the z/OS command interface, either automatically (for example, COMMNDxx member of SYS1.PARMLIB) or by a real operator. They might also be issued through the OSDI program interface by a management component such as Oracle Enterprise Manager Agent. Operating commands are also permitted in the service group configuration file.

A.9 Available Commands

Five operating commands are provided:

• START - Start execution of a service.

• DISPLAY - Display operating status of a service.

• DRAIN - Place a service in quiescent state.

• RESUME - Restore a service to normal operation.

• STOP - Stop execution of a service (see note below).

All of the operating commands take a service name as the first positional parameter. This service name must be the name of a defined service.

A.10 Commands

START

The START command initiates execution of an address space for a specified service. For a database service, this can be the first address space (service not previously started) or an auxiliary address space (service previously started and initialized successfully but not yet at its maximum address spaces). For other types of services the service must not already be running.

The command structure for starting a service is shown in the following example:

START
    name
   [ PARM( string ) ]

START Parameters

DISPLAY

The DISPLAY command displays execution status information for services. OSDI displays the current operating state of the service. If the service state is "active" or "drained", then the command is also posted to the running service for further processing at the service's discretion.

The command structure for displaying a service is shown in the following example:

DISPLAY
     name
   [ LONG ]

DISPLAY Parameters

DRAIN

The DRAIN command places a running service in a quiescent state in which it no longer accepts new connection (bind) requests. Existing connections or sessions are not affected. The command is also posted to the running service for further discretionary processing. This command has no effect when the service is not running.

The command structure for draining a service is shown in the following example:

DRAIN
     name

DRAIN Parameters

RESUME

The RESUME command reverses the effect of a drain, allowing a service to begin accepting new connection requests. The command is also posted to the running service for further discretionary processing. This command has no effect when the service is not running.

The command structure for resuming a service is shown in the following example:

RESUME
     name

RESUME Parameters

STOP

The STOP command requests termination of a running service. The normal mode of stop changes the service state to stopping and posts the stop request to the service; it is up to the service to comply, presumably after allowing current requests to complete and performing required cleanup. A force option causes the service address space(s) to be terminated involuntarily. The force form of stop requires that a normal stop be issued first. This command has no effect when the service is not running.

The command structure for stopping a service is shown in the following example:

STOP
     name
   [ FORCE ]

STOP Parameters

A.11 OSDI Command Keyword Abbreviations

The abbreviated or alternate forms that can be used for OSDI command verbs and parameter keywords are as follows:

ALTER             ALT
DEFINE            DEF
DESCRIPTION       DESC
DISPLAY           DIS, D
DRAIN             DR
FORCE             (none)
JOBACCT           ACCT
JOBNAME           JOB
LONG              L
MAXAS             MXA
MODE              MD
PARM              P
PROCEDURE         PROC
RESUME            RES
SERVICE           SRV, SVC
SERVICEGROUP      SVG, SG
SHOW              SH
SID               IDENTIFIER, ID
SSID              (none)
START             ST, S
STOP              P
SYSTEMS           SYS
TYPE              TY