class %SQL.Shell extends %Library.RegisteredObject%SQL.Shell - Interactive SQL shell
The interactive SQL shell allows the user to execute SQL statements dynamically. There are two execution modes - immediate and deferred. The execution mode can be set by executing a set executemode command with immediate or deferred as the executemode value. If the execution mode is immediate then SQL statements are prepared and executed immediately. If execute mode is deferred then a statement is only prepared and not executed until either a # or go command is entered. The result of executing the statement is displayed on the current device after the statement is executed.
If displaymode is currentdevice and messages is on then the time taken to prepare the current statement and the time taken to execute the current statement are displayed after the result is displayed. Execute time includes the time to instantiate the result object and the time to display the statement.
SQL statements can span multiple lines. To enter a multiline statement, simply press the enter key to enter multiline mode. When the statement is complete enter go to exit multiline mode. If execution mode is immediate the multiline statement will be executed at that point, otherwise and additional # or go will cause the statement to execute.
The user is prompted to supply a value for each parameter defined in the statement each time the statement is executed. If the value entered begins with a colon then the user is prompted to enter if the value is a literal or not. If the value is a literal the user must answer with Y or y. The default is N and if that is the desired response simply press Enter and the value entered is assumed to be a ObjectScript expression or host variable. Host variables are assumed to be public variables. Public variables can be set using the ! set var = value command. Other expressions can be entered, including function calls and class methods that return a value. The statement can be executed again by entering 'go' resulting in prompts for new statement values. The expression used to execute the statement is displayed just prior to executing the statement. If the statement does not contain any parameters then execution will proceed without any prompting.
The Shell supports statement recall. Any statement that is prepared may be recalled from the statement buffer by entering #nbr where nbr is the statement number in the buffer. Just entering # will list the statements currently in the buffer. Entering #clear will clear the statement buffer on confirmation. Entering #0 will recall the most recently prepared statement from the buffer. If executemode is set to immediate then the recalled statement will also be executed.
Statements can also be saved in a statement pool. To save the current statement enter save name. That statement is saved in the pool and can be later recalled by entering open name.
Statements can be deleted from the statement pool by entering clear name. If no name is specified then all statements are removed from the pool on confirmation.
Shell commands are entered in the first column and do not often conflict with executable statements. In some cases, such as set, a command and an SQL statement
can be ambiguous. This occurs most often in complex statements such as CREATE PROCEDURE. To eliminate confusion, the SQL Shell supports a command prefix
that can be set to any value. The command prefix allows the user to specify that all commands begin with a special character or character sequence. To set the command prefix
simply set commandprefix option using the set command:
USER>>set commandprefix = .
Once the command prefix is set, all commands must be prefixed by the value of the commandprefix setting. There are three exceptions - ?, # and GO do not have to be prefixed.
The commandprefix option is saved by the set save command and, if saved, will be restored automatically the next time the user starts the shell. By default there is no
commandprefix. To reset the command prefix back to the default once it has been set to something else, enter:
USER>>set commandprefix = ""
Shell context settings are set by the set command. Context settings can be retained and used by future instances of the shell by entering set save and cleared by entering set clear. Entering set without any additional qualifiers will display the current shell context settings.
To execute an SQL statement, type it in and press ENTER.
To execute a multiline SQL statement, press ENTER to enter multiline mode, type in the statement, and enter go.
|Press ENTER||Enter multiline statement mode. While in multiline
statement mode, some basic commands are supported.
|SQL Statement||Prepare the statement. If EXECUTEMODE is immediate then execute the statement. The result is displayed after execution.|
|#||List statements currently in the history buffer.|
|#nbr||Recall statement nbr from the statement history buffer. If nbr is zero then recall the most recent statement. Recalled statements are executed if EXECUTEMODE is set to 'immediate'. If EXECUTEMODE is set to 'deferred' then it is necessary to enter GO to execute the recalled statement.|
|#?||List statements currently in the history buffer.|
|#clear||Clear the statement history buffer.|
|c[lear] name||Clear (delete) the statement identified by name from the statement pool.|
|! objectscript_command||Execute objectscript_command.|
|g[o]||Run the most recently executed or loaded statement.|
|l[ist]||List statements in the statement pool.|
|load filename||Load a statement from filename.|
|m[etadata]||Displays the metadata for the current statement.|
|obj[ectscript] objectscript_command||Execute objectscript_command.|
|o[pen] name||Open the statement name name from the statement pool. The retrieved statement is prepared and executed (depending on the EXECUTEMODE setting).|
|Exit the shell.|
|run [filename]||Run an SQL script. If |
|saveglobal|sg name||Save the currently prepared statement in the statement global using the given name.|
|s[ave] filename||Save the currently prepared statement to filename.|
|set||Display the current context settings.|
|set clear||Clear the saved Shell settings for this user.|
|set colalign [=] delim[iter] | header | data||
Set column alignment for the SQL Resultset. The context setting colalign can be set to one of the following values:
|set commandprefix [=] string value||Sets the command prefix to string value. To set the command prefix to nothing, enter "" as the string value.|
|set dialect [=] sybase | mssql | IRIS||Sets the dialect to the desired SQL dialect. If schemalist is empty then IRIS SQL is assumed. The dialect setting determines which dialect mode is used when preparing a statement.|
|set displayfile [=] file||Set the name of the file to be used for displaying the results of executing SQL statements. If no file name is specified then a random file name will be generated for each statement execution. Additionally, a messages file may be produced. The name of the file containing messages is either the file concatenated with "Messages" or it is a random file name if file is set to nothing. To set the file setting to nothing after it was previously set, enter "".|
|set displaymode [=] displaymode||Set the DISPLAYMODE. If displaymode is not specified, the current DISPLAYMODE setting is displayed on the current device. displaymode values can be cur[rentdevice],xml,html,pdf, or txt. When DISPLAYMODE is set to CURRENTDEVICE, statement results are displayed on the current device. When XML, HTML, PDF or TXT are specified then statement results are written to a temporary file using a ZEN Report that is generated from the statement metadata.|
|set displaypath [=] path||Set the path where files used to save statement results will be placed.|
|set displaytranslate[table] [=] translatetable||Set the translate table used for displayfile when writing output in 'csv' and 'txt' formats. For example, "UTF8". Values are case sensitive.|
|set executemode [=] executemode||Set EXECUTEMODE to executemode. Valid values are immediate and deferred. If immediate then SQL statements are executed immediately. If deferred then the current statement is executed by entering a 'go' command. If executemode is not specified then the current EXECUTEMODE setting is displayed.|
|set log [=] on | off | file||Turn logging on or off. If a file is specified, logging is turned on and the log is written to the file specified. The default file for logging is used if logging is simply turned 'on'.|
|set messages [=] on | off||Turn messages on or off. If messages is off then results are displayed without any additional information. Times are not displayed.|
|set path [=] schemalist||Sets the current schema search path. If schemalist is empty then the current path is displayed. To set PATH to the default schema then specify schemalist as """".|
|set save||Save the current Shell settings for this user. The settings are restored when the current user starts another Shell session.|
|set selectmode [=] selectmode||Sets the current SELECTMODE to odbc, logical, or display. If selectmode is NULL the current setting is displayed.|
|show [pl[an]] [v[erbose]]||
Show the execution plan for the current statement.
If the verbose qualifier is used, show all the module details for the current statement's execution plan; Otherwise, display only the top-level module details by default.
|show planalt [v[erbose]]||
Run the ShowPlanAlt() method on the the current statement which allows user to browse alternate execution plans.
If the verbose qualifier is used, show all the module details for the current statement's execution plan and all alternate plans; Otherwise, display only the top-level module details by default.
|show st[atement]||Show the current statement text and other details such as the implementation class.|
ColAlign represents the column alignment for the SQL Resultset, and can be set to one of the following values:
- delim[iter] - The SQL Resultset header/data columns will be aligned based on the standard delimiter (tab). [Default]
- header - The SQL Resultset header/data columns will be aligned based on the length of the column header and the standard delimiter (tab).
- data - The SQL Resultset header/data columns will be aligned based on the precision/length of the column data property and the standard delimiter (tab).
USER>>set colalign [=] delim[iter] USER>>set colalign [=] header USER>>set colalign [=] data
CommandPrefix is the string value used to indicate that a command is being entered. The default value is null, meaning that no command prefix is in use. If CommandPrefix is set to a non-empty value then that prefix must be entered as a prefix to most commands. There are three commands that do not require a prefix: ?, # and GO.
USER>>set commandprefix = / USER>>/set save USER>>/quit