1 PACKAGE HR_MESSAGE AUTHID CURRENT_USER AS
2 /* $Header: hrmesage.pkh 115.1 99/07/17 16:42:59 porting ship $ */
3 --
4 -- ----------------------------------------------------------------------------
5 -- |------------------------< provide_error >-------------------------|
6 -- ----------------------------------------------------------------------------
7 -- {Start Of Comments}
8 --
9 -- Description:
10 -- This procedure is required for this package to function correctly.
11 -- It ensures that this package is correctly initialized for any error
12 -- raised with the FND_MESSAGE package, for which the FND_MESSAGE global
13 -- variables are set. It retrieves the encoded error message into a record
14 -- component, before calling several FND_MESSAGE supplied procedures to
15 -- obtain the application that set the last message on the stack, as well as
16 -- the name of that message. This package is transparent to non-APP
17 -- (for example ORA-).
18 --
19 -- Once this record structure is populated with data, other calls can be
20 -- made to this package to obtain useful information. Therefore, in order
21 -- for the other functions to work sucessfully, a call to provide_error
22 -- must be executed before any other.
23 --
24 -- Prerequisites:
25 -- If information is required about a particular message, that message
26 -- must exist on the FND_MESSAGE message stack. This procedure is
27 -- transparent to non-application raised error messages.
28 --
29 -- In Parameters:
30 -- None
31 --
32 -- Post Success:
33 -- This procedure never fails as such. If an application error message
34 -- exists on the FND_MESSAGE stack and the current SQLCODE error code
35 -- indicates an application error, then the global variables are initialized
36 -- In all other instances, the SQLCODE and SQLERRM are transmitted through
37 -- the procedure. This procedure does not affect the local state of the
38 -- FND_MESSAGE package.
39 --
40 -- Post Failure:
41 -- This procedure does not fail. Null values are written to the message
42 -- information globals if the error is not raised by an application. The
43 -- global components corresponding to SQLCODE and SQLERRM are always set.
44 --
45 -- Access Status:
46 -- Public.
47 --
48 -- {End Of Comments}
49 --
50 procedure provide_error;
51 --
52 -- ----------------------------------------------------------------------------
53 -- |------------------------< parse_encoded >-------------------------|
54 -- ----------------------------------------------------------------------------
55 -- {Start Of Comments}
56 --
57 -- Description:
58 -- This procedure assumes that the calling program unit already has
59 -- knowledge of the encoded error message retrieved by a call to
60 -- FND_MESSAGE.get_encoded. This is the case when attempting to trap
61 -- the errors raised by the descriptive (or key) flexfield server
62 -- validation engines. This procedure sets up the global variables
63 -- of the error record in the same fashion as the procedure provide
64 -- error.
65 --
66 -- Once this record structure is populated with data, other calls can be
67 -- made to this package to obtain useful information. Therefore, in order
68 -- for the other functions to work sucessfully, a call to either
69 -- provide_error or parse_encoded must be made before any other.
70 --
71 -- Prerequisites:
72 -- This procedure can only be called with a valid FND_MESSAGE encoded
73 -- error string.
74 --
75 -- In Parameters:
76 -- Name Reqd Type Description
77 -- p_encoded_error Y varchar2 String that results from
78 -- a call to
79 -- FND_MESSAGE.get_encoded
80 --
81 -- Post Success:
82 -- If the string passed is in a valid FND_MESSAGE encoded format, the
83 -- global error records will be set in accordance with provide_error
84 -- and made available for use with the probing functions of this package.
85 --
86 -- Post Failure:
87 -- This procedure will not raise an error. If the string passed to the
88 -- procedure is not in a valid FND_MESSAGE encoded format, the last
89 -- message application, and last message name will be set to null.
90 -- That is the action of FND_MESSAGE.parse_encoded, not this procedure.
91 --
92 -- Access Status:
93 -- Public.
94 --
95 -- {End Of Comments}
96 --
97 procedure parse_encoded(p_encoded_error in varchar2);
98 --
99 -- ----------------------------------------------------------------------------
100 -- |-----------------------< last_message_number >------------------------|
101 -- ----------------------------------------------------------------------------
102 -- {Start Of Comments}
103 --
104 -- Description:
105 -- This function returns the last message number that was placed on
106 -- the stack, assuming it was an HR message, conforming to the standard
107 -- HR_MSGNUM_ERROR_DESCR.
108 -- I.e. MSGNUM must be the five digit number associated with a message
109 -- No SQL is executed to retrieve this number, the message name is
110 -- decomposed to obtain the number. SQL could be added if this
111 -- procedure is needed for non-self service applications.
112 --
113 -- Prerequisites:
114 -- This function must be called after a call to provide_error. If provide
115 -- error has not been called beforehand, the results of a call to this
116 -- function are undefined.
117 --
118 -- In Parameters:
119 -- None
120 --
121 -- Post Success:
122 -- The function returns the last message number, equivalent to
123 -- the FND_NEW_MESSAGES MESSAGE_NUMBER column value, if the message
124 -- name conforms to the standard described above. If called with a
125 -- non-application raised error, this function will return NULL.
126 --
127 -- Post Failure:
128 -- This procedure does not fail. Undefined values are returned if the
129 -- function is called before provide_error.
130 --
131 -- Access Status:
132 -- Public.
133 --
134 -- {End Of Comments}
135 --
136 function last_message_number return VARCHAR2;
137 --
138 function last_message_name return VARCHAR2;
139 --
140 -- ----------------------------------------------------------------------------
141 -- |------------------------< last_message_app >-------------------------|
142 -- ----------------------------------------------------------------------------
143 -- {Start Of Comments}
144 --
145 -- Description:
146 -- This procedure returns application short name of that application
147 -- that raised the last message found on the FND_MESSAGE stack.
148 --
149 -- Prerequisites:
150 -- This function must be called after a call to provide_error. If provide
151 -- error has not been called beforehand, the results of a call to this
152 -- function are undefined.
153 --
154 -- In Parameters:
155 -- None
156 --
157 -- Post Success:
158 -- The function returns the contents the application short name that
159 -- last set a message on the FND_MESSAGE stack. If a non-application
160 -- error has occurred, this function will return NULL.
161 --
162 -- Post Failure:
163 -- This procedure does not fail. Undefined values are returned if the
164 -- function is called before provide_error.
165 --
166 -- Access Status:
167 -- Public.
168 --
169 -- {End Of Comments}
170 --
171 function last_message_app return VARCHAR2;
172 --
173 -- ----------------------------------------------------------------------------
174 -- |------------------------< get_token_value >-------------------------|
175 -- ----------------------------------------------------------------------------
176 -- {Start Of Comments}
177 --
178 -- Description:
179 -- This procedure returns the value assigned to a token found in the
180 -- last message. This procedure checks that the
181 -- error message data contains the token value specified in the call
182 -- and if so, returns the assigned value.
183 --
184 -- Prerequisites:
185 -- This function must be called after a call to provide_error. If provide
186 -- error has not been called beforehand, the results of a call to this
187 -- function are undefined.
188 --
189 -- In Parameters:
190 -- Name Reqd Type Description
191 -- p_token_name Y varchar2 The name of the token whose
192 -- value is required.
193 --
194 -- Post Success:
195 -- The function returns the value assigned to the token if the supplied
196 -- token is present in the message data string. This is case sensitive
197 -- so that a token pushed onto the stack with identifier 'TOKEN', can only
198 -- be retrieved from this procedure by passing the value 'TOKEN'. If
199 -- the token is not in the message string, or the trapped error was not
200 -- raised by the application, a null value is returned.
201 --
202 -- Post Failure:
203 -- This procedure does not fail. Undefined values are returned if the
204 -- function is called before provide_error.
205 --
206 -- Access Status:
207 -- Public.
208 --
209 -- {End Of Comments}
210 --
211 --
212 function get_token_value(p_token_name in varchar2) return varchar2;
213 --
214 -- ----------------------------------------------------------------------------
215 -- |------------------------< get_message_text >-------------------------|
216 -- ----------------------------------------------------------------------------
217 -- {Start Of Comments}
218 --
219 -- Description:
220 -- This procedure returns the text associated with the message. The tokens
221 -- are replaced with their proper values, and the message text will contain
222 -- the same information as if FND_MESSAGE.get were raised. However, it
223 -- leaves the local state of FND_MESSAGE unchanged, meaning that this,
224 -- or other procedures in this package, or any other procedure can still
225 -- access the FND_MESSAGE stack.
226 --
227 -- Prerequisites:
228 -- This function must be called after a call to provide_error. If provide
229 -- error has not been called beforehand, the results of a call to this
230 -- function are undefined.
231 --
232 -- In Parameters:
233 -- None
234 --
235 -- Post Success:
236 -- The function returns the full error message as defined in the
237 -- FND_NEW_MESSAGES table with the tokens replaced by their appropriate
238 -- values. The message returned will be translated, if the text is
239 -- availble in the FND_NEW_MESSAGES table with the appropriate language
240 -- code.
241 --
242 -- Post Failure:
243 -- This procedure does not fail. Undefined values are returned if the
244 -- function is called before provide_error.
245 --
246 -- Access Status:
247 -- Public.
248 --
249 -- {End Of Comments}
250 --
251 function get_message_text return varchar2;
252 --
253 -- ----------------------------------------------------------------------------
254 -- |----------------< General Documentation and Examples >-----------------|
255 -- ----------------------------------------------------------------------------
256 -- {Start Of Comments}
257 --
258 -- Rationale:
259 -- -----------
260 -- This package can be used to detect when a specific application
261 -- error message has been raised. Then either trap it silently,
262 -- or raise a different error message in it's place. Also provide
263 -- the ability to obtain the value of known tokens.
264 --
265 -- These requirements have come from the HR API strategy, where
266 -- server-side PL/SQL is used to centralise validation and
267 -- process logic. HR Development provide these APIs for
268 -- direct customer use. Also they are called from the core
269 -- product Forms and WEB pages.
270 --
271 -- The APIs perform full validation of data values, regardless
272 -- of which end user interface is being used.
273 --
274 -- When an API discovers a validation rule has been violated
275 -- an application error is raised by calling
276 -- fnd_message.set_name and then fnd_message.raise_error.
277 --
278 -- For many error conditions it is impossible to write one
279 -- piece of text which will explain the problem using
280 -- suitable language for all types of end user:
281 -- a) A technical person directly setting the API
282 -- procedure parameters. i.e. Direct PL/SQL call.
283 --
284 -- b) An experienced HR professional. i.e. Forms end user.
285 --
286 -- c) An inexperienced and infrequent user. i.e. WEB pages.
287 --
288 -- For example, the HRMS APIs use an object_version_number
289 -- value as a locking mechanism. Ideally the error
290 -- text should be different for each type of end user:
291 -- a) "The p_object_version_number parameter value
292 -- does not match the current value for this record."
293 --
294 -- b) "Record has been updated. Requery block to see change."
295 -- i.e. As the FND FORM_RECORD_CHANGED error.
296 --
297 -- c) "This data has been changed by another person. The
298 -- latest changes are shown below."
299 --
300 -- In the WEB pages, case c, an automatic re-query is included.
301 --
302 --
303 -- The APIs should raise the error message containing text
304 -- aimed at technical users. If required, the graphical
305 -- user interface code can trap the error raised by the
306 -- API. Examine any message token values. Then raise a
307 -- different error message containing text suitable for
308 -- a non-technical end user.
309 --
310 -- There may be scenarios where the user interface can
311 -- resolve the issue through additional code, and no
312 -- error text need to be displayed to the end user.
313 --
314 -- Example Uses:
315 -- -------------
316 --
317 -- a) HR Development code to trap a particular application error
318 -- message and raise a different error message instead.
319 -- For example, the API raises an invalid object_version_number
320 -- error message. The Form should trap this message and
321 -- display "Record has been updated. Requery..." instead.
322 --
323 -- begin
324 -- <<procedure call>>
325 -- exception
326 -- when app_exception.application_exception then
327 -- hr_message.provide_error;
328 -- if hr_message.last_message_app = 'PER' then
329 -- if hr_message.last_message = 'HR_7155_OBJECT_INVALID' then
330 -- fnd_message.set_name('FND', 'FORM_RECORD_CHANGED');
331 -- fnd_message.raise_error;
332 -- end if;
333 -- end if;
334 -- -- Do not trap any other errors
335 -- raise;
336 -- end;
337 --
338 --
339 -- b) Consultants and customers calling APIs, want to trap
340 -- ORA and APP errors:
341 --
342 -- declare
343 -- l_message_text varchar2(2000);
344 -- begin
345 -- -- API procedure call
346 -- exception
347 -- when other then
348 -- hr_message.provide_error;
349 -- l_message_text := hr_message.get_message_text;
350 -- -- Write l_message_text to error table or log file
351 -- end;
352 --
353 -- {End Of Comments}
354 --
355 END HR_MESSAGE;
[Home] [Help]