Home

Acu4GL User`s Guide v8.1 - Micro Focus Supportline

1. Through experience we have discovered specific ways to better map errors for some drivers For a list of these driver error mapping suggestions look at the file odbcerrs on your installation disks D 24 m Acu4GL for ODBC Information A_ODBC_ISOLATION_LEVEL Use the ALODBC_ISOLATION_LEVEL configuration variable to set the isolation level The default ordering of isolation levels is SQL_TXN_READ COMMITTED SQL_TXN_READ_ UNCOMMITTED SQL_TXN_REPEATABLE READ SQL_TXN_SERIALIZABLE You can change the isolation level by setting the configuration variable A_ODBC_ISOLATION_LEVEL to an integer in the configuration file The settings are Isolation level Setting in configuration file SQL_TXN_READ_UNCOMMITTED 1 SQL_TXN_READ COMMITTED SQL_TXN_REPEATABLE READ SQL_TXN_SERIALIZABLE For example to set the isolation level to SQL_TXN_READ_COMMITTED add the following entry to the configuration file A_ODBC_ISOLATION_LEVEL 2 If the user set isolation level is not supported by the driver the default method of selecting a level is used A_ODBC_LOCK_METHOD Use this variable to specify the locking method that the Acu4GL product should use when accessing your data source Possible values are none SETPOS SETSTMTOPTION UPDATECOLUMN Configuration File Variables m D 25 Example A_ODBC_LOCK_METHOD UPDATECOLUMN The default value is none
2. Example A_MSSQL_ADD TIMESTAMP 1 Note If you do not use this option be prepared for REWRITE statements to fail with an error stating that someone else has modified the row Because of the AcuLocks tables this can happen only from non ACUCOBOL GT applications A_MSSQL_APPROLE_NAME This variable in conjunction with ALMSSQL_APPROLE_PASSWD allows Acu4GL to use approles Before connecting to a database set A_MSSQL_APPROLE_NAME to the name of a role Note that you must also set ALMSSQL_APPROLE_PASSWD to a password for that role By using these two variables you set the runtime to use this approle For more information on approles please see the SQL Server documentation See also A_MSSQL_APPROLE_PASSWD A_MSSQL_APPROLE_PASSWD This variable in conjunction with ALMSSQL_APPROLE_NAME allows Acu4GL to use approles Before connecting to a database set A_MSSQL_APPROLE_ NAME to the name of a role Then set A_MSSQL_APPROLE_PASSWD to a password for that role By using these two variables you set the runtime to use this approle Configuration File Variables m B 13 For more information on approles please see the SQL Server documentation See also A_MSSQL_APPROLE_NAME A_MSSQL_CURSOR_OPTION_1 A_MSSQL_CURSOR_OPTION_ 2 A_MSSQL_CURSOR_OPTION_3 These configuration variables allow you to fine tune the declaration of cursors in the Acu4GL for Microsoft SQL Server product In general cursors are declared with th
3. c ccscccssessssessscsesecsseessaecsseesees C 31 C 2 m Acu4GL for Oracle Information C 1 Oracle Concepts Overview Acu4GL for Oracle is based on the Oracle Call Interface OCD an API that makes the ACUCOBOL GT code more portable to the maximum number of platforms A quick overview of some basic design concepts underlying the Oracle Database Management System will help you interface your COBOL program to it Transactions The Oracle RDBMS is a transaction based system All of the work that you perform while using Oracle must occur within a transaction whether that work is being done through Acu4GL for Oracle or another 4GL application When you use Acu4GL for Oracle a transaction is implicitly started for you by the database engine itself with the first file I O operation performed on a file associated with Oracle Because all operations with Acu4GL for Oracle occur within a transaction any record locked during processing remains locked until either a COMMIT WORK or ROLLBACK WORK is issued This action results in behavior similar to the LOCK ON MULTIPLE RECORDS clause in COBOL The benefits of a transaction management system are best illustrated by an example A COBOL application that handles order entry might perform these steps to accept an order 1 Write an invoice record 2 Update a customer record 3 Write a payroll record for sales commissions 4 Update an inventory record This series of four file operat
4. We first need to determine where you have installed ORACLE If the environment variable ORACLE_HOME has been set the script continues and the next message you see is the version inquiry below If ORACLE_HOME has not been set to the Oracle directory name the installation script displays this message Enter the directory where ORACLE is installed Type the name of the directory in which you installed Oracle and then press Enter The script then determines whether a directory by that name exists if not the script displays the following message entered directory isn t a directory and returns to the Enter the directory prompt to give you another chance After you have entered a legitimate directory name the script responds with C 12 m Acu4GL for Oracle Information Creating Makefile ora You should now be able to execute a make with the command make f Makefile ora in the lt ACUCOBOL GT directory gt lib These are just informative messages Note Be sure to review the makefile ora file and make adjustments as necessary 2b Link the runtime system If you need to link in your own C routines add them to the SUBS line of the file Makefile ora See Chapter 6 in A Guide to Interoperating with ACUCOBOL GT for details on linking C subroutines Make sure you are in the directory containing the ACUCOBOL GT runtime system Then at the UNIX prompt enter the following command make c
5. A 1 Getting Started with Acu4GL for Informix Important Micro Focus does not provide the Informix libraries along with the Acu4GL product The Informix Libraries are necessary for providing a proper connection between Informix and extend products If you do not already possess them please consult your database documentation or database vendor for information on obtaining these libraries You need to order Embedded ESQL for C If you are using the version 5 1 series you need the version 5 1 0 UC1 client libraries If you are using the version 7 2 series or higher you need the version 7 2x or higher To find out whether you can use a client server environment to communicate with other database versions contact IBM Follow the directions provided in your Informix documentation for installation of the Informix libraries or depending on what your arrangement is with Informix contact Informix Technical Support for any questions you may have Before you begin using Acu4GL for Informix on a new system you must install and configure the Informix RDBMS Your Informix vendor provides installation instructions Several steps that must be performed before you begin using Acu4GL for Informix on a new system are e Install and configure the Informix RDBMS e Install Acu4GL for Informix e Designate a database Note Acu4GL for Informix does not support ANSI mode databases e Prepare and compile your COBOL program Your Info
6. Note Often errors are generated for the simple reason that the ODBC driver version you are using is incompatible with Acu4GL for ODBC If you encounter errors when using Acu4GL for ODBC run the driver test program found on your installation disks to determine if you are using a compatible driver version Refer to section D 9 Driver Requirements for more details on the driver test program Runtime Errors Runtime errors will have this format 9D xx The 9D indicates a file system error and is reported in your FILE STATUS variable The xx is a secondary error code These are the secondary errors reported directly from Acu4GL 9D 01Read error on dictionary file An error occurred while reading the XFD file this probably means the XFD is corrupt Recompile with Fx to re create the dictionary See section 8 1 for additional information on compiler options Troubleshooting m D 43 9D 02 Corrupt dictionary file The dictionary file for one of your COBOL files is corrupt and cannot be read Recompile with Fx to re create the dictionary 9D 03 Dictionary xfd file not found The dictionary file for one of your COBOL files cannot be located Be sure you have specified the correct directory via your XFD_PREFIX runtime configuration file variable You may need to recompile with Fx to create the dictionary 9D 04 Too many fields in the key There are more than 16 fields in a key Check your key definit
7. Type Qualifier Owner Table SYSTEM T C Autility_te MSys cce SYSTEM T C Sutility_te MSysACEs SYSTEM T C Sutility_te MSysObjects SYSTEM T C Sutility_te MSysQueries SYSTEM T C utility_te MSysRelati Date Source C Sutility_te accounts AB C utility te animals Eam TABLE C Sutility_te clients Create FD TABLE C Sutility_te codes TABLE C utility_te pets The Column and Create FD buttons become active To see a listing of columns and data types proceed to step 6 To create an FD go to step 8 6 14 m Working with COBOL 6 Click Columns to display a list of the columns in the table and their associated COBOL data types Table Columns dialog E x 03 animals key 05 PHONE pic 8 03 animals data 05 PATIENT_ID pic x 5 05 ATYPE pic x 1 05 OWNER pic 30 05 YEAR pic s9 2 v9 0 05 SEQ_NO pic s9 4 v9 0 05 MM pic s9 2 v9 0 05 DD pic s9 2 v9 0 05 YYYY pic s9 4 v9 0 05 FEE pic s9 5 v9 2 05 DATE_PAID pic s9 8 v9 0 Note that PHONE appears first even though it is not the first column in the table That is because PHONE was defined as the table s key so acu4glfd treats it as a unique index moving it to the top of the list of columns 7 Click OK to close this window 8 Click Create FD to display the Save As dialog Use this standard Windows dialog to indicate where the FD file should reside Be su
8. You can retrieve a secondary error code by using selected runtime options or by calling the library routine CSRERR described in Appendix I in Book 4 Appendices of the ACUCOBOL GT documentation set Note that you can pass two parameters to CSRERR for interface errors rather than just one 9 16 m Performance and Troubleshooting 9 2 3 1 The first parameter retrieves the code the second parameter retrieves a message associated with the error condition Note For Oracle users Because 9D takes two bytes and Oracle secondary errors can be four bytes the first parameter should be PIC x 6 You can retrieve runtime errors in three ways as described in the following sections e Retrieving messages using the x runtime option e Retrieving messages using the debugger e Retrieving messages using CSRERR Unless noted otherwise these methods apply to all RDBMs supported by the Acu4GL family of interfaces For a listing of runtime errors refer to the Troubleshooting section of the appendix that pertains to your product Retrieving messages using the x runtime option At run time if you specify an error file and use the x option the runtime puts the extended error code and some text associated with the error into the error file When run against an Informix database you ll see three levels of error codes in the file ACUCOBOL GT error Informix database error and ISAM error A value of z
9. the default value A_LSYB_SELECT_KEY_ ONLY causes the interface to select only key columns when searching for records and then select the entire row of the single record that must be returned to the COBOL program E 40 m Acu4GL for Sybase Information Setting A_SYB_SELECT_KEY_ONLY to False does not affect how the select is created for files open I O since the record must be locked and then the rest of the data fetched but it causes the interface to select all the columns of the table for files open INPUT While the default value is On true yes this configuration variable can also take values of Off false no A_SYB_SKIP_ALTERNATE_KEYS A_SYB_SKIP_ALTERNATE_KEYS determines whether alternate keys are used to form indexes during table creation The default value of this variable is 0 which means it s okay to use alternate keys If you set the variable to a nonzero value such as 1 alternate keys are not used to form indexes which speeds up processing if many writes or rewrites are being performed Note that a value of 1 may slow processing if the application is reading sequentially using an alternate key While the default value is 0 off false no this configuration variable can also take the value of On true yes You can load a great deal of data into a table rapidly with this variable set to 1 and then create the missing indexes using isql See also Th
10. ALSYB_ADD_IDENTITY adds an extra column to any table created by the Acu4GL for Sybase product The extra column will have the identity property and will be included on all indexes that are not unique Otherwise when A_LSYB_ADD_IDENTITY is set at False an extra column is not added While the default value is Off false no this configuration variable can also take values of On true yes Note The COBOL FD should not include the identity column Example A_SYB_ADD_IDENTITY TRUE On keys that allow duplicates this variable has been found to vastly improve performance Note that the default value is True for a file that allows duplicates and is False for a file with no duplicate keys A_SYB_ADD_TIMESTAMP Using a timestamp column is the only way to absolutely ensure that modifications made to a row are not overwriting someone else s changes See the discussion of BROWSE MODE in the Sybase Commands Reference Manual When reading a table that is open for I O the Acu4GL for Sybase product uses BROWSE MODE if a timestamp column exists When the Acu4GL product is creating a table if the value of A_SYB_ADD_TIMESTAMP is 1 a timestamp column is included in the E 26 m Acu4GL for Sybase Information table Note that your COBOL FD should not include the timestamp column While the default value is Off false no this configuration variable can also take values of On tr
11. In reality most of the time the database query optimizer will not build the entire working set if it has been properly tuned but will instead perform INDEXED READS to process the query This means that the query optimizer will traverse an index tree to retrieve the records much as COBOL index files do as opposed to using combinations of indexes and sort and merge operations It can be helpful for the COBOL developer to influence precisely which information is to be returned If the application developer knows at compile time or before the query is executed the precise scope of the record processing that needs to be performed by the read operations the developer can more finely tune the information being retrieved Acu4GL provides a method by which the COBOL programmer can provide additional information to the database query optimizer by providing more specific selection information to the Acu4GL product This selection information is added to the WHERE clause of the SQL queries generated by the Acu4GL product This can be particularly useful in providing upper boundaries to queries being generated with the result that the working set is smaller The developer may provide upper boundaries on the key segments for a select or any other selection criteria needed to constrain the working set to just the desired subset of rows This additional information is added to 9 10 m Performance and Troubleshooting generated queries with the AN
12. UNIX or Windows NT server Intallations Perform the following steps on the server machine the client and server may be located on the same machine E 12 m Acu4GL for Sybase Information Step 1 Install Sybase The Sybase server version 11 0 or later must be installed and configured on your server machine Follow the Sybase installation instructions in your Sybase documentation Step 2 Move the ACUCOBOL GT stored procedures Move syb_inst sql to your server machine the one hosting the Sybase RDBMS This file was created in step 2 of the client installation Step 3 Install the ACUCOBOL GT stored procedures You must have Database Administrator privileges to install the ACUCOBOL GT stored procedures on the server You need to enter the password for the Database Administrator Enter the following command isql Usa Ppassword lt syb_inst sql syb_inst sql is created during the installation of the client By default the stored procedures are installed into the master or sybsystemprocs databases However you may choose another database in which to store them Follow these steps if you want to install the stored procedures in a database other than the default 1 Before you execute the syb_inst sql query modify the query file to use the desired database instead of the master or sybsystemprocs database After you have modified the query file execute it as described above 2 Create in each databas
13. Variable file name requires File directive This message occurs when the compiler cannot assign a name to the xfd file because the ASSIGN phrase for the file names a variable file name In this case you must use a FILE directive to name the xfd file WHEN variable xxx not found in record This happens if you have a WHEN directive that mentions a variable that doesn t exist in the record 9 2 2 Compiler Warnings xxx not unique in first 30 characters This message occurs if a field name is not unique within the first 30 characters The xxx is the name found You can either change the field name or apply the NAME directive The warning listed below can occur when you compile with the Zx or Fx option The data dictionary will be built and Acu4GL will operate correctly The warning informs you of a special database situation that is not advisable Field xxx causes duplicate database data This warning means that your record definition should be restructured Your current definition is set up in such a way that e you have overlapping key fields and e both keys must be represented in the database as separate items Acu4GL will handle this situation correctly It will keep the overlapping keys updated simultaneously so that they always have the same value However the warning alerts you that you have the same data represented twice in the database This is dangerous because someone at the site might access the
14. You also see Creating cblconfig syb This is a sample file of configuration variables you may want to add to your cblconfig file You then see the following message Do you want to set up the Makefile for this system Type n or N to quit the script Step 4 Install the ACUCOBOL GT stored procedures You must have Database Administrator privileges to install the ACUCOBOL GT shared procedures on the server You need to enter the password for the Database Administrator Enter the following command isql Usa Ppassword lt syb_inst sql Installation and Setup m E 17 By default the stored procedures are installed into the master or sybsystemprocs databases However you may choose another database in which to store them Follow these steps if you want to install the stored procedures in a database other than the default 1 Before you execute the syb_inst sql query modify the query file to use the desired database instead of the master or sybsystemprocs database After you have modified the query file execute it as described above 2 Create in each database that contains tables accessed by Acu4GL the stored procedures that were previously in the master or sybsystemprocs database Note that the stored procedures are executed without being prefixed by a database name and Sybase requires that such stored procedures must be in the master or sybsystemprocs database The interface also searches for and executes th
15. A_MSSQL_NATIVE_LOCK_TIMEOUT This is one of two locking methods available with Acu4GL for Microsoft SQL Server The methods are accessed via two configuration variables A_MSSQL_VISION_LOCKS_FILE and A_MSSQL_NATIVE_LOCK_TIMEOUT The lock method used is determined as follows If ALMSSQL_VISION_LOCKS_FILE is set to the name of a Vision file that can be open I O and has the correct structure the Vision file is used to hold lock information If A_MSSQL_NATIVE_LOCK_TIMEOUT is set to a positive value native locking is used Otherwise the AcuLocks table is used to hold locks B 20 m Acu4GL for Microsoft SQL Server Information This locking method enables you to use Microsoft SQL Server native locks if you explicitly code transactions in your COBOL program You can access this method by setting the configuration variable A_MSSQL_NATIVE_LOCK_TIMEOUT to a positive value This value will be the number of seconds that a connection will wait for a timeout to occur When such a timeout occurs for any reason the Acu4GL product assumes that the timeout was caused by a locked record and will return error 99 record locked If you set this variable but do not explicitly code transactions in your COBOL program record locking will not occur Note that the Acu4GL product will wait the number of seconds specified and your application may seem to hang if the timeout is too long On the other hand if the timeout is too short you may get record loc
16. If you do not know the data source name in advance or if you intend to use more than one data source you may set the data source name dynamically at run time In your COBOL program you would add code similar to this prior to the statement that opens the file SET ENVIRONMENT A_DB2_ DATASOURCE TO DB2 Database You are now ready to use the sql acu program as outlined in section 2 4 Using the sql acu Program After you learn about and use this utility you next find out about preparing and compiling your COBOL program followed by learning to use the demonstration program See section 6 1 Preparing and Compiling Your COBOL Program and section 2 5 The Demonstration Program for additional information F 3 Filename Translation As you prepare to work with Acu4GL for DB2 you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD files are formed and work together When the ACUCOBOL GT compiler generates XFD files it uses lowercase letters to name the XFD file In addition the compiler changes hyphens to underscores when naming the XFD file Through configuration variables the runtime translates the name in the COBOL program into the filename that is passed to the open function in the runtime The open function determines which file system to pass the request to but does not change the name of the file F 14 m
17. To generate a list of columns and data types and a SELECT statement 1 Start the utility by clicking on the acu4glfd icon or entering acu4glfd at the Windows command prompt By default acu4glfd exe resides in your acugt bin directory 2 Click Data Source in the Choose a table dialog Click OK to terminate the application x Type Guster Owner Table Data Source Columns Create FD 3 Select a data source from the standard Microsoft dialog that appears Select Data Source E 21x File Data Source Machine Data Source Data Source Name Description bob s data base User using bob s sample table check_test User checking User clinicO1 User User using my source files datatest User dBASE Files User dBase Files Word User ey tiene Llane adha drittar bar aracla J wll New Machine Data Source is specific to this machine and cannot be shared User data sources are specific to a user on this machine System data sources can be used by all users on this machine or by a system wide service Cancel Help Creating File Descriptors and SELECT Statements m 6 13 If necessary enter your user name and password in the Authorization area of the Login dialog Select a table from the Choose a table dialog which now contains a listing of the tables in the data source you selected in step 3 Note that you can choose only one table at a time gt
18. environment Front end application ODBC interface ODBC API calls Data ODBC Driver Manager ODBC driver calls Data ODBC single tier driver Commands Data Local database files g DBF indexes e g Single tier ODBC architecture ODBC Concepts m D 5 The following diagram indicates how these components work together in a multiple tier environment ODBC interface Front end application ODBC API calls i Data ODBC Driver Manager ODBC driver calls i Data ODBC multiple tier driver Database interface calls i Data Proprietary database communication interface Database engine commands a Networking software E Data Back end database engine Commands Data Physical database Multiple tier ODBC architecture D 6 m Acu4GL for ODBC Information Application The application is your COBOL program or more precisely the ACUCOBOL GT runtime system together with Acu4GL for ODBC The runtime generates the appropriate SQL queries to accomplish the file I O task that your COBOL program is executing This includes all file positioning and record locking When the query results are returned to the ACUCOBOL GT runtime they are mapped either to a COBOL record or to the appropriate COBOL status code if one exists Driver Manager The driver manager loads the ODBC driver The driver manager then passes requests to the driver and returns results to the ACUC
19. on yes its default value the number of columns in the database table do not have to match up with the number of fields in the COBOL program that is accessing 8 10 m Compiler and Runtime Options the table The database table can have more columns than the COBOL program references however the COBOL program may not have more fields than the database table Ensure that these extra columns are set correctly when new rows are added to the table This is database dependent For example under Sybase the columns should either have a default value or should allow NULL Ensuring that the column value is set is important because the SQL generated by the Acu4GL interface will not reference the extra columns when inserting rows This configuration variable can also take values of False off no Note Only the Acu4GL products for Sybase and Microsoft SQL Server support this variable This behavior is the default for Informix and Oracle AGL_FULL_DATA_TEST The configuration variable 4GL_FULL_DATA_TEST allows you to specify whether an entire field is tested for illegal data or if only the first byte is tested The default value is False 0 off no meaning that only the first byte of data is tested However if you set 4GL_FULL_DATA_TEST to True 1 on yes the entire field is tested for illegal data AGL_IGNORED_SUFFIX_LIST This variable is a space delimited list of case independent suffixes to ignore wh
20. Acu4GL for ODBC multiple tier D 9 single tier D 8 architecture ODBC multiple tier D 5 single tier D 4 ASSIGN name XFD file 3 9 backwards compatibility XFD files 3 2 Index 10 m BINARY directive 4 6 BINARY numbers illegal COBOL data 5 2 Btrieve file systems 1 6 building SQL statements 1 13 C case conversions 7 2 cblutil utility 3 7 changing database functions 1 15 checking for stored procedures E 26 Acu4GL for Sybase E 27 C ISAM file systems 1 6 COBOL COMMIT verb C 5 F 5 database interaction 9 6 mapping data to ODBC D 39 mapping DB2 data to F 29 mapping ODBC data to D 40 matching COBOL fields to database fields 7 2 modifying procedures 9 10 preparing and compiling programs 6 2 COBOL code and hyphens 3 7 COBOL data invalid 5 2 COBOL T O translation 1 10 COBOL programs and sql acu 2 4 COBOL records forming 1 13 mapping to databases 1 12 COBOL TRIGGER directive 4 7 columns forcing group items to become 3 3 mapping 1 11 3 3 command line and sql acu 2 3 m Index 11 COMMENT directive 4 8 COMMIT verb C 5 F 5 COMMIT_COUNT configuration variable C 23 COMMIT_COUNT environment variable C 4 COMMIT_COUNT methods F 4 COMP 2 numbers illegal COBOL data 5 2 COMP 3 numbers illegal COBOL data 5 2 compiler errors 9 12 compiler options 8 2 creating XFD files 8 2 data dictionaries XFD files building 8 4 directory for data dictionary XFD files 8 3 matching field names XFD files 8 2 single locking 8 3 STAR
21. CSRERR using error status error text status type display FILE ERROR primary error display DATABASE ERROR secondary error display error text accept omitted stop run Here s an example of the output you might get from this FILE ERROR 9D DATABASE ERROR 1608 A network error was encountered when results were sent to the front end Check the error log for more information Troubleshooting m 9 19 For Informix Remember that the extended code can consist of two parts database error and ISAM error separated by a comma In the example shown below we use the library routine CSRERR with two parameters to retrieve the complete error code first parameter and its associated text second parameter Then we use the UNSTRING verb to separate the code into its parts DATA DIVISION working storage section 01 file status pic xXx 01 error status 03 primary error pic x 2 03 extended error pic x 40 01 secondary error pic x 10 01 isam error pic x 40 01 error text pic x 40 PROCEDURE DIVISION get file err call CSRERR using error status error text unstring extended error delimited by into secondary error isam error display FILE ERROR primary error display DATABASE ERROR secondary error display ISAM ERROR isam error display error text accept omitted stop run Here s an example of the output you might get from this FILE ERROR 9D DATAB
22. Configured login If you want to specify a database login name other than the system login name you can use configured login The SQL command syntax to enroll a new user by configured login is GRANT CONNECT RESOURCE TO db_login_name IDENTIFIED BY password db_login_name is the name you want to use to log in to the database For more details on login see your site s system administrator and the Oracle Database Administrator s Guide C 2 6 Setting Up the User Environment The user s account should have been set up correctly to access the Oracle RDBMS system This includes environment variables such as ORACLE_HOME and ORACLE_SID See your Oracle documentation for more details In addition to the variables required for Oracle you must do the following Ensure that your execution path contains the name of the directory where you placed your newly linked Acu4GL runtime executable If you are not using the automatic login procedure you will need to set the ORA_LOGIN ORA_PASSWD and possibly A_LORA_DATABASE variables either in your environment or in the ACUCOBOL GT runtime configuration file For security reasons it is best to set the password variable from your COBOL program by asking the user to enter a password and then executing SET ENVIRONMENT ORA_PASSWD TO user entry You may want to make and use a personalized copy of the configuration file to avoid impacting other users The ACUCOBOL GT User s Guide describes how
23. For this reason the Acu4GL for Sybase product implements its own locking method This is accomplished with the addition of two tables to a database You choose which database will hold these tables during installation of the Acu4GL for Sybase product Before using the locking tables you need to execute the included syb_inst sql script See the installation instructions you used from this manual for the exact procedure If you don t perform this step the first time you try to execute a COBOL program that opens a Sybase table you receive error 9D 11 ACUCOBOL Lock Table Incorrect E 44 m Acu4GL for Sybase Information The first locking table is called AcuLocks it holds the record locks The columns in this table are the DBID the Table ID the Process ID of the process holding the lock and the primary key of the record that is locked There is a unique index on the DBID the Table ID and the Key Value so that inserts into this table are automatically rejected if another user holds a lock on the row in question This also provides the Database Administrator the information needed to determine who has locks set and whether the user in question still has a connection to the server The second locking table is called AcuOpenTables it holds information about open tables The columns in this table are e the DBID e the Table ID e the process ID PID of the process that has the table open e the open mode input output I
24. If you use relative sequential or XML data files use the Fa option instead Use the Fo option to specify the directory in which the data dictionaries should be placed This option tells the compiler to build Version 4 data dictionaries XFD files for every indexed data file in the FDs of the program This older version of the XFD files is compatible with Acu4GL Version 5 x and earlier To build Version 4 XFDs for every indexed relative and sequential data file in your FDs combine F4 with Fa as in ccbl F4 Fa See section 8 2 for a description of runtime options 8 2 Runtime Configuration Variables There are several variables that can be set in your runtime configuration file that affect Acu4GL processing Those listed below are applicable to any RDBMS with which Acu4GL communicates Some configuration variables are database specific those variables are discussed in the individual database product sections found in this User s Guide Runtime Configuration Variables m 8 5 Note Most configuration variables can be read with the ACCEPT FROM ENVIRONMENT verb If the variable to be read is numeric the receiving field must be defined either as a numeric field or as an alphanumeric field of five or more characters If it is defined as alphanumeric and is longer than five characters the value that is read from the environment will occupy the leftmost five characters of the field and the rem
25. Now enter the following command make f Makefile inf or makerun A 6 m Acu4GL for Informix Information This compiles sub c and filetbl c and then links the runtime system 2d Verify the link 1 Enter the following command runcbl vv 2 Check to see that the version of the Informix Acu4GL is reported to your screen This will verify that the link was successful 3 If no Acu4GL version number is displayed this means that something isn t set up properly a Check filetbl c to make sure that USE_INFORMIX is set to 1 Step 2b b Then check Makefile for accuracy see Step 2c and relink Step 2d Shared libraries If you have relinked the ACUCOBOL GT runtime and receive an error message of this type when you try to execute it Could not load library no such file or directory Can t open shared library this may mean that your operating system is using shared libraries and cannot find them This can occur even if the shared libraries reside in the same directory in which you are currently located Different versions of the UNIX operating system resolve this issue in different ways so it is important that you consult your UNIX documentation to resolve this error Some versions of UNIX require that you set an environment variable that points to shared libraries on your system For example on an IBM RS 6000 running AIX 4 1 the environment variable LIBPATH must point to the direc
26. RDBMSs Previously accessing a relational database from a COBOL program involved writing SQL code and embedding that code in your program You had to know SQL and you had to write SQL statements appropriate for the specific database you wanted to access Because your queries were tailored to suit one database management system you had to recode your COBOL application if you wanted to access a different RDBMS or an indexed file system or even to migrate a file from one system to another As an alternative some interface products now translate COBOL I O statements into direct reads and writes on the database files without going through the driver or engine supplied by the database manufacturer This means that the COBOL programmer must provide for enforcement of database rules that the engine already knows about and is designed to handle Bypassing the database engine also means that new constraints or changes in the database structure will require reprogramming of the COBOL application How Acu4GL Works m 1 11 Acu4GL implements a more suitable approach by dynamically generating industry standard SQL from COBOL I O statements As the ACUCOBOL GT runtime module is executing your COBOL application Acu4GL is running behind the scenes to match up the requirements and rules of both COBOL and the RDBMS to accomplish the task set by your application This means that Acu4GL uses the full power designed into the database engine The engine e
27. Runtime Configuration Variables m 8 15 Example For example if the file CUSTFILE were the only file you wanted to assign to the Vision file system and all other files were to be Informix files you could specify DEFAULT_HOST INFORMIX CUSTFILE_HOST VISION in the configuration file Other possible values for filename_HOST include e ORACLE e MSSQL e ODBC e DB2 e SYBASE e EXTFH See also The DEFAULT_HOST variable which specifies the file system to be used for all files not specified by filename_HOST You can use DEFAULT_HOST and filename_HOST in combination to assign your new files in a default with exceptions manner For example the following directives DEFAULT_HOST VISION afile_HOST ORACLE bfile_HOST ORACLE mean that all new files except afile and bfile will be assigned to Vision and those two files will be assigned to Oracle Now suppose myfilela and myfile1b both reside in mydb1 and myfile2a and myfile2b both reside in mydb2 With the following directives DEFAULT_HOST VISION a mssql database mydbl 8 16 m Compiler and Runtime Options myfilela HOST mssql myfilelb HOST mssql myfile2a mydb2 dbo myfile2a myfile2b mydb2 dbo myfile2b mydb2 HOST mssql the runtime will use the SQL Server interface for myfilela myfile1b myfile2a and myfile2b and will find all the tables in the correct database When the COBOL program opens myfile2a the runtime translates that name to
28. Symbols directive syntax 4 3 Numerics 4GL_2000_CUTOFF configuration variable 8 5 4GL_8_DIGIT_CUTOFF configuration variable 8 5 4GL_COLUMN_CASE configuration variable 8 6 4GL_COMMIT_COUNT configuration variable 8 6 4GL_CONVERT_DATE_ZERO configuration variable 8 8 4GL_DB_MAP configuration variable 8 8 8 13 4GL_EXTRA_DB_COLS_OK configuration variable 8 9 4GL_FULL_DATA_TEST configuration variable 8 10 4GL_IGNORED_SUFFIX_LIST configuration variable 8 10 4GL_ILLEGAL_DATA configuration variable 5 3 8 11 4GL_JULIAN_BASE_DATE configuration variable 4 10 8 11 4GL_MAX_DATE configuration variable D 18 4GL_MIN_DATE configuration variable D 19 4GL_USEDIR_LEVEL configuration variable 8 9 8 12 4GL_WHERE_CONSTRAINT configuration variable 8 13 A A_DB2_ALTERNATE_COMMIT_LOGIC configuration variable D 19 F 15 A_DB2_CATALOG configuration variable F 15 A_DB2_COMMIT_ON_BEGIN configuration variable F 16 A_DB2_DATASOURCE configuration variable F 16 A_DB2_ERROR_MAP_FILE configuration variable F 17 A_DB2_ISOLATION_LEVEL configuration variable F 19 Index 2 A_DB2_LOCK_METHOD configuration variable F 20 A_DB2_LOGIN configuration variable F 21 A_DB2_PASSWD configuration variable F 22 A_DB2_STRICT_EQUAL configuration variable F 23 A_DB2_TABLE_TYPES configuration variable F 24 A_DB2_USE_CATALOG configuration variable F 24 A_DB2_USE_CHAR_FOR_BINARY configuration variable F 25 A_DB2_USE_SQLCOLUMNS configuration variable F 25 A_DB2_USE_SQLTABL
29. access the file However if you want to access files that are owned by other users on the system and do not have public synonyms you must provide the runtime with information on how to locate these files The USER_PATH configuration variable is used by the runtime to locate files It functions in much the same way as ACUCOBOL GT s FILE_PREFIX variable see Chapter 2 in Book 1 User s Guide of the ACUCOBOL GT compiler documentation The syntax for this variable is USER_PATH userl user2 Installation and Setup m C 19 Where the user argument may either be the name of a user on the system or a period which indicates the files owned by yourself For example if you have the following settings ORA_LOGIN OPSSORACLE ORA_PASSWD DATA_FERIT USER_PATH barbara scott and then attempt to open for I O the file myfile the runtime uses the following search path OPEN I O barbara myfile OPEN I O scott myfile OPEN I O opsSoracle myfile Remember that another option for allowing access to a file to all users on the system is to create a public synonym for the file C 2 9 Handling Transactions Issuing a COMMIT WORK database command terminates a transaction and makes all work permanent and accessible to other users The Acu4GL for Oracle runtime issues this command automatically when no locks are held but you can cause it to happen under other conditions by setting the value of the COMMIT_COUNT confi
30. csse0scessssseessessseeteactneseathas biseusies EE REE E E 8 13 DEFAULT HOS T Siti E E E E E ciel Ais ite eit eee 8 13 filename HOST veseecccvies Sen doc ccssude i rt a r a a a ad anae 8 14 FILE TRACE saia a a amass 8 16 AED DIRECTORY tsa gion a ee n A A IA iene E KE A 8 17 FD MAP A E A tk AAN N NSE 8 17 XFD MAP RESETS veere iest ree sE eara O aE ap SE EE E E 8 18 XFD PRERIX soi a Ae oe eis we ERA ih ce RA ee AU ee 8 18 Chapter 9 Performance and Troubleshooting 9 1 Performance Issues snno res eatr eer EE behest EEEE E EE E TE EE TER EET E ias 9 2 QoL TG eONes oi5s es vaeehivetss enra nine EE EE Seen E oes 9 2 9 12 The WHERE Constraint sisin ierste thsssssetecsscessstagistessschitscescts es soesteseseavssbendescntes 9 7 9 2 Troubleshooting oriei cece slocs sence EEE ee suns TE Eee e RS tens cestoctule ches adedoee ea E EEA 9 11 9 2 L Compiler Errors enini a eai eea E E e ETTE TEE ii 9 12 92 2 Compiler Warn gS sc sisi cei vec bends ees EEEa KE E EEE SE EEE EET EE aS ves 9 14 9 2 3 Retrieving Runtime Errors s ssccscscescsssesssessdbeteoscnssesponsdossansevendessevcsedesboessseeedses 9 15 9 2 3 1 Retrieving messages using the x runtime Option eee cree 9 16 9 2 3 2 Retrieving messages using the debuggel eee eee cee eeeeeeereeeeeeeeeaee 9 17 9 2 3 3 Retrieving messages using CSRERR cecccsesesseeeseeeeeceeeeeeeeseeeeeeeeeeeeees 9 18 Chapter 10 General Questions and Answers LO TV Introduction enea ie acied
31. eee ees cseessececsseeseceeceseeeeeeseeeeecaesesecaeenaeeaees C 9 C 2 4 Checking System Parameters sei e S Es ie E E EES C 14 C 2 5 Setting Up a User Account nerio ieres rer ennei reriur ee irere arearen C 15 Contents vi C 2 6 Setting Up the User Environment 00 0 0 cece eee ceeceeeeeeeeecaeeseecaecsseeseesseeseeeeees C 16 C 2 7 Designating the Host File System 0 cece eseceecesecesceeeeeeseneeseecaeesaecaeesseenees C 17 C 2 8 Setting Up the Search Pathe ees cee ceeceeceseeeeceeeseeceseesaecaecsaeeaeenseeeeeees C 18 C 2 9 Handling Transactions 5 5 05 c0i5 cbseecsteciesscssnecbve eevsesupecechncpsbasbavecbunsesieebovbevavees C 19 C 3 Oracle s Instant Clents ccsscs 5sscescketdassaeccdhsvecteceesesgedssevesdisdaseedstescssessssentses sgteacazesivees C 20 CA Filename Translation 53 205 sos sdecsces ches cases seo ntee esos seecs wt dee chavs eee tee teks EEan C 21 C 5 Configuration File Variables sssrini teits sereins rie er iiaea C 21 A ORA DATABASE e E E EE E E E E E Sheed nee eed C 21 A SORA TINTS E ET C 22 A ORA MAX FIE CURSORS aeiee renner e ennaa ronnen isr erneer Tesi C 22 AORA NLS SORT E E E R EENE ERE C 22 AIORA WAIT LOC ona E ae ies C 23 A ORACLE ERROR FIDE 3 3 55 Acd eorne are eme e de yell EAA Media ana e C 23 COMMIT COUNT ss ionachtie neteteiing ee ais Sis hintaan C 23 ORA LOGIN ienris sunset rot iach guested neue sete igen E E gece E A ENNE C 25 ORA PASS WD rien ETE E alates aati ee EER E C 25 USER
32. guidelines 7 3 overview 7 2 extended error descriptions 1 15 extended file descriptors See XFDs m Index 19 external variables declaring 9 10 F F4 option 3 2 Fa option 3 2 features Informix supported A 19 Oracle supported C 28 field name aliases 3 9 field names identical 3 8 long 3 8 fields key 3 5 mapping 1 11 3 3 names 7 4 fields matching COBOL to database 7 2 numeric to database 7 3 text to database 7 3 FILE directive 3 11 4 12 file input and output 9 3 file options compiler 8 2 directory for data dictionary files 8 3 single locking 8 3 START TRANSACTION implied 8 3 transaction implied 8 4 XFD files building data dictionaries 8 4 creating files 8 2 matching field names 8 2 file systems host designating Index 20 m for DB2 F 11 for Oracle C 17 for SQL Server B 8 for Sybase E 22 indexed 1 6 Informix A 18 file tracing 8 16 FILE_TRACE configuration variable 8 16 filename translation Acu4GL for DB2 F 13 Acu4GL for Informix A 8 Acu4GL for ODBC D 17 D 18 Acu4GL for Oracle C 21 Acu4GL for SQL Server B 10 Acu4GL for Sybase E 24 filename_HOST configuration variable 1 12 1 15 8 14 filenames hyphens in A 8 B 10 C 21 D 17 E 24 F 13 lowercase letters in A 8 B 10 D 17 E 24 F 13 underscores in A 8 B 10 C 21 D 17 E 24 F 13 uppercase letters in C 21 files database existing 7 2 7 3 new 7 2 map creating for DB2 F 17 creating for ODBC D 22 Vision 9 5 XFD 3 2 FILLER definition 3 5
33. meaning that the Acu4GL product will do nothing special to lock your data This does not necessarily mean that your data won t be locked Locking depends mainly on your data source and driver No value simply tells Acu4GL for ODBC not to perform any locking functions Note Please note that we cannot guarantee that setting this variable will have any effect for a particular ODBC driver Locking depends mainly on the data source and the driver You can use this variable to attempt to induce row locking If none of the settings cause any rows to be locked or if the machine hangs please report this behavior to Technical Services SETPOS Specify SETPOS as your lock method to tell Acu4GL for ODBC to perform the following locking sequence When setting up a statement handle for accessing the ODBC data source the Acu4GL product calls a function called SQLSetScrollOptions with values SQL CONCUR LOCK SQL SCROLL KEYSET DRIVER 1 When fetching rows from the data source the Acu4GL product calls SQLExtendedFetch instead of SQLFetch Finally it calls SQLSetPos with the values 1 SQL POSITION SQL LOCK EXCLUSIVE If any of these functions do not exist in the ODBC driver then A_ODBC_LOCK_METHOD reverts to none Note Even if these functions do exist there is no guarantee that any rows will be locked using this sequence of calls Contact your driver vendor to determine whether or not this sequence will be effective for your data
34. shutting down the database for any reason This stored procedure must reside in the same database as the AcuOpenTables and AcuLocks tables it is placed there automatically when these tables are created during installation E 7 Limits and Ranges The following limits exist for the Sybase file system Maximum number of columns per key 16 Maximum number of columns 250 Maximum number of bytes in a single row when using Acu4GL for Sybase 1962 To achieve the same sort or retrieval sequence under Sybase as under the Vision file system key fields that contain signed numeric data must be preceded by a BINARY directive Runtime Errors m E 53 Acu4GL for Sybase supports the data types shown below When it s creating tables the following conversion rules are used in the sequence shown BINARY directive VARBINARY if SIZE lt 255 IMAGE if a gt 255 VAR_LENGTH VARCHAR n if SIZE lt 255 directive Usage FLOAT REAL if SIZE 4 FLOAT if SIZE 8 Any other numeric usage PIC SMALLINT if m 0 and n lt 5 9 n V9 m INT if m 0 and n lt 10 DECIMAL n m m otherwise Any other usage PIC CHAR n if n lt 255 X n TEXT if n gt 255 Other limits are described in Appendix B in Book 4 Appendices of the ACUCOBOL GT compiler manual E 8 Runtime Errors This section lists the Acu4GL error messages that could occur during execution of your program Chapter 9 provides information on com
35. source D 26 m Acu4GL for ODBC Information SETSTMTOPTION Specify SETSTMTOPTION as your lock method for ODBC version 2 0 and later drivers This option is similar to SETPOS except ODBC version 2 defines a new function called SQLSetStmtOption which performs the task of SQLSetScrollOptions but has more functionality In particular when using this method of locking the Acu4GL product will call SQLSetStmtOption a number of times with values SQL CONCURRENCY SQL CONCUR LOCK SQL CURSOR TYPES SQL CURSOR KEYSET DRIVEN and SQL_KEYSET SIZE 1 Again if the function does not exist A_ODBC_LOCK_METHOD reverts to none UPDATECOLUMN Specifying UPDATECOLUMN as your lock method performs an entirely different type of locking Instead of trying to lock a row while reading it this method creates a new statement handle for the data source Then after fetching the data from the data source it resubmits an SQL query to select the same row based on the primary key and adds an UPDATE clause Last it fetches the data from the data source Because this method has the most overhead we don t recommend it for slow drivers such as Microsoft Access although it is much more likely to succeed in locking records A_ODBC_LOGIN A_ODBC_LOGIN indicates the user name under which you want to connect to the database system Not all data sources require a user loginname Those that do may have case requirements Check your data source docume
36. 03 def2 redefines defl pic 9 2 results in this database table col_type defi def2 a Xx lt Null gt b lt Null gt 10 4 3 13 XSL If you are using the Fe compiler option to generate XML style XFD files the XSL directive allows you to include a stylesheet reference in the XML header Syntax SXFD XSL stylesheet or XFD XSL stylesheet where stylesheet is an alphanumeric literal indicating the appropriate stylesheet The compiler includes the following line in all generated XML style XFD files lt xml stylesheet type text xsl href stylesheet gt For example XFD XSL myxsl xsl generates this line lt xml stylesheet type text xsl href myxsl xs1 gt Invalid Data Key Topics Illegal COBOL Data ioia ce ee Mel 5 2 DAE Key Data E bois earastesss neaseeitieepesnetesasheesoceest 5 3 Invalid Data Other Than Keys ccccceccesseeseeeseeseeseeeeeceeeneeseessees 5 3 Invalid Database Data ccc cccecccccccecesssssseccsssssssessessssssessesessesseeses 5 3 5 2 m Invalid Data 5 1 Illegal COBOL Data This chapter lists which COBOL data items are considered invalid and explains what happens to them when they are stored in the database We also explain which database items are considered invalid and explain how these are translated to COBOL COBOL data except key data that is illegal by database standards is stored in the database as null unless
37. 22006 is very important It is the code searched for in setting the error condition from within the Acu4GL product If you use a different number your starts may succeed when they should actually fail For example based on the sample XFD you might want to create the following stored procedure to start a file create procedure ftestdat_start001 mode varchar 2 ft2_keyl_segl char 2 f t2_keyl_seg2 char 2 as if exists select 1 from ftestdat where ftest2_keyl_segl ft2_keyl_segl and mode gt and ftest2_keyl_seg2 gt ft2_keyl_seg2 or mode gt and ftest2_keyl_seg2 gt ft2_keyl_seg2 or mode and ftest2_keyl_seg2 ft2_keyl_seg2 or mode lt and ftest2_keyl_seg2 lt ft2_keyl_seg2 or mode lt and ftest2_keyl_seg2 lt ft2_keyl_seg2 return if exists select 1 from ftestdat where mode gt or mode gt and ftest2_keyl_segl gt ft2_keyl_segl or mode lt or mode lt and ftest2_keyl_segl lt ft2_keyl_seg1 return raiserror 22006 Record not found grant execute on ftestdat_start001 to public Stored Procedures m E 51 E 6 2 Built in Stored Procedures Several stored procedures come with Acu4GL for Sybase One sp_AcuInit provides a means for customized initialization The others return information based on the AcuOpenTables and AcuLocks tables Note You will see tha
38. 3 6 4 21 final name XFDs 3 10 format data conversion 7 2 forming COBOL records 1 13 forming the final XFD name 3 10 m Index 21 Fx option 3 2 G generic file handler 1 6 getting started Acu4GL for DB2 F 6 Acu4GL for Informix A 2 Acu4GL for ODBC D 10 Acu4GL for Oracle C 7 Acu4GL for SQL Server B 4 Acu4GL for Sybase E 3 overview 2 2 group items 3 6 and database table columns 3 3 and DATE directive 4 11 growth planning ahead 9 7 guidelines existing database files 7 3 performance 9 2 H handling invalid dates 4 10 Help menu demonstration program 2 11 HIGH VALUES illegal COBOL data 5 2 Hints Oracle feature C 22 host data source designating for Acu4GL for DB2 F 13 for Acu4GL for ODBC D 16 host file systems designating for Acu4GL for DB2 F 11 for Acu4GL for Oracle C 17 for Acu4GL for SQL Server B 8 Index 22 m for Acu4GL for Sybase E 22 how Acu4GL works COBOL T O translation 1 10 runtime ACUCOBOL GT 1 10 SQL generation 1 10 transparent interface 1 11 hyphens in COBOL code 3 7 in filenames A 8 B 10 C 21 D 17 E 24 F 13 T O requests passing to the interface 1 13 identical field names 3 8 illegal COBOL data BINARY numbers 5 2 COMP 2 numbers 5 2 COMP 3 numbers 5 2 DATE fields 5 2 HIGH VALUES 5 2 LOW VALUES 5 2 other 5 3 SPACES 5 2 TEXT fields 5 2 USAGE DISPLAY numbers 5 2 illegal data testing for 8 10 improving database performance C 22 indexed file systems 1 6 alfred editor 1
39. 3 Sample Configuration File 0 0 eee ee esecseeseecsecsseeseeeeeseeseceeeeeesenessaecaeesaeeaes F 10 F 2 4 Setting Up the User Environment eee eeseeceeeceeceeeeeeeeseeeeeeseesaeceesaeenees F 10 F 2 5 Designating the Host File System 0 0 eee eeeeeceeceeeceeeeeeeeaeeseecaeesaecaeenaeenees F 11 F 2 6 Designating the Host Data Source eee ce seeeeceeceeeceeeeeeeeaeeseecseesaecseenseenees F 13 F 3 Filename Translatione s s c sisi sisttsses erni peer rE EEE E E o EE ane F 13 F4 Decimal Points oinn e a ae ee F 14 F gt Configuration File V aria Des seose sessnccsehed steed sas sussveceusdvseser sey eip EERS E A EEE F 14 A_DB2_ALTERNATE_ COMMIT LOGIC cece ceseeeeceeeeeeeeeeeseeeaeseesaeenaes F 14 A DBZ CATALOG E e ar eE E Biase deste Ges thea does See Sued EEE F 15 A_DB2_COMMIT_ON_BEGIN ener a eaa e oE E R AE S F 16 A PB DATASOURCE 455 200 aro a AERE r E E E EE EE R E E ees F 16 A DB2 ERROR MAP PILE rrr e rra arero sasa eaeoe aeae asepe aE Er ao E Eoi F 17 A DB2 ISOLATION LEVE wesc coscessees seis Geseesves lige cus con btacotens leckseb A tveceueh hseniessicetvncns F 19 A DB2 LOCK METHOD nro ornare e denis ca renee Ter Er So e ii F 20 A PBZ LOGIN a e a e E E EE E I E E EE F 21 7 D12 PASSWD D E S EERE F 22 A DBZ STRICT EQUA Eee a E E R E Seapets RA F 23 A DBZ TABLE TYPES reene ra E EE E E A E E R EE EE F 24 A DB2 USE CATALOG a r E R R A RR AE ce F 24 Contents x A_DB2_USE_CHAR_FOR_BINARY 00 ec ceceeceseeeeecseesaecaeceaec
40. 4 18 43 11 VAR LENGTH ohe i onesie oeoa ih tiie eterno tone 4 20 4 3 12 WHEN 2eissscissseiseeiicses sie ara a E E ES EEES ES E ees 4 20 43 13 XSD E E EEE E EE E EE iin Mei 4 26 Chapter 5 Invalid Data 3 1 Megal COBOL Data iiron ioneina ie eee rE E E E E E AE E E dette es 5 2 5 1 1 Invalid Key Data s scisccssssssssecdasecssssenssteciectskesteougsieeesigeteseadessasesebscenescessssacesssesatee 5 3 5 1 2 Invalid Data Other Than Keys oo cece ceceecseceseeseceeceeceseeseseeeeseseneeseesaecsessaeenees 5 3 5 2 Invalid Database Data is c3scessepcscciseessssevieoes re eoten reer ae hee E EE SEEE E E EE 5 3 Chapter 6 Working with COBOL 6 1 Preparing and Compiling Your COBOL Program s eessesessesessessererssrerrsrererrrerereerrerssees 6 2 6 1 1 Compiling With No Directives essesseesesseeesesresesrssesresrerrsreererrnresreesrssersseeersrene 6 4 6 1 2 Compiling With the WHEN Directive sseessseeeseseseesreerereersrreresresesrsserrrsrerrsreee 6 6 6 1 3 Using Additional Directives 0 eee ee eeeeseeseeeseceeceseceeceseeseceeeeseeeaseseesaesassaeenees 6 8 6 2 Creating File Descriptors and SELECT Statements 00 0 eee eeeeeeeeeeeesecneeeneenees 6 10 Chapter 7 New and Existing Databases TA Databases s 28 cess tk os ia E ee ee A MWR MAIS E 7 2 7 2 Default ACU4GL Behavior ssori ions aee aa e eea r E 7 2 7 3 Accessing Existing Database Files oe ec eeeeeeeseeeeeescesaeceeeeaececeseceseeseeeeeeeeeeeeens 7 3 7 3 1 How Do I Match
41. A 8 Runtime Erots noenee i Sane eee E EERE E RR EE E eee A 9 Common Questions and AMSWETS c ccccescecsesseeceseecesseceseeaeceseeeeessueecseaeeeseeeeenes Appendix B Acu4GL for Microsoft SQL Server Information B 1 Microsoft SQL Server Concepts OvervieW e esessseessssreresessrsreserrrsrrrrsreersseer B 2 Installation and Setup s seseseeeseseeesseeeseresseerereersressesrsertsserresrnsestesertesrerrnreeesrenre B 2 1 Installing on a Client Machine essssseeseseeeesseeseseesrsrrsreerssrsresrsresreserrrsreees B 2 2 Setting Up a User Account eseseeeeseeeeseeresrsresesesserresrerrsresrsresrerrereeessrets B 2 3 Setting Up the User Environment esesesseseeesssseersseesrsreserresrerrsreererrereses B 2 4 Designating the Host File System ssseseseesseeessseesssrsseereseerssrereseeresrrseeees B 3 Filename Translation eee niee nesto ree soen ea e eose E TE Ee e EE B 4 Configuration File Variables 0 0 0 0 ce eee eceeeeceeececeeceeessecssesaececeseeseseeeeeeseeeens AW MSSQL_ ADD IDENTITY preiero irer ces teen a a E E E oven os A_MSSQL_ADD_TIMESTAMD 0 cssscessscesscseesevnsssonssseasessnscceecostesscescbeveossess A_MSSQL_APPROLE_ NAME cniri cirese erei orre eeen veera tirri estes A MSSQL APPROLE PASS WD isene a e E E ER E A_MSSQL_CURSOR_OPTION_1 A _MSSQL_CURSOR_OPTION_2 AZMSSOL CURSOR OPTION 3 reren ten nea R T a i A MSSOL DATABASE ea a E E is A MSSQL DEADLOCK LOOPS eet reeter ora pe E Ee E
42. A_ODBC_UNSIGNED_TINYINT to a nonzero value As a result PIC s99 variables are stored in a larger type usually INT that allows negative values While the default value is 0 off false no this configuration variable can also take values of On true yes A_ODBC_USE_CATALOG Not all data sources will support a catalog or the data sources may return a catalog name that is not useful For example Microsoft Access returns the full path to the database which is not needed since this information is detailed in the datasource The default behavior of the runtime is to not use the catalog in the actual SQL queries This configuration variable enables you to modify this behavior Configuration File Variables m D 31 The default value is FALSE which will cause the catalog portion of the table name to be treated as blank in SQL queries Setting this variable to TRUE will cause the value of the catalog returned by SQLTables ODBC function to be used in subsequent SQL queries See also USER_PATH configuration variable A_ODBC_CATALOG configuration variable A_ODBC_USE_CHAR_FOR_BINARY Some data sources have restrictions on the number of binary large objects BLOBs that can be placed into a single table If your data source has such restrictions specify A_LODBC_USE_CHAR_FOR_BINARY in the configuration file The possible values for this variable are 0 use BINARY type 1 use CHAR type If A_LODBC_USE_CHAR_F
43. Acu4GL for DB2 Information Acu4GL for DB2 translates the name to uppercase letters and changes hyphens to underscores File extensions will be stripped based on the setting of 4GL_IGNORED_ SUFFIX LIST This new name is the one that Acu4GL for DB2 will use in the future for references to database tables F 4 Decimal Points Acu4GL for DB2 reads the decimal point character from the environment variable DECIMAL_ POINT If DECIMAL_ POINT is set Acu4GL uses that character If the variable is not set Acu4GL uses the decimal character that is encoded in the XFD file The two most common decimal indicators are the period and the comma e6 399 gt characters The comma is used often in European code and is often indicated in COBOL programs by the DECIMAL POINT IS COMMA clause F 5 Configuration File Variables This section lists the runtime configuration file variables that are specific to Acu4GL for DB2 Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are discussed in section 8 2 Runtime Configuration Variables A_DB2_CATALOG A_DB2_TABLE_TYPES A_DB2_USE_CATALOG USER_PATH A_DB2_ALTERNATE_COMMIT_LOGIC The primary purpose of the configuration variable 4GL_COMMIT_COUNT is to provide for applications that must communicate with a transaction oriented database but have not explicitly coded transactions into their COBOL application Configuration File Vari
44. Any other usage PIC X n CHAR n if n lt 255 TEXT if n gt 255 Other limits are described in Appendix B in Book 4 Appendices of the ACUCOBOL GT documentation set B 9 Runtime Errors This section lists the Acu4GL error messages that could occur during execution of your program Chapter 9 provides information on compile time errors and also provides several methods for retrieving runtime errors Each message is followed by an explanation and a recommended recovery procedure Runtime errors will have this format 9D xx The 9D indicates a file system error and is reported in your FILE STATUS variable The xx is a secondary error code These are the secondary errors reported directly from Acu4GL 9D 01 Read error on dictionary file An error occurred while reading the XFD file this probably means the XFD is corrupt Recreate the XFD file 9D 02 Corrupt dictionary file The dictionary file for one of your COBOL files is corrupt and cannot be read Recompile with the Fx option to re create the dictionary See section 8 1 for information on compiler options B 40 m Acu4GL for Microsoft SQL Server Information 9D 03 Dictionary xfd file not found The dictionary file for one of your COBOL files cannot be located Be sure you have specified the correct directory via your XFD_PREFIX runtime configuration file variable You may need to recompile with the Fx option to create the dictionary 9D 04 Too
45. Ath O EE A ieee 1 6 13 VInterface ROUNES os sis ssceeseicesaeas sad sone cask soup taa R E N 1 7 1 3 2 Data Dictionaries and ACU4GL oe eeeeeseceececeeceseceececaeeeneeeeneesaeeeneeceneeeeeeeeeens 1 8 1 3 3 The ACUCOBOL GT Web Runtime and Acu4GL o oo ee cececeeeeeeeeeeeeeeseeeee 1 8 1 4 Database Concepts 4 isoaie aie el aie hei Glen aS eee aie ant 1 9 VS How ACUA GI WOKS oa oein a a E Becca cg A a A gvesceeubans 1 10 1 5 1 What Is a Transparent Interface oo eee ceeceseeeeceeeeeeeeeeeeeceaeeaeecaeesaenaees 1 11 1 5 2 Data Dictionaries and Mapping c ee eeeceeeeeecseeeseceeseeseceseeeeeeeeeseeseseesaesaes 1 11 15 3 Steps to Follows she sete eS hae Ui a BG ee eee 1 12 1 5 4 SUMMARY ei ie rieo iat e rE E EE diaeen ch eee Meee Ate et 1 14 Chapter 2 Getting Started Del Getting Started Saresp ee eere eee aee o e i ai Ess espe eors 2 2 2 2 Technic l Servi eS iie ieies isene reap aar ioi oa aa aE E a SEn Toe SORE koa inspek ai 2 2 23 Jpstalla onie neers siio soe aE in ones nin baa Naat ER 2 2 2 4 Using the sql act Program siiip teria esa e eE ei teens E repr asas 2 3 2 4 1 Running sql acu From the Command Line eee ceseeeeceseeeeeeeeeeeeeeeens 2 3 2 4 2 To Call sql acu From a Program eee eceeeeeceseesseceeeaecneceseesecesceseeeeeeaeeeaeeas 2 4 2 5 The Demonstration Program eee escesecseceseeseceseesecesceseeeeeeseeseecaeesaecaecsaecseceseeeensens 2 6 Chapter 3 Data Dictionaries 3 1 Data Dictionaries
46. COBOL data processing is based on keyed READ operations following a positioning operation Records are read until the key value being processed changes Because traditional COBOL data processing is based on a B tree file system the overhead for such operations is relatively minor 9 8 m Performance and Troubleshooting RDBMS data processing introduces a new level of complexity to data processing The database s query optimizer receives the SQL query for the COBOL operation being performed and then builds a working set of data that satisfies that query Because the database optimizer has many different possible execution methods this can result in poor performance if the optimizer chooses a query execution path that is less than optimal Performance degradation may also result from the fact that queries generated by COBOL operations result in unbounded index queries Unbounded queries are generated because COBOL positioning operations Start Not Less Than and Start Not Greater Than provide only one of the bounding conditions for the working set instead of both an upper and lower boundary As an example consider the case where an application needs to process all items in a warehouse on aisle 17 shelf 8 and bin 2 If each of these items is a field in a key the COBOL program might generate the following query for a READ operation Note The following example applies to the Acu4GL for Oracle product The SQL generated will be different
47. FIEST2 KEY1 SEG2 00008 00004 16 00004 00 000 000 FTEST2 ALTKEY2 00012 00009 00 00009 00 000 000 FTEST2 NUMBER 00021 00010 16 00010 00 000 000 FTEST2 INFO Stored Procedures m B 33 tablename_insert tablename_insett is used to WRITE a record to the file The parameters passed to the stored procedure are the values of all the columns in the row in the order of the columns in the database The timestamp column and identity column if present in the table are not passed to the stored procedure Given the XFD above you might want to create the following stored procedure for writing records to a file create procedure ftestdat_insert ft2_key char 4 f t2_keyl_segl char 2 ft2_keyl_seg2 char 2 ft2_altkey2 char 4 ft2_number char 9 ft2_info char 10 as insert into ftestdat ftest2_key ftest2_keyl_segl ftest2_keyl_seg2 ftest2_altkey2 ftest2_number ftest2_info values ft2_key ft2_keyl_segl f t2_keyl_seg2 ft2_altkey2 ft2_number ft2_info grant execute on ftestdat_insert to public tablename_delete tablename_delete is used to DELETE a record from the file The parameters passed to the stored procedure are the values of the primary key in the order they are listed in the XFD Based on the sample XFD you might want to create the following stored procedure for deleting records from a file create procedure ftestdat_delete f t2_key char 4 as del
48. File Description based on an existing data source table The most important thing to understand in this situation is that there is almost nothing that you can do wrong When the Acu4GL product opens a data source table the only thing it checks is that the column names match the COBOL data names Data Type Mapping m D 41 When the Acu4GL product reads data from the data source it essentially does a COBOL style MOVE from the native data type to the COBOL data type whatever it is And since most types have a CHAR representation in other words you can actually display most data types using a standard ODBC capable tool using PIC X nn for each column will work perfectly well A better general rule is to use a COBOL type that closely matches the data source data type but don t worry about getting an exact fit So you can use PIC 9 9 whenever the data source has an INTEGER type If you have more information about the data source type you might be able to use a different COBOL representation For example if you know that a particular column in an ODBC data source has values only in the range 0 999 you could use PIC 999 for your COBOL data The COMP type you use is really determined by your own preferences and should have little bearing on the COBOL data type you choose If you want to somehow choose your COBOL data types so that there is a best fit you can use the following mapping SQL_CHAR PIC X nn nn size of it
49. LOWER which means that field names are converted to lower case and hyphens are converted to underscores If this variable is set to Unchanged all field names are used unchanged when the database table is created Be aware that hyphens are not converted to underscores in this situation Most databases do not accept hyphens in column names so the XFD must be modified by hand to replace hyphens with underscores AGL_COMMIT_COUNT The value of 4GL_COMMIT_COUNT indicates the conditions under which you want to issue an automatic COMMIT WORK operation Valid values are 4GL_COMMIT_COUNT 0 Default When you set this variable to zero the runtime tracks the number of logical locks that are currently in effect When the number of logical locks reaches zero the runtime assumes that a transaction is complete and issues a COMMIT statement 4GL_COMMIT_COUNT n When you set this variable to a nonzero value the runtime tracks the number of WRITE REWRITE and DELETE operations until the value of 4GL_COMMIT_COUNT is reached at which time the runtime issues a COMMIT statement The READ START and READ NEXT operations do not count toward this total because the runtime is tracking data altering Runtime Configuration Variables m 8 7 operations rather than logical record locks The disadvantage of this method is that when a COMMIT is issued any record locks held by the runtime are released 4GL_COMMIT_COUNT 1 No com
50. Microsoft SQL Server Information sp_AcuZeroUserCount_1 Use sp_AcuZeroUserCount to remove all locks on a table and close it Be sure to run this stored procedure on all tables in the database if you will be shutting down the database for any reason This stored procedure must reside in the same database as the AcuOpenTables and AcuLocks tables it is placed there automatically when these tables are created during installation B 8 Limits and Ranges The following limits exist for the Microsoft SQL Server file system Maximum number of columns perkey 16 Maximum number of columns 250 Maximum number of bytes in a single row when using Acu4GL for Microsoft SQL Server 1962 To achieve the same sort or retrieval sequence under Microsoft SQL Server as under the Vision file system key fields that contain signed numeric data must be preceded by a BINARY directive Acu4GL for Microsoft SQL Server supports the data types shown below when it s creating tables the following conversion rules are used in the sequence shown COBOL SQL Server DATE directive DATETIME BINARY directive VARBINARY n if SIZE lt 255 IMAGE if SIZE gt 255 VAR_LENGTH VARCHAR n if SIZE lt 255 directive Usage FLOAT REAL if SIZE 4 Usage DOUBLE FLOAT if SIZE 8 Runtime Errors m B 39 Any other numeric usage PIC SMALLINT if m 0 and n lt 5 9 n V9 m INT if m 0 and n lt 10 DECIMAL n m m otherwise
51. O or extend e whether multiple records can be locked e whether the file can be open for I O by any other users e whether the file can be open at all by any other users e whether Mass Update was specified in the open There are no indices on this table but there is a trigger which automatically rejects opens that are not allowed based on other users open modes By using these lock tables the Acu4GL for Sybase product is able to support all the types of locking ordinarily supported by ACUCOBOL GT No special runtime configuration variables are required This method of locking is all that is needed if no applications other than COBOL programs are going to be using the Acu4GL for Sybase product But if your site has other applications that access the Sybase databases you must use a method of locking that is inherent to Sybase Stored Procedures m E 45 The only method of locking that Sybase supports internally is the result of time stamping and the use of BROWSE MODE see the discussion of BROWSE MODE in the Sybase Commands Reference Manual If a table has a time stamp column the Acu4GL for Sybase product uses browse mode This allows the server to detect whether another application has modified a record while an ACUCOBOL GT application has had it locked E 6 Stored Procedures A stored procedure is a collection of SQL statements residing on the server stored as text in a table in the database Stored procedures provide an e
52. Or XFDS enne otin nees Ees iE EEEa SEEGE EE E EEEE 3 2 32 XD Files ies eare ore poean paenan ea e E EEE E SEAN S E AE E EEE S ESEE E 3 2 3 2 1 Understanding How the Database Table Is Formed ssseeseseeseesressererrerereesreees 3 3 3 2 2 Detaults Used m XED Files ironii o E ERE EE EE EEE 3 5 3 2 3 Summary of Dictionary Fields eeeseeeeseeeseessseessseeeseeresrsserrssreesresrsreneerenreresreee 3 7 3 24 1dentical Field Name Si onnon one e aati A 3 8 3 2 3 Long Field N m e Ssnin opr E E ER E A E E E eiS 3 8 3 2 6 Naming the XED Pile wsie area Senn cocks ae eiea eeke cbsncuscns intessenscbesced 3 9 Contents ii Chapter 4 Using Directives 4 1 What Are Directives seareiro eonen dence tude Goanaved Steep Buds EEE E EEES OE OSEE oes 4 2 4 2 Directive Syntax eeto aer EEE EE E oa ohne sages Roche eee Lae ee anata 4 3 4 3 Directives Supported by the Acu4GL Interfaces oe eeceeceseeseceseeeeceeeeeeeeeeeeeeeeeens 4 4 AS aN D d n Va EEE ATSE Shesott sh sngetaesveesiaean ss ETE 4 5 4 3 22BINARY oti araa r a E pee iia Re en ee eee as 4 6 4 3 3 COBOL TRIGGER oriire aenor ese E EE A A A Uae tensed oes aoa E eels 4 7 43 4 COMM N a A RE a RA IA S 4 8 ASD DATES e A e Eee EKERN a EE E EE e r EEO SEE EEEa 4 9 436 FEE ese stents E Ghee a E E Re E 4 12 4 3 T NAME e n E R R E E S 4 13 4 3 8 NUMERI G ete a reo r aa a ESE r E r E EE EE EE as To 4 16 4 3 9 SECONDARY TABLE neeaaeieo oreesa onee EEEE ives E A EE ES EEY 4 17 4 3 10 USE GROUP E EET
53. START KEY EQUAL keyval the interface generates a SELECT statement to select all rows with a key equal to the key columns in keyval When fetching the data Acu4GL eventually detects that there is no more data If A ODBC_STRICT_EQUAL is set to True at the time the START is executed the interface returns the error END OF FILE error 10 at this point If ALODBC_STRICT_EQUAL is set to False the default Acu4GL for ODBC then generates a new SELECT Configuration File Variables m D 29 statement to continue reading records until the end of the file rather than the subset of records represented by keyval and these records may be discarded by the program Note that this is program dependent behavior Setting A_ODBC_STRICT_EQUAL to True causes the interface to stop reading records earlier which can make SELECT statements generated by Acu4GL for ODBC more efficient Note the following conditions e A _ODBC_STRICT_EQUAL must be set to True when the START is executed e The START must be a KEY EQUAL start e There must be no COMMITs between the START and the end of the file Because most ODBC drivers close all cursors on COMMIT and ROLLBACK according to the ANSI 92 SQL standard the interface must regenerate a SELECT the first time it attempts to execute a READ NEXT after a COMMIT or ROLLBACK For most drivers this means that the 4GL_COMMIT_COUNT configuration variable should be set to 1 so that no COMM
54. Suppose that you wanted both record formats to be placed into the table This might be the case if you intended to do any work within your RDBMS Add the WHEN directive in front of each record as shown below see Chapter 4 Using Directives The underlined fields are the ones that will be entered into the table fd p o file xfd when p o record type h 01 p o record 03 p o division number 03 p o record type 88 header record 88 detail record 03 p o number 03 p o number detail redefines p o number 05 picking ticket number 05 shipping region 05 p o customer type pic 9 3 pic x value h value q pic 9 10 pic 9 6 pic 92 pic 9 2 Preparing and Compiling Your COBOL Program m 6 7 05 p o customer breakdown redefines p o customer type 07 customer category pic x 88 p o customer retail value r 88 p o customer whlsale value w 07 customer pay format pic x 88 is net 30 value 3 88 is net 10 value 1 03 p o date 05 p o yy pic 9 2 05 p o mm pic 9 2 05 p o dd pic 9 2 xfd when p o record type d 01 p o detail record 03 p o dept number pic 9 3 03 p o record type pic x 03 detail p o number pic 9 10 03 p o shipping info 05 p o quantity to ship pic s9 4 comp 05 p o total quantity pic s9 4 comp 03 p o notes 05 notes line occurs 3 times pic x 40 Note p o record type is entered into the table only once The detail p o number field is not
55. Sybase E 51 sp_AcuTableReport_1 procedure SQL Server B 37 Sybase E 52 sp_AcuUserCount_1 procedure SQL Server B 37 Sybase E 52 sp_AcuZeroUserCount procedure SQL Server B 38 Sybase E 52 SPACES illegal COBOL data 5 2 SQL errors ODBC D 44 SQL generation 1 10 SQL Server configuration variables list of 4GL_IGNORED_SUFFIX_LIST 8 10 A_MSSQL_ADD_IDENTITY B 11 A_MSSQL_ADD_TIMESTAMP B 11 A_MSSQL_APPROLE NAME B 12 A_MSSQL_APPROLE PASSWD B 12 A_MSSQL_AUTHENTICATION B 22 A_MSSQL_CURSOR_OPTION B 13 A_MSSQL_DATABASE B 14 A_MSSQL_DEADLOCK_LOOPS B 14 A_MSSQL_DEFAULT_CONNECTION B 15 MSSQL_FAST_ACCESS B 16 MSSQL_LOCK_DB B 17 _MSSQL_LOGIN B 18 _MSSQL_MAX_ CHARACTERS B 18 _MSSQL_MAX_COLUMNS B 19 _MSSQL_NATIVE_LOCK_TIMEOUT B 19 A_MSSQL_NO_23_ON_START B 21 A_MSSQL_NO_COUNT_CHECK B 20 A_MSSQL_NO_DBID B 21 A_MSSQL_NO_RECORD_LOCKS B 21 A_MSSQL_NO_TABLE LOCKS B 21 ot a a a m Index 37 _MSSQL_PACKETSIZE B 22 _MSSQL_PASSWD B 23 _MSSQL_ROWCOUNT B 24 _MSSQL_SELECT_KEY_ONLY B 24 _MSSQL_SKIP_ALTERNATE_KEYS B 25 _MSSQL_TRANSLATE_TO_ANSI B 25 _MSSQL_UNLOCK_ON_EXECUTE B 25 A_MSSQL_USE_DROPDOWN_QUERIES B 26 A_MSSQL_VISION_LOCKS_FILE B 27 SQL Server configuration variables overview B 11 SQL Server Acu4GL configuration variables B 11 database table B 28 designating host file system B 8 PDPPP getting started B 4 installation B 4 client B 7 on client B 5 Windows NT server B 5 limits and ranges B 38 overview B 2 run
56. This product is not provided by Micro Focus but probably was installed along with any ODBC drivers or data sources that you have on your system For example if you have installed Microsoft Access on your computer the Access drivers and ODBC may have been automatically installed Follow these steps to determine whether you already have ODBC 1 Open the Windows control panel Acu4GL for ODBC Installation and Setup m D 11 2 On Windows XP and newer versions of Windows double click the Administrative Tools icon then select Data Sources ODBC On older versions of Windows select the 32 bit ODBC icon directly from the control panel noai fouls File Edit View Favorites Tools Help Qa O P Psh f Folders Fy Address Ea Administrative Tools on a A we Component Services Computer Management File and Folder Tasks D Shortcut Shortcut ces ODBC 2KB i Rename this file BR Move this file z D Copy this file z Publish this file to the a Web Local Security Policy Performance E mail this file Shortcut Shortcut 2 KB 2KB XK Delete this file Services Shortcut Other Places 2KB Br Control Panel My Documents Shared Documents E My Computer K My Network Places Details Data Sources ODBC Shortcut Attributes Compressed Date Modified Today January 20 2006 10 22 AM 3 Double clicking the ODBC icon brings up the ODBC Data Source Administrator dialog showing all t
57. You accomplish this with one of two runtime configuration file variables or DEFAULT_HOST filesystem filename_HOST filesystem DEFAULT_HOST Use the DEFAULT_HOST variable to designate the file system to be used for newly created files that are not individually assigned For example Installation and Setup m B 9 DEFAULT_HOST MSSQL means that all new files will be Microsoft SQL Server tables unless otherwise specified by the second configuration variable filename_HOST filename_HOST Use the filename_HOST variable to assign an individual data file to a file system Any file so assigned will use the designated file system and not the one specified by DEFAULT_HOST The syntax is filename_HOST filesystem where filename is the file name without any extension named in the ASSIGN TO clause of your SELECT statement For example myfile_HOST VISION means that my file will be under the Vision file system You can use these runtime configuration file variables in combination to assign your new files in a default with exceptions manner for example this set of entries DEFAULT_HOST VISION afile_HOST MSSQL bfile_HOST MSSQL means that all new files except afile and bfile will be assigned to Vision and those two files will be assigned to Microsoft SQL Server You can also change the values of these variables during program execution by including in your code SET ENVIRONMENT filename_HOST TO filesyste
58. a file for output I get the error 9D 904 Invalid Column Name Why One of your record s data items probably has the same name as an Oracle reserved word Locate the column by comparing a file trace of the CREATE TABLE to Oracle s list of reserved words and then apply the NAME directive to the column in question I created a table the last time I ran the application and now I can t find it Why This is probably a file table ownership problem If you were running the application under a different user name when you created the file that table may not be visible unless the creating user s name is listed in your USER_PATH configuration variable Can the Acu4GL for Oracle product support a full date time format The finest time granularity that Oracle supports is one second Fractions of a second are not supported In order to achieve this you must be sure the xfd date code is correct and specify a date time string in your COBOL application as opposed to just a date See section 4 3 5 DATE for additional information Are there any ACUCOBOL GT library routines that do not work with or would not make sense to use with Acu4GL for Oracle Yes There are two ACUCOBOL GT library routines that either don t work with or do not make sense to use with Acu4GL for Oracle C COPY and C RECOVER Acu4GL for ODBC Information Key Topics ODBC COntepts rreson core hii sade wish deeb dade aden teete
59. a unique index and uses that index as the primary key Upon request acu4glfd generates two kinds of output e a file descriptor FD listing the names of the columns in a table and their associated data types e a SELECT statement for the file You can COPY the FD and SELECT statement into your COBOL program although you may need to make some changes as indicated in this section The acud4glfd utility is intended to help you jump start preparing your table for use with a COBOL program The program determines the names of the columns attempts to determine the appropriate ACUCOBOL GT data type for the column and attempts to determine the primary key acu4glfd does not attempt to identify alternate keys Remember though that database data is flat and COBOL data can contain group items and depth Because table data does not contain information about GROUP structure the way a COBOL program does it may be necessary for you to tweak the code produced by acu4glfd and specify a picture before the program compiles properly Any errors produced in this early compilation will assist in fine tuning the FD for your COBOL program This saves the time and effort of completely analyzing the table and coding the FD and SELECT statements yourself The acu4glfd utility operates only on data types that are understood by ODBC Database drivers can define their own data types as well these driver defined data types are not recognized by acu4glfd The
60. and Setup 00 0 0 cece cseeseeseceeeeceeceaecesseceeeneeseeerenecneeaees F 6 Filename Translation 2 00 00 eseeeesecsseseeseesecsecetesceaeceseeceeenaeeeerenes F 13 Decimal Pomte si s 55 5 csiadlessisl Adenine sE Tarei E keis F 14 Configuration File Variables scesesessseecesesseeeseeeeeneeeeeeeenes F 14 Record and Table Locking cc eeseseesesecseceteseeseceseeceeneeeeteeenee F 28 Limits and RANGES c 05 05 c ccc sccctssestescntoneeetesedcesoedenbehclesiob cettinaneeas F 28 D ta Type Mapping cnisia iep ades ee aeeie F 29 Runtime Errors eaa E EARE EiS F 30 Common Questions and Answers c cccscccsseesssessscessecsssssseceneesees F 32 F 2 m Acu4GL for DB2 Information F 1 DB2 Concepts Overview A quick overview of some basic design concepts underlying the DB2 Database Management System will help you interface your COBOL program to it Transactions The DB2 RDBMS is a transaction based system All of the work that you perform while using DB2 must occur within a transaction whether that work is being done through Acu4GL for DB2 or another 4GL application When you use Acu4GL for DB2 a transaction is implicitly started for you by the database engine itself with the first file I O operation performed on a file associated with DB2 Because all operations with Acu4GL for DB2 occur within a transaction any record locked during processing remains locked until either a COMMIT WORK or ROLL
61. appendix instructs you on installing and setting up the Informix Acu4GL product discusses Informix technical specifications and provides troubleshooting options Appendix B Acu4GL for Microsoft SQL Server Information This appendix provides you with an overview of Microsoft SQL Server concepts instructs you on installing and setting up the Microsoft SQL Server Acu4GL product details the RDBMS s technical specifications and also tells you about troubleshooting options Appendix C Acu4GL for Oracle Information This appendix provides you with an overview of Oracle concepts instructs you on installing and setting up the Oracle Acu4GL product gives you the RDBMS s technical specifications and also lists troubleshooting options 1 6 m Acu4GL Overview Appendix D Acu4GL for ODBC Information The ODBC appendix provides you with an overview of ODBC concepts instructs you on installing and setting up the ODBC Acu4GL product informs you of the RDBMS s technical specifications and discusses troubleshooting options Appendix E Acu4GL for Sybase Information This appendix provides you with an overview of Sybase concepts instructs you on installing and setting up the Sybase Acu4GL product and lists the RDBMS s technical specifications as well as troubleshooting options Appendix F Acu4GL for DB2 Information This appendix provides you with an overview of DB2 concepts instructs you on installing and setting up the DB2 A
62. as column names the data dictionary maps fields that appear subordinate to a REDEFINES clause to column names 3 6 m Data Dictionaries Multiple record definitions This same rule extends to multiple record definitions In COBOL multiple record definitions are essentially redefinitions of the entire record area This leads to the same complication that is encountered with REDEFINES multiple definitions for the same data So the compiler needs to select one definition to use Because the multiple record types can be different sizes the compiler needs to use the largest one so that it can cover all of the fields adequately Thus the compiler s rule is to use the fields in the largest record defined for the file If more than one record is of the largest size the compiler uses the first one Group items Note that group items are by default never included in a data dictionary for the same reason that REDEFINES are excluded they result in multiple names for the same data items You can however choose to combine grouped fields into one data item by specifying the USE GROUP directive described in Chapter 4 FILLER data items In a COBOL FD FILLER data items are essentially place holders FILLER items are not uniquely named and thus cannot be uniquely referenced For this reason they are not placed into the ACUCOBOL GT data dictionary The dictionary maintains the correct mapping of the other fields and no COBOL record positi
63. automatically and you must provide aname The starting name serves as the basis for the dictionary name Syntax SXFD FILE name or XFD FILE name This directive must appear on the line immediately preceding the file s FD Example Suppose your SELECT statement has a variable ASSIGN name such as the one shown here select my file assign to my variable Directives Supported by the Acu4GL Interfaces m 4 13 Then you would need to add the FILE directive as shown here select my file assign to my variable xfd file payroll fd my file Note that this directive must appear immediately before the file s FD See also XFD_MAP configuration variable 4 3 7 NAME The NAME directive assigns a database field name to the field defined on the next line Syntax SXFD NAME fieldname or XFD NAME fieldname This directive has several uses as shown in the following examples Example 1 non unique field names Within a database file all field names must be unique Multiple database tables may include the same field name but duplicates may not exist within a single table Unique field names are not required in COBOL because names can be qualified by group items For example this is acceptable in COBOL 4 14 m Using Directives 01 employee record 03 date hired 05 yy pic 99 05 mm pic 99 05 dd pic 99 03 date last paid 05 yy pic 99 05 mm pic 99 05 dd pie 99 Yo
64. continue but FAST_ACCESS mode will be disabled with the following message appearing in the trace file FAST_ACCESS mode not available Also a new connection technically uses a new concurrent Microsoft SQL Server license from Microsoft Configuration File Variables m B 17 Files opened with FAST_ACCESS will not participate in transactions and may even cause the runtime to hang if transactions are used especially if the FAST_ACCESS file is updated within the transaction We suggest that if you use transactions you don t use FAST_ACCESS At the minimum if you use transactions we suggest that you use FAST_ACCESS only for files open INPUT Files opened with FAST_ACCESS cannot be read backwards In other words READ PREVIOUS will not work with FAST_ACCESS files In fact if you try to READ PREVIOUS on a file opened with FAST_ACCESS you will get an error 9D 20 The ANSI standard states that READ NEXT after a READ will return the next record Some applications depend on this and some applications just want to read dynamically from a file and don t use the positioning facility Because of this ambiguity files that are opened with FAST_ACCESS cannot be READ dynamically If you try to READ on a file opened with FAST_ACCESS you will get an error 9D 20 There are no restrictions on WRITE REWRITE and DELETE However these operations use the cursor based connection not the dedicated connection This is the reason transactions
65. database via SQL and accidentally change only one of the keys Here s an example of the problem and a description of how to correct it the example assumes that both key and key 2 have been declared as keys Troubleshooting m 9 15 01 order record 03 key 1l 05 field a pic x 5 05 field b pre 9 5 05 key 2 redefines field b pic x 3 This example will generate the warning message Because key 2 is a key it must also be represented in the database It doesn t correspond exactly to any other data field so it must be entered as a separate column in the database In the COBOL view of the file key 7 and key 2 overlap But the requirements of database storage force the same data known to COBOL as field b to be physically represented twice in the database Any updates to the data from any ACUCOBOL GT program will correctly update both columns Updates from outside of ACUCOBOL GT carry no such guarantee In this example you can correct the situation by breaking field b into two columns so that key 2 corresponds exactly to another data field 01 order record 03 key 1 05 field a pic x 5 05 field b 07 field bl pie x 3 07 field b2 pic 9 2 05 key 2 redefines field b pic x 3 9 2 3 Retrieving Runtime Errors You can determine the meanings of your database error codes by referring to the database documentation Here are methods for storing the complete error code and some helpful text that describes it
66. details B 8 m Acu4GL for Microsoft SQL Server Information In addition to setting the variables required for Microsoft SQL Server you must do the following Ensure that your execution path contains the name of the directory in which you placed your Acu4GL enabled runtime Set the A_LMSSQL_LOGIN and A_MSSQL_PASSWD variables either in your environment or in the ACUCOBOL GT runtime configuration file If you don t do this Acu4GL will use the value of the USER environment variable as your Microsoft SQL Server login name with no password For security reasons it is best to set the password variable from your COBOL program by asking the user to enter a password and then executing SET ENVIRONMENT A_MSSQL_ PASSWD TO user entry You may want to make and use a personalized copy of the configuration file to avoid impacting other users The ACUCOBOL GT User s Guide describes how to use the A_CONFIG environment variable or the c runtime option to identify a personal configuration file For detailed information on ALMSSQL_LOGIN and A_MSSQL_PASSWD see section B 4 Acu4GL for Microsoft SQL Server Configuration File Variables in this appendix B 2 4 Designating the Host File System If you are opening an existing file all file systems linked into the runtime will be searched for the named file If however you are creating a new file you will need to tell the runtime which file system to use
67. executed To the end user the interaction between the COBOL and the Oracle database is transparent as though they were part of one process You can also access the database information directly from Oracle at your option C 7 Supported Features OPEN ALLOWING READERS is not supported by Oracle You determine in your runtime configuration file how this phrase will be interpreted Set the variable STRENGTHEN_LOCKS to 1 to cause this phrase to be treated as OPEN ALLOWING NO OTHERS Set the variable to 0 to cause the phrase to be treated as OPEN ALLOWING ALL The default value is 0 Transactions are enforced in Oracle Within a transaction records locked by T O operations that modify delete or otherwise result in a COBOL record lock remain locked until aCOMMIT WORK or a ROLLBACK WORK is issued or until your COBOL program encounters a COMMIT or ROLLBACK verb See the description of the COMMIT_COUNT configuration variable Oracle does not support record encryption record compression or alternate collating sequences You may include these options in your program they will be disregarded if they are specified The ACUCOBOL GT utility program vutil cannot be used with Oracle files Instead use utilities supplied by Oracle Whenever you are using the library routine RENAME you must specify that you are using indexed files This information is passed by the value T in the fourth parameter Unless you have DBA
68. files are formed and work together When the ACUCOBOL GT compiler generates XFD files it uses lowercase letters to name the XFD file In addition the compiler changes hyphens to underscores when naming the XFD file Through configuration variables the runtime translates the file name in the COBOL program into the filename that is passed to the open function in the runtime The open function determines which file system to pass the request to but does not change the name of the file However Acu4GL for Sybase needs the name of the file to find the appropriate XFD file To do this Acu4GL for Sybase changes the name of the file to lowercase letters and changes hyphens to underscores Note however that this is performed only on a local copy of the file Once the XFD file is found the filename reverts to the name that was originally passed to the open function Characters that are illegal in identifiers such as a hyphen are trapped by the database and Acu4GL for Sybase will neither find the file nor create a new one Configuration File Variables m E 25 E 4 Configuration File Variables This section lists the runtime configuration file variables that are specific to Acu4GL for Sybase Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are discussed in section 8 2 Runtime Configuration Variables A_SYB_ADD_IDENTITY When it is set at the default of True
69. for Oracle Information Table ownership Table names in Oracle have the form owner table_name If you are the owner of a given table you can refer to it as just table_name If you are not the owner you must refer to it with the owner of the table as a prefix Acu4GL for Oracle provides a user configurable method the USER_PATH configuration variable for implementing this Security Security is implemented in the Oracle RDBMS A user is required to log in to the RDBMS before any file processing can occur Acu4GL for Oracle provides both a default and a user configurable method for implementing this Oracle s security considerations pose several challenges for COBOL programmers Because of the various levels of permissions certain operations are not allowed unless you have Database Administrator DBA privileges These restricted operations include e creating a table under another user s name e dropping a table owned by another user Oracle versions 9i and later also provide additional security levels however you must consult the Oracle documentation to determine if any of these permission levels are appropriate for your site Generally it is best for someone with DBA privileges to create and drop the tables allowing others only the permissions to process information contained in them A table can be referenced either by owner table_name or by a public synonym that you have created for the table See the Oracle documentation
70. for files open I O since the record must be locked and then the rest of the data fetched but causes the interface to select all the columns of the table for files open INPUT A_MSSQL_SKIP_ALTERNATE_KEYS A_MSSQL_SKIP_ALTERNATE_KEYS determines whether alternate keys are used to form indexes during table creation The default value of this variable is 0 which means it s okay to use alternate keys This configuration variable can also take values of 1 on true yes If you set the variable to a nonzero value such as 1 alternate keys are not used to form indexes which speeds up processing if many writes or rewrites are being performed Note that a value of 1 may slow processing if the application is reading sequentially using an alternate key A_MSSQL_TRANSLATE_TO_ANSI Setting this variable to True on yes causes the Acu4GL interface to call the same translation function used by the Windows runtime to translate characters going to the server into the OEM character set and to translate characters coming from the server to ANSI The default is False off no which indicates that the Acu4GL interface does not call the translation function but passes the data as is to the library A_MSSQL_UNLOCK_ON_EXECUTE Setting this variable to True on yes causes all invocations of I IO using the EXECUTE opcode to unlock all records Normally records are unlocked when a transaction finishes But
71. harmonize the civil year with the solar as well as synchronize the time of Easter with the movable feasts by means of epochs Every year divisible by 4 except those divisible by 100 and not by 400 has 366 days all other years have 365 days Contrast Julian calendar indexed file In database design a list of keys or keywords each of which identifies a unique record Indexed files make it faster to find specific records and to sort records by the index field the field used to identify each record See also key 1 O Input Output Input Output Communication between a computer and its users its storage devices other computers using a network or the outside world The devices the computer uses to do this are called peripherals Julian base date The earliest Julian date to be used in defining Julian date formats See also Julian calendar Julian calendar The solar calendar introduced by Julius Caesar in Rome in 46 B C having a year of 12 months and 365 days and a leap year of 366 days every fourth year It was eventually replaced by the Gregorian calendar Contrast Gregorian calendar Glossary 4 m key A value used to identify a record in a database derived by applying some fixed function to the record The key is often one of the fields a column if the database is considered as a table with records being rows Alternatively the key may be obtained by applying some function for example a hash function to
72. if users do their own transaction management using sql acu which calls I IO using the EXECUTE opcode the interface never knows to unlock records because it doesn t check the text sent to the database to see if it is associated with a transaction The default value is Off false no B 26 m Acu4GL for Microsoft SQL Server Information A_MSSQL_USE_DROPDOWN_QUERIES Setting A_LMSSQL_USE_DROPDOWN_QUERIES to a nonzero value causes selects sent to the database to be of the drop down variety instead of a single large query For example if you have a file with three fields in the primary key keyseg1 keyseg2 keyseg3 and your COBOL program does a START the following query is sent to the database select columns from table where keysegl valuel and keyseg2 value2 and keyseg3 gt value3 or keysegl valuel and keyseg2 gt value2 or keysegl gt valuel order by keysegl keyseg2 keyseg3 If you use drop down queries the following collection of queries is sent instead select columns from table where keysegl valuel and keyseg2 value2 and keyseg3 gt value3 order by keysegl keyseg2 keyseg3 When that set is finished we then send select columns from table where keysegl valuel and keyseg2 gt value2 order by keysegl keyseg2 keyseg3 And when that set is finished we then send select columns from table where keysegl gt valuel order by keysegl keyseg2 keyseg3 The
73. in the actual SQL queries This configuration variable enables you to modify this behavior The default value is FALSE which will cause the catalog portion of the table name to be treated as blank in SQL queries Setting this variable to TRUE will cause the value of the catalog returned by SQLTables ODBC function to be used in subsequent SQL queries See also USER_PATH configuration variable A_DB2_CATALOG configuration variable Configuration File Variables m F 25 A_DB2_USE_CHAR_FOR_BINARY Some data sources have restrictions on the number of binary large objects BLOBs that can be placed into a single table If your data source has such restrictions specify A_DB2_USE_CHAR_FOR_BINARY in the configuration file The possible values for this variable are 0 use BINARY type 1 use CHAR type A nonzero value for A_DB2_USE_CHAR_FOR_BINARY lets you store data that uses the BINARY directive as hexadecimal encoded CHAR types This allows you to work around your data source restriction While the default value is 0 off false no this configuration variable can also take values of On true yes Because of current limitations of the interface you must set this variable to 1 or the database returns an error on file creation This has been set for you in the sample configuration file cblconfig db2 Do not change this setting Example A_DB2_USE_CHAR_FOR_BINARY 1 A_DB2_USE_SQLCO
74. is issued whether USER_PATH is present or not a new table is created with the owner being the name specified in A_DB2_LOGIN Using USER_PATH with other variables such as A_DB2_CATALOG can speed up the finding of tables in large databases It can also prevent an error 9D 14 More than one table with the same name thereby enabling access to tables with identical names but with different schemes For example If the USER_PATH and A_DB2_CATALOG are used the form of the SQL statement will be modified from select COLI from TABLENAME to SELECT COL1 FROM catalog username TABLENAME where catalog and username will be filled in if provided See Also A_DB2_LOGIN configuration variable A_DB2_ALTERNATE_COMMIT_LOGIC configuration variable F 28 m Acu4GL for DB2 Information F 6 Record and Table Locking With Acu4GL for DB2 records are locked in a Wait mode An application trying to read a locked record will hang until the record becomes available DB2 Universal Database products have the ability to time out a lock and send an error return code to waiting applications See your database administrator for additional information F 7 Limits and Ranges The following limits exist for the DB2 protocol Maximum number of columns per key 16 Maximum number of columns 500 Maximum index size 255 Maximum record size 4005 Note that these limits may be further constrained by your database configuration
75. it if you discover that a row cannot be added to a table By reducing the upper bound you may be able to prevent the problem Configuration File Variables m B 19 If Microsoft SQL Server increases the maximum number of bytes allowed in a row in a future release of the product you can increase the value of this variable to take advantage of the new limit The A_LMSSQL_MAX_ CHARACTERS variable has a default value of 1962 A_MSSQL_MAX_COLUMNS A_MSSQL_MAX_COLUMNS indicates the maximum number of columns the Acu4GL product will allow in a table The default value is 250 Microsoft SQL Server places a limit on the number of columns per table The Acu4GL product will adhere to this limit but sometimes it cannot accurately count how many columns a table contains because a column has been added to a table without the Acu4GL product s knowledge This variable enables the developer to set the Acu4GL product s upper bound You might want to try reducing the upper bound if you discover that a table cannot be created for some reason By reducing the upper bound you allow for uncountable columns and thus may be able to prevent the problem If SQL Server increases the maximum number of columns allowed per table in a future release of the product you could increase the value of this variable to take advantage of the new limit Consult your SQL Server documentation to decide the new maximum number of columns allowed per table
76. key field that contains signed numeric data High values and low values can cause problems in key fields If you want data that uses the BINARY directive to be stored as hexadecimal encoded CHAR types you can specify A_ODBC_USE_CHAR_FOR_ BINARY in the configuration file Please note that this could potentially increase the size of your key beyond the driver maximum Other limits are described in Appendix B in Book 4 Appendices of the ACUCOBOL GT documentation D 9 Driver Requirements Your ODBC driver must include the following functions e all Core ODBC driver functions e the Level 1 function SQLColumns e the Level 1 function SQLTables Depending on the method of record locking you choose your driver may also need to support some of the following function calls See the description for A_ODBC_LOCK_METHObD in section D 4 Acu4GL for ODBC Configuration File Variables Driver Requirements m D 37 e SQLSetStmtOption e SQLSetScrollOptions e SQLExtendedFetch e SQLSetPos To test the capabilities of your ODBC driver we have included a driver test program on your Acu4GL for ODBC installation disks You can also consult your driver documentation to ensure that it meets these requirements ODBC driver test Acu4GL for ODBC includes a driver test program designed to test your ODBC driver for compatibility with Acu4GL for ODBC The driver test also lists all the tables columns for the driver selected This can help desig
77. like isql Usa Ppassword lt syb_inst sql This script will add some stored procedures and create some tables in a database that you specify during the execution of this script In order to implement locking from ACUCOBOL GT we need to create a lock table This should be a pretty small table but we need to decide which database to create this table in You should now enter the name of the database you want the lock tables created in If the database does not exist it is created E 16 m Acu4GL for Sybase Information The following question is asked until you enter a valid database name Which database would you like to create this table in This database will eventually be located on your server machine Enter a valid database name Invalid names are master model temp or sybsystemprocs Names must start with a letter or underscore must contain only letters digits and underscores and may be up to 30 characters long Any other entry will be modified Next you see the following message Saving any old version of syb_inst sql Old versions of syb_inst sql are saved to syb_instnnn sql where nnn starts at 001 and goes to 999 Ifa file syb_inst sql exists you see Saving syb_inst sql as syb_instnnn sql for some value of nnn Then you see Creating syb_inst sql This uses the file syb_inst in as a template and creates syb_inst sql using the database name you entered above
78. many fields in the key There are more than 16 fields in a key Check your key definitions and restructure the key that is illegal then recompile with Fx 9D 05 no message associated with this error A date given to the Acu4GL interface is invalid and cannot be converted 9D 06 Mismatched dictionary file The dictionary file xfd for one of your files conflicts with the COBOL description of the file FD The xx indicates a tertiary error code that is defined by the host file system You can determine the exact nature of the mismatch by referring to the host system s error values The tertiary error code may have any of these values 01 mismatch found but exact cause unknown this status is returned by the host file system 02 mismatch found in file s maximum record size 03 mismatch found in file s minimum record size 04 mismatch found in the number of keys in the file 05 mismatch found in primary key description 06 mismatch found in first alternate key description 07 mismatch found in second alternate key description The list continues in this manner for each alternate key 9D 11 ACUCOBOL GT stored procedures not found or ACUCOBOL GT lock table missing The installation of Acu4GL for Microsoft SQL Server creates a number of stored procedures and tables At least one of these was not found Runtime Errors m B 41 9D 12 A column of a key is of data type TEXT or IMAGE which is il
79. may hang While the default value is 0 off false no this configuration variable can also take values of On true yes A_MSSQL_LOCK_DB A_MSSQL_LOCK_DB specifies the name of the database that holds the lock table See also Section B 6 Table Locking B 18 m Acu4GL for Microsoft SQL Server Information A_MSSQL_LOGIN A_MSSQL_LOGIN indicates the user name under which you want to connect to the database system Example To connect to the database with the user name MYNAME you would specify A_MSSQL_LOGIN MYNAME in the runtime configuration file If A_MSSQL_LOGIN is not set the runtime will use the value of your USER environment variable as your Microsoft SQL Server login name For this automatic login to succeed you must have set up a user with the same name as your computer login name See also A_MSSQL_PASSWD runtime configuration file variable Section B 2 2 Setting Up a User Account A_MSSQL_MAX_CHARACTERS A_MSSQL_MAX_CHARACTERS indicates the maximum number of bytes the Acu4GL product will allow in a table row Microsoft SQL Server places a limit on the number of bytes per table row The Acu4GL product adheres to this limit but sometimes it cannot accurately count how many bytes a particular row contains because of overhead bytes that Microsoft SQL Server adds This variable enables the developer to set the Acu4GL product s upper bound You might want to try reducing
80. must be on individual lines as single values in the code WHEN values cannot be combined 4 22 m Using Directives For example 03 ar code type pic x xfd when ar code type s 03 ship code record pic x 4 xfd when ar code type b 03 backorder code record redefines ship code record xfd when ar code type other 03 obsolete code record redefines ship code record OTHER may be used before one record definition and may be used once at each level within each record definition Note A WHEN directive with condition OTHER must be used if there is a possibility that the data in the field will not meet any of the explicit conditions specified in the other WHEN directives If this is not done results are undefined Example 1 If the following code were compiled without directives the underlined fields would appear explicitly in the database table Note that the key fields would be included automatically as would the fields from the largest record FILLER would be ignored 01 ar codes record 03 ar codes key 05 ar code type pic x 05 ar code num pic 999 01 ship code record 03 filler pic x 4 03 ship instruct pic x 15 01 terms code record 03 filler pic x 4 03 terms rate 1 pic s9v999 03 terms days 1 pic 9 3 03 terms rate 2 pic s9v999 03 terms descript pic x 15 If you add the WHEN directive as shown below it causes the fields from the SHIP CODE RECORD to be included i
81. mydb2 dbo myfile2a and looks at the basename to determine the filesystem to use mydb2 It then looks for mydb2 HOST to determine which filesystem to send the file requests to You can change the values of the filename HOST and DEFAULT_HOST variables during program execution by including the following in your code SET ENVIRONMENT filename_HOST TO filesystem or SET ENVIRONMENT DEFAULT_HOST TO filesystem This enables you to change file systems during the execution of your program This is not the typical way to specify a file system it is usually designated in the runtime configuration file and is not changed in the COBOL program FILE TRACE This variable allows you to start file tracing without opening the debugger Set this variable to a non zero value to save information about all file OPENs READs and WRITES in the error file This is equivalent to specifying tf n from the debugger where n is an integer The default is 0 See section 3 1 4 File Tracing of the ACUCOBOL GT User s Guide for more information about the file trace feature Runtime Configuration Variables m 8 17 XFD_DIRECTORY XFD_DIRECTORY tells the runtime system the name of the directory that contains the data dictionaries built by the ACUCOBOL GT compiler The default value is the current directory Example To tell the runtime that the dictionaries are stored in the directory us
82. need to regenerate the query The number of cursors available to your COBOL application may need to be adjusted as described below Setting the parameters In summary what you need to do is e Set the Oracle system parameter open_cursors to indicate the total number of cursors you want to have To do this look in Oracle s init ora and initSID ora or any other database initialization files used at your site and add or modify the line open_cursors nnn e The number of cursors can be equal to the number of keys times the number of segments per key for each file For example if you have five files each of which has three keys and each key has three segments you should set open_cursors to a minimum of 45 Note Setting OPEN_CURSORS should be performed only by your System Administrator or Database Administrator because it affects all applications using the database C 2 5 Setting Up a User Account Acu4GL for Oracle must be able to connect to a user account You may either set up one general account for all users or an account for each individual user To set up an account you must have Database Administrator DBA privileges Note You may opt to use Oracle s Enterprise Manager on Windows platforms to simplify the login process If you decide to use the Enterprise Manager please skip this section and refer to the Enterprise Manager documentation C 16 m Acu4GL for Oracle Information
83. one or more of the fields The set of keys for all records forms an index Multiple indexes may be built for one database depending on how it is to be searched See also indexed file network Hardware and software data communication systems Networks are often also classified according to their geographical extent local area network LAN metropolitan area network MAN wide area network WAN and also according to the protocols used ODBC Open Database Connectivity Open Database Connectivity Released in 1992 a library of standardized data access functions that gives programmers a way to access and manipulate data in a variety of data sources Interfaces include Visual Basic Visual C SQL and the ODBC driver pack contains drivers for the Access Paradox dBase Text Excel and Btrieve databases An application can submit statements to ODBC using the ODBC flavor of SQL and ODBC then translates these to whatever flavor the database understands ODBC is based on Call Level Interface and was defined by the SQL Access Group query A user s or agent s request for information generally as a formal request to a database or search engine SQL is the most common database query language See also SQL Structured Query Language record A group of related fields or a single field treated as a unit and comprising part of a file or data set for purposes of input processing output or storage by acomputer Contrast field m
84. open tables on that server by giving them a name like servername database owner tablename Note that this naming can be done in your runtime configuration file I m getting an error 9D 11 ACUCOBOL GT lock table missing I know that I added the lock table during installation This is probably a permissions problem All users must have READ WRITE UPDATE and DELETE access to AcuLocks and therefore to the database that contains it Be sure to check your permissions I keep receiving an error message saying that my login is invalid But Pm sure I m using the correct username and password All usernames passwords and database names are case sensitive Be sure that you are typing the names exactly as they are set up E 58 m Acu4GL for Sybase Information Question The runtime system can t seem to locate my XFD file but when I check the XED directory the file is definitely there Check the case of the XFD filename The Acu4GL product may be looking for uppercase on the base name Are there any ACUCOBOL GT library routines that do not work with or would not make sense to use with Acu4GL for Sybase Yes There are two ACUCOBOL GT library routines that either don t work with or do not make sense to use with Acu4GL for Sybase C COPY and C RECOVER Acu4GL for DB2 Information Key Topics DB2 Concepts Overview scesccsecsceseesecseeeceeceaeceseeceeeneesceseeneeneeates F 2 Installation
85. open the file this way TOM stores johndoe purchl See also The Sybase documentation on isql E 30 m Acu4GL for Sybase Information A_SYB_EXTRA_PROC A_SYB_EXTRA_PROC can be used to keep modifications to the AcuLocks table out of transactions If these modifications are kept out of transactions users can read a record even if they cannot REWRITE it Otherwise they are locked out A_LSYB_EXTRA_PROC works by creating a separate connection for these modifications When this variable is set to a nonzero value an extra connection is used for the following three procedures e Modifying the AcuLocks table e Modifying the AcuOpenTables table e Modifying the IMAGE data Note that two connections are required when updating IMAGE or TEXT data This is a major reason for setting A_SYB_EXTRA_PROC The default value is 0 off false no A nonzero value can also be represented by On true yes If this variable is set to On the extra connection is used to send TEXT or IMAGE data to the server The first connection is used to deliver non TEXT and non IMAGE data to the server When a WRITE or REWRITE is executed the interface program INSERTS or UPDATES the non TEXT and non IMAGE data by using placeholder data in the TEXT or IMAGE columns The TEXT or IMAGE data is then sent using the extra connection established with the A_LSYB_EXTRA_ PROC variable If the first connection is inside a transaction the second conn
86. other files to an XFD file 3 10 XFD files 3 9 matching COBOL fields to database fields 7 2 numeric fields to database fields 7 3 text fields to database fields 7 3 MAX_CURSORS configuration variable C 22 m Index 27 Acu4GL for Informix A 13 menus demonstration program Help 2 11 Options 2 11 Position 2 10 Record 2 9 Microsoft SQL Server Query Analyzer B 4 modifying COBOL procedures 9 10 multiple indexes and tables 9 4 multiple record definitions FILLER 3 5 3 6 4 21 OCCURS 3 5 3 6 overview 3 6 REDEFINES 3 5 4 20 4 23 multiple tier architecture ODBC D 5 N NAME directive 3 8 4 13 names fields conflicts 7 4 identical 3 8 long 3 8 overview 7 4 names XFDs ASSIGN 3 9 final 3 10 overview 3 9 naming indexes 1 15 network service C 21 new database files overview 7 2 NUMERIC directive 4 16 numeric fields matching to database 7 3 Index 28 O OCCURS definition 3 6 ODBC configuration variables list of 4GL_MAX_DATE D 18 4GL_MIN_DATE D 19 A_ODBC_ALTERNATE_COMMIT_LOGIC D 19 A_ODBC_COMMIT_ON_BEGIN D 21 A_ODBC_DATASOURCE D 21 A_ODBC_ERROR_MAP_FILE D 22 A_ODBC_LOCK_METHOD D 24 A_ODBC_LOGIN D 26 D 34 F 27 A_ODBC_NO_NULL_COLUMNS D 27 A_ODBC_PASSWD D 27 A_ODBC_PRINT_LOG D 28 A_ODBC_QUOTE_IDENTIFIERS D 28 A_ODBC_STRICT_EQUAL D 28 A_ODBC_UNSIGNED_TINYINT D 30 A_ODBC_USE_CHAR_FOR_BINARY D 31 A_ODBC_USE_SPACE_IN_DATES D 31 ODBC configuration variables overview D 18 ODBC Acu4GL applicatio
87. part of the table because the key overlays this area This table is built in the database Column Name Type p_o_division_number number 3 p_o_record_type char 1 p_o_number number 10 P_O_yy number 2 p_o_mm number 2 p_o_dd number 2 p_o_dept_number number 3 p_O_quantity_to_ship number 4 6 8 m Working with COBOL Column Name p_o_total_quantity notes_line_1 notes_line_2 notes_line_3 Type number 4 char 40 char 40 char 40 The actual database datatype may vary 6 1 3 Using Additional Directives In this final approach you decide to streamline the code a bit so you introduce the following three changes e You apply the USE GROUP directive to the notes because you don t need to access each note line individually from the database side Grouping them improves execution speed and clarity e You rename the notes field for convenience e You apply the USE GROUP and DATE directives to the date to give it all the properties of a date on the database side fd p o file xfd when p o record type h 01 p o record 03 p o division number 03 p o record type 88 header record 88 detail record 03 p o number 03 p o number detail redefines p o number 05 picking ticket number 05 shipping region 05 p o customer type 05 p o customer breakdown redefines p o customer type 07 customer category 88 p o customer retail 88 p o customer whlsale 07 customer pay form
88. past This definition is represented in the DATE directive with the letter J for example a six digit date field would be preceded with the directive XFD DATE JJJJJJ The default base date for this form of Julian date is 12 31 4714 BC You may define your own base date for Julian date calculations by setting the runtime configuration variable 4GL_JULIAN_BASE_DATE Handling invalid dates Acu4GL considers dates in the following range to be valid 01 01 0001 to 12 31 9999 If Acu4GL considers a date valid and passes it to an RDBMS that considers it invalid the results depend on the particular RDBMS Some systems return an error code Some store the date as NULL and do not return an error Some store the date in an unpredictable fashion and do not return an error We recommend that you determine the error handling procedures of the RDBMS in use Directives Supported by the Acu4GL Interfaces m 4 11 If a COBOL program attempts to write a record containing a date that Acu4GL knows is invalid Acu4GL inserts NULLs into the date field and writes the record If a COBOL program attempts to read into a record from a table with a NULL date field zeroes are inserted into that field in the COBOL record For date fields having two digit years by default years O through 19 are inserted as 2000 through 2019 and years 20 through 99 are inserted as 1920 through 1999 You can change this behavior by changing the value of the variable 4GL_2000_
89. performance Your Acu4GL for ODBC disks include a program that tests your ODBC driver for the various functions the Acu4GL product requires This program is called DRVTST32 EXE You initiate it by selecting the appropriate icon in the Acu4GL for ODBC program group Please refer to section D 9 Driver Requirements for instructions on using the driver test program This section also describes the minimal requirements that your driver must meet to work with Acu4GL for ODBC Data Sources Data sources are the files or databases accessed by a driver Each data source must be identified during setup Some data sources are simple to identify For example to access a text file you would provide the name and location of the file Some are more complex though For example to access a UNIX hosted database such as Oracle you would identify the Windows drivers Windows applications network connections and database information In Windows XP you set up an ODBC data source in the Windows control panel Administrative Tools dialog After you double click the Data Sources ODBC icon an ODBC Data Source Administrator dialog is displayed You must designate the driver the data source and any other information necessary to access the data Setup procedures are described in detail in section D 2 Acu4GL for ODBC Installation and Setup D 8 m Acu4GL for ODBC Information The following diagram shows how the Acu4GL product fits into a s
90. product which is an interactive query tool is also necessary for installing the ACUCOBOL GT stored procedures The Acu4GL product does not need isql after installation but it is a tool that can give you quite a bit of flexibility It allows you to do database work outside of COBOL including interactive queries table creation table modification and creation of views constraints and relationships between tables Micro Focus does not provide these products E 2 2 Acu4GL for Sybase Installation The Acu4GL product for Sybase is an add on module The Sybase Acu4GL product installation includes a DLL file that is detected at run time If you are working in a 32 bit environment it is not necessary to relink the runtime However the relinking process is necessary for UNIX users and is explained below in this section The Acu4GL product can be executed on a machine that is running UNIX or Windows Installation instructions for each of these configurations are given in the following sections The instructions in the sections that follow describe the steps you must follow on both the client machine and the server machine Be sure to use the 64 bit libraries with a 64 bit runtime and 64 bit Acu4GL for Sybase and the 32 bit libraries with a 64 bit runtime and 32 bit Acu4GL for Sybase Installation and Setup m E 5 E 2 3 UNIX Client Installations The Acu4GL product is shipped using either TAR or CPIO format depending on the ty
91. record locking To complement your driver s locking method Acu4GL for ODBC can initiate three locking sequences SETPOS SETSTMTOPTION UPDATECOLUMN As described in section D 4 you specify which type of locking you want to use with the configuration file variable A_ODBC_LOCK_METHOD However if your driver doesn t support locking Acu4GL for ODBC by itself cannot provide locking Record locking with ODBC drivers is a semi random activity Different ODBC drivers have different capabilities and even implement the same capabilities in different ways For this reason you will have to do some experimentation to determine which locking method to specify for A_ODBC_LOCK_METHOD Only through trial and error will you be able to determine which method will lock records in the most efficient way for your particular ODBC driver D 36 m Acu4GL for ODBC Information D 8 Limits and Ranges The following limits exist for the ODBC protocol Maximum number of columns per key depends on driver database Maximum number of columns depends on driver database Acu4GL allows an unlimited number of columns but the database may have a limit and the driver may have a smaller limit than the database If you have too many columns you will receive a database error on the table create for example open output To achieve the same sort or retrieval sequence under ODBC as under the Vision file system place a BINARY directive immediately before each
92. resources are tied up The extensive data verification in COBOL programs only prolongs this If performance is an issue give some thought to dividing each transaction into smaller and more efficient subgroups Tables with multiple indexes If you use tables with multiple indexes keep in mind that when a record is written or updated locks are put onto all of the indexes and they are all basically rewritten during the course of the write update This is a costly Performance Issues m 9 5 process There may be multiple columns per index and multiple indexes per table Each rewrite implies a certain amount of wait time Tables with a large number of indexes can be slow on writes updates and possibly other operations in the database query optimizer become confused There are two things you can do in this circumstance e Restructure your data e Use the Vision file system for some of your data Restructuring the data The benefits of data restructuring may be significant For example if you have any situations in which two indexes start out with the same column or set of columns you may be able to improve performance appreciably by changing your data definition Suppose two indexes both start with MONTH DAY YEAR These identical first three columns can cause the RDBMS s query optimizer to choose the wrong index in which case you will generate a significant amount of unnecessary and unproductive overhead Restructuring one of th
93. runtime with a static link Different versions of the C development system use different flags to accomplish this link Please consult the documentation for your C compiler to determine the correct flag for your environment Step 6 Copy runcbl to the correct directory If the runtime is a system is a statically linked executable copy the new executable to a directory listed in your execution path This file needs to have execute permission for everyone who will be using the compiler or runtime system The copy step is not necessary when the runtime system is a shared library The ACUCOBOL GT license file for the runtime runcbl alc and the license file for the Acu4GL product to Sybase runcbl ylc must be copied into the same directory as the runtime executable If you rename your runtime executable be sure to rename your license files to use the same base name with the extensions unchanged For example if you rename your runtime to be myprog the license file for the Acu4GL product for Sybase should be renamed myprog ylc and the license file for the runtime should be renamed myprog alc The remaining files can be left in the directory to which they were unloaded from the distribution medium Step 7 Use rehash If you are using the C shell enter the command rehash This tells the C shell that there is a new executable in the path This completes the installation process on the client machine
94. s why The compiler uses the base file name without the extension to create the XFD file name IDX1 XFD The runtime needs to be able to locate this file But if you ve mapped the file name to something completely different such as MYFILE the runtime will look for an XFD file named MYFILE XFD So you d have to remember to change the name of IDX1 XFD to MYFILE XFD in the XFD directory Save yourself this extra step by simply dropping the extension when you map the name Also see the configuration variable 4GL_IGNORED_SUFFIX_LIST for an alternate method of removing file extensions Security Security is implemented in the Microsoft SQL Server RDBMS A user is required to log in to the RDBMS before any file processing can occur Acu4GL for Microsoft SQL Server provides both a default and a user configurable method for implementing this Generally it is best for someone with Database Administrator DBA privileges to create and drop the tables allowing others only the permissions to add change or delete information contained in them See the Microsoft SQL Server documentation for more details on DBA privileges B 4 m Acu4GL for Microsoft SQL Server Information B 2 Installation and Setup You must perform several steps before you begin using Acu4GL for Microsoft SQL Server on a new system The following topics provide this information e Installing on a Client Machine e Setting Up a User Account e Setting Up the User
95. script fix the PATH variable and start the script again Installation and Setup m E 9 Finally you see the message Creating Makefile syb Makefile syb created You should be able to execute make f Makefile syb and the script exits Step 3 Move the makefile Copy Makefile syb to the ACUCOBOL GT library subdirectory if it is not already there Now you are ready to relink your ACUCOBOL GT runtime Step 4 Link the runtime system Note In the following directions the term runtime system refers to the runtime shared object on systems where the ACUCOBOL GT runtime is a shared object and to runcbl on other systems where the runtime is static The runtime is a shared object on the following systems AIX 5 1 and later HP UX 11 and later and Solaris 7 and later To check look at the contents of the lib subdirectory of your ACUCOBOL GT installation If the files libruncbl so or libruncbl sl reside in that directory the runtime is a shared object on your system Make sure you are in the directory containing the ACUCOBOL GT runtime system Then at the UNIX prompt enter the following command make clean to ensure that you have a clean directory in which to build your runtime Now enter the following command make f Makefile syb This compiles sub c and filetbl c and then links the runtime system E 10 m Acu4GL for Sybase Information Step 5 Verify the link Ente
96. setting up user accounts C 15 table ownership C 6 transactions C 2 C 19 C 28 troubleshooting C 30 Acu4GL SQL Server configuration variables B 11 database table B 28 designating the host file system B 8 filename interpretation B 10 getting started B 4 installation B 4 installation on client B 5 installation on NT server B 5 overview B 2 runtime errors B 39 security B 3 servers B 2 setting up a user account B 7 setting up the user environment B 7 SQL Server limits and ranges B 38 table locking B 28 table ownership B 2 troubleshooting B 39 Acu4GL Sybase configuration variables E 25 creating a new runtime E 6 creating stored procedures E 15 designating the host file system E 22 filename interpretation E 24 installation and setup E 4 installing stored procedures E 16 E 19 libraries shared E 10 linking the runtime E 9 makefiles E 6 overview E 2 m Index 9 ranges E 52 REWRITE method E 3 runtime errors E 54 security E 3 servers E 2 setting up a user account E 21 setting up the user environment E 21 Sybase limits and ranges E 52 table locking E 43 table ownership E 2 troubleshooting E 53 acu4glfd utility 6 10 ACUCOBOL GT runtime module 1 11 Web runtime and Acu4GL 1 8 ACUCOBOL GT library routines and Acu4GL 1 15 alfred indexed file editor 1 8 3 2 ALPHA directive 4 5 alternate REWRITE method Sybase E 3 ANSI compliant directive 4 3 ANSI mode databases and Acu4GL for Informix A 2 application ODBC D 6 architecture
97. site has customer files that have identical structures but different names such as CUSTO001 CUST0002 and CUST0003 It s not necessary to have a separate XFD for each file as long as their record definitions are the same The individual files can all be mapped to the same XFD via a runtime configuration variable called XFD_MAP The following paragraphs describe how it works XFD Files m 3 11 Suppose your COBOL application has a SELECT with a variable ASSIGN name such as customer file This variable assumes different values such as CUST0001 and CUST0002 during program execution Before compiling the application you would use the FILE directive see Chapter 4 to provide a base name for the XFD Suppose you provide CUST as the base The compiler would then generate an XFD named cust xfd The compiler always converts XFD names to lower case To ensure that all customer files each having a unique name will use this same XFD you make this entry in your runtime configuration file XFD_MAP CUST CUST The asterisk in the example is a wildcard that matches any number of characters Note that the extension xfd should not be included in the map This statement would cause the XFD cust xfd to be used for all files whose names begin with CUST The XFD_MAP variable has this syntax XFD_MAP pattern base xfd name where pattern consists of any valid filename characters and may inclu
98. source you may set the data source name dynamically at run time In your COBOL program you would add code similar to this prior to the statement that opens the file SET ENVIRONMENT A_DB2_DATASOURCE TO data source name There is no default value for this variable A_DB2_ERROR_MAP_FILE Set A_DB2_ERROR_MAP _FILE to the name of the file that maps database specific errors to COBOL errors This configuration file variable allows you to map errors using a text file to supplement the default method of providing errors Create the file using the guidelines described on the following page and then use the configuration file variable A_DB2_ERROR_MAP_FILE to indicate the name and location of the file you created Example If the file used for mapping is called MAP and this file is located in the directory C DB2 you would specify A_DB2_ERROR_MAP_FILE c DB2 MAP in the runtime configuration file There is no default value for this variable Guidelines for creating a map file Although you can check your data source documentation for error code information the easiest way to determine what error codes need to be mapped to more appropriate COBOL codes is through trial and error As users use Acu4GL for DB2 they may report receiving error messages that don t make sense based on their situation Research these errors and try to determine a more appropriate COBOL error response When you create your error map file us
99. structure This would be useful when I create several customer files that use the same record definitions Answer At run time it is possible to use a single XFD for files that have different names For example suppose a site has customer files that have identical structures but different names CUST0001 CUST0002 CUST0003 and so on It s not necessary to have a separate XFD for each file so long as their record definitions are the same The individual files can all be mapped to the same XFD via a runtime configuration variable called XFD_MAP Here s how it works Suppose your COBOL application has a SELECT with a variable ASSIGN name such as customer file This variable assumes different values such as CUST0001 and CUST0002 during program execution Before compiling the application you would use the FILE directive to provide a base name for the XFD Suppose you provide CUST as the base The compiler would then generate an XFD named cust xfd The compiler always converts XFD names to lower case To ensure that all customer files each having a unique name will use this same XFD you make this entry in your runtime configuration file XFD_MAP CUST CUST The asterisk in the example is a wildcard that matches any number of characters Note that the extension xfd should not be included in the map This statement would cause the XFD cust xfd to be used for all files whose names begin with CUST The XFD_MAP variable ha
100. support technical 2 2 supported features Informix A 19 Oracle C 28 switching file systems Informix A 18 Sybase configuration variables list of A_SYB_ADD_IDENTITY E 25 A_SYB_ADD_TIMESTAMP E 25 A_SYB_CHECK_DELETE_SP E 26 A_SYB_CHECK_INSERT_SP E 26 A_SYB_CHECK_UPDATE_SP E 27 A_SYB_CURSOR_OPTION E 27 A_SYB_DATABASE E 28 A_SYB_DEFAULT_CONNECTION E 29 A_SYB_EXTRA_PROC E 30 A_SYB_FAST_ACCESS E 31 A_SYB_FORCED_INDEX E 32 A_SYB_LOCK_DB E 33 A_SYB_LOGIN E 33 A_SYB_MAX_ CHARACTERS E 34 A_SYB_MAX COLUMNS E 34 A_SYB_NATIVE_LOCK_TIMEOUT E 35 A_SYB_NO_23_ON_START E 37 A_SYB_NO_COUNT_CHECK E 36 A_SYB_NO_DBCLOSE E 36 A_SYB_NO_DBID E 36 A_SYB_NO_RECORD_LOCKS E 36 Index 40 A_SYB_NO_TABLE LOCKS E 37 A_SYB_PACKETSIZE E 37 A_SYB_PASSWD E 38 A_SYB_ROWCOUNT E 39 A_SYB_SELECT_KEY_ONLY E 39 A_SYB_SKIP_ALTERNATE_KEYS E 40 A_SYB_TRANSLATE_TO_ANSI E 40 A_SYB_UNLOCK_ON_EXECUTE E 41 A_SYB_USE_DROPDOWN_QUERIES E 41 A_SYB_VISION_LOCKS_FILE E 42 Sybase configuration variables overview E 25 Sybase Acu4GL concepts E 2 configuration variables E 25 creating a new runtime E 6 creating stored procedures E 15 designating host file system E 22 getting started E 3 information E 2 installation and setup E 4 installing stored procedures E 16 E 19 limits and ranges E 52 linking runtime E 9 makefiles E 6 record and table locking E 43 REWRITE method E 3 runtime errors E 54 security E 3 servers E 2 setting up the user environm
101. the Acu4GL error messages that could occur during execution of your program Chapter 9 Performance and Troubleshooting provides information on compile time errors and also provides several methods for retrieving runtime errors Each message is followed by an explanation and a recommended recovery procedure Runtime errors will have this format 9D xxxx The 9D indicates a file system error and is reported in your FILE STATUS variable The xx is a secondary database specific error code These are the secondary errors reported directly from Acu4GL for Oracle 9D 03 Dictionary xfd file not found The dictionary file for one of your COBOL files cannot be located Be sure you have specified the correct directory via your XFD_PREFIX configuration variable You may need to recompile with the Fx option to create the dictionary See section 8 1 for additional information on compiler options Common Questions and Answers m C 31 9D 04 Corrupt dictionary file The dictionary file for one of your COBOL files is corrupt and cannot be read Recompile with Fx to re create the dictionary Note that this error may be caused by inappropriate application of a directive Check all directives and call Technical Services if you have questions 9D 05 Too many fields in the key more than 16 for Oracle Check your key definitions and redefine the key that is illegal and then recompile with Fx 9D 06 Mismatched dictiona
102. the SELECT for the file has a variable ASSIGN name ASSIGN TO filename you must specify a starting name for the XFD file via a FILE directive in your code This process is described in Chapter 4 Using Directives ASSIGN name is a constant If the SELECT for the file has a constant ASSIGN name such as ASSIGN TO COMPFILE that name is used as the starting name for the XFD name 3 10 m Data Dictionaries ASSIGN name is generic If the ASSIGN phrase refers to a generic device such as ASSIGN TO DISK the compiler uses the SELECT name as the starting name Forming the final XFD name From the starting name the final name is formed as follows e The compiler removes any extensions from the starting name e It constructs a universal base name by stripping out directory information that fits any of the formats used by the operating systems that run the ACUCOBOL GT compiler e Itreduces the base name to eight characters and converts it to lower case e It appends the letters xfd to the base name Examples of XFD names COBOL code File name ASSIGN TO usr ar customer dat customer xfd SELECT TESTFILE ASSIGN TO DISK testfile xfd ASSIGN TO D SYSSLIB HELP help xfd ASSIGN TO FILENAME you specify Mapping other files to an XFD At run time it is possible to use a single XFD for files that have different names For example suppose a
103. the XFD file In addition the compiler changes hyphens to underscores when naming the XFD file Through configuration variables the runtime translates the file name in the COBOL program into the filename that is passed to the open function in the runtime The open function determines which file system to pass the request to but does not change the name of the file However Acu4GL for Microsoft SQL Server needs the name of the file to find the appropriate XFD file To do this Acu4GL for Microsoft SQL Server changes the name of the file to lowercase letters and changes hyphens to underscores Note however that this is performed only on a local copy of the file Once the XFD file is found the filename reverts to the name that was originally passed to the open function Characters that are illegal in identifiers such as a hyphen are trapped by the database and Acu4GL for Microsoft SQL Server will neither find the file nor create a new one Configuration File Variables m B 11 B 4 Configuration File Variables This section lists the runtime configuration file variables that are specific to Microsoft SQL Server Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are discussed in section 8 2 Runtime Configuration Variables A_MSSQL_ADD_IDENTITY When is set to the default of On true yes A MSSQL_ADD_IDENTITY adds an extra column to any table created by
104. the order the inventory file is modified to reflect that items have been removed from the stock on hand F 4 m Acu4GL for DB2 Information 3 The user must switch to a different part of the application to perform a different task perhaps as a result of a phone call from a new customer 4 All of the records that were locked or modified by the application before the switch remain locked because the first order is not complete No COMMIT or ROLLBACK has been issued to complete the transaction All of the records locked by the transaction remain locked until the application ends the transaction 5 Because one order is open and not yet committed other applications may be locked out of certain order items if they are still locked by the processing of the first order The second order entry may be held up until the first order is completed 6 Note that the first application is not locked out A process can read its own locked records Acu4GL and record locking Your DB2 database may be set up for wait level locks The DB2 universal database products have the ability to time out a lock and send an error return code to the waiting application See your database administrator for details This SQL code would be placed in ERROR_MAP_FILE Acu4GL provides semi automated ways to handle transaction logging based on the setting of the 4GL_COMMIT_COUNT variable You can also directly alter your source code to deal with this issue Individua
105. the primary key in the order they are listed in the XFD Based on the sample XFD you might want to create the following stored procedure for deleting records from a file create procedure ftestdat_delete ft2_key char 4 as delete from ftestdat where ftest2_key ft2_key grant execute on ftestdat_delete to public tablename_read tablename_read is used to read a random record READ not READ NEXT or READ PREVIOUS The parameters passed to the stored procedure are the values of the primary key in the order they are listed in the XFD The expected rowset is the columns in the first table if secondary tables are used or the columns of the table if secondary tables are not necessary This stored procedure is very similar to tablename_start Stored Procedures m E 49 tablename_update tablename_update is used to REWRITE a record from the file The parameters passed to the stored procedure are the values of all the columns in the row in the order of the columns in the database The timestamp column and identity column if present in the table are not passed to the stored procedure For example based on the sample XFD you might want to create the following stored procedure for rewriting a record create procedure ftestdat_update ft2_key char 4 ft2_keyl_segl char 2 f t2_keyl_seg2 char 2 ft2_altkey2 char 4 ft2_number char 9 ft2_info char 10 as update ftestdat set ftest2_key ft2_key f
106. to True on yes the Acu4GL for Microsoft SQL Server interface attempts to log users on using the SQL Server Windows NT authentication mode See your SQL Server documentation for information about this authentication mode When A_MSSQL_NT_AUTHENTICATION is enabled the A_LMSSQL_LOGIN and A_MSSQL_PASSWD configuration variables are no longer needed or used They are still available if you are not using Windows NT authentication mode If you have not set up SQL Server itself to allow this type of authentication setting this variable to TRUE causes all login attempts to fail See your SQL Server documentation for information on how to set up this type of authentication The default is False off no indicating that the Acu4GL for Microsoft SQL Server interface will not use Windows NT authentication mode when logging users on and will continue to use login password authentication A_MSSQL_PACKETSIZE The A_MSSQL_PACKETSIZE variable sets the size of network packets Setting this variable can affect performance since fewer and larger network calls can improve performance This variable must be set in the configuration file and has no effect if set in a COBOL program via SET CONFIGURATION or SET ENVIRONMENT The value of this variable is the largest size that the transport layer uses for network packets although the underlying library may reduce the size specified this is out of the control of the interface The largest value th
107. to understand in this situation is that there is almost nothing that you can do wrong When the Acu4GL product opens a data source table the only thing it checks is that the column names match the COBOL data names When the Acu4GL product reads data from the data source it essentially does a COBOL style MOVE from the native data type to the COBOL data type whatever it is And since most types have a CHAR representation in other words you can actually display most data types using a standard DB2 capable tool using PIC X nn for each column will work perfectly well F 30 m Acu4GL for DB2 Information A better general rule is to use a COBOL type that closely matches the data source data type but don t worry about getting an exact fit So you can use PIC 9 9 whenever the data source has an INTEGER type If you have more information about the data source type you might be able to use a different COBOL representation For example if you know that a particular column in an DB2 data source has values only in the range 0 999 you could use PIC 999 for your COBOL data The COMP type you use is really determined by your own preferences and should have little bearing on the COBOL data type you choose If you want to somehow choose your COBOL data types so that there is a best fit you can use the following mapping directive applied pic x 255 or greater must apply pic x 255 VAR_LENGTH directive F 9 Runtime Errors This sect
108. with a serial column and cannot change it There may be a solution to this and the solution is determined by whether you need to reference this serial column when you do your READs A 20 m Acu4GL for Informix Information If the user does not need to access these columns directly you can build your FDs without this field Because the current version of Acu4GL for Informix lists the columns from the XFD and Acu4GL for Informix allows the table to have more columns than the FD it should be possible for you not to include the serial columns in the FD This has the effect that on an INSERT the unmentioned serial columns would be populated by the next sequential value If it is necessary for the user to access these columns consider having two FDs One FD would list the serial column included for reading Then use another FD this time without the serial column for your writes or rewrites Informix does not support record encryption record compression or alternate collating sequences You may include these options in your program they will be disregarded if they are specified The ACUCOBOL GT utility program vutil cannot be used with Informix files Instead use utilities supplied by Informix Whenever you are using the library routine RENAME you must specify that you are using indexed files This information is passed by the value T in the fourth parameter If you want to delete an Informix table with the DELETE FILE verb
109. with the ability to define transactions and the ability to commit them or undo them usually in response to an error condition This undo facility is called a rollback e It provides the ability to reconstruct files into a consistent state after a program dies or system failure occurs This operation is called recovery Note that transaction management facilities are available in ACUCOBOL GT Version 2 4 0 and later Record locking issues in transactions Applications that are written for transaction management systems or that perform work in small operation based logical units benefit greatly from DB2 s transaction management systems Applications that are not written for transaction management encounter difficulty with record locking when operating against a system that enforces transaction management The difficulty can occur with an application that is performing more than one logical task at a time Any operation that modifies or reads data in an I O mode without the WITH NO LOCK phrase causes a lock to be placed in the database system As a result the application may have many more record locks present than would be expected by the normal rule of COBOL file locking The application would act in a manner similar to when the LOCKS ON MULTIPLE RECORDS clause in COBOL is used This can best be illustrated by an example 1 The user is entering a customer s order 2 As each line item is entered into
110. with the invalid column then recompile the program to create a new XFD file Common Questions and Answers m D 45 9D 16 Maximum Length for Literal Characters Exceeded The interface queries the data source about the maximum size of a character literal in an SQL statement and if there are any fields in the COBOL data record that exceed that limit the interface fails to open the file with an error 9D 16 Error 9D 16 means that there is at least one COBOL field that exceeds the reported maximum length for character literals and that you may not be able to insert or update at least one column in the database D 12 Common Questions and Answers Question Question Question This section contains some questions and answers specific to Acu4GL for ODBC Refer to Chapter 10 for additional questions and answers that pertain to the Acu4GL family of products Can I open tables in different databases and share the data Yes But you must set up the data sources one at a time as described in this section For example you could first set your data source to be Oracle and open Oracle tables and then you could change the data source to Access and open Access tables Remember you can set up data sources dynamically at run time by adding a line like this before the statement that opens the file SET ENVIRONMENT A_ODBC_DATASOURCE TO data source name I keep receiving an error message saying that my login is invalid But Pm
111. with the user name has the associated password CW021535 specify INF_PASSWD CW021535 in the configuration file or the environment See also INF_LOGIN configuration variable Informix Performance m A 13 MAX_CURSORS MAX_CURSORS is the number of cursors parameterized queries in Acu4GL s cursor cache The default value is 100 The range is 1 100 If you set this variable to a number less than the maximum of 100 you may reduce the number you specify in the Informix system parameter OPEN_CURSORS by alike amount The value of Informix s OPEN_CURSORS should exceed MAX_CURSORS by at least 7 Example To allow your application to use up to 23 cursors specify MAX_CURSORS 23 in the configuration file A 4 Informix Performance Informix databases include many advanced concepts such as parallel queries multi processor support and virtual processors To increase performance for large sites on powerful multi processor machines Informix has changed some of the database default configurations moving to a cost based optimization for its default query mode This means that the query optimizer for Informix OnLine makes its decisions about optimization based purely on costs without considering translation isolation mode With this default OnLine does not give preference to index scans nested loop joins and key base reads over table scans other join methods The behavior can be especially problematic in the c
112. without a password this variable need not be set There is no default value for this variable If no password is specified none will be used D 28 m Acu4GL for ODBC Information A_ODBC_PRINT_LOG This variable is used for debugging only and is best used under the direction of an extend Technical Services representative A_ODBC_QUOTE_IDENTIFIERS A_ODBC_QUOTE_IDENTIFIERS tells the Acu4GL product whether to test for the IDENTIFIER QUOTE CHAR and to use it if it is found If this variable is nonzero and if the driver returns information about the IDENTIFIER QUOTE CHAR all identifiers sent in SQL to the driver will be quoted This is useful for using Microsoft Excel for example if the spreadsheet has column names with quotes or other strange characters Notice that some drivers mistakenly report that they can handle quoted identifiers which is why this variable is needed If you set this variable to a nonzero value and start getting errors about table not found or column not found this variable should not be used when communicating with that driver While the default value is 0 off false no this configuration variable can also take values of On true yes Note We have found that with Excel this variable is useful With Oracle this variable is not recommended Refer to section D 6 for information on using mixed cased identifiers A_ODBC_STRICT_EQUAL When Acu4GL for ODBC executes a
113. you specifically override this default Use the configuration variable 4GL_ILLEGAL_DATA to override The following COBOL data usages are considered illegal by the database e In USAGE DISPLAY numbers LOW VALUES HIGH VALUES and SPACES are all illegal e In COMP 2 numbers HIGH VALUES and SPACES are illegal e In COMP 3 numbers HIGH VALUES is illegal e All other numeric types fit one of the preceding cases depending on their internal storage format e In DATE fields the value zero is illegal as are any other illegal conditions as defined by the date s USAGE type see above e In text fields LOW VALUES is illegal e BINARY numbers are always legal and all values are legal in BINARY text fields Invalid Database Data m 5 3 5 1 1 Invalid Key Data Any field that is part of a key is never stored as null A null key does not have a well defined position in relation to other keys If a key field has an illegal value the field is stored in the database as described here Illegal LOW VALUES minimum possible value 0 or 99999 minimum possible date value 01 01 01 Illegal HIGH VALUES maximum possible value 99999 maximum possible date value database dependent Illegal SPACES zero or 01 01 01 for a date field 5 1 2 Invalid Data Other Than Keys You have the option to convert illegal data other than keys into legal values by setting the configuration variable 4GL_ILLEGAL_DATA to Convert
114. 0 export OPTCOMPIND depending on which shell is being used Informix Performance m A 17 Method 1 and method 2 resulted in the following iobench times Informix 5 1 Informix 7 2 Informix 9 SunOS4 1 3 Intel 486 System 5 4 Write Sequential Load Index 1 13 8 16 6 24 92 4 5 4 1 We can verify the changes that were made by examining the output of the query optimizer The above test resulted in these results SELECT rowid FROM idxl WHERE idx_l_key gt ORDER BY idx_l_key ASC Estimated Cost 4 Estimated of Rows Returned 3 1 informix idxl INDEX PATH 1 Index Keys idx_l_key Lower Index Filter informix idxl idx_l_key gt 0000000900 Both method 1 and method 2 above are useful if you are processing new data They have the drawback however that they permanently constrain the execution paths that the query optimizer has to choose from To allow the query optimizer the greatest flexibility in working with data that exists day to day on your system you will want to choose the next method A 18 m Acu4GL for Informix Information Method 3 Provide the query optimizer with information Database tables that are in use on a frequent basis can benefit from providing the query optimizer with more information This allows the optimizer to work at its best in returning information from the database You provide the optimizer with information of the tables by issuing the following SQL command UPDATE STATISTI
115. 02 mismatch found in file s maximum record size 03 mismatch found in file s minimum record size 04 mismatch found in the number of keys in the file 05 mismatch found in primary key description 06 mismatch found in first alternate key description 07 mismatch found in second alternate key description The list continues in this manner for each alternate key Common Questions and Answers m A 25 255 Not in transaction A stop run has caused a commit or rollback to be sent to Acu4GL for Informix By default this message is disabled If you would like to enable this message set the A_INF_NO_TRANSACTION_ERROR variable to zero 0 A 9 Common Questions and Answers Question This section contains some questions and answers specific to Acu4GL for Informix Refer to Chapter 10 in this book for additional questions and answers that pertain to the Acu4GL family of products How do I create new databases You have two choices 1 you can use an Informix product such as ISQL to create a new database or 2 you can use the program sql acu provided with your Acu4GL product To use the sql acu utility to create an empty database and grant access privileges to other users enter the following command runcbl sql acu The program pauses to accept an SQL command Enter the following CREATE DATABASE database name Note If you want to use the transaction logging facility availabl
116. 2 m Performance and Troubleshooting Note It is possible that you will experience slower performance simply because the Acu4GL application is limited because of the rules of COBOL If you want to keep track of performance levels there are many third party tools available to help monitor performance 9 2 1 Compiler Errors The errors listed below could occur when you compile with the Fx option In some cases the data dictionary cannot be built until you remove the error condition Data dictionary errors do not however prevent the object code from being generated Bad picture for DATE keyname The PICTURE must be six or eight bytes in length either alphanumeric or numeric with no sign Data missing from key segment keyname This occurs when some part of the named key cannot be placed in the dictionary the dictionary cannot be generated in this situation This usually occurs because of filler For example 01 my record 03 my key 05 filler pic xx 05 field 1 pic xx If my key is declared as a record key you will receive this error because the area of the key described by filler is not included in the dictionary To correct this error ensure that every character that is part of the key is included in some field that is part of the dictionary Use an XFD to give a field name to each filler to ensure that fillers are included 01 my record 03 my key xfd name myfiller 05 filler pic xx 05
117. 3 7 sql acu 2 3 V VAR_LENGTH directive 4 6 4 20 variables configuration 8 4 m Index 45 external 9 10 VAX and RMS file systems 1 6 verifying the runtime demonstration program 2 7 Vision file systems 1 6 Vision files 9 5 W warnings compiler 9 14 database upgrades 9 6 Web runtime ACUCOBOL GT 1 8 WHEN directive 3 5 4 20 and field names 3 9 WHERE constraint 9 7 overriding 8 13 working with COBOL 6 2 X XED extended file descriptor files 3 2 creating 8 2 locating 8 18 XML format 8 2 XFD data dictionaries file options compiler 8 4 XFD_DIRECTORY configuration variable 8 17 XFD_MAP configuration variable 3 10 8 17 XFD_MAP_RESETS configuration variable 3 12 8 18 XFD_PREFIX configuration variable 3 7 8 18 XFDs data dictionaries defaults 3 5 defined 1 8 3 2 directives introduction 4 2 file options compiler 8 2 Index 46 location 3 7 mapping to other files 3 10 names 3 9 naming 3 9 XML stylesheet directive 4 26 XML format for XFD files 8 2 XSL directive 4 26
118. 6 m Acu4GL for Microsoft SQL Server Information A_MSSQL_FAST_ACCESS A_MSSQL_FAST_ACCESS is a configuration variable that is set from your COBOL program Files opened while this variable is set to a nonzero value will be optimized for forward sequential access We implemented this option to substantially improve the READ NEXT performance in some cases For example testing the extend benchmark program iobench cbl in three ways yielded the following results for the READ AND SKIP operation No FAST_ACCESS 72 76 seconds FAST_ACCESS ROWCOUNT 0 148 88 seconds FAST_ACCESS ROWCOUNT 10 8 09 seconds 10 is the perfect value for ROWCOUNT in this benchmark because the program does a START 10 READ NEXT operations and then does it again For certain reporting programs this option can dramatically improve performance However please note the following restrictions Files must be open INPUT or open IO with MASS UPDATE FAST_ACCESS gives a performance boost only when no locking is required In files that allow locking a record must be reread after being locked this prevents an uninterrupted forward sequential traversal Files opened with FAST_ACCESS use a dedicated connection for reading from the file Since connections are memory intensive both on the client and on the server the number of files opened with FAST_ACCESS should be kept to a minimum In the event that opening a connection fails the file open will still
119. 8 3 2 indexes Acu4GL naming conventions for 1 15 and tables 9 4 Indicator area 4 3 inf_inst program A 4 m Index 23 INF_LOGIN configuration variable A 12 INF_PASSWD configuration variable A 12 Informix and Acu4GL 7 2 and 7 3 performance A 13 compile sample program A 7 configuration variables A 9 creating a new runtime A 4 data types not supported A 21 database designating A 8 getting started A 2 installation A 3 limits and ranges A 21 linking runtime A 5 makefile A 4 questions and answers A 25 retrieving errors 9 15 runtime errors A 23 shared libraries A 6 supported features A 19 switching file systems A 18 technical tips A 18 troubleshooting A 22 Informix configuration variables and Open_CURSORS A 13 overview A 9 Informix configuration variables list of A_INF_DUPLICATE_KEY A 9 A_INF_NO_FINAL_TRANSACTION_ERROR A 10 A_INFORMIX_ERROR_ FILE A 11 DATABASE A 11 INF_LOGIN A 12 INF_PASSWD A 12 MAX_CURSORS A 13 input file 9 3 installation Index 24 m Acu4GL for DB2 F 6 Acu4GL for DB2 on UNIX F 7 Acu4GL for Informix A 3 Acu4GL for ODBC D 10 Acu4GL for Oracle C 7 Acu4GL for Oracle on UNIX C 9 Acu4GL for Oracle on Windows C 7 Acu4GL for SQL Server B 4 Acu4GL for SQL Server on client B 5 Acu4GL for SQL Server on NT server B 5 Acu4GL for Sybase E 3 E 4 E 14 overview 2 2 SQL Server B 4 installing stored procedures B 6 E 12 E 16 E 17 E 19 Instant Client Oracle C 20 interaction databases and COBOL 9 6 int
120. A ess A_MSSQL_DEFAULT_CONNECTION ssessseeeeseesrsssserrrsrerrsreeerreresreserresene Contents v A MSSQL DEFAULT OWNER 0 eececceeeeseeeseecacessecaeceaesaeceseeeecneeeesenseaaeaaes B 15 A MSSQL FAS T ACCES Siriei eaa n laymen E E EAREN B 16 ALMSSOL LOCK DBn Sra ne A ea a inte B 17 A MSSQL LOGIN a a ho arne nth Busi netidin Rianne Diode des B 18 A_MSSQL MAX CHARACTERS co ssccisccssisccestessecetis sce isecsesvietesenspsndeobesesdascusesseeaseys B 18 A_MSSQL_MAX_COLUMNS o oeae eea E EER ER EES B 19 A_MSSQL_NATIVE_LOCK_TIMEOUT sseeseeeeseeeeeseeessreeeresrerreseeresenresesrerrsserees B 19 A_MSSQL_NO_COUNT_CHECK esiis nte tuote oriei ia eroen osre EE EE Eis ESEE B 20 A MSSOL NO DBD ee sees acs e apar oases aoas oo ar S EESEL sssetathsa seeseesacnscnbeh eesisessets B 21 A_MSSQL_NO_RECORD_LOCKS esseseesesessessrsrrresrerrsreereresresrnseresseeesesrereeserees B 21 A MSSQL NO TABEE LOCKS ee a E N N B 21 A_MSSQL_NO_23_ON_START De N R EEN B 21 A_MSSQL_NT_AUTHENTICATION vresa a eecscesse cee o i eee paeo e T aeee B 22 A MSSQL PACKETSIZE e E EA E ioe ae ou E EA B 22 A MSSQL PASSWD ei ee E E E E E A AAE E B 23 A MSSQL ROWCOUN wisissess ssssecisgeeesstiaupen hen tees cess E EE EREE ET EEE EAEE EEES B 24 A_MSSQL_SELECT_KEY_ONLY aireari set eier reet r Ee rE EE EEEE E sees B 24 A_MSSQL_SKIP_ALTERNATE_KEYS ooo eee ceseeeecesceseeeeeeeeeeeeeneesaecneenaeeaes B 25 A_MSSQL_TRANSLATE_TO_ANSI ooo eo cece ceessecneceeeseceseeeeeee
121. ASE ERROR 350 ISAM ERROR 108 Index already exists on column 9 20 m Performance and Troubleshooting Using the Informix error number and finderr An additional method also for Informix only allows you to take the Informix error number and use the finderr syntax to discover error information More information on this syntax can be found in your Informix documentation The syntax is finderr xxxxx where xxxxx is the Informix error number 10 General Questions and Answers Key Topics Introduction Questions and ANSWEFS ccccccccesscesssseecesseceesseeeseaeeecseteceenseeeses 10 2 m General Questions and Answers 10 1 Introduction This chapter provides answers to some common questions that can apply to any RDBMS or ODBC compliant data source supported by the Acu4GL family of interfaces Be sure to check the appendix pertaining to Acu4GL for ODBC or your RDBMS for additional information Appendix A Acu4GL for Informix Information Appendix B Acu4GL for Microsoft SQL Server Information Appendix C Acu4GL for Oracle Information Appendix D Acu4GL for ODBC Information Appendix E Acu4GL for Sybase Information Appendix F Acu4GL for DB2 Information 10 2 Questions and Answers Question Answer I can t seem to get Acu4GL to create the files in my database or ODBC data source They keep coming up as Vision files Check to see that the DEFAULT_
122. A_MSSQL_DEFAULT_CONNECTION specifies the name of the server to which the runtime will connect This variable is checked only if the DSQUERY environment variable has not been set If neither DSQUERY nor A_MSSQL_DEFAULT_CONNECTION is set the server is named DSQUERY To reference tables in another server open the file servername database owner table Example Suppose you have two servers one named TOM and one named HARRY If most of the tables you want to access are on the server HARRY then you should set A_MSSQL_DEFAULT_CONNECTION HARRY For those occasions when you want to access the TOM server you could open the file this way TOM stores johndoe purchl A_MSSQL_DEFAULT_OWNER In SQL Server tables are named database user tablename The value of A_MSSQL_DEFAULT_OWNER specifies the name of the user If this variable is set it must match the owner of a table Tables are referenced as owner table where owner is the value of A_LMSSQL_DEFAULT_OWNER If this variable is set to a value for which owner table does not exist the interface fails to access the table Note that newly created tables are owned by the users who create them not the owner named in A_MSSQL_DEFAULT_OWNER The default value of this configuration variable is blank causing the interface to call an internal stored procedure to determine the actual owner of the table Note that we discourage multiple tables with the same tablename in a single database B 1
123. BACK WORK is issued This action results in behavior similar to the LOCK ON MULTIPLE RECORDS clause in COBOL The benefits of a transaction management system are best illustrated by an example A COBOL application that handles order entry might perform these steps to accept an order 1 Write an invoice record 2 Update a customer record 3 Write a payroll record for sales commissions 4 Update an inventory record This series of four file operations is a logical unit If the program were interrupted and completed only some of the four file operations then the files would be in an inconsistent state For example if the program terminated unexpectedly after it updated the customer record but before it updated the inventory record then a subsequent run might access non existent inventory The solution to this problem is to provide a method for the programmer to define a set of operations that should either all occur or all not occur Then if the program encounters an error or terminates the files are left in a consistent state DB2 Concepts Overview m F 3 All file operations that are part of a transaction are logged Once logged they can be either committed or rolled back undone by the program If a program dies or the system fails the log file can be used to reconstruct complete transactions returning all files to a consistent state Transaction logging thus offers these two facilities e It provides the programmer
124. COBOL program uses field names that begin with a numeric character use the NAME directive to assign a different name for use with your database SQL will typically generate a syntax error when it encounters a column name that begins with a numeric character For example 03 12 months sales pic 9 5 V99 could be renamed this way Sxfd name twelve months sales 03 12 months sales pic 9 5 V99 NUMERIC The NUMERIC directive allows you to treat a data item as an unsigned integer when it is declared as alphanumeric You might use this when the data stored in the item is always numeric Syntax SXFD NUMERIC or XFD NUMERIC Directives Supported by the Acu4GL Interfaces m 4 17 Example Sxfd numeric 01 student code pic x 7 4 3 9 SECONDARY_TABLE Some RDBMSs such as Sybase permit subordinate tables When this is the case you can use the SECONDARY_TABLE directive to indicate that the next data item may be placed into a subordinate table if more than one table is necessary to accommodate the data Up to 26 subordinate tables can be created from a single record description Each table name is based on the original table name with a letter from A to Z appended For example if the original table were named my table subsequent subordinate tables would be given these names my tableA my tableB my tableC my tableD When the runtime accesses the data dictionary it makes an initial pass through the data taking all
125. CS HIGH FOR TABLE lt tablename gt Executing this command updates the Informix system database catalog tables SYSTABLES SYSCOLUMNS SYSINDEXES and SYSDISTRIB The optimizer uses this data to determine the best execution path for queries The database server does not update this statistical data automatically however Statistics are updated only when you issue an UPDATE STATISTICS statement Informix recommends that you run UPDATE STATISTICS in high mode for all columns that head an index For the fastest execution time of the UPDATE STATISTICS statement you must execute one UPDATE STATISTICS statement in the high mode for each such column For each multi column index run UPDATE STATISTICS in low mode for all of its columns You may want to perform the UPDATE STATISTICS on the entire table periodically as shown above instead of just on the indexes For more information on optimizing Informix performance and general maintenance issues please refer to your Informix OnLine documentation A 5 Technical Tips Switching file systems Each time a file is opened the file system identified by the filename_HOST configuration variable if present or the DEFAULT_HOST variable is used You can change the value of these variables in your code by including SET ENVIRONMENT filename_HOST TO filesystem or Supported Features m A 19 SET ENVIRONMENT DEFAULT_HOST TO filesystem just before you open the file SET ENVIRONMENT thu
126. CUTOFF Note If a field is used as part of a key the field cannot be a NULL value For information about converting date values using the 4GL_CONVERT_DATE_ZERO variable see section 8 2 Runtime Configuration Variables Using group items You may place the DATE directive in front of a group item as long as you also use the USE GROUP directive Example 1 Sxfd date 03 date hired pic 9 8 03 pay scale pic x 3 The column date hired will have eight digits and will be type DATE in the database with a format of YYYYMMDD Example 2 XFD DATE USE GROUP 03 date hired 05 yyyy pic 9 4 05 mm pic 9 2 05 dd pic 9 2 This also will produce a column named date hired with eight digits and type DATE in the database format YY YYMMDD 4 12 m Using Directives Example 3 XFD DATE EEEYYYY 03 date sold pic 9 7 03 sales rep pic x 30 This will produce a column named date sold with seven digits and type DATE in the database The date will contain the day of the year for example February 1 would be 032 followed by the four digit year such as 1999 4 3 6 FILE The FILE directive supplies a starting name from which the data dictionary file name is formed This directive is required only when the file name in the COBOL code is nonspecific For example use this directive when the SELECT for the file has a variable ASSIGN name ASSIGN TO variable_name In this case Acu4GL cannot form a file name
127. D PREVIOUS on a file opened with FAST_ACCESS you get an error 9D 20 The ANSI standard states that READ NEXT after a READ will return the next record Some applications depend on this and some applications just want to read dynamically from a file and don t use the positioning facility Because of this ambiguity files that are open with FAST_ACCESS cannot be READ dynamically If you try to READ on a file open with FAST_ACCESS you get an error 9D 20 There are no restrictions on WRITE REWRITE and DELETE However these operations use the cursor based connection not the dedicated connection This is the reason transactions may hang A_SYB_FORCED_INDEX A_SYB_FORCED_INDEX causes the Acu4GL product to attempt to use an actual index that matches the key used with the table For this variable to have any effect the index matching the key must be a unique index While the default value is 0 off false no this configuration variable can also take the value of Yes on true If you don t use the forced index feature the Acu4GL product adds an ORDER BY clause to the SELECT which can add to processing time Configuration File Variables m E 33 We have discovered that Sybase does not guarantee that an index will be used if this variable is set to 1 and so the order of records returned to the COBOL program is not guaranteed to be correct in that case Because of this we highly discourages setting this variable t
128. D condition It is not possible for the application developer to specify a larger working set than would otherwise have resulted The developer may only constrain the working set to a smaller subset Using WHERE constraints from COBOL The following steps are required for using the WHERE constraint Step 1 Declare an external variable To make use of WHERE constraints from COBOL the application must declare an external variable for communication with the Acu4GL product This variable is declared as follows 77 a4gl where constraint pic x 300 external Step 2 Modify your COBOL procedures Your COBOL application should move the information that you want added to the WHERE clause to the new external variable before a COBOL positioning operation such as START or READ is performed The additional constraint will then be applied to any SQL read query performed on that file until a new positioning operation is performed The additional query information is also stored in Acu4GL s cursor cache so that if the same read conditions occur in later processing the existing closed cursor can be reused with new bind variables instead of being regenerated Be sure to fill the external variable before a positioning operation START or READ The WHERE constraint affects only READ NEXT operations preceded by a positioning operation The WHERE constraint does not affect a READ NEXT that was not preceded by a positioning operation such as a READ N
129. DBMS Installation nsss enin neia iaeia E 4 E 2 2 Acu4GL for Sybase Installation sseeeesseeeseesseeesseeeererrsrsserrssreresreersrenrerrereerssene E 4 Contents viii E 2 3 UNIX Client Installations ccc ccccccsecccceessssceceeessaececeecsesceceecsessaeeecesessaeeeeees E 5 E 2 3 1 UNIX Client Installation Steps 0 eee ee eeeeeseeeeecseesneceeeeaeceeeeeereeseees E 5 E 2 3 2 UNIX or Windows NT server Intallations cccccccccccesesseececeessseeeeees E 11 E 2 4 Windows Client and UNIX or Windows NT Server Installations E 14 E 2 4 1 UNIX Server Machine Installations ccccccsccccesesssccececesseeeecesesseeeees E 14 E 2 4 2 Windows NT Server and Windows Client Installations ccccccceee E 18 E 2 4 3 Windows client Installations ccccccccecesssceceecsesssseecesesssaeccecessaeeeeees E 20 E 25 Setting Upa User ACCOUNT iio ct eee hoi n E AE KESS E 21 E 2 6 Setting Up the User Environment 00 cece eeseeececeesceeceseeeeeceesaecnseeaeensensees E 21 E 2 7 Designating the Host File System 0 0 eee ceeeeeeeeeeseeceeeseecaeceseesesnseeseeneees E 22 E 3Filename Erans lations ES E sh eth E EEE odes Bi eee es eed E 24 E 4 Configuration File Variables 0 0 ceececseceseeseceseeeecesceeeseneeeeecaecsaesaeceecsaessenseeaeeees E 25 A SYB ADD AIDEN TILEY Jstecnicds aero sess eae en ee E 25 A SYB ADD TIMES TA MBP 2s ciccicsset ct AE E cost euece E N SN E 25 A SYB CHECK D
130. Database ID of 0 instead of the actual ID of the database While the default value is Off false no this configuration variable can also take the value of On true yes A_SYB_NO_RECORD_LOCKS Setting this variable ON causes all READS to be treated as READ NO LOCK which can improve performance but has the obvious consequences While the default value is Off false no this configuration variable can also take the value of On true yes Configuration File Variables m E 37 A_SYB_NO_TABLE_LOCKS Setting this variable ON causes the interface not to use the AcuOpenTables table which causes all table locking to be disabled This can improve performance on OPEN and CLOSE statements While the default value is Off false no this configuration variable can also take the value of On true yes A_SYB_NO_23_ON_START When A_SYB_NO_23_ON_START is set to a nonzero value START does not detect whether records actually exist Because it does not detect the existence of records it is possible when using this variable to do a START without error and for the next READ NEXT to return END_OF_FILE contrary to the ANSI standard Example A_SYB_NO_23_ON_START number where number can be a zero or nonzero value While the default value is 0 off false no this configuration variable can also take values of the value of On yes true A_SYB_PACKETSIZE A_
131. E 37 A SYB PASSWD ine n a onan plete deel adele eae eae E 38 Contents ix A SYB ROWCOUNT secant adic Gada Sean E E EEATT E EES E 39 A SYB SELECT KEY ONL Yonenn a E A E Sa E 39 A SYB SKIP ALTERNATE KEYS eneren ie eee ar errerik ikes E 40 A SYB TRANSLATE TO ANS a E E sien Hse E E 40 AUSYB UNLOCK ON FXAPCO UTE aTa a E EE ae E A PEE ai iieiea E 41 A_ SYB_USE_DROPDOWN_QUERIES cee eecceesceseceseeesseeenceceeeeeneceeeecereeeneeeenees E 41 A SYB_MVISION LOCKS FILE peran ena sittin A A ER E 42 E 5 Record and Table Locking sciis ienesis er nocens niee s renra e nas oe E 43 E 6 otored M anO E0 NET S ER E E N E 45 E 6 1 Developer or Site supplied Stored Procedures seeeesseeesseeseeesreresrerrseseseees E 46 E 6 2 Built in Stored Procedures cccceccccsssececsececessececesceceseececesaeceseaeecesneeeseaeesnsaees E 51 E7 Enmits and Ranges nnn N E sii aes eect earns eees E 52 ES Runtime Brrr AAE E T ETERA Mech O EE E E OEE EE E E EE E 53 E 9 Common Questions and Answers esssseessesesseeesteseretssreesseesesessereesreeesrreesresereesrreessee E 56 Appendix F Acu4GL for DB2 Information F 1 DB2 Concepts Overview aneii ere E r Naa Ea SE Ee ES EE EREE ERT eNi F 2 F2 Installation and Setpoint oei ee o E i a TEE O EE a F 6 F 2 1 Windows Installation eeeeseeeesseesesseesesesesreeerrsreerssreresrsrestesesresrerrseetsrentesrereersse F 6 F 2 2 UNIX Installation Steps iieiea ose eo etss EE EESE Ean En Eser F 7 F 2
132. E AFTER VALUE D 01 FILE RECORD PIC X MAX RECORD SIZE 01 ERROR CODE PIC 99 You can use CSPARAMSIZE to determine the size of the record passed in case you have variable length records See Appendix I Library Routines in Book 4 of the ACUCOBOL GT documentation set for more information on C PARAMSIZE e n cases where the record size is known the actual record is passed READ AFTER all WRITE BEFORE WRITE AFTER REWRITE BEFORE REWRITE AFTER e In cases where the record size is not known the maximum record size is passed READ BEFORE all DELETE BEFORE DELETE AFTER 4 8 m Using Directives The contents of this field will be identical to the record area given to the file operation The BEFORE images will have the value before the file operation and the AFTER images will have the value after the file operation Use the ERROR CODE parameter to signal to Acu4GL that an error occurred e If you set this parameter ina BEFORE trigger the file operation will not execute e If you set this parameter in an AFTER trigger the runtime will treat the file operation as an error though in fact the file operation did execute This means that for sequential access next or previous the file position has changed and a subsequent next or previous will act as if the prior file operation succeeded Also if you set an error in the REWRITE AFTER or DELETE AFTER the record will not return to
133. ELETE SP ir eae eni peenes ie orea ape eaea eoet aaee E 26 A SYB CHECK INSERT OP a E a aE n E 26 A SYB CHECK R ADOP a aE a uae E a E 26 A SYB CHECK UPDATE SP ena R Aaa EE R aTe SaS E 27 A_SYB_CURSOR_OPTION_1 A_SYB_CURSOR_OPTION_2 ASSYB CURSOR OPTIONS serinin r E S E E EREE E 27 A SYB DATABASE hn tao a NE O E IS E 28 A_SYB DEADLOCK LOOPS keciren eresien ee ee Eae a e a E 28 A_SYB_DEFAULT_ CONNECTION io scccscccscssctssceessosecustesseeteseedsosassoesesapesceerceenesssoes E 29 A SYB EXTRA PROC 15055 tl bce aia wiaidheeia cei a E a Me ees E 30 A SYB FAST ACCESS raai ar oter E eor e ae oe eis E 31 A SYB FORCED INDEX e a Sit din he A ene aie E 32 A SYB COCR DBi a e eaa e p O o NE HSS E 33 A SYB LOGIN iy A E E even ee E E eden E eee E 33 AcSSY BMAX CHARACTERS e eee ie remei e a EE EA EEA E 34 A SYB MAX COLUMNS oi e a a E E S SEa roren E 34 AS SYB NATIVE LOCK TIMEOUD iepenens er i ooa e e E 35 A SYB NO COUNT CHECK criera tar n E none tbat S a i R E 36 A SYB NO DBCLOSE eesi ienie aoste e ene Goes E a EEE E 36 A SYB NO DBID ennyire i e Er e EE E EE EE E TE E 36 A SYB NO RECORD LOCKS veronii eese epen uenho ro eo eea rE Te E 36 A SYB NO TABLE LOCKS eriei osae sss eroe sce sssba seca sous sascs iia opb E EnS r OKEE Ts Eoo EES iin E 37 A SYB NO 23 ON STAR yess cesicih ceasing raritne nen oranana e eA rE E E Eaa E 37 A SYB PACKET SIZE os iccicssecivissseesssiatse veststbvteesaduhsees dicniincs i EE E sees ete EEE REES
134. ES configuration variables F 26 A_INF_DUPLICATE_KEY configuration variable A 9 A_INF_NO_FINAL_TRANSACTION_ERROR configuration variable A 10 A_INFORMIX_ERROR_FILE configuration variable A 11 A_MSSQL_ADD_IDENTITY configuration variable B 11 A_MSSQL_ADD_TIMESTAMP configuration variable B 11 A_MSSQL_APPROLE_NAME configuration variable B 12 A_MSSQL_APPROLE_PASSWD configuration variable B 12 A_MSSQL_CURSOR_OPTION configuration variable B 13 A_MSSQL_DATABASE configuration variable B 14 A_MSSQL_DEADLOCK_LOOPS configuration variable B 14 A_MSSQL_DEFAULT_CONNECTION configuration variable B 15 A_MSSQL_DEFAULT_OWNER configuration variable B 15 A_MSSQL_FAST_ACCESS configuration variable B 16 A_MSSQL_LOCK_DB configuration variable B 17 A_MSSQL_LOGIN configuration variable B 18 A_MSSQL_MAX_ CHARACTERS configuration variable B 18 A_MSSQL_MAX_COLUMNS configuration variable B 19 A_MSSQL_NATIVE_LOCK_TIMEOUT configuration variable B 19 A_MSSQL_NO_23_ON_START configuration variable B 21 A_MSSQL_NO_COUNT_CHECK configuration variable B 20 A_MSSQL_NO_DBID configuration variable B 21 A_MSSQL_NO_RECORD_LOCKS configuration variable B 21 A_MSSQL_NO_TABLE LOCKS configuration variable B 21 A_MSSQL_NT_AUTHENTICATION configuration variable B 22 A_MSSQL_PACKETSIZE configuration variable B 22 A_MSSQL_PASSWD configuration variable B 23 m Index 3 A_MSSQL_ROWCOUNT configuration variable B 24 A_MSSQL_SELECT_KEY_ONLY configuration variable B 24 A_MSSQL_SKIP
135. ES to 0 because a fewer number of queries need to be sent to the database On the other hand if you START files and stop reading after some condition but haven t used the WHERE constraint then you may get more efficient access by setting this variable to 1 and using the drop down style of query In either case we recommend that you run some tests to see which value of this variable makes the most sense for your application While the default value is 0 off false no this configuration variable can also take the value of On true yes Example A_SYB_USE_DROPDOWN_QUERIES number where number is a zero or nonzero value A_SYB_VISION_LOCKS_FILE This is one of two locking methods available with Acu4GL The methods are accessed via two configuration variables A_SYB_VISION_LOCKS_FILE and A_SYB_NATIVE_LOCK_TIMEOUT The lock method used is determined as follows if A_SYB_VISION_LOCKS_ FILE is set to the name of a Vision file that can be open I O and has the correct structure this method is used if ALSYB_NATIVE_LOCK_TIMEOUT is set to a positive value then this method is used Otherwise the AcuLocks table is used to hold locks A_SYB_VISION_LOCKS_FILE causes the lock table AcuLocks to be a Vision file instead of an SQL table This can be accessed via the configuration variable A_LSYB_VISION_LOCKS_FILE which must be set to the name of the Vision file that will hold the lock information Note tha
136. EXT without a START immediately after opening a file Example In your COBOL program you include this statement Troubleshooting m 9 11 Move ftest_key gt 3 and ftest_key lt 6 to A4GL_WHERE_CONSTRAINT Inspect A4GL_WHERE_CONSTRAINT replacing trailing spaces by low values START FTEST FILE KEY NOT LESS FTEST KEY These results occur CURSOR 0 SELECT ROWID FROM ftest WHERE ftest_keyl_segl AND ftest_keyl_seg2 gt AND ftest_key gt 3 and ftest_key lt 6 ORDER BY ftest_keyl_segl ASC ftest_keyl_seg2 ASC CURSOR 1 SELECT ROWID FROM ftest WHERE ftest_keyl_segl gt AND ftest_key gt 3 and ftest_key lt 6 ORDER BY ftest_keyl_segl ASC ftest_keyl_seg2 ASC Limitations e WHERE constraints added by the COBOL program may not be portable between databases e The application may specify conditions of such complexity that they confuse the database query optimizer resulting in poor performance Be sure to examine the results of the optimizer trace facilities to ensure optimal performance e Take care to prevent the COBOL application from sending information that will result in a syntax error that will not be detected until runtime e The WHERE constraint should reference only columns in the primary table 9 2 Troubleshooting The remainder of this chapter lists the possible error messages that can occur during compilation Recommended recovery procedures are given for each situation 9 1
137. EY1 SEG1 FTEST2 KEY1 SEG2 01 0 004 00008 hb oO FTEST2 ALTKEY2 000 0006 00006 00000 00004 16 00004 00 000 000 FIEST2 KEY 00004 00002 16 00002 00 000 000 FTEST2 KEY1 SEG1 00006 00002 16 00002 00 000 000 FTEST2 KEY1 SEG2 00008 00004 16 00004 00 000 000 FTEST2 ALTKEY2 00012 00009 00 00009 00 000 000 FTEST2 NUMBER 00021 00010 16 00010 00 000 000 FTEST2 INFO tablename_insert tablename_insett is used to WRITE a record to the file The parameters passed to the stored procedure are the values of all the columns in the row in the order of the columns in the database The timestamp column and identity column if present in the table are not passed to the stored procedure Given the XFD above you might want to create the following stored procedure for writing records to a file create procedure ftestdat_insert ft2_key char 4 f t2_keyl_segl char 2 f t2_keyl_seg2 char 2 ft2_altkey2 char 4 E 48 m Acu4GL for Sybase Information ft2_number char 9 ft2_info char 10 as insert into ftestdat ftest2_key ftest2_keyl_segl ftest2_keyl_seg2 ftest2_altkey2 ftest2_number ftest2_info values ft2_key ft2_keyl_segl ft2_keyl_seg2 ft2_altkey2 ft2_number ft2_info grant execute on ftestdat_insert to public tablename_delete tablename_delete is used to DELETE a record from the file The parameters passed to the stored procedure are the values of
138. Environment e Designating the Host File System The Microsoft SQL Server RDBMS version 6 5 or later must be installed and configured prior to the installation of Acu4GL for Microsoft SQL Server Microsoft SQL Server s Query Analyzer product an interactive query tool is also necessary for installing the ACUCOBOL GT stored procedures Micro Focus does not provide these products Note The default sort order for Microsoft SQL Server is case independent Make sure that this is what you really want when you install the server Acu4GL for Microsoft SQL Server will use the sort order as installed and cannot change its behavior to do case dependent ordering if that is not what the server uses First you must install the files from the extend installation media onto the client machine Then follow the instructions below for the server machine Final setup steps on the client machine complete the installation Be sure to use the 64 bit libraries with a 64 bit runtime and 64 bit Acu4GL for Microsoft SQL Server and the 32 bit libraries with a 32 bit runtime and 32 bit Acu4GL for SQL Server Installation and Setup m B 5 B 2 1 Installing on a Client Machine The Acu4GL interface for Microsoft SQL Server is an add on module The product installation includes a DLL file that is detected at run time It is not necessary for 32 bit users to relink the runtime Acu4GL for SQL Server can be executed on a machine that is running an
139. Existing Text Fields oes cececeeeeeeceseeeeeeseeseecsecnseenees 7 3 7 3 2 How Do I Match Existing Numeric Fields 00 eee cee eeceeeseeeeeeseeesecneeeaeesees 7 3 P33 Field Names cs so dB secs scecsscoe sos n a a E a e a RE E E 7 4 Bis NG 016 gt Gal NF 11 Uc er oO a aaa r r R AEE EN 7 4 Contents iii Chapter 8 Compiler and Runtime Options 8 1 Compiler Options isc ceninin esse cee bbec eb hs aon Ss seid Sek casks Voere Eea lee EEIE OSEE EESE 8 2 8 2 Runtime Configuration Variables oo cece eeeececeeeeeeeeeeeseeceeesaeceesaeeseseseeseeeeseaeeeeeens 8 4 AGL 2000 CUTOF E io issgeech Sass atistinties th EEE AE sine pointe dels QUE ive a 8 5 AGI 28 DIGIT CU TO T 2 sic 35 ssscoes tabcsscoehfsscpessend tictaces iste sts EEEE rea Er EST pea ieres Seis TRE SES SS 8 5 4G COLUMN CASE toopae aii ie ciate Se a ae eh eee 8 6 AGILE COMMIT COUNT ti cruss 2 iicvthe E E E SE A EE E A EN es 8 6 4GL CONVERT DATE ZERO a ee S eae ES ERNE AENA E 8 8 AGL DBR MA Pict a toed vert cadectiy duces epstectivande slvences epevecbensepesvepensanedeebel E a rE TES SEERE SE 8 8 4GL EXTRA DB COLS OK ae S ESE eE 8 9 4GL FULLE DATA TES Eriin e E AN 8 10 AGL IGNORED SUFFIX LIST eepe eiar E e rE EE aE EE EE r EES E EEEE 8 10 4GL ILLEGAL DATA e re Ra ns ain bathe eed AiG E EA a 8 11 AGL JULIAN BAS E DA E ssc r a aaa par a E Ep iore E iS ELISE EEE inat SES 8 11 AGL USEDIR LEVE arerio heo naien e en E A a o E e e E 8 12 AGL WHERE CONSTRAINT o
140. FAULT_HOST configuration variable 1 12 1 15 8 13 defaults XFDs 3 5 definitions record 3 5 demo cbl demonstration program 2 6 demonstration program compiling 2 7 Help menu 2 11 Options menu 2 11 overview 2 6 Position menu 2 10 Record menu 2 9 running 2 8 m Index 17 runtime verification 2 7 starting 2 8 designating databases Acu4GL for Informix A 8 designating host data source DB2 F 13 ODBC D 16 designating host file system DB2 F 11 Oracle C 17 SQL Server B 8 Sybase E 22 dictionaries data Acu4GL 1 8 creating 1 12 overview 1 11 source code 4 3 XFDs 3 1 dictionary fields summary 3 7 directives and existing data 7 3 ANSI compliant 4 3 introduction 4 2 syntax 4 3 directives list of ALPHA 4 5 BINARY 4 6 COBOL TRIGGER 4 7 COMMENT 4 8 DATE 4 9 FILE 3 11 4 12 NAME 3 8 4 13 NUMERIC 4 16 SECONDARY_TABLE 4 17 USE GROUP 4 6 4 18 VAR_LENGTH 4 6 4 20 Index 18 m WHEN 3 5 4 20 document overview 1 3 drivers ODBC general information D 6 managing D 6 requirements D 36 testing D 37 duplicate field names 3 8 E environment setting up user Acu4GL for DB2 F 10 Acu4GL for ODBC D 14 Acu4GL for Oracle C 16 Acu4GL for SQL Server B 7 Acu4GL for Sybase E 21 error descriptions extended 1 15 ERROR CODE parameter 4 8 errors compile 9 12 extended descriptions for 1 15 errors runtime DB2 F 31 Informix 9 15 9 19 A 23 ODBC D 42 Oracle C 30 SQL Server B 39 Sybase E 54 existing database files
141. For example the size of your page affects the maximum row size Some limits are given here but please refer to your database documentation for additional information Page Size Maximum Maximum Maximum Index Row Size Column Count Size 4K 4 005 500 255 8K 8 101 1 012 16K 16 293 1 012 32K 32 677 1 012 To achieve the same sort or retrieval sequence under DB2 as under the Vision file system place a BINARY directive immediately before each key field that contains signed numeric data High values and low values can cause problems in key fields If you want data that uses the BINARY directive to be stored as hexadecimal encoded CHAR types you can specify A_DB2_USE_CHAR_FOR_BINARY in the configuration file Other limits are described in Appendix B in Book 4 Appendices of the ACUCOBOL GT documentation Data Type Mapping m F 29 F 8 Data Type Mapping DB2 data types must be mapped to COBOL data types In the table below please note that directives have been applied to the COBOL data types See Chapter 4 for additional information on directives COBOL Data Type Acu4GL for DB2 binary BINARY directive char 2 x applied varchar VAR_LENGTH varchar directive applied pic x 255 or greater must apply VAR_LENGTH directive Mapping DB2 data types to COBOL data types Sometimes developers are in a situation where they need to create a COBOL File Description based on an existing data source table The most important thing
142. GL Overview 1 3 2 Data Dictionaries and Acu4GL An Acu4GL product uses data dictionaries created by the ACUCOBOL GT compiler These dictionaries map COBOL records into database fields and map the database fields back into records Data dictionaries are also known as XFDs eXtended File Descriptors COBOL records Database fields Acu4GL ACUCOBOL GT data dictionaries The following sections describe the Acu4GL products and explain how they interface to database systems by referencing data dictionaries Interfaces to indexed file systems such as Vision and C ISAM do not require data dictionaries because they are record oriented systems but they can be used by the indexed file editor alfred to view records in these alternate file systems 1 3 3 The ACUCOBOL GT Web Runtime and Acu4GL The ACUCOBOL GT Web Runtime is enabled for Acu4GL In essence if an Acu4GL dll file is in the path and the Acu4GL license with the same base name is in the Web runtime directory and the appropriate configuration file options are set the Web runtime can take advantage of the acu4GL interface Database Concepts m 1 9 The particular dll files for supported 32 bit runtimes are as follows a4ora32 dll Acu4GL for Oracle a4sql32 dll Acu4GL for Microsoft SQL Server adsyb32 dll Acu4GL for Sybase a4db232 dll Acu4GL for DB2 a4odbc32 dll Acu4GL for ODBC Note Microsoft Internet Explorer Version 5 5 Se
143. GL_COMMIT_COUNT is met regardless of the current transaction state When A_ODBC_ALTERNATE_ COMMIT_LOGIC is set to 1 the value of 4GL_COMMIT_COUNT is checked after each WRITE REWRITE DELETE or UNLOCK operation A commit is issued however only if the runtime is not currently in a transaction D 20 m Acu4GL for ODBC Information Example 4GL_COMMIT_COUNT 1 A_ODBC_ALTERNATE_COMMIT_LOGIC 0 Each WRITE operation is committed to the database immediately This prevents an application from being able to rollback a WRITE See Also 4GL_COMMIT_COUNT runtime configuration variable A_ODBC_ALTERNATE_COMMIT_LOGIC configuration variable A_ODBC_CATALOG This variable indicates the catalog name to be used when Acu4GL searches for objects in the database Note that not all data sources will support a catalog Using A_ODBC_CATALOG with other variables such as USER_PATH and ALODBC_TABLE_TYPES can speed up the finding of tables in large databases It can also prevent an error 9D 14 More than one table with the same name thereby enabling access to tables with identical names but with different catalogs For example If USER_PATH and A_LODBC_CATALOG are used the form of the SQL statement will be modified from select COL1 from TABLENAME to SELECT COL1 FROM catalog username TABLENAME where catalog and username will be filled in if provided See Also USER_PATH configuration var
144. Glossary 5 relational database A database system in which any database file can be a component of more than one of the database s tables Relational database management systems may be referred to as RDBMSs server A computer that makes services as access to data files programs and peripheral devices available to workstations on a network Contrast client See also network SQL Structured Query Language Structured Query Language According to specification the language by which ODBC programs retrieve data See also query TAR format Tape Archive format A general purpose archive utility and file format used in UNIX environments TAR was originally intended for use with magnetic tape but though it has several command line options related to tape it is now used more often for packaging files together on other media for example for distribution on the Internet The resulting archive a tar file is often compressed using gzip or some other form of compression TCP IP Transfer Control Protocol Internet Protocol A protocol for communication between computers used as a standard for transmitting data over networks and as the basis for standard Internet protocols XFD file Extended File Descriptors Data dictionaries are also called extended file descriptors XFDs because they re based on the standard COBOL file descriptors FDs See also data dictionaries and file descriptor Glossary 6 m Index
145. HECK READ SPis set to False The default is True yes on 1 to check for the stored procedure A_SYB_CHECK_UPDATE_SP This configuration variable controls whether the Acu4GL for Sybase interface checks for the tablename_update stored procedure when opening a table If A SYB_CHECK_UPDATE SP is set to False no off 0 the Acu4GL interface does not check for the stored procedure Therefore even if tablename_update exists it is not used if A_SYB_CHECK_UPDATE_SP is set to False The default is True yes on 1 to check for the stored procedure A_SYB_CURSOR_OPTION_1 A_SYB_CURSOR_OPTION_2 A_SYB_CURSOR_OPTION_3 These configuration variables allow you to fine tune the declaration of cursors in the Acu4GL for Sybase product In general cursors are declared with the following syntax DECLARE cursor_name option_1 CURSOR option_2 FOR lt select gt option_3 In other words different phrases can go in each of the option_X places Also different versions of Sybase allow different options in each of those places Because of this the Acu4GL product allows customization of the cursor declaration via these three variables The values of these variables are placed verbatim into the declare phrase when building a cursor Note that any errors in the values of these variables may make your Acu4GL product inoperable You should refer to the Sybase documentation to determine what phrases are allowed in each case
146. HOST variable is set in the runtime configuration file or the environment Setting DEFAULT_HOST in the environment overrides the setting in the runtime configuration file Enter one of the following commands depending on your operating system For UNIX systems runcbl vv For Windows systems wrun32 vv to make sure that the version number of the Acu4GL interface for your RDBMS is reported This tells you that the Acu4GL product has been installed successfully Questions and Answers m 10 3 Question Question Note In Windows environments if vv does not return the Acu4GL product information make sure the runtime has the name you used and is the first so named executable on the PATH and that the dll is in the same directory If you are running Acu4GL for Sybase and vv does not return the Sybase Acu4GL product information make sure the linked runtime has the name you used and is the first so named executable on the PATH If you cannot locate a runtime that displays a Sybase Acu4GL product version number using vv you must create one by re linking the runtime If you must do that make sure that USE_SYBASE is set to 1 in the file filetbl c before you relink Can I use both an RDBMS or ODBC data source and Vision at the same time Yes you can In the configuration file set DEFAULT_HOST to the file system you want the runtime to use automatically Then for select file
147. ILE E PERMISSION E_NO_SUPPORT E_NO_LOCKS The file DB2 err contains some initial file error mappings A_DB2_ISOLATION_LEVEL Use the A_DB2_ISOLATION_LEVEL configuration variable to set the isolation level The default ordering of isolation levels is SQL_TXN_READ COMMITTED SQL_TXN_READ_ UNCOMMITTED SQL_TXN_REPEATABLE READ SQL_TXN_SERIALIZABLE You can change the isolation level by setting the configuration variable A_DB2_ISOLATION_LEVEL to an integer in the configuration file The settings are Isolation level Setting in configuration file For example to set the isolation level to SQL_TXN_READ_COMMITTED add the following entry to the configuration file A_DB2_ISOLATION_LEVEL 2 If the user set isolation level is not supported by the driver the default method of selecting a level is used F 20 m Acu4GL for DB2 Information A_DB2_LOCK_METHOD Use this variable to specify the locking method that Acu4GL for DB2 should use when accessing your data source Possible values are none SETPOS SETSTMTOPTION UPDATECOLUMN The default is UPDATECOLUMN Example A_DB2_LOCK_METHOD UPDATECOLUMN SETPOS Specify SETPOS as your lock method to tell Acu4GL for DB2 to perform the following locking sequence When setting up a statement handle for accessing the DB2 data source the Acu4GL product calls a function called SQLSetScrollOptions with values SQL CONCUR LOCK SQL SCRO
148. ITs are issued by Acu4GL for ODBC See 4GL_COMMIT_COUNT in Chapter 8 for additional information e A_ODBC_STRICT_EQUAL is most useful with alternate keys that allow duplicates Note This same behavior can be accomplished with the 4GL_WHERE_CONSTRAINT but using A_LODBC_STRICT_EQUAL requires less programming While the default value is False off no 0 this configuration variable can also take the value True on yes 1 A_ODBC_TABLE_TYPES This variable is used to specify a table type TABLE VIEW and so forth that should be looked for when selecting a database table Using A_ODBC_TABLE_TYPES with other variables such as USER_PATH and A_ODBC_CATALOG can speed up the finding of tables in large databases D 30 m Acu4GL for ODBC Information This information will be passed to the API function call SQLTables as the TableType parameter Please refer to your driver s documentation for supported types Example A_ODBC_TABLE_TYPES TABLE VIEW See also USER_PATH configuration variable A_ODBC_CATALOG configuration variable A_ODBC_UNSIGNED_TINYINT Some ODBC drivers may assign the TINYINT data type a signed 1 byte variable that can store values from 128 to 127 to an internal unsigned type that can store values from 0 to 255 To determine if your ODBC driver does this set a PIC s99 variable to a negative value and then write a record Ifa value out of range message is returned you must set
149. If the USER_PATH and A_DB2_CATALOG are used the form of the SQL statement will be modified from F 16 m Acu4GL for DB2 Information select COL1 from TABLENAME to SELECT COL1 FROM catalog username TABLENAME where catalog and username will be filled in if provided See Also USER_PATH configuration variable A_DB2_TABLE_TYPES configuration variable A_DB2_COMMIT_ON_BEGIN DB2 has no START TRANSACTION method Everything since the last COMMIT or ROLLBACK is considered part of the current transaction To ensure that the previous transaction has been ended before a new one begins set A_DB2_COMMIT_ON_BEGIN to a nonzero value This causes each COBOL START TRANSACTION to first issue a COMMIT This ensures that the previous transaction has been ended before the new one starts If this variable is not set or is set to 0 a COBOL ROLLBACK may affect file I O that occurred before the most recent COBOL START TRANSACTION While the default value is 0 off false no this configuration variable can also take values of On true yes A_DB2_DATASOURCE Set A_DB2_ DATASOURCE to the exact name of the host data source You can set this variable in your COBOL configuration file if you will be using only one data source Example A_DB2_DATASOURCE stores Configuration File Variables m F 17 If you do not know the data source name in advance or if you intend to use more than one data
150. If you want to delete the table you created enter the following command DROP TABLE newtab 2 4 2 To Call sql acu From a Program You can also call sql acu from within a COBOL program The syntax is call sql acu using mysql command The SQL command may be up to 50 000 characters and may be a variable or a quoted command string in the CALL statement Note The sql acu utility may be used only with SQL commands that are data definition statements those that do not return data Be sure to end each SQL command with a semicolon 3 Using the sql acu Program m 2 5 Example IDENTIFICATION DIVISION program id command the sql acu command to issue data definition commands to the RDBMS DATA DIVISION working storage section 01 sql command pic x15 01 error status 03 primary error pic x 2 03 secondary error pic x 40 01 error text pic x 40 01 error window pic x 10 PROCEDURE DIVISION main logic display window erase display window line 20 column 2 size 75 lines 3 boxed top title SQL COMMAND bottom right title Return to exit perform do sql command with test after until sql command spaces stop run do sql command accept sql command line 1 column 1 erase to end of line if sql command not spaces call sql acu using sql command if return code not zero perform show error show error display window line 2 column 2 size 75 lines 6 boxed erase pop up are
151. L product and the database engine We ll ask and answer questions of that type in the next few sections 7 2 Default Acu4GL Behavior The following are automatically handled by the Acu4GL product e Acu4GL automatically converts upper case field names to lower case or vice versa when necessary so don t concern yourself with case differences e Acu4GL automatically performs the data conversions needed to match the internal storage formats used by the database e Ifthe database files don t already exist they will be created for you automatically when you execute an OPEN OUTPUT verb If this is your situation you ll have no concerns about matching COBOL fields to database fields The fields will match perfectly because the database fields will be based on your COBOL code e You may encounter unexpected sequencing of data returned from a database If your COBOL definition does not include alternate keys with duplicates the data is returned in key order If your COBOL definition does include alternate keys with duplicates be aware that Acu4GL cannot control the sequence in which the data is returned The database Accessing Existing Database Files m 7 3 query optimizer decides how to order the returned records For a set of records with the same key value the records may not be in historical order See also A_MSSQL_ADD_IDENTITY A_SYB_ADD_IDENTITY A_INF_DUPLICATE_KEY 7 3 Accessing Existing Database Files If y
152. L for Sybase UNIX only All files in the lib subdirectory of your ACUCOBOL GT distribution sub c sub85 c filetbl c config85 c sub h From your Acu4GL media you need sybase o From Sybase you need the platform specific Open Client DB Library C product Instructions for linking are given in the installation portion of this appendix Common Questions and Answers m E 57 Question Question Question Question Question When I try to open a file for output I get the error 9D 2714 There is already an object named in the database Why One of your record s data items probably has the same name as a Sybase reserved word Locate the column by comparing a file trace of the CREATE TABLE to Sybase s list of reserved words Apply the NAME directive to the field in the FD that is associated with the invalid column then recompile the program to create a new XFD file Can I open tables in different databases Yes Use a file name like database owner tablenam Note that because Acu4GL for Sybase automatically determines an owner you can also specify a file name like database tablename The two dots are mandatory in this case Can I use multiple servers on the same machine or on different machines on my network Yes Each server has a unique name To see if the necessary setup has been performed enter isql S servername If this connects you to the server you want you can
153. LL KEYSET DRIVEN 1 When fetching rows from the data source the Acu4GL product calls SQLExtendedFetch instead of SQLFetch Finally it calls SQLSetPos with the values 1 SQL POSITION SQL LOCK EXCLUSIVE If any of these functions do not exist A_DB2_LOCK_METHOD reverts to none Note Even if these functions do exist there is no guarantee that any rows will be locked using this sequence of calls Contact your database vendor to determine whether or not this sequence will be effective for your data source Configuration File Variables m F 21 SETSTMTOPTION This option is similar to SETPOS except a function called SQLSetStmtOption performs the task of SQLSetScrollOptions and has more functionality In particular when using this method of locking the Acu4GL product will call SQLSetStmtOption a number of times with values SQL CONCURRENCY SQL CONCUR LOCK SQL CURSOR TYPES SQL CURSOR KEYSET DRIVEN and SQL_KEYSET SIZE 1 Again if the function does not exist A_DB2_LOCK_METHOD reverts to none UPDATECOLUMN Specifying UPDATECOLUMN as your lock method performs an entirely different type of locking Instead of trying to lock a row while reading it this method creates a new statement handle for the data source Then after fetching the data from the data source it resubmits an SQL query to select the same row based on the primary key and adds an UPDATE clause Last it fetches the data from the data source
154. LUMNS For some large databases the API function SQLColumns which is called to get a description of the columns in a table sometimes takes a long time to execute If you are experiencing such problems you can use the API function call SQLDescribeCol instead which can improve performance for large databases To turn on this new functionality set the A_DB2_USE_SQLCOLUMNS configuration variable to FALSE The default value of this variable is TRUE F 26 m Acu4GL for DB2 Information A_DB2_USE_SQLTABLES For some large databases the API function SQLTables which is called to get a list of the tables and information about them sometimes takes a long time to execute If you are experiencing such problems you can instruct the interface to build a test SQL query and use the API function call SQLNumResultTables to determine if the table exists This may improve performance for large databases To turn on this new functionality set the A_DB2_USE_SQLTABLES configuration variable to FALSE The default value of this variable is TRUE which means the interface will use the SQLTables API function USER_PATH USER_PATH indicates the user name or names schemas to be used when Acu4GL searches for files The order of the names is significant The syntax for this variable is USER_PATH userl user2 where the user argument may be either the name of a user schema on the 6699 system or a period which in
155. MEOUT The lock method used is determined as follows If A_SYB_VISION_LOCKS_ FILE is set to the name of a Vision file that can be open I O and has the correct structure the Vision file is used to hold lock information If ALSYB_NATIVE_LOCK_TIMEOUT is set to a positive value native locking is used Otherwise the AcuLocks table is used to hold locks This locking method enables you to use Sybase native locks if you explicitly code transactions in your COBOL program You can access this method by setting the configuration variable A_SYB_NATIVE_LOCK_TIMEOUT to a positive value This value will be the number of seconds that a connection will wait for a timeout to occur When such a timeout occurs for any reason the Acu4GL product assumes that the timeout was caused by a locked record and will return error 99 record locked If you set this variable but do not explicitly code transactions in your COBOL program record locking does not occur Note that the Acu4GL product will wait the number of seconds specified and your application may seem to hang if the timeout is too long On the other hand if the timeout is too short you may get record locked errors when the network is slow Sybase uses a page locking mechanism and so this method of locking records may cause your application to return spurious record locked errors because of a record being locked on the same page as the record you are trying to access If a future version of Sybase imple
156. NES whose field names are more meaningful than the fields they redefine you might consider switching the order of your code rather than using a WHEN directive Use the less significant field names in the REDEFINES For example you might change this 03 code info 05 filler pic 9 8 05 code 1 pic x 10 03 patient info redefines code info 05 patient id pic 9 4 05 service code pic 9 8 05 server name pic x 6 to this 03 patient info 05 patient id pic 9 4 05 service code pic 9 8 05 server name pic x 6 03 code info redefines patient info 05 filler pic 9 8 05 code 1 pic x 10 The fields that would appear in the database table by default are underlined above This shows how the column names might become more meaningful when the order is reversed Your application operates the same either way Note When a WHEN directive condition is met COBOL record definitions or REDEFINES records that are subordinate to other WHEN directives are not used Database columns in rows that correspond to those records are set to the special database value NULL This means that there is no value provided for those columns NULL is not equivalent to zero and it has special properties in the RDBMS For example you can select all rows for which a given column is NULL 4 26 m Using Directives Example 4 This COBOL code 01 col type pic x Sxfd when col type a 03 defl pic x 2 Sxfd when col type b
157. NMENT filename_HOST TO filesystem or SET ENVIRONMENT DEFAULT_HOST TO filesystem This enables you to change file systems during the execution of your program This is not the typical way to specify a file system normally it is designated in the runtime configuration file and is not changed in the COBOL program Note The interface to Sybase allows you to create a Sybase table with an OPEN OUTPUT statement just as you can create Vision indexed files The Sybase equivalent of a Vision file is a table not a database You need to create a database for your Sybase tables before you run the COBOL program that creates the tables just as you need to create a directory for your files before you run a COBOL program that creates Vision files E 24 m Acu4GL for Sybase Information You are now ready to use the sql acu program You can find information on this program in section 2 4 Using the sql acu Program After you learn about and use this utility you will next find out about preparing and compiling your COBOL program followed by learning to use the demonstration program See section 6 1 Preparing and Compiling Your COBOL Program and section 2 5 The Demonstration Program for additional information E 3 Filename Translation As you prepare to work with Acu4GL for Sybase you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD
158. NTERVAL BLOB FLOAT SMALLFLOAT Acu4GL for Informix supports the following data types conversions between COBOL and database formats are as shown COBOL to INFORMIX PIC X CHAR PIC XX VARCHAR PIC 9 PIC 99X PIC 999 PIC 9999 SMALLINT PIC 9 5 PIC 9 6 PIC 9 7 X PIC 9 8 PIC 9 9 All other PIC 9 s DECIMAL INTEGER A 22 m Acu4GL for Informix Information INFORMIX to COBOL INTERGERX PIC S9 10 or PIC S9 9 COMP 4 SMALLINT PIC S9 5 or PIC S9 4 COMP 4 DECIMAL 6 2 PIC 4 V99 MONEY 4 PIC 2 V99 SERIAL PIC 9 9 DATE PIC 9 6 or PIC 9 8 DATETIME PIC 9 12 or PIC 9 14 VARCHAR max min PIC X max Opening a file I O exclusive doesn t hold lock on Informix This is a limitation on the way the Informix Acu4GL product works Since we do not do any actual operations on the table except to get information about it Informix does not tell us the file is locked Users should get a lock condition when they do a read with lock Performing error handling on the read write will yield a 99 record locked on any read operation performed even if the file is open for input Other limits are described in Appendix B in Book 4 Appendices of the ACUCOBOL GT documentation A 8 Runtime Errors This section lists the Acu4GL error messages that could occur during execution of your program Chapter 9 provides information on compile time errors and also provides several methods for retrieving runtime erro
159. OBOL GT runtime For the Microsoft Windows environment the driver manager is called ODBC32 DLL for 32 bit architectures The driver manager is typically included with the ODBC driver and is often installed along with the driver For some products such as Microsoft Access and Excel the driver manager is installed automatically if you choose the ODBC support option while installing the product The ODBC support option tends to be part of the custom install process Driver The driver processes ODBC requests and returns data to the driver manager and your application If necessary the driver translates the runtime s SQL request into a form that is understood by the target data source Your application is not limited to communicating through just one driver however By setting the ACUCOBOL GT configuration variable A_ODBC_DATASOURCE you can direct the ACUCOBOL GT runtime to connect to a different driver for any given file Simply set this variable before opening the indexed data file The Acu4GL interface for ODBC will then handle connecting to the new data source and performing any operations necessary to open the file ODBC Concepts m D 7 The driver is the most important feature of ODBC ODBC drivers for a given data source may be available from many different vendors They vary greatly in performance and in the options they provide for a given data source Be sure to carefully review a data source driver to determine its level of
160. OR_BINARY is set to a nonzero value you can store data that uses the BINARY directive as hexadecimal encoded CHAR types This allows you to work around your data source restriction While the default value is 0 off false no this configuration variable can also take values of On true yes Example A_ODBC_USE_CHAR_FOR_BINARY 1 A_ODBC_USE_SPACE_IN_DATES Some ODBC drivers require spaces when sending dates or timestamps to the data source For data sources that require spaces between the qd and the quote set the configuration variable A_ODBC_USE_SPACE_IN_DATES D 32 m Acu4GL for ODBC Information For example Set MYDATE d 1999 3 20 note that there is a space between d and Setting the ALODBC_USE_SPACE_IN_DATES configuration variable to 1 causes the Acu4GL for ODBC product to use syntax as above instead of Set MYDATE d 1999 3 20 note that there is not a space between d and Keep in mind that it is possible that all data sources may allow a space between the d and the and that it is always safe to set this variable While the default value is 0 off false no this configuration variable can also take values of 1 on true yes Example A_ODBC_USE_SPACE_IN_DATES 1 A_ODBC_USE_SQLCOLUMNS For some large databases the API function SQLColumns which is called to get a description of the columns in a table some
161. PATE dnare a tate honk ciate att E EENE C 26 C 6 Using the Database Table vesscsc sccscercsassasscccescestacsessonsostesssisssseasenses desde rare rE tnos Rei Sires C 28 CoP Supported Features isos cick sos conien orior nii ck ews hisses sobs Seca NEE Hees ESTEE C 28 C 8 Limits and Ranges ssi ssc scesdes a asaciseepsaeaabiees sseeeueug cape SA os soba EEE EE EE Tea STE C 29 C9 Rumtamie Errors xcs ics eere airo rer aE a S Siesta ca leek ibe beh csdoke del E ela ER ceed C 30 C 10 Common Questions and ANSWETS ccccessccesseecsesecessececesaeceseeceessseecsesaeeeseeeeeseeeeenegs C 31 Appendix D Acu4GL for ODBC Information D LODBC Concepts airties rererere E eer E ep E a E E o E E a EESTE Esi D 2 D 1 1 W at IS ODBC riunn AAS A ee th ae beta D 2 D 1 2 Origins of ODBC wersy eain pablestevedy ES EE ESE SEa EE ES D 2 D123 Restrictions 2 46124 iis ee es Ble E E Oa as E ae D 3 D J 4 ODBE Structure onre E Un E E A E E R S D 3 D 2 Acu4GL for ODBC Installation and Setup ssseeeseeeeeeseeersreererreseersreererreesesseresseeees D 10 D 2 1 ODBC Installation s i4cc whee Hid Rae dle iand abl E E A cine D 10 D 2 2 Installation of Acu4GL for ODBC ooo ceceseceeceeeeeeeeeeeseecaecseeaeeeensees D 12 D 2 3 Setting Up Data Sources eceseeeecseensecseceecesececeseeseeeseeeaseseesaecaeesaeenees D 12 D 2 4 Setting Up the User Environment 0 0 ice ec eeceeeeeeereeseeceeeseecaecsseesesnseeeeneees D 14 D 2 5 Designating the Host File System e
162. QQ PaidDate The demo program enables you to view or change any of the rows records in the orders table You can also view the source code for the demo program Record Menu Record Posit New Delete Save Exit The choices under the Record menu item offer the following functionality New Clear all fields Delete Remove the order that is being displayed from the database 2 10 m Getting Started Save Write or rewrite the displayed record Exit Exit the demo program and return to the operating system prompt Position Menu Position Optior First Next Previous Last Search The choices under the Position menu item offer the following functionality First View or modify the first record in the file Next View or modify the next record in the sequence Previous View or modify the previous record in the sequence Last View or modify the last record in the file The Demonstration Program m 2 11 Search Enter the order number of the order to be viewed Options Menu Options Help View program The choices under the Options menu item offer the following functionality View program Start the debugger and display the source code Be sure you compiled the program with Zd and execute it with d Help Help brings up a window containing a short description of the demo program 2 12 m Getting Started Data Dictionaries Key Topics Data Dictionarie
163. RDBMS be careful The new software components may interact with your applications differently than their predecessors did This is to be expected It s important to rerun your pre installation simulations see Guideline 4 Plan for growth to determine whether your system resources are still adequate Investigate any differences in the two simulations You may have to make adjustments to compensate for the differences in the RDBMS versions Upgrading or switching to a new database may also mean that you need to modify your makefile to coordinate with the settings of the new database You can edit your makefile manually or use one of the editing tools distributed with Acu4GL For more information see the appendix specific to the Acu4GL interface you are using If you notice a change in performance with a new release of your RDBMS keep in mind that certain database settings can have a significant effect on speed Fine tuning your settings can make a difference Several other options to help you improve performance are listed below e Try one of the many third party monitoring tools available e Break up data onto several connected hard drives to free up space and resources e Limit the number of indexes you have assigned with each database table Performance Issues m 9 7 Guideline 4 Plan for growth We cannot emphasize enough the importance of planning ahead for growth You need to be able to predict the system resources that you
164. SSQL_VISION_LOCKS_FILE which must be set to the name of the Vision file that will hold the lock information Note that you must also set a configuration variable that specifies this file as a Vision file using a _host variable This file must be accessible to all users accessing the Microsoft SQL Server either through a common directory or through AcuServer Also included with the Acu4GL for Microsoft SQL Server product is a small COBOL program that will manage this Vision file lockmgr This program should be run with the same runtime that you normally use to access Microsoft SQL Server tables and with the same configuration variables set The program detects whether Acu4GL for Microsoft SQL Server is available and detects the ALMSSQL_VISION_LOCKS_FILE variable to determine which file to manage This program displays all the records in the lockfile and gives options for removing single records by highlighting the desired record to remove or removing all shown records and also for restricting the shown records by PID Table and Database This program also creates the B 28 m Acu4GL for Microsoft SQL Server Information Vision lock file and is the only method of creating the file You can refresh the display by selecting the Restrict button and then pressing OK without restricting the display further If everything is working correctly there should be no records in this table when there are no users accessing Microsoft SQL Ser
165. SYB_PACKETSIZE sets the size of network packets Setting this variable can affect performance since fewer and larger network calls can improve performance This variable must be set in the configuration file It has no effect if it is set in a COBOL program via SET CONFIGURATION or SET ENVIRONMENT The value of this variable is the largest size that the transport layer uses for network packets although the underlying library may reduce the size specified this is out of the control of the interface The E 38 m Acu4GL for Sybase Information largest value that can be specified is 32767 The default depends on which version of the client libraries is linked into the runtime although 512 is the most common default Use this configuration variable to tune your database performance To set the packet size to 8192 use A_SYB_PACKETSIZE 8192 Setting this variable to 0 or to a negative value causes the Acu4GL product to use the default value A_SYB_PASSWD The variable A_LSYB_PASSWD should be set to the password assigned to the database account associated with the user name specified by A_SYB_LOGIN Examples If the account with the user name in A_SYB_LOGIN has the associated password CW021535 you would specify A_SYB_PASSWD CW021535 in the runtime configuration file For better security you can accept a password from the user during program execution set the A_LSYB_PASSWD variable bas
166. Sybase instructions for selecting a Net Library After you make your selection you will be prompted for directory names and for the server internet address or host name The installation utility will then make an entry in the SQL INI file which points to the server The SQL INI file is located in the INI subdirectory under the directory where your Net Library is stored The name of the server that is placed into SQL INI is the name you must use in your COBOL configuration file with the variable A_SYB_DEFAULT_CONNECTION Any name listed in brackets in that file can be used as a server name Installation and Setup m E 21 Step 2 Verify that your client is communicating with your server To verify that you are connected use the Sybase client utility SYBPING to ping the server Make sure you receive a response to the ping The following sections describe the next steps to take before using Acu4GL for Sybase for the first time Setting Up a User Account Setting Up the User Environment Designating the Host File System Using the sql acu Program Preparing and Compiling Your COBOL Program The Demonstration Program E 2 5 Setting Up a User Account Acu4GL for Sybase must be able to connect to a user account You may either set up one general account for all users or an account for each individual user To set up an account you must have DBA privileges See sp_addlogin and Sybase sp_adduser in the Sybase Commands Reference M
167. T and READ NEXT do not COMMIT_COUNT 1 No commit is issued by the Acu4GL product When COMMIT_COUNT is set to 1 there are two alternate ways to perform a commit or rollback e One way is to call sql acu with COMMIT WORK or ROLLBACK WORK e The second way is to use the COBOL verbs COMMIT and ROLLBACK available in ACUCOBOL GT COMMIT_COUNT is set to 1 internally when you use the transaction management facilities available in the ACUCOBOL GT compiler A COMMIT WORK however is issued on exit from the runtime for example on execution of a STOP RUN See also Section 2 4 Using the sql acu Program Section C 7 Supported Features Configuration File Variables m C 25 ORA_LOGIN ORA_LOGIN indicates the user name under which you want to connect to the database system Example To connect to the database with the user name MYNAME you would specify ORA_LOGIN MYNAME in the configuration file See also ORA_PASSWD configuration variable A_ORA_DATABASE configuration variable Section C 2 5 Setting Up a User Account ORA_PASSWD The variable ORA_PASSWD should be set to the password assigned to the database account associated with the user name specified by ORA_LOGIN Example For example if the account with the user name has the associated password CW021535 you would specify ORA_PASSWD CW021535 in the configuration file or the environment For a full
168. T 1 11 runtime verification demonstration program 2 7 S sample program Acu4GL for Informix A 7 SCO UNIX relinking Oracle C 13 search path setting up for Acu4GL for Oracle C 18 searching for XFD files 8 18 SECONDARY_TABLE directive 4 17 security Oracle Acu4GL C 6 SQL Server B 3 Sybase Acu4GL E 3 sequencing data 7 2 servers SQL Server B 2 Sybase E 2 SETPOS DB2 F 20 ODBC D 25 SETSTMTOPTION DB2 F 21 ODBC D 26 setting database specific variables 1 13 setting the files host 1 12 m Index 35 setting up a search path for Oracle C 18 setting up Acu4GL for ODBC D 10 setting up Acu4GL for Sybase E 4 setting up data sources Acu4GL for ODBC D 12 setting up user accounts Acu4GL for Oracle C 15 Acu4GL for SQL Server B 7 Acu4GL for Sybase E 21 setting up user environment Acu4GL for DB2 F 10 Acu4GL for ODBC D 14 Acu4GL for Oracle C 16 Acu4GL for SQL Server B 7 Acu4GL for Sybase E 21 settling isolation levels D 24 F 19 shared libraries Acu4GL for DB2 F 9 Acu4GL for Informix A 6 Acu4GL for Oracle C 13 Acu4GL for Sybase E 10 single locking file options compiler 8 3 single tier architecture Acu4GL for ODBC D 8 ODBC D 4 sources data designating host for DB2 F 13 designating host for ODBC D 16 ODBC D 7 setting up for ODBC D 12 sp_Aculnit procedure SQL Server B 36 Sybase E 51 sp_Aculnit stored procedure E 12 E 17 E 19 sp_AcuRemovrUnusedLocks_1 procedure SQL Server B 37 Index 36 m
169. T TRANSACTION implied 8 3 transaction implied 8 4 XFD files creating 8 2 compiler warnings 9 14 compiling demonstration program 2 7 preparing a COBOL program 6 2 sample program Informix A 7 conditions OTHER 4 21 configuration variables Acu4GL for DB2 F 14 Acu4GL for Informix A 9 Acu4GL for ODBC D 18 Acu4GL for Oracle C 21 Acu4GL for SQL Server B 11 overview 8 4 setting in runtime files 1 13 WHERE constraint 9 7 configuration variables list of 4GL_2000_CUTOFF 8 5 Index 12 m 4GL_8_DIGIT_CUTOFF 8 5 4GL_COLUMN_CASE 8 6 4GL_COMMIT_COUNT 8 6 4GL_CONVERT_DATE_ZERO 8 8 4GL_DB_MAP 8 8 8 13 4GL_EXTRA_DB_COLS_OK 8 9 4GL_FULL_DATA_TEST 8 10 4GL_IGNORED_SUFFIX_LIST 8 10 4GL_ILLEGAL_DATA 5 3 8 11 4GL_JULIAN_BASE_ DATE 4 10 8 11 4GL_USEDIR_LEVEL 8 9 8 12 4GL_WHERE_ CONSTRAINT 8 13 A_DB2_CATALOG F 15 A_DB2_TABLE_TYPES F 24 A_DB2_USE_SQLCOLUMNS F 25 A_DB2_USE_SQLTABLES F 26 A_ODBC_CATALOG D 20 A_ODBC_TABLE_TYPES D 29 A_ODBC_USE_SQLCOLUMNS D 32 A_ODBC_USE_SQLTABLES D 33 A_ORA_DATABASE C 21 A_ORA_HINTS C 22 A_ORA_MAX_FILE_CURSORS C 22 A_ORA_WAIT_LOCK C 23 A_ORACLE_ERROR_FILE C 23 COMMIT_COUNT C 23 DECIMAL _POINT D 18 DEFAULT_HOST 1 12 1 15 8 13 FILE_TRACE 8 16 filename_HOST 1 12 1 15 8 14 ORA_LOGIN C 25 ORA_PASSWD C 25 USER_PATH C 26 D 33 F 26 XFD_DIRECTORY 8 17 XFD_MAP 3 10 8 17 m Index 13 XFD_MAP_RESETS 3 12 8 18 XFD_PREFIX 3 7 8 18 configured login Oracle C 16 conflicts between field na
170. The default values are as follows limit is 65 characters for each option E 28 m Acu4GL for Sybase Information OPTION_1 SCROLL OPTION_2 blank OPTION_3 For read only Users of Sybase version 11 should set the value of OPTION_3 to at isolation read uncommitted to prevent page locks A_SYB_DATABASE A_SYB_DATABASE specifies the name of the specific database to be accessed You cannot open any database files until you have set this variable Example A_SYB_DATABASE stores indicates the stores database is to be accessed A_SYB_DEADLOCK_LOOPS Use A_LSYB_DEADLOCK_LOOPS if you expect that more than one user will be opening a lot of tables at the same time This configuration variable can be used to instruct Acu4GL to re execute an INSERT statement that could not execute because a row in the AcuOpenTables table was locked or to return an error if the user chooses not to run the query again The default for A_LSYB_DEADLOCK_LOOPS is 0 which causes the interface to return an error 9D 1205 indicating that a table is locked Set A_LSYB_DEADLOCK_LOOPS to a positive numeric value to cause Acu4GL for Sybase to re execute by the number specified the query that tried to open the table and thus caused the deadlock Note that it can be as long as 10 seconds until Sybase detects the deadlock and the application appears to hang while the repeated attempts to re execute the query are in progress Set A_S
171. This method has the most overhead but it is much more likely to succeed in locking records A_DB2_LOGIN A_DB2_LOGIN indicates the user name under which you want to connect to the database system Not all data sources require a user login name Those that do may have case requirements Check your data source documentation to determine if login is case sensitive Example To connect to the database with the user name MYNAME you could specify A_DB2_LOGIN MYNAME or A_DB2_LOGIN myname F 22 m Acu4GL for DB2 Information in the runtime configuration file There is no default value for this variable If no login is specified none will be used See also A_DB2_PASSWD runtime configuration file variable A_DB2_PASSWD The variable A_DB2_PASSWD should be set to the password assigned to the database account associated with the user name specified by A_DB2_LOGIN Not all data sources require a password Those that do may have case requirements Check your data source documentation to determine if password is case sensitive Examples If the account with the user name in A_DB2_LOGIN has the associated password CW021535 you would specify A_DB2_PASSWD CW021535 in the runtime configuration file For better security you can accept a password from the user during program execution set the A_DB2_PASSWD variable based on the response ACCEPT RESPONSE NO ECHO SET ENVIRONMENT A_DB2_PASSWD TO RESPONSE Note If the use
172. UCOBOL GT No special runtime configuration variables are required This method of locking is all that is needed if no applications other than COBOL programs are going to be using the Acu4GL for Microsoft SQL Server product But if your site has other applications that access the Microsoft SQL Server databases you must use a method of locking that is inherent to Microsoft SQL Server Another method of locking that Microsoft SQL Server supports internally is the result of time stamping and the use of BROWSE MODE see the discussion of BROWSE MODE in the Microsoft SQL Server Commands Reference Manual If a table has a time stamp column the Acu4GL for Microsoft SQL Server product will use browse mode This will allow the server to detect whether another application has modified a record while an ACUCOBOL GT application has had it locked For information about alternative locking methods see the configuration variables A_LMSSQL_NATIVE_LOCK_TIMEOUT and A_MSSQL_USE_DROPDOWN_QUERIES B 7 Stored Procedures A stored procedure is a collection of SQL statements residing on the server stored as text in a table in the database Stored procedures provide an efficient environment for Acu4GL because once they are executed on the server they do not need to be parsed and optimized each time they are executed However if the server goes down the stored procedure will be parsed and optimized again the first time the procedure is called after the databas
173. ULT_HOST in section 8 2 Runtime Configuration Variables and DATABASE later in this chapter for important information on setting these variables A_INF_DUPLICATE_KEY This variable determines how Acu4GL for Informix handles the processing of alternate keys with duplicates When reading on an alternate key with duplicates it is possible that not all records will be returned The probability of this scenario increases if the direction of the read changes for example switching from read next to read previous This generally occurs when e The the data set was imported from an external file e The the database has undergone large amounts of modifications resulting in the re use of row IDs e The the initial query returned the record set in a way such that the records are not in row ID order Three potential values can be set for this variable Note These settings can affect performance If you need assistance see your Database Administrator A 10 m Acu4GL for Informix Information Zero 0 If this variable is set to zero 0 no ROWID is added to the SELECT statements for reading in a forward direction but a ROWID is added to SELECT statements for reading in a backward direction if the file is not a VIEW Note We don t recommend setting this variable to zero 0 because ROWIDs may not be in ascending order This method can be used if the direction in which the application reads records does
174. User s Guide Acu4GL Version 8 1 Micro Focus IP Ltd 9920 Pacific Heights Blvd Suite 150 San Diego CA 92121 858 795 1900 Copyright Micro Focus IP Ltd 1998 2008 All rights reserved Acucorp ACUCOBOL GT Acu4GL AcuBench AcuConnect AcuServer AcuSQL AcuXDBC AcuXUI extend and The new face of COBOL are registered trademarks or registered service marks of Micro Focus IP Ltd COBOL Virtual Machine is a trademark of Micro Focus IP Ltd Acu4GL is protected by U S patent 5 640 550 and AcuXDBC is protected by U S patent 5 826 076 Microsoft and Windows are registered trademarks of Microsoft Corporation in the United States and or other countries UNIX is a registered trademark of the Open Group in the United States and other countries Solaris is a trademark of Sun Microsystems Inc in the United States and other countries Other brand and product names are trademarks or registered trademarks of their respective holders DB2 Connect is a trademark and IBM AIX DB2 Informix MQSeries AS 400 OS 390 PowerPC RS 6000 WebSphere pSeries and zSeries are registered trademarks of IBM in the United States E 01 UG 080901 Acu4GL 8 1 Contents Chapter 1 Acu4GL Overview 1 1 Welcome to ACUA GE i csicen ce iicciviccctvbesscavezcentoest tubes EN REKNE EEE EE NE Eik 1 2 12 DOCUMENT OVERVIEW seis a aar aoa E O E aE casovaceea sdgpuaboen ao iae eai 1 3 T 3 Accessing D ta oireeni teen oa ee r ah e EEE
175. YB_DEADLOCK_LOOPS to 1 or MESSAGE to cause Acu4GL for Sybase to display a message box containing the text of the Sybase error message and the option to rerun the query Configuration File Variables m E 29 Sybase has returned an error text of message from Sybase Do you want to retry the operation If the user answers yes the interface reruns the query If the user answers no the interface returns an error 9D Setting A_SYB_DEADLOCK_LOOPS to 1 or MESSAGE is the preferred action the time it takes to inform users of the problem allows other connections to finish opening the tables giving the AcuOpenTables table time to remove the deadlock A_SYB_DEFAULT_CONNECTION A_SYB_DEFAULT_CONNECTION specifies the name of the server to which the runtime will connect Acu4GL for Sybase checks this variable only if the DSQUERY environment variable has not been set Note that Sybase recommends assigning a value to the DSQUERY environment variable If neither DSQUERY nor A_SYB_DEFAULT_CONNECTION is set the default server is named SYBASE just as for isql To reference tables in another server open the file servername database owner table Example Suppose you have two servers one named TOM and one named HARRY If most of the tables you want to access are on the server HARRY you should set A_SYB_DEFAULT_CONNECTION HARRY For those occasions when you want to access the TOM server you could
176. _ALTERNATE_KEYS configuration variable B 25 A_MSSQL_TRANSLATE_TO_ANSI configuration variable B 25 A_MSSQL_UNLOCK_ON_EXECUTE configuration variable B 25 A_MSSQL_USE_DROPDOWN_QUERIES configuration variable B 26 A_MSSQL_VISION_LOCKS_FILE configuration variable B 27 A_ODBC_ALTERNATE_COMMIT_LOGIC configuration variable D 19 A_ODBC_CATALOG configuration variable D 20 A_ODBC_COMMIT_ON_BEGIN configuration variable D 21 A_ODBC_DATASOURCE configuration variable D 21 A_ODBC_ERROR_MAP FILE configuration variable D 22 A_ODBC_ISOLATION_LEVEL configuration variable D 24 A_ODBC_LOCK_METHOD configuration variable D 24 A_ODBC_LOGIN configuration variable D 26 D 34 F 27 A_ODBC_NO_NULL_COLUMNS configuration variable D 27 A_ODBC_PASSWD configuration variable D 27 A_ODBC_PRINT_LOG configuration variable D 28 A_ODBC_QUOTE_IDENTIFIERS configuration variable D 28 A_ODBC_STRICT_EQUAL configuration variable D 28 A_ODBC_TABLE_TYPES configuration variable D 29 A_ODBC_UNSIGNED_TINYINT configuration variable D 30 A_ODBC_USE_CHAR_FOR_BINARY configuration variable D 31 A_ODBC_USE_SPACE_IN_DATES configuration variable D 31 A_ODBC_USE_SQLCOLUMNS configuration variable D 32 A_ODBC_USE_SQLTABLES configuration variable D 33 A_ORA_DATABASE configuration variable C 8 C 21 A_ORA_HINTS configuration variable C 22 A_ORA_MAX_FILE_ CURSORS configuration variable C 22 A_ORA_WAIT_LOCK configuration variable C 23 A_ORACLE_ERROR_FILE configuration variable C 23 A_SYB_ADD_IDENTITY configurati
177. a in your COBOL programs and how to handle differences in the field names and data types that are passed between COBOL and the database engine Acu4GL is part of the extend family of solutions Note Unless otherwise indicated the references to Windows in this manual denote the following 32 bit versions of the Windows operating systems Windows Vista Windows XP Windows NT 4 0 or later Windows 2000 Windows 2003 and the following 64 bit versions of the Windows operating system Windows Server 2003 and 2008 x64 Vista x64 In those instances where it is necessary to make a distinction among the individual versions of those operating systems we refer to them by their specific version numbers Windows 2000 Windows NT 4 0 etc The Micro Focus extend unit tested the Acu4GL Version 8 1 products with the following RDBMSs e Oracle e Microsoft SQL Server e DB2 e Sybase e Informix e ODBC Document Overview m 1 3 As aresult of our testing and according to general information received from the makers of the RDBMS regarding upward compatibility of their product we believe the following to be accurate Please check the Micro Focus Web site for the most recent versions of this table RDBMS Acu4GL Version 8 Probable compatibility tested with with Acu4GL Version 8 RDBMS version based on vendor information Client Server may be used for connecting to other versions Informix 9 10 32 and Versions greate
178. a is error window call CSRERR using error status error text display DATABASE ERROR secondary error display error text accept omitted close window error window display window line 20 column 2 size 75 lines 3 2 6 m Getting Started 2 5 The Demonstration Program As soon as your installation and setup are complete you may run the demonstration program demo cbl included on your distribution medium This program illustrates many of the Acu4GL product capabilities including e how to map RDBMS data types to traditional COBOL data types e how to compile a COBOL program in preparation for interfacing with an RDBMS e how to modify records within the RDBMS database The demo program simulates what might be used in a distributor s shipping department You ll be creating the acuorders table which contains information about the orders placed by the distributor s customers The acuorders table has the following columns of information the database data type and COBOL data type are shown for each Note The data type may be slightly different depending on the RDBMS Column Name Data Type COBOL PIC rder_num varchar 4 pic 9 4 rder_date int pic 9 6 ustomer_num varchar 3 pic 9 3 hip_instruct varchar 40 pic x 40 acklog varchar 1 pic x o_num varchar 10 pic x 10 hip_date int pic 9 6 hip_weight decimal 8 2 pic 9 6 v99 hip_charge decimal 6 2 pic 9 4 v99 aid_date int pic 9 6 Th
179. a new data source driver set A_ODBC_DATASOURCE to the personalized name that you entered in the Add window If you do not know the data source name in advance or if you intend to use more than one data source you may set the data source name dynamically at run time In your COBOL program you would add code similar to this prior to the statement that opens the file Filename Translation m D 17 SET ENVIRONMENT A_ODBC_DATASOURCE TO MS Access Databases You are now ready to use the sql acu program as outlined in Chapter 2 Getting Started After you learn about and use this utility you next find out about preparing and compiling your COBOL program followed by learning to use the demonstration program See section 6 1 Preparing and Compiling Your COBOL Program and section 2 5 The Demonstration Program for additional information D 3 Filename Translation As you prepare to work with Acu4GL for ODBC you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD files are formed and work together When the ACUCOBOL GT compiler generates XFD files it uses lowercase letters to name the XFD file In addition the compiler changes hyphens to underscores when naming the XFD file Through configuration variables the runtime translates the name in the COBOL program into the filename that is passed to the open function in the runtime The open
180. a standard ACUCOBOL GT library routine for an extended error description It is possible that there are ACUCOBOL GT library routines that do not work with or do not make sense to use with some of the Acu4GL products To find out if that is the case with your Acu4GL product look in the Common Questions and Answers section of the appendix specific to your product 1 16 m Acu4GL Overview Getting Started Key Topics Getme Startel ne e Seanad cee hides at cae es 2 2 Technical Services sccccscsessescesssssseecesscesdeccesscestecnssensssesenssnssaeesases 2 2 Tastallatj n n aiei a hcsndeientida E E S 2 2 Using the sql acu Program eeeeeeseeseseeeeesesereerseresrsrerersrseserereee 2 3 The Demonstration Program eseeeeeeeeeeeseseeereeerrersesesrresrererereersreese 2 6 2 2 m Getting Started 2 1 Getting Started The Getting Started chapter points you in the right direction for installing and setting up the Acu4GL interface for your particular RDBMS Once Acu4GL is installed and ready you should return to this chapter to find the information you need for operating the sql acu utility preparing and compiling a COBOL program and running the demonstration program 2 2 Technical Services You can reach extend Technical Services in the United States Monday through Friday from 6 00 a m to 5 00 p m Pacific time excluding holidays You can also raise and manage product issues onlin
181. a system configuration file each time it is started Two configuration files apply the file onconfig std is used as a template for creating database configuration files when new databases are created the onconfig lt database gt file is the configuration file for a given database In the database configuration file locate the line OPTCOMPIND 2 To hint the optimizer Modify this line to read OPTCOMPIND 0 To hint the optimizer The OPTCOMPIND configuration parameter helps the optimizer choose an appropriate join method for your application A setting of 0 indicates that when appropriate indexes exist the optimizer chooses index scans nested loop joins without considering the cost over table scans sort merge joins or hash joins This new setting takes effect the next time you shut down and restart the ONLINE database engine The altered setting is then applied to all operations with the query optimizer To ensure that this change applies to newly created databases you should modify the onconfig std file Method 2 Altering a user session You can modify how the query optimizer executes queries on an individual basis by setting a UNIX environment variable in the user s environment This environment variable should be set before executing your COBOL application It cannot be set with the COBOL SET CONFIGURATION or SET ENVIRONMENT verbs Use the syntax setenv OPTCOMPIND 0 or OPTCOMPIND
182. able Incorrect AcuLocks table The first locking table is called AcuLocks it holds the record locks The columns in this table are e the DBID e the Table ID e the Process ID of the process holding the lock e the primary key of the record that is locked There is a unique index on the DBID the Table ID and the Key Value so that inserts into this table are automatically rejected if another user holds a lock on the row in question This also gives the Database Administrator the information needed to determine who has locks set and whether the user in question still has a connection to the server AcuOpentables table The second locking table is called AcuOpenTables it holds information about open tables The columns in this table are e the DBID e the Table ID e the process ID PID of the process that has the table open e the Open Mode Input Output I O or Extend e whether Multiple records can be locked e whether the file can be open for I O by any other users B 30 m Acu4GL for Microsoft SQL Server Information e whether the file can be open at all by any other users e whether Mass Update was specified in the open There are no indices on this table but there is a trigger which will automatically reject opens that are not allowed based on other users open modes By using these lock tables the Acu4GL for Microsoft SQL Server product is able to support all the types of locking ordinarily supported by AC
183. ables m F 15 The configuration variable A_DB2_ALTERNATE_COMMIT_LOGIC determines how the interface will respond to the setting of 4GL_COMMIT_COUNT When A_DB2_ALTERNATE_COMMIT_LOGIC is set to 0 or FALSE the default the value of 4GL_COMMIT_COUNT is checked only at startup The interface will issue a commit when the criteria set by 4GL_COMMIT_COUNT is met regardless of the current transaction state When A_DB2_ALTERNATE_COMMIT_LOGIC is set to 1 the value of 4GL_COMMIT_COUNT is checked after each WRITE REWRITE DELETE or UNLOCK operation A commit is issued however only if the runtime is not currently in a transaction Example 4GL_COMMIT_COUNT 1 A_DB2_ALTERNATE_COMMIT_LOGIC 0 Each WRITE operation is committed to the database immediately This prevents an application from being able to rollback a WRITE See Also 4GL_COMMIT_COUNT runtime configuration variable A_ODBC_ALTERNATE_COMMIT_LOGIC configuration variable A_DB2_CATALOG This variable indicates the catalog name to be used when Acu4GL searches for objects in the database Note that not all data sources will support a catalog Using A_DB2_CATALOG with other variables such as USER_PATH and A_DB2_TABLE_TYPES can speed up the finding of tables in large databases It can also prevent an error 9D 14 More than one table with the same name thereby enabling access to tables with identical names but with different catalogs For example
184. aeceseeeeneeeseeees F 25 A DB2 USE SQUGOLUMNNS rz satis ere pearen E NAAR nda tet at aight F 25 A DB2 USE SOLTA BLES yc 3305 nae ed ek eR einen ee a eects F 26 USER PATH erpe e reee otecethe oh cusles GU ee EEE EE abe E Sean F 26 F 6 Record and Table Locking is sccesssusessecsiessesdessspsesschustevass donstevaas ESEE teresen Enei Ee rioa F 28 F 7 Limitsand Rang S innana r Gove E E E A AA eee os F 28 F 8 Data Type Mapping sinnini ssectsgees isi eerren eoio eop EE EE EE E E E E E TEs F 29 FeO RUmtiMe Err oiS aina a A A A a N E F 30 F 10 Common Questions and AnSWETS 0 ccsscsesesseecsscecessececesseceseecessaeeceeaaeecseseessneeecnaes F 32 Glossary of Terms Index Acu4GL Overview Key Topics Welcome to ACU4GL 00 eesecseeecesesseceseeceseseeeeeseenecoeessenecaeeeseeesaeees 1 2 Document Overview sriain anian aea iE a a nE enese Ei 1 3 Agtesdog Data csie osi serions a eni iE aE R 1 6 Database Comeepes i ccescsccscccechieoneediassonven tae icarmnd 1 9 How Acu4GL Works cece cccsessceccecsssssecesesecssssesssessscsssesesssssenss 1 10 1 2 m Acu4GL Overview 1 1 Welcome to Acu4GL Welcome to the Acu4GL family of products This guide describes how the ACUCOBOL GT programming language uses Acu4GL interfaces to access information stored in Oracle Informix Sybase Microsoft SQL Server DB2 and ODBC compliant relational database management systems RDBMSs It explains how to describe dat
185. ainder will be space filled AGL_2000_CUTOFF This variable is used to implement date windowing for Acu4GL This variable determines which two digit years will be considered to be in the twentieth century and which two digit years will be considered to be in the twenty first century This variable accepts a two digit value e Two digit years that are smaller than this value are considered part of the twenty first century 2000 is added to these dates e Two digit years that are equal to or larger than this value are considered to be in the twentieth century 1900 is added to them The default value for this variable is 20 AGL_8_DIGIT_CUTOFF This variable determines whether to use the 4GL_2000_CUTOFF for dates that don t use a format string and that are 8 digits Setting this variable to 1 causes Acu4GL to apply the 4GL_2000_CUTOFF logic for 8 character long dates The default value is 0 off false no This configuration variable can also take values of 1 on true yes 8 6 m Compiler and Runtime Options AGL_COLUMN_CASE This variable causes the Acu4GL product to leave the case of the field names found in the XFD unchanged Normally all field names are converted to lower case by Acu4GL except for Oracle which converts all values to upper case and all hyphens are converted to underscores e Valid values for this variable are UNCHANGED and LOWER e The default value is
186. all other indexed files to the Vision system These are runtime settings that allow you to change hosts without recompilation and enable you to tailor your application for the specific needs of a particular end user site Note The filename_HOST variable also enables you to do load balancing and migration of your application You can move Vision files into the database in an incremental fashion allowing you to test scaling and performance of the new configuration How Acu4GL Works m 1 13 Setting database specific variables At this point you set variables in the runtime configuration file that apply to the specific database system you are using See the appendix specific to your RDBMS for details Passing I O requests to the interface You use the Acu4GL enabled ACUCOBOL GT runtime system to execute your application Whenever the runtime system encounters an input or output instruction such as READ or WRITE on a file that is directed to an RDBMS it passes the request to the Acu4GL product Automatically building SQL statements Acu4GL automatically builds SQL instructions that your database management system can understand As it builds these SQL instructions it looks at the ACUCOBOL GT data dictionary which maps the COBOL record and its fields to the table rows and its columns Accessing a database The database management system uses its own dictionary as a pointer into its own data files performs the requested I O o
187. allowed The BINARY directive may not be used in combination with the VAR_LENGTH directive The method of storing fields declared as binary is database specific For example with Informix databases binary data is stored in char fields with an extra leading character This character always contains a space Oracle uses the data type raw for the field Syntax SXFD BINARY or XFD BINARY Example You might use this directive when you need to store a key that contains LOW VALUES COBOL allows a numeric field to contain LOW or HIGH values but these are invalid for a numeric field in the RDBMS 01 code record 03 code key 05 code indic pic x XFD BINARY 05 code num pic 9 5 05 code suffix pic x 3 move low values to code num Directives Supported by the Acu4GL Interfaces m 4 7 4 3 3 COBOL TRIGGER There is an XFD directive that tells Acu4GL that a COBOL trigger is to be executed Note This directive must come immediately before the FD of the file for which the trigger is defined It uses the standard XFD directive syntax either or Syntax XFD COBOL TRIGGER program name The following three parameters are passed to the COBOL program 01 OPCODE 88 READ BEFORE VALUE r 88 READ AFTER VALUE R 88 WRITE BEFORE VALUE w 88 WRITE AFTER VALUE W 88 REWRITE BEFORE VALUE u 88 REWRITE AFTER VALUE U 88 DELETE BEFORE VALUE q 88 DELET
188. and Out format A UNIX utility cursor A prepared query saved in a parameterized format data dictionaries Extended file descriptors that map your application s SQL commands to COBOL records and vice versa Based on the standard COBOL file descriptors FDs See also file descriptor and XFD file directives Optional comments that you can place into a file descriptor in your COBOL source code to control how the data dictionary is built See also file descriptor DSN Data Source Name Data Source Name An arbitrary name for every group of indexed or relative data files that your Windows application needs to access Extended File Descriptor See file descriptor and XFD file field An element of a database record in which one piece of information is stored Contrast record m Glossary 3 file descriptor An integer that identifies an open file within a process This number is obtained as a result of opening a file Operations that read write or close a file would take the file descriptor as an input parameter In many operating system implementations file descriptors are small integers that index a table of open files In UNIX file descriptors 0 1 and 2 correspond to the standard input standard output and standard error files respectively See also data dictionaries and XFD file Gregorian calendar The calendar as reformed by Pope Gregory XIII in 1582 This calendar adjusts the leap years to
189. and used together Someone who really knows how the data is being used might help to identify groups of fields that can be combined to speed processing 4 20 m Using Directives 4 3 11 VAR_LENGTH By default the compiler generates fixed length fields in the XFD The VAR_LENGTH directive requests that the data item that immediately follows the directive be assigned a type that implies variable length if possible This can save considerable space in your database The VAR_LENGTH directive cannot be used in combination with the BINARY directive The precise variable type that is assigned to the data item depends on which RDBMS is in use Possible variable types that might be assigned are VARCHAR and VARBINARY Syntax XFD VAR_LENGTH or XFD VAR_LENGTH Example For example the directive in the following code indicates that the employee name field should be entered into a SYBASE database as a VARCHAR data item XED VAR_LENGTH 03 employee notes pic x 300 4 3 12 WHEN The WHEN directive is used when you want to include multiple record definitions or REDEFINES in a database table It s typically used when you want to force certain columns to be built that wouldn t be built by default because you want to use them from the RDBMS side Directives Supported by the Acu4GL Interfaces m 4 21 Recall that the key fields and the fields from the largest record are automatically included as explicit column
190. anual E 2 6 Setting Up the User Environment The user s account should have been set up correctly to access the Sybase RDBMS system This includes environment variables such as SYBASE and DSQUERY See your Sybase documentation for more details In addition to setting the variables required for Sybase you will need to do the following E 22 m Acu4GL for Sybase Information e Ensure that your execution path contains the name of the directory in which you placed your newly linked Acu4GL runtime executable Set the A_LSYB_LOGIN and A_SYB_PASSWD variables either in your environment or in the ACUCOBOL GT runtime configuration file if you don t do this Acu4GL will use your UNIX login name as your Sybase login name and no password For security reasons it is best to set the password variable from your COBOL program by asking the user to enter a password and then executing SET ENVIRONMENT A_SYB_PASSWD TO user entry You may want to make and use a personalized copy of the configuration file to avoid impacting other users The ACUCOBOL GT User s Guide describes how to use the A_CONFIG environment variable or the c runtime option to identify a personal configuration file For detailed information on A_LSYB_LOGIN and A_SYB_PASSWD see section E 6 Acu4GL for Sybase Configuration File Variables E 2 7 Designating the Host File System If you are opening an existing file most but not all file s
191. any changes you want to make immediately Make those changes COPY the FD and SELECT into your program and try to compile the program If compilation is successful you can move on to the next step in your development effort If compilation is not successful use the information contained in the error messages to aid in troubleshooting the program 6 16 Working with COBOL New and Existing Databases Key Topics DataDASeS 06cccccccecsecsesusccestccsenscossssvevsovscsnvonsvavececsecesecsscns suse csveveverssoenrecst 7 2 Default Acu4GL Behavior ccccccccccecseececsssesseessessessesseessessssseeee 7 2 Accessing Existing Database Files 2 0 0 0 ceeeeeseceeeeceeeeeesereeeneeneeeees 7 3 7 2 m New and Existing Databases 7 1 Databases You ll probably find yourself in one of two situations as you begin to use this product In situation one the database files don t exist yet and will be brand new In situation two the database files already exist and you want to access that existing data from a COBOL application There may or may not already be existing COBOL programs that access the database Each situation brings up its own questions How do I declare my COBOL data so that it matches the database data Are there any special fields in the database that must be accessed in a special way How do I choose COBOL record names field names index names and data types that best conform to the compiler the Acu4G
192. arch these errors and try to determine a more appropriate COBOL error response When you create your error map file use the following guidelines e Begin comment lines with Blank lines are also considered comments e Break the rest of the file into sections with each section header comprising all the information enclosed in brackets from the data source error function For example if the data source returns this error OdbcOneInfo State S1000 Native Error 346 Visigenic ODBC Informix 5 Driver Informix Could not update a row in the table Configuration File Variables m D 23 make your section header Visigenic ODBC Informix 5 Driver Informix e Include two fields in each line in the section the internal error number and an ACUCOBOL GT mapping string Using the same example if you wanted to map the Visigenic Informix driver error 346 Could not update a row in the table to the COBOL error Not found you would include this line in the section 346 E_NOT_FOUND Other Visigenic Informix error maps would follow in the same section If you use other drivers you could use multiple sections The valid values for the second field are as follows E_SYS_ERR ERR NY_FILES CLASH OCKED E BROKEN E_DUPLICATE E_NOT_FOUND DEF_RECORD SK_FULL ILE_LOCKED EC_CHANGED E_MISMATCH E_NO_MEMORY E_MISSING_FILE E PERMISSION _NO_SUPPORT zZ O o OQ el
193. ariable the XFD file in the object library is loaded first unless the XFD_PREFIX configuration variable uses remote name notation 3 2 3 Summary of Dictionary Fields Fields defined with an OCCURS clause are assigned unique sequential names Fields without names are disregarded When multiple fields occupy the same area the compiler chooses only one of them unless you have a WHEN directive to distinguish them 3 8 m Data Dictionaries To choose e The compiler preserves fields mentioned in KEY IS phrases e It discards group items unless USE GROUP is specified e It discards REDEFINES e It uses the largest record if there are multiple record definitions 3 2 4 Identical Field Names In COBOL you distinguish fields with identical names by qualification For example there are two fields named RATE in the following code but they can be qualified by their group items Thus you would reference RATE OF TERMS CODE and RATE OF AR CODE in your program 01 record area 03 terms code 05 rate pic s9v999 05 days pic 9 3 05 descript pic x 15 03 ar code 05 rate pic s9v999 05 days pic 9 3 05 descript pic x 15 However database systems consider duplicate names an error Thus if more than one field in a particular file has the same name the data dictionary will not be generated for that file The solution to this situation is to add a NAME directive see Chapter 4 that associates an alternate name with one or bot
194. ase of benchmark testing When the table is created a mass insert of the records is performed on the database table The indexes are created for the table but the database has not yet gathered information about the distribution of data in the underlying table or the usefulness of a particular index The lack of statistical information within the database regarding the data in the tables results in possible poor decisions on the part of the query optimizer The optimizer is A 14 m Acu4GL for Informix Information unable to determine that an index exists that best matches the requirements of the query and will choose an alternate execution approach that will cause drastically poorer performance of the benchmark application Example As an example of this problem we will examine performance times from ACUCOBOL GT s iobench program Test Informix 5 1 Informix 7 2 SunOS Intel 486 Write Sequential Sort Sequential 4 5 reme s e o The times between the two machines and databases that the benchmark were run on are comparable for all times except for the read operation The read operation shows a significant performance degradation Isolating the problem To isolate the source of the problem you can insert into your COBOL program a call to Acu4GL s utility program sql acu Before the Read benchmark test we inserted the call CALL sql acu USING SQL COMMAND In the working storage section SQL COMMAND is defined a
195. at pic 9 3 pic x value h value d pic 9 10 pic 9 6 pic 9 2 pic 9 2 pic x value r value w pic x Preparing and Compiling Your COBOL Program m 6 9 88 is net 30 value 3 88 is net 10 value 1 xfd use group date 03 p o date 05 p o yy pic 9 2 05 p o mm pic 9 2 05 p o dd pic 9 2 xfd when p o record type d 01 p o detail record 03 p o dept number pic 9 3 03 p o record type pic x 03 detail p o number pic 9 10 03 p o shipping info 05 p o quantity to ship pic s9 4 comp 05 p o total quantity pic s9 4 comp xfd use group name notes 03 p o notes 05 notes line occurs 3 times pic x 40 Note p o record type is entered only once into the table The detail p o number field is not part of the table because the key overlays this area This table is built in the database Column Name Type p_o_division_number number 3 p_o_record_type char 1 p_o_number number 10 p_o_date date p_o_dept_number number 3 p_o_quantity_to_sh number 4 p_o_total_quantity number 4 notes char 120 6 10 Working with COBOL 6 2 Creating File Descriptors and SELECT Statements acu4glfd is a Windows based utility that can help you analyze tables and create File Descriptors and SELECT statements This utility uses ODBC technology to retrieve table information to list the fields in the table When possible the utility also determines
196. at can be specified is 32767 The default depends on which version of the client libraries are linked into the runtime although 512 is the most common default Use this configuration variable to tune your database performance To set the packet size to 8192 use Configuration File Variables m B 23 A_MSSQL_PACKETSIZE 8192 Setting this variable to 0 or to a negative value will cause the Acu4GL product to use the default value A_MSSQL_PASSWD The variable A_LMSSQL_PASSWD should be set to the password assigned to the database account associated with the user name specified by A_MSSQL_LOGIN Examples If the account with the user name in A_LMSSQL_LOGIN has the associated password CW021535 you would specify A_MSSQL_PASSWD CW021535 in the runtime configuration file For better security you can accept a password from the user during program execution set the ALMSSQL_PASSWD variable based on the response ACCEPT RESPONSE NO ECHO SET ENVIRONMENT A_MSSQL_ PASSWD TO RESPONSE Note If the user has been set up without a password this variable need not be set See also A_MSSQL_LOGIN runtime configuration file variable B 24 m Acu4GL for Microsoft SQL Server Information A_MSSQL_ROWCOUNT This variable has an effect only if you are reading on a key that does not allow duplicates or if you have added an Identity column to the table A_MSSQL_ROWCOUNT determines how many rows are r
197. ating indexes Performance Issues m 9 3 If a site experiences a performance problem this usually means there is a bottleneck somewhere in the system The DBA can help to isolate the bottleneck Once the bottleneck is identified the site can determine whether to apply more resources or correct the situation that is stressing the existing resources Guideline 2 Understand COBOL operations and database operation Some COBOL operations are particularly stressful to a database The more the application uses these operations the more likely it will slow the performance of the RDBMS The more you understand about your RDBMS and how it operates the more you can help your COBOL applications to work efficiently with it File Input and Output Consider these standard COBOL I O operations e READ e REWRITE e WRITE e DELETE e OPEN Each has an associated cost in terms of database performance Each asks the database to do something that takes time So if there are I O operations that are optional in your COBOL application you may want to remove them For example let s examine file OPENs Developers sometimes OPEN and CLOSE files unnecessarily using the OPEN CLOSE pairing as a way to demarcate each new procedure OPEN file A procedural code CLOSE file A 9 4 m Performance and Troubleshooting But it s important to know that file OPENs are expensive in terms of performance If you can eliminate non essential OPENs fro
198. ation Resolving name conflicts If naming differences exist you need not rename your COBOL fields and you need not change the database This is because the ACUCOBOL GT compiler s Fx option builds data dictionaries that map your COBOL fields to the correct database fields The mapping is automatic if the names are the same If the COBOL name differs from the database name you enable the compiler to make the correct mapping by adding a NAME directive to your COBOL code Directives can also be used to produce other effects when data is mapped from COBOL to the database Chapter 4 Using Directives describes directives in detail 7 3 4 Index Names Acu4GL uses a specific naming convention for indexes it creates Indexes created with Acu4GL use the i lt TABLENAME gt _ lt key value gt convention If you are using indexes created outside of the Acu4GL application you need to make sure the index names match the Acu4GL naming convention Performance is affected by the number of indexes you may have If you use tables with multiple indexes keep in mind that when a record is written or updated locks are put onto all of the indexes and they are all basically rewritten during the course of the write update This is a costly process There may be multiple columns per index and multiple indexes per table Each rewrite implies a certain amount of wait time Tables with a large number of indexes can be slow on writes updates and p
199. ation settings and procedures Acu4GL communicates with versions 9i or later of Oracle To install the Acu4GL product perform the following steps C 10 m Acu4GL for Oracle Information Step 1 Install Oracle The Oracle RDBMS must be installed and configured prior to the installation of Acu4GL for Oracle We also recommend e Oracle s SQL Plus product which is an interactive query tool This is not mandatory but it will give you quite a bit of flexibility SQL Plus allows you to do database work outside of COBOL including interactive queries table creation table modification and creation of views constraints and relationships between tables g3 e Oracle s scott tiger test schema which can be used for testing Micro Focus does not provide these products Make sure all environment variables Oracle requires such as ORACLE_HOME ORACLE_SID and LD_LIBRARY_PATH or equivalent if necessary are set up in the environment of each user who will be accessing Acu4GL for Oracle see your Oracle documentation for the list of variables required Verify Oracle s setup and configuration using an Oracle tool such as SQL Plus Also verify that the PATH references the necessary Oracle subdirectories Step 2 Create a new runtime system Note In the following directions the term runtime system refers to the runtime shared object on systems where the ACUCOBOL GT runtime is a shared object and to runcbl on othe
200. before the first database file is accessed Configuration File Variables m C 23 A_ORA_WAIT_LOCK This configuration variable determines the type of Oracle locks used wait or nowait locks The default is FALSE nowait locks This variable is read at file open time for each file A_ORACLE_ERROR_FILE This configuration file variable allows you to map errors using a text file to supplement the default method of providing errors By adding the name of the file that contains the actual error mapping to A_ORACLE_ERROR_FILE database specific errors are mapped to COBOL errors Note Some messages related to COBOL I O cannot be supplemented Example A sample syntax for this configuration file variable would be A_ORACLE_ERROR_FILE ORCLerrs where ORCLerrs is a file of a specified format containing a mapping of database specific errors to COBOL errors One such entry might be 1 DUPLICATE_RECORD COMMIT_COUNT The value of COMMIT_COUNT indicates the conditions under which you want to issue an automatic COMMIT_WORK operation C 24 m Acu4GL for Oracle Information Examples COMMIT_COUNT 0 A commit is issued when no locks are held either because all files that had locked records have been closed or because a COBOL COMMIT verb has been issued This is the default value COMMIT_COUNT n A commit is issued after n operations WRITE REWRITE and DELETE count towards n READ STAR
201. bl or libruncbl so 2b Create a Makefile inf file The inf_inst program can be run to create a Makefile inf file Note Please read the reference section at the start of the inf_inst script for the latest information regarding the Makefile ini and database or platform differences Getting Started with Acu4GL for Informix m A 5 First create the Makefile inf file by entering the following command sh inf_inst in the install directory Next you are asked to enter the directory where ACUCOBOL GT is installed Type the information and press Enter After that you are asked which version of Informix you have installed You have four choices e For version 5 x1 enter 5 e For version 7 2 32 bit enter 7 e For version 7 3 or for version 9 enter 3 e For version 7 3 64 bit enter 4 Once you have entered the version add the names of your C routines 0 if any to the line starting with SUBS Note The if_inst script generates a makefile that may require slight modifications Make sure that the FSI_LIBS line in your makefile is correct Now you are ready to relink your ACUCOBOL GT runtime 2c Link the runtime system 1 Make sure you are in the directory containing the ACUCOBOL GT runtime system Then at the UNIX prompt enter the following command make clean to ensure that you have a clean directory in which to build your runtime
202. c 9 6 05 species code type pic 9 5 05 species name pic x 6 03 03 03 03 service code key 05 service code type pic 9 6 05 service name pic x 10 billing code 05 billing code type pic 9 4 05 plan name pic x 8 office info 05 date in office pic 9 8 05 served by name pic x 10 remote info redefines office info 05 van id pic 9 4 05 proc code pic 9 8 05 vet name pic x 6 If you add the WHEN directives shown below you add several columns to the database table The fields that then appear in the table are underlined xfa 01 03 03 03 03 xfd 01 xfd 03 03 03 xfd 03 when animal id key archive record filler archive code archive location filler when animal id key master record use group animal id key 05 patient id 05 species code type 05 species name service code key 05 service code type 05 service name billing code 05 billing code type 05 plan name when billing code type office info 05 date in office 05 served by name xfd when billing code type 03 remote info redefines 05 van id 05 proc code 05 vet name 00000000000000000 pic pic pic pic other pic pic pic pic 9 pic pic pic 1440 pic 9 pic other office info pic pic pic Directives Supported by the Acu4GL Interfaces m 4 25 Example 3 If your application has a REDEFI
203. c x 88 header record value h 88 detail record value q 03 p o number pic 9 10 03 p o number detail redefines p o number 05 picking ticket number pic 9 6 05 shipping region pic 9 2 05 p o customer type pie 9 2 05 p o customer breakdown redefines p o customer type 07 customer category pic x 88 p o customer retail value r 88 p o customer whlsale value w 07 customer pay format pic x 88 is net 30 value 3 88 is net 10 value 1 03 p o date 05 p o yy pre 9 2 05 p o mm pie 9 2 05 p o dd PVve 92 01 p o detail record 03 p o dept number pic 9 3 03 p o record type pic x 03 detail p o number pic 9 10 03 p o shipping info 05 p o quantity to ship pic s9 4 comp 05 p o total quantity pic s9 4 comp 03 p o notes 6 4 m Working with COBOL 05 notes line occurs 3 times pic x 40 working storage section 01 p o status pic x 2 PROCEDURE DIVISION level 1 section main logic open output p o file close p o file stop run 6 1 1 Compiling With No Directives You can compile the preceding program as is with the Fx option to generate the data dictionary The compiled program will run and will build the database table shown at the end of this section Here s how the database table is built First any fields listed in the KEY IS clause of the SELECT are included p o number in this example Then the compiler takes the largest record p o detail record and lists
204. caeten cae D 2 Acu4GL for ODBC Installation and Setup ce eeeeeeeeeneees D 10 Filename Translation 2 00 00 es eseeceeecsseseeseesecseceesceaeceseneeeeneeseeerenes D 17 Deciinal Points siie sie edie ice cen eee ee eee D 18 Configuration File Variables 0 0 ccsssssecsseeceseeseeeeeeceeeneeeeeeeenee D 18 Mixed case SQL Identifiers ccccccccccssecsssesscecsseeesscessessseeeseeeees D 35 Record and Table Locking ce seseeeesececeeeseeseceseeceeneeeeserenes D 35 limits atid Ranges iceri so ceskeaes Rect dvh etna sbieastetotdismasiaiiae D 36 Driver Requirements 25 0 c cciescteceseesesecciessnsoteccessveseostaeernees D 36 Data Type Mapping 2 02 ccce cecieasbetiae ect dereey eieeeeoneriees D 38 Troubleshooting rieien iaiaeiaeiaa eis D 42 Common Questions and Answers c ccscecssessssessscessecssesenseeeseeess D 45 D 2 m Acu4GL for ODBC Information D 1 ODBC Concepts With Acu4GL for ODBC your Windows based application can access the most common database formats found on desktop computer systems as well as relational database management systems on UNIX or Windows NT servers This section gives a brief overview of concepts you Il need to work with ODBC D 1 1 What Is ODBC Open Database Connectivity ODBC is a library of standardized data access functions It s intended to give programmers a way to access and manipulate data in a variety of data sou
205. ctnies E ie Rik Rea ee ee aa 10 2 10 2 Questions and ANSWETS cccccsecessscecessececescecesseecsenececececessececessecesasesssaeecseaeeesneeeenas 10 2 Contents iv Appendix A Acu4GL for Informix Information A 1 Getting Started with Acu4GL for Informix eee eee ceeesee ce cnseeecneeseeneeees A 1 1 Installation Preparation cc eeceeseceeeecsseeeceeereeceeencecereecaeeeeeeceseeesaeeeneens Av 12 Installation Steps vic Sci sie tists seen dee E ag ene et wench A 1 3 Designating a Database oo eee cece csecnsececeeceseeeeceeceseceseeeassnecsaeaeenaes A 2 Filename Translation esesscessessecssceceseecesceeececeeecseceececeeeecsaceeneessecesaeseneeces A 3 Configuration File Variables onreine ieee mea e Eae Ee oe N Eens A INF DUPLICATE KEY eo E a aia a ae A_INF_NO_TRANSACTION_ERROR 000 ceceseeeeceeeeeeceeeeeeeeneesaeeaeenaes A_INFORMIX_ERROR_ FILE wo eee ceseeseceeceeceeeeseeeeceeeeeeseaeeseeeaesaeeaees DATABASE sits csveven ininve conection ta veesa ti Seiten eee endian aA INE LOGIN osiectic assesses coo estima elie ieee EEEE saat INE PASSW Dinen hl atest E eaves a AS E ee de ieee le MAX CURSORS a toe setesb ate scpheck oot ts E EEr A E a EE ASEE E SERE EE AA Informix Performance ssriisra iei idnina aen a oae ao o T a io aioa A S Techical Tips tss sccsesseesssasessgsssccsseepeseechius sapee isin sheehashbaea E E E E TS i A 6 Supported Features n sentiet rr ei ee ed n EE oes EEE E K E A Limits and RAN BES eierne a ae E R
206. cu4GL product and lists the RDBMS s technical specifications as well as troubleshooting options 1 3 Accessing Data The standard file system supplied with ACUCOBOL GT is the Vision indexed file system On VAX VMS systems RMS is used instead of Vision Vision offers a wide variety of features including variable length records data compression and data encryption At your option Vision can be replaced by or used in conjunction with other indexed file systems such as C ISAM and Btrieve database management systems such as Oracle Microsoft SQL Server Informix Sybase and DB2 Accessing Data m 1 7 and data sources accessible through ODBC This is possible because all of ACUCOBOL GT s I O passes through a generic file handler that can accommodate a wide variety of protocols ACUCOBOL GT i gt Vision ee eee m Others Generic file handler ed C ISAM Tii Btrieve Acu4GL interfaces em E 1 3 1 Interface Routines All file systems communicate with the ACUCOBOL GT generic file handler via interface routines The interfaces to external file systems such as C ISAM and the various RDBMSs are available from Micro Focus as add on modules The user is free to add any combination of traditional ISAM interfaces and RDBMS interfaces that will meet a site s particular needs The ACUCOBOL GT runtime system communicates with relational databases via a special family of add on products called Acu4GL 1 8 m Acu4
207. d how to work with them Chapter 4 Using Directives This chapter tutors you on the use of directives the optional comments that control how things look on the database side Chapter 5 Invalid Data Invalid Data tells you about illegal COBOL data items and what happens when they are stored in the database as well as an explanation of invalid database items and how they are translated into COBOL Chapter 6 Working with COBOL This chapter gives you an opportunity to work with COBOL by preparing and compiling a COBOL program Chapter 7 New and Existing Databases The New and Existing Database Files chapter discusses default behavior along with matching existing COBOL data to database data Document Overview m 1 5 Chapter 8 Compiler and Runtime Options This chapter details compiler options and runtime configuration variables that can be used with all of the Acu4GL products Chapter 9 Performance and Troubleshooting The Performance and Troubleshooting chapter provides guidelines for improving system performance and an alphabetical listing of compile time error messages and recommended recovery procedures for each error Chapter 10 General Questions and Answers This chapter lists some frequently asked questions and answers that pertain across the Acu4GL family of interfaces A section in each appendix contains FAQs specific to that RDBMS Appendix A Acu4GL for Informix Information The Informix
208. d pic x 6 Sxfd name date last paid 03 acme employee record date last paid pic x 6 Note that your COBOL names have not changed The new names are used only for the database fields Each time you compile your program and specify Fx to create data dictionaries any field names longer than 18 characters will be checked for uniqueness within the first 18 If any field names are identical for the first 18 characters a compiler warning message will be issued A warning of this type does not prevent the program from compiling and the XFD is generated Example 3 assigning shorter names You may want to use the NAME directive to assign shorter names than those used in your COBOL programs This makes the formation of interactive SQL queries easier and quicker For example XFD NAME EMPNO 03 employee number pic x 8 This directive causes the data dictionary to map EMPLOYEE NUMBER to EMPNO in the database 4 16 m Using Directives 4 3 8 Example 4 matching field names and COBOL FDs If your database already exists and a field name in the database does not match the name used in your COBOL FD you can use a NAME directive to associate the two names For example Sxfd name employee no 03 employee number pic x 8 This directive causes the data dictionary to map EMPLOYEE NUMBER in the COBOL program to EMPLOYEE NO in the database Example 5 renaming fields that begin with a numeric character If your
209. database Runtime Configuration Variables m 8 9 where directory is matched against the file specification and database is used when a directory matches For example if you have two databases data01 and data02 and have COBOL programs written that reference data files in home dataA and home dataB you can set 4GL DB MAP as follows 4GL DB MAP home dataA data01 4GL DB MAP home dataB data02 When the runtime attempts to open a file with a directory specification of home dataA Acu4GL uses the table in database data01 By setting this variable to blank all maps will be reset to nothing so no mapping will be performed In this case the Acu4GL interface behaves as it has always done in the past Currently this feature is available with the following Acu4GL interfaces MSSQL and Sybase Any special instructions will be included in the section describing support See Also The 4GL_USEDIR_LEVEL variable which determines how many levels of directory information to use as part of a table name 4GL_DB_MAP interacts with 4GL_USEDIR_LEVEL in the following way 1 4GL_DB_MAP is tested first to determine which database to search for the table 2 Then 4GL_USEDIR_LEVEL is used to change the final name of the table AGL_EXTRA_DB_COLS_OK 4GL_EXTRA_DB_COLS_OK allows the database table to have more columns than the COBOL program s corresponding file descriptor If the 4GL_EXTRA_DB_COLS_OK variable is set to True
210. de or These two characters have special meanings in the pattern i matches any number of characters matches a single occurrence of any character For example CUST matches CUST0001 and CUSTOMER does not match CUST001 or CUST00001 CUST matches all of the above CUST 1 matches CUST001 and CUSTO0001 and CUST00001 does not match CUSTOMER QMER matches CUSTOMER does not match CUSTO01 or CUSTO001 The XFD_MAP variable is read during the open file stage of any Acu4GL products linked into the runtime 3 12 m Data Dictionaries XFD values can be replaced or be added to the end of existing XFD map values by setting the XFD_MAP_RESETS configuration variable This variable determines whether setting the XFD_MAP adds to or replaces the existing value When this variable is set to 0 off false no setting the XFD_MAP adds new value patterns to the end of the existing value When it is set to 1 on true yes setting the XFD_MAP replaces the existing value with a new value The default value is 1 on true yes This variable may be useful if you need to include multiple XFD_MAP lines in a configuration file and want to avoid setting and resetting the variable When multiple lines exist all patterns are used in the order they are listed Using Directives Key Topics What Are Directives oooi noaee aeiiae eee 4 2 DPA CCELV CS VODA esses kets ckiseen casecieagesebeisebvasceshcuseanapieebp
211. dicates the files owned by yourself The type of OPEN being issued for the file determines the effects of this setting Examples If an OPEN INPUT or OPEN I O is issued and a USER_PATH variable is defined in the runtime configuration file Acu4GL searches for a user of the named file in the list of users in USER_PATH The first valid file is opened If USER_PATH is defined and the current user is the owner of the file the current user must be included as one of the users as indicated by a or the setting of your login schema A_DB2_LOGIN in the USER_PATH If this is not the case even though the current user has created the table it will not Configuration File Variables m F 27 be found and a file error 35 will result This circumstance can occur if the file was created with the OPEN OUTPUT phrase and is not an element in USER_PATH When the table is created the current user will be the owner of that table When the runtime attempts to open the table the runtime will not look for tables owned by the current user unless USER_PATH is not set or unless or the user s current schema is part of the USER_PATH setting If an OPEN INPUT or OPEN I O is issued and no USER_PATH variable is in the runtime configuration file Acu4GL searches for a user of the named file in the user named for login A_DB2_LOGIN Acu4GL opens the first file that has a valid combination of user and file name If an OPEN OUTPUT
212. dows NT server machine Step 1 Install SQL Server Sybase version 11 0 or later must be installed and configured on the Windows NT server machine before you install Acu4GL for Sybase on the client machine Follow the instructions from your RDBMS vendor The isql product which is an interactive query tool is also necessary for installing the ACUCOBOL GT stored procedures The Acu4GL product does not need isql after installation but it is a tool that can give you quite a bit of flexibility It allows you to do database work outside of COBOL including interactive queries table creation table modification and creation of views constraints and relationships between tables Micro Focus does not provide these products Step 2 Copy the batch file The file syb_inst cmd is a batch file from Micro Focus that will create the syb_inst sql file which is the collection of stored procedures necessary for executing the Acu4GL product Copy syb_inst cmd to your server machine into a directory of your choice Step 3 Execute the batch file To execute the batch file enter SYB_INST LockDatabase where LockDatabase is the database you want to use for the internal ACUCOBOL GT lock tables If this database does not already exist it will be created Everyone who will use the Acu4GL for Sybase product must have write access to this database Installation and Setup m E 19 This step creates syb_inst sql which
213. duce a directive is with an asterisk in the Indicator Area In this case you begin the directive with the letters XFD and enclose the entire comment in double parentheses For example XFD NAME EMP NUMBER There should be no space between the asterisk and the double left parentheses Spaces are permitted elsewhere on the line as separators You may use either form of the directive syntax or both in your applications In addition note that directives are case insensitive and that hyphens and underscores are considered equivalent Thus for example 4 4 m Using Directives SXFD VAR_LENGTH SXFD VAR LENGTH Sxfd var_length Sxfd var length are all recognized as equivalent by the Acu4GL products Two or more directives that pertain to the same line of COBOL code may be combined on one comment line The directives should be separated by a space ora comma For example to specify both USE GROUP and NUMERIC at the same time you would add this line SXFD USE GROUP NUMERIC or XFD USE GROUP NUMERIC The following pages describe each of the directives in alphabetical order 4 3 Directives Supported by the Acu4GL Interfaces The Acu4GL interfaces support the following directives ALPHA BINARY COMMENT COBOL TRIGGER DATE FILE NAME NUMERIC SECONDARY_TABLE USE GROUP VAR_LENGTH WHEN XSL Directives Supported by the Acu4GL Interfaces m 4 5 4 3 1 ALPHA The ALPHA direc
214. e If you are not the owner you must refer to it with the owner of the table as a prefix Different owners can thus have tables of the same name However this is not true when you use the Acu4GL for Microsoft SQL Server interface Acu4GL for SQL Server works a little differently It automatically determines the owner name it will use to reference a table It is therefore essential that there not be multiple tables with the same name in a single database even though the tables have different owners If there are multiple tables the Acu4GL for Microsoft SQL Server product will not necessarily find the correct one and no diagnostic will be issued Note that table names include dots as separators Because of this you must make sure there are no extensions on COBOL file names that will be converted to table names For example if you were to have a COBOL file named IDX1 DTA Acu4GL for Microsoft SQL Server would attempt to open a table DTA with owner IDX1 You can avoid this problem either by Microsoft SQL Server Concepts Overview m B 3 renaming your COBOL file in your source program or by using an ACUCOBOL GT runtime configuration file variable to map the file name to an allowable file name such as IDX1 DTA IDX1 In the above example IDX1 DTA is the name in the ASSIGN clause of the file s SELECT statement If you map your file name to a new name we recommend that you simply drop the extension to form the new name Here
215. e yes A_MSSQL_NO_RECORD_LOCKS Setting this variable ON will cause all READS to be treated as READ NO LOCK which can improve performance but has the obvious consequences While the default value is Off false no this configuration variable can also take the value of On true yes A_MSSQL_NO_TABLE_LOCKS Setting this variable ON will cause the interface to not use the AcuOpenTables table which causes all table locking to be disabled This can improve performance on OPEN and CLOSE statements While the default value is Off false no this configuration variable can also take the value of On true yes A_MSSQL_NO_23_ON_START When A_MSSQL_NO_23_ON_START is set to a nonzero value START does not detect whether records actually exist Because it does not detect the existence of records it is possible when using this variable to do a START without error and for the next READ NEXT to return END_OF_FILE contrary to the ANSI standard While the default value is Off false no this configuration variable can also take the value of On true yes Example A_MSSQL_NO_23_ON_START number where number can be a zero or nonzero value B 22 m Acu4GL for Microsoft SQL Server Information A_MSSQL_NT_AUTHENTICATION The A_MSSQL_NT_AUTHENTICATION configuration variable indicates whether Microsoft SQL Server will authenticate users based on their Windows login If this variable is set
216. e Demonstration Program m 2 7 Here is the COBOL FD file descriptor that matches the acuorders table Note that the FD entries must match the names of the RDBMS fields and must match their data types fd orders 01 order record 03 order num pic x 4 03 order fields 05 order date pic 9 6 05 customer num pic 9 3 05 ship instruct pic x 40 05 backlog pic x 05 po num pic x 10 05 ship date pic 9 6 05 ship weight pic 9 6 v99 05 ship charge pic 9 4 v99 05 paid date pic 9 6 First we ll compile the demo program Then we ll prepare the data and run the demo Compiling the demo program To compile the demo program for use with the RDBMS data source enter one of the following commands For ACUCOBOL GT Version 4 2 or later 32 bit version ccb132 Fx o demo demo cbl For ACUCOBOL GT Version 4 2 or later UNIX version ccbl Fx o demo demo cbl This compiles the program and generates the ACUCOBOL GT data dictionary acuorders xfd The runtime system will use this data dictionary to map RDBMS data types to COBOL data types Verifying the runtime Before starting the demo program you need to verify the runtime To do this enter the following runcbl vv or wrun32 vv 2 8 m Getting Started Be sure that the version information you receive references your Acu4GL product Starting the demo program Be sure the RDBMS data source is available and that all the non Acu4GL environment variables req
217. e Sybase documentation on isql A_SYB_TRANSLATE_TO_ANSI Setting this variable to On true yes causes the Acu4GL interface to call the same translation function used by the Windows runtime to translate characters going to the server into the OEM character set and to translate characters coming from the server to ANSI The default is Off false no which indicates that the Acu4GL interface does not call the translation function but passes the data as is to the library This variable applies only to the Windows version of the Acu4GL for Sybase interface Configuration File Variables m E 41 A_SYB_UNLOCK_ON_EXECUTE Setting this variable ON causes all invocations of I IO using the EXECUTE opcode to unlock all records Normally records are unlocked when a transaction finishes But if users perform their own transaction management using sql acu which calls I IO using the EXECUTE opcode the interface never knows to unlock records because it doesn t check the text sent to the database to see if it associated with a transaction While the default value is Off false no this configuration variable can also take the value of On true yes A_SYB_USE_DROPDOWN_QUERIES Setting A_LSYB_USE_DROPDOWN_QUERIES to a nonzero value causes select queries sent to the database to be of the drop down variety instead of a single large query This variable is accessed only during a positioning operation so you can
218. e and follow the progress of the issue or post additional information directly through the website Following is our contact information Phone 1 858 795 1902 Phone 800 399 7220 in the USA and Canada Fax 1 858 795 1965 E mail support microfocus com Online http supportline microfocus com For worldwide technical support information please visit http supportline microfocus com 2 3 Installation The installation for your particular RDBMS can be found in the appendices of this manual Appendix A Acu4GL for Informix Information Appendix B Acu4GL for Microsoft SQL Server Information Appendix C Acu4GL for Oracle Information Appendix D Acu4GL for ODBC Information Using the sql acu Program m 2 3 Appendix E Acu4GL for Sybase Information Appendix F Acu4GL for DB2 Information Each of the appendices contains an overview of the Acu4GL functions installation instructions setup instructions technical specifications and a troubleshooting guide Note Before going any further in this manual go to the appendix listed above that pertains to your RDBMS and begin the Acu4GL installation and setup processes Once the installation is complete and you are ready to run return to this chapter and begin section 2 4 Using the sql acu Program 2 4 Using the sql acu Program 2 4 1 Acucorp provides a utility program called sql acu This program gives you access to some of the standard SQL c
219. e by which an application program accesses operating system and other services An API is defined at source code level and provides a level of abstraction between the application and the kernel or other privileged utilities to ensure the portability of the code An API can also provide an interface between a high level language and lower level utilities and services which were written without consideration for the calling conventions supported by compiled languages batch file A text file containing operating system commands which are executed automatically by the command line interpreter A batch file is called a shell script in UNIX since it is the UNIX shell which includes the command line interpreter Batch files can be used as a simple way to combine existing commands into new commands Binary Large Object BLOB A large block of data stored in a database such as an image or sound file A BLOB has a structure that cannot be interpreted by a database management system but is known only by its size and location Glossary 2 m buffer An internal memory area used for temporary storage of data records during input or output operations Most programs keep track of changes in the buffer and then copy the buffer to a disk Buffers are also used for printing client A computer or program that can download files for manipulation from a server Contrast server See also network CPIO format Copy In and Out format Copy In
220. e following syntax DECLARE cursor_name option_1l CURSOR option_2 FOR lt select gt option_3 In other words different phrases can go in each of the option_X places Also different versions of SQL Server allow different options in each of those places Because of this the Acu4GL product allows customization of the cursor declaration via these three variables The values of these variables are placed verbatim into the declare phrase when building a cursor Note that any errors in the values of these variables may cause your Acu4GL product to be inoperable Be sure to read the SQL Server documentation to determine what phrases are allowed in each case The default values are as follows the limit is 65 characters for each option OPTION_1 SCROLL OPTION_2 blank OPTION_3 For read only This was added because of an issue in SQL Server 6 5 and SQL Server 7 0 that would return incorrect results if this phrase was not used B 14 m Acu4GL for Microsoft SQL Server Information A_MSSQL_DATABASE A_MSSQL_DATABASE specifies the name of the specific database to be accessed You cannot open any database files until you have set this variable Example A_MSSQL_DATABASE stores indicates the stores database is to be accessed A_MSSQL_DEADLOCK_LOOPS Use A_LMSSQL_DEADLOCK_LOOPS if you expect that more than one user will be opening a lot of tables at the same time This configuration variable can be used to
221. e in ACUCOBOL GT you must enable it for the database you are creating The precise SQL command depends on the Informix engine you are using as shown below For Informix OnLine enter the following command to use transaction logging CREATE DATABASE database name WITH LOG For Informix SE enter the following command to use transaction logging CREATE DATABASE database name WITH LOG IN acct 1992 acct_log A 26 m Acu4GL for Informix Information Question If you are using an Informix database with transactions enabled you must use ACUCOBOL GT s transaction management capabilities Either use START TRANSACTION and COMMIT or compile with fs or use the sql acu program to issue BEGIN WORK and COMMIT Using a transaction enabled database without ACUCOBOL GT s transaction management capabilities results in the records not being locked and can generate error messages The program pauses to accept an SQL command Now enter the following GRANT DBA TO PUBLIC Then press Enter again to exit the program The database name may be up to ten characters and must contain only letters digits and underscores The first character must be a letter The statement GRANT DBA TO PUBLIC gives the Database Administrator access privileges to all other users Is it possible to use both Informix OnLine and Informix SE on the same machine Yes You ll need to tell the runtime which database eng
222. e indexes can make a difference Using Vision files If you cannot restructure your data but are finding certain operations to be too expensive you might want to consider moving some data into the Vision indexed file system Guiding the data searches You can guide the data searches that result from database queries and thus improve performance by making use of an external variable called A4GL_WHERE_CONSTRAINT This process is explained in section 9 1 2 The WHERE Constraint 9 6 m Performance and Troubleshooting Guideline 3 Program and database interaction A database can interact with your COBOL program in surprising ways When you introduce a database to a mature COBOL application your application may experience errors you have not seen before Being aware of this possibility helps you to prepare your response For example your existing application without the database may rarely exceed the limit on the number of data files that can be open simultaneously But when you add a database you increase the likelihood of this significantly This is because the query processing may often require temporary tables Also the ORDER BY clause used in SQL statements to sequence retrieved data opens temporary work files So you may find that these files cause you to reach the limit sooner Note that proper tuning of the query optimizer can reduce the number of temporary files required When you upgrade to a new version of the
223. e issued on exit from the runtime for example on execution of a STOP RUN Note 4GL_COMMIT_COUNT can be set only in the configuration file It cannot be set programmatically 4GL_COMMIT_COUNT is available only in the Acu4GL for ODBC and Acu4GL for DB2 interfaces AGL_CONVERT_DATE_ZERO If your data uses dates as part of Oracle or Informix database keys the dates cannot be written as NULL or illegal values To write data that includes NULL or illegal values Acu4GL converts the NULL or illegal date values used in keys to a value of 01 01 01 when writing data to Oracle Unfortunately the code would not make a similar conversion when reading the same record and those records written with 01 01 01 were not found This could easily result in writing a record that cannot be read or deleted When the 4GL_CONVERT_DATE_ZERO variable is set to the default setting CONVERTED Acu4GL is able to locate and return those records written using the date 01 01 01 This functionality can be disabled by setting the variable to UNCHANGED AGL_DB_MAP This variable enables you to set one map at a time until all of the desired maps are set by using FILE PREFIX as a list of directories each of which maps to a different database Note that in this case database refers to collection of tables rather than distinguishing between say Oracle and SQL Server The syntax of the value of 4GL_DB_MAP is directory
224. e restarts Stored Procedures m B 31 If you run a set of stored procedures for the database where data is manipulated your production database this database must be the setting for A_MSSQL_LOCK_DB If you run the stored procedures against both the lock database and the production database the lock database can be the setting for A MSSQL_LOCK_DB Note that if you run one version of stored procedures against the lock database and another version against the production database the stored procedures in the lock database override those in the production database Therefore we recommend that you always update your stored procedures with each new installation of Acu4GL so that these procedures are consistent when you run them against the tables in your database This section discusses two types of stored procedures e Procedures that you may want to add to Acu4GL for SQL Server e Procedures provided in Acu4GL for SQL Server that you as the developer or administrator may find useful Note If you are upgrading from an earlier version of Acu4GL be sure to install the new stored procedures We always upgrade stored procedures in such a way that they will be compatible with older versions of the product so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software B 7 1 Developer or Site supplied Stored Procedures This section provides information on st
225. e sp_AcuInit stored procedure from this location This stored procedure is executed when a connection is made to the database therefore sp_AcuInit should reside in the default database for each user if it is not created in the master database See section E 6 2 Built in Stored Procedures for information on the sp_AculInit stored procedure This completes the setup on the UNIX or Windows NT server machine Note If you are upgrading from an earlier version of Acu4GL be sure to install the new stored procedures We always upgrade stored procedures in such a way that they are compatible with older versions of the product so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software Your new version of Acu4GL for Sybase may not run properly without the corresponding stored procedures It can be difficult to maintain multiple copies of stored procedures therefore We recommend that you continue to create the stored procedures in the master or sybsystemprocs database If your installation does not permit this you do have the flexibility to create the stored procedures elsewhere However to facilitate maintenance of the stored procedures We recommend that you create as few databases as possible E 18 m Acu4GL for Sybase Information E 2 4 2 Windows NT Server and Windows Client Installations Complete the following steps to install the Acu4GL product on a Win
226. e syntax for this configuration file variable would be A_INFORMIX_ERROR_FILE INFerrs where INFerrs is a file of a specified format containing a mapping of database specific errors to COBOL errors One such entry might be 1 DUPLICATE_RECORD DATABASE DATABASE specifies the name of the specific database to be accessed You cannot open any database files until you have set this variable Example DATABASE stores indicates the stores database is to be accessed Note If you choose you can set the DATABASE variable in the startup script for the session A 12 m Acu4GL for Informix Information INF_LOGIN INF_LOGIN indicates the user name under which you want to connect to the database system This is an optional variable If INF_LOGIN and INF_PASSWD are not set a default login is performed If these variables are set there must be a matching UNIX login name and password Example To connect to the database with the user name MYNAME you would specify INF_LOGIN MYNAME in the configuration file See also INF_PASSWD configuration variable INF_PASSWD The variable INF_PASSWD should be set to the password assigned to the database account associated with the user name specified by INF_LOGIN If INF_LOGIN and INF_PASSWD are not set a default login is performed If these variables are set there must be a matching UNIX login name and password Example For example if the account
227. e that contains tables accessed by Acu4GL the stored procedures that were previously in the master or sybsystemprocs database Note that the stored procedures are executed without being prefixed by a database name and Sybase requires that such stored procedures must be in the master or sybsystemprocs database The interface also searches for and executes the sp_AcuInit stored procedure from this location This stored procedure is executed when a connection is made to the database therefore sp_AcuInit should reside in the default Installation and Setup m E 13 database for each user if it is not created in the master database See section E 6 2 Built in Stored Procedures for information on the sp_AcuInit stored procedure This completes the setup on the UNIX or Windows NT server machine Note If you are upgrading from an earlier version of Acu4GL be sure to install the new stored procedures We always upgrade stored procedures in such a way that they are compatible with older versions of the product so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software Your new version of Acu4GL for Sybase may not run properly without the corresponding stored procedures It can be difficult to maintain multiple copies of stored procedures therefore we recommend that you continue to create the stored procedures in the master or sybsystemprocs database If your
228. e the following guidelines F 18 m Acu4GL for DB2 Information e Begin comment lines with Blank lines are also considered comments e Break the rest of the file into sections with each section header comprising all the information enclosed in brackets from the data source error function The following example leads to the entry in the sample DB2 error file OdbcOneInfo State 23505 Native Error 803 IBM CLI Driver DB2 NT SQL0803N One or more values in the INSERT statement UPDATE statement or foreign key update caused by a DELETE statement are not valid because they would produce duplicate rows for a table with a primary key unique constraint or unique index SQLSTATE 23505 Setting f_errno 19 Leaving error x File system error value 803 gt gt gt file status 9D 803 e Include two fields in each line in the section the internal error number and an ACUCOBOL GT mapping string Using the same example you would include this line in the error_map file 803 E_DUPLICATE T The valid values for the second field are as follows T _SYS_ERR _PARAM_ERR _FILES fe by O ro Qe Q iw E C_LOCKED ra ee ee ede GQ2Z2U0W WW G ins tA H Q D H al Wd ER H O Qe nN iw Configuration File Variables m F 19 E_MISSING_F
229. eatures A 19 filename interpretation A 8 getting started A 2 installation A 3 libraries shared A 6 limits A 21 linking the runtime A 5 runtime errors A 23 switching file systems A 18 technical specifications A 18 troubleshooting A 22 unsupported data types A 21 Acu4GL ODBC application D 6 configuration variables D 18 creating map files D 22 data sources D 7 data types D 38 designating the host data source D 16 driver manager D 6 driver requirements D 36 driver test D 37 drivers D 6 filename interpretation D 17 D 18 getting started D 10 installation and setup D 10 m Index 7 limits and ranges D 36 mapping COBOL data to ODBC data D 39 mapping ODBC data to COBOL data D 40 origins of ODBC D 2 overview D 2 record and table locking D 35 restrictions D 3 runtime errors D 42 SQL errors D 44 structure D 3 troubleshooting D 42 Acu4GL Oracle checking system parameters C 14 configuration variables C 21 configured login C 16 creating a new runtime C 10 cursors per file C 22 database table C 28 designating host file system C 17 features C 28 filename interpretation C 21 getting started C 7 installation for UNIX C 9 installation for Windows C 7 Instant Client C 20 libraries shared C 13 linking the runtime C 12 open_cursors parameter C 5 Oracle file system limits C 29 record locking C 3 relinking C 8 runtime errors C 30 security C 6 setting up the search path C 18 setting up the user environment C 16 Index 8
230. ecified are checked first Therefore when data should be of type DATE or BINARY a DATE or BINARY type is located and used if the data source supports it If the COBOL data type is usage float or usage double a data source type of FLOAT REAL or DOUBLE is used depending on what is available If none of these is available the Acu4GL product abides by the next rule If the COBOL data type is numeric a numeric type is used in the data source The numeric type chosen depends on how large the COBOL data type is and how many digits to the right of the decimal point if any there are e For example if the COBOL data type is PIC 99 the data source types checked for are TINYINT SMALLINT INTEGER BIGINT DECIMAL NUMERIC CHAR The first of these that exists is the type that will be used for that column e For another example if the COBOL data type is PIC 9 6 v99 the data source types checked for are DECIMAL NUMERIC DOUBLE FLOAT REAL CHAR Again the first of these types that exists is the type that will be used for that column e Anything else will use CHAR Occasionally you may encounter a data source type that supports only type CHAR which is the only data type that is guaranteed to exist according to the ODBC specification Under these data sources all the COBOL data types will be mapped to CHAR types Mapping ODBC data types to COBOL data types Sometimes developers are in a situation where they need to create a COBOL
231. ection is locked out of the row that is added or updated The result is that it is not possible to WRITE or REWRITE records containing TEXT or IMAGE data while inside a transaction Note Large columns cannot be used in conjunction with transaction management because any column larger than 255 bytes 254 characters is automatically converted to a TEXT or IMAGE column when the table is created If you have TEXT or IMAGE columns in your table WRITEs and REWRITEs fail unless this variable is set to On Configuration File Variables m E 31 See also Section E 5 Record and Table Locking A_SYB_FAST_ACCESS A_SYB_FAST_ACCESS is a configuration variable that is set from your COBOL program Files opened while this variable is set to a nonzero value are optimized for forward sequential access While the default value is 0 off false no this configuration variable can also take values of On true yes We implemented this option to substantially improve the READ NEXT performance in some cases For example testing the benchmark program iobench cbl in three different ways yielded the following results for the READ AND SKIP operation No FAST_ACCESS 72 76 seconds FAST_ACCESS ROWCOUNT 0 148 88 seconds FAST_ACCESS ROWCOUNT 10 8 09 seconds 10 is the perfect value for ROWCOUNT in this benchmark because the program does a START 10 READ NEXT operations and then does it again For certain rep
232. ed When this is set the Acu4GL interface converts data the same way it does for keys 4GL_ILLEGAL_DATA can also be set to Null to indicate that illegal COBOL data other than keys should be converted to null This is the default behavior 5 2 Invalid Database Data When Acu4GL receives a null field from the database it translates it to COBOL as follows Numbers including dates zero Text including binary spaces See the DATE directive in Chapter 4 for additional information about the handling of invalid dates 5 4 m Invalid Data 6 Working with COBOL Key Topics Preparing and Compiling Your COBOL Program 006 6 2 Compiling With No Directives 00 0000 cece eseeseneeseneeseeeseteeseeeeaees 6 4 Compiling With the WHEN Directive 00 0 cece eset cnet ereeeenees 6 6 Using Additional Directives eee cseecesecsececeeeeseaeeeserenaeneees 6 8 Creating File Descriptors and SELECT Statements 6 10 6 2 m Working with COBOL 6 1 Preparing and Compiling Your COBOL Program After the environment has been set up for the Acu4GL interface you are ready to use the system The following example illustrates how to set up a COBOL program to use your Acu4GL RDBMS product Note If you are not familiar with the XFD directives described in Chapter 4 Using Directives you may want to read that chapter before continuing with this section The purchase
233. ed for DB2 you will need to do the following 1 Ensure that your execution path contains the name of the directory in which you placed the runtime executable that includes Acu4GL for DB2 2 Set the A_DB2_ LOGIN and A_DB2_PASSWD variables either in your environment or in the ACUCOBOL GT runtime configuration file Also consider whether or not setting the USER_PATH variable Installation and Setup m F 11 would be useful in your set up situation For security reasons it is best to set the password variable from your COBOL program by asking the user to enter a password and then executing SET ENVIRONMENT A_DB2_PASSWD TO user entry 3 You may want to make and use a personalized copy of the configuration file to avoid impacting other users The ACUCOBOL GT documentation describes how to use the A_CONFIG environment variable or the c runtime option to identify a personal configuration file 4 Define any other configuration file variables you require for your unique environment Possible variables define error map file location locking method commit count commit timing and BINARY CHAR type conversion For detailed information on ACUCOBOL GT configuration file variables see section F 5 Configuration File Variables F 2 5 Designating the Host File System When your COBOL application opens an existing file most file systems linked into the runtime will be searched for the named file However eac
234. ed on the response ACCEPT RESPONSE NO ECHO SET ENVIRONMENT A_SYB_PASSWD TO RESPONSE Note If the user has been set up without a password this variable need not be set Configuration File Variables m E 39 A_SYB_ROWCOUNT This variable has an effect only if you are reading on a key that does not allow duplicates or if you have added an Identity column to the table A_SYB_ROWCOUNT determines how many rows are returned by a SELECT statement sent to the server This variable can be used to speed up the Acu4GL product For example if you know you will be reading only one record at a time and reading from a unique key you can set A_SYB_ROWCOUNT to 1 thus speeding up the processing If you know you are going to be reading records ten rows at a time set A_SYB_ROWCOUNT to 10 If you don t have any information about how many rows are going to be requested set this variable to 0 which is the default Note Setting this variable to a non optional value can actually degrade performance since the interface may be forced to issue more SELECT statements once the rowcount has been determined Use caution when setting this variable See also A_SYB_ADD_IDENTITY runtime configuration file variable A_SYB_SELECT_KEY_ONLY This variable directs the interface to select key columns only when searching for records Its use can improve READ performance on large tables with many rows When set to True
235. edundancies and give you optimum performance 01 ar codes record 03 ar codes key 05 ar code type pic x 05 ar code num pic 999 01 ship code record 03 filler pic x 4 03 ship weight pic s999v9 03 ship instruct pic x 15 01 terms code record 03 filler pic x 4 03 terms rate 1 pic s9v999 03 terms days 1 pic 9 3 03 terms rate 2 pic s9v999 03 terms descript pic x 15 The following diagram shows how Acu4GL creates database columns for some of the fields in the COBOL record while the data dictionary maps other fields to those columns this means that all the fields are accessible to the COBOL program x o 5 N Q N A o7 CA Pa Datab x se 2 a atabase er b b b b column E amp P amp amp Character 1 234 5678 91011 12131415 1617 18 19 20 21 22 23 24 position XFD entry only Ye mapped to DB Nae h y z See section 3 2 2 Defaults Used in XFD Files for a description of the rules that Acu4GL follows as it builds the database table and an explanation of how you can override those rules when necessary XFD Files m 3 5 3 2 2 Defaults Used in XFD Files Several elements of COBOL require special handling when data dictionaries are built These include multiple record definitions REDEFINES FILLER and OCCUR This section describes how the compiler handles each of these situations Note that in many instances you can override the default behavior described below b
236. ee ceeceeeeeeeeecneeesecaeceseeecsseeeeneees D 14 D 2 6 Designating the Host Data Source 0 eee eeeeeeeeeeeeeeecneeseecaecaecaeceaeeecneenseees D 16 D 3 Filename Translation ce n e a E E E E ES D 17 D4 Decimal Points a a aE a a N A a Gee bes uth E ee D 18 Contents vii D 5 Configuration File Variables cee ececeecseeesecsseeseceecesceseeeeeeseeeesesecsaecaecsaecsecneesaeeas D 18 AGILE MAX DATE ze hna eie e E EAE IR ine ee R E enna nen eess D 18 4GIo MIN DA TE anei n a E eI E TEVI S D 19 A_ODBC_ALTERNATE_COMMIT_LOGIC 200 ceceeeeceseeeeceeceeeeeeeeneesaeeaee D 19 A ODBC CATALOG ae aiae i areosa eara et aooaa EEEE Te ie Eeer AEE EEEE E SES ES D 20 A_ODBC_COMMIT_ON_ BEGIN iesse sioa seii D 21 A ODBC _ DATASOURCE vitrero sera ape rE sb E Eer TETE T EA E D 21 A ODBC ERROR MAP FILE neniet serineto ia Teenis i ar k Teee ieSe D 22 A ODBC_ISOLATON LEVEL so scscccsicesiscsssctsssschessesescesasevechsebiecedcasassseesesvecigeesets D 24 A_ODBC_LOCK_METHOD aeri a e r a n a e D 24 ASODBCEOGIN dantan a E EE E E A Ga RE D 26 A_ODBC_NO_NULL_COLUMNS ooo ec EEVEE EN a N is D 27 A ODBC PASOM D a e e e a ae aree eee Eae o a a reves D 27 A ODBC PRINT LOG 2s o hilar eu eee A nea D 28 A ODBC QUOTE IDENTIFIERS s ses s s i e a a E E E E A RE D 28 A ODBC STRICT EQUA Dece n E E EEE EEEE E ES D 28 A ODBC TABLE TYPES vieden orare eE tiie niin EERE D 29 A ODBC UNSIGNED TIN YINT 52 5 sos scssesiscetsstssstenes ses steveasi
237. eeneeeeeseenes 9 15 9 2 m Performance and Troubleshooting 9 1 Performance Issues This chapter provides guidelines for improving system performance Also included is an alphabetical listing of the error messages that can occur during the compilation of your program Each message is followed by an explanation and a recommended recovery procedure Adding a relational database management system brings significant complexity to any computer system A few key guidelines may help to improve the performance of the system and prevent problems as the database grows 9 1 1 Guidelines The following sections describe some areas for you to consider as you prepare your database and your COBOL program Guideline 1 Database administrator A site with a database management system needs a Database Administrator DBA The administrator is critical in any large database installation The DBA checks performance statistics and memory usage performs general maintenance and backup for the database initiates traces executes database utilities sets buffer sizes determines how often buffers are flushing and in general understands how database settings and events affect overall performance The DBA also performs periodic tuning of the database including e using monitoring tools e allocating table spaces e examining output of the query optimizer to ensure that the most efficient paths are being used e updating table statistics e cre
238. ees E 25 Record and Table Locking cee sesessesececeeeseeseceseeeeeneeeeserenes E 43 Stored Procedures 206i5 ccicccanienininaiaaaiwacwailune E 45 Limits and Ranges eceseseeeeeecsseeeseesecsecessceaeceseeeeenaeseeeeenee E 52 Runtime Ervrors cccccccccssesseceeceseesccescesscescesecencecnecaseseecseceaeeeeeaees E 53 Common Questions and ANSWEFS ccscccssessssessscessecssseesaeenseesees E 56 E 2 m Acu4GL for Sybase Information E 1 Sybase Concepts Overview A quick overview of some basic design concepts underlying the Sybase Database Management System will help you interface your COBOL program to it Servers A Sybase server is one copy of the database engine executing on a computer A server has a name and when a program wants to access the database controlled by a server the program asks for a connection to that server by name Multiple servers can be executing on a single machine controlling different databases The default name that Sybase gives to a server is SYBASE Naming of servers is discussed in section E 6 Acu4GL for Sybase Configuration File Variables under the configuration variable A_SYB_DEFAULT_CONNECTION Table ownership Table names in Sybase have the form database owner table_name Within Sybase if you are the owner of a given table you can refer to it as just table_name If you are not the owner you must refer to it with the owner of the table as a prefix Di
239. eeseseaeeneesaeeaes B 25 A_MSSQL_UNLOCK_ON_EXECUTE s eeeseseeseseseesseenscsessseessennsesseonsonsesse sees B 25 A_MSSQL_USE_DROPDOWN_QUERIES coe ceececceesceeceeeeeeeeseeseeesaecaeeaenaes B 26 A MSSQL VISION LOCKS FULE oroe eree seee ee eiS B 27 B 5 Using the Database Table eee aenant epei eoe E seee e erra Sare sis B 28 B 6Table LOCK iN 8 oo ccevss sce a E E E A E R aed oy B 28 B 7 Stored Procedures inasin E A E E EE a B 30 B 7 1 Developer or Site supplied Stored Procedures ssseeeseseeeesseressseeresrssererserees B 31 B 7 2 Built in Stored Procedures es esseeeeeeseseeeseeereesesresseeseserseereeereereeereeseereeesessee B 36 B 8 Limitsand Ranges erniet oec sebeaden Gichcn conse sates ions SEO DEEE eE EEEE EE RETEN EEE ESS B 38 BQ Runtime Errors merien iiron Eea EEA E REEE EA E E E E a a B 39 B 10 Common Questions and Answers cccscccessscesescecesseceseececeeeecesseceseaseeseeeeeessaeeessaees B 42 Appendix C Acu4GL for Oracle Information C 1 Oracle Concepts Overview rosiorii ereire coer o nri e EN aE ae aE oeni C 2 C 2 Installation and Setup sco soe csssktares sssebeas vestecesecesctuscsseg sadedeoesozsceuso eg iE oe raer Tr EEs C 7 C 2 1 Windows Installation Steps eee ee eeeeseeseeceecsseeseceseeseeeeceeeeeeseaeeeeeeaeesaeeaees C 7 C 2 2 UNIX Installation Steps sci scs0 05 ses sc0s yes seeseesbesesesctdecs soe svcdessdsssbvnesscuseveteaedsscosedesgeds C 9 C 2 3 Completing the Installation
240. eligible data items for which the SECONDARY_TABLE directive is not specified SECONDARY_TABLE is ignored for certain data items These include e any field that is part of a key e any field that is an indicator for a WHEN directive If the table size is not exceeded in the first pass then in a second pass the runtime appends to the original table all items marked SECONDARY_ TABLE that can be accommodated When the first table reaches a limit either in total number of columns or total number of characters that table is created and a new table is begun Items that did not fit into the previous table are placed into a subordinate table in the order in which they are encountered 4 18 m Using Directives The process repeats until all items have been accommodated It is permissible to place the SECONDARY_TABLE directive just before a level 01 record definition In this case it applies to all fields underneath the level 01 Syntax SXFD SECONDARY_TABLE XFD SECONDARY_TABLE Example Sxfd secondary_table 01 description pic x 80 4 3 10 USE GROUP The USE GROUP directive allows you to enter a group item into the database as a single field instead of using the elements contained in the group This is necessary if the item is stored in an existing database as a group rather than as individual fields Combining fields of data into meaningful groups for database storage also improves I O efficiency Synta
241. em SQL_VARCHAR PIC X nn nn maximum size of item SQL_DECIMAL PIC 9 n v9 m SQL_NUMERIC PIC 9 n v9 m SQL_SMALLINT PIC 9 5 COMP 5 SQL_INTEGER PIC 9 9 COMP 5 SQL_REAL USAGE FLOAT SQL_FLOAT USAGE FLOAT SQL_DOUBLE USAGE DOUBLE SQL_TINYINT PIC 9 3 COMP 5 SQL_BIGINT PIC 9 9 COMP 5 SQL_BINARY PIC X nn SQL_VARBINARY PIC X nn SQL_LONGVARBINARY PIC X nn SQL_DATE PIC 9 6 or PIC 9 8 SQL_TIMESTAMP USAGE DISPLAY Note The BINARY data types are usually of a form that COBOL can t understand anyway You will usually just read these columns and rewrite them unchanged If you have more information about the data in the columns you might be able to do something else but this requires more knowledge about the columns D 42 m Acu4GL for ODBC Information The DECIMAL NUMERIC DATE and TIMESTAMP types usually have special representations in a data source which really doesn t match any COBOL data type exactly When the Acu4GL product binds the data a technical term it asks the data source to return it in character form so the most efficient COBOL data type would probably be USAGE DISPLAY D 11 Troubleshooting D 11 1 This section lists the Acu4GL error messages that could occur during execution of your program Chapter 9 provides information on compile time errors and also provides several methods for retrieving runtime errors An explanation and a recommended recovery procedure follow each message
242. en opening Microsoft SQL Server tables DB2 tables or tables in an ODBC compliant application The standard syntax for Microsoft SQL Server tables is server database owner table with a dot as the separator This syntax causes the filename idx1 dat to be interpreted as the table dat owned by the user idx1 By setting this variable which must be set in the configuration file and cannot be set via SET ENVIRONMENT the Acu4GL for Microsoft SQL Server product will ignore the listed suffixes There can be up to 10 ignored suffixes more than that are not kept internally so will be ignored The default value for this variable is dat Runtime Configuration Variables m 8 11 Example 4GL_IGNORED_SUFFIX_LIST dat idx txt AGL_ILLEGAL_DATA 4GL_ILLEGAL_DATA determines how COBOL data that is considered illegal by the database will be converted before it is stored in the database The default value is NULL This causes all illegal data except key fields to be converted to null before it is stored The value CONVERTED causes the following conversions to occur Illegal LOW VALUES minimum possible value 0 or 99999 minimum possible date value 01 01 01 Illegal HIGH VALUES maximum possible value 99999 maximum possible date value database dependent Illegal SPACES zero or 01 01 01 for a date field Illegal data in key fields is always converted regardless of the value of this config
243. ent E 21 setting up user accounts E 21 shared libraries E 10 stored procedures E 46 table ownership E 2 troubleshooting E 53 m Index 41 syntax directives 4 3 Indicator area 4 3 using the symbol 4 3 system parameters Oracle C 14 systems designating host file DB2 F 11 Oracle C 17 SQL Server B 8 Sybase E 22 systems Informix file A 18 T table locking ODBC D 35 SQL Server B 28 Sybase E 43 table ownership Oracle Acu4GL C 6 SQL Server B 2 Sybase Acu4GL E 2 tablename_delete procedure SQL Server B 33 Sybase E 48 tablename_insert procedure SQL Server B 33 Sybase E 47 tablename_read procedure SQL Server B 34 Sybase E 48 tablename_startnnn procedure SQL Server B 35 Sybase E 49 Index 42 m tablename_update procedure SQL Server B 34 Sybase E 49 tables and multiple indexes 9 4 creating with sql acu 2 3 database formation of 3 3 Oracle database C 28 owners B 15 SQL Server database B 28 technical tips Informix A 18 test ODBC driver D 37 testing for illegal data 8 10 TEXT fields illegal COBOL data 5 2 matching to database 7 3 tracing files 8 16 transactions DB2 F 2 file options compiler 8 2 guidelines 9 4 implied file options compiler 8 4 Oracle C 2 C 19 C 28 translation COBOL I O 1 10 filenames Acu4GL for DB2 F 13 Acu4GL for Informix A 8 Acu4GL for ODBC D 17 D 18 Acu4GL for Oracle C 21 Acu4GL for SQL Server B 10 Acu4GL for Sybase E 24 troubleshooting Acu4GL DB2 F 30 Acu4GL for In
244. eractive SQL B 4 interface passing I O requests to 1 13 routines 1 7 interpretation of filenames B 10 invalid COBOL data 5 2 database data 5 3 dates handling 4 10 key data 5 3 other data 5 3 isolation levels setting D 24 F 19 ISQL A 4 E 4 issues performance 9 2 J Julian dates 4 10 m Index 25 K key data invalid 5 3 key fields 3 5 KEY IS phrase 3 5 L large tables creating 1 15 libraries shared Acu4GL for DB2 F 9 Acu4GL for Informix A 6 Acu4GL for Oracle C 13 Acu4GL for Sybase E 10 limitations WHERE constraint 9 11 limits and ranges DB2 F 28 Informix A 21 ODBC D 36 Oracle C 29 SQL Server B 38 linking Acu4GL for DB2 F 7 linking Acu4GL for Oracle C 8 linking runtime Acu4GL for DB2 F 8 Acu4GL for Informix A 5 Acu4GL for Oracle C 12 Acu4GL for Sybase E 9 locating XFD files 8 18 location of XFDs 3 7 locking record C 4 F 4 DB2 F 3 ODBC D 35 Oracle C 3 locking table Index 26 m ODBC D 35 SQL Server B 28 Sybase E 43 login configured Oracle C 16 long field names 3 8 lowercase letters in filenames A 8 B 10 D 17 E 24 F 13 LOW VALUES illegal COBOL data 5 2 M makefiles Informix A 4 Oracle C 11 Sybase E 6 managing drivers ODBC D 6 map files creating Acu4GL for DB2 F 17 Acu4GL for ODBC D 22 mapping COBOL data to ODBC data D 39 COBOL records to a database 1 12 columns and records 1 11 3 3 DB2 data to COBOL F 29 DB2 data types F 29 ODBC data to COBOL D 40 ODBC data types D 38
245. ernate directory with the Fo compiler option Then at run time make sure you have the configuration variable XFD_PREFIX set to include that same directory See Chapter 8 Compiler and Runtime Options for information on the Fo option and the XFD_PREFIX configuration variable Why aren t my KEYs being retrieved in the correct order If your KEY field is numeric or alphanumeric you may have illegal data in the field For example if you ve used LOW VALUES or HIGH VALUES to mark control records those values are considered invalid and can cause the records containing them to be retrieved in an unexpected sequence To enable special values such as these to be processed use the BINARY directive in front of the key field This allows data of any classification to be processed Either designate an individual field as binary or specify USE GROUP BINARY in front of a group of fields The method of storing variables declared as binary is database specific For example for Informix databases these are stored as char fields with an extra leading character that always contains a space For Oracle databases to use another example variables declared as binary are stored as raw fields Refer to your database documentation for information specific to your data source or RDBMS Questions and Answers m 10 5 Question Is it possible to use the same XFD file for data files with different names if they all have the same
246. ero for any level means no error at that level For example runcbl le errfile x myprog where l causes the contents of the runtime configuration file to be included in the error output e or e causes the error output to be placed in the file named immediately after the option errfile is the user specified name of the error file X causes the secondary error numbers to be included myprog is the name of your object file Troubleshooting m 9 17 9 2 3 2 The text of the error would then have this format in the file x x File system error value 3 Dictionary xfd file not found File error 9D 03 on filename Dictionary xfd file not found Retrieving messages using the debugger Occasionally you may receive an error message that means syntax error In Informix for example this is error code 201 You can examine the error file and determine the cause of the problem if you receive this error code You ll need to rerun the program specifying the options shown below and turning on Trace Files TF when execution begins runcbl d1 rrfil x yourprog Notice that the only change from Method One is the d option which turns on the debugger The source code does not need to be compiled in debug mode After you press Enter you will be at the debugger screen Enter the following command tf on where n is anumber from to 9 The higher the number you enter the more debugging informatio
247. erted to underscores Field names longer than 18 characters will cause a warning to be issued if they are not unique within the first 18 characters Some databases Informix for example limit you to 18 total characters We recommend that for portability and for end user purposes you use the least number of characters You can use the NAME directive for this to avoid changing your procedure division code Fields in OCCURS clauses get special handling because the runtime system must assign a unique name to each data item So sequential index numbers are appended to the item named in the OCCURS Limits vary between databases so refer to the documentation that accompanied your RDBMS In some instances the name may be truncated by Acu4GL if necessary before the index is added Note detail p o number is not part of the table because the key overlays this area 6 6 m Working with COBOL This table is built in the database Column Name p_o_number p_o_dept_number p_o_record_type p_o_quantity_to_ship p_o_total_quantity notes_line_1 notes_line_2 notes_line_3 Type number 10 number 3 char 1 number 4 number 4 char 40 char 40 char 40 The actual database datatype may vary See the Limits and Ranges section found in the appendix of this manual that is specific to your RDBMS for a list of supported data types and their COBOL equivalents 6 1 2 Compiling With the WHEN Directive
248. es CUST001 and CUSTO0001 and CUST00001 does not match CUSTOMER OMER matches CUSTOMER does not match CUST001 or CUST0001 Note that XFD_MAP cannot be read from the ACCEPT FROM ENVIRONMENT statement XFD_MAP_RESETS This configuration variable determines whether setting the XFD_MAP adds to or replaces the existing value When this variable is set to 0 off false no setting the XFD_MAP adds new value patterns to the end of the existing value When it is set to 1 on true yes setting the XFD_MAP replaces the existing value with a new value The default value is 1 on true yes This variable may be useful if you need to include multiple XFD_MAP lines in a configuration file and want to avoid setting and resetting the variable When multiple lines exist all patterns are used in the order they are listed XFD_PREFIX When this variable is assigned a value it is used to locate the XFD file and the variable XFD_DIRECTORY is ignored This variable enables you to define a specific series of directories to search for XFD files rather than Runtime Configuration Variables m 8 19 indicating only one The runtime searches each directory in the order specified until an XFD file matching the name of the desired file is found and then assumes that is the correct file Therefore when using the XFD_PREFIX variable be aware that the runtime e Searches each named directory and not its subdirectories e Stops searc
249. es will be ODBC files unless otherwise specified by the second configuration variable which is filename_HOST filesystem where filename is the file name without any extension named in the ASSIGN TO clause of your SELECT statement This configuration variable is used to assign an individual data file to a different file system Any file so assigned will use the designated file system and not the one specified by DEFAULT_HOST For example myfile_HOST VISION means that my file will be under the Vision file system The ability to designate a different file system for certain files enables you to tailor your application to a specific customer s needs or to implement an incremental conversion for a customer With relational databases this is particularly useful in that it allows you to tune an application for processing speed and resource requirements You can use these runtime configuration file variables in combination to assign your new files in a default with exceptions manner for example this set of entries DEFAULT_HOST VISION afile_HOST ODBC bfile_HOST ODBC means that all new files except afile and bfile will be assigned to Vision and those two files will be assigned to ODBC You can also change the values of these variables during program execution by including in your code SET ENVIRONMENT filename_HOST TO filesystem or SET ENVIRONMENT DEFAULT_HOST TO filesystem D 16 m Acu4GL for ODBC Information Th
250. esrv Information on Oracle s Net Configuration Assistant can be found in your Oracle documentation Installation and Setup m C 9 C 2 2 UNIX Installation Steps The Acu4GL for Oracle product on UNIX is an add on module that must be linked with the ACUCOBOL GT runtime system For this reason you ll need a C compiler to install the Acu4GL product To interface you must use the ACUCOBOL GT compiler and runtime the version of the runtime must match the version of Acu4GL The Acu4GL product is shipped using either TAR or CPIO format depending on the type of machine you have The label on the medium shipped to you tells you which format has been used From your Acucorp directory choose where you want to install the Acu4GL product or create a new directory for it and then enter one of the following commands tar xfv device or cpio icvBd lt device This will copy the files from the distribution medium to your Acucorp directory structure device is the appropriate hardware device name for example dev rdiskette or dev rmt0 Sites using Texas Instruments System 1500 should add an uppercase T to the cpio options icvBdT Contents of the medium Note that each Acu4GL product has its own license file that must be located in the same directory as the ACUCOBOL GT runtime For Oracle the license file is distributed with the name runcbl olc C 2 3 Completing the Installation With appropriate install
251. ete from ftestdat where ftest2_key ft2_key grant execute on ftestdat_delete to public B 34 m Acu4GL for Microsoft SQL Server Information tablename_read tablename_read is used to read a random record READ not READ NEXT or READ PREVIOUS The parameters passed to the stored procedure are the values of the primary key in the order they are listed in the XFD The expected rowset is the columns in the first table if secondary tables are used or the columns of the table if secondary tables are not necessary This stored procedure is very similar to tablename_start tablename_update tablename_update is used to REWRITE a record from the file The parameters passed to the stored procedure are the values of all the columns in the row in the order of the columns in the database The timestamp column and identity column if present in the table are not passed to the stored procedure For example based on the sample XFD you might want to create the following stored procedure for rewriting a record create procedure ftestdat_update ft2_key char 4 ft2_keyl_segl char 2 ft2_keyl_seg2 char 2 ft2_altkey2 char 4 ft2_number char 9 ft2_info char 10 n ate ftestdat set test2_key ft2_key test2_keyl_segl ft2_keyl_segl test2_keyl_seg2 ft2_keyl_seg2 test2_altkey2 ft2_altkey2 test2_number ft2_number test2_info ft2_info here ftest2_key ft2_key BRED Bb eb Eben ee ee eee Q grant e
252. eturned by a SELECT statement sent to the server This variable can be used to speed up the Acu4GL product For example if you know you will be reading only one record at a time and reading from a unique key you can set A MSSQL_ROWCOUNT to 1 thus speeding up the processing If you know you are going to be reading records ten rows at a time set A_MSSQL_ROWCOUNT to 10 If you don t have any information about how many rows are going to be requested set this variable to 0 which is the default Note Setting this variable to a non optional value can actually degrade performance since the interface may be forced to issue more SELECT statements once the rowcount has been determined Use caution when setting this variable See also A_MSSQL_ADD_IDENTITY runtime configuration file variable A_MSSQL_SELECT_KEY_ONLY This variable directs the interface to select key columns only when searching for records Its use can improve READ performance on large tables with many rows When set to True on yes the default value A_MSSQL_SELECT_KEY_ONLY causes the interface to select only key columns when searching for records and then select the entire row of the single record that must be returned to the COBOL program This improves performance on large tables with many rows Configuration File Variables m B 25 Setting A_LMSSQL_SELECT_KEY_ONLY to False off no does not affect how the select is created
253. fferent owners can thus have tables of the same name However this is not true when you use Acu4GL for Sybase Acu4GL for Sybase works a little differently It automatically determines the owner name it will use to reference a table It is therefore essential that there not be multiple tables with the same name in a single database even though the tables have different owners If there are the Acu4GL for Sybase product will not necessarily find the correct one and no diagnostic will be issued Note that table names include dots as separators Because of this you must make sure there are no extensions on COBOL file names that will be converted to table names If you were to have a COBOL file named IDX1 DAT Acu4GL for Sybase would attempt to open a table DAT with owner IDX1 You can avoid this problem either by renaming your COBOL file in your source program or by using an ACUCOBOL GT runtime configuration file entry to map the file name to an allowable file name such as IDX1 DAT IDX1 Installation and Setup m E 3 If you map your file name to a new name we recommend that you simply drop the extension to form the new name Here s why The compiler uses the base file name without the extension to create the XFD file name IDX1 XFD The runtime needs to be able to locate this file But if you ve mapped the file name to something completely different such as MYFILE the runtime will look for an XFD
254. fficient environment for Acu4GL because once they are executed on the server they do not need to be parsed and optimized each time they are executed If the server goes down however the stored procedure is parsed and optimized again the first time the procedure is called after the database restarts If you run a set of stored procedures for the database in which data is manipulated your production database this database must be the setting for A_SYB_LOCK_DB If you run the stored procedures against both the lock database and the production database the lock database can be the setting for A_SYB_LOCK_DB Note that if you run one version of stored procedures against the lock database and another version against the production database the stored procedures in the lock database override those in the production database Therefore we recommend that you always update your stored procedures with each new installation of Acu4GL so that these procedures are consistent when you run them against the tables in your database This section discusses two types of stored procedures e Procedures that you may want to add to Acu4GL for Sybase e Procedures provided in Acu4GL for Sybase that you as the developer or administrator may find useful E 46 m Acu4GL for Sybase Information Note If you are upgrading from an earlier version of Acu4GL be sure to install the new stored procedures We always upgrade stored procedures in such a way that
255. field 1 pic xx Troubleshooting m 9 13 Directive word too long keyname With one exception the words contained in a directive including field names cannot exceed 30 characters The value of a WHEN directive may consist of up to 50 characters GROUP expected after USE The USE GROUP directive must include both words Missing in XFD directive The NAME directive requires an equal sign The WHEN directive requires a comparison operator Missing field name after WHEN A valid field name or the word OTHER must be specified with the WHEN directive xxx unknown XFD directive The compiler did not recognize the directive you used The xxx is the directive found Check for a typographical error Value should be a name xxx 669 This error occurs when the item to the right of an should be a name and it isn t For example it would be an error to use a quoted string with the NAME directive XFD NAME some text The xxx in the message is the value found Value should be numeric xxx 669 This error occurs when the item to the right of an should be numeric and itisn t The xxx in the message is the value found Value should be a literal xxx 669 This error occurs when the item to the right of an should be a literal and itisn t The xxx in the message is the value found A literal is either a quoted string or a numeric integer 9 14 m Performance and Troubleshooting
256. file named MY FILE XFD So you d have to remember to change the name of IDX1 XFD to MYFILE XFD in the XFD directory Save yourself this extra step by simply dropping the extension when you map the name Security Security is implemented in the Sybase RDBMS A user is required to log in to the RDBMS before any file processing can occur Acu4GL for Sybase provides both a default and a user configurable method for implementing this Generally it is best for someone with Database Administrator DBA privileges to create and drop the tables allowing others only the permissions to add change or delete information contained in them See the Sybase documentation for more details on DBA privileges Alternate REWRITE method If the above stored procedure is not available then the update query passed to the database has been optimized to update only dirty columns This should improve performance E 2 Installation and Setup The following sections describe several steps that must be performed before you begin using Acu4GL for Sybase on a new system e Acu4GL for Sybase Installation e Setting Up a User Account e Setting Up the User Environment Designating the Host File System E 4 m Acu4GL for Sybase Information E 2 1 Sybase RDBMS Installation The Sybase RDBMS must be installed and configured prior to the installation of Acu4GL for Sybase Acu4GL can interface to Sybase version 11 0 and later Sybase s isql
257. for more details on DBA privileges and public synonyms Note By default Acu4GL for Oracle always checks to see if a public synonym is available for a file at open time regardless of what the USER_PATH is set to If the name of a table owned by a current user is the same as a public synonym the user owned table is chosen Installation and Setup m C 7 C 2 Installation and Setup The following topics list the steps you must perform before you begin using Acu4GL for Oracle The following sections describe the steps you must take before you begin using Acu4GL for Oracle on a new system Windows Installation Steps UNIX Installation Steps Completing the Installation Checking System Parameters Setting Up a User Account Setting Up the User Environment Designating the Host File System Setting Up the Search Path Handling Transactions C 2 1 Windows Installation Steps Installation of the product The Oracle RDBMS version 9i or later must be installed and configured prior to the installation of Acu4GL for Oracle Consult the Oracle documentation if you have any questions regarding this step This section details installation instructions for Acu4GL for Oracle on your Windows machine UNIX installation instructions can be found in section C 2 2 UNIX Installation Steps of this appendix C 8 m Acu4GL for Oracle Information CD ROM installation Instructions for installing your Acu4GL product from CD ROM are contai
258. for the different products SELECT FROM warehouse_items WHERE aisle 17 and shelf 8 and bin 2 ORDER BY aisle ASC shelf ASC bin ASC This query achieves the desired result but has one problem For the COBOL program to end its processing it must read a record that has a new value for bin The COBOL application has no way of specifying an upper boundary for the read operation so when all rows of data from bin 2 have been read Acu4GL will attempt to read the next record by generating the following query SELECT FROM warehouse_items WHERE aisle 17 and shelf 8 and bin gt 2 ORDER BY aisle ASC shelf ASC bin ASC Performance Issues m 9 9 This query will cause the database query optimizer to gather all records pertaining to items on the remainder of shelf 8 to build its working set This is excessive from the COBOL application s point of view because the COBOL program needs only the first record of the working set to determine that it has finished processing This problem can be even more serious if the application is processing the last bin on a shelf Because there are no more bins on that shelf the query would drop down a level and generate the following SELECT FROM warehouse_items WHERE aisle 17 and shelf gt 8 ORDER BY aisle ASC shelf ASC bin ASC This would select all items on the remainder of that aisle of the warehouse which could be a very large working set if each aisle had 130 shelves
259. for variable xxx An elementary data item in your FD was larger than 255 bytes or there is no ODBC type that matches the current data type 9D 14More than one table with the same name When tables were listed more than one table was found with the same name Consider whether or not setting the USER_PATH configuration variable will resolve the issue This variable will enable tables with identical names but with different ownership located in a different schema to be found and accessed 9D 15ODBC driver missing needed types The driver doesn t support the data types needed for Acu4GL for ODBC D 11 2 Native SQL Errors You may encounter the following native SQL errors when using Acu4GL for ODBC These errors are generated by your data source so the exact wording and error number will vary 9D Too many BLOBs binary large objects Some databases have restrictions on how many BLOBs can be placed into a single table To work around this restriction specify the configuration variable A_ODBC_USE_CHAR_FOR_BINARY This allows you to encode binary data in hexadecimal and write it out as CHAR data instead of BINARY 9D Invalid Column Name OR Reserved Word You probably specified a column name using a word that has been reserved for your data source Locate the column by comparing a file trace of the CREATE TABLE to your data source s list of reserved words Apply the NAME directive to the field in the FD that is associated
260. formix A 22 m Index 43 Acu4GL for Oracle C 30 Acu4GL for SQL Server B 39 Acu4GL for Sybase E 53 compile errors 9 12 compile warnings 9 14 data searches 9 5 database interaction with COBOL 9 6 file input and output 9 3 guidelines 9 2 Informix A 18 ODBC D 42 overview 9 2 planning ahead 9 7 restructuring data 9 5 runtime errors Acu4GL for DB2 F 31 Acu4GL for Informix A 23 Acu4GL for ODBC D 42 Acu4GL for Oracle C 30 Acu4GL for SQL Server B 39 Acu4GL for Sybase E 54 SQL errors ODBC D 44 tables and multiple indexes 9 4 transactions 9 4 Vision files 9 5 truncated field names 3 8 types data DB2 F 29 ODBC D 38 U underscores in filenames A 8 B 10 C 21 D 17 E 24 F 13 unsupported data types Informix A 21 Index 44 m UPDATECOLUMN DB2 F 21 ODBC D 26 upgrading databases 9 6 upgrading stored procedures Acu4GL for Sybase E 13 E 17 E 20 SQL Server B 7 B 31 uppercase letters in filenames C 21 USAGE DISPLAY numbers illegal COBOL data 5 2 USE GROUP directive 3 3 4 6 4 18 user accounts setting up Acu4GL for Oracle C 15 Acu4GL for SQL Server B 7 Acu4GL for Sybase E 21 user environment setting up Acu4GL for DB2 F 10 Acu4GL for ODBC D 14 Acu4GL for Oracle C 16 Acu4GL for SQL Server B 7 Acu4GL for Sybase E 21 USER_PATH configuration variable C 26 D 33 F 26 using Oracle database table C 28 using SQL Server database table B 28 using sql acu 2 3 utilities acu4glfd 6 10 cblutil
261. function determines which file system to pass the request to but does not change the name of the file Acu4GL for ODBC translates the name to lowercase letters and changes hyphens to underscores unless the configuration variable 4GL_COLUMN_CASE is set See section D 6 for information on this variable This new name is the one that Acu4GL for ODBC will use in the future for references to database tables D 18 m Acu4GL for ODBC Information D 4 Decimal Points Acu4GL for ODBC reads the decimal point character from the environment variable DECIMAL POINT If DECIMAL_POINT is set Acu4GL uses that character If the variable is not set Acu4GL uses the decimal character that is encoded in the XFD file The two most common decimal indicators are the period and the comma ee 99 7 characters The comma is used often in European code and is often indicated in COBOL programs by the DECIMAL POINT IS COMMA clause D 5 Configuration File Variables This section lists the runtime configuration file variables that are specific to Acu4GL for ODBC Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are discussed in section 8 2 Runtime Configuration Variables A_ODBC_ALTERNATE_COMMIT_LOGIC A_ODBC_USE_SQLTABLES AGL_MAX_DATE It is possible that invalid dates can be incorrectly written to the database Invalid dates are written as NULL but if the date is in the key p
262. gh the current user has created the table it will not be found and a file error 35 will result This circumstance can occur if the file was created with the OPEN OUTPUT phrase and is not an element in USER_PATH When the table is created the current user will be the owner of that table When the runtime attempts to open the table the runtime will not look for tables owned by the current user unless USER_PATH is not set or is part of the USER_PATH setting If an OPEN INPUT or OPEN I O is issued and no USER_PATH variable is in the runtime configuration file Acu4GL searches for a user of the named file in the following sequence of places 1 The user named for login ORA_LOGIN or OPS username 2 Public synonyms Acu4GL opens the first file that has a valid combination of user and file name If an OPEN OUTPUT is issued whether USER_PATH is present or not a new table is created with the owner being 1 The name specified in ORA_LOGIN 2 The name constructed by automatic login see section C 2 5 Setting Up a User Account See also Chapter 2 in the ACUCOBOL GT User s Guide contains a discussion of the FILE_PREFIX configuration variable and general guidelines on the use of file search paths Section C 2 8 Setting Up the Search Path C 28 m Acu4GL for Oracle Information C 6 Using the Database Table The database table is built and accessed automatically when the COBOL application is
263. gram 6 2 procedures COBOL 9 10 SQL Server B 31 stored B 30 Sybase E 46 programs and sql acu 2 4 COBOL preparing and compiling 6 2 demonstration 2 6 inf_ inst A 4 sample Informix A 7 Q Query Analyzer B 4 R RDBMS relational database management system 1 2 record definitions 3 5 record locking m Index 33 Acu4GL C 4 F 4 Acu4GL for DB2 F 3 F 28 Acu4GL for ODBC D 35 Acu4GL for Oracle C 3 Acu4GL for Sybase E 43 COMMIT_COUNT 0 8 6 C 4 F 4 COMMIT_COUNT 1 8 7 C 5 F 5 COMMIT_COUNT n 8 6 C 4 F 5 Record menu demonstration program 2 9 records forming COBOL 1 13 mapping 1 11 3 3 REDEFINES definition 3 5 4 20 4 23 relational database management system RDBMS 1 2 requests passing I O to interface 1 13 requirements ODBC driver D 36 restrictions ODBC D 3 restructuring data 9 5 retrieving errors for Informix 9 19 REWRITE method Sybase E 3 routines interface 1 7 running sql acu from a program 2 4 from the command line 2 3 running the demonstration program 2 8 runtime Acu4GL for Informix A 4 Acu4GL for Oracle C 10 Acu4GL for Sybase E 6 linking Acu4GL for DB2 F 8 linking Acu4GL for Informix A 5 linking Acu4GL for Oracle C 12 linking Acu4GL for Sybase E 9 runtime configuration variables 8 4 Index 34 m runtime errors Acu4GL for DB2 F 31 Acu4GL for Informix A 23 Acu4GL for ODBC D 42 Acu4GL for Oracle C 30 Acu4GL for SQL Server B 39 Acu4GL for Sybase E 54 retrieving 9 16 runtime module ACUCOBOL G
264. guration file variable which is discussed in detail in section C 4 Acu4GL for Oracle Configuration File Variables For direct control over the transaction logging facility in Oracle use the transaction management features available with ACUCOBOL GT compiler See Chapter 5 in Book 1 User s Guide of the ACUCOBOL GT compiler documentation Note You are now ready to use the sql acu program Go to section 2 4 Using the sql acu Program to learn about using this Micro Focus provided utility After you learn about and use this utility you are ready to find out about preparing and compiling your COBOL program followed by learning to use the demonstration program All of this information can also be found in Chapter 2 Getting Started C 20 m Acu4GL for Oracle Information C 3 Oracle s Instant Client Instant Client a free download from Oracle allows you to run your applications without installing the standard Oracle client or having an ORACLE_HOME Note Setting up Oracle Instant Client can be challenging and should be performed only by advanced users To use Oracle s Instant Client with Acu4GL for Oracle download the Basic Lite and SQL Plus packages from Oracle Follow Oracle s instructions to install and configure the products and test their connection using SQL Plus before proceeding to work with Acu4GL Once you have completed this process test the installation We recomme
265. h time the COBOL application creates a new file it needs to know which file system to use You provide the name of the file system with one of two runtime configuration file variables The first is DEFAULT_HOST filesystem This will designate the file system to be used for newly created files that are not individually assigned For example DEFAULT_HOST DB2 means that all new files will be DB2 files unless otherwise specified by the second configuration variable which is filename_HOST filesystem where filename is the file name without any extension named in the ASSIGN TO clause of your SELECT statement This configuration variable is used to assign an individual data file to a different file system Any file so F 12 m Acu4GL for DB2 Information assigned will use the designated file system and not the one specified by DEFAULT_HOST For example myfile_HOST VISION means that my file will be under the Vision file system The ability to designate a different file system for certain files enables you to tailor your application to a specific customer s needs or to implement an incremental conversion for a customer With relational databases this is particularly useful in that it allows you to tune an application for processing speed and resource requirements You can use these runtime configuration file variables in combination to assign your new files in a default with exceptions manner for example this set of ent
266. h of the conflicting fields 3 2 5 Long Field Names To meet the SQL requirements of some RDBMSs the Acu4GL runtime for those systems truncates long field names to the maximum allowed by the RDBMS In the case of the OCCURS clause described above the truncation is to the original name not the appended index numbers However the final XFD Files m 3 9 name including the index number is limited to the RDBMS maximum It s a good idea to make sure that your field names are unique and meaningful within the first 18 characters The database you are connecting to may allow longer names and if so more characters will be used Names longer than 30 characters will generate a warning Instead of allowing default truncation you can use the WHEN directive to give a shorter alias to a field with a long name Note that within the COBOL application you can continue to use the original name The NAME directive affects only the data dictionary connection to the RDBMS table 3 2 6 Naming the XFD File The compiler needs to give a name to each XFD file data dictionary that is built It attempts to build the name from your COBOL code although there are some instances where the name in the code is nonspecific and you must provide a name Each XFD name is built from a starting name that is derived if possible from the SELECT statement in your COBOL code The following paragraphs explain how that occurs ASSIGN name is a variable If
267. hat perform work in small operation based logical units benefit greatly from Oracle s transaction management systems Applications that are not written for transaction management encounter difficulty with record locking when operating against a system that enforces transaction management The difficulty can occur with an application that is performing more than one logical task at a time Any operation that modifies or reads data in an I O mode without the WITH NO LOCK phrase causes a lock to be placed in the database system As a result the application may have many more record locks present than would be expected by the normal rule of COBOL file locking The application would act similarly as to when the LOCKS ON MULTIPLE RECORDS clause in COBOL is used This can best be illustrated by an example 1 The user is entering a customer s order 2 As each line item is entered into the order the inventory file is modified to reflect that items have been removed from the stock on hand C 4 m Acu4GL for Oracle Information 3 The user must switch to a different part of the application to perform a different task perhaps as a result of a phone call from a new customer 4 All of the records that were locked or modified by the application before the switch remain locked because the first order is not complete No COMMIT or ROLLBACK has been issued to complete the transaction All of the records locked by the transaction remain loc
268. hat myfile will be under the Vision file system You can use these configuration file variables in combination to assign your new files in a default with exceptions manner for example this set of entries DEFAULT_HOST ORACLE afile_HOST VISION bfile_HOST VISION C 18 m Acu4GL for Oracle Information means that all new files except afile and bfile will be assigned to Oracle and those two files will be assigned to Vision You can change the values of these variables during program execution by including in your code SET ENVIRONMENT filename_HOST TO filesystem or SET ENVIRONMENT DEFAULT_HOST TO filesystem This enables you to change file systems during the execution of your program This is not the typical way to specify a file system normally it is designated in the runtime configuration file and is not changed in the COBOL program Note Acu4GL for Oracle allows you to create a table with an OPEN OUTPUT statement just as you can create Vision indexed files The Oracle equivalent of a Vision file is a table not a database You must create a database for your Oracle tables before you run the COBOL program that creates the tables just as you must create a directory for your files before you run a COBOL program that creates Vision files C 2 8 Setting Up the Search Path If you own a file because you created it with OPEN OUTPUT from COBOL or because you created it using SQL you do not need to do anything more to
269. he data sources currently configured for your system If the ODBC icon is not in your control panel ODBC is probably not installed on your system To install ODBC on your system you have two options e Buy an ODBC driver from a driver or database vendor and install it ODBC is installed automatically e Buy and install a Windows based ODBC data source The ODBC driver and ODBC will be one of the install options D 12 m Acu4GL for ODBC Information D 2 2 Installation of Acu4GL for ODBC The Acu4GL product for ODBC is an add on module The ODBC Acu4GL product installation includes a DLL file that is detected at run time The Acu4GL product for ODBC can be executed only on a machine that is running a 32 bit Windows platform or a 64 bit Windows platform with a 32 bit runtime and 32 bit drivers Note that 32 bit drivers may be able to access a 64 bit database Consult your driver vendor to be sure CD ROM installation Instructions for installing your Acu4GL product from the ACUCOBOL GT Development Suite CD ROM are contained on the CD booklet that accompanied the product Please refer to it for installing the ACUCOBOL GT Development Suite which includes Acu4GL Once the installation is complete please refer to this appendix for setting up your Acu4GL product Be sure to set up your data source in the Windows control panel as instructed in section D 2 3 Setting Up Data Sources and then enter the data source name in the co
270. he first time it attempts to execute a READ NEXT after a COMMIT or ROLLBACK This means that the 4GL_COMMIT_COUNT configuration variable should be set to 1 so that no COMMITs are issued by Acu4GL for DB2 See 4GL_COMMIT_COUNT in Chapter 8 for additional information e A_DB2_STRICT_EQUAL is most useful with alternate keys that allow duplicates Note This same behavior can be accomplished with the 4GL_WHERE_CONSTRAINT but using A_DB2_STRICT_EQUAL requires less programming While the default value is False off no 0 this configuration variable can also take the value True on yes 1 F 24 m Acu4GL for DB2 Information A_DB2_TABLE_TYPES This variable is used to specify a table type TABLE VIEW and so forth that should be looked for when selecting a database table Using A_DB2_TABLE_TYPES with other variables such as USER_PATH and A_DB2_CATALOG can speed up the finding of tables in large databases This information will be passed to the API function call SQLTables as the TableType parameter Please refer to your driver s documentation for supported types Example A_DB2_TABLE_ TYPES TABLE VIEW See also USER_PATH configuration variable A_DB2_ALTERNATE_COMMIT_LOGIC configuration variable A_DB2_USE_CATALOG Not all data sources will support a catalog or the data sources may return a catalog name that is not useful The default behavior of the runtime is to not use the catalog
271. hing once a matching file name is found even if other files of the same name are located in a different directory later in the series e Does not validate that the file specifications such as key or record size parameters of the XFD file match those in the COBOL program Be sure the correct file you want to use is in the path specified You can specify a directory path that contains embedded spaces if you surround the path with quotation marks You separate entries using a semi colon For example XFD_PREFIX C Sales Data C Customers You can specify up to 4096 characters for this variable Note The default for XFD_PREFIX is empty If this variable is set to any other value the configuration variable XFD_DIRECTORY in which you specify only one directory is ignored See also XFD_DIRECTORY runtime configuration variable Sections 5 2 1 and 5 2 2 in the ACUCOBOL GT User s Guide for more information about client enabled runtimes and remote notation 8 20 m Compiler and Runtime Options Performance and Troubleshooting Key Topics Performance Issues os cioc iio sesi pets pecsecanse ode penee ieee leteves tebe catdeeseesaseteeies 9 2 Troubleshooting c o00 5 b ee stink ciation nthe 9 11 Compiler Brrr s 60 0 2stsscnies peo an teeter 9 12 Compiler Warnings 0 ccsseesesesseeeceeceseseeeeeseeneesescenecaeeeceaesaeseses 9 14 Retrieving Runtime Errors 0 0 0 0 ecesesessesecseceeeseeseceeeec
272. iable A_ODBC_TABLE_TYPES configuration variable Configuration File Variables m D 21 A_ODBC_COMMIT_ON_BEGIN ODBC has no START TRANSACTION method Everything since the last COMMIT or ROLLBACK is considered part of the current transaction To ensure that the previous transaction has been ended before a new one begins set ALODBC_COMMIT_ON_BEGIN to a nonzero value This causes each COBOL START TRANSACTION to first issue a COMMIT to all applicable ODBC drivers in use This ensures that the previous transaction has been ended before the new one starts If this variable is not set or is set to 0 a COBOL ROLLBACK may affect file I O that occurred before the most recent COBOL START TRANSACTION While the default value is 0 off false no this configuration variable can also take values of On true yes A_ODBC_DATASOURCE Set ALODBC_DATASOURCE to the exact name of the data source that you established in the Windows ODBC driver manager You can set this variable in your COBOL configuration file if you will be using only one data source For example if the data source you want to select is listed in the Windows ODBC driver manager window as MS Access Databases Access Data mdb you should add the following line to your configuration file A_ODBC_DATASOURCE MS Access Databases If you do not know the data source name in advance or if you intend to use more than one data source you may set the data sou
273. icrosoft SQL Server may not run properly without the corresponding stored procedures It can be difficult to maintain multiple copies of stored procedures therefore we recommend that you continue to create the stored procedures in the master database If your installation does not permit this you do have the flexibility to create the stored procedures elsewhere However to facilitate maintenance of the stored procedures we recommend that you create as few databases as possible Installation steps for a Windows client Installation instructions for Microsoft SQL Server are provided by Microsoft and need to be read and understood to install the Windows client Be sure to choose your communication method at the client machine To do this follow the instructions provided with your SQL Server software B 2 2 Setting Up a User Account Acu4GL for Microsoft SQL Server must be able to connect to a user account You may either set up one general account for all users or an account for each individual user To set up an account you must have DBA privileges See sp_addlogin and sp_adduser in the Microsoft SQL Server Commands Reference Manual for additional information on setting up user accounts B 2 3 Setting Up the User Environment The user s account should have been set up correctly to access the Microsoft SQL Server RDBMS system This includes environment variables such as DSQUERY See your Microsoft SQL Server documentation for more
274. ient software version 6 01 or higher on the client machine The bin directory of your DB2 client software must be in your PATH CD ROM installation Instructions for installing your Acu4GL product from the ACUCOBOL GT Development Suite CD ROM are contained on the Quick Start card that accompanied the product Please refer to it for installing the ACUCOBOL GT Development Suite which includes Acu4GL Once the installation is complete please refer to this appendix for setting up your Acu4GL product Installation and Setup m F 7 Relinking for Windows users Relinking is not required for Windows users but it is required for UNIX users and is explained in the next section Acu4GL for DB2 is a windows DLL a4db232 dll that is loaded at run time from the bin directory of your ACUCOBOL GT product distribution F 2 2 UNIX Installation Steps The Acu4GL for DB2 product on UNIX is an add on module that must be linked with the ACUCOBOL GT runtime system For this reason you ll need a C compiler to install the Acu4GL product To interface you must use the ACUCOBOL GT compiler and runtime and the version of the runtime must match the version of Acu4GL The Acu4GL product is shipped using either TAR or CPIO format depending on the type of machine you have The label on the medium shipped to you tells you which format has been used From your Acucorp directory choose where you want to install the Acu4GL p
275. ilename before it is used as a table name e When set to negative values nothing is done differently e When set to a positive value the number determines how much directory information to keep For example given the file home data1 gl master dat the following values result in the given table name 4GL USEDIR LEVEL Final resolved name 0 master dat 1 glmaster dat 2 data glmaster dat 3 or largerhomedata 1 glmaster dat This variable has an upper limit of 127 characters and is currently available with the following Acu4GL interfaces MSSQL and Sybase Any special instructions will be included in the section describing support Runtime Configuration Variables m 8 13 See Also The 4GL_DB_MAP variable which enables you to set one map at a time 4GL_USEDIR_LEVEL interacts with 4GL_DB_MAP in the following way 1 4GL_DB_MAP is tested first to determine which database to search for the table 2 Then 4GL_USEDIR_LEVEL is used to change the final name of the table AGL_WHERE_CONSTRAINT 4GL_WHERE_CONSTRAINT allows you to override any value given in the external variable A4GL WHERE CONSTRAINT This configuration variable can have a value with any length limited only by machine memory If a value is set in 4GL_WHERE_CONSTRAINT any value in the external variable is ignored See section 9 1 2 The WHERE Constraint for information on the external variable DEFAULT_HOST If you are opening an existing file most fi
276. iles conflicts with the COBOL description of the file FD The xx indicates a tertiary error code that is defined by the host file system You can determine the exact nature of the mismatch by referring to the host system s error values The tertiary error code may have any of these values 01 mismatch found but exact cause unknown this status is returned by the host file system 02 mismatch found in file s maximum record size Runtime Errors m E 55 03 mismatch found in file s minimum record size 04 mismatch found in the number of keys in the file 05 mismatch found in primary key description 06 mismatch found in first alternate key description 07 mismatch found in second alternate key description The list continues in this manner for each alternate key 9D 11 ACUCOBOL GT stored procedures not found or ACUCOBOL GT lock table missing The installation of Acu4GL for Sybase creates a number of stored procedures and tables At least one of these was not found 9D 12 A column of a key is of data type TEXT or IMAGE which is illegal Columns that are part of an index may not be of type TEXT or type IMAGE Check your key definition 9D 13 Internal error Multiple records were found with the same index this is a Sybase error 9D 14 DB library function returned an unexpected errordbinit Sybase failed An error message from Sybase is displayed on the terminal 9D 16 Trying to rename a table acr
277. in Installation and Setup m E 7 This database will eventually be located on your server machine Enter a valid database name Invalid names are master model temp or sybsystemprocs Names must start with a letter or underscore must contain only letters digits and underscores and may be up to 30 characters long Any other entry will be modified Next you will see the following message Saving any old version of syb_inst sql Old versions of syb_inst sql are saved to syb_instnnn sql where nnn starts at 001 and goes to 999 Ifa file syb_inst sql exists you see Saving syb_inst sql as syb_instnnn sql for some value of nnn Then you see Creating syb_inst sql This uses the file syb_inst in as a template and creates syb_inst sql using the database name you entered above You also see Creating cbhlconfig syb This is a sample file of configuration variables you may want to add to your cblconfig file You then see the following message In order to use the Acu4GL for Sybase interface you need to relink the runtime system We are assuming that the Makefile that came with your runtime system still has the FSI_SUBS and FSI_LIBS lines in it and will base our changes on that Makefile However we will create a new file called Makefile syb that has these changes in it Do you want to set up the Makefile for this system Type y or Y to continue You then see the f
278. ine to use You do this by setting the environment variable SQLEXEC as shown here Informix OnLine SQLEXEC S INFORMIXDIR lib sgqlturbo Informix SE SQLEXEC INFORMIXDIR lib sqlexec Setting SQLEXEC tells the Informix utility programs and the ACUCOBOL GT runtime which engine to access This variable must be set before you execute the runtime Only one engine either OnLine or SE can be used for any given execution of the runtime INFORMIXDIR is an environment variable that you must set to the location of your Informix product Common Questions and Answers m A 27 Question What files do I need to link my C routines into Acu4GL Answer From your ACUCOBOL GT runtime medium you need Question sub c sub85 c filetbl c config85 c sub h libruncbl a libvision a libacuterm a clntstub o If you are using AcuServer instead of linking clntstub o see the relinking instructions in your AcuServer User s Guide From your Acu4GL medium you need all of the following that are present infemb7 o for version 7 2 infemb73 o for version 7 3 infemb oo for version 5 1 inf o cur o libsql a libgen a libos a libasf a netlib a These files are provided by Informix and should be located in the appropriate Informix directory Instructions for linking are given in section A 1 2 Installation Steps I could not find the secondary error number for a 9D in the doc
279. ing is a description of the desired date format composed of characters from the following list M Month 01 12 Y Year two or four digits D Day of month 01 31 J Julian day 00000000 99999999 E Day of year 001 366 H Hour 00 23 N Minute S Second T Hundredths of a second Any other characters cause the date format string to be invalid and result in a corrupt XFD error or a compile time warning 4 10 m Using Directives Each character in a date format string can be considered a place holder that represents the type of information stored at that location The characters also determine how many digits will be used for each type of data For example although you would typically represent the month with two digits if you specify MMM as part of your date format the resulting date will use three digits for the month left zero filling the value If the month is given as M the resulting date will use a single digit and will truncate on the left Julian dates Because the definition of Julian day varies the DATE directive offers a great deal of flexibility for representing Julian dates Many source books define the Julian day as the day of the year with January 1 being 001 January ge being 002 and so forth If you want to use this definition for Julian day simply use EEE day of year in your date formats Other reference books define the Julian day as the number of days since some specific base date in the
280. ingle tier environment ACUCOBOL GT Domain ACUCOBOL GT application program Generic file system interface Acu4GL for ODBC ODBC API cals _ y ODBC Domain gt ODBC driver COBOL manager indexed files xK DBC driver calls ODBC driver feommands O Data Source Local database files Acu4Gl for ODBC in a single tier environment ODBC Concepts m D 9 The following diagram shows how Acu4GL fits into a multiple tier environment ACUCOBOL GT Domain ACUCOBOL GT application program Generic file system interface Acu4GL for ODBC ODBC API dale Be ODBC Domain ODBC driver COBOL 0 manager indexed files Ky ODBC driver calls ODBC driver t Database interface calls Proprietary database communication interface Database engine commands Networking software Data Source Ec Back end DBMS engine Databases Acu4GL for ODBC in a multi tier environment D 10 m Acu4GL for ODBC Information D 2 Acu4GL for ODBC Installation and Setup The following sections describe the steps you must perform before you begin using Acu4GL for ODBC on a new system e ODBC Installation e Installation of Acu4GL for ODBC e Setting Up Data Sources e Setting Up the User Environment e Designating the Host File System e Designating the Host Data Source D 2 1 ODBC Installation ODBC must be installed and configured before you install Acu4GL for ODBC
281. ins it Be sure to check your permissions I keep receiving an error message saying that my login is invalid But m sure I m using the correct username and password All usernames passwords and database names are case sensitive Be sure that you are typing the names exactly as they are set up Common Questions and Answers m B 43 Question Are there any ACUCOBOL GT library routines that do not work with or would not make sense to use with Acu4GL for Microsoft SQL Server Answer Yes There are two ACUCOBOL GT library routines that either don t work with or do not make sense to use with Acu4GL for Microsoft SQL Server C COPY and CSRECOVER B 44 m Acu4GL for Microsoft SQL Server Information Acu4GL for Oracle Information Key Topics Oracle Concepts Overview csssceseesecseeeceecsseceseeceeeneeseeseenecseeaees C 2 Installation and Setup 0 cece csecseeseeseceececeresseceseceeeseeseeseenecneeaees C 7 Oracle s Instant Ghent sssini eieiei reesei C 20 Filename Translation 2 000 000 seeeeceeecsseseeseesecsecosesceaeceseeceeeneeseeseenee C 21 Configuration File Variables 0 ccsesessecsseeeeseeseeeseeceeeeeeeeeeene C 21 Using the Database Table eeseseeeeesecseceeeseaeceseeceeeneeeeteenee C 28 Supported Features eesesesesecsseseeseesecseceeescsaecaseeceenaeeeeerenes C 28 imnits atid RAMOS E T C 29 Runtime Errors ene OS ee A kas C 30 Common Questions and Answers
282. installation instructions in your Sybase documentation Sybase s isql product which is an interactive query tool is also necessary for installing the ACUCOBOL GT stored procedures The Acu4GL product does not need isql after installation but it s a tool that can give you quite a bit of flexibility It allows you to do database work outside of COBOL including interactive queries table creation table modification and creation of views constraints and relationships between tables Micro Focus does not provide these products Installation and Setup m E 15 Step 2 Copy files 99 66 Copy syb_inst syb_cfg in and syb_inst in to your UNIX server machine Step 3 Create stored procedures The file syb_inst is an interactive shell script that generates the SQL script used to install ACUCOBOL GT stored procedures Execute the shell script syb_inst by entering the following command on your server machine sh syb_inst Note You may exit the script at any time by pressing the system interrupt key usually CTRL C If you entered only syb_inst instead of the full command this message may appear VAL 0 command not found VAL Undefined variable This can be fixed by entering sh syb_inst When the script begins executing you will see the following message During the execution of this script we will create an SQL script which you will need to execute from isql using a command
283. installation does not permit this you do have the flexibility to create the stored procedures elsewhere However to facilitate maintenance of the stored procedures we recommend that you create as few databases as possible The following sections describe the next steps you must take before using Acu4GL for Sybase for the first time e Setting Up a User Account e Setting Up the User Environment Designating the Host File System e Using the sql acu Program e Preparing and Compiling Your COBOL Program The Demonstration Program E 14 m Acu4GL for Sybase Information E 2 4 Windows Client and UNIX or Windows NT Server E 2 4 Installations First you must install the files from the installation media onto the client machine Then follow the instructions below for the appropriate server machine Finally some setup steps on the client machine complete the installation Instructions for installing your Acu4GL product from the ACUCOBOL GT CD ROM are contained on the Quick Start CD booklet that accompanied the product Please refer to it for installing your products Once the installation is complete please refer to this appendix for setting up your Acu4GL product UNIX Server Machine Installations To install the Acu4GL for Sybase on a UNIX server machine Step 1 Install Sybase The Sybase RDBMS version 11 0 or later must be installed and configured before you install Acu4GL for Sybase Follow the Sybase
284. instruct Acu4GL to re execute an INSERT statement that could not execute because a row in the AcuOpenTables table was locked or to return an error if the user chooses not to run the query again The default for A_MSSQL_DEADLOCK_LOOPS is 0 which causes the interface to return an error 9D 1205 indicating that a table is locked Set ALMSSQL_DEADLOCK_LOOPS to a positive numeric value to cause Acu4GL for SQL Server to re execute by the number specified by the query that tried to open the table and thus caused the deadlock Note that it can be as long as 10 seconds until SQL Server detects the deadlock and the application appears to hang while the repeated attempts to re execute the query are in progress Set AMSSQL_DEADLOCK_LOOPS to 1 or MESSAGE to cause Acu4GL for SQL Server to display a message box containing the text of the SQL Server error message and the option to rerun the query SQL Server has returned an error text of message from SQL Server Do you want to retry the operation If the user answers Yes the interface reruns the query If the user answers No the interface returns an error 9D Setting A_MSSQL_DEADLOCK_LOOPS to 1 or MESSAGE is the preferred Configuration File Variables m B 15 action the time it takes to inform users of the problem allows other connections to finish opening the tables giving the AcuOpenTables table time to remove the deadlock A_MSSQL_DEFAULT_CONNECTION
285. ion B 10 Common Questions and Answers Question Question This section contains some questions and answers specific to Acu4GL for Microsoft SQL Server Refer to Chapter 10 for additional questions and answers that pertain to the Acu4GL family of products When I try to open a file for output I get the error 9D 2714 There is already an object named in the database Why One of your record s data items probably has the same name as a Microsoft SQL Server reserved word Locate the column by comparing a file trace of the CREATE TABLE to Microsoft SQL Server s list of reserved words Apply the NAME directive to the field in the FD that is associated with the invalid column then recompile the program to create a new XFD file Can I open tables in different databases Yes Use a file name like database owner tablename Note that because Acu4GL for Microsoft SQL Server automatically determines an owner you can also specify a file name like database tablename The two dots are mandatory in this case Can I use multiple servers on the same machine or on different machines on my network Yes Each server has a unique name Im getting an error 9D 11 ACUCOBOL GT lock table missing I know that I added the lock table during installation This is probably a permissions problem All users must have READ WRITE UPDATE and DELETE access to AcuLocks and therefore to the database that conta
286. ion lists the Acu4GL error messages that could occur during execution of your program Chapter 9 provides information on compile time errors and also provides several methods for retrieving runtime errors Runtime Errors m F 31 An explanation and a recommended recovery procedure follow each message Runtime errors will have this format 9D xx The 9D indicates a file system error and is reported in your FILE STATUS variable The xx is a secondary error code These are the secondary errors reported directly from Acu4GL 9D 01 Read error on dictionary file An error occurred while reading the XFD file this probably means the XFD is corrupt Recompile with Fx to re create the dictionary See section 8 1 for information on compiler options 9D 02 Corrupt dictionary file The dictionary file for one of your COBOL files is corrupt and cannot be read Recompile with Fx to re create the dictionary 9D 03 Dictionary xfd file not found The dictionary file for one of your COBOL files cannot be located Be sure you have specified the correct directory via your XFD_PREFIX runtime configuration file variable You may need to recompile with Fx to create the dictionary 9D 04 Too many fields in the key There are more than 16 fields in a key Check your key definitions and restructure the key that is illegal and then recompile with Fx 9D 06 Mismatched dictionary file The dictionary file xfd for one
287. ions and restructure the key that is illegal and then recompile with the Fx option 9D 06Mismatched dictionary file The dictionary file xfd for one of your files conflicts with the COBOL description of the file FD The xx indicates a tertiary error code that is defined by the host file system You can determine the exact nature of the mismatch by referring to the host system s error values The tertiary error code may have any of these values 01 mismatch found but exact cause unknown this status is returned by the host file system 02 mismatch found in file s maximum record size 03 mismatch found in file s minimum record size 04 mismatch found in the number of keys in the file 05 mismatch found in primary key description 06 mismatch found in first alternate key description 07 mismatch found in second alternate key description The list continues in this manner for each alternate key 9D 11ODBC connection missing needed functionality Because ODBC has so many implementations we require certain minimal functionality This includes the ability to list columns list primary keys list existing tables and support Level 1 SQL Your ODBC driver lacks one or more of these capabilities D 44 m Acu4GL for ODBC Information 9D 12ODBC library function returned an unexpected error One of the ODBC library functions returned an error that was not expected 9D 13Illegal size or type of data
288. ions is a logical unit If the program were interrupted and completed only some of the four file operations then the files would be in an inconsistent state For example if the program terminated unexpectedly after it updated the customer record but before it updated the inventory record then a subsequent run might access non existent inventory Oracle Concepts Overview m C 3 The solution to this problem is to provide a method for the programmer to define a set of operations that should either all occur or all not occur Then if the program encounters an error or terminates the files are left in a consistent state All file operations that are part of a transaction are logged Once logged they can either be committed or rolled back undone by the program If a program dies or the system fails the log file can be used to reconstruct complete transactions returning all files to a consistent state Transaction logging thus offers these two facilities e It provides the programmer with the ability to define transactions and the ability to commit them or undo them usually in response to an error condition This undo facility is called a rollback e It provides the ability to reconstruct files into a consistent state after a program dies or system failure occurs This operation is called recovery Record locking issues in transactions Applications that are written for transaction management systems or t
289. ionships between keys and foreign keys on tables constraints on field relationships and contents and so forth If you have specified that a file is to reside on a RDBMS by setting either DEFAULT_HOST or filename_HOST an OPEN OUTPUT filename statement in your COBOL program will automatically generate a CREATE TABLE filename function on the specified host database Appropriate permissions will be granted based on your login and password and on access parameters you have set See the Contents page to find the appendix specific to your RDBMS for details If a table will eventually be large you may wish to have your systems database administrator create the table and indexes for you Databases offer many methods of creating tables that may improve performance for large tables such as spreading the table across multiple hard drives or storing the data and the indexes on different drives Note Acu4GL uses a specific naming convention for indexes it creates Indexes created with Acu4GL use the i lt TABLENAME gt _ lt key value gt convention If you are using indexes created outside of the Acu4GL application you must ensure that the index names match the Acu4GL naming convention Changes to the way a database functions should be carefully considered and tested before being fully implemented If a database violation occurs the engine detects it and Acu4GL returns an I O error condition to the COBOL program The program can if desired call
290. is created with the owner being the name specified in A_ODBC_LOGIN Using USER_PATH with other variables such as ALODBC_CATALOG can speed up the finding of tables in large databases It can also prevent an error 9D 14 More than one table with the same name thereby enabling access to tables with identical names but with different schemas For example If the USER_PATH and ALODBC_CATALOG are used the form of the SQL statement will be modified from select COL1 from TABLENAME to SELECT COL1 FROM catalog username TABLENAME where catalog and username will be filled in if provided See Also A_ODBC_LOGIN configuration variable A_ODBC_CATALOG configuration variable Mixed case SQL Identifiers m D 35 D 6 Mixed case SQL Identifiers Identifiers in SQL 92 are not case sensitive However drivers that do not conform strictly to SQL 92 may require mixed case identifiers If your driver enforces a mixed case do the following 1 Compile your source COBOL program with the Fc option to generate mixed case identifiers in your XFD files 2 Modify the filename in your COBOL program to match the target identifier s case 3 In your configuration file set the configuration variable 4GL_COLUMN_CASE to UNCHANGED Possible values are UPPER LOWER UNCHANGED D 7 Record and Table Locking Acu4GL for ODBC supports record locking for multi user systems as long as your ODBC driver supports
291. is enables you to change file systems during the execution of your program This is not the typical way to specify a file system normally it is designated in the runtime configuration file and is not changed in the COBOL program Note The Acu4GL for ODBC product allows you to create an ODBC table with an OPEN OUTPUT statement just as you can create Vision indexed files if the data source driver allows for table creation The ODBC equivalent of a Vision file is a table not a database You must create a database for your ODBC tables before you run the COBOL program that creates the tables just as you must create a directory for your files before you run a COBOL program that creates Vision files D 2 6 Designating the Host Data Source You must tell the runtime system which data source to use for your ODBC file You accomplish this by setting the configuration variable A_ODBC_DATASOURCE to the exact name that you set up in the Windows ODBC driver manager You can set this variable in your COBOL configuration file if you will be using only one data source This variable is described in section D 4 Acu4GL for ODBC Configuration File Variables For example if the data source you want to select is listed in the control panel ODBC window as MS Access Databases Access Data mdb you should add the following line to your configuration file A_ODBC_DATASOURCE MS Access Databases If you used the Add option to configure
292. is the collection of stored procedures necessary for executing the Acu4GL product Step 4 Install the ACUCOBOL GT stored procedures You must have Database Administrator privileges to do this step You need to enter the password for the Database Administrator Type ISQL USA Ppassword lt SYB_INST SQL Another way to accomplish the same result is to use ISQL W to execute syb_inst sql as a query See your Sybase documentation for how to do this By default the stored procedures are installed into the master or sybsystemprocs databases However you may choose another database in which to store them Follow these steps if you want to install the stored procedures in a database other than the default 1 Before you execute the syb_inst sql query modify the query file to use the desired database instead of the master or sybsystemprocs database After you have modified the query file execute it as described above 2 Create in each database that contains tables accessed by Acu4GL the stored procedures that were previously in the master or sybsystemprocs database Note that the stored procedures are executed without being prefixed by a database name and Sybase requires that such stored procedures must be in the master or sybsystemprocs database The interface also searches for and executes the sp_AcuInit stored procedure from this location This stored procedure is executed when a connection is made to the database therefore s
293. its prior state the record will be modified or deleted in the database We suggest that you use transactions if this behavior is not acceptable Please note that if the COBOL program cannot be called for any reason it is treated as having succeeded 4 3 4 COMMENT The COMMENT directive allows you to include comments in an XFD file Because the information is embedded in a comment it does not interfere with processing by Acu4GL products Each comment entered with this directive will appear in the XFD file with the symbol in column one Syntax SXFD COMMENT text or XFD COMMENT text Directives Supported by the Acu4GL Interfaces m 4 9 4 3 5 DATE The DATE directive s purpose is to store a field in the database as a date Because there s no COBOL syntax that identifies a field as a date you may want to add this directive to differentiate dates from other numbers so that they enjoy the properties associated with dates in the RDBMS See the description of the configuration variable 4GL_2000_CUTOFF in section 8 2 Runtime Configuration Variables to view special options for two digit dates Syntax SXFD DATE date format string or XFD DATE date format string This directive implies the NUMERIC directive If no date format string is specified six digit or six character fields are retrieved as YYMMDD from the database Eight digit fields are retrieved as YYYYMMDD The date format str
294. ked until the application ends the transaction 5 Because one order is open and not yet committed other applications may be locked out of certain order items if they are still locked by the processing of the first order The second order entry may be held up until the first order is completed 6 Note that the first application is not locked out A process can read its own locked records Acu4GL and record locking Acu4GL provides semi automated ways to handle transaction logging based on the setting of the COMMIT_COUNT environment variable You can also directly alter your source code to deal with this issue Individual users determine how much work they wish to do to conform to the Oracle transaction management system by choosing the method that best fits their needs and resources The following methods are listed in order of increasing amount of work COMMIT_COUNT 0 Default When you set this variable to zero 0 the runtime tracks the number of logical locks that are currently in effect When the number of logical locks reaches zero the runtime assumes that a transaction is complete and issues a COMMIT statement COMMIT_COUNT n When you set this variable to a nonzero value the runtime tracks the number of WRITE REWRITE and DELETE operations until the value of COMMIT_COUNT is reached at which time the runtime issues a COMMIT statement The READ START and READ NEXT operations do not count toward this total beca
295. ked errors when the network is slow Microsoft SQL Server uses a page locking mechanism and so this method of locking records may cause your application to return spurious record locked errors caused by a record being locked on the same page as the record you are trying to access SQL Server 7 0 uses row level locking but because of the timing issue we discourage the use of this option Note Even with this variable set the interface still needs the AcuOpentTables table See also A_MSSQL_VISION_LOCKS_FILE configuration variable Section B 6 Table Locking A_MSSQL_NO_COUNT_CHECK When performing a REWRITE the interface checks to see that a record was actually updated If not it will return an error 23 Setting this variable ON will cause that check not to happen This will improve performance on REWRITE at the risk of missing an error While the default value is Off false no this configuration variable can also take the value of On true yes Configuration File Variables m B 21 A_MSSQL_NO_DBID The interface stores the Database ID in the AcuLocks and AcuOpenTables tables to distinguish different tables in different databases Sometimes this causes problems So setting this variable ON will cause the interface to use a Database ID of 0 instead of the actual ID of the database While the default value is Off false no this configuration variable can also take the value of On tru
296. l users determine how much work they wish to do to conform to DB2 s transaction management system by choosing the method that best fits their needs and resources The following methods are listed in order of increasing amount of work 4GL_COMMIT_COUNT 0 Default When you set this variable to zero the runtime tracks the number of logical locks that are currently in effect When the number of logical locks reaches zero the runtime assumes that a transaction is complete and issues a COMMIT statement DB2 Concepts Overview m F 5 4GL_COMMIT_COUNT n When you set this variable to a nonzero value the runtime tracks the number of WRITE REWRITE and DELETE operations until the value of 4GL_COMMIT_COUNT is reached at which time the runtime issues a COMMIT statement The READ START and READ NEXT operations do not count toward this total because the runtime is tracking data altering operations rather than logical record locks The disadvantage of this method is that when a COMMIT is issued any record locks held by the runtime are released 4GL_COMMIT_COUNT 1 No commit is issued by the Acu4GL product When 4GL_COMMIT_COUNT is set to 1 two alternate ways to perform a commit or rollback are available 1 Call sql acu with COMMIT WORK or ROLLBACK WORK 2 Use the COBOL verbs COMMIT and ROLLBACK available in ACUCOBOL GT 4GL_COMMIT_COUNT is set to 1 automatically when you use the transaction management faci
297. lation for UNIX C 9 installation for Windows C 7 Instant Client C 20 limits and ranges C 29 linking C 8 linking runtime C 12 makefiles C 11 open_cursors C 5 record locking C 3 runtime errors C 30 SCO UNIX C 13 security C 6 setting up the search path C 18 setting up the user environment C 16 setting up user accounts C 15 shared libraries C 13 supported features C 28 table ownership C 6 transactions C 2 C 19 C 28 troubleshooting C 30 origins of ODBC D 2 OTHER condition 4 21 output file 9 3 overriding the WHERE constraint 8 13 overview m Index 31 Acu4GL 1 2 configuration variables 8 4 data dictionaries 3 1 demonstration program 2 6 document 1 3 getting started 2 2 installation 2 2 multiple record definitions 3 6 ODBC D 2 Sybase E 2 XFDs 3 9 ownership tables Oracle Acu4GL C 6 SQL Server Acu4GL B 2 Sybase Acu4GL E 2 P parameters ERROR CODE 4 8 Oracle system C 14 performance compile errors 9 12 compile warnings 9 14 data searches 9 5 database interaction with COBOL 9 6 file input and output 9 3 guidelines 9 2 improving database C 22 Informix 7 2 and 7 3 A 13 overview 9 2 planning ahead 9 7 restructuring data 9 5 runtime errors Index 32 m DB2 F 31 Informix A 23 ODBC D 42 Oracle C 30 SQL Server B 39 Sybase E 54 SQL errors ODBC D 44 tables and multiple indexes 9 4 transactions 9 4 Vision files 9 5 planning ahead growth 9 7 Position menu demonstration program 2 10 preparing a COBOL pro
298. le rather than just the fields from the largest record e assign a column the DATE type so that it will have the built in functionality that dates have in the RDBMS e give a name to the data dictionary file itself Directive Syntax m 4 3 Directives are always placed within a COBOL FD They do not affect Procedure Division I O statements and they do not change your COBOL fields in any way Rather they guide the building of the data dictionaries giving you a measure of control over the way COBOL data is mapped to database fields Data dictionaries may be built directly from your source code with no directives if the default mapping rules described in Chapter 3 Data Dictionaries and Chapter 7 New and Existing Databases are sufficient for your situation If you would like to override the default mapping behavior or map a field to a different name you must add directives to your COBOL code 4 2 Directive Syntax Place each directive syntax on a line by itself immediately before the COBOL line to which it pertains Introduce each directive with a in the Indicator Area column 7 in standard ANSI source format followed immediately by the letters XFD and then the directive itself There should be no space between the and the XFD Spaces are permitted elsewhere on the line as separators For example the NAME directive looks like this S XFD NAME EMP NUMBER An alternate ANSI compliant way to intro
299. le systems linked into the runtime will be searched for the named file If however you are creating a new file you will need to tell the runtime which file system to use You accomplish this with one of two configuration variables the first is DEFAULT_HOST filesystem This will designate the file system to be used for newly created files that are not individually assigned If this variable is not given a value the Vision file system is used Example DEFAULT_HOST x means that all new files will be x files unless individually assigned to another file system For example 8 14 m Compiler and Runtime Options DEFAULT_HOST INFORMIX means that all new files will be Informix files unless they are individually assigned to another file system The possible values for x are the following e INFORMIX e ORACLE e MSSQL e ODBC e DB2 e SYBASE e EXTFH See also The filename_HOST variable which specifies the file system to be used for one specific file filename_HOST The second variable that can be used to assign a newly created file to a file system is filename_HOST This configuration variable is used to assign an individual data file to a file system Any file so assigned will use the designated file system and not the one specified by DEFAULT_HOST Substitute the base name of the file for filename The name you substitute should not include any directory names and should not include a file extension
300. lean to ensure that you have a clean directory in which to build your runtime Now enter the following command make f Makefile ora or makerun This compiles sub c and filetbl c and then links the runtime system Note Make sure you have correctly set all of the flags specific to your platform correctly before you relink your library and object files If the make fails because of an out of date symbol table execute the following command ranlib a and then execute the make again If the make fails for any other reason call Technical Services Installation and Setup m C 13 If you are relinking your runtime under SCO UNIX you must add Irpe lsocket to the LIBS section of Makefile ora If you place them on a line by themselves remember to place a backslash at the end of the previous line You must also remove these two libraries from the ACUSERVER_LIBS line 2c Verify the link Enter the following command runcbl vv to verify the link This returns version information on all of the products linked into your runtime system Make sure it reports the version of Acu4GL for Oracle Shared libraries If you have relinked the ACUCOBOL GT runtime and receive an error message of this type when you try to execute it Could not load library no such file or directory Can t open shared library this may mean that your operating system is using shared libraries and ca
301. legal Columns that are part of an index may not be of type TEXT or type IMAGE Check your key definition 9D 13 Internal error Multiple records were found with the same index this is a Microsoft SQL Server error 9D 14 DB library function returned an unexpected error dbinit Microsoft SQL Server failed An error message from Microsoft SQL Server is displayed on the terminal 9D 16 Trying to rename a table across databases RENAME works only within the same database 9D 17 Cache error internal error The internal process cache has been corrupted Please contact Technical Services 9D 18 Primary Key error An error occurred when creating the primary key for a secondary table 9D 19 Table Size Error The table is larger than Microsoft SQL Server will accept either in the number of columns or in the number of bytes in the row Use the SECONDARY_TABLE directive to get around this 9D 20 no message associated with this error This error tells you that you are trying to do something with a FAST_ACCESS table that is not allowed The description of the A_MSSQL_FAST_ACCESS configuration variable in section B 4 details the restrictions for tables opened this way 9D 21 no message associated with this error There was a problem accessing one or more Vision locks files and processing of this request cannot continue The tertiary error is an error code returned from Vision B 42 m Acu4GL for Microsoft SQL Server Informat
302. lities available in the ACUCOBOL GT compiler ACOMMIT WORK is however issued on exit from the runtime for example on execution of a STOP RUN COMMIT VERB IN COBOL This method forces a COMMIT to be sent to DB2 It can be used in conjunction with other modes of COMMIT handling For non DB2 files this is equivalent to the UNLOCK ALL verb EXPLICITLY CODED TRANSACTIONS This method provides the greatest flexibility in that transactions are specifically tailored for the user s application This method also requires the most work for traditional COBOL programs in which transaction modules may not be clearly defined See section F 6 Record and Table Locking for additional information F 6 m Acu4GL for DB2 Information F 2 Installation and Setup The following topics list the steps you must perform before you begin using Acu4GL for DB2 on a new system e Windows Installation e UNIX Installation Steps e Sample Configuration File e Setting Up the User Environment e Designating the Host File System e Designating the Host Data Source F2 1 Windows Installation The DB2 RDBMS version 6 01 or higher must be installed and configured prior to the installation of Acu4GL for DB2 Consult your DB2 documentation if you have any questions regarding this step You should have the client software installed and configured along with any Database Aliases before installing Acu4GL for DB2 Note Acu4GL for DB2 requires DB2 cl
303. ll fit within the table and simplifies the storage and retrieval process If you were to examine the database columns only the fields from the largest record and the key fields would appear See section 3 2 2 Defaults Used in XFD Files for additional information Note If the field named in the KEY IS phrase is a group item it will not become a column in the database table Instead each of the elementary items subordinate to the named group item will become a column You can force a group item to be a column by using the USE GROUP directive described in Chapter 4 With multiple record formats level 01 not all COBOL fields are represented in the database by name but all fields are storable and retrievable The data dictionary maps fields from all records of a file to the corresponding locations in the master largest record of the file and thus to the database table Since Acu4GL has access to the data dictionary it knows where the data from a given COBOL record fits in the database tables This activity is invisible to the COBOL application For example if your program has one file with the three records shown below the underlined fields will be included in the database table by default this example assumes that ar codes key is named in a KEY IS phrase 3 4 m Data Dictionaries Some fields will not appear in the table but the data dictionary will map them to the master field names Acu4GL thus will eliminate r
304. login from a client to a remote server you could have either of the following two settings ORA_LOGIN username ORA_PASSWD userpass A_ORA_DATABASE remotesrv C 26 m Acu4GL for Oracle Information or ORA_LOGIN username remotesrv ORA_PASSWD userpass In this example remotesrv is the net service name you have set up as defined above in the section dealing with ALORA_DATABASE See also ORA_LOGIN configuration variable A_ORA_DATABASE configuration variable USER_PATH USER_PATH indicates the user name or names to be used when Acu4GL searches for files The order of the names is significant The syntax for this variable is USER_PATH userl user2 where the user argument may be either the name of a user on the system or 66 99 a period which indicates the files owned by yourself The type of OPEN being issued for the file determines the effects of this setting Examples If an OPEN INPUT or OPEN I O is issued and a USER_PATH variable is defined in the runtime configuration file Acu4GL searches for a user of the named file in the following sequence of places 1 The list of users in USER_PATH 2 The public synonyms The first valid file is opened Configuration File Variables m C 27 If USER_PATH is defined and the current user is the owner of the file the current user must be included as one of the users as indicated by a in the USER_PATH If this is not the case even thou
305. m or SET ENVIRONMENT DEFAULT_HOST TO filesystem This enables you to change file systems during the execution of your program This is not the typical way to specify a file system normally it is designated in the runtime configuration file and is not changed in the COBOL program B 10 m Acu4GL for Microsoft SQL Server Information Note The ACUCOBOL GT interface to Microsoft SQL Server allows you to create a Microsoft SQL Server table with an OPEN OUTPUT statement just as you can create Vision indexed files The Microsoft SQL Server equivalent of a Vision file is a table not a database You must create a database for your Microsoft SQL Server tables before you run the COBOL program that creates the tables just as you must create a directory for your files before you run a COBOL program that creates Vision files You are now ready to use the sql acu program as defined in Chapter 2 After you learn about and use this utility you will next find out about preparing and compiling your COBOL program followed by learning to use the demonstration program which can also be found in Chapter 2 B 3 Filename Translation As you prepare to work with Acu4GL for Microsoft SQL Server you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD files are formed and work together When the ACUCOBOL GT compiler generates XFD files it uses lowercase letters to name
306. m portions of your application you can probably make an improvement in processing speed READ operations can also affect performance All COBOL I O is based on key indexes Examining the output of your query optimizer allows you to determine if the most efficient execution path is being used for READs The execution path for a given query can change as your data changes and as the size of the tables changes It is also affected by database initialization parameters and any statistical information that you may have gathered on your tables It might be helpful to know that typically the index path is the most efficient for Acu4GL applications Transactions Large transactions are also very expensive The main problem here is that the database will hold locks on indexes and rows throughout an entire transaction Thus the database is creating additional overhead for an extended period of time if the transaction is lengthy In addition complex information tracking must take place to ensure that transactions can be successfully rolled back Often application designers decide to err on the side of safety when applying transaction management to a mature application Which operations should be included in a single transaction The safe approach is to group everything that is related into one transaction But this scheme is expensive even more so when a database is involved The lengthier the transaction the longer the locks are held and system
307. make sure the verb references an indexed file Acu4GL passes all transaction operations on to the database Passing all transaction flags to the database may have the unexpected effect of releasing a lock because of the COMMIT of a transaction Acu4GL for Informix performs REWRITE and DELETE operations on the current record through the record lock using the syntax WHERE CURRENT OPF If this is a problem Acu4GL can be told to use an alternate method of explicitly specifying the primary key in the REWRITE and DELETE operations by setting the configuration variable 4GL_POSITIONED_MODIFICATIONS 0 The default is 1 You should note that database systems will not perform well with applications compiled with the ft option You should consider explicitly coding the transactions Limits and Ranges m A 21 A 7 Limits and Ranges The following limits exist for the Informix SE file system Maximum indexed key size 120 bytes Maximum number of fields per key 8 The following limits exist for the Informix OnLine file system Maximum indexed key size 256 bytes Maximum number of fields per key 16 With the Acu4GL product for Informix only one database can be open at a time Within this one database a maximum of 100 tables can be open at the same time You can set this table maximum to a lower number via the runtime configuration variable MAX CURSORS The following Informix data types are not currently supported I
308. ments row level locking this locking method may be the preferred method See also A_SYB_VISION_LOCKS_FILE configuration variable Section E 5 Record and Table Locking E 36 m Acu4GL for Sybase Information A_SYB_NO_COUNT_CHECK When doing a REWRITE the interface checks to see that a record was actually updated If the record was not updated the interface returns an error 23 Setting this variable On causes that check not to happen This improves performance on REWRITE at the risk of missing an error While the default value is Off false no this configuration variable can also take the value of On true yes A_SYB_NO_DBCLOSE When the runtime is shutting down the interface closes all the open connections as per the Microsoft documentation Sometimes with some network drivers this takes a significant amount of time Setting this variable On causes the interface not to close the connections Though this can speed up the runtime during shutdown we don t recommended it because the Microsoft documentation is not being followed While the default value is Off false no this configuration variable can also take the value of On true yes A_SYB_NO_DBID The interface stores the Database ID in the AcuLocks and AcuOpenTables tables to distinguish different tables in different databases Sometimes this causes problems Setting this variable ON causes the interface to use a
309. mes 7 4 conversions data 7 2 upper and lower case 7 2 creating an empty table with sql acu 2 3 creating COBOL records 1 13 creating dictionaries 1 12 creating FDs file descriptors 6 10 creating large tables 1 15 creating makefile Informix A 4 creating map files Acu4GL for DB2 F 17 Acu4GL for ODBC D 22 creating runtimes Acu4GL for Informix A 4 Acu4GL for Oracle C 10 Acu4GL for Sybase E 6 creating SELECTs 6 10 creating SQL statements 1 13 creating stored procedures SQL Server B 6 Sybase E 15 creating XFD files at compile time 3 2 creating XFD files compiler option 8 2 cursor caching Oracle C 14 cursors maximum per file C 22 D data accessing 1 6 Index 14 m DB2 types F 29 existing 7 2 7 3 format conversion 7 2 invalid database 5 3 invalid key 5 3 new 7 2 ODBC types D 38 restructuring 9 5 searches 9 5 sequencing 7 2 types not supported Informix A 21 data dictionaries XFDs 3 2 Acu4GL 1 8 creating 1 12 overview 1 11 source code 4 3 data mapping COBOL to ODBC D 39 DB2 types to COBOL types F 29 ODBC types to COBOL types D 40 data sources DB2 designating the host F 13 ODBC designating the host D 16 overview D 7 setting up D 12 DATABASE configuration variable A 11 database data invalid 5 3 database functions changing 1 15 database table Oracle C 28 SQL Server B 28 database violations 1 15 databases accessing 1 13 m Index 15 ANSI mode and Acu4GL for Informix support A 2 concepts 1 9 data
310. mine the correct flag for your environment Step 3 Copy runcbl to the correct directory If the runtime system is a statically linked runcbl copy the new executable to a directory mentioned in your execution path This file needs to have execute permission for everyone who will be using the runtime system The copy step is not necessary when the runtime system is a shared library The ACUCOBOL GT license file for the runtime runcbl alc and the license file for the Acu4GL product to Oracle runcbl olc must be copied into the same directory as the runtime executable If you rename your runtime executable be sure to rename your license files to base name with the extensions unchanged For example if you rename your runtime to be myprog bin the license file for the Acu4GL product for Oracle should be renamed myprog olc and the license file for the runtime should be renamed myprog alc The remaining files can be left in the directory into which they were installed from the distribution medium C 2 4 Checking System Parameters Acu4GL makes use of cursor caching to process Oracle RDBMS data efficiently A cursor is a prepared query saved in a parameterized format When a like function is to be performed on a different record such as a GET NEXT the task can be performed by executing the saved query with new Installation and Setup m C 15 parameters This improves performance by eliminating the
311. mit is issued by the Acu4GL product When 4GL_COMMIT_COUNT is set to 1 two alternate ways to perform a commit or rollback are available 1 Call sql acu with COMMIT WORK or ROLLBACK WORK 2 Use the COBOL verbs COMMIT and ROLLBACK available in ACUCOBOL GT 4GL_COMMIT_COUNT is set to 1 automatically when you use the transaction management facilities available in the ACUCOBOL GT compiler ACOMMIT WORK is however issued on exit from the runtime for example on execution of a STOP RUN Examples 4GL_COMMIT_COUNT 0 A commit will be issued when no locks are held either because all files that had locked records have been closed or because a COBOL COMMIT verb has been issued This is the default value Note that some data sources lose the current row when a COMMIT or ROLLBACK is executed For these data sources a setting of O for 4GL_COMMIT_COUNT can adversely affect performance 4GL_COMMIT_COUNT n A commit will be issued after n operations WRITE REWRITE and DELETE count towards n READ START and READ NEXT do not 4GL_COMMIT_COUNT 1 No commit will be issued by the Acu4GL product When 4GL_COMMIT_COUNT is set to 1 the only way to perform a commit or rollback is to use the COBOL verbs COMMIT and ROLLBACK 8 8 m Compiler and Runtime Options 4GL_COMMIT_COUNT is set to 1 internally when you use the transaction management facilities available in ACUCOBOL GT A COMMIT will however b
312. n COBOL FD statements for existing tables To start the program select the DRVTST32 EXE icon in the program group where Acu4GL for ODBC has been installed User interaction for this program is minimal The only time you need to interact with the program is when it first starts and you are asked for the name of the ODBC driver to connect to You will see a dialog very similar to the ODBC setup dialog prompting you to select a data source Once you have selected a data source you may be asked to log on to the data source this depends on the data source you select Enter your login and password if necessary After that the program queries the ODBC driver and creates a file called ACUCOBOL RPT in the current directory This file is filled with information about the driver you chose but is in a format that is most useful to extend Technical Services When you are finished running the driver test program send the ACUCOBOL RPT file to extend Technical Services and they can help you determine the compatibility level of your driver If you execute this program multiple times information will be appended to the original ACUCOBOL RPT file D 38 m Acu4GL for ODBC Information D 10 Data Type Mapping Overview of ODBC data types ODBC defines certain generic data types which every data source driver maps to its own internal types Each driver needs to be queried about which types it supports because different drivers s
313. n D 6 concepts D 2 configuration variables D 18 creating map files D 22 data sources D 7 D 12 data type mapping D 38 description D 2 designating host data source D 16 Driver Manager D 6 driver requirements D 36 driver test D 37 drivers D 6 getting started D 10 m Index 29 information D 2 installation and setup D 10 limits and ranges D 36 mapping COBOL data to ODBC data D 39 mapping ODBC data types to COBOL data types D 40 origins of D 2 record and table locking D 35 restrictions D 3 runtime errors D 42 setting up the user environment D 14 SQL errors D 44 structure multiple tier architecture D 5 overview D 3 single tier architecture D 4 troubleshooting D 42 Open Database Connectivity See ODBC open_cursors parameter Oracle C 5 options F4 3 2 Fa 3 2 Fx 3 2 Options menu demonstration program 2 11 ORA_LOGIN configuration variable C 25 ORA_PASSWD configuration variable C 25 Oracle configuration variables list of A_ORA_DATABASE C 21 A_ORA_HINTS C 22 A_ORA_MAX_FILE_CURSORS C 22 A_ORA_WAIT_LOCK C 23 A_ORACLE ERROR _FILE C 23 COMMIT_COUNT C 23 ORA_LOGIN C 25 ORA_PASSWD C 25 USER_PATH C 26 Index 30 Oracle configuration variables overview C 21 Oracle Hints feature turning on C 22 Oracle Instant Client C 20 Oracle Acu4GL checking system parameters C 14 configured login C 16 creating a new runtime C 10 database table C 28 designating host file system C 17 getting started C 7 instal
314. n the database table and determines when specific database columns are used The underlined fields then appear as columns in the database table Directives Supported by the Acu4GL Interfaces m 4 23 01 ar codes record 03 ar codes key 05 ar code type pic x 05 ar code num pic 999 Sxfd when ar code type s 01 ship code record 03 filler pic x 4 03 ship instruct pic x 15 xfd when ar code type t 01 terms code record 03 filler pic x 4 03 terms rate 1 pic s9v999 03 terms days 1 pic 9 3 03 terms rate 2 pic s9v999 03 terms descript pic x 15 FILLER data items don t have unique names and are thus not used to form columns in the database table You could use the NAME directive to give them a name if you really need to see them in the database table Note In this example the FILLER data items implicitly redefine key fields Thus they would be disregarded even if you provided a name for them Example 2 In the following code in which no WHEN directives are used the underlined fields will be explicitly named in the database table Key fields have the suffix key in their names in this example Note that REDEFINES records simply re map the same data area and are not explicitly included in the database table by default 01 archive record 03 filler pic x 33 03 archive code pic 9 6 03 archive location pic 9 2 03 filler pic x 10 01 master record 03 animal id key 05 patient id pi
315. n you receive See Chapter 3 of the ACUCOBOL GT User s Guide for more information on using the debugger FILE TRACE ON is echoed on the screen Now enter the following command g You are now running your program normally Proceed until you encounter the error condition and then exit Your error file contains the error information described in Method One above and also contains the SQL queries that the Acu4GL product constructed Examining these queries can help to determine the cause of the syntax error Please contact Technical Services if you need help 9 18 m Performance and Troubleshooting 9 2 3 3 Retrieving messages using C RERR You might want to separate the error codes and their associated text and store them in variables The variables can then be displayed to the screen or handled in whatever way you deem appropriate You saw an example of the usage of CSRERR in the sample program in Chapter 2 Getting Started The simplified example shown below uses the library routine CSRERR with two parameters to retrieve the complete error code first parameter and its associated text second parameter Note See For Informix at the end of this section for code that is specific to Informix DATA DIVISION working storage section 01 file status pic xXx 01 error status 03 primary error pic x 2 03 secondary error pic x 40 01 error text pic x 40 PROCEDURE DIVISION get file err call
316. nd that you go to a different directory and then type the following command sqlplus scott bigdb tiger select user from dual On UNIX if this test is successful relink the runtime to use the Instant Client For instructions on relinking see section C 2 3 Completing the Installation The ora_inst script will recognize the Instant Client structure just tell it the directory into which you installed the Instant Client when asked for the ORACLE_HOME setting On Windows if this test is successful you are ready to use the runtime The Windows runtime loads the Oracle Instant Client dynamically from the specified path To verify that you have loaded the application successfully enter wrun32 v on the command line You should see Acu4GL ORACLE OCI file system included on the ACUCOBOL GT window that is displayed Filename Translation m C 21 C 4 Filename Translation As you prepare to work with Acu4GL for Oracle you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD files are formed and work together When the ACUCOBOL GT compiler generates XFD files it uses lowercase letters to name the XFD file In addition the compiler changes hyphens to underscores when naming the XFD file Through configuration variables the runtime translates the file name in the COBOL program into the filename that is passed to the open function in the runtime The
317. ned on the Quick Start card that accompanied the product Please refer to it for installing the ACUCOBOL GT development system and Acu4GL Once the installation is complete please refer to this appendix for setting up your Acu4GL product Regarding relinking for Windows users Relinking is not required for Windows users but it is required for UNIX users and is explained in section C 2 2 UNIX Installation Steps Windows users access Oracle through a DLL file detected at runtime a4ora32 dIl For compatibility purposes this file is a copy of the file aA4oraoci dll and is created during the installation process Note If users are using Oracle client software to connect to a database not on the current machine they must set up an alias for the database they are connecting to using Oracle s Net Configuration Assistant or a similar tool For example you would use such a tool to set up an alias called sun10 that has these settings Protocol TCP IP Host Name SUN10 Database Instance ORCL You should then test this alias using SQL Plus with a login of username sun10 Once this configuration is verified you can set the ORA_LOGIN variable in the COBOL configuration file to that value for example ORA_LOGIN username sun10 If you prefer this setting can be broken up using the new configuration variable A_LORA_DATABASE as follows ORA_LOGIN username ORA_PASSWD userpass A_ORA_DATABASE remot
318. nfiguration variable A_ODBC_DATASOURCE as described in section D 4 If your driver requires them be sure to set A_ODBC_LOGIN and A_ODBC_PASSWD Also set DEFAULT_HOST Other configuration variables that may make finding and accessing tables faster and more precise are USER_PATH and A_ODBC_CATALOG D 2 3 Setting Up Data Sources You will need to set up a data source name for any item you want to be able to access from Acu4GL for ODBC The exact steps required for this will vary for each individual driver The general steps for setting up an ODBC data source are 1 Open the Windows control panel and select Administrative Tools Acu4GL for ODBC Installation and Setup m D 13 2 Double click the Data Sources ODBC icon The ODBC Data Source Administrator dialog is displayed This dialog lists all the data sources currently configured for your system J x User DSN System DSN File DSN Drivers Tracing Connection Pooling About User Data Sources Name Driver O a dBASE Files Microsoft dBase Driver dbf dBase Files Word Microsoft dBase YFP Driver dbf Remove DeluxeCD Microsoft Access Driver mdb Excel Files Microsoft Excel Driver xIs Configure FoxPro Files Microsoft FoxPro Driver dbf _Lenfigue FoxPro Files Word Microsoft FoxPro YFP Driver dbf MAIS SAL Server MS Access 97 Database Microsoft Access Driver mdb _ MS Access Database Microsoft Access Driver mdb Text Files Mic
319. nforces database rules and constraints any violations are returned to the COBOL program as I O error conditions 1 5 1 What Is a Transparent Interface Acu4GL products provide a transparent efficient interface between your program and the relational database The interface is categorized as transparent because the communication between your COBOL program and the database is smooth with no special query coding on your part and no interruptions in the execution of your program You need not change your COBOL code if you later want to access a different database or to access an alternate indexed file system The information exchange operations between the database and the COBOL program are invisible to the end user For example if your program specifies a READ a database query is automatically generated by the interface Then the data that is read from the database is translated into a COBOL record This exchange occurs in fractions of a second and the application proceeds without interruption 1 5 2 Data Dictionaries and Mapping Because relational databases handle I O at the column field level and COBOL handles I O at the record level some mapping is necessary to associate records with their fields One function of the Acu4GL product is to map COBOL records into database fields and to map the database fields back into records Acu4GL does this by consulting data dictionaries generated by the compiler The detailed structure of data dic
320. nnot find them This can occur even if the shared libraries reside in the same directory in which you are currently located Different versions of the UNIX operating system resolve this in different ways so it is important that you consult your UNIX documentation to resolve this error Some versions of UNIX require that you set an environment variable that points to shared libraries on your system For example on an IBM RS 6000 running AIX 4 1 the environment variable LIBPATH must point to the directory in which the shared libraries are located On HP UX the environment variable that must be set to point to shared libraries is SHLIB_PATH On UNIX SVR4 the environment variable is LD_LIBRARY_PATH Note that the correct version of the ORACLE_HOME lib should be in your LD_LIBRARY_PATH This might C 14 m Acu4GL for Oracle Information be ORACLE_HOME lib64 or ORACLE_HOME lib depending on what the default is for your system If a lib32 directory exists the 64 bit libraries may be the default Please refer to your Oracle release notes for more information Be sure to read the system documentation for your operating system to determine the appropriate way to locate shared libraries A second way to resolve this type of error is to link the libraries into the runtime with a static link Different versions of the C development system use different flags to accomplish this link Please consult the documentation for your C compiler to deter
321. not change but it is unknown if this will work for all situations We provide this method for backwards compatibility only One 1 If this variable is set to one 1 a ROWID is added to the ORDER BY clause of all SELECT statements reading tables on an alternate key that allow duplicates A ROWID is not added if the file is a VIEW This assures a predictable ordering of keys and is the default setting Two 2 If this variable is set to two 2 the primary key segments are added to the ORDER BY clause of all SELECT statements reading tables or VIEWS on an alternate key that allow duplicates A_INF_NO_TRANSACTION_ERROR This configuration file variable allows you to enable or disable the 9D 255 Not in transaction Informix error The default setting for this variable is 1 and does not allow this message to be displayed If this variable is set to zero 0 the 9D 255 error is returned if a stop run caused a commit or rollback to be sent to Acu4GL for Informix Configuration File Variables m A 11 A_INFORMIX_ERROR_FILE This configuration file variable allows you to map errors using a text file to supplement the default method of providing errors By adding the name of the file that contains the actual error mapping to A_INFORMIX_ERROR_FILE database specific errors are mapped to COBOL errors Note Several messages related to COBOL I O cannot be supplemented Example A sampl
322. ntation to determine if login is case sensitive Example To connect to the database with the user name MYNAME you could specify A_ODBC_LOGIN MYNAME or A_ODBC_LOGIN myname Configuration File Variables m D 27 in the runtime configuration file There is no default value for this variable If no login is specified none will be used See also A_ODBC_PASSWD runtime configuration file variable A_ODBC_NO_NULL_COLUMNS The interface will never insert NULL into the database if this is set to TRUE or ON or YES While the default value is Off false no this configuration variable can also take values of On true yes A_ODBC_PASSWD The variable ALODBC_PASSWD should be set to the password assigned to the database account associated with the user name specified by A_ODBC_LOGIN Not all data sources require a password Those that do may have case requirements Check your data source documentation to determine if password is case sensitive Examples If the account with the user name in ALODBC_LOGIN has the associated password CW021535 you would specify A_ODBC_PASSWD CW021535 in the runtime configuration file For better security you can accept a password from the user during program execution set the ALODBC_PASSWD variable based on the response ACCEPT RESPONSE NO ECHO SET ENVIRONMENT A_ODBC_PASSWD TO RESPONSE Note If the user has been set up
323. nted differently in Acu4GL for ODBC than it is in Acu4GL for Oracle or Informix For this reason writing data with one Acu4GL product and then reading it with another will probably produce different results Future releases of Acu4GL for Oracle and Informix will address this problem When I create a table I get an error saying I have placed too many BLOBs binary large objects in my table Some databases have restrictions about the number of BLOBS that can be placed into a single table To work around this restriction you can specify the configuration variable A ODBC_USE_CHAR_FOR_BINARY This allows you to encode binary data in hexadecimal and write it out as CHAR data instead of BINARY Refer to section D 4 Acu4GL for ODBC Configuration File Variables for more information on this variable Are there any ACUCOBOL GT library routines that do not work with or would not make sense to use with Acu4GL for ODBC Yes The CSCOPY and CSRENAME ACUCOBOL GT library routines do not work with Acu4GL for ODBC Acu4GL for Sybase Information Key Topics Sybase Concepts Overview cssscesessecseseseresseceseeceeeneeseeseeneeneeaees E 2 Installation and Setup se eecsecseeseeseceececeresaecesseceeeneeseesrenesneeaees E 3 Filename Translation cceccesceecceseeesceeceeeeeneeeeeceeeseecaecsneceeeaees E 24 Configuration File Variables c cccsccsceesececeeeeeeseeseeeeeeseeese
324. nteractive shell script that determines which libraries your version of Sybase has and then creates a makefile suitable for linking Acu4GL with an ACUCOBOL GT runtime for UNIX It also generates the SQL script used to install ACUCOBOL GT stored procedures Execute the shell script syb_inst by entering the following command on your client machine sh syb_inst Note You may exit the script at any time by pressing the system interrupt key usually CTRL C If you entered only syb_inst instead of the full command this message may appear VAL 0 command not found VAL Undefined variable This can be fixed by entering sh syb_inst When the script begins executing you see the following message During the execution of this script we will create an SQL script which you will need to execute from isql using a command like isql Usa Ppassword lt syb_inst sql This script will add some stored procedures and create some tables in a database that you specify during the execution of this script In order to implement locking from ACUCOBOL GT we need to create a lock table This should be a pretty small table but we need to decide which database to create this table in You should now enter the name of the database you want the lock tables created in If the database does not exist it is created The following question is asked until you enter a valid database name Which database would you like to create this table
325. o On A_SYB_LOCK_DB A_SYB_LOCK_DB specifies the name of the database that holds the lock table See also Section E 5 Record and Table Locking A_SYB_LOGIN A_SYB_LOGIN indicates the user name under which you want to connect to the database system Example To connect to the database with the user name MYNAME specify A_SYB_LOGIN MYNAME in the runtime configuration file If A_LSYB_LOGIN is not set on Windows the runtime uses the value of your USER environment variable as your Sybase login name On UNIX systems the runtime uses your UNIX login name as your Sybase login name For this automatic login to succeed you must have set up a user with the same name as your computer login name See also A_SYB_PASSWD runtime configuration file variable Section E 2 5 Setting Up a User Account E 34 m Acu4GL for Sybase Information A_SYB_MAX_CHARACTERS A_SYB_MAX_CHARACTERS indicates the maximum number of bytes the Acu4GL product will allow in a table row Sybase places a limit on the number of bytes per table row The Acu4GL product adheres to this limit but sometimes it cannot accurately count how many bytes a particular row contains because of overhead bytes that Sybase adds This variable enables the developer to set the Acu4GL product s upper bound You might want to try reducing it if you discover that a row cannot be added to a table By reducing the upper bound you may be able to prevent
326. o all connections a transaction makes to the database not just the primary connection sp_AcuRemoveUnusedLocks_1 Use this stored procedure to determine who is logged in and to remove Process IDs that are no longer active on the system You can call this from sp_Aculnit each time a user connects to the database to ensure that the lock table contains only active locks This stored procedure must reside in the same database as the AcuOpenTables and AcuLocks tables it is placed there automatically when these tables are created during installation sp_AcuTableReport_1 Use this stored procedure to learn who is using the tables in the database at the time this procedure is run Run this procedure before running the sp_AcuZeroUserCount stored procedure so that you can contact users to inform them that the database will be closing This stored procedure must reside in the same database as the AcuOpenTables and AcuLocks tables it is placed there automatically when these tables are created during installation sp_AcuUserCount_ You can run sp_AcuUserCount from the query analyzer to learn how many users have a particular table open You can use this to track table and database activity to ensure that your database is running as efficiently as possible This stored procedure must reside in the same database as the AcuOpenTables and AcuLocks tables it is placed there automatically when these tables are created during installation B 38 m Acu4GL for
327. of your files conflicts with the COBOL description of the file FD The xx indicates a tertiary error code that is defined by the host file system You can determine the exact nature of the mismatch by referring to the host system s error values The tertiary error code may have any of these values 01 mismatch found but exact cause unknown this status is returned by the host file system 02 mismatch found in file s maximum record size F 32 m Acu4GL for DB2 Information 03 mismatch found in file s minimum record size 04 mismatch found in the number of keys in the file 05 mismatch found in primary key description 06 mismatch found in first alternate key description 07 mismatch found in second alternate key description The list continues in this manner for each alternate key 9D 12 DB2 library function returned an unexpected error One of the DB2 library functions returned an error that was not expected 9D 13 legal size or type of data for variable xxx An elementary data item in your FD was larger than 255 bytes or there is no DB2 type that matches the current data type 9D 14 More than one table with the same name When tables were listed more than one table was found with the same name Consider whether or not setting the USER_PATH configuration variable will resolve the issue This variable will enable tables with identical names but with different ownership located in a different schema
328. ollowing message We next need to determine where you have installed the SYBASE client libraries E 8 m Acu4GL for Sybase Information The following prompt is repeated until you enter the directory that contains the Sybase files Enter the directory where the SYBASE client libraries are installed Type the full pathname of the directory containing the Sybase client libraries and press Enter Note that this is the directory that contains the Sybase lib directory For example if the full path for the file libsybdb a is usr sybase lib libsybdb a you would type usr sybase The script checks for a file lib libsybdb a in the directory you entered You then see one of the following messages We seem to have the ACUCOBOL GT library files in this directory We need to find the ACUCOBOL GT library files Enter the directory where ACUCOBOL GT is installed If you are asked to enter the directory name type the full pathname of the directory containing ACUCOBOL GT then press Enter Before the Makefile is created we need to check for some alternate optional libraries You see the message Checking for lnsl or lnsl_s If one of the libraries exists you see using lnsl of using lnsl_s If you instead see a message like this one syb_inst cc not found it s likely that your PATH environment variable does not include the location of your compiler In this case exit from the
329. ollowing steps A 4 m Acu4GL for Informix Information Step 1 Install Informix Install the Informix RDBMS and make sure it is operational Micro Focus does not provide this product Make sure you install the libraries in the appropriate directories based on the Informix documentation We recommend that you obtain Interactive SQL ISQL or dbaccess if possible This is not mandatory but it will give you quite a bit of flexibility ISQL allows you to do database work outside of COBOL including interactive queries and reports ACUCOBOL GT s standard file utility vutil cannot be used on Informix tables One way to test the installation of Informix is to access Interactive SQL and examine the stores database Step 2 Create a new runtime Create a new runtime system that includes the Informix Acu4GL product Note In the following directions the term runtime system refers to the runtime shared object on systems where the ACUCOBOL GT runtime is a shared object and to runcbl on other systems where the runtime is static The runtime is a shared object on the following systems AIX 5 1 and later HP UX 11 and later and Solaris 7 and later To check look at the contents of the lib subdirectory of your ACUCOBOL GT installation If the files libruncbl so or libruncbl sl reside in that directory the runtime is a shared object on your system 2a Backup Make a backup copy of your newly installed runc
330. ommands It can be called from a COBOL program or executed from the command line As a general rule sql acu may be used to issue all SQL commands except those that perform data retrieval The sql acu program cannot perform statements that return data such as the SELECT statement This category of statements returns an error when passed to the sql acu program The global variable return code is 0 when a command has completed successfully If a command is not successful return code contains an error code Running sql acu From the Command Line To use the sql acu utility to create an empty table and grant access privileges to other users 1 Enter runcbl sql acu The program will pause to accept an SQL command 2 4 m Getting Started 2 Enter the following italics indicate variable names non italics are SQL reserved words CREATE TABLE newtab coll CHAR 30 col2 CHAR 11 The program will pause to accept an SQL command 3 Now enter the following command GRANT ALL PRIVILEGES ON newtab TO PUBLIC The program will pause to accept an SQL command 4 Now enter CREATE UNIQUE INDEX newtab_index ON newtab coll 5 Next press Enter again to exit the program Note When naming columns and tables make sure to use underscores _ not hyphens or a syntax error will result The above entries will create a new table and grant access permission to everyone
331. on is updated by one This is why you can install new stored procedures without overwriting older ones Be sure to install all stored procedures when you install Acu4GL for SQL Server sp_Aculnit If the stored procedure sp_AcuInit exists in the master database it is executed when the connection is made to the server This is a procedure you can set up to do customized initialization This stored procedure does not take any parameters and does not return any results This optional stored procedure is executed for all connections by the Acu4GL interface to the database not just the primary connection As an example of customized initialization you can use this stored procedure to remove stale locks by calling sp_AcuRemoveUnusedLocks_1 which is installed when all the other Acu4GL stored procedures are installed or to limit access to the database by certain users during certain hours If sp_AculInit returns an error the connection is denied and the error is reported Stored Procedures m B 37 to the COBOL program The method for returning an error is to execute the Transact SQL statement raiserror See your SQL Server documentation for information about Transact SQL and stored procedures The sp_AcuInit procedure if it exists in the master database is executed whenever Acu4GL makes a new connection including FAST_ACCESS connections to the database Therefore any customization that you ve indicated via sp_AculInit applies t
332. on variable E 25 A_SYB_ADD_TIMESTAMP configuration variable E 25 A_SYB_CHECK_DELETE_SP configuration variable E 26 A_SYB_CHECK_INSERT_SP configuration variable E 26 Index 4 A_SYB_CHECK_UPDATE_SP configuration variable E 27 A_SYB_CURSOR_OPTION configuration variables E 27 A_SYB_DATABASE configuration variable E 28 A_SYB_DEFAULT_CONNECTION configuration variable E 29 A_SYB_EXTRA_PROC configuration variable E 30 A_SYB_FAST_ACCESS configuration variable E 31 A_SYB_FORCED_INDEX configuration variable E 32 A_SYB_LOCK_DB configuration variable E 33 A_SYB_LOGIN configuration variable E 33 A_SYB_MAX_CHARACTERS configuration variable E 34 A_SYB_MAX_COLUMNS configuration variable E 34 A_SYB_NATIVE_LOCK_TIMEOUT configuration variable E 35 A_SYB_NO_23_ON_START configuration variable E 37 A_SYB_NO_COUNT_CHECK configuration variable E 36 A_SYB_NO_DBCLOSE configuration variable E 36 A_SYB_NO_DBID configuration variable E 36 A_SYB_NO_RECORD_LOCKS configuration variable E 36 A_SYB_NO_TABLE LOCKS configuration variable E 37 A_SYB_PACKETSIZE configuration variable E 37 A_SYB_PASSWD configuration variable E 38 A_SYB_ROWCOUNT configuration variable E 39 A_SYB_SELECT_KEY_ONLY configuration variable E 39 A_SYB_SKIP_ALTERNATE_KEYS configuration variable E 40 A_SYB_TRANSLATE_TO_ANSI configuration variable E 40 A_SYB_UNLOCK_ON_EXECUTE configuration variable E 41 A_SYB_USE_DROPDOWN_QUERIES configuration variable E 41 A_SYB_VISION_LOCKS_FILE c
333. onal information is lost Sometimes you need to include a FILLER data item such as when it occurs as part of a key In such a case you could include it under a USE GROUP directive or give it a name of its own with the NAME directive described in Chapter 4 OCCURS clauses An OCCURS clause always requires special handling because the Acu4GL runtime system must assign a unique name to each database column The runtime accomplishes this by appending sequential index numbers to the item named in the OCCURS clause XFD Files m 3 7 For example if the following were part of a file s description 03 employee table occurs 20 times 05 employee number pic 9 3 these column names would be created in the database table employee_number_1 employee_number_2 employee_number_10 employee_number_11 employee_number_20 Note that the hyphens in the COBOL code are translated to underscores in database field names and the index number is preceded by an underscore XFD location If you are using object libraries XFD files can be embedded into COBOL libraries through cblutil and the runtime will find them This is particularly effective when you are using the ACUCOBOL GT Web Runtime and Acu4GL It allows you to send all of the COBOL objects as well as XFD files in one package Please note that if an XFD file is located in an object library and is also located on the disk in a directory pointed to by the XFD_PREFIX configuration v
334. onfiguration variable E 42 access privileges granting with sql acu 2 3 accessing a database 1 13 accessing data 1 6 accounts setting up user for Oracle C 15 for SQL Server B 7 for Sybase E 21 Acu4GL m ndex 5 case conversion in data 7 2 data dictionaries XFDs 1 8 1 11 3 1 data format conversions 7 2 data sequencing 7 2 database concepts 1 9 default behavior 7 2 field names 7 4 getting started 2 2 how it works 1 10 matching COBOL fields to database fields 7 2 matching numeric fields to database fields 7 3 matching text fields to database fields 7 3 overview 1 2 record locking C 4 F 4 summary 1 14 Acu4GL and ACUCOBOL GT library routines 1 15 Acu4GL index naming conventions 1 15 Acu4GL DB2 configuration variables F 14 creating map files F 17 data types F 29 decimal points and F 14 designating the host data source F 13 designating the host file system F 11 filename interpretation F 13 installation and setup F 6 installation for UNIX F 7 libraries shared F 9 limits and ranges F 28 linking the runtime F 7 F 8 mapping DB2 data to COBOL data F 29 record locking F 3 F 28 runtime errors F 31 table locking F 28 transactions F 2 Index 6 troubleshooting F 30 Acu4GL Informix 7 2 and 7 3 performance A 13 and ANSI mode databases A 2 compiling the sample program A 7 configuration variables A 9 creating a makefile A 4 creating anew runtime A 4 designating a database A 8 f
335. open function determines which file system to pass the request to but does not change the name of the file For additional information on configuration variables see Appendix H in Book 4 Appendices of the ACUCOBOL GT documentation set At this point Acu4GL for Oracle translates the file name to uppercase letters and changes hyphens to underscores This new name is the one that Acu4GL for Oracle will use in the future for references to the database table C 5 Configuration File Variables This section lists the runtime configuration file variables that are specific to Acu4GL for Oracle Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are discussed in section 8 2 Runtime Configuration Variables A_ORA_DATABASE A_ORA_DATABASE specifies the name of a network service that you have set up to refer to a database using an Oracle tool such as Net Configuration Assistant or by manually editing tnsnames ora See also ORA_LOGIN configuration variable ORA_PASSWD configuration variable C 22 m Acu4GL for Oracle Information A_ORA_HINTS This variable enables the Oracle Hints feature The default value is 1 on true yes To turn off this feature set it to 0 off false no Oracle Hints can improve database performance considerably in some situations by strongly suggesting to the oracle query optimizer that it use a given index to p
336. option to re create the dictionary See section 8 1 for information on compiler options 04 Corrupt dictionary file The dictionary file for one of your COBOL files is corrupt and cannot be read Recompile with Fx to re create the dictionary A 24 m Acu4GL for Informix Information 05 Too many fields in the key more than 8 for Informix SE more than 16 for Informix OnLine Check your key definitions and redefine the key that is illegal and then recompile with the Fx option There are additional 9D extended error numbers these have values of 100 or more Often they have two parts that are separated by a comma such as 9D 350 108 These are Informix error codes The first part is the database error the second part if any is the ISAM error Informix database error numbers are typically greater than 200 ISAM errors when present fall between 100 and 199 Note See your Informix documentation regarding the finderr syntax for more information 06 Mismatched dictionary file The dictionary file xfd for one of your files conflicts with the COBOL description of the file FD The xx indicates a tertiary error code that is defined by the host file system You can determine the exact nature of the mismatch by referring to the host system s error values The tertiary error code may have any of these values 01 mismatch found but exact cause unknown this status is returned by the host file system
337. orders file from a COBOL program at an imaginary company will be stored in the database This file contains the records that handle all of the information from the company s purchase orders Within the purchase orders file are two record types the purchase order header record There is one of these for each purchase order form the purchase order detail record There is one detail record for each line item in a purchase order The file is keyed off the purchase order number We will build and examine the database table three times to illustrate three different approaches to using the COBOL file description First no directives will be added to the COBOL code The code will be compiled as is Only the largest record will be included in the database table Second the WHEN directive will be added and the program recompiled This will cause all record formats to be included in the database Finally several fields will be grouped together and renamed as a matter of convenience Here s the sample code IDENTIFICATION DIVISION program id purchase ENVIRONMENT DIVISION Preparing and Compiling Your COBOL Program m 6 3 input output section file control select p o file assign to disk purchl organization is indexed access mode is dynamic record key is p o number file status is p o status DATA DIVISION file section fd p o file 01 p o record 03 p o division number pic 9 3 03 p o record type pi
338. ored procedures you may want to create It also supplies some example code The Acu4GL for Microsoft SQL Server interface checks for these stored procedures when opening a file and will use them in certain circumstances such as when A_LMSSQL_NO_23_ON_START is set to No These stored procedures are e tablename_insert where tablename is the name of the table being accessed e tablename_delete B 32 m Acu4GL for Microsoft SQL Server Information e tablename_read e tablename_update e tablename_startnnn where nnn is the key number to start on Note The Acu4GL for Microsoft SQL Server interface does not create these stored procedures or check their accuracy It is possible to create stored procedures in such a way as to make the Acu4GL for Microsoft SQL Server product completely inoperable The Acu4GL product uses these stored procedures for performance reasons only Sample XFD Sample code for developer supplied stored procedures is based on the following example of an XFD XFD 03 FIEST2 FILE FTESTDAT ftestdat xfd generated by ACUCOBOL GT v4 2 Alpha 1 8 22 99 Generated Sun Aug 22 07 54 28 1999 00031 00031 003 01 0 004 00000 01 FTEST2 KEY 01 1 004 00004 02 FTEST2 KEY1 SEG1 FTEST2 KEY1 SEG2 01 0 004 00008 01 FTEST2 ALTKEY2 000 0006 00006 00000 00004 16 00004 00 000 000 FTEST2 KEY 00004 00002 16 00002 00 000 000 FTEST2 KEY1 SEG1 00006 00002 16 00002 00 000 000
339. orting programs this option can dramatically improve performance However please note the following restrictions Files must be open INPUT or open IO with MASS UPDATE FAST_ACCESS gives a performance boost only when no locking is required In files that allow locking a record must be reread after being locked this prevents an uninterrupted forward sequential traversal Files opened with FAST_ACCESS use a dedicated connection for reading from the file Since connections are memory intensive both on the client and on the server the number of files opened with FAST_ACCESS should be kept to a minimum In the event that opening a connection fails the file open still continues but FAST_ACCESS mode is disabled with the following message appearing in the trace file FAST_ACCESS mode not available E 32 m Acu4GL for Sybase Information Also a new connection technically uses a new concurrent Sybase license from Sybase Files open with FAST_ACCESS will not participate in transactions and may even cause the runtime to hang if transactions are used especially if the FAST_ACCESS file is updated within the transaction We suggest that if you use transactions you don t use FAST_ACCESS At the minimum if you use transactions we suggest that you use FAST_ACCESS only for files open INPUT Files open with FAST_ACCESS cannot be read backwards In other words READ PREVIOUS does not work with FAST_ACCESS files In fact if you try to REA
340. oss databases RENAME works only within the same database 9D 17 Cache error internal error The internal process cache has been corrupted Please contact Technical Services 9D 18 Primary Key error This means there was an error when creating the primary key for a secondary table 9D 19 Table Size Error The table is larger than Sybase will accept either in the number of columns or in the number of bytes in the row Use the SECONDARY_TABLE directive to get around this E 56 m Acu4GL for Sybase Information 9D 20 no message associated with this error This error tells you that you are trying to do something with a FAST_ACCESS table that is not allowed See A_SYB_FAST_ ACCESS to learn the restrictions for tables opened this way 9D 21 no message associated with this error There was a problem accessing one or more Vision locks files and processing of this request cannot continue The tertiary error is an error code returned from Vision E 9 Common Questions and Answers Question This section contains some questions and answers specific to Acu4GL for Sybase Refer to Chapter 10 for additional questions and answers that pertain to the Acu4GL family of products What files do I need to link my C routines into Acu4GL Relinking is not necessary on Windows platforms To add your own C routines to the runtime relink the runtime as discussed in the runtime manual You do not need to add anything special to use Acu4G
341. ossibly other operations in the database query optimizer become confused For more information about indexes and performance issues see Chapter 9 Performance and Troubleshooting Compiler and Runtime Options Key Topics Compiler Optom os ssie ens cens ses eee assed ancdeasedecpedieatasentieat cs 8 2 Runtime Configuration Variables 0 ccceceseceseeceeeneeseeeeeneceeeeees 8 4 8 2 m Compiler and Runtime Options 8 1 Compiler Options Some file options Fa Fe Fx and F4 are used to generate XFD files data dictionaries that are used with Acu4GL Other file options FI Fs and Ft can simplify the addition of transaction management facilities to existing programs This section describes compiler options that are useful when working with Acu4GL Fa This option tells the compiler to build data dictionaries XFD files for every indexed relative and sequential data file in the FDs of the program It is the only option that builds XFDs for relative and sequential files This option is also used for international character mapping See also the Fo compile time option which specifies the directory in which the data dictionaries are placed The Fa option generates the most current format for the XFD files Version 6 compatible with Acu4GL Version 6 0 and later This option causes the field names in generated XFD files to match exactly the source of the COBOL program that genera
342. ou are accessing existing data in a relational database you need to know how to declare your data so that it will match the database fields If your COBOL code isn t written yet you should follow the guidelines given in the appendix of this manual for your specific RDBMS If your COBOL application already exists you can make necessary adjustments by adding directives to your code Directives are comments that guide the creation of the data dictionaries The dictionaries in turn help map the COBOL fields to their equivalent database fields Directives are described in Chapter 4 Using Directives 7 3 1 How Do Match Existing Text Fields To access character data you simply declare the field as PICTURE X with as many X s as appropriate 7 3 2 How Do Match Existing Numeric Fields Numeric fields are more database specific Most relational database systems accommodate INTEGER DECIMAL and DATE types For information on the handling of other numeric types see the appendix containing information specific to your RDBMS 7 4 New and Existing Databases 7 3 3 Field Names If your COBOL application already exists and if it must access a relational database that already exists you may have to work around differences in the names of the fields as well as naming conventions imposed by the RDBMS For example your program might use the name EMPLOYEE NO while the database uses the name EMP NUMBER for the same item of inform
343. p_AcuInit should reside in the default database for each user if it is not created in the master database See section E 6 2 Built in Stored Procedures for information on the sp_AculInit stored procedure This completes the setup on the UNIX or Windows NT server machine E 20 m Acu4GL for Sybase Information Note If you are upgrading from an earlier version of Acu4GL be sure to install the new stored procedures We always upgrade stored procedures in such a way that they are compatible with older versions of the product so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software Your new version of Acu4GL for Sybase may not run properly without the corresponding stored procedures It can be difficult to maintain multiple copies of stored procedures therefore we recommend that you continue to create the stored procedures in the master or sybsystemprocs database If your installation does not permit this you do have the flexibility to create the stored procedures elsewhere However to facilitate maintenance of the stored procedures we recommend that you create as few databases as possible E 2 4 3 Windows client Installations Complete the following steps to install the Acu4GL product on a Windows client machine Step 1 Choose your communication method Be sure to choose your communication method at the client machine To do this follow the
344. pe of machine you have The media label tells you which format has been used You can start by copying all of the files onto your client machine If you are using a second machine as your server this is optional move the server files identified below to that second machine You will be installing Acu4GL into the same directory where your ACUCOBOL GT runtime is located Change to that directory and type one of the following commands tar xfv device or cpio icvBd lt device This will copy the files from the distribution medium to your directory device is the appropriate hardware device name for example dev rmt0 Sites using Texas Instruments System 1500 should add an uppercase T to the cpio options icvBdT E 2 3 1 UNIX Client Installation Steps Acu4GL communicates with Sybase version 11 0 or later The client your application and the server the RDBMS may be located on the same UNIX machine or on different UNIX machines The server may also be located on a Windows NT machine To install the Acu4GL product first perform the following steps on the UNIX client machine Step 1 Install Sybase client library The Open Client DB Library C from Sybase version 11 0 or later must be installed on the client machine before you install Acu4GL for Sybase Follow the installation instructions in your Sybase documentation E 6 m Acu4GL for Sybase Information Step 2 Create a makefile The script syb_inst is an i
345. peration and passes the results back to the Acu4GL product Forming COBOL records Acu4GL translates the data fields into COBOL records or status codes which are then passed back to the runtime system via the generic file handler All of this communication is automatic and all database queries and translations are performed behind the scenes so that the end user experiences no interruption in program execution 1 14 m Acu4GL Overview 1 5 4 Summary The Acu4GL product ensures that all changes to your database are immediately available to your COBOL program Also it ensures that all data updates introduced by your COBOL program are immediately reflected in the database e The Developer s World COBOL source program ACUCOBOL GT object code lt ACUCOBOL GT compiler ACUCOBOL GT data dictionaries The User s World ACUCOBOL GT runtime system Generic file handler Acu4GL SQL queries and results RDBMS engine a gt Relational databases _ After your ACUCOBOL GT data dictionaries have been generated you can switch to a different RDBMS simply by linking in a different Acu4GL module and setting DEFAULT_HOST to point to the new RDBMS No recompiling is necessary How Acu4GL Works m 1 15 Because Acu4GL accesses the database through its native engine the full relational integrity of the database is maintained The COBOL program need not be concerned about enforcing relat
346. pile time errors and also provides several methods for retrieving runtime errors An explanation and a recommended recovery procedure follow each message E 54 m Acu4GL for Sybase Information Runtime errors have this format 9D xx The 9D indicates a file system error and is reported in your FILE STATUS variable The xx is a secondary error code These are the secondary errors reported directly from Acu4GL 9D 01 Read error on dictionary file An error occurred while reading the XFD file this probably means the XFD is corrupt Recreate the XFD file 9D 02 Corrupt dictionary file The dictionary file for one of your COBOL files is corrupt and cannot be read Recompile with Fx to re create the dictionary See section 8 1 for additional information on compiler options 9D 03 Dictionary xfd file not found The dictionary file for one of your COBOL files cannot be located Be sure you have specified the correct directory via your XFD_PREFIX runtime configuration file variable You may need to recompile with Fx to create the dictionary 9D 04 Too many fields in the key There are more than 16 fields in a key Check your key definitions and restructure the key that is illegal and then recompile with Fx 9D 05 no message associated with this error A date given to the Acu4GL interface is invalid and cannot be converted 9D 06 Mismatched dictionary file The dictionary file xfd for one of your f
347. privileges or special privileges provided by Oracle Version 9i you can t e Delete a table you don t own e Create a table under another user s name Limits and Ranges m C 29 C 8 Limits and Ranges The following limits exist for the Oracle 9i file system Maximum indexed key size 250 bytes Maximum number of fields per key 16 Maximum number of columns 254 Maximum length of a char field 255 Note The limits and ranges differ between releases of Oracle Acu4GL for Oracle supports the following data types COBOL to PIC X PIC X n PIC X n PIC X n PIC 9 n PIC 9 n PIC 9 n V9 m example PIC999V99 Oracle to CHAR CHAR n VARCHAR2 DATE NUMBER n NUMBER n m RAW n example NUMBER 4 3 Oracle CHAR CHAR n VARCHAR RAW n NUMBER n RAW n NUMBER n m m NUMBER 5 2 COBOL PIC X PIC X n PIC X n PIC 9 6 or PIC 9 8 PIC 9 n PIC 9 n m V9 m PIC X n or PIC 9 n PIC9V999 C 30 m Acu4GL for Oracle Information indicates that the VAR_LENGTH directive is required indicates that the BINARY directive is required Internally Acu4GL for Oracle uses VARCHAR to prevent key fields that are all spaces from being converted to null These Oracle data types are not currently supported LONG LONG RAW Other limits described in Appendix B of Book 4 Appendices of the ACUCOBOL GT documentation set apply C 9 Runtime Errors This section lists
348. r inventory dictionaries enter the following xfd directory usr inventory dictionaries Note This configuration variable is ignored if you have specified a search path for XFD files using the XFD_PREFIX configuration variable See also XFD_PREFIX runtime configuration variable which enables you to specify a path to search for XFD files XFD_PREFIX extends the functionality of XFD_DIRECTORY See section 8 1 Compiler Options for information about the Fo option which tells the compiler where to put the dictionaries Unless you have moved the dictionaries you should use the same value in XFD_PREFIX or for XFD_DIRECTORY that you used with the Fo option XFD_MAP XFD_MAP tells the runtime system to associate certain filenames with a particular XFD This enables you to use one XFD for many different files You can use XFD_MAP to add or replace the existing value depending on the setting of the XFD_MAP_RESETS variable The XFD_MAP variable has this syntax XFD_MAP pattern base xfd name 8 18 m Compiler and Runtime Options where pattern consists of any valid filename characters and may include or These two characters have special meanings in the pattern aa matches any number of characters matches a single occurrence of any character For example CUST matches CUST0001 and CUSTOMER does not match CUSTOO1 or CUSTO0001 CUST matches all of the above CUST 1 match
349. r application will require when it reaches a full load both in terms of users and database size Before you choose and install hardware it is best to run a simulation Your hardware vendor or RDBMS vendor can help you to simulate a large number of users on a given platform with a given RDBMS Setting up and running a simulation that includes your own application does cost money But if you are moving into an installation of any size the consequences of not knowing what to expect can be far greater than the cost of the simulation A potentially costly mistake is to test in your office with a small database and a small number of users Databases respond differently to small amounts of data and a small number of users than they do to large amounts of data and a large number of users Functionally the database works differently as the load increases You might think of this adjustment as switching into a different gear Significant changes in the load on your database can lead to large increases in overhead The behaviors and loads you will encounter as the database expands cannot be determined from a linear projection based on the smaller scenario 9 1 2 The WHERE Constraint The Acu4GL WHERE constraint is an external variable that gives the developer some control over the data searches that result from database queries It can help to improve performance in some situations This section describes its purpose and shows how it is implemented
350. r has been set up without a password this variable need not be set There is no default value for this variable If no password is specified none will be used Configuration File Variables m F 23 A_DB2_STRICT_EQUAL When Acu4GL for DB2 executes a START KEY EQUAL keyval the interface generates a SELECT statement to select all rows with a key equal to the key columns in keyval When fetching the data Acu4GL eventually detects that there is no more data If A_DB2_STRICT_EQUAL is set to True at the time the START is executed the interface returns the error END OF FILE error 10 at this point If A_DB2_STRICT_EQUAL is set to False the default Acu4GL for DB2 then generates a new SELECT statement to continue reading records until the end of the file rather than the subset of records represented by keyval and these records may be discarded by the program Note that this is program dependent behavior Setting A_DB2_STRICT_EQUAL to True causes the interface to stop reading records earlier which can make SELECT statements generated by Acu4GL for DB2 more efficient Note the following conditions e A_DB2_STRICT_EQUAL must be set to True when the START is executed e The START must be a KEY EQUAL start e There must be no COMMITs between the START and the end of the file Because DB2 closes all cursors on COMMIT and ROLLBACK according to the ANSI 92 SQL standard the interface must regenerate a SELECT t
351. r systems where the runtime is static The runtime is a shared object on the following systems AIX 5 1 and later HP UX 11 and later and Solaris 7 and later To check look at the contents of the lib subdirectory of your ACUCOBOL GT installation If the files libruncbl so or libruncbl sl reside in that directory the runtime is a shared object on your system Complete steps 2a through 2c below to create a new runtime that includes the Oracle Acu4GL product You may also link your own C routines with the runtime system Installation and Setup m C 11 2a Execute the script The ora_inst script is an interactive shell script that determines which libraries your version of Oracle has and then creates a makefile suitable for linking Acu4GL for Oracle In the instructions below bold italicized text within a message indicates that the script inserts what you had previously typed Execute the shell script ora_inst by typing the following command sh ora_inst Note You may exit the script at any time by pressing the system interrupt key usually CTRL C This is the first message that you see If this script dies with an error like VAL 0 command not found try executing it with a bourne shell as in sh ora_inst If the script does terminate and if re entering the command does not work call Technical Services When the script begins executing the following message is displayed no response is needed
352. r than 7 3 64 bit Microsoft SQL Server NT 2000 and 2005 Versions greater than 6 5 ODBC Specification Versions greater than 3 0 Oracle 9i for UNIX 32 Versions greater than 9i and 64 bit and Windows 10g for UNIX 32 and 64 bit and Windows 1 x 12 5 Versions greater than 11 x The essence of an Acu4GL product is that standard COBOL I O statements are used to access databases Acu4GL handles the translation between standard COBOL and the language that the RDBMS understands There are special instructions and status messages that apply to each individual RDBMS These are included in the appendices of this manual each RDBMS has an appendix dedicated to its own specific information 1 2 Document Overview The Acu4GL User s Guide is organized in the following manner 1 4 m Acu4GL Overview Chapter 1 Acu4GL Overview This chapter offers an overview of this manual an explanation of accessing data an explanation of database concepts and a lesson on how Acu4GL works Chapter 2 Getting Started After pointing you in the right direction for installing and setting up Acu4GL the Getting Started chapter shows you how to use the sql acu program as well as instructs you on using the Acu4GL demo program Technical support information is also found in this chapter Chapter 3 Data Dictionaries Data Dictionaries details all you should know about XFD files which map COBOL records to database fields an
353. r the following command runcbl vv to verify the link This returns version information on all of the products linked into your runtime system Make sure it reports the version of Acu4GL for Sybase Shared libraries If you have relinked the ACUCOBOL GT runtime and receive an error message of this type when you try to execute it Could not load library no such file or directory Can t open shared library this may mean that your operating system is using shared libraries and cannot find them This can occur even if the shared libraries reside in the same directory where you are currently located Different versions of the UNIX operating system resolve this in different ways So it is important that you consult your UNIX documentation to resolve this error Some versions of UNIX require that you set an environment variable that points to shared libraries on your system For example on an IBM RS 6000 running AIX 4 1 the environment variable LIBPATH must point to the directory where the shared libraries are located On HP UX the environment variable that must be set to point to shared libraries is SHLIB_PATH On UNIX SVR4 the environment variable is LD_LIBRARY_PATH Be sure to read the system documentation for your operating system to determine the appropriate way to locate shared libraries Installation and Setup m E 11 E 2 3 2 A second way to resolve this type of error is to link the libraries into the
354. r whether or not setting the USER_PATH variable would be useful in your set up situation For security reasons it is best to set the password variable from your COBOL program by asking the user to enter a password and then executing SET ENVIRONMENT A_ODBC_PASSWD TO user entry You may want to make and use a personalized copy of the configuration file to avoid impacting other users The ACUCOBOL GT documentation describes how to use the A_CONFIG environment variable or the c runtime option to identify a personal configuration file Define any other configuration file variables you require for your unique environment Possible variables define error map file location locking method commit count commit timing and BINARY CHAR type conversion For detailed information on ACUCOBOL GT configuration file variables see section D 5 Configuration File Variables D 2 5 Designating the Host File System Each time the COBOL application creates a new file it needs to know which file system to use The runtime checks the file system to use when the file is opened You provide the name of the file system with one of two runtime configuration file variables The first is DEFAULT_HOST filesystem Acu4GL for ODBC Installation and Setup m D 15 This will designate the file system to be used for newly created files that are not individually assigned For example DEFAULT_HOST ODBC means that all new fil
355. rce name dynamically at run time In your COBOL program you would add code similar to this prior to the statement that opens the file SET ENVIRONMENT A_ODBC_DATASOURCE TO data source name There is no default value for this variable If you do not enter a name ODBC will use the default ODBC driver D 22 m Acu4GL for ODBC Information A_ODBC_ERROR_MAP_FILE Because there are so many drivers available for ODBC you may find that data source error codes don t necessarily map well to COBOL error codes To solve this problem Acu4GL for ODBC allows you to create an error map file to map native database errors to COBOL errors Create this file using the guidelines described on the following page and then use the configuration file variable A_LODBC_ERROR_MAP_ FILE to indicate the name and location of the file you created Example If the file used for mapping is called MAP and this file is located in the directory C ODBC you would specify A_ODBC_ERROR_MAP_FILE c ODBC MAP in the runtime configuration file There is no default value for this variable Guidelines for creating a map file Although you can check your data source documentation for error code information the easiest way to determine what error codes need to be mapped to more appropriate COBOL codes is through trial and error As users use Acu4GL for ODBC they may report receiving error messages that don t make sense based on their situation Rese
356. rces ODBC operates in a way that is similar to Informix ESQL C and Oracle Pro COBOL The main difference is that ODBC offers the advantage of being able to access almost any data source With traditional call level interfaces CLI you are required to learn the Application Programming Interface API for each data source If you want to port an application from one data source to another you must write a complete new access module ODBC was designed expressly to access almost any data source It offers a standard API that can be used to manipulate data in a Microsoft Access database on your PC or connect from your PC to an Oracle database on a UNIX host It can even access files that are not databases such as Btrieve data files and Excel spreadsheets D 1 2 Origins of ODBC ODBC is able to access a wide variety of file systems because it takes advantage of their common properties and common standards ODBC Concepts m D 3 For example most of the popular database systems on the market today bear a strong resemblance to each other both in functionality and in the methods they use to access data This is because the major vendors products are based in whole or in part on the relational database concepts of E F Codd ODBC makes use of these commonalties Shared standards also lend power to ODBC Several groups have been working to set standards in the UNIX environment where much of the database technology originated These g
357. re to indicate to save as file type File Descriptors For this example the FD is as follows animals fd Generated by Acu4GLfd from animals on 2002 11 11 fd animals 01 animals record 03 animals key 05 PHONE pic x 8 03 animals data Creating File Descriptors and SELECT Statements m 6 15 05 PATIENT_ID pic x 5 05 ATYPE pic x 1 05 OWNER pic x 30 05 YEAR pic s9 2 v9 0 05 SEQ NO pic s9 4 v9 0 05 M pic s9 2 v9 0 05 DD pic s9 2 v9 0 05 YYYY pic s9 4 v9 0 F 05 pic s9 5 v9 2 05 DATE PAID pic s9 8 v9 0 Note that in the FD as in the column listing PHONE appears as the first item When acu4glfd determines a unique index it creates a SELECT statement as well By default this SELECT is placed in the same directory as the FD The base name is the same however the SELECT has an extension of sl For this example the SELECT is as follows animals sl Generated by Acu4GLfd from animals on 2002 11 11 select animals assign to disk animals organization is indexed access is dynamic record key is animals key status is animals status Note that the FD generated by acu4glfd uses the name of the table in the fd line See the sample code in step 6 This will be the same name that appears in the assign line in the SELECT statement See step 8 for the sample SELECT statement You can now look at the FD and SELECT to determine if there are
358. re are advantages and disadvantages to each method If you use the A4GL_WHERE_CONSTRAINT variable you should probably set A_MSSQL_USE_DROPDOWN_QUERIES to 0 because the WHERE constraint will limit the result set sufficiently that the larger query will be more efficient See Section 9 1 2 The WHERE Constraint for additional information If you usually START files and read to the end you should set A_MSSQL_USE_DROPDOWN_QUERIES to 0 because a fewer number of queries need to be sent to the database On the other hand if you START Configuration File Variables m B 27 files and stop reading after some condition but haven t used the WHERE constraint you may get more efficient access by setting this variable to 1 and using the drop down style of query In either case we recommend that you run some tests to see which value of this variable makes the most sense for your application This variable is accessed only during a positioning operation so you can set it at different times for different tables While the default value is 0 off false no this configuration variable can also take values of On true yes Example A_MSSQL_USE_DROPDOWN_QUERIES number where number can be a zero or nonzero value A_MSSQL_VISION_LOCKS_FILE This locking method causes the lock table AcuLocks to be a Vision file instead of an SQL table This can be accessed via the configuration variable A_M
359. re no longer active on the system You can call this from sp_Aculnit each time a user connects to the database to ensure that the lock table contains only active locks This stored procedure must reside in the same database as the AcuOpenTables and AcuLocks tables it is placed there automatically when these tables are created during installation E 52 m Acu4GL for Sybase Information sp_AcuTableReport_1 Use this stored procedure to learn who is using the tables in the database at the time this procedure is run Run this procedure before running the sp_AcuZeroUserCount stored procedure so that you can contact users to inform them that the database will be closing This stored procedure must reside in the same database as the AcuOpenTables and AcuLocks tables it is placed there automatically when these tables are created during installation sp_AcuUserCount_ You can run sp_AcuUserCount from the query analyzer or ISQL to learn how many users have a particular table open You can use this to track table and database activity to ensure that your database is running as efficiently as possible This stored procedure must reside in the same database as the AcuOpenTables and AcuLocks tables it is placed there automatically when these tables are created during installation sp_AcuZeroUserCount_1 Use sp_AcuZeroUserCount to remove all locks on a table and close it Be sure to run this stored procedure on all tables in the database if you will be
360. refore the utility may not be able to identify all data types represented in the table Refer to your database driver and ODBC documentation for additional information Creating File Descriptors and SELECT Statements m 6 11 Before starting the acu4glfd utility you must define your table data as an ODBC data source See your ODBC documentation for information about drivers and data sources Note that the examples are based on the following table in Microsoft Access E Microsoft Access animals Table E E File Edit view Insert Format Records Tools Window Help M B SRY Sees ol NUY Ry EEE PATIENT_ID ATYPE PHONE YEAR SEQ_NO MM YYYY _ 00001 0 555 0123 Robert Jones 85 5678 2 2001 __ 100102 D 555 0145 Ellen Smith 94 9012 12 24 2000 100 2212001 _ 100050 B 555 0167 Sam Tucker 95 9876 3 28 2001 465 4012001 _ 100002 c 555 0186 Hartt Knox 98 6185 6 18 1999 67 5 7041999 __ 00801 R 555 0198 Bob Hernandez 99 1234 5 23 2000 67 5 5232000 Note that the phone number PHONE field is the table s key Field Name Data Type PATIENT_ID Text ATYPE Text EH PHONE Text OWNER Text YEAR Number SEQ_NO Number MM Number DD Number YYYY Number FEE Number DATE_PAID Number F General Lookup Field Size 8 Format Input Mask Caption Default Value Validation Rule Validation Text Required No Allow Zero Length No Indexed Yes No Duplicates Unicode Compression No 6 12 Working with COBOL
361. ries DEFAULT_HOST VISION afile_HOST DB2 bfile_HOST DB2 means that all new files except afile and bfile will be assigned to Vision and those two files will be assigned to DB2 You can also change the values of these variables during program execution by including in your code SET ENVIRONMENT filename_HOST TO filesystem or SET ENVIRONMENT DEFAULT_HOST TO filesystem This enables you to change file systems during the execution of your program This is not the typical way to specify a file system normally it is designated in the runtime configuration file and is not changed in the COBOL program Note The Acu4GL for DB2 product allows you to create a DB2 table with an OPEN OUTPUT statement just as you can create Vision indexed files The DB2 equivalent of a Vision file is a table not a database You must create a database for your DB2 tables before you run the COBOL program that creates the tables just as you must create a directory for your files before you run a COBOL program that creates Vision files Filename Translation m F 13 F 2 6 Designating the Host Data Source You must tell the runtime system which data source to use for your DB2 file You accomplish this by setting the configuration variable A_DB2_DATASOURCE You can set this variable in your COBOL configuration file if you will be using only one data source This variable is described in section F 4 Acu4GL for DB2 Configuration File Variables
362. rmix vendor provides installation instructions for the Informix RDBMS Please refer to the file SERVERS _7 2 in the release directory of your Informix distribution for more information about version 7 2 7 3 and above Getting Started with Acu4GL for Informix m A 3 A 1 1 Installation Preparation The Informix Acu4GL product is an add on module that must be linked with the ACUCOBOL GT runtime system Note that your versions of Acu4GL and the runtime must be the same For this reason you ll need a C compiler to install Acu4GL Acu4GL is compatible with Informix versions 5 x1 7 2 7 3 9 and later Note Please make sure that you have obtained the proper Informix libraries for your version of Informix See Section A 1 Getting Started with Acu4GL for Informix for information on these libraries Acu4GL is shipped using either TAR or CPIO format depending on the type of machine you have The label on the product medium tells you which format has been used Create a directory on your machine to hold the product and then type one of the following commands tar xfv device or cpio icvBd lt device In either case device is the appropriate hardware device name for example dev rdiskette or dev rmt0 Note Sites using Texas Instruments System 1500 should add an uppercase T to the cpio options icvBdT A 1 2 Installation Steps To install the Acu4GL for Informix product perform the f
363. roblems can occur To avoid invalid date problems in this instance use the 4GL_MAX_DATE configuration variable to set the high value date The format is 4GL_MAX_DATE YYYYMMDD The maximum date for 4GL_MAX_DATE is 20991231 December 31 2099 See also 4GL_MIN_DATE configuration file variable Configuration File Variables m D 19 AGL_MIN_DATE As noted with the configuration variable 4GL_MAX_DATE invalid dates can be incorrectly written to the database Invalid dates are written as NULL but if the date is in the key problems can occur To avoid invalid date problems in this instance use the 4GL_MIN_DATE configuration variable to set the low value date The format is 4GL_MIN_DATE YYYYMMDD The default date for 4GL_MIN_DATE is 19000101 January 1 1900 See also 4GL_MAX_DATE configuration file variable A_ODBC_ALTERNATE_COMMIT_LOGIC The primary purpose of the configuration variable 4GL_COMMIT_COUNT is to provide for applications that must communicate with a transaction oriented database but have not explicitly coded transactions into their COBOL application The configuration variable A_LODBC_ALTERNATE_COMMIT_LOGIC determines how the interface will respond to the setting of 4GL_COMMIT_COUNT When A_ODBC_ALTERNATE_COMMIT_LOGIC is set to 0 or FALSE the default the value of 4GL_COMMIT_COUNT is checked only at startup The interface will issue a commit when the criteria set by 4
364. rocess a query Note that keys must use the ACUCOBOL GT naming convention for naming indexes in the database to use this function For example the primary key on the file ftest would be named iftest_0 A_ORA_MAX_FILE_CURSORS This configuration variable allows you to set the maximum number of cursors that the runtime is allowed to have per file This is similar to the configuration variable MAX_CURSORS found in Acu4GL for Oracle prior to Version 6 2 0 except that the number is on a per file basis as opposed to the maximum number of cursors available to the runtime in total The default value for A_ORA_MAX_FILE_CURSORS is 0 meaning that the runtime uses all of the cursors that it can Because each file must have access to at least two cursors set this variable to a value greater than 2 if you want to specify a particular value If all the allotted cursors for a file have been used the least recently used cursor for that file is freed Note that this variable is read only at startup time and should therefore be set in the configuration file A_ORA_NLS_SORT This configuration variable forces the sort order of returned records to be in a binary order Set ALORA_NLS_SORT to 1 to turn off the default binary order and use the native language sort instead The default is 0 which means that the sort order will not be the NLS sort order and will instead be binary This variable must be set
365. roduct or create a new directory for it and then enter one of the following commands tar xfv device or cpio icvBd lt device This will copy the files from the distribution medium to your ACUCOBOL GT directory structure device is the appropriate hardware device name for example dev rdiskette or dev rmt0 Sites using Texas Instruments System 1500 should add an uppercase T to the cpio options icvBdT Contents of the medium Note that each Acu4GL product has its own license file which must be located in the same directory as the ACUCOBOL GT runtime For DB2 the license file is distributed with the name runcbl klc F 8 m Acu4GL for DB2 Information Step 1 Install DB2 The DB2 RDBMS version 6 01 must be installed and configured prior to the installation of Acu4GL for DB2 Step 2 Create a new runtime system Complete steps 2a and 2b to create a new runtime that includes the Acu4GL for DB2 product Note In the following directions the term runtime system refers to the runtime shared object on systems where the ACUCOBOL GT runtime is a shared object and to runcbl on other systems where the runtime is static The runtime is a shared object on the following systems AIX 5 1 and later HP UX 11 and later and Solaris 7 and later To check look at the contents of the lib subdirectory of your ACUCOBOL GT installation If the files libruncbl so or libruncbl sl reside in that direc
366. rosoft Text Driver txt csv Visual FoxPro Datahase Microsoft Visual FoxPro Driver lt a An ODBC User data source stores information about how to connect to the indicated data provider A User data source is only visible to you and can only be used on the current machine OK Cancel Apply Help 3 Double click on the data source you plan to use to access a setup dialog A subsequent window lets you add a description of the data source and allows you to supply other information the driver requires If the data source you want is not listed choose Add to indicate which driver to use for the data source you will create Remember the exact steps required for setting up a driver vary greatly between drivers and driver vendors Please refer to the driver s documentation for precise details on this step We recommend that you test the setup of your new data source Many data sources come with a testing utility for this purpose D 14 m Acu4GL for ODBC Information D 2 4 Setting Up the User Environment In addition to setting the variables required for ODBC you will need to do the following 1 Ensure that your execution path contains the name of the directory in which you placed the runtime executable that includes Acu4GL for ODBC Set the A_ODBC_LOGIN and A_ODBC_PASSWD variables either in your environment or in the ACUCOBOL GT runtime configuration file if they are required for your data source Also conside
367. roups include the ANSI standards committee the X Open consortium and the SQL Access Group Together these groups have devised much of the core technology that Microsoft has organized into ODBC D 1 3 Restrictions ODBC does not make your application instantly portable to any database or data source that has ODBC support Many layers of software are involved in the data retrieval process and each layer adds its own restrictions The major component that makes an ODBC connection work is the ODBC driver See section D 1 4 ODBC Structure for more information The driver processes API function calls submits SQL requests to a specific data source or DBMS and returns results ODBC drivers are available from a variety of vendors and offer very different levels of support and performance The sources of the data that the drivers connect to also offer very different capabilities in areas such as record locking file operations and transaction management These differences in performance and capability can have a significant impact on your application D 1 4 ODBC Structure A quick overview of the components of ODBC will help you interface your COBOL program to ODBC compliant data sources D 4 m Acu4GL for ODBC Information ODBC requires four components an ODBC enabled application the ODBC driver manager ODBC database drivers and data sources The following diagram indicates how these components work together in a single tier
368. rrent directory For example to cause the dictionaries to be stored in the directory usr inventory dictionaries you would enter Fo usr inventory dictionaries This option causes an implied START TRANSACTION verb before the first OPEN CLOSE WRITE REWRITE or DELETE and after each COMMIT or ROLLBACK In effect every file operation is part of a transaction If this option is enabled and the compiler encounters a START TRANSACTION verb it reports a warning and does not generate any code for the START TRANSACTION The Fs option provides an alternate way to program transactions and is often useful when you are converting from other COBOL or SQL implementations 8 4 m Compiler and Runtime Options Ft This option causes implied transactions for every OPEN CLOSE WRITE REWRITE or DELETE that is not part of an explicit transaction Single file operations that are not part of a transaction are preceded by an implied START TRANSACTION and followed by an implied COMMIT This option makes converting existing applications to a transaction system easier Note that unlike most COMMITs which unlock all of the file s currently locked records the implied COMMIT does not unlock any records This option directs the compiler to build Version 5 data dictionaries XFD files for every indexed data file in the FDs of the program If you require the older version of XFD files specify the F4 option instead of Fx
369. rs Runtime Errors m A 23 An explanation and a recommended recovery procedure follow each message Runtime errors will have this format 9D xx The 9D indicates a file system error and is reported in your FILE STATUS variable The xx is a secondary or extended error code You can retrieve an extended error code by using selected runtime options or by calling the library routine CSRERR Note that you can pass two parameters to CSRERR for interface errors rather than just one The first parameter retrieves the code the second parameter retrieves a message associated with the error condition This process is explained in detail on the following pages When the extended error code is greater than 99 the error is explained in the Informix documentation Error codes less than 99 are explained here 01 DATABASE is not defined in the environment You must specify which database you are using Use the DATABASE configuration variable 02 Attempt to open more than one database at once This can happen if you specify a database open a file then specify a different database with SET ENVIRONMENT and try to open another file Informix does not allow files to be open from two databases simultaneously 03 Dictionary xfd file not found The dictionary file for one of your COBOL files cannot be located Be sure you have specified the correct directory via your XFD_PREFIX configuration variable You may need to recompile with the Fx
370. rvice Pack 2 and above supports the ACUCOBOL GT Web Runtime For more information regarding the ACUCOBOL GT Web Runtime please consult the Programmer s Guide to the Internet user manual 1 4 Database Concepts Relational databases differ from indexed file systems in several significant ways These are the logical associations between database concepts and COBOL indexed file concepts Indexed File Concept Database Concept Directory Database File Table Record Row Field Column Or put another way e Database operations are performed on columns Indexed file operations are performed on records e A COBOL indexed file is logically represented in database table format Within a table each column represents one COBOL field each row represents one COBOL record e Database table columns are strictly associated with a particular data type such as date integer or character In COBOL data can have multiple type definitions 1 10 m Acu4GL Overview For example for Oracle a COBOL record that looks like this 01 terms record 03 terms code pic 999 03 terms rate pic s9v999 03 terms days pic 9 2 03 terms descript pic x 15 would be represented in the database as a table with a format similar to this Name Null Type TERMS_CODE NOT NULL NUMBER 3 TERMS_RATE NUMBER 4 3 TERMS_DAYS NUMBER 2 TERMS_DESCRIPT CHAR 15 1 5 How Acu4GL Works Acu4GL implements a direct transparent interface between COBOL and
371. ry file The dictionary file xfd for one of your files conflicts with the COBOL description of the file FD The xx indicates a tertiary error code that is defined by the host file system You can determine the exact nature of the mismatch by referring to the host system s error values The tertiary error code may have any of these values 01 mismatch found but exact cause unknown this status is returned by the host file system 02 mismatch found in file s maximum record size 03 mismatch found in file s minimum record size 04 mismatch found in the number of keys in the file 05 mismatch found in primary key description 06 mismatch found in first alternate key description 07 mismatch found in second alternate key description The list continues in this manner for each alternate key 9D 1001 Invalid Cursor The prepare portion is aged out of cache Re enter the code while invalidating the prepare portion C 10 Common Questions and Answers This section contains some questions and answers specific to Acu4GL for Oracle Refer to Chapter 10 for additional questions and answers that pertain to the Acu4GL family of products Question Question Question What files do I need to link my C routines into Acu4GL You need to modify the file makefile ora to add your C routines to the file and then relink your runtime with the command make f makefile ora When I try to open
372. s assign them to an alternate file system with the variable filename_HOST For example to put CUSTFILE into a specified RDBMS and everything else into Vision you would add DEFAULT_HOST Vision CUSTFILE_HOST name_of_file_system where name_of_file_system is one of the following Informix Microsoft SQL Server Oracle ODBC Sybase or DB2 How can I find out what an error message is If you run your application with the x option you will receive extended error numbers that include those returned by your RDBMS or ODBC application Note For Informix two types of errors are returned the Informix error and the ISAM error For Oracle the error code must include five digits If your error code does not already include five digits you must add leading zeros to complete this requirement For example if your error code is code number 150 the syntax for this option would be OERR ORA 00150 10 4 m General Questions and Answers Question Question e6 a If you have sent the errors to an output file with the e option the runtime will also attempt to include the text that explains the errors You can also use the C RERR library routine You can also retrieve error codes from within your COBOL program See the example in section 9 2 3 Retrieving Runtime Errors Do my XFD files have to be in the same directory as my object files No You can instruct the compiler to put the XFD files in an alt
373. s Or XFDS cccccesceeccesceseeesceseeencescecneceeeeeesseesaees 3 2 WADE M E ere eee arene ere 3 2 Understanding How the Database Table Is Formed 06 3 3 Defaults Used in XFD Files cccccccceescesceeseesceeseeneeseeeeecaeeenesseeesees 3 5 Summary of Dictionary Fields 2 00 00 tees ceeeeeeseceececeeeeaeceseeeeeenee 3 7 Identical Field Names cccccesceecceseesecesceeeeeneeseeencesteceecaeeeeesseeeaees 3 8 Long Field Names siiis inssin ieseoi eskici thee edhe essdee bel ieinter es 3 8 Naming the XFD Pile 03 0 5 ccc lean 3 9 3 2 m Data Dictionaries 3 1 Data Dictionaries or XFDs At the heart of the Acu4GL database product are the data dictionaries that map COBOL records to database fields These dictionaries are also called eXtended File Descriptors XFDs because they re based on standard COBOL file descriptors FDs XFDs are used by Acu4GL to interface to database management systems They are also used by the alfred record editor and European character mapping in AcuConnect and AcuServer file server software 3 2 XFD Files The compiler creates an XFD for each indexed file in the compiled program when you specify the Fx compile time option XFDs are fully portable so no recompilation is necessary if you change hardware The compiler option Fa causes the generation of XFDs for indexed relative and sequential files for use with interna
374. s enables you to change file systems during the execution of your program The filesystem value for Informix is Informix The value for Vision is Vision If you change to the Informix file system in the midst of a program be sure to specify the database to be used SET ENVIRONMENT DEFAULT_HOST TO INFORMIX SET ENVIRONMENT DATABASE TO STORES Note that the database cannot be changed if there are tables open in the active database Be sure to close all tables before making a change Remember that SET ENVIRONMENT is not the typical way to specify a file system Normally the file system is designated in the runtime configuration file and is not changed in the COBOL program A 6 Supported Features OPEN ALLOWING READERS is not supported by Informix You determine in your runtime configuration file how this phrase will be interpreted Set the variable STRENGTHEN_LOCKS to 1 one to cause this phrase to be treated as OPEN ALLOWING NO OTHERS Set the variable to 0 zero to cause the phrase to be treated as OPEN ALLOWING ALL The default value is 0 Only single record locking is supported unless the program is within a transaction If you attempt to REWRITE a record that contains a SERIAL data type you will receive an Informix error You might want to change SERIAL fields to SMALLINT as we do for the orders table in the demonstration However you may encounter the situation in which the user has a table
375. s follows 77 SQL COMMAND pic x 75 value SET EXPLAIN ON Informix Performance m A 15 This call instructs the Informix database engine to print out the query optimizer s execution plan to a file in the current directory called sqexpain out Here is a sample of the optimizer s output SELECT rowid FROM idxl WHERE idx_l_key gt ORDER BY idx_l_key ASC Estimated Cost 2 Estimated of Rows Returned 3 Temporary Files Required For Order By 1 informix idxl SEQUENTIAL SCAN Filters informix idxl idx_l_key gt 0000000900 This output shows that the Informix query optimizer is performing a sequential scan on the table for each set of start read operations The optimizer is also making use of a temporary file during processing to sort the information in key order as described by the ORDER BY clause This clause is necessary to ensure that the COBOL application receives the records in the required sequence Problem resolutions To correct the problems with the query optimizer you can take one of several approaches 1 Override the Informix database parameter in the database configuration files 2 Override the new database parameter for a given user session 3 Provide the query optimizer with more information so that it can choose a more efficient method of returning data A 16 m Acu4GL for Informix Information Method 1 Configuration files The Informix database engine reads
376. s in the database table All fields are stored and retrieved from the database whether they appear as explicit columns or not So you don t need to use WHEN unless you want to ensure that some additional fields are explicitly listed by name in the table WHEN declares that the field or subordinate fields if itis a group item that immediately follow the directive must appear as a column or columns in the database table It also states one condition under which the columns are to be used The WHEN directive guarantees that the fields will be explicitly included in the table as long as they aren t FILLER and don t occupy the same area as key fields The WHEN directive results in a table that unites all fields subordinate to the WHEN directive This table might include more columns and could affect performance and storage requirements Syntax SXFD WHEN field value SXFD WHEN field lt value SXFD WHEN field lt value SXFD WHEN field gt value SXFD WHEN field gt value SXFD WHEN field value SXFD WHEN field OTHER oe less than or equals less than ee than or equals unas than not equal to i i i i i or XFD WHEN field value also lt lt gt gt The value may be an explicit data value in quotes The word OTHER can be used only with It means use the following field s only if the WHEN condition s listed at the level of this field are not met Note WHEN values
377. s this syntax XFD_MAP pattern base xfd name where pattern consists of any valid filename characters and may include or These two characters have special meanings in the pattern matches any number of characters y matches a single occurrence of any character 10 6 m General Questions and Answers For example CUST matches CUST0001 and CUSTOMER does not match CUSTO001 or CUSTO0001 CUST matches all of the above CUST 1 matches CUST001 and CUSTO0001 and CUST00001 does not match CUSTOMER OMER matches CUSTOMER does not match CUST001 or CUST0001 The XFD_MAP variable is read during the open file stage of any Acu4GL products linked into the runtime Acu4GL for Informix Information Key Topics Getting Started with Acu4GL for Informix A 2 Filename Translation 0 csesecseseceseeseceeeeceneveeceseneeseneeseeenenesseeeses A 8 Configuration File Variables 0 csesseceseeeseseseeserceeeneeeeeseeneees A 9 Informix Performance 0 cceccesesseseeeeeecsecoteseaeceseeceeenaeeeseeenes A 13 Ae TP esse dacs cass c vss hea eevee sd ong T tests A 18 Supported Features 2 s c6i 4ci tien inieeiidenidnindinis A 19 Limits and Ranges cece eseseeeeseceseeeeesecnecessceaecaseeceeenaeeeeerenes A 21 Rb Ie BGP O IS iioeiaeueiiai A 22 Common Questions and Answers csscccsseesssessscessecssesessecsseeees A 25 A 2 m Acu4GL for Informix Information
378. se use the tools available from Informix A 2 Filename Translation As you prepare to work with Acu4GL for Informix you may find it helpful to understand the rules around filename interpretation and to understand how the names of tables and XFD files are formed and work together When the ACUCOBOL GT compiler generates XFD files it uses lowercase letters to name the XFD file In addition the compiler changes hyphens to underscores when naming the XFD file Through configuration variables the runtime translates the file name in the COBOL program into the filename that is passed to the open function in the runtime The open function determines which file system to pass the request to but does not change the name of the file For additional information on configuration variables see Appendix H in Book 4 Appendices of the ACUCOBOL GT documentation set Configuration File Variables m A 9 At this point Acu4GL for Informix translates the file name to lowercase letters and changes hyphens to underscores This new name is the one that Acu4GL for Informix will use in the future for references to the database table A 3 Configuration File Variables This section lists the runtime configuration file variables that are specific to Acu4GL for Informix Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates are discussed in section 8 2 Runtime Configuration Variables See DEFA
379. se Table cece eeseeseesecseceeesceaeceeeeeeeeneeseeerenee B 28 Table Locking 20 55 56 5 Sa aii ee ede B 28 Stored Procedures ccccscssscceseeseessceseeescesseeeeeeeeeeecaeeseecaesneeeaeenaees B 30 Limits and RANG OS oo eis egi ons esseni siese asni otis arisa oit B 38 RUG Errore ran a i eke B 39 Common Questions and Answers ccscccssessssesssesesecsseeesseesseesees B 42 B 2 m Acu4GL for Microsoft SQL Server Information B 1 Microsoft SQL Server Concepts Overview A quick overview of some basic design concepts underlying the Microsoft SQL Server Database Management System will help you interface your COBOL program to it Servers A Microsoft SQL Server server is one copy of the database engine executing on a computer A server has a name and when a program wants to access the database controlled by a server the program asks for a connection to that server by name Multiple servers can be executing on a single machine controlling different databases The default name that Microsoft SQL Server gives to a server is DSQUERY The naming of servers is discussed in section B 4 Acu4GL for Microsoft SQL Server Configuration File Variables under the configuration variable A_MSSQL_DEFAULT_CONNECTION Table ownership Table names in Microsoft SQL Server have the form database owner table_name Within Microsoft SQL Server if you are the owner of a given table you can refer to it as just table_nam
380. sequencing 7 2 designating for Acu4GL for Informix A 8 existing files 7 2 7 3 field names 7 4 how the table is formed 3 3 installing stored procedures SQL Server B 6 Sybase E 12 E 17 E 19 interacting with COBOL 9 6 matching fields to COBOL 7 2 matching fields to numeric 7 3 matching fields to text 7 3 new files 7 2 relational 1 9 upgrading 9 6 DATE directive 4 9 DATE fields illegal COBOL data in 5 2 dates invalid 4 10 Julian 4 10 DB2 configuration variables A_DB2_ALTERNATE COMMIT_LOGIC D 19 F 15 A_DB2_COMMIT_ON_BEGIN F 16 A_DB2_DATASOURCE F 16 A_DB2_ERROR_MAP_FILE F 17 A_DB2_ISOLATION_LEVEL F 19 A_DB2_LOCK_METHOD F 20 A_DB2_LOGIN F 21 A_DB2_PASSWD F 22 A_DB2_STRICT_EQUAL F 23 A_DB2_USE_CHAR_FOR_BINARY F 25 overview F 14 DB2 configuration variables list of Index 16 A_DB2_USE_CATALOG F 24 DB2 Acu4GL configuration variables F 14 creating map files F 17 data type mapping F 29 designating host data source F 13 designating host file system F 11 installation for UNIX F 7 limits and ranges F 28 linking F 7 linking runtime F 8 mapping DB2 data types to COBOL data types F 29 record locking F 3 runtime errors F 31 setting up the user environment F 10 shared libraries F 9 transactions F 2 troubleshooting F 30 decimal points and Acu4GL for ODBC D 18 decimal points in Acu4GL for DB2 F 14 DECIMAL_ POINT environmental variable D 18 declaring external variables 9 10 default behavior Acu4GL 7 2 DE
381. set it at different times for different tables For example if you have a file with three fields in the primary key keyseg1 keyseg2 keyseg3 and your COBOL program performs a START the following query is sent to the database select columns from table where keysegl valuel and keyseg2 value2 and keyseg3 gt value3 or keysegl valuel and keyseg2 gt value2 or keysegl gt valuel order by keysegl keyseg2 keyseg3 If you use drop down queries the following collection of queries is sent instead select columns from table where keysegl valuel and keyseg2 value2 and keyseg3 gt value3 order by keysegl keyseg2 keyseg3 When that set is finished the interface sends select columns from table where keysegl valuel and keyseg2 gt value2 order by keysegl keyseg2 keyseg3 And when that set is finished the interface sends select columns from table where keysegl gt valuel order by keysegl keyseg2 keyseg3 E 42 m Acu4GL for Sybase Information There are advantages and disadvantages to each method If you use the A4GL_WHERE_CONSTRAINT variable you should probably set A_SYB_USE_DROPDOWN_QUERIES to 0 because the WHERE constraint limits the result set sufficiently that the larger query will be more efficient See Section 9 1 2 The WHERE Constraint for additional information If you usually START files and read to the end you should set A_SYB_USE_DROPDOWN_QUERI
382. ssnctesunsbsberstoceests 4 3 Directives Supported by the Acu4GL Interfaces ccceeees 4 4 4 2 m Using Directives 4 1 What Are Directives ACUCOBOL GT data dictionaries are based on your COBOL FDs For this reason we call them extended FDs or XFDs Each dictionary describes all of the fields for one file Directives are optional comments that you can use in your FDs to control how things look on the database side Many applications won t use directives at all They re most commonly used when a site intends to do a lot of work with the database management system outside of the COBOL application and wants to control how the database table is built Directives are special comments placed into an FD in your COBOL source code They guide the building of the data dictionaries which in turn guide the building of the database table Each directive includes the letters XFD These three letters indicate to the compiler that the comment is to be used in data dictionary generation Directives offer you a great deal of control over how the database table is built Among other things they enable you to e specify a column name to be used in the database table in place of a COBOL field name e map elementary items of a group item together into a single column cause numeric COBOL data to be treated as a text string in the database e cause the fields from a specific record in a file to appear in the database tab
383. sssvees ogsbitebessuptsseesecusess D 30 A ODBC_USE2CA TAL OG arei reei enr heii cesta rE E EEE ta see ete ena tates e D 30 A_ODBC_USE_CHAR_FOR_BINARY ooo cecesseceeceseeseeeeceseeeeeeaeeeaecneesaeaes D 31 A_ODBC_USE_SPACE_IN_DATES crierai iine rine ooet EEren euE Te E Sres D 31 A ODBC USE SQLCOLUMNS erreser pese esr iaeoe enee eiee neret D 32 A ODBC USE SOQLTABLES ae n a E E E ee a D 33 WISER PAT E E E E E dav toe AG iastes cess seawecuptorsoesebaeeeee D 33 D 6 Mixed case SQL Identifiers eeeececcsececsececessececesaecesneceesececsesececeseeceseeeeesaeeeseeees D 35 D 7 Record atid Table Locka mp esse ash sadeeevsdete a tere Meweectss D 35 D 8 Lamuits and Ranges 00 0 3 casei aie tes ithe ee aie eee D 36 D9 Driver Requirement uc1 s5 cc5 cbepsee ck icheases cs cbca bus cad be cadens eo e A aebenionescuncusue ssoebuedecoetes D 36 D 10 Data Type Mapping s seiniin niir aieea r oE a ETE E a E D 38 Delt Troubleshooting ivi evsistoucke coct eek renee e e E E E E E D 42 D11 R ntime Errors iei artien a a a E a ds Seats ea E aE Ea D 42 DAIL Native SOLENO Syrer e rr a hie Seo E E D 44 D 12 Common Questions and ANSWETS csccccessecesscecesseeceseececsececesaecesseceesneeeneseeeeneeees D 45 Appendix E Acu4GL for Sybase Information E l Sybase Concepts Overview sissssssescscksssiesedescscesiessecsvesvsensssugssusbsstonsveespogeseoescvscedssevtssgeedy E 2 E 2 Installation and Setup 0 sirens o n e E E RSE E 3 E 2 1 Sybase R
384. sued for the file determines the effects of this setting Examples If an OPEN INPUT or OPEN I O is issued and a USER_PATH variable is defined in the runtime configuration file Acu4GL searches for a user of the named file in the list of users in USER_PATH The first valid file is opened If USER_ PATH is defined and the current user is the owner of the file the current user must be included as one of the users as indicated by a or the setting of your login schema A_ODBC_LOGIN in the USER_PATH If this is not the case even though the current user has created the table it will D 34 m Acu4GL for ODBC Information not be found and a file error 35 will result This circumstance can occur if the file was created with the OPEN OUTPUT phrase and is not an element in USER_PATH When the table is created the current user will be the owner of that table When the runtime attempts to open the table the runtime will not look for tables owned by the current user unless USER_PATH is not set or unless or the user s current schema is part of the USER_PATH setting If an OPEN INPUT or OPEN I O is issued and no USER_PATH variable is in the runtime configuration file Acu4GL searches for a user of the named file in the user named for login A_ODBC_LOGIN Acu4GL opens the first file that has a valid combination of user and file name If an OPEN OUTPUT is issued whether USER_PATH is present or not a new table
385. sure I m using the correct username and password All usernames passwords and database names are case sensitive Be sure that you are typing the names exactly as they are set up I m using Microsoft Access version 2 0 and I m having trouble accessing writing tables from my ACUCOBOL GT program D 46 m Acu4GL for ODBC Information Answer Question Question Question Question Check the version of the Access driver you are using Microsoft Access version 2 0 requires version 2 0 of the driver If you are using a previous version of the driver the runtime will generate errors To determine the version number of your driver you can run the Acu4GL for ODBC driver test program DRVTST32 EXE 32 bit version I m noticing some performance degradation when accessing my ODBC data source What is the cause of this You may notice some performance impact if you were previously accessing Vision indexed files directly This is because ODBC adds a software layer between your applications and your data sources In return for minor performance impact you can reap the benefits of database independence and enhanced portability Overall performance depends on several factors including your network configuration and your specific data source I wrote data with my Acu4GL for Oracle or Informix product When I try to read it with Acu4GL for ODBC the data is not the same By necessity the BINARY data type is impleme
386. t you must also set a configuration variable that specifies this file as a Vision Record and Table Locking m E 43 file using a _host variable This file must be accessible to all users accessing the Sybase SQL server either through a common directory or through AcuServer Also included with the Acu4GL for Sybase product is a small COBOL program that will manage this Vision file lockmgr This program should be run with the same runtime that you normally use to access Sybase tables and with the same configuration variables set The program detects whether Acu4GL for Sybase is available and detects the A_SYB_VISION_LOCKS_FILE variable to determine which file to manage This program displays all the records in the lockfile and provides options for removing single records by highlighting the desired record to remove or removing all shown records and also for restricting the shown records by PID Table and Database You can refresh the display by clicking the Restrict button and then clicking OK without restricting the display further If everything is working correctly there should be no records in this table when there are no users accessing the Sybase SQL server through Acu4GL The source for this program is in the sample acu4g directory See also Section E 5 Record and Table Locking E 5 Record and Table Locking By default Sybase doesn t support the type of record and table locking that COBOL expects
387. t for Informix should be renamed myprog ilc and the license file for the runtime should be renamed myprog alc The remaining files can be left in the directory in which they were unloaded Step 4 Compile the sample program 1 If you are using the C shell enter the command rehash 2 Now try compiling and running the sample program with the following commands ccbl zd Fx demo cbl runcbl demo acu Note You can also run the sample program using runtime flags if necessary A 8 m Acu4GL for Informix Information A 1 3 Designating a Database Use the configuration variable DEFAULT_HOST to establish Informix as your file system DEFAULT_HOST informix Next select the particular Informix database to be accessed by your COBOL application Identify this database to the runtime system via the DATABASE configuration variable DATABASE database name The database you choose might be one that has been in use at the site for some time and already contains data or it might be a new blank database that has just been created and named Note The Acu4GL product for Informix allows you to create a file with an OPEN OUTPUT statement just as you can create Vision indexed files The Informix equivalent of a Vision file is a table not a database You need to have an existing database for your Informix tables just as you must have an existing directory for Vision files To create a new blank databa
388. t the names of several stored procedures end in _1 indicating the first version of the stored procedure Whenever a stored procedure is updated the extension is updated by one This is why you can install new stored procedures without overwriting older ones Be sure to install all stored procedures when you install Acu4GL for Sybase sp_Aculnit If the stored procedure sp_AculInit exists in the master database it is executed when the connection is made to the server This is a procedure you can set up to perform customized initialization This stored procedure does not take any parameters and does not return any results This optional stored procedure is executed for all connections by the Acu4GL interface to the database not just the primary connection As an example of customized initialization you can use this stored procedure to remove stale locks by calling sp_AcuRemoveUnusedLocks_1 which is installed when all the other Acu4GL stored procedures are installed or to limit access to the database by certain users during certain hours If sp_Aculnit returns an error the connection is denied and the error is reported to the COBOL program The method for returning an error is to execute the Transact SQL statement raiserror See your database documentation for information about Transact SQL and stored procedures sp_AcuRemoveUnusedLocks_1 Use this stored procedure to determine who is logged in and to remove Process IDs that a
389. ta So the Acu4GL for ODBC product will use the Informix INTEGER type instead of the SERIAL type for integer data For another example MS Access maps these types like this SQL_CHAR CHAR SQL_VARCHAR TEXT SQL_DECIMAL no such type SQL_NUMERIC CURRENCY SQL_SMALLINT SHORT SQL_INTEGER LONG or COUNTER SQL_REAL SINGLE SQL_FLOAT no such type SQL_DOUBLE DOUBLE SQL_TINYINT BYTE SQL_BIGINT no such type SQL_BINARY BINARY SQL_VARBINARY VARBINARY SQL_LONGVARBINARY LONGBINARY SQL_DATE no such type SQL_TIMESTAMP DATETIME Access also defines types SQL_BIT BIT and SQL_LONGVARCHAR LONGTEXT which the Acu4GL for ODBC product doesn t use Mapping COBOL data types to ODBC data types When the Acu4GL for ODBC product creates a table it uses what it determines to be the best match of a data type for any particular column This means that the database column will be able to hold any data that the COBOL data type can hold and is as close as possible to the type of data that the COBOL program is using This determination is based in part on what data types the data source has available Obviously if a data source doesn t D 40 m Acu4GL for ODBC Information support some data type the Acu4GL for ODBC product can t use it with that data source The actual algorithm used is rather complicated but the general rules are as follows User preferences take precedence This means that the XFD directives sp
390. ted them This option causes XFD files to be generated in XML format rather than the standard flat text format Acu4GL AcuXDBC and alfred can all read the XFD files in XML format This option must be used in conjunction with the Fx or Fa options The C6XML library routine can be used to parse the XML files if desired In addition by specifying the XSL directive you can specify a stylesheet to be used when compiling This option will not work in combination with F4 Version 4 XFD files cannot be generated in XML format Compiler Options m 8 3 This option enables single locking rules rather than multiple locking rules as the lock mode default Normally WITH ROLLBACK causes multiple locking rules to be in effect for a file When FI is used the WITH ROLLBACK clause does not affect whether single or multiple record locking rules are followed Single locking becomes the default You may enable multiple locking either by specifying WITH LOCK ON MULTIPLE RECORDS in a file s SELECT statement or by using APPLY LOCK HOLDING ON file in the I O CONTROL paragraph This option must be followed as the next separate argument by the directory that will hold the data dictionary files generated by the compiler when you use the Fx option Type a space after the option and then give the name of the chosen directory If this option is not used the data dictionaries are placed into the cu
391. test2_keyl_segl ft2_keyl_segl ftest2_keyl_seg2 ft2_keyl_seg2 ftest2_altkey2 ft2_altkey2 ftest2_number ft2_number ftest2_info ft2_info where ftest2_key ft2_key grant execute on ftestdat_update to public tablename_startnnn tablename_startnnn is used to START a file The nnn value is the key number to start on and will be 0 filled For example the start procedure for the primary key for table mytab will be mytab_start000 Note If A_SYB_NO_23_ON_START is set to Yes the start stored procedure is disabled Because there can be up to 119 alternate keys the Acu4GL product does not search for a start procedure unless or until itis used The parameters passed to the stored procedure are a 2 char mode it is a varchar 2 field with one E 50 m Acu4GL for Sybase Information of the following values gt gt lt or lt The rest of the parameters are the columns of the key used to start Because the ANSI specification for START includes information about the size of the key being used and in particular allows partial keys the start procedure is used only if an entire key is given to the start verb This procedure is also special in that it does not return data but needs to raise an error condition if the start fails The way to raise the error condition from within the stored procedure is to include code similar to the following raiserror 22006 Record not found The code
392. the Acu4GL for Microsoft SQL Server product The extra column will have the identity property and will be included on all indexes that are not unique Otherwise when A_MSSQL_ADD_IDENTITY is set to False false no no extra column is added Note The COBOL FD should not include the identity column Example A_MSSQL_ADD_IDENTITY TRUE On keys that allow duplicates this variable has been found to vastly improve performance Note that the default value is True for a file that allows duplicates and is False for a file with no duplicate keys A_MSSQL_ADD_TIMESTAMP Using a timestamp column is the only way to absolutely ensure that modifications made to a row are not overwriting someone else s changes When it s reading a table that is open for I O the Acu4GL for Microsoft SQL Server product uses BROWSE MODE if a timestamp column exists When the Acu4GL product is creating a table if the value of A_MSSQL_ADD_TIMESTAMP is TRUE a timestamp column is included in the table Note that your COBOL FD should not include the timestamp column While the default value is Off false no this configuration variable can also take values of On true yes B 12 m Acu4GL for Microsoft SQL Server Information Note Microsoft discourages the use of BROWSE MODE on Select statements because of performance reasons Therefore unless it is absolutely necessary we discourage setting this variable to On
393. the fields that make up that record The next two pages show the specific fields that are placed into the table All of the data from the COBOL program is stored in and retrieved from the database even though not all fields are explicitly named in the database table See Chapter 3 Data Dictionaries for a description of how this works The underlined fields are the only ones that will be entered into the table fd p o file 01 p o record 03 p o division number pic 9 3 03 p o record type pic x 88 header record value h 88 detail record value d 03 p o number pic 9 10 03 p o number detail redefines p o number 05 picking ticket number pic 9 6 05 shipping region pic 9 2 05 p o customer type pic 9 2 05 p o customer breakdown redefines p o customer type Preparing and Compiling Your COBOL Program m 6 5 01 07 customer category pie x 88 p o customer retail value r 88 p o customer whlsale value w 07 customer pay format pic x 88 is net 30 value 3 88 is net 10 value 1 03 p o date 05 p o yy pic 9 2 05 p o mm pic 9 2 05 p o dd pic 9 2 p o detail record 03 p o dept number pic 9 3 03 p o record type pic x 03 detail p o number pic 9 10 03 p o shipping info 05 p o quantity to ship pic s9 4 comp 05 p o total quantity pic s9 4 comp 03 p o notes 05 notes line occurs 3 times pic x 40 As the table is built Any hyphens in the COBOL field names are conv
394. they will be compatible with older versions of the product so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software E 6 1 Developer or Site supplied Stored Procedures This section provides information on stored procedures you may want to create It also supplies some example code The Acu4GL for Sybase interface checks for these stored procedures when opening a file and will use them in certain circumstances such as when A_SYB_NO_23_ON_START is set to No These stored procedures are e tablename_insert where tablename is the name of the table being accessed e tablename_delete e tablename_read e tablename_update e tablename_startnnn where nnn is the key number to start on Note The Acu4GL for Sybase product does not create these stored procedures or check their accuracy Thus it is possible to create stored procedures in such a way as to make the Acu4GL for Sybase product completely inoperable The Acu4GL product uses these stored procedures for performance reasons only Stored Procedures m E 47 Sample XFD Sample code for developer supplied stored procedures is based on the following example of an XFD XFD 03 FIEST2 FILE FTESTDAT ftestdat xfd generated by ACUCOBOL GT v4 2 Alpha 1 8 22 99 Generated Sun Aug 22 07 54 28 1999 00031 00031 003 01 0 004 00000 01 FTEST2 KEY 01 1 004 00004 02 FTEST2 K
395. this problem If Sybase increases the maximum number of bytes allowed in a row ina future release of the Sybase product you can increase the value of this variable to take advantage of the new limit The A_LSYB_MAX_ CHARACTERS variable has a default value of 1962 A_SYB_MAX_COLUMNS A_SYB_MAX_COLUMNS indicates the maximum number of columns the Acu4GL product will allow in a table Sybase places a limit on the number of columns per table The Acu4GL product adheres to this limit but sometimes it cannot accurately count how many columns a table contains because a column has been added to a table without the Acu4GL product s knowledge This variable enables the developer to set the Acu4GL product s upper bound You might want to try reducing the upper bound if you discover that a table cannot be created for some reason By reducing the upper bound you allow for uncountable columns and thus may be able to prevent this problem If Sybase increases the maximum number of columns allowed per table in a future release of the Sybase product you can increase the value of this variable to take advantage of the new limit The A_LSYB_ MAX_ COLUMNS variable has a default value of 250 Configuration File Variables m E 35 A_SYB_NATIVE_LOCK_TIMEOUT This is one of two locking methods available with Acu4GL for Sybase The methods are accessed via two configuration variables A_SYB_VISION_LOCKS_FILE and A_SYB_NATIVE_LOCK_TI
396. time errors B 39 security B 3 servers B 2 setting up a user environment B 7 setting up user accounts B 7 stored procedures B 31 table locking B 28 table ownership B 2 troubleshooting B 39 SQL statements building 1 13 sql acu utility introduction 2 3 running from a program 2 4 running from the command line 2 3 Index 38 START TRANSACTION implied 8 3 starting the demonstration program 2 8 statements building SQL 1 13 steps to follow accessing a database 1 13 building SQL statements 1 13 compiling with Fx 1 12 creating dictionaries 1 12 forming COBOL records 1 13 passing I O requests 1 13 setting database specific variables 1 13 setting the files host 1 12 stored procedures B 30 sp_AcuInit E 12 E 17 E 19 storing in alternate database B 6 E 12 E 17 E 19 stored procedures SQL Server creating B 31 sp_Aculnit B 36 sp_AcuRemoveUnusedLocks B 37 sp_AcuTableReport_1 B 37 sp_AcuUserCount_ B 37 sp_AcuZeroUserCount B 38 tablename_delete B 33 tablename_insert B 33 tablename_read B 34 tablename_startnnn B 35 tablename_update B 34 upgrading B 7 B 31 stored procedures Sybase creating E 15 installing E 16 E 19 sp_Aculnit E 51 sp_AcuRemoveUnusedLocks 1 E 51 sp_AcuTableReport_1 E 52 sp_AcuUserCount_l E 52 m Index 39 sp_AcuZeroUserCount E 52 tablename_delete E 48 tablename_insert E 47 tablename_read E 48 tablename_startnnn E 49 tablename_update E 49 upgrading Acu4GL for E 13 E 17 E 20 structure ODBC D 3
397. times takes a long time to execute If you are experiencing such problems you can use the API function call SQLDescribeCol instead which can improve performance for large databases To turn on this new functionality set the ALODBC_USE_SQLCOLUMNS configuration variable to FALSE The default value of this variable is TRUE which means the interface will use the SQLColumns API function Configuration File Variables m D 33 A_ODBC_USE_SQLTABLES For some large databases the API function SQLTables which is called to get a list of the tables and information about them sometimes takes a long time to execute If you are experiencing such problems you can instruct the interface to build a test SQL query and use the API function call SQLNumResultCols to determine if the table exists This may improve performance for large databases To turn on this new functionality set the ALODBC_USE_SQLTABLES configuration variable to FALSE The default value of this variable is TRUE which means the interface will use the SQLTables API function USER_PATH USER_PATH indicates the user name or names schemas to be used when Acu4GL searches for files The order of the names is significant The syntax for this variable is USER_PATH userl user2 where the user argument may be either the name of a user schema on the 6699 system or a period which indicates the files owned by yourself The type of OPEN being is
398. tional character mapping only The compiler option F4 generates version 4 XFD files for backwards compatibility with older versions of the runtime See section 8 1 Compiler Options for additional information ACUCOBOL GT COBOL FDs gt compiler with Fx option _ XFDs See Chapter 5 in Book 1 User s Guide of the ACUCOBOL GT compiler documentation for details on how the XFD files are generated from the COBOL program s FDs Creating XFD files at compile time offers two significant advantages e Any changes made to the file definitions are automatically included in the data dictionaries when the program is recompiled XFD Files m 3 3 e The effects of all compile time options COPY REPLACING source code control lines and data layout compiler flags d are reflected correctly in the XFDs 3 2 1 Understanding How the Database Table Is Formed ACUCOBOL GT data dictionaries XFDs enable the Acu4GL product to create a table or access an existing one in the database for each indexed file Each column in the table contains the values for one field The column names are essentially the field names The table that is built is based on the largest record in the COBOL file and contains the fields from that record plus any key fields key fields are those that are named in KEY IS phrases of SELECT verbs in the FILE CONTROL section This ensures that data from all of the COBOL records wi
399. tionaries is discussed in section 3 2 XFD Files The next section describes how and when these data dictionaries are built 1 12 m Acu4GL Overview 1 5 3 Steps to Follow The Acu4GL product builds its own database queries dynamically whenever an input or output request is received These are the steps that you take to compile your program and execute it using Acu4GL Compiling with Fx You compile your standard COBOL application with ACUCOBOL GT See the appendix specific to your RDBMS for details to determine which version of the compiler is required When you compile you specify via a compile time option that you want the compiler to generate data dictionaries in addition to an object code file Creating dictionaries An ACUCOBOL GT data dictionary is created by the compiler for each indexed file in your program These data dictionaries map COBOL records in an indexed file to rows in a database Like ACUCOBOL GT object files these data dictionaries are portable across platforms Setting the files host In your configuration file you may specify which RDBMS or ISAM file system you are using by setting the DEFAULT_HOST variable sets a default for all files or the filename_HOST variable sets a file system for individual files or both For example you might say DEFAULT_HOST VISION and EMPFILE_ HOST ORACLE This would direct EMPFILE input and output functions to the Oracle RDBMS via Acu4GL and direct I O for
400. tive allows you to treat a data item as alphanumeric text in the database when it is declared as numeric in the COBOL program Syntax SXFD ALPHA or XFD ALPHA This is especially useful when you have numeric keys in which you occasionally store non numeric data such as LOW VALUES or special codes In this situation treating the field as alphanumeric allows you to move any kind of data to it Example Suppose you have specified KEY IS code key Then assume the following record definition 01 code record 03 code key 05 code num pic 9 5 In the database group items are disregarded so CODE NUM is the actual key field Suppose you needed to move a non numeric value to the key MOVE C0531 TO CODE KEY WRITE CODE RECORD In this case the results are not well defined because a non numeric value has been moved into a numeric field The database might very well reject the record One way to solve this problem is to use the ALPHA directive This causes the corresponding database field to accept alphanumeric data 01 code record 03 code key SXFD ALPHA 05 code num pic 9 5 4 6 m Using Directives As an alternative you could specify the USE GROUP directive on the line before code key The USE GROUP directive implies that the field is alphanumeric 4 3 2 BINARY The BINARY directive is used to specify that the data in the field could be alphanumeric data of any classification Absolutely any data is
401. to be found and accessed F 10 Common Questions and Answers Question This section contains some questions and answers specific to Acu4GL for DB2 Refer to Chapter 10 for additional questions and answers that pertain to the Acu4GL family of products I m noticing some performance degradation when accessing my DB2 data source What is the cause of this You may notice some performance impact if you were previously accessing Vision indexed files directly This is because DB2 adds a software layer between your applications and your data sources In return for minor performance impact you can reap the benefits of database independence and enhanced portability Overall performance depends on several factors including your network configuration and your specific data source Common Questions and Answers m F 33 Question Are there any ACUCOBOL GT library routines that do not work with or would not make sense to use with Acu4GL for DB2 Answer Yes The C COPY and CSRENAME ACUCOBOL GT library routines do not work with DB2 F 34 m Acu4GL for DB2 Information Glossary of Terms ANSI American National Standards Institute American National Standards Institute ANSI along with the International Organization for Standards ISO standardized the C programming language and continues to promote many other important software standards API Application Programming Interface Application Programming Interface The interfac
402. to use the A_CONFIG environment variable or the c runtime option to identify a personal configuration file a Installation and Setup m C 17 If you will be accessing files that you do not personally own and that do not have public synonyms you will need to set the configuration variable USER_PATH For detailed information on ORA_LOGIN ORA_PASSWD and USER_PATH see section C 4 Acu4GL for Oracle Configuration File Variables in this appendix C 2 7 Designating the Host File System If you are opening an existing file all file systems linked into the runtime are searched for the named file If however you are creating a new file you must tell the runtime which file system to use You accomplish this with one of two configuration file variables the first is DEFAULT_HOST filesystem This designates the file system to be used for newly created files that are not individually assigned For example DEFAULT_HOST ORACLE means that all new files will be Oracle files unless otherwise specified by the second configuration variable which is filename_HOST filesystem where filename is the file name without any extension named in the ASSIGN TO clause of your SELECT statement This configuration variable is used to assign an individual data file to a file system Any file so assigned will use the designated file system and not the one specified by DEFAULT_HOST For example myfile_HOST VISION means t
403. tory the runtime is a shared object on your system 2a Link the runtime system Edit the Makefile in the lib subdirectory Change the CFLAGS file to read as follows CFLAGS ACUSERVER_FLAGS ACUCONNECT_FLAGS ACUSQL_FLAGS DACU4GL DUSE_DB2 Note Be sure to include the first word CFLAGS Edit the FSI_SUBS line to read as follows FSI_SUBS a4db2 0 Edit the FSI_LIBS line to read as follows FSI_LIBS ACU_LIBDIR libexpat a lt ibm DB2 directory gt lib libdb2 so Make sure you are in the directory containing the ACUCOBOL GT runtime system Then at the UNIX prompt enter the following command make Installation and Setup m F 9 This compiles sub c and filetbl c and then links the runtime system Note Make sure you have set all of the flags specific to your platform correctly before you relink your library and object files If the make fails because of an out of date symbol table execute the following command ranlib a and then execute the make again If the make fails for any other reason call Technical Services 2b Verify the link Enter the following command cuncbhl vv to verify the link This returns version information on all of the products linked into your runtime system Make sure it reports the version of Acu4GL for DB2 Shared libraries If you have relinked the ACUCOBOL GT runtime and receive an error message of this type when
404. tory in which the shared libraries are located On HP UX the environment variable that must be set to point to shared libraries is SHLIB_PATH On UNIX SVR4 the environment variable is LD_LIBRARY_PATH Getting Started with Acu4GL for Informix m A 7 Be sure to read the system documentation for your operating system to determine the appropriate way to locate shared libraries A second way to resolve this type of error is to link the libraries into the runtime with a static link Different versions of the C development system use different flags to accomplish this link Please consult the documentation for your C compiler to determine the correct flag for your environment Step 3 Copy runcbl to the correct directory If the runtime is a statically linked runcbl copy the new executable to a directory mentioned in your execution path This file needs to have execute permission for everyone who will be using the compiler or runtime This step is not necessary when the runtime system is a shared library The ACUCOBOL GT license file for the runtime runcbl alc and the license file for the Acu4GL product to Informix runcbl ilc must be copied into the same directory as the runtime executable If you rename your runtime executable be sure to rename your license files to use the same base name with the extensions unchanged For example if you rename your runtime to be myprog then the license file for the Acu4GL produc
405. u need not change the field names in your COBOL program to access a database Instead you use the NAME directive to provide unique database names for the fields For example 01 employee record 03 date hired 05 yy pic 99 05 mm pic 99 05 dd pic 99 03 date last paid xfd name year paid 05 yy pic 99 Sxfd name month paid 05 mm pic 99 Sxfd name day paid 05 dd pic 99 The dates portion of the resulting database table will look like this year_paid month_paid day_paid 88 02 15 94 04 30 Example 2 names not unique within first 18 characters or longer than 18 characters Some SQL based databases require that names be unique within 18 characters and some require that names be no longer than 18 characters For those systems the Acu4GL runtime will automatically truncate longer COBOL names after the first 18 characters Directives Supported by the Acu4GL Interfaces m 4 15 For names that are identical within the first 18 characters or are not meaningful if shortened to the first 18 characters use the NAME directive to assign them different database field names Suppose you had 01 acme employee record 03 acme employee record date hired pic x 6 03 acme employee record date last paid pic x 6 You could add two NAME directives to differentiate the two item names by making them meaningful within 18 characters 01 acme employee record Sxfd name date hired 03 acme employee record date hire
406. u4GL product Copy MS_INST CMD to your server machine into a directory of your choice Step 3 Execute the batch file To execute the batch file enter MS_INST LockDatabase where LockDatabase is the database you want to use for the internal ACUCOBOL GT lock tables If this database does not already exist it will be created Everyone who will use the Acu4GL for Microsoft SQL Server product must have write access to this database This step creates MS_INST SQL the collection of stored procedures necessary for executing Acu4GL for SQL Server Step 4 Install the ACUCOBOL GT stored procedures To install the ACUCOBOL GT stored procedures in your Microsoft SQL database execute the generated MS_INST SQL file with the SQL Query Analyzer or the SQL Server Management Studio if you are using Microsoft SQL Server 2005 By default the stored procedures are installed into the master database However you may choose another database in which to store them This completes the setup on the Windows NT server machine Installation and Setup m B 7 Note If you are upgrading from an earlier version of Acu4GL be sure to install the new stored procedures Micro Focus always upgrades stored procedures in such a way that they are compatible with older versions of the product so installing new stored procedures over old ones does not affect your ability to run with an older version of the interface software Your new version of Acu4GL for M
407. ue yes Example A_SYB_ADD_TIMESTAMP 1 See also BROWSE MODE in the Sybase Commands Reference Manual A_SYB_CHECK_DELETE_SP This configuration variable controls whether the Acu4GL for Sybase interface checks for the tablename_delete stored procedure when opening a table If A SYB_CHECK_DELETE SP is set to False no off 0 the Acu4GL interface does not check for the stored procedure Therefore even if tablename_delete exists it is not used if A_SYB_ CHECK_DELETE_SP is set to False The default is True yes on 1 to check for the stored procedure A_SYB_CHECK_INSERT_SP This configuration variable controls whether the Acu4GL for Sybase interface checks for the tablename_insert stored procedure when opening a table If A_SYB_CHECK_INSERT_SP is set to False no off 0 the Acu4GL interface does not check for the stored procedure Therefore even if tablename_insertt exists it is not used if A_SYB_CHECK_INSERT_SP is set to False The default is True yes on 1 to check for the stored procedure A_SYB_CHECK_READ_SP This configuration variable controls whether the Acu4GL for Sybase interface checks for the tablename_read stored procedure when opening a table If A_LSYB CHECK _READ_SP is set to False no off 0 the Configuration File Variables m E 27 Acu4GL interface does not check for the stored procedure Therefore even if tablename_read exists it is not used if A_SYB_C
408. uired for your data source are set To run the demo program you ll need to notify the ACUCOBOL GT runtime system that you will be interfacing to an RDBMS driver You accomplish this by adding the following line to your runtime configuration file or to the machine s environment DEFAULT_HOST RDBMS_NAME If you re running demo cbl from the same directory where you placed the ACUCOBOL GT data dictionary you are ready to run If the data dictionary acuorders xfd created when you compiled the demo program is in another directory you will need to add the following line to the cblconfig configuration file XFD_PREFIX dir containing dictionary Set any environment variables required for your specific Acu4GL product See the Designating the Host Data Source or Designating the Host File System section in the appendix specific to your particular RDBMS At this point you can run the demo program by entering one of the following commands For ACUCOBOL GT Version 5 0 or later 32 bit Windows runtime wrun32 c config demo For ACUCOBOL GT Version 5 0 or later UNIX runtime runcbl c config demo The Demonstration Program m 2 9 For UNIX versions you will see a character version of the following screen For Window based versions this is what you ll see EO ioxi Record Position Options Help Order 0001 CEDEGE 21209 Customer t PO Ship Weight TE Ship Date O Ship Charge
409. umentation What does the number mean The errors fall into three categories 01 99 are Acu4GL codes and are described in section A 8 of this manual A 28 m Acu4GL for Informix Information Question Question 100 199 are ISAM errors and are explained in Informix manuals 200 and up are Informix database errors and are explained in Informix manuals Can the Acu4GL for Informix product support a full date time format The finest time granularity that Informix will support is one hundredths of a second To achieve this you must be sure the code is correct in the DATE directive and specify a date format string in your COBOL application as opposed to just a date See section 4 3 5 DATE for additional information Are there any ACUCOBOL GT library routines that do not work with or would not make sense to use with Acu4GL for Informix Yes There are two ACUCOBOL GT library routines that either don t work with or do not make sense to use with Acu4GL for Informix C COPY and C RECOVER Acu4GL for Microsoft SQL Server Information Key Topics Microsoft SQL Server Concepts Overview B 2 Installation and Setup 0 ce eeeecsecseeseeseceececeecsaecesseceeeseeseeseenecneeaees B 4 Filename Translation cceccesceecceseeesceeceeeeeeceeeeceeeseecsecseeeeeeaees B 10 Configuration File Variables c cccsccsceeseceeeeeeceeeeseeeeeeteeneees B 11 Using the Databa
410. upport different types The types that Acu4GL for ODBC uses if they exist in the driver are SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ L L S K Ty L Hi Hi L ar TI BIGINT _BI VA LO _DATE TI L_CHAR L_VARCHAR L_DECIMAL L_NUMERIC _ SMALLINT L_INTEGER L_REAL L_FLOAT _DO UBLE YINT ARY RBINARY GVARBINARY ESTAMP For example Informix maps these types like this SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ SQ L_CHAR CHAR L_VARCHAR VARCHAR L_DECIMAL DECIMAL or MONEY L_NUMERIC no such type L_SMALLINT SMALLINT L_INTEGER INTEGER or SERIAL L_REAL REAL L_FLOAT no such type L_DOUBLE FLOAT L_TINYINT no such type L_BIGINT no such type L_BINARY no such type L_VARBINARY no such type L_LONGVARBINARY BYTE L_DATE DATE L_TIMESTAMP DATETIME YEAR TO FRACTION 5 Data Type Mapping m D 39 Informix also defines a type that ODBC calls SQL_LONGVARCHAR and Informix calls TEXT which the Acu4GL for ODBC product doesn t use Notice that Informix has two types that match the ODBC SQL_DECIMAL type and two that match the SQL_INTEGER type The Acu4GL product will usually use the first type that it finds that matches an ODBC type unless there are restrictions on that type For example the SERIAL type is limited in that a table can have only one such column while a typical table may have more than one column of integer da
411. uration variable AGL_JULIAN_BASE_DATE This variable sets the base date to be used for Julian date calculations It is used in conjunction with the DATE directive To define your own base date for Julian dates set this variable to a date having the format YYYYMMDD The default value is set internally at 01 01 4713 BC Dates other than the default must be greater than 01 02 4713 BC For example suppose your COBOL program uses dates in the form of the number of days since 12 31 1899 If you want to store these dates in a database accessed by Acu4GL you can set your DATE directives to be 8 12 m Compiler and Runtime Options XFD DATE JJJJJJ make sure that the number of characters matches your date field Then you should set the runtime configuration variable 4GL_JULIAN_BASE_DATE to 18991231 If you are using the runtime intrinsic functions that work with Julian dates you should set the 4GL_JULIAN_BASE_DATE variable to December 31 1600 using the Gregorian calendar AGL_USEDIR_LEVEL This variable provides a method of mapping filenames with directory information to table names 4GL_USEDIR_LEVEL allows you to use files of the same name which would normally go into separate directories as separate names in a single database This variable determines how many levels of directory information to use as part of the table name e If set to the default value of 0 all directory information is removed from the f
412. use the runtime is tracking data altering operations Oracle Concepts Overview m C 5 rather than logical record locks The disadvantage of this method is that when a COMMIT is issued any record locks held by the runtime are released COMMIT_COUNT 1 No commit is issued by the Acu4GL product When COMMIT_COUNT is set to 1 two alternate ways to perform a commit or rollback are available 1 Call sql acu with COMMIT WORK or ROLLBACK WORK 2 Use the COBOL verbs COMMIT and ROLLBACK available in ACUCOBOL GT COMMIT_COUNT is set to 1 automatically when you use the transaction management facilities available in the ACUCOBOL GT compiler A COMMIT WORK is however issued on exit from the runtime for example on execution of a STOP RUN COMMIT Verb in COBOL This method forces a COMMIT to be sent to Oracle It can be used in conjunction with other modes of COMMIT handling For non ORACLE files this is equivalent to the UNLOCK ALL verb Explicitly Coded Transactions This method provides the greatest flexibility in that transactions are specifically tailored for the user s application This method also requires the most work for traditional COBOL programs in which transaction modules may not be clearly defined Acu4AGL for Oracle The Oracle system parameter open_cursors should be set to enhance communication with Acu4GL See section C 2 4 Checking System Parameters for more information C 6 m Acu4GL
413. ver through Acu4GL The source for this program is in the sample acu4gl directory See also A_MSSQL_NATIVE_LOCK_TIMEOUT configuration file variable Section B 6 Table Locking B 5 Using the Database Table The database table is built and accessed automatically when the COBOL application is executed To the end user the interaction between the COBOL and the Microsoft SQL Server database is invisible queries are generated and data is exchanged in fractions of a second and the application proceeds without interruption You can also access the database information directly from Microsoft SQL Server at your option B 6 Table Locking By default Microsoft SQL Server doesn t support the type of record and table locking that COBOL expects For this reason the Acu4GL for Microsoft SQL Server product implements its own locking method This is accomplished with the addition of two tables to a database You choose which database will hold these tables during installation of the Acu4GL for Microsoft SQL Server product Table Locking m B 29 Before using the locking tables you must execute the included ms_inst sql script See the installation instructions you used from this manual for the exact procedure They can be located in the table of contents If you don t perform this step the first time you try to execute a COBOL program that opens a Microsoft SQL Server table you will receive error 9D 11 ACUCOBOL Lock T
414. x SXFD USE GROUP or XFD USE GROUP By default the USE GROUP directive implies that the consolidated field is alphanumeric If you want a numeric field simply add the word NUMERIC at the end of the directive Directives Supported by the Acu4GL Interfaces m 4 19 Example 1 combining DATE and USE GROUP directives For example the directive in the following code combines the functions of the USE GROUP and DATE directives and indicates that the date should be entered into the database as a single date formatted data item instead of three distinct fields XFD USE GROUP DATE 03 date entered 05 yy pic 99 05 mm pic 99 05 dd pic 99 Either a comma or a space or both may separate the word DATE from the words USE GROUP Example 2 forming larger units Other fields with which you might use this directive include multi part account numbers or department numbers or keys that are referenced as a unit but not by their individual pieces Here s an example of an item that might be grouped Sxfd use group 01 gl acct no 03 main acct pic 9 4 03 sub acct pic 9 3 03 dept no pic 9 3 If you are using an existing database in which certain fields are grouped they must also be grouped in your COBOL FD If the database does not yet exist keep in mind that combining fields into groups can improve execution speed Whether to group fields or not also depends on whether they are always stored
415. xecute on ftestdat_update to public Stored Procedures m B 35 tablename_startnnn tablename_startnnn is used to START a file The nnn value is the key number to start on and will be 0 filled For example the start procedure for the primary key for table mytab will be mytab_start000 Note If A MSSQL_NO_23_ON_START is set to Yes the start stored procedure is disabled Because there can be up to 119 alternate keys the Acu4GL product does not search for a start procedure unless or until itis used The parameters passed to the stored procedure are a 2 char mode it is a varchar 2 field with one of the following values gt gt lt or lt The rest of the parameters are the columns of the key used to start Because the ANSI specification for START includes information about the size of the key being used and in particular allows partial keys the start procedure is used only if an entire key is given to the start verb This procedure is also special in that it does not return data but needs to raise an error condition if the start fails The way to raise the error condition from within the stored procedure is to include code similar to the following raiserror 22006 Record not found The code 22006 is very important It is the code searched for in setting the error condition from within the Acu4GL product If you use a different number your starts may succeed when the
416. y 32 bit Windows platform from Microsoft The following diagrams show the supported machine configurations Windows machine Windows NT machine Your application ACUCOBOL GT lt gt Microsoft SQL Server Acu4GL Note that the client machine may be the same machine as the server Installation instructions for each of these configurations are given in the next section The instructions describe the steps you must follow on both the client machine and the server machine CD ROM installation Instructions for installing your Acu4GL product from the ACUCOBOL GT CD ROM are contained on the Quick Start card that accompanied the product Please refer to it for installing your extend products Once the installation is complete please return to this appendix for setting up your Acu4GL product Installation steps on a Windows NT server Complete the following steps to install the Acu4GL product on a Windows NT server machine B 6 m Acu4GL for Microsoft SQL Server Information Step 1 Install SQL Server Microsoft SQL Server version 6 5 or later must be installed and configured on the Windows NT server machine before you install Acu4GL for Microsoft SQL Server on the client machine Follow the instructions from your RDBMS vendor Step 2 Copy the batch file MS_INST CMD is a batch file from ACUCOBOL GT that creates the MS_INST SQL file which is the collection of stored procedures necessary for executing the Ac
417. y placing special comment lines in the FDs of your COBOL code These comments are called directives and are described in Chapter 4 Using Directives For example the WHEN directive allows you to use multiple definitions for a single set of data by specifying when each definition should be used Databases generally do not support the notion of multiple definitions for the same column As the following paragraphs explain whenever a COBOL program gives more than one definition for the same data the compiler makes a choice about which definition to use in the dictionary Then it disregards the rest KEY IS phrase Fields named in KEY IS phrases of SELECT statements are included as column names Other fields that occupy the same areas as the key fields by either explicit or implicit redefinition are not included by name but are mapped to the key field column names by the data dictionary Remember if the field named in the KEY IS phrase is a group item it will not become a column in the database table unless a USE GROUP directive is used see section 3 2 1 Understanding How the Database Table Is Formed Instead the subordinate fields of the group item will be used REDEFINES clause Fields contained in a redefining item occupy the same positions as the fields being redefined The compiler needs to select only one of the field definitions to use The default rule that it follows is to use the fields in the item being redefined
418. y should actually fail For example based on the sample XFD you might want to create the following stored procedure to start a file create procedure ftestdat_start001 mode varchar 2 ft2_keyl_segl char 2 ft2_keyl_seg2 char 2 as if exists select 1 from ftestdat where ftest2_keyl_segl ft2_keyl_segl and mode gt and ftest2_keyl_seg2 gt ft2_keyl_seg2 or mode gt and ftest2_keyl_seg2 gt ft2_keyl_seg2 or mode and ftest2_keyl_seg2 ft2_keyl_seg2 or B 36 m Acu4GL for Microsoft SQL Server Information mode lt and ftest2_keyl_seg2 lt ft2_keyl_seg2 or mode lt and ftest2_keyl_seg2 lt ft2_keyl_seg2 return if exists select 1 from ftestdat where mode gt or mode gt and ftest2_keyl_segl gt ft2_keyl_segl or mode lt or mode lt and ftest2_keyl_segl lt ft2_keyl_seg1 return raiserror 22006 Record not found grant execute on ftestdat_start001 to public B 7 2 Built in Stored Procedures Several stored procedures come with Acu4GL for SQL Server One sp_AculInit provides a means for customized initialization The others return information based on the AcuOpenTables and AcuLocks tables Note You will see that the names of several stored procedures end in _1 indicating the first version of the stored procedure Whenever a stored procedure is updated the extensi
419. you try to execute it Could not load library no such file or directory Can t open shared library this may mean that your operating system is using shared libraries and cannot find them This can occur even if the shared libraries reside in the same directory in which you are currently located Set the environment variable LD_LIBRARY_PATH to find these shared libraries F 10 m Acu4GL for DB2 Information F 2 3 Sample Configuration File The cblconfi db2 file is a sample configuration file This file demonstrates setting the DEFAULT_HOST to DB2 designating an ERROR_MAP_FILE used to map DB2 s errors into COBOL errors and setting the configuration variables required for the Acu4GL for DB2 interface Modify cblconfi db2 to configure your individual login password and database or database alias These configuration variables are A_DB2_LOGIN A_DB2_PASSWD A_DB2_DATASOURCE The sample error mapping file is placed in the etc subdirectory of your Acu4GL for DB2 distribution See section F 5 Configuration File Variables for additional information Note Be sure to set the PATH to find ERROR_MAP_ FILE F 2 4 Setting Up the User Environment You must use the sample configuration file described in section F 2 3 and error map file as your template These files contain important settings for DB2 e A_DB2_USE_CHAR FOR BINARY e error mappings In addition to setting the variables requir
420. ystems linked into the runtime will be searched for the named file If however you are creating a new file you must tell the runtime which file system to use You accomplish this with one of two runtime configuration file variables the first is DEFAULT_HOST filesystem This designates the file system to be used for newly created files that are not individually assigned For example DEFAULT_HOST SYBASE means that all new files will be Sybase files unless otherwise specified by the second configuration variable which is filename_HOST filesystem Installation and Setup m E 23 where filename is the file name without any extension named in the ASSIGN TO clause of your SELECT statement This configuration variable is used to assign an individual data file to a file system Any file so assigned uses the designated file system and not the one specified by DEFAULT_HOST For example myfile_HOST VISION means that myfile will be under the Vision file system You can use these runtime configuration file variables in combination to assign your new files in a default with exceptions manner for example this set of entries DEFAULT_HOST VISION afile_HOST SYBASE bfile_HOST SYBASE means that all new files except afile and bfile will be assigned to Vision and those two files will be assigned to Sybase You can also change the values of these variables during program execution by including in your code SET ENVIRO

Acu4GL User`s Guide v8.1 - Micro Focus Supportline

Contents

Download Pdf Manuals

Related Search

Related Contents