1 PACKAGE dbms_epgc AUTHID CURRENT_USER IS
2
3 ----------------
4 ---- TYPES -----
5 ----------------
6 type VARCHAR2_TABLE is table of varchar2(4000) INDEX BY BINARY_INTEGER;
7
8 ----------------
9 -- EXCEPTIONS --
10 ----------------
11 config_error EXCEPTION;
12 PRAGMA EXCEPTION_INIT(config_error, -20000);
13 config_error_num CONSTANT PLS_INTEGER := -20000;
14 -- *Mesg: "%s failed"
15 -- *Cause: Some gateway configuration operations fails.
16 -- *Action: Look at the previous errors on the stack.
17
18 user_already_exists EXCEPTION;
19 PRAGMA EXCEPTION_INIT(user_already_exists, -20001);
20 user_already_exists_num CONSTANT PLS_INTEGER := -20001;
21 -- *Mesg: "%s is already an admin user"
22 -- *Cause:
23 -- *Action:
24
25 invalid_port EXCEPTION;
26 PRAGMA EXCEPTION_INIT(invalid_port, -20002);
27 invalid_port_num PLS_INTEGER := -20002;
28 -- *Mesg: "invalid port number specified"
29 -- *Cause: The argument is expecting a non-null, valid value but the
30 -- argument value passed in is null, invalid, or out of range.
31 -- *Action: Check your program and correct the caller of the routine
32 -- to not pass a null, invalid or out-of-range argument value.
33 -- Make sure that a gateway instance has been created for
34 -- specified port (via a dbms_epgc.create_instance call).
35
36 invalid_username EXCEPTION;
37 PRAGMA EXCEPTION_INIT(invalid_username, -20003);
38 invalid_username_num PLS_INTEGER := -20003;
39 -- *Mesg: "invalid username specified"
40 -- *Cause: specified username is NULL or too long.
41 -- *Action:
42
43
44 not_an_admin EXCEPTION;
45 PRAGMA EXCEPTION_INIT(not_an_admin, -20004);
46 not_an_admin_num PLS_INTEGER := -20004;
47 -- *Mesg: "%s is not an admin user"
48 -- *Cause:
49 -- *Action:
50
51 privilege_error EXCEPTION;
52 PRAGMA EXCEPTION_INIT(privilege_error, -20005);
53 privilege_error_num PLS_INTEGER := -20005;
54 -- *Mesg: "%s does not have admin privileges on gateway instance %s"
55 -- *Cause: Specified user does not have administrative privileges
56 -- for configuring the PL/SQL gateway instance running on
57 -- specified port.
58 -- *Action:
59
60 dad_not_found EXCEPTION;
61 PRAGMA EXCEPTION_INIT(dad_not_found, -20006);
62 dad_not_found_num PLS_INTEGER := -20006;
63 -- *Mesg: "database access descriptor (DAD) %s not found"
64 -- *Cause: Specified Database Access Descriptor (DAD) does not
65 -- exist.
66 -- *Action:
67
68 invalid_dad_attribute EXCEPTION;
69 PRAGMA EXCEPTION_INIT(invalid_dad_attribute, -20007);
70 invalid_dad_attribute_num PLS_INTEGER := -20007;
71 -- *Mesg: "%s is not a valid DAD attribute".
72 -- *Cause: Specified attribute is not a valid DAD attribute.
73 -- *Action:
74
75 invalid_global_attribute EXCEPTION;
76 PRAGMA EXCEPTION_INIT(invalid_global_attribute, -20008);
77 invalid_global_attribute_num PLS_INTEGER := -20008;
78 -- *Mesg: "%s is not a valid DAD attribute".
79 -- *Cause: Specified attribute is not a valid DAD attribute.
80 -- *Action:
81
82 instance_already_exists EXCEPTION;
83 PRAGMA EXCEPTION_INIT(instance_already_exists, -20009);
84 instance_already_exists_num PLS_INTEGER := -20009;
85 -- *Mesg: "a gateway instance at port %s already exists"
86 -- *Cause: There is already a gateway instance on specified
87 -- port number.
88 -- *Action: You must either drop the specified gateway instance,
89 -- or use a different port number.
90
91 ------------------------------------
92 ---- INSTANCE LEVEL OPERATIONS -----
93 ------------------------------------
94
95 --
96 -- Creates/reserves a gateway instance identified
97 -- by <port> for further use. This call must be done
98 -- prior to do further configuration of the instance
99 -- (such as adding global attributes, dad attributes,
100 -- or granting admin privileges).
101 --
102 -- If the instance (port) is already in use, then
103 -- this operation will result in an error.
104 --
105 -- However, before using the "import" APIs (i.e. the
106 -- bulk configuration upload APIs) describe later,
107 -- the "create_instance" step need not be done.
108 --
109 -- The calling user of this routine automatically gets
110 -- admin privileges on this gateway instance.
111 --
112 PROCEDURE create_instance(port IN PLS_INTEGER);
113
114 --
115 -- Drops the configuration information for the gateway
116 -- instance identified by <port>.
117 --
118 -- This API can be used, for instance, to delete any prior (old)
119 -- configuration that might be present for the gateway instance
120 -- identified by "port" before starting to configuring the instance
121 -- afresh (using create_instance).
122 --
123 PROCEDURE drop_instance(port IN PLS_INTEGER);
124
125 --
126 -- Drops the configuration information for ALL gateway
127 -- instances in the database.
128 --
129 -- This API can be used, for instance, to delete any prior (old)
130 -- configuration that might be present for any gateway instances
131 -- in the database.
132 --
133 -- The caller of this routine should be either SYS or must have
134 -- admin privileges on all gateway instances in the database.
135 --
136 PROCEDURE drop_all_instances;
137
138
139 -----------------------
140 ----- ADMIN APIs ------
141 -----------------------
142 --
143 -- The following APIs are for granting/revoking Gateway administration
144 -- privileges to database users.
145 --
146 -- Note: The SYS and SYSTEM are always "admin" users by default.
147
148 --
149 -- grants admin privileges to a user.
150 --
151 procedure grant_admin(port IN pls_integer, username IN varchar2);
152
153 -- revokes admin privileges of a user
154 procedure revoke_admin(port IN pls_integer, username IN varchar2);
155
156 --
157 -- gets list of admin users (other than SYS/SYSTEM)
158 --
159 -- Note: if no admin users exist then <users> will be set to
160 -- an empty table (i.e. the number of elements will be 0).
161 --
162 procedure get_admin_list(port IN pls_integer,
163 users OUT NOCOPY VARCHAR2_TABLE);
164
165 -----------------------------------------
166 ------ CONFIGURING GLOBAL DEFAULTS ------
167 -----------------------------------------
168 --
169 -- This interface must be used to set global default attributes
170 -- for the Embedded PL/SQL Gateway.
171 --
172 -- If <attrname> attribute has been set before for a given
173 -- gateway (i.e. port number), then the old value
174 -- will be overwritten with the new <attrvalue> argument.
175 --
176 --
177 -- The names of the attributes are not case sensitive. The values
178 -- may or may not be case-senstive depending on the attribute.
179 --
180 -- Examples:
181 -- set_global_attribute(8080, 'defaultDAD', 'myApp');
182 -- set_global_attribute(8080, 'upload_as_blob', 'jpeg, *');
183 --
184 procedure set_global_attribute(port IN pls_integer,
185 attrname IN varchar2,
186 attrvalue IN varchar2);
187
188 --
189 -- Gets the value of a global attribute.
190 -- Returns NULL if attribute has not been set.
191 -- Raises exception if the attribute is not a valid attribute.
192 --
193 function get_global_attribute(port IN pls_integer,
194 attrname IN varchar2)
195 return VARCHAR2;
196
197 --
198 -- Deletes a global attribute.
199 --
200 procedure delete_global_attribute(port IN pls_integer,
201 attrname IN varchar2);
202
203 --
204 -- Get all global attributes/values for an Embedded Gateway
205 -- instance.
206 --
207 -- The output is 2 correlated index-by tables of the name,
208 -- value pairs.
209 --
210 --
211 -- Note: if the gateway instance has no global attributes set, then
212 -- attrnamearray and attrvaluearray will be set to empty arrays.
213 --
214 procedure get_all_global_attributes(port IN pls_integer,
215 attrnamearray OUT NOCOPY VARCHAR2_TABLE,
216 attrvaluearray OUT NOCOPY VARCHAR2_TABLE);
217
218 ----------------------------------------------------------
219 ----- CONFIGURING DATABASE ACCESS DESCRIPTORS (DADs) -----
220 ----------------------------------------------------------
221 --
222 -- Creates a new DAD. None of its attributes will be set.
223 --
224 -- DAD name is not case-sensitive. If a DAD with this name
225 -- already exists, then the old DAD's information will be
226 -- deleted.
227 --
228 procedure create_dad(port IN pls_integer, dadname IN varchar2);
229
230 --
231 -- drops a DAD from the gateway configuration.
232 --
233 procedure drop_dad(port IN pls_integer, dadname IN varchar2);
234
235 --
236 -- This interface must be used to set attributes for a
237 -- DAD (Database Access Descriptor). If the DAD whose
238 -- attribute is being set doesn't already exist then
239 -- it will be automatically created.
240 --
241 -- If <attrname> attribute has been set before for the given
242 -- dad/port number combination, then the old value
243 -- will be overwritten with the new <attrvalue> argument.
244 --
245 -- DAD names and DAD attribute names are not case
246 -- sensitive. DAD attribute names might be case-sensitive
247 -- depending upon the attribute.
248 --
249 --
250 -- Example:
251 --
252 -- set_dad_attribute(8080, 'myApp', 'default_page', 'myApp.home');
253 -- set_dad_attribute(8080, 'myApp', 'document_path', 'docs');
254 --
255 procedure set_dad_attribute(port IN pls_integer,
256 dadname IN varchar2,
257 attrname IN varchar2,
258 attrvalue IN varchar2);
259
260 --
261 -- Gets the value of a DAD attribute.
262 -- Raises an error if DAD does not exist.
263 -- Raises an error if attribute is not a valid attribute.
264 -- Returns NULL if attribute has not been set.
265 --
266 function get_dad_attribute(port IN pls_integer,
267 dadname IN varchar2,
268 attrname IN varchar2) return VARCHAR2;
269
270 --
271 -- Deletes a DAD attribute.
272 --
273 procedure delete_dad_attribute(port IN pls_integer,
274 dadname IN varchar2,
275 attrname IN varchar2);
276
277 --
278 -- Get list of all DADs for an Embedded Gateway instance.
279 --
280 -- Note: if no DADs exist then <dadarray> will be set to
281 -- an empty table (i.e. the number of elements will be 0).
282 --
283 procedure get_dad_list(port IN pls_integer,
284 dadarray OUT NOCOPY VARCHAR2_TABLE);
285
286 --
287 -- Get all attributes of a DAD. The output is 2 correlated
288 -- index-by tables of the name, value pairs.
289 --
290 -- Note: if the DAD has no attributes set, then attrnamearray
291 -- and attrvaluearray will be set to empty arrays.
292 --
293 procedure get_all_dad_attributes(port IN pls_integer,
294 dadname IN varchar2,
295 attrnamearray OUT NOCOPY VARCHAR2_TABLE,
296 attrvaluearray OUT NOCOPY VARCHAR2_TABLE);
297
298
299
300 -------------------------------------
301 ---- BULK IMPORT/EXPORT OPERATIONS --
302 -------------------------------------
303
304
305 -- The following APIs can be used for bulk loading the
306 -- configuration information for an Embedded PL/SQL Gateway.
307 -- The configuration can be supplied in one of the following
308 -- forms:
309 -- - a varchar2
310 -- - a index-by table of varchar2s
311 -- - a CLOB
312 --
313 -- Note:The syntax of the configuration information must be
314 -- the same as that used by the mod_plsql gateway running under
315 -- Apache.
316 --
317 --
318 -- Import configuration information from a VARCHAR2 input.
319 -- Note: This form has a 32K limitation on the VARCHAR2
320 -- input size.
321 --
322 procedure import(port IN pls_integer,
323 cfg IN varchar2);
324
325 --
326 -- Import configuration information from a index-by table
327 -- of VARCHAR2 input.
328 --
329 procedure import(port IN pls_integer,
330 cfg IN DBMS_EPGC.VARCHAR2_TABLE);
331
332 --
333 -- Import configuration information from a CLOB input.
334 --
335 procedure import(port IN pls_integer,
336 cfg IN CLOB);
337
338
339 -- The following APIs are to be used for exporting the
340 -- configuration information of an Embedded PL/SQL Gateway
341 -- to a flattened form so that it can be used against
342 -- the mod_plsql gateway running under Apache. The configuration
343 -- information can be output to one of the following forms:
344 -- -- a varchar2
345 -- -- a index-by table of varchar2 elements
346 -- -- a CLOB
347 --
348
349 --
350 -- Output configuration to a varchar2 OUT argument.
351 -- Note: this form has a 32K limitation.
352 --
353 procedure export(port IN pls_integer,
354 cfg OUT NOCOPY varchar2);
355
356 --
357 -- Exports configuration information into a index-by table of
358 -- varchar2 elements.
359 --
360 PROCEDURE export(port IN PLS_INTEGER,
361 cfg OUT NOCOPY dbms_epgc.varchar2_table);
362
363 --
364 -- Output configuration to a CLOB OUT argument.
365 --
366 procedure export(port IN pls_integer,
367 cfg OUT NOCOPY CLOB);
368
369
370 END dbms_epgc;
[Home] [Help]