Oracle Built−in Packages- P77 ppt

The program does not assert a purity level with the RESTRICT_REFERENCES pragma.7.2.3.2 Example The following procedure could be part of an application that maintains corporate department

The program does not assert a purity level with the RESTRICT_REFERENCES pragma.

7.2.3.2 Example

The following procedure could be part of an application that maintains corporate departmental information:

/* Filename on companion disk: apinex1.sql */*

CREATE OR REPLACE PROCEDURE drop_dept

(deptno_IN IN NUMBER

,reassign_deptno_IN IN NUMBER)

IS

temp_emp_count NUMBER;

BEGIN

DBMS_APPLICATION_INFO.SET_MODULE

(module_name => 'DEPARTMENT FIXES'

,action_name => null);

−− first check dept for employees

DBMS_APPLICATION_INFO.SET_ACTION

(action_name => 'CHECK EMP');

SELECT COUNT(*)

INTO temp_emp_count

FROM emp

WHERE deptno = deptno_IN;

−− reassign any employees

IF temp_emp_count >0

THEN

DBMS_APPLICATION_INFO.SET_ACTION

(action_name => 'REASSIGN EMPLOYEES');

UPDATE emp

SET deptno = reassign_deptno_IN

WHERE deptno = deptno_IN;

END IF;

−− OK, now drop the department

DBMS_APPLICATION_INFO.SET_ACTION

(action_name => 'DROP DEPT');

DELETE FROM dept WHERE deptno = deptno_IN;

COMMIT;

DBMS_APPLICATION_INFO.SET_MODULE(null,null);

EXCEPTION

WHEN OTHERS THEN

DBMS_APPLICATION_INFO.SET_MODULE(null,null);

END drop_dept;

Notice in this example that DBMS_APPLICATION_INFO is called three times to distinguish between the three steps involved in the process of dropping the department This gives a very fine granularity to the level

at which the application can be tracked

7.2.3.3 Recommendations for usage

Note the following recommendations for using the SET_ACTION procedure:

•

Set the action name to a name that can identify the current transaction or logical unit of work within the module

•

When the transaction terminates, call SET_ACTION and pass a NULL value for the action_name parameter In case subsequent transactions do not register using DBMS_APPLICATION_INFO, passing the NULL value ensures that they are not incorrectly counted as part of the current action As

in the example, if the program handles exceptions, the exception handler should reset the action information

7.2.4 The DBMS_APPLICATION_INFO.SET_CLIENT_INFO procedure

The SET_CLIENT_INFO procedure is used to set, or register, additional client information about the user session The registered client information appears in the CLIENT_INFO column of the V$SESSION virtual table The header for this program is,

PROCEDURE DBMS_APPLICATION_INFO.SET_CLIENT_INFO

(client_info IN VARCHAR2);

where the client_info parameter specifies the client information to register into V$SESSION

The program does not raise any exceptions

7.2.4.1 Restrictions

Note the following restrictions on calling SET_CLIENT_INFO:

•

The client_info parameter is limited to 64 bytes Longer values will be truncated to this maximum size

•

The program does not assert a purity level with the RESTRICT_REFERENCES pragma

7.2.4.2 Example

The following procedure could be utilized by an application in which all sessions connect to a common Oracle username and security is handled within the application This would allow the DBA to externally distinguish between user sessions in V$SESSION by examining the CLIENT_INFO column

/* Filename on companion disk: apinex1.sql */*

CREATE OR REPLACE PROCEDURE set_user(app_user_IN IN VARCHAR2)

IS

BEGIN

DBMS_APPLICATION_INFO.SET_CLIENT_INFO(app_user_IN);

END set_user;

Suppose that users JOE SMITH and SALLY DALLY log into the application, which connects to Oracle as the user OPBIP If the application calls the set_user procedure at login, we can distinguish between the database sessions for Joe and Sally in V$SESSION as follows:

SQL> SELECT sid, username, client_info

2 FROM v$session

3 WHERE username='OPBIP';

SID USERNAME CLIENT_INFO

−−−−−−−−− −−−−−−−−−− −−−−−−−−−−−−−−−−−−−−

7.2.4 The DBMS_APPLICATION_INFO.SET_CLIENT_INFO procedure 372

14 OPBIP JOE SMITH

24 OPBIP SALLY DALLY

7.2.5 The DBMS_APPLICATION_INFO.SET_MODULE procedure

The SET_MODULE procedure is used to set, or register, a name for the program that the user is currently executing and, optionally, an action name for the current transaction within the program Registered module and action names appear in the MODULE and ACTION columns of the V$SESSION and V$SQLAREA virtual tables Here's the header for this procedure:

PROCEDURE DBMS_APPLICATION_INFO.SET_MODULE

(module_name IN VARCHAR2

,action_name IN VARCHAR2);

Parameters are summarized in the following table

Parameter Description

module_name Name of the module to register into V$SESSION

action_name Name of the action to register into V$SESSION

