================================== WINDOWS NT DOCUMENTATION NOTES FOR RELEASE 7.23.TC1 JULY 1, 1997 ================================== These Documentation Notes describe feature and performance topics not covered in the manuals or modified since publication. Please examine this file. It contains vital information about application and performance issues. This file includes information for the following manuals: DB-Access User Manual Getting Started with Informix Database Server Products Informix Backup and Restore Guide Informix Error Messages Informix Guide to Enterprise Replication Informix Guide to GLS Functionality Informix Guide to SQL: Reference Informix Guide to SQL: Syntax Informix Guide to SQL: Tutorial Informix Migration Guide Informix SNMP Subagent Guide INFORMIX-OnLine Dynamic Server Administrator's Guide INFORMIX-OnLine Dynamic Server Guide to Feature Enhancements INFORMIX-OnLine Dynamic Server Trusted Facility Manual Managing Relational Objects Using the INFORMIX-Command Center ============================================================ DB-Access User Manual ============================================================ IFX_AUTOFREE and OPTOFC Environment Variables The IFX_AUTOFREE and OPTOFC environment variables are not supported by Informix utilities such as DB-Access. These environment variables should be used only with INFORMIX-ESQL/C client applications. For more information, see the Documentation Notes for the INFORMIX-ESQL/C Programmer's Manual. Do not set the IFX_AUTOFREE environment variable to 1 (to enable AUTOFREE) when you use DB-Access. ============================================================ Getting Started with Informix Database Server Products ============================================================ No new information is available at this time. ============================================================ Informix Backup and Restore Guide ============================================================ Table of Contents A. The Storage Manager B. Hostname in the INFORMIXSQLHOSTS File C. The bar_version Table D. Setting ON-Bar Configuration Parameters E. Resolving Problems with XBSA and ON-Bar F. Restoring the Whole System G. BAR_MAX_BACKUP Configuration Parameter A. The Storage Manager (page 1-5) The onbar utility communicates with both OnLine Dynamic Server and a storage manager. For a backup, ON-Bar requests the contents of dbspaces and blobspaces, and logical-log files from OnLine Dynamic Server and passes them to the storage manager. For a restore, the process is reversed. The ON-Bar utility requests the contents of dbspaces, blobspaces, and logical-log files from the storage manager and passes them to OnLine Dynamic Server. B. Hostname in the INFORMIXSQLHOSTS File The hostname in your $INFORMIXSQLHOSTS file must contain 18 or fewer characters. C. The bar_version Table (page 4-5) For each storage manager, there should be a row in this format: 1||| where is the release version of the storage manager's XBSA shared library, is the name of the storage manager, and is the storage manager version. The data in this file is inserted into the bar_version table in the sysutils database. You can use DB-Access to update the bar_version table. D. Setting ON-Bar Configuration Parameters In "Setting ON-Bar Configuration Parameters" on pages 3-3 to 3-5, BAR_XFER_BUFSIZE should be spelled as BAR_XFER_BUF_SIZE and BAR_XPORT_COUNT should be spelled as BAR_NB_XPORT_COUNT. E. Resolving Problems with XBSA and ON-Bar One common error that occurs after installing a storage manager to work with ON-Bar is that the first backup attempts give the message: ERROR: Version of XBSA shared library not compatible with version 1 of ONBAR This continues until the configuration problem gets resolved. The error is a result of the bar_version table in the sysutils database not matching the output of the BSAQueryApiVersion() function call. In the first drafts of the XBSA specification, no real meaning was assigned to the version number returned by this function call. The value was left to the discretion of the storage management vendor. All that ON-Bar requires is that the version number returned from BSAQueryApiVersion exists in a row in the bar_version table. The storage manager needs to insert a row into the bar_versions table. Consult the documentation that comes with the storage manager's XBSA implementation for more information. F. Restoring the Whole System (page 2-11) To restore the whole system, use the -r and -w options as shown in the following example: onbar -r -w NOTE: If you use onbar -b to back up your system, you must use onbar -r to restore both the physical and logical logs. However, if you use onbar -b -w to back up the whole system, you can use onbar -r -p -w to restore the physical logs only. G. BAR_MAX_BACKUP Configuration Parameter (page 3-5) Correction to the third paragraph in the section, "BAR_MAX_BACKUP:" Use the BAR_MAX_BACKUP parameter to limit the computer resources that onbar uses. If you do not set BAR_MAX_BACKUP or set it to 0, the number of onbar processes is limited by the number of dbobjects or the amount of memory available to the database server, whichever is less. On Windows NT, BAR_MAX_BACKUP should always be set to 1 because parallelism is not currently supported. ============================================================ Informix Error Messages ============================================================ No new information is available at this time ============================================================ Informix Guide to Enterprise Replication ============================================================ Table of Contents A. Error Message Files B. Machines notes C. Multiple instances of OnLine D. Installing Enterprise Replication E. Synchronizing Host Time F. Configuring Enterprise Replication G. Configuring the Database Server for Use with Enterprise Replication A. Error Message Files Informix software products provide ASCII files that contain all of the Informix error messages and their corrective actions. To read the error messages in the ASCII file, Informix provides the Find Error option in the INFORMIX-Command Center. On Windows NT, the error messages file is in help file format (errmess.hlp). The finderr icon is in the Informix Administration Tools program manager group. B. Machine Notes Machines notes are NOT included. Refer to documentation and release notes for feature and performance topics. C. Multiple Instances of OnLine Multiple instances of OnLine Dynamic Server are not supported on Windows NT. D. Installing Enterprise Replication Reference the Installation Manual and Release Notes for installation information. E. Synchronizing Host Time Enterprise Replication requires that all NT workstations participating in replication be time synchronized. For recommended utilities and information, reference the Microsoft Knowledge Base, Article ID: Q131715 (www.microsoft.com/kb/articles/q131/7/15.htm). F. Configuring Enterprise Replication Reference the Release Notes for configuration information. G. Configuring the Database Server for Use with Enterprise Replication The following information should only be used if your environment contains 7.22 and pre-7.22 INFORMIX-OnLine. Configuring the Database Server for Enterprise Replication ========================================================== The current version of the setup program in 7.23 OnLine Dynamic Server for Windows NT installs the product and configures it so that it is ready to use without enabling Enterprise Replication. To enable Enterprise Replication, you must make manual changes to the database server configuration. Two components define the OnLine Dynamic Server configuration: the ONCONFIG file and the SQLHOSTS registry. Both of these components need to be changed to enable Enterprise Replication. The following section describes the changes required to the ONCONFIG file and the SQLHOSTS registry. Changing SQLHOSTS and ONCONFIG for Enterprise Replication ========================================================= Perform these steps immediately after the installation. If OnLine Dynamic Server was started by the setup program, you need to bring down the database server before you perform the following steps. The following text describes each of these steps in detail. 1. Define one or more dbserveraliases to use Enterprise Replication. 2. Define a group name for Enterprise Replication to use. 3. Bring up OnLine Dynamic Server. 4. Start the Replication Manager 5. Declare database servers to Enterprise Replication. 6. Define the replication system. 7. Start Enterprise Replication Steps 1 and 2 are OnLine Dynamic Server configuration-related items, which these Documentation Notes describe. Steps 4 through 7 relate to Enterprise Replication configuration and are documented in the Informix Guide to Enterprise Replication. Perform Steps 1 and 2 for each OnLine Dynamic Server database server installation so that each database server can participate in Enterprise Replication. If you re-install OnLine Dynamic Server from the media, you need to perform these steps again. Defining DBSERVERALIAS ====================== Follow these steps to create and define the DBSERVERALIAS in the ONCONFIG file. The steps are fully described in the following sections. 1. Edit the ONCONFIG file and add the DBSERVERALIAS. 2. Edit the SQLHOSTS registry to add the new DBSERVERALIAS. 3. Edit the NT Services file. Step 1. Edit the ONCONFIG File Edit the ONCONFIG file and add an entry for DBSERVERALIAS following the DBSERVERNAME entry, as follows: DBSERVERALIASES , ,... This line in the ONCONFIG file provides alternative database server names that clients can use to connect to the same database server. You use the alternative database server names only to connect to Enterprise Replication database servers. Although 7.23 clients can use the alternative server names to connect to database servers, you might have some pre-7.22 clients that might not be able to use alternative server names. Informix advises that you use the DBSERVERNAME entry only to connect to OnLine Dynamic Server. For more information regarding backward compatibility of OnLine Dynamic Server, see the question and answer section at the end of these documentation notes. Important: You must use one alternative database server name in the DBSERVER-ALIASES line. Because alternative database server names are designated for Enterprise Replication use, Informix recommends that you use Enterprise Replication in the prefix of your DBSERVERNAME value. Step 2. Edit the SQLHOSTS Registry Create an entry in the SQLHOSTS registry for each alternative database server name listed in the DBSERVERALIASES line of the ONCONFIG file (usually you have only one). Then determine the value of the INFORMIXSQLHOSTS environment variable to determine the name of the computer on which the SQLHOSTS registry resides. For the example, call this computer Cherry. To connect to the registry of computer Cherry: 1. Run the regedt32 tool 2. Choose Registry->Select Computer to select the computer Cherry. If Cherry is the same computer as the OnLine Dynamic Server database server computer, then you do not need to connect because, by default, you are connected to your own computer in regedt32. 3. From Cherry, choose the following item: HKEY_LOCAL_MACHINE->SOFTWARE->Informix->SQLHOSTS To add a subkey for the alternative server name: 1. Choose Edit->Add Key. Type an alternative DBSERVERNAME value in the Key Name field, such as REPDBSERVE. Click OK. 2. Choose Edit->Add Value. Type the value 'HOST' in the value name field. Click OK. Type the computer name Cherry in the string field of the dialog box. Cherry is the name of the computer on which OnLine Dynamic Server was installed. This name should be the TCP/IP name of the computer, which is usually the same as the Windows NT computer name. If the Windows NT computer name and TCP/IP names are not the same, use the TCP/IP name. 3. Choose Edit->Add Value. Type the value OPTIONS in the value name field. Click OK. Type g=group-name in the string field of the dialog box. Group name is a new group name that you will create. The suggested naming convention is IER_GROUP_COMPUTER. For example, you can name a group IER_GROUP_cherry. You can use any group name as long is it is unique and does not conflict with any existing DBSERVERNAME keys in the SQLHOSTS registry. The maximum length allowed for the group name is 18 characters. If you have more than one alternative database server name listed in DBSERVERALIASES, use the same group name in the OPTIONS field. Note the group name that you used in this step. You will need this group name again when you define and register the group name in the SQLHOSTS registry, which is explained in "Define GROUP NAME." 4. Choose Edit->Add Value. Type the value 'PROTOCOL' in the value name field. Click OK. Type olsoctcp in the string field of the dialog box. (Currently OnLine Dynamic Server supports only socket protocol.) 5. Choose Edit->Add Value. Type the value 'SERVICE' in the value name field. Click OK. Type the unique service name. By default, the setup program sets up the primary DBSERVERNAME entry to use turbo as the service name. For the first alias, you can use turbo1, for the second you can use turbo2, and so on. For example, IER_ol_cherry is the name of the DBSERVERALIAS. The values are as follows: HOST:REG_SZ:cherry OPTIONS:REG_SZ:g=IER_GROUP1 PROTOCL:REG_SZ:olsoctcp SERVICE:REG_SZ:turbo2 Step 3. Edit the NT Services File For each service name that you used in the previous step (turbo1, turbo2, and so on), you need to add that service name to the Windows NT Services file. The Services file is located in the Windows NT systems directory. You must perform the following steps in a DOS window. To add a service name to the Services file: 1. Change directories to %WINDIR%\system32\drivers\etc. 2. Use your favorite editor to open the services file. 3. At the end of the file add a line(s) with service name, port number, and optional comment field. Example turbo2 31528/tcp #For Informix ODS use turbo3 31529/tcp #For Informix ODS use The port number should be unique. Make sure the port numbers that you use (315, and so on) are not already being used by some other service name. Defining a Group Name ===================== A GROUP NAME entry needs to be created in the SQLHOSTS registry. A group name defines an abstract database server name to which clients can connect. Internally, the connection is made to any one of the members of a group. For Enterprise Replication, the members of a group are lists of DBSERVERNAME and/or DBSERVERALIAS values defined in the ONCONFIG file. In version 7.22 and more recent versions, you can connect to a database server name or to a group. Enterprise Replication uses the group name rather than a DBSERVERNAME value to connect to a database server. Each instance of OnLine Dynamic Server has its own group name. Each instance of OnLine Dynamic Server defines one or more DBSERVERALIAS values that belong to the group name created for that instance. The DBSERVERALIAS values that belong to a group are called members of the group. This section explains how to create a group and how to add members to it in the SQLHOSTS registry. To create a group entry: 1. Look up the value of the INFORMIXSQLHOSTS environment variable to determine the name of the computer on which the SQLHOSTS registry resides. For this example, call this computer Cherry. 2. Run the regedt32 tool and connect to the registry of computer Cherry. 3. Choose Registry->Select Computer and select Cherry. If computer Cherry is the same as the OnLine Dynamic Server database server computer, you do not need to connect because, by default, you are already connected to your own computer in regedt32. 4. From Cherry, choose the following item: HKEY_LOCAL_MACHINE->SOFTWARE->Informix->SQLHOSTS. Next, add a subkey for the group name, in which the group name is the name that you chose when you defined OPTIONS as g=groupname. To add the values to this recently created subkey: 1. Choose Edit->Add Value. Type the value 'HOST' in the value name field. Click OK. Type a "-" (dash) in the string field of the dialog box. 2. Choose Edit->Add Value. Type the value and fill in 'OPTIONS' in the value name field. Click OK. Type i=group-id in the string field of the dialog box. The group-id is a decimal number that is globally unique across all IER database servers and that is not used in any other GROUP definition in the SQLHOSTS registry. For example, 1234 is the group-id. 3. Choose Edit->Add Value. Type the value 'PROTOCOL' in the value name field. Click OK. Type 'group' in the string field of the dialog box. Use only lowercase letters when you enter the letters of the word group. 4. Choose Edit->Add Value. Type the value 'SERVICE' in the value name field. Click OK. 5. Type a "-" (dash) in the string field of the dialog box. Under the GROUP subkey that you just created, add a subkey for each of the alternative server names that you created when you edited the ONCONFIG file. To add a subkey: 1. Choose Edit->Add Key. Type the alternative dbservername value in the key name field (for our example, IER_ol_cherry.). Click OK. 2. Choose Add Key... to add each alternative server name. Do not add the original DBSERVERNAME entry to the group; only the aliases need to be members of the group. From our previous example, IER_ol_cherry is a member of IER_GROUP1. The IER_GROUP1 subkey values are as follows: HOST:REG_SZ:- OPTIONS:REG_SZ:i=1234 PROTOCL:REG_SZ:group SERVICE:REG_SZ:- Questions and Answers ===================== The following questions and answers are related to backward compatibility (pre-7.22 clients and pre-7.22 database server). Question. My client application (for example, ROM, SQLEDITOR) displays database server names that contain the word GROUP. Can I connect to that? Answer. The current version of ROM and SQLEDITOR do not support connecting to GROUP, so you cannot connect to that group. Similarly, if any other client application (for example, an ESQL/C application) tries to connect to a database server name that has the word GROUP in it, that application will fail. Question. My client application (for example, ROM, SQLEDITOR) displays server names that contain the word IER. Can I connect to that? Answer. Yes. All Windows NT clients should be able to connect to it. But all UNIX clients prior to Version 7.22 will fail. Question. In my client application I generally connect to an existing 7.1/7.12/7.20 OnLine Dynamic Server. From there can I initiate a distributed query to 7.22 OnLine Dynamic Server? Answer. Yes. You can do that as long as you are using a regular database server name of a 7.22 (or more recent) OnLine Dynamic Server in your query and not the DBSERVERNAME alias that you set up for Enterprise Replication. ============================================================ Informix Guide to GLS Functionality ============================================================ No new information is available at this time. ============================================================ Informix Guide to SQL: Reference ============================================================ Table of Contents A. New OPTOFC Environment Variable B. New OPTMSG Environment Variable C. New IFX_AUTOFREE Environment Variable A. New OPTOFC Environment Variable The OPTOFC environment variable is introduced in this release. You can use the OPTOFC environment variable to enable or disable the OPTOFC (Optimized Open Fetch Close) feature. This feature is available for ESQL/C applications only. Setting the OPTOFC Environment Variable ======================================= You can set the OPTOFC environment variable to the following values: 1 enables the OPTOFC feature. When you specify this value, you enable the OPTOFC feature for every cursor in every thread of the application. 0 disables the OPTOFC feature. By default, the OPTOFC feature is not enabled. Purpose of OPTOFC Environment Variable ====================================== The OPTOFC feature minimizes the number of round-trip messages between an ESQL/C application and the database server. The OPTOFC feature performs this optimization by sending the OPEN message with the FETCH message to the database server. In addition, the database server automatically closes the cursor at the end of the last FETCH, so no CLOSE message needs to be sent to the database server when the application requests that the cursor be closed. The end result of these optimizations is that three round-trip messages are reduced to one. The performance of queries is improved because the overhead of opening and closing the cursor is reduced. Example of OPTOFC Environment Variable ====================================== In the following example, the user enables the OPTOFC feature for every cursor in every thread of the application: setenv OPTOFC 1 Informix Utilities ================== The IFX_AUTOFREE and OPTOFC environment variables are not supported by Informix utilities. These environment variables should be used only with INFORMIX-ESQL/C client applications. Behavior of Static and Dynamic Cursors with OPTOFC ================================================== Static cursors behave differently depending on whether the OPTOFC feature is enabled or disabled. Dynamic cursors behave the same regardless of whether the OPTOFC feature is enabled or disabled. The following analysis explains these points. When OPTOFC is Disabled ----------------------- When the OPTOFC feature is disabled, a static cursor is freed implicitly by the close. When the server closes a statically declared cursor, the client sends a message to the server to actually close and free memory associated with the cursor on server and also frees the memory associated with the cursor. When the server closes a dynamic cursor, the dynamic cursor is not freed by the close. The dynamic cursor must be freed explicitly. When OPTOFC is Enabled ---------------------- When the OPTOFC feature is enabled, a static cursor is NOT freed by the close. The close message is not actually sent to the server because the OPTOFC feature is in effect, so the static cursor is not freed implicitly. When the server closes a dynamic cursor, the dynamic cursor is not freed by the close. The dynamic cursor must be freed explicitly. This behavior is the same as when OPTOFC is not enabled. Neither a static nor a dynamic cursor is freed upon close when the OPTOFC feature is enabled. A subsequent OPEN/FETCH of the same cursor actually opens the same cursor on the server, but now the server notices that the table has been modified and issues error -710 (Table has been dropped, altered, or renamed.) For further information on using the OPTOFC feature, see the Documentation Notes for the INFORMIX-ESQL/C Programmer's Manual. B. New OPTMSG Environment Variable The OPTMSG environment variable is introduced in this release. The OPTMSG environment variable enables or disables the OPTMSG (Optimized Messages) feature. This feature is available for ESQL/C applications only. You can set the OPTMSG environment variable to the following values: 1 enables the OPTMSG feature. When both the ESQL/C global variable OptMsg and the OPTMSG environment variable are set to 1, a group of SQL statements is sent to the database server in a single message packet. 0 disables the OPTMSG feature. By default, the OPTMSG feature is not enabled. The OPTMSG feature reduces the number of small message packets between the client application and the database server by chaining or piggybacking the messages for two or more successive SQL statements in a single message packet. Many SQL statements are considered likely to succeed in a correct application, so the confirmation responses from the database server can be chained in a single reply. The OPTMSG feature can be used for any SQL statements that can be chained together. By reducing network traffic, this feature can improve performance greatly, and it does not require any memory allocation. Set the global variable OptMsg to 0 explicitly to avoid chaining of statements that require immediate replies or for debugging purposes. Even if this global variable is set to 1 before statements like FETCH, DESCRIBE, and PREPARE, it is ignored. Examples of statements that cannot be chained include FETCH, PREPARE, COMMIT, implicit ROLLBACK, FLUSH, EXECUTE, PUT, and singleton SELECT. After you set the OPTMSG environment variable to 1, you still need to assign a value of 1 to the global variable OptMsg before each SQL statement that is to be chained. To avoid unintended chaining, you should reset OptMsg to 0 immediately after the statement. In the following example, assume the OPTMSG environment variable has been set to 1. OptMsg=1; /*Enable the OPTMSG feature for this statement: chain this statement to the next SQL statement*/ EXEC SQL set isolation to committed read; OptMsg=0; /*Disable the OPTMSG feature.*/ EXEC SQL insert into table1 values(2); EXEC SQL update table1 set col1=5 where col1=2; In this example, the application delays sending the SET ISOLATION statement to the database server until the INSERT statement is sent. However, the INSERT statement is not chained to the following UPDATE statement. So the application sends the messages for SET ISOLATION and INSERT in one packet to the database server as soon as the INSERT statement is executed. For further information on using the OPTMSG feature, see the documentation notes for the INFORMIX-ESQL/C Programmer's Manual. C. New IFX_AUTOFREE Environment Variable You can enable the AUTOFREE feature by setting the new environment variable IFX_AUTOFREE. When this feature is enabled, the memory allocated for cursors is automatically freed right after the close of the cursors. You should set the IFX_AUTOFREE environment variable before the application starts. The following list shows the values that you can assign to the IFX_AUTOFREE environment variable. 1 This value enables the AUTOFREE feature. When you specify this value, you enable the AUTOFREE feature for every cursor in every thread of the application. However, in each thread of the application, the SET AUTOFREE statement overrides the setting of the IFX_AUTOFREE environment variable. 0 This option disables the AUTOFREE feature. If you set the IFX_AUTOFREE environment variable to ANY value (including no value) other than 0 or 1, the AUTOFREE feature is not enabled. The IFX_AUTOFREE and OPTOFC environment variables are not supported by Informix utilities. These environment variables should be used only with INFORMIX-ESQL/C client applications. NOTE: Support for the IFX_AUTOFREE environment variable might be dropped in a future release. Users should use the AUTOFREE feature by explicitly using the SET AUTOFREE statement within their applications. ============================================================ Informix Guide to SQL: Syntax ============================================================ Table of Contents A. DEFINE Changes B. AUTOFREE Feature C. Deferred Prepare Feature A. DEFINE Changes DEFINE variable LIKE is allowed. For example: create procedure proc1() define local_var like ; return; end procedure; The variable is treated as an integer variable. DEFINE variable serial is NOT allowed. For example: create procedure proc2() define local_var serial; return; end procedure; This example produces the following error: 670: Variable(local_var) declared as SERIAL type. B. AUTOFREE Feature The new SET AUTOFREE statement enables the Autofree feature for cursors in INFORMIX-ESQL/C programs. When you enter a SET AUTOFREE statement in the program, the database server automatically frees memory allocated for the specified cursor as soon as it closes the cursor. Therefore, you do not need to enter a FREE statement to free the server's cursor memory explicitly once it is closed. If you enter a FREE statement after the CLOSE statement, the FREE statement has no effect. By enabling the Autofree feature, you save a network round-trip. When the Autofree feature is enabled, the program does not send messages to the database server instructing it to free the cursor memory. Example ------- Suppose you enable the AUTOFREE feature for the following cursor: /*Cursor associated with a SELECT statement */ EXEC SQL declare sel_curs cursor for select * from customer; When the database server closes the sel_curs cursor, it automatically performs the equivalent of the following FREE statement: FREE sel_curs ATTACHED AND DETACHED STATEMENTS ================================ When a cursor is automatically freed, its associated prepared statement (or associated statement for short) is also freed. You cannot use this statement to declare any new cursor thereafter. The term "associated statement" has a special meaning in the context of the Autofree feature. A cursor is associated with a prepared statement if it is the first cursor that you declare using the prepared statement, or if it is the first cursor that you declare using the statement after the statement is detached. The term "detached statement" has a special meaning in the context of the Autofree feature. A prepared statement is detached if you do not declare a cursor using the statement, or if the cursor with which the statement is associated has been freed. Example ------- Suppose you enable the Autofree feature for the following cursor: /*Cursor associated with a prepared statement */ EXEC SQL prepare sel_stmt 'select * from customer'; EXEC SQL declare sel_curs2 cursor for sel_stmt; When the database server closes the sel_curs2 cursor, it automatically performs the equivalent of the following FREE statements: FREE sel_curs2; FREE sel_stmt SYNTAX OF THE SET AUTOFREE STATEMENT ==================================== The SET AUTOFREE statement is valid in ESQL/C only. This statement is an Informix extension to the ANSI SQL standard. The syntax of the SET AUTOFREE statement is as follows. ::= | ::= SET AUTOFREE [ ENABLED | DISABLED ] ::= SET AUTOFREE [ ENABLED | DISABLED ] FOR { | } The following list explains the input parameters in the syntax diagram. The name of a cursor for which the Autofree feature is enabled or disabled A host variable that holds the value of As the syntax diagram shows, you can specify global-autofree mode or cursor-autofree mode with the SET AUTOFREE statement. These modes are explained below. Global-Autofree Mode -------------------- In global-autofree mode, the SET AUTOFREE statement affects all subsequent cursors in the program. When you specify the ENABLED option, the Autofree feature is enabled for all the cursors that are opened later in the program. The following example shows how to use the ENABLED option to automatically free memory for all subsequent cursors: EXEC SQL set autofree enabled; When you specify the DISABLED option, the Autofree feature is disabled for all the cursors that are opened later in the program. However, the SET AUTOFREE DISABLED statement does not disable the Autofree feature for an autofree-enabled cursor after that cursor is opened. The following example shows how to use the DISABLED option to disable the Autofree feature for all subsequent cursors: EXEC SQL set autofree disabled; If you do not specify the ENABLED or DISABLED option in global-autofree mode, the default is ENABLED. The following example specifies that memory is automatically freed for all subsequent cursors: EXEC SQL set autofree; Cursor-Autofree Mode -------------------- In cursor-autofree mode, the SET AUTOFREE statement affects only the cursor that you specify after the FOR keyword. If you specify the ENABLED option, the cursor is autofree-enabled. The following example shows how to enable the Autofree feature for the specific cursor named x1: EXEC SQL set autofree enabled for x1; If you specify the DISABLED option, the cursor is autofree-disabled. The following example shows how to disable the Autofree feature for the specific cursor named x1: EXEC SQL set autofree disabled for x1; If you do not specify the ENABLED or DISABLED option in cursor-autofree mode, the cursor is autofree-enabled by default. The following example enables the Autofree feature for the cursor named x1: EXEC SQL set autofree for x1; One advantage of cursor-autofree mode is that you can use it to override a global setting for all cursors. For example, if you issue a SET AUTOFREE ENABLED statement to enable the Autofree feature for all cursors in a program, you can issue a subsequent SET AUTOFREE DISABLED FOR statement to disable the Autofree feature for a particular cursor. In the following example, the first statement enables the Autofree feature for all cursors, while the second statement disables the Autofree feature for the cursor named x1: EXEC SQL set autofree enabled; EXEC SQL set autofree disabled for x1; USING THE IFX_AUTOFREE ENVIRONMENT VARIABLE =========================================== You can also enable the Autofree feature by setting the new environment variable IFX_AUTOFREE. You should set the IFX_AUTOFREE environment variable before the application starts. The following list shows the values that you can assign to the IFX_AUTOFREE environment variable. 1 This value enables the Autofree feature. When you specify this value, you enable the Autofree feature for every cursor in every thread of the application. However, in each thread of the application, the SET AUTOFREE statement overrides the setting of the IFX_AUTOFREE environment variable. 0 This option disables the Autofree feature. If you set the IFX_AUTOFREE environment variable to ANY value (including no value) other than 0 or 1, the Autofree feature is not enabled. The IFX_AUTOFREE and OPTOFC environment variables are not supported by Informix utilities. These environment variables should be used only with INFORMIX-ESQL/C client applications. NOTE: support for the IFX_AUTOFREE environment variable will be dropped in a future release. Users should use the Autofree feature by explicitly using the SET AUTOFREE statement within their applications. RULES FOR USING THE SET AUTOFREE STATEMENT ========================================== Observe the following rules and considerations when you use the SET AUTOFREE statement: 1) If you specify the Autofree feature for a cursor, the cursor is freed after you close it and cannot be reopened. Also the prepared statement associated with the cursor is freed automatically, and it cannot be reused. 2) If you have not enabled the Autofree feature for a cursor, you must issue a FREE statement to free the cursor memory in the server. You must also issue a FREE statement to free the resources for the prepared statement associated with the cursor. 3) You do not have to enable the Autofree feature right before the first open of a cursor. You can enable the Autofree feature any time before you reopen the cursor. 4) If you use a SET AUTOFREE ENABLED statement to specify the Autofree feature for all cursors, the Autofree feature remains in effect until you issue a SET AUTOFREE DISABLED statement. 5) If you close a cursor that has an associated prepared statement, but the cursor does not have the Autofree feature enabled, the CLOSE statement does not cause the prepared statement to become detached. 6) If a cursor has the Autofree feature enabled, but the prepared statement within the cursor is not an associated statement, closing detached. 7) If you explicitly free a cursor that has an associated prepared statement, the FREE statement causes the prepared statement to become detached. Resources remain allocated for the detached prepared statement, and you can use the prepared statement in a new DECLARE statement. 8) Once a prepared statement becomes detached, the next DECLARE statement that uses this prepared statement causes the prepared statement to become the attached statement for the cursor specified in that DECLARE statement. 9) If you have not set the IFX_AUTOFREE environment variable to any value, or if you have set the value to 0, the Autofree feature is not enabled for the cursors in your program. If you want to enable the Autofree feature for a particular cursor, or for all the cursors in your program, you must enter an appropriate form of the SET AUTOFREE statement. 10) A potential problem exists with cursors that have the Autofree feature enabled. If you do not close the cursor explicitly and then open it again, the cursor is closed implicitly. This implicit closing of the cursor triggers the Autofree feature. The second time the cursor is opened, the database server generates an error message (cursor not found) because the cursor is already freed. This potential problem can only occur in databases that are not ANSI-compliant. In ANSI-compliant databases, an explicit CLOSE statement is required. C. Deferred Prepare Feature The SET DEFERRED_PREPARE statement is introduced in this release. This statement enables or disables the Deferred-Prepare feature in an application program. This feature defers the sending of a PREPARE statement to the database server until the OPEN statement is sent. The performance of the application is enhanced because fewer messages are sent between the application and the database server. The Deferred-Prepare feature is available for ESQL/C applications only. Syntax ====== The following diagram shows the syntax of the SET DEFERRED_PREPARE statement. This statement is an Informix extension to the ANSI standard. SET DEFERRED_PREPARE--------------------------------------------| | | | | | | |-----ENABLED-----| | | | | |-----DISABLED----| The meaning of the keywords in the syntax diagram is as follows: ENABLED enables the Deferred-Prepare feature. DISABLED disables the Deferred-Prepare feature. If you do not specify either the ENABLED or DISABLED keyword, the default behavior is ENABLED. Usage ===== The SET DEFERRED_PREPARE statement allows you to reduce the number of round-trip messages between the application program and the database server. This statement causes the application program to delay sending the PREPARE statement to the database server until the OPEN statement is executed. In effect, the PREPARE statement is bundled with the OPEN statement so that only one round trip of messages (not two) is sent between the client and the server. The Deferred-Prepare feature works with the following sequences: o PREPARE, DECLARE, OPEN sequences that operate with the FETCH or PUT statement o PREPARE, EXECUTE sequences or the EXECUTE IMMEDIATE statement If you use the Deferred-Prepare feature in a statement block that contains a DESCRIBE statement, the DESCRIBE statement must follow the OPEN statement rather than the PREPARE statement. If the DESCRIBE statement follows the PREPARE statement, the DESCRIBE statement results in an error. To execute the DESCRIBE statement successfully, you must place it after the OPEN statement. The ENABLED Option ================== The ENABLED option enables the Deferred-Prepare feature within the application. The following example shows the use of the ENABLED option: EXEC SQL set deferred_prepare enabled; When you enter a SET DEFERRED_PREPARE ENABLED statement in your application, the Deferred-Prepare feature is enabled for all PREPARE statements in the application. The application then exhibits the following behavior: o All DESCRIBE statements must be performed after the cursor has been opened with an OPEN statement. The following sequence of statements is valid: PREPARE, DECLARE, OPEN, DESCRIBE. The following sequence of statements is invalid: PREPARE, DESCRIBE. This sequence generates error message -1826. o The sequence PREPARE, DECLARE, OPEN sends the PREPARE statement to the database server with the OPEN statement. o If a prepared statement contains syntax errors, the database server does not return error messages to the application until the application has declared a cursor for the prepared statement and opened the cursor. The reason is that the PREPARE statement is not sent to the server until the OPEN statement is executed. o The sequence PREPARE, EXECUTE sends the PREPARE statement to the database server with the EXECUTE statement. If a prepared statement contains syntax errors, the database server does not return error messages to the application until the application attempts to execute the prepared statement. The DISABLED Option =================== The DISABLED option disables the Deferred-Prepare feature within the application. The following example shows the use of the DISABLED option: EXEC SQL set deferred_prepare disabled; When you disable the Deferred-Prepare feature, the application sends each PREPARE statement to the database server when the PREPARE statement is executed. None of the application characteristics described in "The ENABLED Option" applies when the Deferred-Prepare feature is disabled. Using Deferred-Prepare with OPTOFC ================================== You can use the Deferred-Prepare and OPTOFC (Open-Fetch-Close Optimization) features together in your application. The OPTOFC feature delays sending the OPEN message to the database server until the FETCH message is sent. You use the OPTOFC environment variable to enable the OPTOFC feature. You should be aware of the following consequences of enabling the Deferred-Prepare and OPTOFC features at the same time: o If the text of a prepared statement has syntax errors, the error messages are not returned to the application until the first FETCH statement is executed. The reason is that the OPTOFC feature optimizes the OPEN and FETCH statements so that the OPEN statement is sent with the first FETCH statement. o A DESCRIBE statement cannot really be executed until after the FETCH statement. ESQL/C enables users to work around this limitation by internally executing a statement similar to a SET DESCRIPTOR statement. Normally the user would have to specify this SET DESCRIPTOR statement before specifying the FETCH statement. The end result of internal execution of a SET DESCRIPTOR statement is that ESQL/C sets the TYPE, LENGTH, DATA, and other fields in the system descriptor area, and the user can specify a GET DESCRIPTOR statement after the FETCH statement to see the data that is returned. Note that the user must enter an ALLOCATE DESCRIPTOR statement before a DESCRIBE or GET DESCRIPTOR statement can be executed. For further information on the OPTOFC feature, see the documentation notes for the ESQL/C Programmer's Manual. Using Deferred-Prepare with OPTMSG ================================== You can use the Deferred-Prepare and OPTMSG (Optimized Messages) features together in your application. The PREPARE statement will not be chained and sent to the server until the OPEN statement is sent; Deferred-Prepare takes precedence over OPTMSG. For more information on the OPTMSG feature, see the documentation notes for the Informix Guide to SQL: Reference. ============================================================ Informix Guide to SQL: Tutorial ============================================================ No new information is available at this time. ============================================================ Informix Migration Guide ============================================================ Table of Contents A. New Environment Variables B. Reversion from OnLine Dynamic Server 7.23 C. Conversion to OnLine Dynamic Server 7.23 D. Installing the Latest Maintenance Release E. Corrections to the Migration Guide F. Using DB-Access with Dbschema Output G. Working with Dbexport Comments A. New Environment Variables The IFX_AUTOFREE and OPTOFC environment variables are not supported by Informix utilities. These environment variables should be used only with INFORMIX-ESQL/C 7.23 client applications. For more information, see the Documentation Notes for the INFORMIX-ESQL/C Programmer's Manual. B. Reversion from OnLine Dynamic Server 7.23 Follow steps 1 through 3 to revert to an earlier version of OnLine Dynamic Server if Enterprise Replication is active: 1) Stop Enterprise Replication. 2) For altered tables with CRCOLS, issue the command: alter drop CRCOLS 3) Perform the reversion process by issuing the command: onmode -b X In the command, X is the OnLine Dynamic Server version to which you are reverting. If you try to revert to a previous version of OnLine Dynamic Server while Enterprise Replication is active, the reversion will fail. Follow steps A and B to revert to an earlier version of OnLine Dynamic Server if Enterprise Replication is inactive. (Enterprise Replication was previously active on the server.) A) For altered tables with CRCOLS, issue the command: alter
drop CRCOLS B) Perform the reversion process by issuing the command. onmode -b X In the command, X is the OnLine Dynamic Server version to which you are reverting. To revert to an earlier version of OnLine Dynamic Server if Enterprise Replication has never been active on the server, perform the reversion process by issuing the command: onmode -b X In the command, X is the OnLine Dynamic Server version to which you are reverting. C. Conversion to OnLine Dynamic Server 7.23 To convert to OnLine Dynamic Server 7.23, install the 7.23 server and bring it on-line. Conversion to 7.23 occurs automatically. D. Installing the Latest Maintenance Release Informix recommends that you install the latest maintenance release for your current database server version before you migrate to a new version. Migration Complete ------------------ The first time OnLine Dynamic Server is brought on-line, the sysmaster database is built. The sysmaster database build might take as long as 15-30 minutes to complete. Check the message log to ensure that the sysmaster database build has completed before you allow users to access the database server. E. Corrections to the Migration Guide When Is the sysmaster Database Built? ===================================== The Migration Guide incorrectly states that the sysmaster database is built when you bring up the database server in quiescent mode. The sysmaster database is built when you bring the server on-line. For example, if you bring up the server with oninit -s, then with onmode -m, the sysmaster database is built. (Refer to pages 5-20, 6-33.) Creating a dbload Command File ============================== TIP: If you specify part (but not all) of the required information, dbload prompts you for additional specifications. The database name, command file, and error log file are all required. If you are missing these three options, you receive an error message. (See page 9-23.) Two consecutive delimiters define a null field. As a precaution, you can place a delimiter immediately before the new-line character that marks the end of each data row. If the last field of a data row has data, you must use a delimiter. If you omit this delimiter, an error results whenever the last field of a data row is empty. (See page 9-28, second paragraph.) Using the INSERT INTO Statement with dbload =========================================== Do not use the CURRENT, TODAY, and USER keywords of the INSERT INTO statement in a dbload command file because they are not supported. For example, the following dbload command is not supported: FILE "testtbl2.unl" DELIMITER '|' 1; INSERT INTO testtbl (testuser, testdttm, testfield) VALUES ('kae', CURRENT, f01); If you need to insert the current time, date, or user login into the table, write an SQL query. For example: INSERT INTO cust_calls (customer_num, call_dtime, user_ID, call_code, call_descr) VALUES (212, CURRENT, USER, 'L', '2 days'); The CURRENT keyword returns the system date and time. The word returns the system date. The USER keyword returns the user login name. F. Using DB-Access with dbschema Output You can use the dbschema utility to get the schema of a database, redirect the output to a file, and then feed this file to DB-Access. Inserting a Table into a Database Example ========================================= The following example copies the CREATE TABLE statements for the customer table into the dbschema output file, tab.sql. dbschema -d db -t customer > tab.sql Remove the header for dbschema from the dbschema output file. Then use dbaccess to recreate the table in another database: dbaccess db1 tab.sql Recreating the Schema in Another Database ========================================= The following examples puts the statements for creating the entire database into the dbschema output file. 1. Remove the header for dbschema from the output file. 2. Add a CREATE DATABASE statement at the beginning of the output file or use dbaccess to create a new database. 3. Use dbaccess to recreate the schema in a new database. dbschema -d db > db.sql dbaccess testdb db.sql Now you have databases db and testdb which differ in name but have the same schema. G. Working with Dbexport Comments The schema file that dbexport creates contains comments, enclosed in curly braces, with information about the number of rows, columns, and indexes in tables, and information about the unload files. Dbimport uses the information in these comments to load the database. WARNING: Do NOT delete any comments in the schema file. It is strongly recommended that you do not change any existing comments or add any new comments, or else the dbimport will abort or produce unpredictable results. (Refer to the IMPORTANT note on page 9-14.) TIP: If you delete some rows from an unload file, update the comment in the schema file with the correct number of rows for that unload file. Then the dbimport will be successful. The number of rows should match in the unload file and the corresponding unload comment in the schema file. If you change the number of rows in the unload file but not the number of rows in the schema file, there will be a mismatch. For complete information on dbimport, refer to the dbimport section of the Informix Migration Guide. ============================================================ Informix SNMP Subagent Guide ============================================================ On page 2-6, the last line of the sample installation script should include "rdbms.mib" instead of "rdbs.mib". (An "m" was omitted.) On page 2-6, in item 3 of the numbered list should read: "Copy appl.mib, rdbms.mib, and onmib.mib from the %INFORMIXDIR%\etc director into the temporary directory." (An "m" was omitted from "rdbms.mib" and the names of the source files were given incorrectly.) ============================================================ INFORMIX-OnLine Dynamic Server Administrator's Guide ============================================================ Table of Contents A. SQLHOSTS Registry B. HDR setup C. Using Multiple Server Names for the Same Remote Server in a Distributed Query D. Clarification of Data Replication term Migration E. Maximum Number of Allocated Buffers A. SQLHOSTS Registry (sqlhosts file in Chapter 4) OnLine Dynamic Server Version 7.22 introduced an enhanced SQLHOSTS registry. The enhanced SQLHOSTS registry allows users to define group options. The following is an example from the enhanced SQLHOSTS registry. #dbservername nettype hostname servicename options #-------------------------------------------------------------------- mygroup group - - i=123 dbserver1 onipcshm myhost myservice g=mygroup dbserver2 ontlitcp myhost myservice2 g=mygroup The group options are required if you choose to replicate information with Informix Enterprise Replication. If you do not use Informix Enterprise Replication, no changes are required for your existing SQLHOSTS registry. (For a detailed explanation and an example of an enhanced SQLHOSTS registry (sqlhosts file), see the Informix Guide to Enterprise Replication.) You need to create a separate SQLHOSTS registry for the 7.23 products if you will use Informix Enterprise Replication or the group options, and you currently have existing SQLHOSTS registries from one of the following Informix product versions: - 7.1x - 7.20 - 7.21 - 7.22 Use the following steps to help you create an enhanced SQLHOSTS registry to use Informix Enterprise Replication. Follow steps 1 through 2 to use the enhanced SQLHOSTS registry with Informix Enterprise Replication using client and server applications. Follow steps A through B to use the enhanced SQLHOSTS registry with Informix Enterprise Replication in a distributed environment. 1. Keep your current SQLHOSTS registry. Define entries for the OnLine servers without using any group related options. Use this SQLHOSTS registry for your existing 7.10 through 7.22 client applications and/or database servers. 2. Create a separate SQLHOSTS registry with the group related options for the OnLine 7.23 server. Use this SQLHOSTS registry for your OnLine 7.23 server and 7.23 client applications. To specify the full path name of the SQLHOSTS registry, use the INFORMIXSQLHOSTS environment variable. A. Keep your current SQLHOSTS registry. Define entries for the OnLine servers without using any group related options. Use this SQLHOSTS registry for your existing 7.10 through 7.22 server applications and/or database servers. B. Create a separate SQLHOSTS registry with the group related options for the OnLine 7.23 server. Use this SQLHOSTS registry for your OnLine 7.23 server applications. To specify the full path name of the SQLHOSTS registry, use the INFORMIXSQLHOSTS environment variable. B. HDR setup The ONCONFIG parameter LBU_PRESERVE must be set to 1 to use HDR. C. Using Multiple Server Names for the Same Remote Server in a Distributed Query When you use different server names/aliases for the same remote server in a distributed query, OnLine hangs the client program; however, other clients can function properly. The following is provided as a workaround: Avoid using multiple names for the same database server in distributed queries within the same client. If the client gets hung, interrupt it to return control to the database server. When you interrupt the client, the threads created by the client are not terminated. The threads are terminated when the servers are restarted. Note that the problem only hangs the client, and servers can continue to work with other clients. D. Clarification of Data Replication term When you see the term data replication in the book, it refers to High-Availability Data Replication (HDR). OnLine Dynamic Server, Version 7.23, includes a new feature named Enterprise Replication that allows peer-to-peer asynchronous data replication. For more information on Enterprise Replication, see the Informix Guide to Enterprise Replication. E. Maximum Number of Allocated Buffers The maximum number of allocated buffers has changed in Version 7.23. The previous formula was (768 * 1024). The new formula is (1800 * 1024). As always, an actual limit may be imposed by the memory available in the system and by the kernel shared memory parameters. See page 12-19 of the 7.2 Administrator's Guide for a description of the OnLine buffer table and allocating buffers. ============================================================ INFORMIX-OnLine Dynamic Server Guide to Feature Enhancements ============================================================ Table of Contents A. Migration B. SQL Syntax C. Database Server Information A. Migration Installing onsnmp ================= Enterprise Replication and the onsnmp utility require Windows NT SNMP. The installation and upgrade program checks the registry for the SNMP master agent. If the master agent has not been installed, the program displays a warning message but does not configure the registry for Enterprise Replication or onsnmp. If you later choose to install the SNMP master agent, you must run the %INFORMIXDIR%\bin\inssnmp.exe command-line utility to install the SNMP subagents. You need not reinstall the database server. Conversion to OnLine Dynamic Server 7.23 ======================================== To convert to OnLine Dynamic Server 7.23, install the 7.23 server and bring the server on-line. Conversion to 7.23 automatically occurs. B. SQL Syntax DEFINE changes ============== DEFINE variable LIKE is allowed. For example: create procedure proc1() define local_var like ; return; end procedure; The variable is treated as an integer variable. DEFINE variable serial is NOT allowed. For example: create procedure proc2() define local_var serial; return; end procedure; This example produces the following error: 670: Variable(local_var) declared as SERIAL type. C. Database Server Information HDR setup ========= The ONCONFIG parameter LBU_PRESERVE must be set to 1 to use HDR. Using Multiple Server Names for the Same Remote Server in a Distributed Query ============================================================================= When you use different server names/aliases for the same remote server in a distributed query, OnLine Dynamic Server hangs the client program; however, other clients can function properly. The following is provided as a workaround: Avoid using multiple names for the same database server in distributed queries within the same client. In event of hung state, interrupt the client to get control back. When you interrupt the client the threads created by the client are not terminated. The threads are terminated when the servers are restarted. Note that the problem only hangs the client, and servers can continue to work with other clients. Clarification of Data Replication Term ====================================== When you see the term data replication in the book, it refers to High-Availability Data Replication (HDR). OnLine Dynamic Server, Version 7.23 includes a new feature named Enterprise Replication, which allows peer-to-peer asynchronous data replication. For more information on Enterprise Replication, see the Informix Guide to Enterprise Replication. Trusted Facility Capabilities ============================= The following information pertains to the Trusted Facility capabilities of OnLine. Windows NT Event Logs --------------------- The Windows NT operating system provides an event-logging facility as a common repository for storing logs and other useful information. The event- logging facility also provides a user interface to filter, view, and back up the information that is stored there. Windows NT provides secure event logs, so OnLine does not need to provide any additional security. Security logs and system logs are for use only by Windows NT services that are running under the LocalSystem user account and the Windows NT security subsystem. Any workstation in the Windows NT network can view the event logs as long as the user has sufficient access rights. Security logs are accessible only to users who belong to the Windows NT Administrator group, including Domain Administrators. Any messages that OnLine writes to the OnLine log file, it also writes to the Windows NT event logs. OnLine also writes auditing records to the event logs. See "Event Logs for Auditing" on page 1-5 for more information on auditing records and the event logs. Message Server -------------- OnLine for Windows NT runs as a service under the informix user account. Because the Windows NT security logs and system logs are for use only by services running under the LocalSystem user account, OnLine includes a Message Server service that runs under that account. The Message Server communicates with OnLine through the named pipes interprocess communication (IPC) mechanism to receive information and write it to the event logs. OnLine starts the Message Server when it first needs to write a message to the event logs. The Message Server terminates automatically when OnLine terminates. Auditing -------- The INFORMIX-OnLine secure-auditing facility is described in the INFORMIX-OnLine Dynamic Server Trusted Facility Manual and the feature enhancement guide for ODS. The implementation of the auditing facility for OnLine for Windows NT, however, differs from what is described in that manual in the following ways: 1. OnLine uses the Windows NT event logs instead of audit-trail files to record audit events. 2. OnLine for Windows NT uses a Message Server to receive messages from OnLine and write them to the event logs. 3. OnLine does not use the ADTPATH and ADTSIZE parameters (because it does not use audit trail files). 4. The onaudit utility does not support the following options: -n (start a new audit file) -p auditdir (specify the directory where the audit files are to be created) -s maxsize (specify the maximum size of an audit file) The -c option, which displays the current configuration parameters, only displays the values of the ADTMODE and ADTERR parameters. 6. The onshowaudit utility does not support the -I (Informix- maintained audit files) and -O (Operating-system-maintained audit files) options because they are not applicable. 7. The onshowaudit utility supports the following additional options: -ts to extract only success audit records -tf to extract only failure audit records -d to assume default values for the user (current user) and the database server (INFORMIXSERVER) The -ts and -tf options are mutually exclusive, and the -u username and -s servername options are mutually exclusive with respect to the -d (default) option. See "The onshowaudit Utility" on page 1-8 for descriptions of these options. Event Logs for Auditing ----------------------- OnLine uses the event-logging facility, instead of audit-trail files, to store audit event records. The format of audit-trail records in the event logs is the same as it is for records in standard OnLine audit-trail files as described in the INFORMIX-OnLine Dynamic Server Trusted Facility Manual. The onshowaudit utility enables you to filter and review the OnLine audit records stored in the event logs. See "The onshowaudit Utility" later in this file for a description of onshowaudit. The onaudit Utility ------------------- This section and the following syntax diagram illustrate the onaudit tasks available in the Windows NT version of the utility. If you want to show the audit configuration or change the audit configuration, see the corresponding sections later in this file. If you want to do any of the following tasks, see the Trusted Facility Manual: Showing Audit Masks Creating or Adding an AUdit Mask Modifying an Audit Mask Deleting Audit Masks The sections describe the onaudit options for showing and changing the auditing configuration under Windows NT. Showing the Auditing Configuration ---------------------------------- Under Windows NT, the -c option only shows the values of the ADTMODE and the ADTERR parameters. The -c option directs the onaudit utility to display the current state of auditing. Sample audit-configuration output is shown below. > onaudit -c Onaudit -- Audit Subsystem Control Utility Copyright (c) Informix Software, Inc., 1995 Current audit system configuration: ADTMODE = 1 ADTERR = 0 Changing the Auditing Configuration ----------------------------------- Under Windows NT, the onaudit options available for changing the audit configuration are the -l and -e options. -l audit_mode specifies the auditing mode. This option pertains to the value set for the ADTMODE parameter in the ADTCFG file. It can have one of the following values: 0 turns auditing off. OnLine stops auditing for all existing sessions, and new sessions are not audited. 1 turns on OnLine-managed auditing; does not automatically audit DBSSO or OnLine administrator actions. 3 turns on OnLine-managed auditing; automatically audits DBSSO actions. 5 turns on OnLine-managed auditing; automatically audits OnLine administrator actions. 7 turns on OnLine-managed auditing; automatically audits DBSSO and OnLine administrator actions. -e error_mode specifies the error-handling method for auditing when OnLine cannot write a record to the audit file. This option specifies the value of the ADTERR parameter in the ADTCFG file and is in effect only when auditing is on. The error mode can have one of the following values: 0 a halt mode; indicates that OnLine should suspend processing a thread when it cannot write a record to the current audit file and should continue the write attempt until it succeeds. 1 also known as continue mode; indicates that OnLine should continue processing the thread and note the error in the message log. Errors for subsequent attempts to write to the audit file are also sent to the message log. 2 a halt mode; indicates that OnLine is to terminate the session. 3 a halt mode; indicates that OnLine is to shut down. The onshowaudit Utility ----------------------- The onshowaudit utility for Windows NT includes the -ts and -tf options to show only success or only failure audit records and the -d option to assume default values for the username and servername. Note that the Windows NT version of onshowaudit DOES NOT SUPPORT the -I or the -O options because onshowaudit uses the Windows NT event logs to store audit trail records. -ts directs onshowaudit to show only success audit records. -tf directs onshowaudit to show only failure audit ============================================================ INFORMIX-OnLine Dynamic Server Trusted Facility Manual ============================================================ Table of Contents A. Controlling Access to Audit Files B. Configuring and Enforcing Role Separation A. Controlling Access to Audit Files The ownership is informix. B. Configuring and Enforcing Role Separation For Windows NT, Role separation is controlled through Registry settings. ============================================================ Managing Relational Objects ============================================================ On page 6, in the Introduction chapter, the statement ...(located in the release directory of the installation directory)... should be ...(located in the %INFORMIXDIR%\release directory). In Appendix B, the term "splash box" is used. A splash box is an introductory screen that is displayed when a ROM component is launched. ============================================================ Using the INFORMIX-Command Center ============================================================ No new information is available at this time.