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: • [Appendix A] What's on the Companion Disk? 7.2.3 The DBMS_APPLICATION_INFO.SET_ACTION procedure 371 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 −−−−−−−−− −−−−−−−−−− −−−−−−−−−−−−−−−−−−−− [Appendix A] What's on the Companion Disk? 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; [Appendix A] What's on the Companion Disk? 7.2.5 The DBMS_APPLICATION_INFO.SET_MODULE procedure 373 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 stepsofar Any number steptotal Any number sofar Any number totalwork Any number application_data_1 Any number application_data_2 Any number application_data_3 Any number [Appendix A] What's on the Companion Disk? 7.2.5 The DBMS_APPLICATION_INFO.SET_MODULE procedure 374 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 [Appendix A] What's on the Companion Disk? 7.2.6 The DBMS_APPLICATION_INFO.SET_SESSION_LONGOPSprocedure 375 . DBMS_APPLICATION_INFO.SET_MODULE procedure 373 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. 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. 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