The SET_MODULE procedure does not raise any exceptions

7.2.5.1 Restrictions

Note the following restrictions on calling SET_MODULE:

•

The module_name parameter is limited to 48 bytes, and action_name is limited to 32 bytes Longer values for either parameter will be truncated to their respective maximum sizes

•

The program does not assert a purity level with the RESTRICT_REFERENCES pragma

7.2.5.2 Example

The following procedure could be part of an application that maintains employee data:

/* Filename on companion disk: apinex1.sql */*

CREATE OR REPLACE PROCEDURE award_bonus

(empno_IN IN NUMBER

,pct_IN IN NUMBER)

IS

BEGIN

DBMS_APPLICATION_INFO.SET_MODULE

(module_name => 'EMPLOYEE UPDATE'

,action_name => 'AWARD BONUS');

UPDATE emp

SET sal = sal*(1+pct_IN/100)

WHERE empno = empno_IN;

COMMIT;

DBMS_APPLICATION_INFO.SET_MODULE(null,null);

EXCEPTION

WHEN OTHERS THEN

DBMS_APPLICATION_INFO.SET_MODULE(null,null);

END award_bonus;

Oracle recommends that the module name correspond to a recognizable name for the program or logical application unit that is currently executing Examples Oracle provides include the name of the form executing

in a Forms application and the name of a SQL script executing under SQL*Plus

7.2.5.3 Recommendations for usage

Note the following recommendations for using the SET_MODULE procedure:

•

Set the action name to one that can identify the current transaction or logical unit of work within the module

•

When the module terminates, call the SET_MODULE procedure and pass in NULL values for both parameters In the event that subsequent transactions and programs do not register using

DBMS_APPLICATION_INFO, they won't be incorrectly counted as part of the current module As in the example, if the program handles exceptions, the exception handler should reset the module and action information

7.2.6 The DBMS_APPLICATION_INFO.SET_SESSION_LONGOPS

procedure

The SET_SESSION_LONGOPS procedure is used to track the progress of long−running operations by allowing the entry and modification of data in the V$SESSION_LONGOPS virtual table Here's the header for the program:

PROCEDURE DBMS_APPLICATION_INFO.SET_SESSION_LONGOPS

(hint IN OUT BINARY_INTEGER

,context IN NUMBER DEFAULT 0

,stepid IN NUMBER DEFAULT 0

,stepsofar IN NUMBER DEFAULT 0

,steptotal IN NUMBER DEFAULT 0

,sofar IN NUMBER DEFAULT 0

,totalwork IN NUMBER DEFAULT 0

,application_data_1 IN NUMBER DEFAULT 0

,application_data_2 IN NUMBER DEFAULT 0

,application_data_3 IN NUMBER DEFAULT 0);

The parameters are summarized in the following table

Parameter Description

hint Token representing the row to update

context Any number representing the context

stepid Any number representing the stepid

application_data_1 Any number

application_data_2 Any number

application_data_3 Any number

The program does not raise any exceptions, nor does it assert a purity level with the

RESTRICT_REFERENCES pragma

7.2.6.1 Example

The following script loops 1000 times and sets values in the V$SESSION_LONGOPS table as follows:

•

The totalwork value is set to 1000

•

The sofar column is incremented for every iteration

•

The stepsofar column is incremented every 100 iterations

/* Filename on companion disk: apinex2.sql */

DECLARE

longops_row BINARY_INTEGER:=

DBMS_APPLICATION_INFO.set_session_longops_nohint;

step_number NUMBER:=0;

BEGIN

−− get new row in V$SESSION_LONGOPS

DBMS_APPLICATION_INFO.SET_SESSION_LONGOPS

(hint => longops_row);

−− Do operation 1000 times and record

FOR i IN 1 1000

LOOP

DBMS_APPLICATION_INFO.SET_SESSION_LONGOPS

(hint => longops_row

,sofar => i

,totalwork => 1000

,stepsofar => step_number);

−− increment step every 100 iterations

IF MOD(i,100) = 0

THEN

step_number := i/100;

END IF;

END LOOP;

END;

/

After executing the previous PL/SQL block, the following SQL shows the results recorded in

V$SESSION_LONGOPS Notice that the COMPNAM column has been updated by Oracle to indicate that DBMS_APPLICATION_INFO was used to set the row Also notice that Oracle sets rows in

V$SESSION_LONGOPS for internal operations like table scans, and sorts

SELECT sid

,compnam

,stepsofar

,sofar

,totalwork

FROM v$session_longops

WHERE sid = my_session.sid;

SID COMPNAM STEPSOFAR SOFAR TOTALWORK

−−−− −−−−−−−−−−−−−−−−−−−−−−−−− −−−−−−−−− −−−−−−−−− −−−−−−−−−

16 Table Scan 0 0 1

7.2.6 The DBMS_APPLICATION_INFO.SET_SESSION_LONGOPSprocedure 375