Write my pending documentation.

doc/README.isql_enhancements.txt

@@ -1,9 +1,96 @@
-TO DO.
+Isql enhancements in Firebird v2.
+---------------------------------
+
+Author: Claudio Valderrama C. <cvalde at usa.net>
 
 1) Command line switch -b to bail out on error when used in non-interactive mode.
-Also, return an error code to the operating system.
-2) Add SET HEADING ON/OFF option
-3) Add -M2 command-line option to send output of statistics and plans to the same file than the rest of the output
 
-Claudio.
+When using scripts as input in the command line, it may be totally unappropriate
+to let isql continue executing a batch of commands after an error has happened.
+Therefore, the "-b[ail]" option was created. It will stop at the first error it
+can detect. Most cases have been covered, but if you find some error that's not
+recognized by isql, you should inform the project, as this is a feature in progress.
+When isql stops, it means it will no longer execute any command in the input script
+and will return an error code to the operating system. At this time there aren't
+different error codes. A return non-zero return code should be interpreted as failure.
+Depending on other options (like -o, -m and -m2) , isql will show the error message
+on screen or will send it to a file.
+
+Some features:
+
+- Even if isql is executing nested scripts, it will cease all execution and will
+return to the operating system when it detects an error. Nested scripts happen
+when a script A is used as isql input but in turn A contains an INPUT command to
+load script B an so on. Isql doesn't check for direct or indirect recursion, thus
+if the programmer makes a mistake and script A loads itself or loads script B that
+in turn loads script A again, isql will run until it exhaust memory or an error
+is returned from the database, at whose point -bail if activated will stop all
+activity.
+
+- The line number of the failure is not yet known. It has been a private test feature
+for some years but needs more work to be included in the official isql.
+
+- DML errors will be caught when being prepared or executed, depending on the type
+of error.
+
+- DDL errors will be caught when being prepared or executed by default, since isql
+uses AUTODDL ON by default. However, if AUTO DLL is OFF, the server only complains
+when the script does an explicit COMMIT and this may involve several SQL statements.
+
+- The feature can be enabled/disabled interactively or from a script by means of the
+SET BAIL [ON | OFF]
+command. As it's the case with other SET commands, simply using SET BAIL will toggle
+the state between activated and deactivated. Using SET will display the state of
+the switch among many others.
+
+- Even if BAIL is activated, it doesn't mean it will change isql behavior. An
+additional requirement should be met: the session should be non-interactive. A
+non-interactive session happens when the user calls isql in batch mode, giving it
+a script as input. Example:
+isql -b -i my_fb.sql -o results.log -m -m2
+However, if the user loads isql interactively and later executes a script with the
+input command, this is considered an interactive session even though isql knows it's
+executing a script. Example:
+isql
+Use CONNECT or CREATE DATABASE to specify a database
+SQL> set bail;
+SQL> input my_fb.sql;
+SQL> ^Z
+Whatever contents the script has, it will be executed completely even with errors
+and despite the BAIL option was enabled.
+
+
+2) SET HEADING ON/OFF option.
+
+Some people consider useful the idea of doing a SELECT inside isql and have the
+output sent to a file, for additional processing later, specially if the number
+of columns make isql display unpractical. However, isql by default prints column
+headers and in this scenario, they are a nuisance. Therefore, the feature (that was
+previously the fixed default) can be enabled/disabled interactively or from a script
+by means of the
+SET HEADing [ON | OFF]
+command. As it's the case with other SET commands, simply using SET HEAD will toggle
+the state between activated and deactivated. Using SET will display the state of
+the switch among many others.
+Note: this switch cannot be deactivated with a command line parameter.
+
+
+3) Command line switch -m2 to send output of statistics and plans to the same file
+than the rest of the output.
+
+When the user specifies that the output should be sent to a file, two possibilities
+have existed for years: either the command line switch -o followed by a file name
+is used or once inside isql, the command OUTput followed by a file name is used at
+any time, be it an interactive or a batch session. To return the output to the
+console, simply typing OUTput; is enough. So far so good, but error messages
+don't go to that file. They are shown in the console. Then isql developed the -m
+command line switch to melt the error messages with the normal output to whatever
+place the output was being redirected. This left still another case: statistics
+about operations (SET STATs command) and SQL plans as the server returns them
+(SET PLAN and SET PLANONLY commands) are considered diagnostic messages and thus
+were sent always to the console. What the -m2 command line switch does is to
+ensure that such information about stats and plans goes to the same file the output
+has been redirected to.
+Note: neither -m nor -m2 have interactive counterparts through the SET command.
+They only can be specified in the command line switches for isql.
 

