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.
The topics in this appendix include:
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.
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 through 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.
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.
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:
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.
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 ) ]
Parameter | Definition |
---|---|
SSID | Specifies the one-character to four-character z/OS subsystem name associated with the service group. If coded, then it must match the subsystem identifier specified in the IEFSSNxx parmlib member or the SETSSI operator command. This parameter defaults to the correct value. It is therefore coded only to confirm that the correct configuration file is in use. String cannot contain system symbols. |
DESCRIPTION | Specifies an arbitrary text string of up to 64 characters that appears in certain displays associated with the service group. This can be used to supply installation-specific identification for the service group. The default value is 'Service Group ssn ' where ssn is the subsystem name. String can contain system symbols, but should not contain non-printable characters or control characters. |
MODE | This parameter is not yet supported. |
SYSTEMS | This parameter is not yet supported. |
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 ) ]
Parameter | Description |
---|---|
DESCRIPTION | Specifies an arbitrary text string of up to 64 characters that appears in certain displays associated with the service group. This can be used to supply installation-specific identification for the service group. String can contain system symbols but should not contain non-printable or control characters. |
MODE | This parameter is not yet supported. |
SYSTEMS | This parameter is not yet supported. |
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 ]
The LONG
show parameter specifies that the name, type, and description of each service in the service group be included in the display.
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. After a service is defined, it may be started, stopped, modified, or displayed 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 ) ] [ JCLPARM( string ) ] [ MODE( SYSPLEX | LOCAL ) ] [ SYSTEMS( sysname [ sysname... ] | *SVG ) ]
Parameter | Description |
---|---|
name | Specifies the name of the service. The name is used in other commands that operate on the service or its definition and by program functions that interact with the service. It must be one to eight characters long. (Although OSDI permits service names up to eight characters long, the name you use for a database service should be seven characters or less due to a length limitation on what is stored in the database control file.) In addition, it must consist of upper case alphabetic, numeric, or national characters, and must begin with an alphabetic character. It must be unique within the service group. Name cannot contain system symbols.
Note: Unless you specify JOBNAME, |
TYPE | Specifies the Oracle product being configured. String is a one-character to four-character alphabetic or numeric identifier that designates an installed Oracle for z/OS product managed under this architecture. Currently supported values are ORA (Oracle database), NET (Oracle Net), and GTW (Oracle Transparent Gateway). String cannot contain system symbols. |
PROC | Specifies the member name in a system JCL procedure library used to start an address space for the service. Usually this is a procedure that is created during installation of the associated Oracle for z/OS product. String cannot contain system symbols. |
DESCRIPTION | Specifies an arbitrary text string of up to 64 characters that appears in certain displays associated with the service. This can be used to supply installation-specific identification for the service. The default value is 'Service svc Type type ', where svc is the service name and type is the type. String can contain system symbols but should not contain non-printable or control characters. |
PARM | Specifies a parameter string passed to the service when an address space is started. String can be from 0 characters to 64 characters. If it contains characters other than alphabetic, numeric, and national characters, then it must be enclosed in single apostrophes. To indicate a zero-length (empty) parameter, specify PARM('') . Content requirements for this string depend on the service type and are discussed in Chapter 3, "Configuring a Database Service and Creating a New Database" and Chapter 8, "Oracle Net." The default is a null string. The value specified can contain system symbols. |
MAXAS | Specifies the maximum number of address spaces that can be started for the service. This is meaningful only for a database (TYPE(ORA)) service. If specified for any other type, then number must be 1. For a database service, number must be between 1 and 255 inclusive. The default for this parameter is 1. The value cannot include system symbols. |
SID | Specifies a unique identifier for the service that is used in client- or application-supplied service addressing. String is a one-character to eight-character identifier that conforms to the same rules as those for service names. The value supplied must be unique within the z/OS image: it cannot duplicate the SID of any other service in this or any other service group. This parameter defaults to the service name. If you accept the default, it means that the service name must be unique within the z/OS image. |
JOBNAME | Specifies a z/OS jobname to use when starting address spaces for the service. String is either a one-character to eight-character identifier that conforms to z/OS jobname requirements, or it is a one-character to five-character identifier followed by an asterisk. The asterisk form can be used with multiple address space services to provide unique jobnames; it is replaced with a three-digit address space counter (001, 002, and so on) as each address space is started. The jobname should conform to any rules or requirements specific to your installation. This parameter has no default. If you omit it, service address spaces are started without a jobname but with the service name as the address space identifier. System symbols cannot be used in this parameter. |
JOBACCT | Specifies an installation-specific string containing job accounting fields. String can be from 1 character to 64 characters. If it contains characters other than alphabetic, numeric, and national characters, then it must be enclosed in single apostrophes. Use this parameter if your installation requires job accounting data to be included with started tasks (STCs). If this parameter is omitted or specified as a null string (a pair of adjacent apostrophes), then no job accounting data is supplied when service address spaces are started. String can include system symbols. |
JCLPARM | Specifies JCL parameters used to override the cataloged procedure specified by the PROCEDURE (PROC ) parameter. Any valid JCL and symbolic parameters may be specified, including job-level keywords. Separate multiple keywords by commas and enclose the whole string within single apostrophes. System symbols may be included. To indicate a zero-length (empty) parameter, specify JCLPARM('') . The default is a null string. |
MODE | This parameter is not yet supported. |
SYSTEMS | This parameter is not yet supported. |
Refer to "Examples" in Chapter 1, "Configuring and Initializing the Subsystem."
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 ) ]
Parameter | Description |
---|---|
name | Specifies the name of the service to be altered. It must be the name of an existing service in the service group. Name cannot contain system symbols.
Note: The name of a service cannot be altered. |
DESCRIPTION | Specifies an arbitrary text string of up to 64 characters that appears in certain displays associated with the service. This can be used to supply installation-specific identification for the service. String can contain system symbols but should not contain non-printable or control characters. |
PROC | Specifies the member name in a system procedure library used to start an address space for the service. Usually this is a procedure that is created during installation of the associated Oracle for z/OS product. String cannot contain system symbols.
Note: Altering PROC while a multiple address space or multiple system service is running can have unpredictable effects. |
PARM | Specifies a parameter string passed to the service when an address space is started. Requirements for this string depend on the service type and are discussed in the associated Oracle for z/OS product documentation. The value specified can contain system symbols.
Note: Altering PARM while a multiple address space or multiple system service is running can have unpredictable effects. |
MAXAS | Specifies the maximum number of address spaces that can be started for the service. This is meaningful only for a database (TYPE(ORA)) service. MAXAS is accepted on an ALTER SERVICE command only when the service is not active. If the service is active, starting, or stopping, an ALTER SERVICE command with MAXAS specified will be rejected. |
JOBNAME | Specifies a jobname to use when starting service address spaces, as discussed under DEFINE SERVICE. You can nullify (remove) a service jobname specification by coding JOBNAME(''). The value specified cannot contain system symbols. |
JOBACCT | Specifies job accounting data to be included when service address spaces are started, as discussed under DEFINE SERVICE. You can nullify (remove) job accounting data by coding JOBACCT(''). The value specified can contain system symbols. |
MODE | This parameter is not yet supported. |
SYSTEMS | This parameter is not yet supported. |
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
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.
Operating commands manage the execution of services. They are normally issued through 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.
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.
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 ) ]
Parameter | Description |
---|---|
name | Name specifies the name of the service to start. It must be a defined service whose current state is inactive or, if active, must not already have its maximum address spaces running. |
PARM | Specifies a parameter string passed to the service when an address space is started. This overrides any PARM value established by DEFINE or ALTER SERVICE. Requirements for this string depend on the service type and are discussed in Chapter 3, "Configuring a Database Service and Creating a New Database" and Chapter 8, "Oracle Net". String can contain system symbols.
Note: A PARM override must not be used when starting auxiliary address spaces for a database service. |
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 ]
Parameter | Description |
---|---|
name | Specifies the name of the service to be displayed. |
LONG | Specifies that a more detailed display is desired. This provides information about each active address space of the service. |
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
Parameter | Description |
---|---|
name | Specifies the name of the service to be made quiescent. This must be the name of a running service whose current state is active. |
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
Parameter | Description |
---|---|
name | Specifies the name of the service to be resumed. This must be the name of a running service whose current state is drained. |
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 ]
Parameter | Description |
---|---|
name | Specifies the name of the service to be stopped. This must be the name of a running service whose current state is active, drained, or (if the FORCE option is specified) stopping. |
FORCE | Specifies that an involuntary stop is requested. |
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) JCLPARM JCLP 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