MANUAL.md

   1 % Stew4 User Manual
   2 %
   3 % version 4.0
   4
   5
   6 ## What Is Stew ?
   7
   8 ...
   9
  10
  11 ## PRECAUTIONS
  12
  13 ### Password Management
  14
  15 ...
  16
  17
  18 For details, see [How To Use - Connector Settings](#Connector-Settings).
  19
  20
  21 ### Rollback Does Not Work When The Connection Is Disconnecting
  22
  23
  24 ...
  25
  26
  27 For details, see [How To Use - Connector Settings](#Connector-Settings).
  28
  29
  30 ### Other
  31
  32 For more information, see the project site.
  33 <http://stew.sourceforge.jp/>
  34
  35
  36 ## Installation
  37
  38
  39 ...
  40
  41
  42
  43 ## Running App
  44
  45 If you want to use GUI mode, execute the following command:
  46
  47     > java -jar stew.jar --gui
  48
  49 If you want to use CUI mode, execute the following command:
  50
  51     > java -jar stew.jar --cui
  52
  53 At first time, a system directory ".stew" created. It is used by some configurations.
  54 By default, ".stew" creates at the current directory.
  55
  56
  57 ## Uninstallation
  58
  59 Remove all of installed files and ".stew" directory.
  60
  61
  62 ----------------------------------------------------------------------------------------------------
  63
  64 ## Usage
  65
  66 To access database with Stew, you need DBMS that supports JDBC and its JDBC driver.
  67 For details, see the manual of DBMS.
  68
  69
  70 ### Configuration Of "Connector"
  71
  72 In Stew, an asset of JDBC Connection called it "Connector".
  73
  74 In CUI mode, to start edit tool, specifies --edit option.
  75
  76     # command line
  77     $ stew --edit
  78     # running stew
  79     > --edit
  80
  81 In GUI mode, executes "Edit Connectors" to start edit dialog.
  82
  83
  84 Connector has the following properties:
  85
  86 Connector ID
  87 :   ID for connector command. Allows only ASCII letters (A-Za-z0-9).
  88
  89 Connector Name
  90 :   The name to display at Prompt.
  91
  92 Classpath
  93 :   Specifies classpath of JDBC driver. This form is same with -CLASSPATH option.
  94
  95 Driver
  96 :   Specifies the driver class that implements java.sql.Driver.
  97     (In GUI mode, you can use the "search Driver" button.)
  98
  99 URL to connect
 100 :   Specifies JDBC URL (same as url at DriverManager.getConnection(url)).
 101
 102 User
 103 :   Specifies the user ID.
 104
 105 Password
 106 :   Specifies the password of its user ID.
 107
 108 Encryption
 109 :   Specifies the type to save password into file.
 110     See the next section.
 111
 112 Readonly
 113 :   Is set to READONLY the connection, so that you can not run the commands that update.
 114  (., Which according to ReadOnly the command side)
 115
 116 Auto Rollback
 117 :   If it was set, the transaction will be rollbacked automatically when disconnect.
 118
 119
 120
 121 ### About Password Management
 122
 123 How to save the password, you can select the encryption process.
 124
 125 PlainTextPassword
 126 :   Saves as plain text. (default)
 127
 128 PbePassword
 129 :   You can store your password by using the PBE encryption.
 130
 131
 132 ### Anonymous Connector
 133 ### Interactive Mode
 134 ### Non-interactive Mode
 135 ### Alias
 136 ## Commands
 137 ### connect - Connects to database (built-in)
 138
 139     > connect <connector-id>
 140     > -c <connector-id>
 141
 142 This command connects to database with prepared Connector.
 143
 144 In interactive mode, connection is kept until disconnect.
 145 If already connected, disconnect it first, then connect.
 146
 147
 148 ### disconnect - Disconnects from database (built-in)
 149
 150     > disconnect
 151     > -d
 152
 153 This command disconnects from database.
 154
 155 If auto-rollback was available, try to rollback before disconnecting.
 156
 157
 158 ### commit - Commits current transaction (built-in)
 159
 160 This command commits current transaction.
 161
 162 ** caution: Commit cannot cancel. Please use carefully. **
 163
 164
 165 ### rollback - Rollbacks current transaction (built-in)
 166
 167 This command rollbacks a current transaction.
 168
 169
 170 ### -e - Evaluates multiple commands (built-in)
 171
 172     > -e <command> -e <command> ...
 173
 174 For example, you can execute two export command continuously,
 175  or can execute as batch in non-interactive mode.
 176
 177
 178 ### -f - Executes file content as command (built-in)
 179
 180     > -f <file>
 181
 182 ...
 183
 184
 185 ### -s - Executes file content as script (built-in)
 186
 187     > -s <file>
 188
 189 ( default=JavaScript )
 190
 191 The following variables will be available in the script:
 192
 193  * object of current connection: connection, conn
 194  * object of Parameter: parameter, p
 195  * object of OutputProcessor: outputProcessor, op
 196
 197
 198 ### cd - Changes current directory (built-in)
 199
 200     > cd <directory>
 201
 202 Changes current directory to specified one.
 203 (This current directory is not OS's, but internal Stew.)
 204
 205
 206 ### @ - Displays directories (built-in)
 207
 208     > @
 209
 210 Displays the paths of current directory and system directory.
 211
 212
 213 ### ? - Displays System Properties (built-in)
 214
 215     > ? [<property-name> [<property-name-2> ... <property-name-n>]]
 216
 217 Display System Properties. (System.getProperty)
 218
 219 By defauts, it displays JRE, OS and Locale.
 220
 221     > ?
 222     JRE : ...
 223     OS : ...
 224     Locale : ja_JP
 225     > ? java.version user.timezone zzz
 226     java.version=[1.6.0_##]\r
 227     user.timezone=[Europe/London]\r
 228     zzz=undefined\r
 229
 230
 231 ### alias - Registers alias (built-in)
 232
 233     > alias [<name> [<command>]]
 234
 235 Registers the alias of command.
 236 When called with an argument, display the alias and its command.
 237 When called without arguments, display all aliases.
 238
 239 Before registering or displaying, refreshes cached info in memory.
 240 If modified aliases in another process, includes you directly edit the config file,
 241 run this command.
 242
 243 (implementation details:
 244  for the infinite loop suppression of circular references,
 245  the depth of the expansion up to 100.)
 246
 247     > alias
 248     No aliases.
 249     > alias search select * from
 250     > alias count select count(*) from
 251     > alias search
 252     alias search=[select * from]
 253     > search table1
 254     >> select * from table1
 255     (diplays the results of "select * from table1")
 256     >
 257
 258
 259 ### unalias - Removes alias (built-in)
 260
 261     > unalias <alias>
 262
 263 If the specified alias does not exist, does nothing.
 264 Whether the target exists or not, refreshes cached info in memory.
 265
 266
 267 ### exit - Exits application (built-in)
 268
 269     > exit
 270
 271 This command exits Stew without confirmation.
 272
 273 All connections will be disconnected automatically.
 274 Rollback will do only the connector set auto-rollback option.
 275 For automatic rollback, see [Usage - Configuration Of "Connector"](#configuration-of-connector).
 276
 277
 278 ### load - Executes file content as SQL
 279
 280     > load [<SQL-file> | <data-file> <table-name> [ HEADER ]]
 281
 282 This command executes the SQL read from specified file.
 283
 284 When If a parameter is specified, executes file content as SQL,
 285 otherwise, two or more parameters, imports the file as data file.
 286 The file format is automatically selected by file extension.
 287  *. .csv : CSV format
 288  *. .xml : XML format (definition: src/net/argius/stew/io/stew-table.dtd)
 289  *. otherwise: TSV format
 290
 291 (implementation detail: this is basically same as import command,
 292                         executes as not batch but executes by record)
 293
 294
 295 ### import - Imports from file
 296
 297     import <data-file> <table-name> [ HEADER ]
 298
 299 This command imports from file as data file.
 300 The file format is automatically selected by file extension.
 301  *. .csv : CSV format
 302  *. .xml : XML format (definition: src/net/argius/stew/io/stew-table.dtd)
 303  *. otherwise: TSV format
 304
 305 (implementation detail: this is basically same as load command,
 306                         but uses Statement#addBatch.)
 307
 308
 309 ### export - Exports to file
 310
 311 This command exports result of command to the specified file.
 312 The file format is automatically selected by file extension.
 313  *. .htm,html : HTML format
 314  *. .csv : CSV format
 315  *. .xml : XML format (definition: src/net/argius/stew/io/stew-table.dtd)
 316  *. others: TSV format
 317
 318
 319 ### time - Measures time to execute SQL
 320
 321     > time [<count>] <SQL>
 322
 323 This command executes specified SQL and measures its execution time.
 324
 325 If specified count, executes SQL by count continuously
 326  and summaries "Total", "Ave(average)", "Max" and "Min".
 327 Otherwise, executes once and measure its execution time.
 328
 329     > time select * from EMPLOYEE
 330     execution time: 0.093 seconds
 331     > time 100 select * from EMPLOYEE
 332     Total: 0.484 seconds
 333       Ave: 0.005 seconds
 334       Max: 0.094 seconds
 335       Min: 0.000 seconds
 336     >
 337
 338
 339 ### find - Finds table names
 340
 341     > find <table-name-pattern> [<table-type-pattern> [<schema-pattern> [<catalog-pattern> [ FULL ]]]]
 342
 343 This command displays list of tables allowed to show.
 344 The parameter including "pattern" in its name can be specified wildcard (#,?).
 345
 346
 347 ### report - Reports database info
 348
 349     > report - | <table-name> [ FULL | PK | INDEX ]
 350
 351 This command displays the info about current connection and connecting database.
 352
 353 If specifies - (hyphen), displays the name and version of database and JDBC driver,
 354  user and JDBC address.
 355
 356 If only specifies table name, displays the column info about specified table.
 357
 358 If specifies table name and option,
 359 displays the primary key or index info about specified table.
 360
 361
 362 ### download - Downloads a column as file
 363
 364     > download <root-dir> SELECT <data-column> [, file-path...] FROM ...
 365
 366 This command downloads a column data by rows and saves to file.
 367
 368 For any data type.
 369 It is useful for downloading large text data or large objects (BLOB, CLOB) all at once.
 370
 371 In order to be able to download multiple files,
 372 generates file name using column data.
 373
 374 The file name will be generated by concatenate second column and after as string.
 375 This supporses to specify primary keys and file extension.
 376
 377     > download emp select FULL_NAME, JOB_COUNTRY, '/', EMP_NO, '.txt' from EMPLOYEE
 378     The dir[./emp/USA] was created.
 379     Downloaded. (size=14bytes, file=./emp/USA/2.txt)
 380     Downloaded. (size=12bytes, file=./emp/USA/4.txt)
 381      .
 382      .
 383      .
 384     Downloaded. (size=12bytes, file=./emp/USA/24.txt)
 385     The dir[./emp/England] was created.
 386     Downloaded. (size=11bytes, file=./emp/England/28.txt)
 387      .
 388      .
 389      .
 390     Downloaded. (size=18bytes, file=./emp/USA/145.txt)
 391     Selected 42 records.
 392
 393 When data exist a record, specified <data-column>,
 394 saves file to <root-dir> as file name.
 395
 396 Saving file already exists or no permission to write file,
 397 the process will abort immediately.
 398
 399
 400 ### upload - Uploads file data to a column
 401
 402     > upload <file> <SQL(UPDATE|INSERT)>
 403
 404 This command registers a data file to the column that specified by place-holder.
 405
 406
 407 ### wait - Waits for specified interval
 408
 409     > wait seconds()
 410
 411 This command waits for the interval that specified number of seconds.
 412 It may be useful for executing multiple commands.
 413
 414
 415
 416 ## The GUI Mode
 417
 418 ### Common Behaviors
 419
 420 Standard commands, "undo", "redo", "cut", "copy", "paste", and "select all", can use in all text components via context menu or shortcut key.
 421
 422
 423 ### Main Window
 424
 425 A window has "Input/Output Area", "Result Set Table", "Database Info Tree", "Main Menu", "Status Bar" and "Find Pane".
 426 By default, the database info tree, the status bar and the find pane" are hidden.
 427
 428
 429 ### Input/Output Area
 430
 431 The I/O area is similar to CUI interface.
 432
 433 ... When cursor is at the end of textarea, executes command which is string from prompt to the end of textarea.
 434 ... Otherwise, move cursor to the end of textarea.
 435 ... The part before prompt can't edit.
 436
 437
 438 ... Context menus for this component has the standard commands.
 439
 440
 441 ### Result Set Table
 442
 443 The result set table displays command results, usually query results from database.
 444
 445 The row header (the leftmost of the table) displays the row number.
 446 ... display "+" sign instead of the row number in the row header.
 447
 448 Automatic column width adjustment ...
 449
 450
 451 The context menu for this component are listed below:
 452
 453
 454 Sorts clicked column
 455 :   This command sorts clicked column, not a selected one.
 456     The same column is sorted continuously, ... reverse.
 457
 458 Copy (Ctrl-C)
 459 :   This command copies selected cell values as text into the clipboard.
 460
 461 Copy With Escape (Ctrl+Shift-C)
 462 :   This command copies selected cell values as quoted strings into the clipboard.
 463
 464 Paste (Ctrl-V)
 465 :   This command pastes values into selected cells from the clipboard.
 466     Type conversion from the text to column types of the cells depends on each JDBC driver implementation.
 467
 468 Select All (Ctrl-A)
 469 :   This command selects all cells in the table.
 470
 471 Clear Selected Cell Value
 472 :   This command clears selected cell values (actually sets NULL).
 473
 474 Set Current Time Value
 475 :   This command sets current time (Timestamp) into selected cells.
 476
 477 Copy Column Names
 478 :   This command copies the table header as text into the clipboard.
 479
 480 Find Column Name
 481 :   This command shows the find pane and sets find target ...
 482
 483 Add New (Empty) Row
 484 :   This command adds a new empty row into the table.
 485
 486 Insert From Clipboard
 487 :   This command ... imports data from the clipboard and inserts the data into the linking table.
 488
 489 Duplicate Rows
 490 :   This command adds duplicate rows ... selected cells.
 491
 492 Link Rows Into Database
 493 :   This command make unlink  ...
 494
 495 Delete Rows
 496 :   This command deletes selected rows.
 497     The deleted rows are also deleted from database.
 498
 499
 500
 501 ### Database Info Tree
 502
 503 The database info tree is a tree view of hierarchical structure, which consists
 504  catalogs, schemas, tables, table type and columns as a tree.
 505 Not connected: blank ...
 506 just connected: connector as a root node and sub nodes ...
 507 Each node expands ...
 508
 509
 510 An "Auto-expansion" is a function to automatically expands nodes in the database info tree when connecting a database.\r
 511 If you use it, create a TSV file named "autoexpansion.tsv" in the system directory (.stew) and write node name lists as TSV into this file.
 512
 513
 514 The context menu for this component are listed below:
 515
 516
 517 Copy
 518 :   This command copies displayed strings of selected nodes as text into the clipboard.
 519
 520 Copy Simple Name
 521 :   This command copies the simple name of selected nodes as text into the clipboard.
 522
 523 Copy Full Name
 524 :   This command copies the full qualified name of selected nodes as text into the clipboard.
 525
 526 Refresh
 527 :   This command ...
 528
 529 Generate WHERE Phrase
 530 :   This command generates a WHERE phrase consisting selected tables and columns ...
 531     selected same name, generate ...
 532
 533 Generate SELECT Statement (with WHERE)
 534 :   This command generates a SELECT statement with "WHERE" keyword.
 535
 536 Generate UPDATE Statement (with WHERE)
 537 :   This command ...
 538
 539 Generate INSERT Statement
 540 :   This command ...
 541
 542 Jump To Column By Name
 543 :   This command ... the name of selected node. Jump to the column which has the same name in current result table if found it.
 544     Double-clicking the node is the same as this command.
 545
 546 Toggle Show Column Number
 547 :   This command provides the toggle between showing and hiding the column number of all columns nodes.
 548
 549
 550 ### Main Menu
 551
 552 See Menus ...
 553
 554
 555 ### Status Bar
 556
 557 ... Display last command and its execution time.
 558 ...This time is not query but command.
 559
 560
 561 ### Saving Configuration
 562
 563 ...
 564
 565
 566 ### Key Binding
 567
 568 ...
 569 It is not able to change key bind after opening new window.
 570 ... For the keywords, see https://github.com/argius/Stew4/blob/master/src/net/argius/stew/ui/window/Menu.u8p
 571
 572
 573 ## Menus in the GUI Mode
 574
 575 ### File - New Window (N) Ctrl-N
 576
 577 This command opens a new window.
 578 Current connections are independent of each window.
 579
 580
 581 ### File - Close Window (C) Ctrl-W
 582
 583 This command closes current window.
 584 If connected, show confirm dialog.
 585
 586 If current window is only a window, processes as Quit(Q).
 587
 588
 589 ### File - Quit (Q) Ctrl-Q
 590
 591 This command quits this application.
 592 When executed, shows confirm dialog. Click "Yes" to quit.
 593
 594
 595 ### Edit - Cut (T) Ctrl-X
 596
 597 This command cuts the selection to the clipboard.
 598
 599
 600 ### Edit - Copy (C) Ctrl-C
 601
 602 This command copies the selection to the clipboard.
 603
 604
 605 ### Edit - Paste (P) Ctrl-V
 606
 607 This command pastes the selection to the clipboard.
 608
 609
 610 ### Edit - Select All (A) Ctrl-A
 611
 612 This command selects all text or all elements.
 613
 614
 615 ### Edit - Find (F) Ctrl-F
 616
 617 This command finds out a specific string from selected component.
 618
 619 ...
 620
 621
 622 ### Edit - Toggle focus (G) Ctrl-G
 623
 624 This command toggles focus between the result set table and the input/output area in a current window.
 625
 626 ### Edit - Clear Message (M)
 627
 628 This command clears input/output area in a current window.
 629
 630
 631 ### View - Show Status Bar (S)
 632
 633 This command toggles the visibility of status bar in a current window.
 634
 635
 636 ### View - Show Column Number (C)
 637
 638 This command toggles the visibility of column number in the result set table of a current window.
 639
 640
 641 ### View - Show Info Tree (I)
 642
 643 This command toggles the visibility of database info tree in a current window.
 644
 645
 646 ### View - Always On Top (T)
 647
 648 This command toggles the state that always stays on top of a current window.
 649
 650
 651 ### View - Refresh (R) F5
 652
 653 This command ...
 654
 655
 656 ### View - Widen Column Width (W) Ctrl-.(period)
 657
 658 This command widens all column widths in the result set table of a current window.
 659
 660
 661 ### View - Narrow Column Width (N) Ctrl-,(comma)
 662
 663 This command narrows all column widths in the result set table of a current window.
 664
 665
 666 ### View - Adjust Column Width (A) Ctrl-/(slash)
 667
 668 This command adjusts all column widths in the result set table of a current window.
 669 For about adjust mode, see the next item.
 670
 671
 672 ### View - Auto Adjust Mode (M)
 673
 674 This command selects auto-adjusting mode to use when shows result.
 675
 676 There are following modes:
 677
 678  * None(N): does nothing.
 679  * Header(H): adjusts column width based on each header string.
 680  * Value(V): adjusts based on the longest string in column values.
 681  * Header And Value(A): adjusts based on the longest string in column values and column header string.
 682
 683
 684 ### Command - Execute (X) Ctrl-M
 685
 686 This command executes command.
 687 This is same as pressing enter key in the end of the I/O area. (... same behavior)
 688
 689
 690 ### Command - BREAK (B) Ctrl-Pause(Break)
 691
 692 This command cancels executing command.
 693 The process on the server is not canceled.
 694
 695
 696 ### Command - History Back (P) Ctrl-Up
 697
 698 This command rotates command histories backward.
 699
 700
 701 ### Command - History Next (N) Ctrl-Down
 702
 703 This command rotates command histories forward.
 704
 705
 706 ### Command - Rollback (R)
 707
 708 This command displays confirm dialog and click "OK" to rollback.
 709
 710
 711 ### Command - Commit (M)
 712
 713 This command displays confirm dialog and click "OK" to commit.
 714
 715
 716 ### Command - Connect (C) Ctrl-E
 717
 718 This command shows the list of connectors.
 719 Select connector name you want to connect to, and click "OK" to executes connect command.
 720
 721
 722 ### Command - Disconnect (D) Ctrl-D
 723
 724 This command disconnects current connection.
 725 This is the same as disconnect command.
 726
 727
 728 ### Command - Post-Proccess (0)
 729
 730 This command specifies the configuration of a "Post-Proccess" mode.
 731
 732 The "Post-Proccess" is an action to notify that command finished.
 733 When the window which command is running, is not active, "Post-Proccess" is invoked.
 734
 735 There are following modes:
 736
 737  * None(N): Does nothing.
 738  * Focus(F): Focuses window.
 739  * Shake(S): Shakes window.
 740  * Blink(B): Blinks window.
 741
 742
 743 ### Command - Encryption Key (K)
 744
 745 This command shows the dialog to input an encryption key.
 746
 747
 748 ### Command - Edit Connectors (E)
 749
 750 This command shows the dialog to edit connectors.
 751
 752
 753 ### Data - Sort (S) Alt-S
 754
 755 This command sorts records by selected column.
 756
 757
 758 ### Data - Import File (I)
 759
 760 This command imports from file into the table of current result.
 761
 762
 763 ### Data - Export File (E) Ctrl-Shift-S
 764
 765 This command exports results into file.
 766
 767
 768 ### Help - Show Help
 769
 770 This command shows this help file by default browser.
 771
 772
 773 ### Help - About Stew
 774
 775 This command shows version dialog about Stew.
 776
 777
 778
 779 ## Properties
 780
 781 You can set these system properties into java -D option or stew.properties file.
 782
 783
 784 ### net.argius.stew.properties - Location Of Properties File
 785
 786 Property Value: a file path or a directory path
 787
 788 This property specifies the location of "stew.properties" file.
 789 This properties file is used as system properties and searched in the following steps:
 790
 791 +If it specifies a file path, the file will be used as system properties.
 792 +If it specifies a directory path, the file will be searched a "stew.properties" file in the directory.
 793 +Search a file in the classpath.
 794 +Search a file in the system directory.
 795
 796 The first file found is used.
 797 If a file is not found, ... (ignore it).
 798
 799
 800 ### net.argius.stew.directory - Working Directory
 801
 802 Property Value: a directory path (default: current directory)
 803
 804 This property specifies the current directory as a internal state at the start, but it is not a platform one.
 805
 806
 807 ### net.argius.stew.query.timeout - Query Timeout
 808
 809 Property Value: integer seconds (default: 0)
 810
 811 This property specifies the query timeout which is used in commands.
 812
 813 If it is under 0, the property was not set.
 814
 815 (implementation detail: for java.sql.Statement#setQueryTimeout)
 816
 817
 818 ### net.argius.stew.rowcount.limit - Limit Of Display Result Row Count
 819
 820 Property Value: maximum number of rows (default: Integer.MAX_VALUE, about 2,147,000,000)
 821
 822 This property specifies the maximum number of rows which show in the result set table.
 823 It is not used to output files, such as the export command.
 824
 825
 826 ### net.argius.stew.command.Import.batch.limit - Limit Of Import Command Using Batch
 827
 828 Property Value: limit number of rows (default: 10000)
 829
 830 This property is used by the Import command.
 831 It is not used to output files, such as the export command.
 832
 833
 834 ### net.argius.stew.ui.window.resident - Regident
 835
 836 Property Value: integer minutes
 837
 838 This is an experimental feature.
 839
 840 The app redraws continuously at the specified interval to prevent swap-out.
 841
 842
 843 ### Logger Configurations
 844
 845 Use logging.properties in this package.
 846