Merge branch 'oramain' into '3.2.0'

Oramain to 3.2.0

See merge request rwp/rwloadsim!37

bin/sqlexplain

@@ -0,0 +1,13 @@
+#!/bin/sh
+
+# RWP*Load Simulator
+#
+# Copyright (c) 2024 Oracle Corporation
+# Licensed under the Universal Permissive License v 1.0
+# as shown at https://oss.oracle.com/licenses/upl/
+#
+# call rwloadsim -u sqlreport.rwl
+
+# bengsig   6-dec-2024 - Created 
+
+exec rwloadsim --pretend-gen-banner='RWP*SQL Explain' -u sqlexplain.rwl "$@"

docs/refman/Makefile.refman

@@ -21,7 +21,7 @@
 
 ALL1=atclause.html bengsig.html compoundstatement.html conditional.html controlloop.html database.html databasedeclaration.html databasestatement.html declaration.html directive.html double.html expression.html filestatement.html histogram.html identifier.html include.html integer.html lob.html lobdeclaration.html multiprocess.html oerstats.html percentiles.html persec.html proceduredeclaration.html randomproceduredeclaration.html randomstringdeclaration.html regex.html runres.html rwlcpu.html rwlman.html rwloadsim.html rwlprogram.html rwlrun.html simpledeclaration.html sqldeclaration.html sqlexecution.html sqlstatement.html statement.html statistics.html string.html sysres.html threadexecution.html useroption.html rwlerror.html random.html procedure.html printfstatement.html cqnthread.html clob.html concatenation.html constant.html cursor.html cursorloop.html directives.html executionblock.html file.html forloop.html fractiles.html function.html functiondeclaration.html histogram_a.html if.html ifstatement.html longoption.html loop.html persec_a.html printline.html readline.html readlob.html readloop.html regexextract.html regexsearch.html regexsubstitute.html run.html runres_a.html rwl.html rwlcpu_a.html scalardeclaration.html sql.html statementlist.html thread.html threads.html userswitch.html variable.html while.html writeline.html writelob.html userhelp.html
 
-ALL2=ashplot.html awrreport.html awreport.html awrdump.html connping.html nettest.html oltp.html oltpcheckkey.html oltpcore.html oltpcreate.html oltpday.html oltpping.html oltpdrop.html oltpfilloe.html oltpforever.html oltpparams.html oltpplot.html oltprun.html oltpscale.html oltpscalereport.html oltpverify.html ovid2.html sqlid2file.html sqlmonitor.html sqlmonitorawr.html ociping.html oltpsetup.html oltpawcols.html oltpplus.html oltpconnect.html utilities.html sqlreport.html netthroughput.html oltpxcset.html oltpxcrun.html oltpxc.html oltpdirectory.html oltpkomment.html ashdata.html rwlash.html filecommands.html
+ALL2=ashplot.html awrreport.html awreport.html awrdump.html connping.html nettest.html oltp.html oltpcheckkey.html oltpcore.html oltpcreate.html oltpday.html oltpping.html oltpdrop.html oltpfilloe.html oltpforever.html oltpparams.html oltpplot.html oltprun.html oltpscale.html oltpscalereport.html oltpverify.html ovid2.html sqlid2file.html sqlexplain.html sqlmonitor.html sqlmonitorawr.html ociping.html oltpsetup.html oltpawcols.html oltpplus.html oltpconnect.html utilities.html sqlreport.html netthroughput.html oltpxcset.html oltpxcrun.html oltpxc.html oltpdirectory.html oltpkomment.html ashdata.html rwlash.html filecommands.html
 
 all: $(ALL1) $(ALL2)
 
@@ -145,6 +145,7 @@ oltpverify.html: ../../man/man2rwl/oltpverify.2rwl
 ovid2.html: ../../man/man2rwl/ovid2.2rwl
 sqlid2file.html: ../../man/man2rwl/sqlid2file.2rwl
 sqlreport.html: ../../man/man2rwl/sqlreport.2rwl
+sqlexplain.html: ../../man/man2rwl/sqlexplain.2rwl
 sqlmonitor.html: ../../man/man2rwl/sqlmonitor.2rwl
 sqlmonitorawr.html: ../../man/man2rwl/sqlmonitorawr.2rwl
 rwlash.html: ../../man/man2rwl/rwlash.2rwl

man/man2rwl/sqlexplain.2rwl

