Applied Biosystems SQL*LIMS Technical Support Technical Note Document Number: LIMS017 Last Revision Date: 3162004 Software Versions: SQL*LIMS v4.0.16 and v4.1 Platform: All Platforms Authors: Deborah Man and Ken Madsen Subject: How to prepare SQL*LIMS v4.0 and v4.1 to use the API Purpose This article explains the functionality of the SQL*LIMS Application Programming Interface and outlines the setup process to prepare for using the API with the SQL*LIMS application. Definition The Application Programming Interface or API is a set of PLSQL packaged procedures that can be used as an alternative to traditional Oracle Forms to enter new data or alter existing data while maintaining data integrity and interrelationship of the Oracle database tables. The advantage of using an API is that it allows you to perform data entry without manually entering the information into the application. The API can be called by a direct SQL*Plus call or executed by a PLSQL module. The API packages should never be modified. However, APIs can be used as building blocks to be called within a more extensive package (or wrapper) that you may build to address specific functionality. Scope and Application SQL*LIMS application has an API to allow adding and entering attributes, entering results and some logging. The following are the packages that implement the API in our application: SQLLIMS_RECORDS_API: Defines constants and record types used by the other API packages. This package is available as well for end-user use. ATTRIBUTES_API: Contains specific procedures for adding and entering attributes or parameters for submission, sample, task, and result records. LOGGING_API: Contains specific procedures for adding samples to submissions and methods to samples. RESULT_API: Contains specific procedures for creating, changing, entering, and finding results, and procedures to fire calculations and add and enter attributes. It offers similar function as Automatic Result Entry (ARE) included in the core product. ERROR_HANDLING_API: Contains specific procedures for getting, saving, and displaying error messages to the caller. Procedures developed against these API functions will work directly on SQL*LIMS v4.0 or v4.1 and allow changes to the database without going through standard SQL*LIMS Forms. Page 1 of 9
With SQL*LIMS v4.0 and v4.1, we also ship a PLSQL package called the Wakeup Package, which contains a number of procedures to communicate with the Dispatcher and wake up the Logger, Status Monitor, Event Monitor or Lot Monitor to process requests. The Wakeup package is not explicitly defined in the API, but for all intents and purposes can be treated as an API procedure. It is needed with many of the API calls so that request records processing can be initiated. The original usage of API is for instrument interfacing as in the case of Labtronics IDM-LimsLink support so that attribute values and result values can be entered programmatically. The API calls available in SQL*LIMS v4.1 are also considered as an option to Automatic Result Entry (ARE). The use of the API is entirely up to you based on your specific operating environment. Preparation 1. The sm_logging package body is missing for SQL*LIMS v4.1 migration for 2-tier or 3-tier,. The specification, sml.spec is loaded correctly but not for sml.pkg. There is a procedure in the sm_logging package (file sml.pkg) that is called internally by the logging procedure. Without this package body, logging and logging_api will not work correctly in sample logging process. To create the package body, login as LIMS owner to reload the sm_logging package and run the revalidate_all script on the server. -- Bring up sqlplus in the following directories on the server and login as LIMS Owner. C:\sqllimssvr41\v4_1_0\packages>sqlplus SQL> drop public synonym naip_sm_logging; Synonym dropped. SQL> @sml.spec Package created. Synonym created. SQL> @sml.pkg -- switch to C:\sqllimssvr41\v4_1_0\sql and login as the LIMS owner to clean up any invalid -- objects. Make sure you download our latest version of revalidate_all.orig attached to the -- QA40165_011 patch from our website. Make sure to replace '%DB_OWNER%' with your LIMS owner -- account, e.g., 'OPS$LIMS3T' in the script 'revalidate_all.orig' and saved it as -- 'revalidate_all.sql' before running. C:\sqllimssvr41\v4_1_0\sql>sqlplus SQL> @revalidate_all.sql 2. Apply the patch that is specific to the SQL*LIMS version installed on your system. 2.1 For SQL*LIMS v4.1 Apply the Result API and Wakeup Package patch (SL410_001), which adds these features to the API: In wakeup, initialize client can run as either a LIMSUSER account or the Oracle account that matches a SQL*LIMS user. Change_Result will automatically bring the instance tree ONLINE when a result in an approval condition is changed. Create_Result will set the result sequence column to the next highest sequence number for a task. Add_Result_Attribute will default attribute to hid=n, upd=y when not specified. Page 2 of 9
Follow the patch release notes or the steps below to apply this patch: 2.1.1. Stop all SQL*LIMS monitors. 2.1.2. Copy the two PLSQL package bodies in this patch (results.pkg and wakeup.pkg) to a directory on the server. Login as LIMS owner to run the scripts: SQL> drop public synonym naip_result_api; Synonym dropped. SQL> @results.pkg SQL> @wakeup.pkg SQL> @result_api.spec Package created. Synonym created. SQL> @result_api.pkg -- query for invalid objects SQL>select object_name, object_type, owner from all_objects where status = 'INVALID'; -- navigate to C:\sqllimssvr41\v4_1_0\sql to run revalidate_all.sql to recompile all invalid -- objects. Make sure to edit the script first with LIMS owner logon name. -- e.g. owner = 'OPS$LIMS3T') SQL> sqlplus SQL> @revalidate_all.sql 2.1.3. Start all SQL*LIMS monitors. 2.2 For SQL*LIMS v4.0 Apply Labtronics IDM-LimsLink support patch (SL4016_020B) to obtain integration support to use both API and Wakeup Packages. This patch adds these features to the API in addition to the base API that the prior versions of the support patch added: In wakeup, initialize client can run as either a LIMSUSER account or the Oracle account that matches a SQL*LIMS user. Change_Result will automatically bring the instance tree ONLINE when a result in an approval condition is changed. Create_Result will set the result sequence column to the next highest sequence number for a task. Page 3 of 9
Follow the patch release note or the steps below to apply this patch: 2.2.1 Stop all SQL*LIMS monitors. 2.2.2 Download the patch to a directory on the server. Login as LIMS Owner and run the following scripts: SQL>drop public synonym naip_extras; SQL>drop public synonym naip_sqllims_records; SQL>drop public synonym naip_make_status_request; SQL>drop public synonym naip_attributes_api; SQL>drop public synonym naip_result_api; SQL>drop public synonym naip_results; -- run the scripts from the patch SQL>@SQLLIMS_records.spec SQL>@make_status_request.spec SQL>@extras40.spec SQL>@Attributes_Parameters_API.spec SQL>@results.spec SQL>@Result_API.spec -- Separate files exist for make_status_request package. For SQL*GT or Life Science LIMS option, -- run make_status_request_sqlgt.pkg. SQL>@make_status_request_sqlgt.pkg -- All other cases without SQL*GT and Life Science LIMS option, run make_status_request.pkg. SQL>@make_status_request.pkg -- Then, in all cases, load the following packages: SQL>@extras40.pkg SQL>@Attributes_Parameters_API.pkg SQL>@results.pkg SQL>@Result_API.pkg SQL>@wakeup.pkg -- Edit revalidate_all.sql by replacing the <LIMS_OWNER> keyword with the exact Oracle logon -- LIMS Owner name and run the script. SQL>@revalidate_all.sql -- Change to the LIMS_PROGRAMS directory, e.g. c:\sqllimssvr\v4_0_16\bin to run SGU commands -- to grant the synonyms to all of the LIMS Users. cd C:\sqllimssvr\v4_0_16\bin C:\sqllimssvr\v4_0_16\bin >sgu ops$penlimspenlims option=2 synonym=naip_extras C:\sqllimssvr\v4_0_16\bin >sgu ops$penlimspenlims option=2 synonym=naip_sqllims_records C:\sqllimssvr\v4_0_16\bin > sgu ops$penlimspenlims option=2 synonym=naip_make_status_request C:\sqllimssvr\v4_0_16\bin > sgu ops$penlimspenlims option=2 synonym=naip_attributes_api C:\sqllimssvr\v4_0_16\bin > sgu ops$penlimspenlims option=2 synonym=naip_result_api C:\sqllimssvr\v4_0_16\bin > sgu ops$penlimspenlims option=2 synonym=naip_results 2.2.3 Start all SQL*LIMS monitors. Page 4 of 9
3. Verify the following synonyms are in the database by using the 'describe' command in SQL*Plus session: Synonyms naip_attribute_api naip_error_handling_api naip_extras naip_logging_api naip_make_status_request naip_pen_error naip_results naip_result_api naip_samples naip_sm_logging naip_sqllims_records naip_submissions naip_tasks naip_wakeup -- 'describe' command will list out all procedures in the package. SQL> desc naip_wakeup; PROCEDURE DISPATCHER Argument Name Type InOut Default? SERVER_PROCESS VARCHAR2 IN REQUEST_ID NUMBER IN STATUS NUMBER INOUT PROCEDURE GET_PIPE_NAME Argument Name Type InOut Default? RETSTR VARCHAR2 INOUT PROCEDURE INITIALIZE_CLIENT Argument Name Type InOut Default? SQLLIMS_HOST VARCHAR2 IN SQLLIMS_SID VARCHAR2 IN STAT NUMBER INOUT PROCEDURE SHUTDOWN_CLIENT Argument Name Type InOut Default? STAT NUMBER INOUT 4. Error Messages When a procedure returns a failure status (stat = 1), there may be messages saved by our package, pen_error (synonym naip_pen_error). To retrieve our error messages programmatically, use the stored procedure get_error within the pen_error package. This returns the message text into a string variable. PROCEDURE GET_ERROR Argument Name Type InOut Default? ERR_MESSAGE VARCHAR2 OUT MESSAGE_LEN NUMBER OUT Page 5 of 9
To display error messages from the pen_error pipe: DECLARE msg VARCHAR2(256); len NUMBER; naip_pen_error.get_error (msg, len); dbms_output.put_line ('msg is ' msg); 5. There are basically two ways to establish a client session connecting to SQL*LIMS for the Wakeup Package. Use the public shared client pipe in the wakeup package Use initialize_client procedure to create a client pipe for a particular client session By default, 'TEST_SA_PACK_9999_WAKEUP' is a public shared client pipe in the wakeup package. If no other client pipe is built, this public pipe will be automatically created and stay on for all wakeup users after naip_wakeup is executed. Messages sent or received by all wakeup users will go through the same buffer of this client pipe. Depending on the client pipe size and the number of wakes sent to the monitors, this public client pipe can be easily overloaded posing potential risks such as overwriting messages or rendering the Dispatcher and other monitors too busy to be responsive to other Oracle Forms users. While using the public client pipe remains a feasible option, it is preferable to create your own pipe using the Initialize_Client procedure. 5.1. The example below shows the Initialize_Client procedure to build a client pipe to receive communication from the server. This should be used only ONCE PER SESSION. SQL>DECLARE -- Substitute correct values for your test system here hostname VARCHAR2 (15) := 'LIFTS'; -- Hostname of server where Dispatcher resides sid VARCHAR2 (10) := 'LIMS3T'; stat NUMBER; msg VARCHAR2(256) := 'Test'; -- Initialize to dummy value len NUMBER; stat := naip_sqllims_records.success; naip_wakeup.initialize_client (hostname, sid, stat); IF stat = Naip_SQLLIMS_Records.SUCCESS THEN DBMS_OUTPUT.PUT_LINE ('Client initialization completed.'); ELSE naip_pen_error.get_error (msg, len); DBMS_OUTPUT.PUT_LINE ('Client initialization failed.'); DBMS_OUTPUT.PUT_LINE (msg); END IF; Client initialization completed. PLSQL procedure successfully completed. -- Caution: A separate client pipe 'GTCL_LIFTS_LIMS3T_<audsid>_OPS$LIMS3T' will be created -- every time the Initalize_Client procedure is executed. If there are several API users -- using Initialize_Client, each of them will be working with their own exclusive pipes for -- sending and receiving messages. Page 6 of 9
5.2 Parameters passed to the Initialize_Client procedure are hostname, sid, and stat. hostname is the server name where the Dispatcher resides. sid is the SQL*LIMS instance. stat is the procedure s return status and can be translated to a readable form by the constant definitions in naip_sqllims_records: SUCCESS CONSTANT NUMBER := 0; FAILURE CONSTANT NUMBER := 1; 5.3 Exercise care when using the wakeup package when constructing your PLSQL programs. Never overuse the initialize_client procedure because a separate client pipe will automatically be created whenever the initialize_client procedure is called. Once created, the pipe persists in the shared memory until you explicitly remove it or until the database instance is shut down. Remember, Initialize_Client procedure and Shutdown_Client procedure should be used in pairs. Whenever you create a client pipe with Initialize_Client, you should use Shutdown_Client to clean up the pipe at the end of your session. Shown below is an example of how to use the Shutdown_Client procedure. The pipe will still be present after shutdown; however, any memory it used will be released. Oracle will age these empty implicitlycreated pipes out of the SGA. SQL>DECLARE stat msg len NUMBER; VARCHAR2(256) := 'Test'; NUMBER; naip_wakeup.shutdown_client (stat); If stat = naip_sqllims_records.success THEN DBMS_OUTPUT.PUT_LINE ('Shutdown client completed.'); ELSE naip_pen_error.get_error(msg, len); DBMS_OUTPUT.PUT_LINE ('Shutdown client failed.'); DBMS_OUTPUT.PUT_LINE (msg); END IF; Shutdown client completed. PLSQL procedure successfully completed. Page 7 of 9
5.4 Where appropriate, query v$db_pipes to monitor the database pipes. Example shows certain pipes only there will be more present in an actual query. SQL> select * from v$db_pipes; OWNERID NAME TYPE PIPE_SIZE --------- ----------------------------------- ------- --------- DISPATCHER_LIFTS_LIMS3T PUBLIC 556 -- Determine your sessions unique identifier (AUDSID) SQL>select userenv('sessionid') from dual; USERENV('SESSIONID') -------------------- 1944 SQL>DECLARE stat number; naip_wakeup.initialize_client('lifts', 'LIMS3T', stat); PLSQL procedure successfully completed. SQL> select * from v$db_pipes; OWNERID NAME TYPE PIPE_SIZE --------- ----------------------------------- ------- --------- DISPATCHER_LIFTS_LIMS3T PUBLIC 556 GTCL_LIFTS_LIMS3T_1944_OPS$LIMS3T PUBLIC 566 -- 'GTCL_LIFTS_LIMS3T_1944_OPS$LIMS3T' is a client pipe created explicitly in this -- client session. It will stay present and is independent of the termination of your -- sqlplus session. Execute Shutdown_Client procedure to ready it for removal by Oracle. SQL>DECLARE stat number; naip_wakeup.shutdown_client(stat); PLSQL procedure successfully completed. 5.5 Occasionally, bulk data loads will fill up the client pipe resulting in the Dispatcher or other monitors becoming too busy to be responsive. Because all pipes share a single buffer, it is a best practice for you to minimize the number of wakes to the monitors. One way to do this is to use API to process several requests such as entering results for 10 tasks and then followed by using Wakeup Package to wake up Status Monitor once. Another way is to programmatically put the wakeup procedure outside the loop for entering results in your PLSQL program so that the number of wakes can be kept to a manageably low number to be handled by the monitors. Think of this as a typical Forms session, where the user can enter multiple results over time and commit more than one time in that form. The form only wakes the monitor when the form is exited, that is, when all the work is completed. Page 8 of 9
5.6. Shown below is an example of how to make the changes in the wakeup package so that it will work in a 3-tier environment. Note: This is only needed if you don t use initialize_client. -- Edit the package body of Wakeup. -- Locate and hardcode the dispatcher_pipe_name in the beginning of the package body. -- (Default value is null) dispatcher_pipe_name VARCHAR2(40) := 'DISPATCHER_LIFTS_LIMS3T'; max_timeout INTEGER := null; -- seconds max_pipe_size INTEGER := 20000; instance_name VARCHAR2(20) := null; machine_name VARCHAR2(20) := null; the_delimiter char := '_'; -- Note: LIFTS is the application server name and LIMS3T is the instance name. -- max_timeout is the time (in second) to wait while attempting to place a message on a pipe. -- If max_timeout value in the above section is set to null, wakeup package will go by the -- disp_timeout value in NAI_CONFIGURABLE_VALUES i.e. 20 seconds as default. -- Reload wakeup package for the changes to take effect. -- Navigate to sqllimssvr41\v4_1_0\packages directory and login as Lims Owner to run the -- following script. SQL> @wakeup.pkg 6. All SQL*LIMS monitors must be up, especially the following ones: POD Dispatcher Logger Status Monitor At this point, the system is getting ready to test the API. For more information on how to use the API, please refer to our technical note LIMS018: Case Studies How to use the API and wakeup package to perform standard API functions. Page 9 of 9