1 PACKAGE DBMS_RESULT_CACHE as
2
3 /**
4 * NAME:
5 * Status
6 * DESCRIPTION:
7 * Checks the status of the Result Cache.
8 * PARAMETERS:
9 * None.
10 * RETURNS:
11 * One of the following values.
12 * STATUS_DISA: Cache is NOT available.
13 * STATUS_ENAB: Cache is available.
14 * STATUS_BYPS: Cache has been temporarily made unavailable.
15 * STATUS_SYNC: Cache is available, but is synchronizing with RAC nodes.
16 * STATUS_CORR: Cache is corrupt and thus unavailable.
17 * EXCEPTIONS:
18 * None.
19 * NOTES:
20 * None.
21 */
22
23 STATUS_DISA CONSTANT VARCHAR2(10) := 'DISABLED';
24 STATUS_ENAB CONSTANT VARCHAR2(10) := 'ENABLED';
25 STATUS_BYPS CONSTANT VARCHAR2(10) := 'BYPASS';
26 STATUS_SYNC CONSTANT VARCHAR2(10) := 'SYNC';
27 STATUS_CORR CONSTANT VARCHAR2(10) := 'CORRUPT';
28
29 FUNCTION Status RETURN VARCHAR2;
30
31 /**
32 * NAME:
33 * Flush
34 * DESCRIPTION:
35 * Attempts to remove all the objects from the Result Cache, and depending
36 * on the arguments retains/releases the memory and retains/clears the
37 * statistics.
38 * PARAMETERS:
39 * retainMem - TRUE => retains the free memory in the cache
40 * FALSE (default) => releases the free memory to the system
41 * retainSta - TRUE => retains the existing cache statistics
42 * FALSE (default) => clears the existing cache statistics
43 * global - TRUE => flushes all caches in the RAC cluster
44 * FALSE (default) => flushes only the local instance cache
45 * RETURNS:
46 * TRUE iff was successful in removing ALL the objects.
47 * EXCEPTIONS:
48 * None.
49 * NOTES:
50 * Objects that are under an active scan are not removed.
51 */
52 FUNCTION Flush(retainMem IN BOOLEAN DEFAULT FALSE,
53 retainSta IN BOOLEAN DEFAULT FALSE,
54 global IN BOOLEAN DEFAULT FALSE) RETURN BOOLEAN;
55 PROCEDURE Flush(retainMem IN BOOLEAN DEFAULT FALSE,
56 retainSta IN BOOLEAN DEFAULT FALSE,
57 global IN BOOLEAN DEFAULT FALSE);
58
59 /**
60 * NAME:
61 * Memory_Report
62 * DESCRIPTION:
63 * Produces the memory usage report for the Result Cache.
64 * PARAMETERS:
65 * detailed - TRUE => produces a more detailed report
66 * FALSE (default) => produces the standard report
67 * RETURNS:
68 * Nothing
69 * EXCEPTIONS:
70 * None.
71 * NOTES:
72 * This procedure uses the DBMS_OUTPUT package; the report requires
73 * "serveroutput" to be on in SQL*Plus.
74 */
75 PROCEDURE Memory_Report(detailed IN BOOLEAN DEFAULT FALSE);
76
77
78 /**
79 * NAME:
80 * Delete_Dependency
81 * DESCRIPTION:
82 * Deletes the specified dependency object from the Result Cache, while
83 * invalidating all results that used that dependency object.
84 * PARAMETERS [Overload 0]:
85 * owner - schema name
86 * name - object name
87 * PARAMETERS [Overload 1]:
88 * object_id - dictionary object number
89 * RETURNS:
90 * The number of objects that were invalidated.
91 * EXCEPTIONS:
92 * None.
93 * NOTES:
94 * None.
95 */
96 FUNCTION Delete_Dependency(owner IN VARCHAR2, name IN VARCHAR2)RETURN NUMBER;
97 PROCEDURE Delete_Dependency(owner IN VARCHAR2, name IN VARCHAR2);
98
99 FUNCTION Delete_Dependency(object_id IN NATURALN) RETURN NUMBER;
100 PROCEDURE Delete_Dependency(object_id IN NATURALN);
101
102 /**
103 * NAME:
104 * Invalidate
105 * DESCRIPTION:
106 * Invaidates all the result-set objects that dependent upon the specified
107 * dependency object.
108 * PARAMETERS [Overload 0]:
109 * owner - schema name
110 * name - object name
111 * PARAMETERS [Overload 1]:
112 * object_id - dictionary object number
113 * RETURNS:
114 * The number of objects that were invalidated.
115 * EXCEPTIONS:
116 * None.
117 * NOTES:
118 * None.
119 */
120 FUNCTION Invalidate(owner IN VARCHAR2, name IN VARCHAR2) RETURN NUMBER;
121 PROCEDURE Invalidate(owner IN VARCHAR2, name IN VARCHAR2);
122
123 FUNCTION Invalidate(object_id IN NATURALN) RETURN NUMBER;
124 PROCEDURE Invalidate(object_id IN NATURALN);
125
126 /**
127 * NAME:
128 * Invalidate_Object
129 * DESCRIPTION:
130 * Invaidates the specified result-set object(s).
131 * PARAMETERS [Overload 0]:
132 * id - the address of the cache object in the Result Cache
133 * PARAMETERS [Overload 1]:
134 * cache_id - the cache-id
135 * RETURNS:
136 * The number of object that were invalidated.
137 * EXCEPTIONS:
138 * None.
139 * NOTES:
140 * None.
141 */
142 FUNCTION Invalidate_Object(id IN NATURALN) RETURN NUMBER;
143 PROCEDURE Invalidate_Object(id IN NATURALN);
144
145 FUNCTION Invalidate_Object(cache_id IN VARCHAR2) RETURN NUMBER;
146 PROCEDURE Invalidate_Object(cache_id IN VARCHAR2);
147
148
149 /**
150 * NAME
151 * Bypass
152 * DESCRIPTION
153 * Can be used to set the bypass mode for the Result Cache.
154 * o When bypass mode is turned on, it implies that cached results are
155 * no longer used and that no new results are saved in the cache.
156 * o When bypass mode is turned off, the cache resumes normal operation.
157 * PARAMETERS
158 * bypass_mode - TRUE => Result Cache usage is bypassed.
159 * FALSE => Result Cache usage is turned on.
160 * session - TRUE => Applies to current session.
161 * FALSE (default) => Applies to all sessions.
162 * RETURNS
163 * None.
164 * EXCEPTIONS
165 * None.
166 * NOTES
167 * This operation is database instance specific.
168 *
169 * USAGE SCENARIO(S):
170 *
171 * (1) Hot Patching PL/SQL Code:
172 *
173 * This operation can be used when there is a need to hot patch PL/SQL
174 * code in a running system. If a code-patch is applied to a PL/SQL module
175 * on which a result cached function directly or transitively depends,
176 * then the cached results associated with the result cache function are
177 * not automatically flushed (if the instance is not restarted/bounced).
178 * This must be manually achieved.
179 * To ensure correctness during the patching process follow these steps:
180 *
181 * a) Place the result cache in bypass mode, and flush existing results:
182 *
183 * begin
184 * DBMS_RESULT_CACHE.Bypass(TRUE);
185 * DBMS_RESULT_CACHE.Flush;
186 * end;
187 * /
188 * This step must be performed on each instance (if in a RAC env).
189 * b) Apply the PL/SQL code patches.
190 * c) Resume use of the result cache, by turning off the cache bypass mode.
191 *
192 * begin
193 * DBMS_RESULT_CACHE.Bypass(FALSE);
194 * end;
195 * /
196 * This step must be performed on each instance (if in a RAC env).
197 *
198 * (2) Other usage scenarios might be for debugging,
199 * diagnostic purposes.
200 */
201 PROCEDURE Bypass(bypass_mode IN BOOLEAN,
202 session IN BOOLEAN DEFAULT FALSE);
203
204 END DBMS_RESULT_CACHE;