doc/sql.extensions/README.ddl.txt

@@ -1,8 +1,79 @@
-TO DO.
+DDL enhancements in Firebird v2.
+--------------------------------
 
-Ability to signal SQL NULL via a NULL pointer.
-Claudio.
+Author: Claudio Valderrama C. <cvalde at usa.net>
+
+Other DDL enhancements may have their own README file.
+
+1) Ability to signal SQL NULL via a NULL pointer.
+(Claudio Valderrama C.)
+
+Previous to Firebird v2, UDF authors only could guess they got a null value,
+but they couldn't be sure, so this let to several problems with UDFs. People
+ended up assuming that a null string would be passed as an empty string, a null
+numeric would be the same than zero and a null date would mean the base date used
+by the engine. Of course, for a numeric value, the author only could assume null
+if the UDF was done for an environments where it's known that value is not possible
+normally. But several UDFs (including ib_udf supplied with FB) assumed an empty
+string most likely would mean a null parameter than a string of length zero. The
+trick may work with CHAR type (the minimal declared CHAR length is one and would
+contain a blank character normally, so a binary zero in the first position would
+signal effectively NULL) but it doesn't work with VARCHAR or CSTRING, where length
+zero is valid. The other solution was to rely on raw descriptors, but this draws
+people to an area with a lot of things to check, more than they would want to tackle.
+The biggest problem is that the engine won't obey the declared type for a parameter;
+it will simply send whatever data it has for that parameter, so the UDF is left to
+decide whether to reject or to try to convert the parameter to the expected data
+type. Since UDFs don't have a formal mechanism to signal errors, the returned value
+will have to be used as an indicator.
+But the basic problem was how to keep the simplicity of the typical declarations
+(no descriptors) while at the same time being able to signal null. The engine
+normally passed UDF parameters by reference and it means in practical terms to
+pass a pointer to the data. By simply passing a null pointer we can tell the UDF
+we have SQL NULL, but since we can't afford to crash an unknown number of different
+public and private UDFs in use that don't expect NULL, we had to enhance the syntax
+to be able to request explicitly NULL handling. Therefore, only UDFs that are able
+to deal with the new scenario can request SQL NULL signaling.
+To avoid adding more keywords, the NULL keyword is appended to the UDF parameter
+type and this is all the required change. Example:
+declare external function sample int null returns int by value...;
+
+If you are already using functions from ib_udf and want to take advantage of
+null signaling (and null recognition) in some functions, you should connect to
+your desired database and run
+upgrade/v2/ib_udf_upgrade.sql
+and commit afterwards, preferable when no more users are connected to the database.
+The code in the listed functions in that script has been modified to recognize
+null only when NULL is signaled by the engine. Therefore, starting with FB v2,
+rtrim and ltrim no longer assume that an empty string means a NULL string. If you
+don't upgrade, the functions won't crash. They simply won't be able to detect NULL.
+If you never have used ib_udf and want to do that, you should connect to your desired
+database, run
+udf/ib_udf2.sql
+and commit afterwards, preferable when no more users are connected to the database.
+Note the "2" at the end of the name. The original script for FB v1.5 is still
+available in the same directory.
+The directories upgrade" and "udf" are inside the home directory of your FB v2
+installation.
+
+
+2) Implemented REVOKE ADMIN OPTION FROM user
+(Dmitry Yemanov.)
+
+SYSDBA, the database creator or the owner of an object can grant rights on that
+object to other users. However, those rights can be made inheritable, too. By using
+WITH GRANT OPTION, the grantor gives the grantee the right to become a grantor of
+the same rights in turn. This ability can be removed by the original grantor with
+REVOKE GRANT OPTION FROM user.
+
+However, there's a second form that involves roles. Instead of specifying the
+same rights for many users (soon it becomes a maintenance nightmare) you can
+create a role, assign rights to that role and then grant it to a group of users.
+By simply changing the role's rights you affect all those users. By using
+WITH ADMIN OPTION, the grantor (typically the role creator) gives the grantee the
+right to become a grantor of the same role in turn. Until FB v2, this ability
+couldn't be removed unless the original grantor fiddles with system tables directly.
+Now, the ability to grant the role can be removed by the original grantor with
+REVOKE ADMIN OPTION FROM user.
 
-Implemented REVOKE ADMIN OPTION FROM statement
-Dmitry.