Release and Installation Notes Open Desktop ODT-DATA 1.1 Development System Extended Functionality Supplement For computers running Open Desktop 1.1 March 6, 1991 0. Preface These Release and Installation Notes document the Open Desktop(r) ODT-DATA 1.1 Development System EFS (Extended Functionality Supple- ment) product. Use this product when developing ODT-DATA applications to run under Open Desktop 1.1. The software provided in this release replaces the existing ODT-DATA Development System. If you upgrade to Open Desktop 1.1, use this EFS to upgrade the ODT-DATA Development System to version 1.1. The 1.1 EFS release includes several new features. Further, only the 1.1 ODT-DATA Development System is compatible with INGRESTM Applica- tions by Forms (ABF) 6.2. The 1.0 ODT-DATA Development System works with the ODT-DATA 1.1 server, but it has not been tested extensively. It is also incompati- ble with the new versions of ABF. Therefore, it is recommended that users of the ODT-DATA Development System install this EFS if they upgrade to Open Desktop 1.1. Note, however, that ODT-DATA applications developed with the libraries on this EFS may not run under Open Desktop 1.0. You should run them under Open Desktop 1.1 only. 0.1 Contents of This Package The ODT-DATA 1.1 Development System EFS consists of the following: o two ODT-DATA 1.1 Development System EFS diskettes o these Release and Installation Notes 0.2 About These Notes The ODT-DATA 1.1 Development System EFS Release and Installation Notes include the following: o Chapter 1, ``Installing Your Software,'' describes how to install or remove the software provided in the ODT-DATA Development Sys- tem. o Chapter 2, ``Release Information,'' describes features and enhancements specific to this release. 0.2.1 Conventions Used in This Guide This guide uses the following notational conventions: bold represents commands, command options, parameters in files, and data structures italics represents files, directories, and variables that you sup- ply; for example, in the command argument path:pathname, the variable pathname is replaced with an actual pathname when you type the command < > represents special keys that you press; for example, x means to hold down the Control key and press the x key simultaneously, then release them Courier represents system responses, excerpts from files, and pro- gramming examples 1. Installing Your Software 1.1 Introduction This chapter describes how to install and configure the ODT-DATA 1.1 Development System EFS under Open Desktop version 1.1. The installa- tion process uses a utility called custom(ADM). When custom installs a software product, the files that comprise the product are transferred from the distribution media to your system's hard disk drive. Using the information supplied in a parameter list, custom places the files in the correct locations, assigns permissions, and performs optional tasks such as making device nodes. Keep both of the floppy diskettes containing the EFS until the next release of Open Desktop, in case you have to install or re-install the packages. Please read these notes completely before you begin installing the EFS. The information contained within these chapters is crucial to the proper installation and operation of the updated system. 1.2 Prerequisites for Installation You can install the ODT-DATA 1.1 Development System EFS under Open Desktop 1.1 only. You must also have installed the Open Desktop Development System 1.0.1 or later. Before installing the EFS, you should read all chapters in this docu- ment. Also, log in as root, and be certain that you are in the root (/) directory before starting the installation procedure. 1.3 Installation Procedure The following procedure explains how to install the ODT-DATA 1.1 Development System EFS on a computer running Open Desktop version 1.1. The procedure involves two steps: 1. If the ODT-DATA 1.0 Development System is already installed, remove it using the custom installation utility. You must do this before installing the EFS. 2. Use custom to install the EFS from the two distribution diskettes. The following sections show you how to do this. 1.3.1 Removing the ODT-DATA 1.0 Development System Follow this procedure to remove the ODT-DATA 1.0 Development System from your Open Desktop System, if it is installed. If it is not installed, skip ahead to the next section and install the EFS. 1. Log in as root. Enter the root password at the password prompt. 2. Enter custom directly from the command line by typing custom and pressing , or from sysadmsh by making the following sysadmsh selection: System->Software 3. You see the main custom menu, which displays a list of the software currently installed on your system: --------------------------------------------- begin screen display --- Custom Install Remove List Quit Install software / Monday April 1, 1991 10:11 Open Desktop Open Desktop Development System --------------------------------------------- end screen display ----- The software list on your screen may be different from the list shown here. 4. Select Remove at the main custom menu and press . The custom utility displays the Remove screen, with a list of the software currently installed on the system at the bottom right-hand corner of the screen. It looks something like this: --------------------------------------------- begin screen display --- Remove Select a product to remove and press Press to cancel, movement keys are active Monday April 1, 1991 10:11 Select a product : [ ] Open Desktop * Open Desktop Development System --------------------------------------------- end screen display ----- Again, the software list on your screen may be different from the list shown above. 5. Highlight the Open Desktop Development System option, as shown in the previous screen example, and press . 6. You now see a screen that asks whether you want to remove the entire product, a service, or a service component. Highlight Service Component and press . ********************************************************************* Warning Do not choose the Entire Product option or the Service option. Choos- ing the Entire Product option removes the entire Open Desktop Develop- ment System, while choosing the Service option removes the ODT-DATA ISAM Development System. ********************************************************************* 7. You now see a screen which lists the components of the Open Desktop Development System. Highlight ODT-DATA Database Develop- ment System and press . 8. Now you see a list of the ODT-DATA Development System packages currently installed on your system. The list appears near the bottom of the screen. Highlight the All selection, to remove all the packages, and press . Now you see the following screen: --------------------------------------------- begin screen display --- Remove Proceed Monday April 1, 1991 10:12 Please verify the removal of the following packages: ALL Do you wish to continue? Yes No --------------------------------------------- end screen display ----- 9. To continue, select Yes and press . 10. You now see the message Creating file lists. . ., followed by the message Removing files. . .. When custom finishes removing the selected packages, you return to the main custom menu. If you selected the All option, the list of currently installed products on your screen no longer includes the ODT-DATA Develop- ment System. You can use the custom menu's List option to ver- ify this. 11. Exit custom by selecting the Quit option and pressing . You are asked to confirm that you want to quit; select Yes and press again. If you invoked custom from sysadmsh, press after quitting custom to return to the sysadmsh main menu. There, select Quit. You are asked to confirm that you want to quit; select Yes and press again to return to the operating system prompt. Even if you plan to install the EFS immediately, it is recom- mended that you quit custom now, and then start a new session of custom for installing the new code. 1.3.2 Installing the EFS Use the following procedure to install the ODT-DATA Development System EFS. Before you start, make sure that you have the two EFS distribu- tion diskettes. 1. Log in as root and enter the root password at the password prompt. 2. Enter custom directly from the command line by typing custom and pressing , or from sysadmsh by making the following sysadmsh selection: System->Software 3. You see the main custom menu: --------------------------------------------- begin screen display --- Custom Install Remove List Quit Install software / Monday April 1, 1991 10:11 Open Desktop Open Desktop Development System --------------------------------------------- end screen display ----- The software list on your screen may be different from the list shown here. Use the arrow keys to highlight the Install option and press . 4. The custom utility now displays the Install screen, with a list of the software currently installed on the system at the bottom right-hand corner of the screen. It looks something like this: --------------------------------------------- begin screen display --- Install Select a product to install and press Press to cancel, movement keys are active / Monday April 1, 1991 10:11 Select a product : [ ] Choose an option : [Entire Product] Packages Files * A New Product Open Desktop Open Desktop Development System --------------------------------------------- end screen display ----- Again, your software list may look different. Select A New Pro- duct and press . 5. The Install screen offers the choice of installing an Entire Product, Packages, or Files: --------------------------------------------- begin screen display --- Install Install the entire product / Monday April 1, 1991 10:11 Select a product : [A New Product ] Choose an option : Entire Product Packages Files --------------------------------------------- end screen display ----- Select the Entire Product option and press . 6. Next, the Install screen directs you to insert Distribution Floppy Volume 1 of the EFS: --------------------------------------------- begin screen display --- Install Insert the requested volume, and press to continue the installation / Monday April 1, 1991 10:12 Insert: Distribution Floppy Volume 1 Continue Quit --------------------------------------------- end screen display ----- Insert the EFS distribution disk marked Volume 1 of 2 and press to continue. The message Installing custom data files. . . briefly appears on the screen. Then the message Creating file lists. . . appears for a moment. At this point, custom asks you again to insert the Volume 1 diskette. You have already done this, so just press to continue. 7. The message Extracting files. . . now appears as the EFS is loaded into your system from the distribution diskette. When the information is loaded, custom asks you to insert ODT-DATA Development System EFS Floppy Volume 2. Insert the EFS distri- bution disk marked Volume 2 of 2 and press to continue. The message Extracting files. . . appears again as custom loads the rest of the EFS from the new distribution diskette. 8. When custom finishes extracting files from the second diskette, you see: --------------------------------------------- begin screen display --- Executing ODT-DATA Development System EFS Init Script --------------------------------------------- end screen display ----- 9. A new message appears, prompting you to press any key to con- tinue. Do so. Then you see: --------------------------------------------- begin screen display --- Checking file permissions... --------------------------------------------- end screen display ----- You now return to the main custom menu. 10. Exit custom by selecting the Quit option and pressing . You are asked to confirm that you want to quit; select Yes and press again. If you invoked custom from sysadmsh, press after quitting custom to return to the sysadmsh main menu. There, select Quit. You are asked to confirm that you want to quit; select Yes and press again. 11. Remove the distribution media from the disk drive. 12. Enter this command at the operating system prompt: ln /usr/ingres/lib/libingres.a /usr/lib/libingres.a This command copies the EFS software into the proper directory. If you do not do this, you have not actually upgraded the ODT- DATA Development System to Version 1.1. You may use the cp command instead of ln, if you want. If you use cp, however, you must also change the permissions, group, and ownership of the file that you are copying. You would have to enter all of the following commands to complete the copy pro- cess properly: cp /usr/ingres/lib/libingres.a /usr/lib/libingres.a chown ingres /usr/lib/libingres.a chgrp bin /usr/lib/libingres.a chmod 644 /usr/lib/libingres.a Installation of the ODT-DATA 1.1 Development System EFS is now com- plete. After you finish using the software distribution disks, you should store them in a safe place. If an accident or a hardware failure damages the development system files on your hard disk, you need the distribution media to reinstall the product. 2. Release Information 2.1 Introduction This chapter contains information specific to the ODT-DATA Development System 1.1 EFS release. Topics covered include: o compatibility with ODT-DATA 1.1 o compatibility issues, including incompatibilities with ODT-DATA 1.0 o new features 2.2 Compatibility Issues The following sections discuss compatibility of the ODT-DATA Develop- ment System 1.1 EFS and its components with releases of SCO Open Desk- top. 2.2.1 Compatibility with ODT-DATA 1.1 The ODT-DATA Development System 1.1 EFS is supported only on version 1.1 of Open Desktop. You must use the EFS if you want to use version 6.2 of INGRES Applications-By-Forms to develop applications under the 1.1 server. 2.2.2 No Backward Compatibility ODT-DATA applications developed with the libraries on this EFS will not run under Open Desktop 1.0. You can only run such applications on Open Desktop systems that you have upgraded to Version 1.1. 2.2.3 Generic Error Support for Future Releases In future releases, a set of generic error codes will replace all classes of specialized INGRES error numbers. Generic error codes allow applications to be more portable. Applications can run against an INGRES DBMS and gateways, and yet be able to program against a sin- gle set of error codes. Error numbers remain the same irrespective of the database management system. For backward compatibility, applications will be provided with an environment setting and an ESQL command that allows them to access the specific error instead of the generic error, which is the default. The runtime (LIBQ) support for embedded SQL applications that checks for both generic errors and local DBMS errors is already in place in the ODT-DATA 1.1 code. By default, ESQL applications are now seeing the local INGRES DBMS error in the INQUIRE_INGRES errorno and the SQLCA sqlcode statements. When the INGRES DBMS support for generic errors is completed, existing ESQL applications that check for specific error numbers in INQUIRE_INGRES errorno and SQLCA sqlcode will not work correctly. Applications that check only if an error occurred (sqlcode 0) will not be affected. 2.2.3.1 Implementation For backward compatibility and to ease the user's transition from local errors to generic errors, the following commands are currently available. Until the INGRES DBMS supports generic errors, the com- mands will not effect the errors reported. The DBMS only returns the local INGRES error. Here are the commands to allow programming of applications in anticipation of generic errors. o II_EMBED_SET environment variable If II_EMBED_SET is set to dbmserror, the local DBMS error (for example, the INGRES error) is reported in INQUIRE_INGRES errorno and in SQLCA sqlcode, and the generic error will be reported in INQUIRE_INGRES dbmserror and in SQLCA sqlerrd(1). The object sqlerrd(1) refers to the first element of the sqlerrd array. Note that some languages start array subscripts at 0. The default is for the generic error to be reported in INQUIRE_INGRES errorno and in SQLCA sqlcode and the local DBMS error is reported in INQUIRE_INGRES dbmserror and in SQLCA/sqlerrd(1). Here is the syntax for the command under the UNIX system C-shell: setenv II_EMBED_SET "dbmserror|genericerror" Here is the syntax for the command under the UNIX system Bourne shell or Korn shell: II_EMBED_SET="dbmserror|genericerror" export II_EMBED_SET o 3GL SET_INGRES command The ERRORTYPE parameter for this command gives the programmer control over the expected error returned by the DBMS regardless of the environment setting. The command SET_INGRES ERRORTYPE takes precedence over the II_EMBED_SET environment variable. Individual modules may set the error type, so in an application one module may use generic error codes, while another uses the DBMS error codes. This allows a generic error application to spawn a local error application successfully. Here is the syntax for the command: SET_INGRES (ERRORTYPE = :str_var|'genericerror'|'dbmserror') o 3GL INQUIRE_INGRES command This is the counterpart to the SET_INGRES command. This command returns a character string (genericerror or dbmserror). Here is the syntax for the command: INQUIRE_INGRES (:str_var = ERRORTYPE) 1.2.3.2 SQL Communications Area (SQLCA) The SQLCA returns an error number in sqlerrd(1), depending upon which error is returned in sqlcode. Based upon the II_EMBED_SET environment variable or SET_INGRES setting, the local INGRES error is reported in sqlerrd(1) if the generic error is the program default. If the local INGRES error is the program default, then the generic error is reported in sqlerrd(1). Please note that the INGRES DBMS local error is returned in INQUIRE_INGRES errorno|dbmserror and SQLCA sqlcode|sqlerrd(1) until the DBMS supports generic errors. These error messages are returned with the code from the ori- ginating DBMS to show the class of error that has occurred. The messages describe the type of error that has occurred, not the exact error. The following table includes the symbolic definitions for all of the generic error messages. Symbolic Definitions of Generic Error Messages Symbolic Definition Value Definition _____________________________________________________________________________ E_GE0000_OK 0 Successful completion E_GE0032_WARNING 50 Warning occurred E_GE0064_NO_MORE_DATA 100 End of data E_GE7594_TABLE_NOT_FOUND -30100 Table not found in database E_GE759E_COLUMN_UNKNOWN -30110 Column not known/not in table E_GE75A8_CURSOR_UNKNOWN -30120 Unknown cursor E_GE75B2_NOT_FOUND -30130 Other database object not found E_GE75BC_UNKNOWN_OBJECT -30140 Other unknown/unavailable resource E_GE75F8_DEF_RESOURCE -30200 Duplicate resource definition E_GE7602_INS_DUP_ROW -30210 Attempt to insert invalid duplicate row E_GE7918_SYNTAX_ERROR -31000 Statement syntax error E_GE797C_INVALID_IDENT -31100 Invalid identifier E_GE79E0_UNSUP_LANGUAGE -31200 Unsupported query language E_GE7D00_QUERY_ERROR -32000 Inconsistent or incorrect query specification E_GE80E8_LOGICAL_ERROR -33000 Runtime logical error E_GE84D0_NO_PRIVILEGE -34000 Not privileged/restricted operation E_GE8CA0_SYSTEM_LIMIT -36000 System limit exceeded E_GE8D04_NO_RESOURCE -36100 Out of needed resource E_GE8D68_CONFIG_ERROR -36200 System configuration error E_GE9088_COMM_ERROR -37000 Communication or transmission error E_GE9470_GATEWAY_ERROR -38000 Error in the gateway E_GE94D4_HOST_ERROR -38100 Host system error E_GE9858_FATAL_ERROR -39000 Session terminated E_GE98BC_OTHER_ERROR -39100 Unmappable error E_GE9CA4_CARDINALITY -40100 Cardinality violation E_GE9D08_DATAEX_NOSUB -40200 Data Exception, with subcode. The subcode is identified by SQLCODE - GE_DATA_EXCEPTION E_GE9D6C_CONSTR_VIO -40300 Constraint violation E_GE9DD0_CUR_STATE_INV -40400 Invalid cursor state E_GE9E34_TRAN_STATE_INV -40500 Invalid transaction state E_GE9E98_INV_SQL_STMT_ID -40600 Invalid SQL Statement ID E_GE9EFC_TRIGGER_DATA -40700 Triggered data change violation E_GEA028_USER_ID_INV -41000 Invalid user authorization ID E_GEA0F0_SQL_STMT_INV -41200 Invalid SQL statement E_GEA154_RAISE_ERROR -41300 Error was raised by user E_GEA21C_DUP_SQL_STMT_ID -41500 Duplicate SQL statement ID E_GEC2EC_SERIALIZATION -49900 Serialization failure (deadlock) The following table shows generic error subcodes: Generic Error Subcodes Symbolic Definition Value Definition ________________________________________________________________ GESC_NO_SC 00 No subcode GESC_TRUNC 01 Character data, right truncation GESC_NEED_IND 02 Null value, no indicator parameter GESC_NUMOVR 03 Exact numeric data, loss of signi- ficance ** (decimal overflow) GESC_ASSGN 04 Error in assignment GESC_FETCH0 05 Fetch orientation has value zero GESC_DTINV 06 Invalid datetime format GESC_DATEOVR 07 Datetime field overflow GESC_RSV08 08 Reserved GESC_INVIND 09 Invalid indicator parameter value GESC_CURSINV 10 Invalid cursor name GESC_TYPEINV 15 Invalid data type GESC_FIXOVR 20 Fixed-point overflow GESC_EXPOVR 21 Exponent overflow GESC_FPDIV 22 Fixed-point divide GESC_FLTDIV 23 Floating-point divide GESC_DCDIV 24 Decimal divide GESC_FXPUNF 25 Fixed-point underflow GESC_EPUNF 26 Exponent underflow GESC_DECUNF 27 Decimal underflow GESC_OTHER 28 Other unspecified math GESC_MAX 99 Max legal subcode The following codes combine a generic error code with the gen- eric error subcodes. The example used is the generic error code for data exceptions: Generic Error Codes Combined with Subcodes Symbolic Description Value Definition ______________________________________________ E_GE9D09_DATAEX_TRUNC -40201 E_GE9D0A_DATAEX_NEED_IND -40202 E_GE9D0B_DATAEX_NUMOVR -40203 E_GE9D0C_DATAEX_ASSGN -40204 E_GE9D0D_DATAEX_FETCH0 -40205 E_GE9D0E_DATAEX_DTINV -40206 E_GE9D0F_DATAEX_DATEOVR -40207 E_GE9D10_DATAEX_RSV08 -40208 E_GE9D11_DATAEX_INVIND -40209 E_GE9D12_DATAEX_CURSINV -40210 E_GE9D17_DATAEX_TYPEINV -40215 E_GE9D1C_DATAEX_FIXOVR -40220 E_GE9D1D_DATAEX_EXPOVR -40221 E_GE9D1E_DATAEX_FPDIV -40222 E_GE9D1F_DATAEX_FLTDIV -40223 E_GE9D20_DATAEX_DCDIV -40224 E_GE9D21_DATAEX_FXPUNF -40225 E_GE9D22_DATAEX_EPUNF -40226 E_GE9D23_DATAEX_DECUNF -40227 E_GE9D24_DATAEX_OTHER -40228 1.3 3GL Incompatibilities with ODT-DATA 1.0 The following sections describe how SQL under the ODT-DATA Development System EFS is incompatible with SQL applications developed under Open Desktop 1.0. 1.3.1 Error-Number Incompatibilities in 3GL SQL Applications In anticipation of the change to generic error codes in future releases, the INGRES runtime system linked to every SQL appli- cation has already been converted to return generic error codes by default. The INGRES runtime system errors represent a small class of errors that generally are not examined by user appli- cations. Their range is from hex 970001 to 9700be and 0b80005 to 0b8003d. In the event that there are existing applications that trap specific errors from this class, a symbolic mapping from the specific errors to the generic errors is provided below. The decimal code associated with each generic error sym- bol is included with the list of generic errors earlier in this chapter. Note that the INGRES DBMS error handling has not changed in this release. It continues to provide the INGRES-specific error and will not return generic error codes until a future release. The generic error codes may be accessed by the application through the INQUIRE_INGRES errorno statement and in the "sqlcode" field of the program's SQLCA. To examine the (old) specific error, a new parameter to the INQUIRE_INGRES command has been provided. The statement may be used by an embedded SQL program as follows: INQUIRE_INGRES (:intvar = dbmserror) In addition, the first element of the sqlerrd array in the SQLCA will be set to the INGRES specific error. The following table maps the INGRES runtime-specific errors to generic errors. Corresponding Runtime-Specific and Generic Errors Runtime-Specific Error Corresponding Generic Error ____________________________________________________________ E_LQ0001_STARTUP E_GE94D4_HOST_ERROR E_LQ0002_USTARTUP (Unused) E_LQ0003_ADFINIT E_GE8D04_NO_RESOURCE E_LQ0004_TWODB E_GE7918_SYNTAX_ERROR E_LQ0005_FLAGS E_GE7918_SYNTAX_ERROR E_LQ0006_ASSOC_BAD_FLAG E_GE7918_SYNTAX_ERROR E_LQ0007_PRINTQRY (Cannot be trapped by application) E_LQ0008_XID E_GE7918_SYNTAX_ERROR E_LQ0009_GCFMT E_GE9088_COMM_ERROR E_LQ000A_EMBBAD E_GE9D09_DATAEX_ASSGN E_LQ000B_EMBOVFL E_GE9D1C_DATAEX_FIXOVR E_LQ000C_EMBCNV E_GE9D09_DATAEX_ASSGN E_LQ000D_EMBDTID E_GE9D17_TYPEINV E_LQ000E_EMBIND E_GE9D0A_NEED_IND E_LQ0010_EMBNULLIN E_GE7918_SYNTAX_ERROR E_LQ0011_EMBNULLOUT E_GE9D09_DATAEX_ASSGN E_LQ0012_DBTOOLONG E_GE9D09_DATAEX_ASSGN E_LQ0014_DBVAR E_GE9D17_TYPEINV E_LQ0015_DBOVF E_GE9D1C_DATAEX_FIXOVR E_LQ0016_DBNULL E_GE9D0A_NEED_IND E_LQ0017_DBCONV E_GE9D09_DATAEX_ASSGN E_LQ0018_DBQRY_NULL E_GE7918_SYNTAX_ERROR E_LQ001F_BADPARAM E_GE7918_SYNTAX_ERROR E_LQ0020_PARMMAX E_GE9CA4_CARDINALITY E_LQ0021_RETPARAM E_GE8D04_NO_RESOURCE E_LQ002A_NODB E_GE7918_SYNTAX_ERROR E_LQ002B_INQUERY E_GE7918_SYNTAX_ERROR E_LQ002C_INPROC E_GE7918_SYNTAX_ERROR E_LQ0030_UTBAD E_GE94D4_HOST_ERROR E_LQ0036_INTERRUPT (unused) E_LQ003A_RETINIT E_GE80E8_LOGICAL_ERROR E_LQ003B_RETDESC E_GE80E8_LOGICAL_ERROR E_LQ003C_RETCOLS E_GE9CA4_CARDINALITY E_LQ0040_SHORTREAD E_GE9088_COMM_ERROR E_LQ004A_REPDEF E_GE80E8_LOGICAL_ERROR E_LQ004B_UNDEFREP E_GE80E8_LOGICAL_ERROR Corresponding Runtime-Specific and Generic Errors (Continued) Runtime-Specific Error Corresponding Generic Error ____________________________________________________ E_LQ0055_CSOPEN E_GE80E8_LOGICAL_ERROR E_LQ0056_CSDESC E_GE80E8_LOGICAL_ERROR E_LQ0057_CSALLOC E_GE8D04_NO_RESOURCE E_LQ0058_CSNOTOPEN E_GE75A8_CURSOR_UNKNOWN E_LQ0059_CSINIT E_GE80E8_LOGICAL_ERROR E_LQ005A_CSCOLS E_GE9CA4_CARDINALITY E_LQ005B_CSXCOLS E_GE9CA4_CARDINALITY E_LQ005C_CSRDO E_GE7918_SYNTAX_ERROR E_LQ006A_SQMULTSEL E_GE9CA4_CARDINALITY E_LQ006B_SQNULLDYN E_GE9D0A_NEED_IND E_LQ006C_SQVARDYN E_GE7918_SYNTAX_ERROR E_LQ006D_SQDESC E_GE80E8_LOGICAL_ERROR E_LQ006E_SQLDA E_GE7918_SYNTAX_ERROR E_LQ0080_QRYID E_GE80E8_LOGICAL_ERROR E_LQ008A_RDNODESC E_GE80E8_LOGICAL_ERROR E_LQ008B_RDTUPSIZE E_GE9088_COMM_ERROR E_LQ008C_RDCOLS E_GE9088_COMM_ERROR E_LQ008D_RDALLOC E_GE8D04_NO_RESOURCE E_LQ008E_RDTYPE E_GE9088_COMM_ERROR E_LQ008F_RDCOLEN E_GE9088_COMM_ERROR E_LQ0090_RDCONAME E_GE9088_COMM_ERROR E_LQ0091_RDFLAGS E_GE9088_COMM_ERROR E_LQ0092_RDTOOBIG E_GE9CA4_CARDINALITY E_LQ0093_RDTID E_GE9088_COMM_ERROR E_LQ00A0_ATTNOINQ E_GE7918_SYNTAX_ERROR E_LQ00A1_ATTNOSET E_GE7918_SYNTAX_ERROR E_LQ00A2_ATTBADTYPE E_GE8D04_NO_RESOURCE E_LQ00A3_ATTSETDATA E_GE7918_SYNTAX_ERROR E_LQ00B0_PROCNAME E_GE797C_INVALID_IDENT E_LQ00B1_PARAMNAME E_GE797C_INVALID_IDENT E_LQ00BA_SESSDUP E_GE80E8_LOGICAL_ERROR E_LQ00BB_SESSALLOC E_GE8D04_NO_RESOURCE E_LQ00BC_SESSID E_GE7918_SYNTAX_ERROR E_LQ00BD_SESSNONCUR E_GE80E8_LOGICAL_ERROR E_LQ00BE_SESSNOTFOUND E_GE7918_SYNTAX_ERROR Corresponding Runtime-Specific and Generic Errors (Continued) Runtime-Specific Error Corresponding Generic Error ______________________________________________________ E_CO0005_FILE_OPEN_ERR E_GE94D4_HOST_ERROR E_CO0006_FILE_CREATE_ERR E_GE94D4_HOST_ERROR E_CO0008_DOMAIN_SIZE (unused) E_CO0009_BAD_INPUT (unused) E_CO000A_EOF_ERR E_GE9D08_DATAEX_NOSUB E_CO000B_LEN_SPEC_ERR E_GE9D08_DATAEX_NOSUB E_CO000F_UNTERMINATED (unused) E_CO0011_WIDTH_EXCEEDED (unused) E_CO0014_BLANKED_CHARS E_GE9D08_DATAEX_NOSUB E_CO0015_TRUNCATED_CHARS E_GE9D08_DATAEX_NOSUB E_CO0018_BAD_FILETYPE E_GE7918_SYNTAX_ERROR E_CO0019_NOBINARY E_GE80E8_LOGICAL_ERROR E_CO001A_GENERAL_ERR (unused) E_CO001B_INVALID_VALUE (unused) E_CO001D_ROWLEN_EXCEEDED (unused) E_CO001E_TYPE_CONVERT (unused) E_CO0022_COPY_INIT_ERR E_GE80E8_LOGICAL_ERROR E_CO0023_COPY_INTRNL_ERR E_GE9D08_DATAEX_NOSUB E_CO0024_FILE_READ_ERR E_GE80E8_LOGICAL_ERROR E_CO0025_MEM_ALLOC_ERR (unused) E_CO0028_WARNINGS E_GE80E8_LOGICAL_ERROR E_CO0029_COPY_TERMINATED E_GE80E8_LOGICAL_ERROR E_CO002A_COPY_ABORTED E_GE80E8_LOGICAL_ERROR E_CO002B_BADROWS E_GE80E8_LOGICAL_ERROR E_CO002C_LOGGED E_GE80E8_LOGICAL_ERROR E_CO002F_LOG_WRITE_ERR E_GE94D4_HOST_ERROR E_CO0030_LOG_CLOSE_ERR E_GE94D4_HOST_ERROR E_CO0031_FILE_CLOSE_ERR E_GE94D4_HOST_ERROR E_CO0032_BAD_DATA E_GE9D08_DATAEX_NOSUB E_CO0036_LOG_OPEN_ERR E_GE94D4_HOST_ERROR E_CO0037_MEM_INIT_ERR E_GE80E8_LOGICAL_ERROR E_CO0038_MEM_ERR E_GE8D04_NO_RESOURCE E_CO0039_TUP_FORMAT_ERR E_GE80E8_LOGICAL_ERROR E_CO003A_ROW_FORMAT_ERR E_GE80E8_LOGICAL_ERROR E_CO003B_FILE_WRITE_ERR E_GE80E8_LOGICAL_ERROR E_CO003C_PROG_READ_ERR E_GE80E8_LOGICAL_ERROR E_CO003D_PROG_WRITE_ERR E_GE80E8_LOGICAL_ERROR 1.3.2 ESQL Indicator Variables When Embedded SQL retrieves character data from the database or form system into a host character variable that is shorter than the data being received, the indicator variable (if one has been provided) is set to the original length of the data. Prior to this release the only setting of indicator variables was to 0 (non-null) or to -1 (null). Programs that check for a null value using the following convention must be modified: if (indicator_var != 0) assume null; Modify such programs in this way: if (indicator_var = -1) assume null; This change only works for variables whose length is known at prepro- cess time. For example, the C preprocessor cannot determine the length of the buffer that a (char *) variable points to. 2.3.3 Dynamic SQL USING Clause An application program may now set the ``SQLD'' field to zero when the SQLDA descriptor is used with the dynamic EXECUTE OPEN statements. This allows an "empty" SQLDA to be used with statements that have no dynamic parameters. However, to use this feature, the source files containing the relevant dynamic SQL statement must be repreprocessed. Using an ODT-DATA 1.0 version of the preprocessor causes run-time SQL syntax errors. 2.4 New Features The following section describes new features in the ODT-DATA Develop- ment System 1.1 EFS. 2.4.1 Enhancements to the Forms System A number of enhancements were made to the Forms System: o Support of DisplayOnly and Invisible fields in the FRS Users can now specify, both at runtime and in the Visual Forms Editor (VIFRED), whether or not a field or table field column is display-only. Users can now specify, both at runtime and in VIFRED, whether a simple field or a table field is visible or invisible. o Changing a Field's Display Format at Runtime A field's display format can now be changed at runtime, subject to three restrictions. First, the field's datatype and new for- mat must be compatible. Second, the new format must not exceed the size of the original format. Finally, data in the field being reformatted must be valid. o New "activate timeout" Block Users can now regain control from the forms system when a certain amount of (application-specified) time passes without any user input at the terminal. An ``activate timeout'' block is run when such an event occurs in a display loop. If no such block (code) is specified, the display loop exits with a break display on timeout. Messages and prompts are also subject to timeout, returning as if the user had pressed . No timeout block will be executed in such cases. 1.4.2 3GL Enhancements The features in the following sections are supported in Embedded SQL across all host languages: o Dynamic Naming Capabilities for Cursors in ESQL Cursor names can be specified using host language string variables. The statements where cursor names are used are DECLARE, OPEN, CLOSE, FETCH/RETRIEVE, UPDATE/REPLACE, DELETE. The cursor name specified in a string variable has similar rules to the cursor name specified statically. o CALL SYSTEM Support in Embedded Languages Note that the CALL SYSTEM statement introduces a security hole if the application that contains the statement is installed as setuid on a UNIX system. SYSTEM is a new object on the CALL command. It provides application programs with a way to escape to the operating system. o Timeout Support This feature allows a program to regain control when the user's response in a forms-based application times out. The feature is enabled using the SET_FRS statement and is trapped using a new ACTIVATE TIMEOUT block in a DISPLAY loop. The timeout period is the length of time that the forms sys- tem waits for a user to take an action. If the user does not make a requested response or move the cursor within the specified time, the forms system returns control to the application. The timeout constant establishes the timeout period. The syntax for this is: exec frs set_frs frs (timeout = value); You can only specify a timeout period for user-written, forms-based applications. In the preceding syntax example, value specifies the length of the timeout period and can be an integer constant or integer variable. The timeout's length may not be greater than 32767 seconds. A timeout value of 0 means that no timeout will occur. If the timeout value is less than 0, the value is forced to 0 and a runtime error is issued. ********************************************************************* NOTE When the timeout period is less than 10 seconds, its behavior is very system-dependent. Some environments have problems working with small values for timers. Others will experience problems with small values only when heavily loaded. For these reasons, setting your timeout period to less than 10 seconds may affect the portability of your application. ********************************************************************* o Changing Field Display Formats Using the SET_FRS command, a program may now set or unset the attribute of a field on a form to be DISPLAYONLY or INVISIBLE. The INQUIRE_FRS command may be used by the pro- gram to inquire about these attributes. o Indicator Variable Usage When retrieving a character value into a host variable and the character value is longer than the size of the variable, the indicator variable, if provided, is set to the original length of the the character value. (The data is truncated and the ``SQLWARN1'' field of the SQLCA is set as in previ- ous releases.) This can only be done if the length of the host variable is known at preprocess time. This feature is compatible with ANSI SQL. o Open-SQL Preprocessor Flag The ESQL preprocessor may be invoked with the -wopen flag, which causes a warning to be given whenever a non-open SQL statement is used. This flag is useful when writing applica- tions that must be portable to gateways. o Dynamic SQL ``USING DESCRIPTOR'' Syntax The DESCRIBE and PREPARE statements have been changed to allow the keywords USING DESCRIPTOR as an alternative to the word INTO. The following example shows the syntax for the DESCRIBE statement: DESCRIBE statement_name INTO | USING DESCRIPTOR descriptor_name [USING NAMES]; The following example shows the syntax for the enhanced PREPARE statement: PREPARE statement_name INTO | USING DESCRIPTOR descriptor_name [USING NAMES]; FROM string This syntax is in keeping with ANSI SQL standards. o Empty Descriptor Usage A descriptor containing zero SQLVAR elements may be used with a dynamic EXECUTE or OPEN statement. In previous releases INGRES SQL required that the ``SQLD'' field be greater than zero, disallowing the descriptor clause to be used for a statement with no dynamic parameters. This change allows a single-coded EXECUTE statement to be associated with a dynamic statement that may or may not require parame- ters. o Dynamic SQL EXECUTE PROCEDURE Extension Prior to this release, database procedures could only be executed using the hard-coded EXECUTE PROCEDURE statement with static procedure and parameter names. This caused prob- lems for dynamic applications that created random procedures (via interactive SQL scripts) but did not allow their execu- tion during the running of the driving application. The new syntax of the EXECUTE PROCEDURE statement includes a dynamic SQL variant that enables you to specify the procedure name, parameter names, and variables dynamically. Refer to the Embedded SQL Reference Manual for a complete description. o Extended Data Types (C Language Only) The C preprocessor for Embedded SQL now accepts Extended C types in data declarations. This syntax includes UNSIGNED declarations and type ``adjectives'' such as LONG INT.