@@ -0,0 +1,67 @@
+.TH sqlexplain "2rwl" "December 2024" "RWP*Load Simulator" "Utilities Syntax"
+.SH NAME
+sqlexplain \- Create an explain plan
+.SH SYNOPSIS
+\fBsqlexplain [options] -l u/p@c sqlid \fR
+.P
+For the provided sqlid, the sqlexplain utility will write an explain plan
+to stdout
+calling dbms_xplan.display_cursor or dbms_xplan.display_awr
+.P
+.SH OPTIONS
+.B -l u/p
+.P
+.B -l u/p@c
+.RS 4
+Compulsory option to provide the username, password, and potentially
+connect string for a database connection that provides access to
+a login with access to various gv$ and dba_ views.
+If you omit /p, rwloadsim will prompt for the password.
+.RE
+.P
+.B --awr
+.RS 4
+Use the display_awr function rather then the display_cursor function from the dbms_xplan package.
+.RE
+.P
+.B --format=' text string '
+.RS 4
+Provide the format argument; the default is 'last, all, allstats'.
+.RE
+.P
+.B --child-no=child#
+.RS 4
+When using the display_cursor function, provide this cursor_child_no, the default is 0.
+.RE
+.P
+.B --sessionid=sid
+.br
+.B --instance=inst#
+.RS 4
+Rather than providing the sqlid as a command line argument, get it by querying
+v$session for the provided sessionid
+or gv$session for the provided sessionid and instance number.
+.RE
+.P
+\fBsqlid\fR
+.RS 4
+.P
+Unless --sessionid is specified, exactly one sqlid must be given as a command line argument.
+.RE
+.SH EXAMPLE
+.nf
+\fC
+sqlexplain -l system/{password} 07rw9znc8g7aj
+\fR
+.fi
+.P
+will print the output of running the query
+select * from table(dbms_xplan.display_cursor('07rw9znc8g7aj',0,'last, all, allstats'))
+to stdout
+.SH COPYRIGHT
+Copyright \(co 2024 Oracle Corporation
+.br
+Licensed under the Universal Permissive License v 1.0
+as shown at https://oss.oracle.com/licenses/upl
+.SH "SEE ALSO"
+rwloadsim(1rwl), sqlreport(2rwl), sqlmonitor(2rwl) sqlmonitorawr(2rwl), utilities(2rwl)

man/man2rwl/sqlmonitor.2rwl

@@ -80,4 +80,4 @@ Copyright \(co 2023 Oracle Corporation
 Licensed under the Universal Permissive License v 1.0
 as shown at https://oss.oracle.com/licenses/upl
 .SH "SEE ALSO"
-rwloadsim(1rwl), sqlreport(2rwl), sqlmonitorawr(2rwl), utilities(2rwl)
+rwloadsim(1rwl), sqlreport(2rwl), sqlmonitorawr(2rwl), sqlexplain(2rwl), utilities(2rwl)

man/man2rwl/sqlreport.2rwl

@@ -58,4 +58,4 @@ Copyright \(co 2023 Oracle Corporation
 Licensed under the Universal Permissive License v 1.0
 as shown at https://oss.oracle.com/licenses/upl
 .SH "SEE ALSO"
-rwloadsim(1rwl), sqlmonitor(2rwl) sqlmonitorawr(2rwl), utilities(2rwl)
+rwloadsim(1rwl), sqlmonitor(2rwl) sqlmonitorawr(2rwl), sqlexplain(2rwl), utilities(2rwl)

public/sqlexplain.rwl

@@ -0,0 +1,79 @@
+# sqlexplain.rwl
+#
+# Copyright (c) 2024 Oracle Corporation
+# Licensed under the Universal Permissive License v 1.0
+# as shown at https://oss.oracle.com/licenses/upl/
+#
+# History
+#
+# bengsig   5-dec-2024 - Creation
+#
+# usage:
+#
+# rwloadsim -ul system/{password}@//host/database sqlexplain.rwl sqlid
+#
+$alwaysmute:206
+
+# If we didn't connect, don't do anything
+$if not defined(default database) $then
+  writeline stderr, "Missing or incorrect -l option; use -h to get help";
+  exit 1;
+$endif
+
+$longoption:file-count=1
+
+integer sessionid, instance;
+integer awr := 0, child_no := 0;
+string format := "last, all, allstats";
+
+	              $userhelp:"Create a sql explain plan by calling dbms_xplan.display_cursor"
+	              $userhelp:"-l usr/pwd@con           : required option to give database logon"
+	              $userhelp:"sqlid                    : if provided, use that sqlid"
+           $useroption:child-no:"--child-no=child#        : provide cursor_child_no, default 0"
+             $useroption:format:"--format='format text'   : provide format, default 'last, all, allstats'"
+          $useroption:sessionid:"--sesssionid=sid         : query v$session for the sqlid"
+           $useroption:instance:"--instance=inst#         : query gv$session"
+                $userswitch:awr:"--awr                    : use display_awr in stead of display_cursor"
+
+$oraerror:stop
+
+string(13) sqlid;
+
+if $# = 1 then
+  sqlid := $1;
+elseif instance is null and sessionid is not null then
+  select nvl(sql_id,prev_sql_id) sqlid
+  from v$session where sid=:sessionid
+  /
+elseif instance is not null and sessionid is not null then
+  select nvl(sql_id,prev_sql_id) sqlid
+  from gv$session where sid=:sessionid
+  and inst_id = :instance
+  /
+end if;
+
+if sqlid = "" then
+  writeline stderr, "\nusage: sqlexplain [--help] [options] -l system/{password}@//host/database sqlid";
+  exit 1;
+end if;
+
+string(10000) plan_table_output;
+
+if awr then
+  for
+    select * from
+    table(dbms_xplan.display_awr(sql_id=>:sqlid,format=>:format))
+    /
+  loop
+    printline plan_table_output;
+  end loop;
+else
+  for
+    select * from
+    table(dbms_xplan.display_cursor(sql_id=>:sqlid,cursor_child_no=>:child_no,format=>:format))
+    /
+  loop
+    printline plan_table_output;
+  end loop;
+end if;
+