1 PACKAGE dbms_service_prvt AS
2
3 ------------
4 -- OVERVIEW
5 --
6 -- This package allows an application to manage services and sessions
7 -- connected with a specific service name. The difference to the previous
8 -- package is that additional parameters like the global flag can be set.
9 --
10 -- Oracle Real Application Cluster (RAC) has a functionality to manage
11 -- service names across instances. This package allows the creation,
12 -- deletion,starting and stopping of services in both RAC and single
13 -- instance.
14 -- Additionally it provides the ability to disconnect all sessions which
15 -- connect to the instance with a service name when RAC removes that
16 -- service name from the instance.
17
18 ----------------
19 -- CAUTION
20 --
21 -- This package was specifically defined with GSM in mind. Prospective users
22 -- are advised to talk to the file owener before using this package.
23
24 ----------------
25 -- INSTALLATION
26 --
27 -- This package should be installed under SYS schema.
28 --
29 -- SQL> @dbmssrv
30 --
31
32 ------------
33 -- SECURITY
34 --
35 -- The execute privilage of the package is granted to DBA role only.
36
37 ----------------------------
38 -- PROCEDURES AND FUNCTIONS
39 --
40
41 TYPE svc_parameter_array IS TABLE OF VARCHAR2(100) INDEX BY VARCHAR2(100);
42
43 PROCEDURE create_service(service_name IN VARCHAR2,
44 network_name IN VARCHAR2,
45 cluster_attributes IN svc_parameter_array,
46 db_attributes IN svc_parameter_array,
47 is_called_by_crs IN BOOLEAN DEFAULT FALSE,
48 srvc_context IN NUMBER DEFAULT 1);
49 -- Creates a new service$ entry for this service name
50 -- Input parameter(s):
51 -- service_name
52 -- The service's short name. Limited to 64 characters.
53 -- network_name
54 -- the full network name for the service. This will usually be the same
55 -- as the service_name.
56 -- cluster_attributes
57 -- associative array with name/value pairs of the crs service
58 -- attributes. The following list describes the supported names.
59 --
60 -- preferred_all
61 -- All databases in the pool are preferred
62 -- preferred
63 -- A comma separated list of preferred databases
64 -- available
65 -- A comma separated list of available databases
66 -- locality
67 -- Service region locality. Must be ANYWHERE or LOCAL_ONLY
68 -- region_failover
69 -- service is enabled for region failover
70 -- role
71 -- Database role the database must be in to start this service.
72 -- This only applies to database pools that have a data guard broker
73 -- configuration.
74 -- failover_primary
75 -- Enable service to failover to primary. This is only applicable to
76 -- services with the role PHYSICAL_STANDBY.
77 -- lag
78 -- Specifes the lag of the service.
79 -- tafpolicy
80 -- TAF client policy
81 -- policy
82 -- Management policy for the service. Can be automatic or manual.
83 -- db_attributes
84 -- associative array with name/value pairs of the database service
85 -- attributes. The following list describes the supported names.
86 --
87 -- goal
88 -- the workload management goal directive of the service. Valid values
89 -- are : DBMS_SERVICE.GOAL_SERVICE_TIME,
90 -- DBMS_SERVICE.GOAL_THROUGHPUT,
91 -- DBMS_SERVICE.GOAL_NONE.
92 -- dtp
93 -- declares the service to be for DTP or distributed transactions.
94 -- aq_ha_notifications
95 -- determines whether HA events are sent via AQ for this service.
96 -- failover_method
97 -- the TAF failover method for the service
98 -- failover_type
99 -- the TAF failover type for the service
100 -- failover_retries
101 -- the TAF failover retries for the service
102 -- failover_delay
103 -- the TAF failover delay for the service
104 -- edition
105 -- the initial session edition
106 -- pdb
107 -- the initial pdb
108 -- commit_outcome
109 -- persist outcome of transactions
110 -- retention_timeout
111 -- timeout when the transaction outcome is retained
112 -- replay_initiation_timeout
113 -- timeout when replayed is disabled
114 -- session_state_consistency
115 -- Consistency of session state: static or dynamic
116 -- sql_translation_name
117 -- Name of SQL translation unit
118 -- global
119 -- global service
120 -- is_called_by_crs
121 -- Is this function invoked by CRS? (MUST ONLY BE SET BY CRS)
122 -- srvc_context
123 -- which service context does this apply to (DB &/or OCR)?
124
125 PROCEDURE modify_service(service_name IN VARCHAR2,
126 cluster_attributes IN svc_parameter_array,
127 db_attributes IN svc_parameter_array,
128 is_called_by_crs IN BOOLEAN DEFAULT FALSE,
129 srvc_context IN NUMBER DEFAULT 1);
130 -- Modifies an existing service
131 -- Input parameter(s):
132 -- service_name
133 -- The service's short name. Limited to 64 characters.
134 -- cluster_attributes
135 -- associative array with name/value pairs of the crs service
136 -- attributes. The following list describes the supported names.
137 --
138 -- preferred_all
139 -- All databases in the pool are preferred
140 -- preferred
141 -- A comma separated list of preferred databases
142 -- available
143 -- A comma separated list of available databases
144 -- locality
145 -- Service region locality. Must be ANYWHERE or LOCAL_ONLY
146 -- region_failover
147 -- service is enabled for region failover
148 -- role
149 -- Database role the database must be in to start this service.
150 -- This only applies to database pools that have a data guard broker
151 -- configuration.
152 -- failover_primary
153 -- Enable service to failover to primary. This is only applicable to
154 -- services with the role PHYSICAL_STANDBY.
155 -- lag
156 -- Specifes the lag of the service.
157 -- tafpolicy
158 -- TAF client policy
159 -- policy
160 -- Management policy for the service. Can be automatic or manual.
161 -- db_attributes
162 -- associative array with name/value pairs of the database service
163 -- attributes. The following list describes the supported names.
164 --
165 -- goal
166 -- the workload management goal directive of the service. Valid values
167 -- defined under create_service above.
168 -- dtp
169 -- declares the service to be for DTP or distributed transactions.
170 -- aq_ha_notifications
171 -- determines whether HA events are sent via AQ for this service.
172 -- failover_method
173 -- the TAF failover method for the service
174 -- failover_type
175 -- the TAF failover type for the service
176 -- failover_retries
177 -- the TAF failover retries for the service
178 -- failover_delay
179 -- the TAF failover delay for the service
180 -- edition
181 -- the initial session edition
182 -- pdb
183 -- the new pdb
184 -- commit_outcome
185 -- persist outcome of transactions
186 -- retention_timeout
187 -- timeout when the transaction outcome is retained
188 -- replay_initiation_timeout
189 -- timeout when replayed is disabled
190 -- session_state_consistency
191 -- Consistency of session state: static or dynamic
192 -- sql_translation_name
193 -- Name of SQL translation unit
194 -- is_called_by_crs
195 -- Is this function invoked by CRS? (MUST ONLY BE SET BY CRS)
196 -- srvc_context
197 -- which service context does this apply to (DB &/or OCR)?
198
199 PROCEDURE delete_service(service_name IN VARCHAR2,
200 is_called_by_crs IN BOOLEAN DEFAULT FALSE,
204 -- service_name
201 srvc_context IN NUMBER DEFAULT 1);
202 -- Marks a service$ entry as deleted.
203 -- Input parameter(s):
205 -- The services short name. Limited to 64 characters.
206 -- is_called_by_crs
207 -- Is this function invoked by CRS? (MUST ONLY BE SET BY CRS)
208 -- srvc_context
209 -- which service context does this apply to (DB &/or OCR)?
210
211 PROCEDURE start_service(service_name IN VARCHAR2,
212 all_nodes IN BOOLEAN DEFAULT FALSE,
213 is_called_by_crs IN BOOLEAN DEFAULT FALSE);
214 -- In single instance starts the service with this service_name.
215 -- In RAC will optionally start the service only on the instance specified.
216 -- Input parameter(s):
217 -- service_name
218 -- The services short name. Limited to 64 characters.
219 -- all_nodes
220 -- Where shall the service be started? FALSE results in starting the
221 -- the service on the local node.
222 -- In single instance this can only be the current
223 -- instance or FALSE.
224 -- Specify TRUE to start the service on all configured nodes.
225 -- is_called_by_crs
226 -- Is this function invoked by CRS? (MUST ONLY BE SET BY CRS)
227
228 PROCEDURE stop_service(service_name IN VARCHAR2,
229 all_nodes IN BOOLEAN DEFAULT FALSE,
230 is_called_by_crs IN BOOLEAN DEFAULT FALSE);
231 -- In single instance it stops the service specified by service_name.
232 -- In RAC will call out to CRS to stop the service, optionally on the
233 -- instance specified. Calls clscrs_stop_resource.
234 -- Input parameter(s):
235 -- service_name
236 -- The services short name. Limited to 64 characters.
237 -- all_nodes
238 -- Where shall the service be stopped? FALSE results in stopping the
239 -- the service on the local node.
240 -- In single instance this can only be the current instance or FALSE.
241 -- Specify TRUE to stop the service on all configured nodes.
242 -- is_called_by_crs
243 -- Is this function invoked by CRS? (MUST ONLY BE SET BY CRS)
244
245 PROCEDURE rename_pdb_attribute(pdb_name IN VARCHAR2,
246 new_pdb_name IN VARCHAR2);
247 -- Changes the pdb_name of all qualifying services to new_pdb_name
248 -- Input parameter(s):
249 -- pdb_name
250 -- current pdb name
251 -- new_pdb_name
252 -- new pdb name
253
254 END dbms_service_prvt;