Home

DCI USER'S GUIDE

Contents

1. 6 7 6 8 Copyright 1995 2012 CASEMaker Inc iii Al User s Guide 7 lv DCI 7 1 DCI ATTRS _ TABLE 6 8 DCI _MAX_BUFFER_LENGTH nn 6 9 DEMAS DATE decadas 6 10 DEE MIN DATE cutis 6 10 NULL ON ILLEGAL DATE 6 10 6 11 DCI STORAGE _CONVENTION sisi 6 11 IGI EEVEL iia 6 12 DCE USER PAT Assassin trt edes 6 13 DCLXPD PATH el reido 6 14 DGE XML XPD 6 14 ent RULES M neue 6 15 DCI TABLE CACHE Variables 2 2 2 2 000000000000000000001 6 15 DELATA BLES PA CE dd lacada 6 16 DCI_AUTOMATIC_SCHEMA_ADIJUST sine 6 16 DELANCEUDE 6 17 DCI IGNORE BUFFER LENGTH eee 6 17 DGI NULL DATE 0500 ro reiten 6 17 DCI NULL MIN DATE ns 6 17 6 18 DEL ani S 6 18 DCI GRANT ON OUTTUT iii 6 18 7 1 Calling DCI functions 7 2 DOIL SETENV NETT 7 2 DCI GETENV sii 7 2 ip MUI BN Ur d tr 7 2 DCI GBET LABLE NAME nettement 7 3 DETSEL TABLE CACHE 7 3 DCL BLOD ERROR iip ane e add Mad RINT HOME E 7 4 DEL BLOB GET 7 4 DEL PUT annees 7 DCI GET TABLE SERIAL 7 7 Copyright 1995 2012 CASEMak
2. a 01 PAYROLL RECORD 05 EMP SALARY Pu SNO a 05 DD S S 05 MM 2 CS PICIE In this case the data dictionary is created from the largest file The record EMPLOYEE RECORD contains 33 characters while the record PAYROLL RECORD contains only 16 In this case records are sequentially entered into the database The record EMPLOYEE RECORD is used to create the schema for the table column size and data type EMP ID INT 6 NAME CHAR 17 EMP PHONE DEC 10 Figure 3 4 Preceding Example Table Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 Fields from the following record are written into the columns according to the character positions of the fields The result is that no discrete columns exist for the smaller records The data can be retrieved from the database by the COBOL application because the XFD file contains a map for the fields but there are no columns in the table representing those fields In the previous example when adding the first record to the database there is a correlation between the columns and the COBOL fields When adding the second record there is no such correlation The data occupies its corresponding character position according to the field So the first five characters of EMP SALARY occupy the ID column the last five characters of SALARY occupy the EMP NAME column The fields DD and MM and YY are also located within the NAME column
3. 90 5 Os CZ SOY working storage section Copyright 1995 2012 CASEMaker Inc 3 25 Al User s Guide 3 26 Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 Copyright 1995 2012 CASEMaker Inc 3 27 Al User s Guide 3 9 Using Synonyms DCI allows the use of DBMaker synonyms instead of a table or view Users can create the synonym on a table view or remote database s table or view If the synonym for the view is not a single table view the user can only OPEN INPUT with that synonym 3 28 Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 3 10 Open Tables in Remote Databases Users can access the remote database s table or view by adding a special token E in the COBOL SELECT statement For example SELECT tb1 ASSIGN TO RANDOM 1 1 11 To use a different user name and password set DD DDBMD 1 in the dmconfig ini and create a remote database link 2 Example Connecting to database dci_db1 and accessing a table in database db2 1 Sec DD DDBMD 1I in dmconfig ini 2 Create the table in dci db2 NOTE Use dmSQL tool to create the tables in the dci db2 database 3 Use a COBOL program to connect to dci dbl and then open the table in dci db2 dmconfig ini DCI DB1 DB SVADR 127 0 0 1 DB PTNUM 22999 DD DDBMD DCI DB2 DB SVADR 127 0 0 1 DB PTNUM 23000 DD DDBMD 1 Use dmSQL tool to create the tab
4. Copyright 1995 2012 CASEMaker Inc 7 3 Al User s Guide DCI_BLOB_ERROR This function gets the error after calling DCI_BLOB_GET or DCI_BLOB_PUT gt Example working storage section 77 BLOB ERROR ERRNO 59 4 5 BLOB ERROR INT ERRNO pic 59 4 5 PROCEDURE DIVISION CALL DCI BLOB ERROR USING BLOB ERROR ERRNO BLOB ERROR INT ERRNO DISPLAY BLOB ERROR ERRNO BLOB ERROR ERRNO DISPLAY BLOB ERROR INT ERRNO BLOB ERROR INT ERRNO DCI BLOB GET This function enables users to more effectively use BLOB data in a COBOL program By using the BLOB GET command you can quickly and efficiently access BLOB data using COBOL When using the BLOB GET command you must follow the rules listed below user s table must have a BLOB long varchar long varbinary data type Users cannot set the field with BLOB type in the COBOL FD Users can only use the GET command after the READ READ NEXT or READ PREVIOUS command gt Example user creates a table by CREATE TABLE BLOBTB SB CODCLI char 8 SB PROG SERIAL IL BLOB LONG VARBINARY PRIMARY KEY sb codcli LOCK MODE ROW NOCACHE Copyright 1995 2012 CASEMaker Inc DCI Functions 7 The following gives a practical application of the use of the DCI_BLOB_GET in the COBOL program Copyright 1995 2012 CASEMaker Inc 7 5 Al User s Guide close blobtb ACCEPT OMITTED st
5. N OPEN I O with a valid user file DCI LOGIN name will be opened OPEN OUTPUT Yes or no Doesn t search for new table will a user be made for the name associated with DCI LOGIN Figure 6 1 Types of OPEN Statements Copyright 1995 2012 CASEMaker Inc 6 13 Al User s Guide 6 14 DCI_XFDPATH DCI is used to specify the name of the directory where data dictionaries are stored The default value is the current directory Example 1 Include the following entry in the configuration file in order to store data dictionaries in the directory usr dbmaker dictionaries DCI XFDPATH usr dbmaker dictionaries Example 2 If it is necessary to specify more than one path different directories have to be separated by spaces DCI XFDPATH usr dbmaker dictionaries usr dbmaker dictionariesl Example 3 In a WIN 32 environment embedded spaces can be specified using double quotes DCI XFDPATH c tmp xfdlist c Way folder with space Wfdlist DCI XML XFD This variable is set to 1 to indicate the DCI runtime need to use the ACUCOBOL XML format XFD file The default is 0 for user are using old xfd format which is made by previous ACUCOBOL compiler or when ACUCOBOL user compile their COBOL program with Fx3 option Because ACUCOBOL GT compiler does not support some XFD syntax like the XFD COMMENT directive syntax in the XML format it is not recommended for users to use the XML format if th
6. gt DBMaker D 2 ali CASEMaker CASEMaker Inc Corporate Headquarters 1680 Civic Center Drive Santa Clara CA 95050 U S A www casemaker com www casemaker com support Copyright 1995 2012 by CASEMaker Inc Document No 645049 235145 DBM53 M12302012 DCIU Publication Date 2012 12 30 Al rights reserved No part of this manual may be reproduced stored in a retrieval system or transmitted any form without the prior written permission of the manufacturer For a description of updated functions that do not appear in this manual read the file named README TXT after installing the CASEMaker DBMaker software Trademarks CASEMaker the CASEMaker logo and DBMaker are registered trademarks of CASEMaker Inc Microsoft MS DOS Windows and Windows NT are registered trademarks of Microsoft Corp UNIX is a registered trademark of The Open Group ANSI is a registered trademark of American National Standards Institute Inc Other product names mentioned herein may be trademarks of their respective holders and are mentioned only form information purposes SQL is an industry language and is not the property of any company or group of companies or of any organization or group of organizations Notices The software described in this manual is covered by the license agreement supplied with the software Contact your dealer for warranty details Your dealer makes no representations or warranties with respect to the
7. EY IS IDX 3 KI ED 3 18 Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 Copyright 1995 2012 CASEMaker Inc 3 19 Al User s Guide To read table idx 1 in these databases by file prefix 3 20 Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 Copyright 1995 2012 CASEMaker Inc 3 21 Al User s Guide 3 7 2 2 2 Using Triggers COBOL Triggers are a very useful and powerful feature of DCI COBOL triggers can automatically execute predefined COBOL programs in response to specific I O events regardless of which user or application program generated them COBOL triggers can Implement business rules Create an audit trail for COBOL activities Derive additional values from existing data Replicate data across multiple files Perform security authorization procedures Control data integrity Define unconventional integrity constraints The following XFD directives to define a COBOL trigger specifying the COBOL program name to be called when an I O event occurs Syntax SXFD DCI COMMENT COBTRIGGER cobolpgmname Example 1 The cobolpgmname is case sensitive and looks in the CODE PREFIX directory or current running directory The I O events may be READ any WRITE REWRITE DELETE and OPEN The COBOL trigger performs BEFORE and AFTER I O events except for OPEN that performs BEFORE I O events xfd dci comment cobtrigger c
8. 2 3 b The original filetbl c contains the entry E a 2 c The original filetbl c contains the entry a 2 2 3 Edit the ACUCOBOL GT runtime configuration file sub85 c It is in the same directory as the ACUCOBOL GT libraries The original sub85 c contains the entry Add a new entry as follows Copyright 1995 2012 CASEMaker Inc 2 7 Al User s Guide extern int extern int extern int DCI G DCI BLO DCI BLO ET B PU GI TABLI ERIAL VALUI teen dme struct PROCTABLI E XFD VEAR LIBTABLI W F SYSTEM DCI SETENV DCI GETENV DCI DISCONNECT ET ET pT pm T Li call system DCI SETENV DCI GETENV DCI DISCONNECT ET pump ET m DCI GET TABI ET pm amp Li E E DCI GET TABLE NAM LI Li DCI SET TABI DCI BLOB DCI BLOB DCI DCI GET TI RROR D BG TABLI qu amp BL y F S E CAC F E HE DCI SET TABLE CACHE DCI BLOB ERROR DCI BLOB PUT DCI BLOB GET ERIAL VALUE DCI Gl m ET TABLI ERIAL VAL
9. gt Example 2 The following example illustrates this Given the following input to the COBOL application ENTER EMPLOYEE ID NUMBER 1 99999 ENTER 0 TO STOP ENTRY 51100 LAVERNE HENDERSON 2221212999 5000000000 DI 04 00 The fields have been merged and split according to the character positions of the fields relative to the table s schema Furthermore the data type of the column NAME is CHAR Because DCI has access to the data dictionary all fields will be mapped back to the COBOL application in the correct positions This is a very important fact by default the fields of the largest record are used to create the schema of the table therefore table schema must be carefully considered when creating file descriptors To take advantage of the flexibility of SOL data types are consistent between fields for different records that will occupy the same character Copyright 1995 2012 CASEMaker Inc 3 11 Al User s Guide positions If a PIC X field is written to a DECIMAL type database column the database will return an error to the application gt Example 3 An SQL select on the first record of all columns in EMP_NAME would display the following 51100 LAVERNE HENDERSON 2221212999 gt Example 4 An SQL select on the second record of all columns in EMP_NAME would display the following 500000 0000010400 3 12 Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 3 4 Using XFD File
10. A COBOL FD structure using the When directive with two table names FILE SECTION SXFD FILE INV FD INVOICE SXFD WHEN INV TYPE A TABLENAME INV TOP 01 INV RECORD TOP 03 INV KEY 05 INV TYPE ITE 05 INV NUMBER PICS 05 INV ID PIE OS 03 INV CUSTOMER IPC 30 o SXFD WHEN INV TYPE B TABLENAME INV DETAILS 01 INV RECORD DETAILS 03 INV KEY D 05 INV TYPE D ec 05 INV NUMBER D IC 909 o 05 INV ID B BIC 999 03 INV ARTICLES PI 30 lt 03 BIC MS o 03 INV PRICE Em SLT e 2 Example 2 The DCI interface makes two tables named inv top and inv details based on the value of the inv type fields in example 1 DCI checks the value of the inv type field to know where to fill the record MAKE TOP ROW MOVE A TO INV TYPE Copyright 1995 2012 CASEMaker Inc XFD Directives 4 MOVE 1 TO INV NUMBER MOVE 0 TO INV ID JOVE acme company TO INV CUSTOMER RITE INV RECORD TOP MAKE DETAIL ROWS MOVE B TO INV TYPE OVE 1 TO INV NUMBER MOVE 0 TO INV ID MOVE floppy disk TO INV ARTICLES MOVE 10 TO INV QTA MOVE 123 TO INV PRICE WRITE INV RECORD DETAILS Running the preceding code DCI fills the TOP ROW record in the INV TOP table and DETAIL ROW in the INV DETAILS table When DCI reads the above record it can use sequential reading or use the key to access filled records If you plan to use sequential reading through record types
11. User s Guide DCI_MAPPING This variable is used to associate particular filenames with a specific XFD in the DCI system In this way one XFD can be used in conjunction with multiple files A pattern can be made up of any valid filename characters It may include the wildcard symbol which stands for any number of characters or the question mark which stands for a single occurrence of any one character and can be used multiple times Syntax DCI MAPPING pattern base xfd name Example 1 The pattern CUST 1 and base XFD name CUSTOMER will cause filenames such as CUST01 CUST001 CUST0001 and CUST00001 to be associated with the XFD customer XFD DCI MAPPING CUST 1 CUSTOMER ORD ORDER ord cli ordcli Example 2 The pattern CUST and base XFD name CUST will cause filenames such as CUSTOMER and CUST0001 to be associated with the XFD cust XFD DCI MAPPING CUST CUST DCI MAX ATTRS PER TABLE A DBMaker table may have up to 2000 columns A COBOL file with more than 2000 fields will not be able to map all fields to columns in the table DCI provides the DCI MAX ATTRS PER TABLE configuration variable to define the number of fields at which the table will split into two or more distinct tables The resulting tables must have unique names so DCI appends the table name with an underscore character followed by letters in consecutive order
12. 2 17 PASSWD a 2 17 DCOCILI XFDPA TH 2 17 Runsql Utility 2 19 Invalid Data BEB RRR 2 20 Copyright 1995 2012 CASEMaker Inc i Al User s Guide 2 7 Sample Application 2 22 Setting up tbe Application 2 22 a AA 2 25 Accessing Data Ri 2 26 Data Dictionaries 3 1 3 1 Assigning Table Names 3 2 3 2 Mapping Columns and Records 3 G Identical Field Names 9 20 0 000000 60 3 8 Lone Field NAMES T tt 3 9 3 3 Using Multiple Record Formats 3 10 3 4 Using XFD File 3 13 REDEFINES Clauses Re 3 13 KEY IS Phrase viii 3 13 FILLER Data ems omita 3 14 OCCURS Clausen 3 14 3 5 Mapping Multiple Files 3 16 3 6 Mapping to Multiple Databases 3 18 3 7 Using Triggers 3 22 3 8 Using 929 3 9 Using Synonyms 3 28 3 10 Open Tables in Remote Databases 3 29 3 11 Using DCI WHERE CONSTRAINT 3 32 XFD Directives 4 1 4 1 Using Directive S
13. LOGIN allows specification of a username for connecting to the database system It has no default value Therefore if no username is specified no login will be used Copyright 1995 2012 CASEMaker Inc Configuration File Variables 6 The username specified by the LOGIN variable should have RESOURCE authority or higher with the database Additionally the user should have permission with existing data tables New users may be created using the JDBA Tool or dmSQL NOTE For more detailed information on creating new users refer to the JDBA Tool Users Guide or the Database Administrator s Guide Example sample username entry JOHNDOE made in the Config cfg file DCI LOGIN JOHNDOE DCI JULIAN BASE DATE This variable used with the DATE directive sets the base date for Julian date calculations It utilizes the format YYYYMMDD The default value for this variable is January 1 1 AD One usage of this variable could be a COBOL program that uses dates from 1850 onwards These dates can be stored in a database by setting the DATE directive to XFD DATE JJJJJJ the date field must have the same number of characters and setting the DCI configuration variable JULIAN BASE DATE to 18500101 DCI LOGTRACE This variable sets different levels for the trace log 0 no trace l connect trace 2 record i o trace 3 full trace 4 internal debug trace Copyright 1995 2012 CASEMaker Inc 6 7 Al
14. ad hoc data queries can use Copyright 1995 2012 CASEMaker Inc 2 3 Al User s Guide either of DBMaker s SQL interfaces dmSQL or JDBA Tool The ACUCOBOL GT compiler creates data dictionaries which are discussed in Chapter 3 Data Dictionaries ACUCOBOL Application Program Interface User Generic File Handler Data Dictionaries DBMaker Client Process DBMaker Storage Figure 2 3 Data Flowchart 2 4 Copyright 1995 2012 CASEMaker Inc DCI Basics 2 2 2 System Requirements DCI for DBMaker is an add on module that must be linked with the ACUCOBOL GT runtime system For this reason a C compiler is required to install the DCI product To interface the ACUCOBOL GT Version 4 3 or later compiler and runtime is required The README TXT file located in the DCI directory lists files that ship with the product DCI supports the following platforms SCO OpenServer Sun Solaris x86 Windows 9x ME NT 2000 XP Linux 2 2 2 3 AIX HP UX FreeBSD 4 DCI requires the following software DBMaker version 5 2 or greater ACUCOBOL GT runtime version 4 3 or greater C compiler for the local machine e g Visual C Version 6 0 for a Windows platform Copyright 1995 2012 CASEMaker Inc 2 5 Al User s Guide 2 3 Setup Instructions Install and configure the most recent version of DBMaker before configuring DCI
15. except that positive COMP 3 items use as the positive sign value instead of x0C This option is compatible with NCR COBOL DCA Selects the ACUCOBOL GT storage convention It is the default setting This convention is also compatible with data produced by RM COBOL not RM COBOL 85 and previous versions of ACUCOBOL GT DCI USEDIR LEVEL If this variable is set gt 0 use the directory in addition to the name of the table Example 1 The following line is equal to usr test 01 clients Olclients DCI USEDIR LEVEL 1 2 Example 2 The following line is equal to usr test 01 clients testO 1 clients DCI USEDIR LEVEL 2 Copyright 1995 2012 CASEMaker Inc Configuration File Variables 6 2 Example 3 The following line is equal to usr test 01 clients usrtestO 1 clients DCI USEDIR LEVEL 3 USER PATH When DCI looks for a file or files the variable USER PATH allows for specification of a username or names The user argument can be a period with regard to the files or the name of a user on the system gt Syntax DOTEUSERTPATH The type of OPEN statement issued for a file will determine the results of this setting OPEN DCI USER PATH DCI RESULT STATEMENT SEARCH SEQUENCE OPEN INPUT or Yes 1 list of users in The first valid file OPEN I O USER PATH 2 the current user will be opened OPEN INPUT or The user associated The first file with
16. merchantability or fitness of this computer product for any particular purpose Your dealer is not responsible for any damage caused to this computer product by external forces including sudden shock excess heat cold ot humidity nor for any loss or damage caused by incorrect voltage or incompatible hardware and or software Information in this manual has been carefully checked for reliability however no responsibility is assumed for inaccuracies This manual is subject to change without notice Contents Contents 1 4 1 1 1 1 2 1 3 Additional Resources 1 3 Technical Support 1 4 Document 4 1 5 2 DCI Basics 2 1 2 1 2 2 2 3 2 4 2 5 2 6 Overview 2 2 File System and Databases quidera fe 2 2 ACCESS tlie ind pr e e retro ORI Rocio 2 3 System 2 5 Setup Instructions 2 6 Windows Setup ud li 2 6 DNS D nee nes ape nel 2 11 Shared Libraries 2 14 Basic Configuration 2 16 DCL DATABASE aene eres ott 2 16 DECLLOGIN A A A aie
17. not the appended index numbers The final name however including the index number is limited to the 32 characters For example if the field name is Employee statistics 01 it truncates to Employee statis 01 It is important to ensure that field names are unique and meaningful within the first 18 characters NAME can be used to rename a field with a long name but within the COBOL application you must continue using the original name The NAME directive affects only the corresponding column name in the database Copyright 1995 2012 CASEMaker Inc 3 9 Al User s Guide 3 3 3 10 Using Multiple Record Formats The example in the previous section showed how fields are used to create a database table However the example only shows the case of an application with one record A multiple record format is stored differently from a single record format COBOL programs with multiple records map all records from the master largest record in the file and any key fields in the file Smaller records map to the database table by the XFD file but do not appear as discrete defined columns in the table they occupy new records in the existing columns of the database gt Example 1 Take the previous example but modify the file descriptor to include several records DATA DIVISION FILE SECTION FD HR FILE LABEL RECORDS ARE STANDARD 01 EMPLOYEE RECORD 05 EMP ID So o 05 EMP NAME CS o 05 EMP PHONE
18. table called username customer The ACUCOBOL GT compiler always creates a file name in lowercase The username default is determined by the LOGIN value in the CONFIG file or can be changed with the USER PATH configuration variable SELECT FILENAME ASSIGN TO CUSTOMER 2 Example 3 gt If the file has a file extension DCI replaces characters with DCI will open a DBMaker table named username customer_ dat SELECT FILENAME ASSIGN TO customer dat 2 Example 4 DCI MAPPING can be used to make the dictionary customer xfd available Since DCI uses the base name to look for the XFD dictionary in this case it looks for an XFD file named customer dat xfd The following setting is based on an XFD file named customer xfd DCI MAPPING customer customer COBOL applications may use the same base file name in different directories For example a COBOL application opens a file named customer in different directories such as usr file customer and usr1 file customer To make the file names unique we would include directory paths in the file names A way to do this is to change the CONFIG variable DCI_USEDIR_ LEVEL to 2 DCI will then open a table as follows COBOL RDBMS XFD FILENAME lusr file customer usrfilecustomer usrfilecustomer xfd usr1 file customer usr filecustomer usr 1 filecustomer xfd Figure 3 1 Sample USEDIR LEVEL to 2
19. Defaults In many cases directives can override the default behavior of DCI Please refer to XFD Directives for more information The compiler uses special methods to deal with the following COBOL elements REDEFINES Clause KEYIS phrase FILLER data items OCCURS Clauses REDEFINES Clause A REDEFINES clause creates multiple definitions for the same field DBMaker supports a single data definition per column Therefore a redefined field occupies the same position in the table as the original field By default the data dictionary uses the field definition of the subordinate field to define the column data type Multiple record definitions are essentially redefines of the entire record area Please refer to the previous section for details on multiple record definitions Group items are not included in the data dictionary s definition of the resultant table s schema Instead the individual fields within the group item are used to generate the schema Grouped fields may be combined using the USE GROUP directive KEY IS Phrase The KEY IS phrase in the input output section of a COBOL program defines a field or group of fields as a unique index for all records The data dictionary maps fields included in the KEY IS phrase to primary keys in the database If the field named in the KEY IS phrase is a group item the subordinate fields of the group item become the primary key columns of the table Use the USE GROUP directive to
20. Fx to dictionary file The a COBOL file is re create the dictionary dictionary file cannot be corrupt file read 9D 03 dictionary file xfd The dictionary file for Specify a correct has not been found a COBOL file cannot directory in the be found DCI XFDPATH configuration file variable it may be necessary to recompile using Fx 9D 04 There are too many There are more Check key definitions fields in the key than16 fields in a key re structure illegal key recompile with Fx 1111 11 9D 12 There is an unexpected A DBMaker library error on a DBMaker function returned an library function unexpected error 9D 13 The size of the xxx An elementary data variable is illegal item in an FD is larger than 255 bytes 9D 13 The type of data for There is no DBMaker the xxx variable is type that matches the illegal data type used 9D 14 There is more than one More than one table table with the same had the same name name when they were listed Figure 8 5 DCI Secondary Errors Chart 8 8 Copyright 1995 2012 CASEMaker Inc COBOL Conversions 8 8 5 Troubleshooting Native SQL Errors Some native SOL errors may be generated by a database while using DCI for DBMaker The exact error number and wording may vary from database to database Copyright 1995 2012 CASEMaker Inc 8 9 Al User s Guide 9D Invalid column A column was named using Compare a file trace of 6523
21. XFD differs from the table schema This variable is incompatible with the split tables those with a Copyright 1995 2012 CASEMaker Inc Configuration File Variables 6 number of columns 2000 and those who s record size is greater than 32 KB exclude the BLOB field The possible values of this variable are 0 Default does nothing 1 Add the new fields to the table and drop the ones who are not in the XFD 2 Add the new fields to the table but do not drop the ones who are not in the XFD DCI INCLUDE This variable permits the inclusion an additional CONFIG file It works as the COBOL COPY statement and allows you to define more complex configurations 2 Example DCI INCLUDE etc generic dci config DCI IGNORE MAX BUFFER LENGTH This variable is used to ignore the setting of DCI LENGTH value It will not split the table when the record length 32k The default is off DCI NULL DATE When DCI writes a date field with this value it will write NULL and when DCI reads date with a NULL value it will return NULL DATE to a COBOL program DCI NULL ON MIN DATE With this variable set to 1 the following action occurs When a COBOL program writes a value of 0 to a DATE field the value is stored in the database as NULL Likewise when a NULL value is read from the database the COBOL FD will be 0 Copyright 1995 2012 CASEMaker Inc 6 17 Al User s Guide DCI_DB_MAP This
22. collect all Copyright 1995 2012 CASEMaker Inc 3 13 Al User s Guide subordinate fields into one field Please see XFD USE GROUP Directive in Chapter for more details FILLER Data Items FILLER data items are placeholders in a COBOL file descriptor They do not have unique names and cannot be uniquely referenced The data dictionary maps all other named fields as if the fillers existed in terms of character position but does not create a distinct field for the FILLER data item If a FILLER must be included in the table schema it can be combined with other fields using the USE GROUP directive see XFD USE GROUP Directive in Chapter 4 or the NAME directive see XFD NAME Directive in Chapter 4 OCCURS Clauses The OCCURS clause allows a field to be defined as many times as necessary DCI must assign a unique name for each database column but multiple fields defined with an OCCURS clause will all have identical names To avoid this problem a sequential index number is appended to the field specified in the OCCURS clause Example 1 The following file descriptor part 03 EMPLOYEE RECORD OCCURS 20 TIMES UD 95 5 gt Example 2 generates the following column names for the database EMP ID 1 EMP ID 2 EMP ID 5 EMP ID 6 Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 Copyright 1995 2012 CASEMaker Inc 3 15 Al User s Guide 3 5 Ma
23. configuration file DCI PASSWD SUPERVISOR Example 2 password can also be accepted from a user upon execution of the program This allows for greater reliability To do this the PASSWD variable must be set according to the response ACCEPT RESPONSE NO ECHO CALL DCI SETENV USING DCI PASSWD RESPONSE In this case however you should furnish a native API to call in order to read and write environment variables Syntax 1 This statement can be used in the COBOL program to write or update the environment variable CALL DCI SETENV USING environment variable value Syntax 2 This statement can be used in the COBOL program to read the environment variable CALL DCI GETENV USING environment variable value DCI STORAGE CONVENTION This variable sets the COBOL storage convention There are four value types currently supported by DBMaker Copyright 1995 2012 CASEMaker Inc 6 11 Al User s Guide DCI Selects the IBM storage convention It is compatible with IBM COBOL as well as with several other COBOL versions including RM COBOL 85 It is also compatible with the X Open COBOL standard DCM Selects the Micro Focus storage convention It is compatible with Micro Focus COBOL when the Micro Focus ASCII sign storage option is used this is the Micro Focus default DCN Causes a different numeric format to be used The format is the same as the one used when the DCI option is used
24. larger than 20 or whatever value you give to this variable making them part of the 20 Century A COBOL date like 99 10 10 will be translated into 1999 10 10 A COBOL date like 00 02 12 will be translated into 2000 02 12 Copyright 1995 2012 CASEMaker Inc Configuration File Variables 6 DCI DEFAULT RULES Default management methods for the WHEN directive located in multi definition files The BEFORE statement indicates that a table be open when the WHEN condition is matched The POST statement indicates that all related tables be open when the COBOL application opens multi definition files The possible values are POST or COBOL BEFORE or DBMS DCI DEFAULT TABLESPACE This variable is used to set the default tablespace where new tables are to be stored The tablespace specified must already exist in the database If no tablespace is specified by this variable then new tables will be created in the default user tablespace DCI DUPLICATE CONNECTION DCI DUPLICATE CONNECTION is used to acquire a lock when opening the same table and locking the same record two times in the same COBOL application by opening the same table using the same COBOL process but with a different database connection The default value is off 0 2 Example To allow a COBOL application to acquire a lock on a table using different database connections DCI DUPLICATION CONNECTION 1 GET EDGE DATES DCI SET EDGE DATE is used to sp
25. or the content in the dmconfig ini file Figure 1 1 Document Conventions Table Copyright 1995 2012 CASEMaker Inc 1 5 Al User s Guide 1 6 Copyright 1995 2012 CASEMaker Inc DCI Basics 2 2 DCI Basics This chapter provides essential DCI environment set up and configuration information for DBMaker Also included is information about using the demonstration program to show you the basic functions of DCI The following topics are covered in this chapter Software and hardware requirements Step by step setup for UNIX and Windows platforms Options for configuring DCI for DBMaker DCI demonstration program instructions Copyright 1995 2012 CASEMaker Inc 2 1 Al User s Guide 2 1 DCI Overview Although traditional COBOL file systems and databases both contain data they differ significantly Databases are generally more robust and reliable than traditional file systems Furthermore they act as efficient systems for data recovery from software or hardware crashes In addition to ensure data integrity DBMaker RDBMS provides support for referential actions and domain column and table constraints File System and Databases There are parallels between database data storage and COBOL indexed files The following table shows each system s data structures and how they correspond COBOL INDEXED FILE SYSTEM DATABASE OBJECT OBJECT Directory Database 000 Reod Row F
26. section Wil CO STATS 77 SERIAL NUM pic S9 9 COMP 5 procedure division main open i o serialtb move AAAAAAAA TO SB CODCLI move 0 TO SB PROG WRITE SB RECORD CALL DCI GET TABLE SERIAL VALUE USING SERIAL NUM DISPLAY SERIAL NUM SERIAL NUM DCI FREE XFD This function is used to purge the XFD image DCI keeps in cache This can be useful to reload a XFD that changed after a table has already been opened by this connection CALL DCI FREE XFD DCI UNLOAD CONFIG This function is used to unload the current configuration Then you can create a new configuration by calling SETENV Very useful in ThinClient environment call DCI UNLOAD CONFIG 7 8 Copyright 1995 2012 CASEMaker Inc COBOL Conversions 8 COBOL Conversions Transactions are enforced in DCI during conversions All I O operations are done using transactions DCI sets AUTOCOMMIT off and manages DBMaker transactions to make record changes for users available DCI fully supports COBOL transaction statements like START TRANSACTION COMMIT ROLLBACK TRANSACTION DCI doesn t support record encryption record compression or the alternate collating sequence If these options are included in code they will be disregarded DCI also doesn t support the P PICture edit function in the XFD data definition and all file names are converted to lowercase DBMAKER DATABASE SETTINGS RANGE LIMIT TAE Number of columns per key 32 L
27. sensitive The DCI CASE configuration variable determines how file names are translated into table names Setting it to lower translates file names into table names with all lowercase characters Setting it to upper translates file names into table names with all uppercase characters Setting it to ignore means no file names are translated into table names with Copyright 1995 2012 CASEMaker Inc Configuration File Variables 6 all lowercase or uppercase characters The default setting for CASE is lower If your file names are DBCS words set CASE to ignore 2 Example DCI CASE IGNORE DCI COMMIT COUNT The COMMIT COUNT configuration variable indicates the conditions under which COMMIT WORK operation is issued There are two possible values 0 and n DCI COMMIT COUNT 0 No automatic commit is done default value DCI COMMIT COUNT v Under this condition DCI waits until the number of WRITE REWRITE AND DELETE operations are equal to the value lt n gt before issuing a COMMIT WORK statement This rule applies only when opening the file in output or exclusive mode DCI DATABASE DCI DATABASE is used to specify the name of the database established during the setup of DBMaker gt Example 1 The following entry has to be included in the configuration file if the database used is named DBMaker Test DCI DATABASE DBMaker Test gt Example 2 Sometimes the database name is no
28. variable is used to map files in different directories as tables of different databases Refer to Mapping to Multiple Databases for more info DCI_VARCHAR With this variable set to 1 the following action occurs When a COBOL program creates a new table trough OPEN OUTPUT verb all fields that were created as CHAR will become VARCHAR DCI_GRANT_ON_OUTPUT This new option allows you to specify the permission on the table during table creation OPEN OUTPUT Example DCI GRANT ON OUTPUT userl SELECT DCI GRANT ON OUTPUT user2 SELECT INSERT UPDATE After open output user will be able to select from the table user2 will be able to select and modify data Copyright 1995 2012 CASEMaker Inc DCI Functions 7 DCI Functions This section lists the DCI functions that could be called in the COBOL program To enable these functions the user must add these functions in the sub85 c and rebuild the DCI runtime Copyright 1995 2012 CASEMaker Inc 7 1 Al User s Guide 7 1 7 2 Calling DCI functions Add this to your COBOL program to call these DCI functions CALL dci function name USING variable variable DCI SETENV This function writes or updates the environment variable Syntax CALL DCI SETENV USING environment variable value Example call DCI SETENV using DCI DATABASE DBNAME DCI GETENV This function reads the environment variable Syntax CALL DCI GETENV USING env
29. 0 or 99999 or DCI MIN DATE default value Illegal HIGH VALUES stored as the highest possible value 99999 or DCI DATE default value Illegal SPACES stored as zero or DATE in the case of a date field Illegal DATE values stored as DATE default value Illegal TIME stored as INV DATE default value Null fields sent to DCI from a database convert to COBOL in the following ways Numbers including dates convert to zero Copyright 1995 2012 CASEMaker Inc DCI Basics 2 Text including binary text converts to spaces If you want to change these conversion rules except for the key fields you can use DCI NULL ON ILLEGAL DATE that convert to NULL illegal COBOL data Copyright 1995 2012 CASEMaker Inc 2 21 Al User s Guide 2 7 Sample Application sample application program is included with the DCI files and demonstrates mapping application data to a DBMaker database This section teaches Setting up the application Compiling source code to create application object code Application data input Data access using dmSQL and Tool How source code conforms to the generated table s schema Setting up the Application Located in the DCI directory the application consists of these files INVD CBL INVD FD INVD SL TOTEM DEE CBLCONFIG INVD XFD DCI CFG and the object file INVD ACU The application may be run directly from the INVD ACU obje
30. 0001 EMP matches all of the above OCopyright 1995 2012 CASEMaker Inc Data Dictionaries 3 2 EMP 1 matches 001 0001 and 00001 but does nor match EMPLOYEE OYEE matches EMPLOYEE does not match 0001 or EMP00001 Syntax 3 Where pattern consists of any valid filename characters and may include or The MAPPING variable has the following syntax DCI MAPPING lt pattern gt base xfd name Copyright 1995 2012 CASEMaker Inc 3 17 Al User s Guide 3 6 Mapping to Multiple Databases It is possible to reference tables in different databases with DCI_DB_MAP by specifying different files or COBOL file prefix links to the DBMS gt Example To reference table idx1 in the databases DBNAME as default DBCED and DBMULTI add the following settings in the DCI_CONFIG configuration file DCI DB MAP usr CED DBCED DCI DB MAP usr MULTI DBMULTI To create the idx1 table in these databases by specifying different files INPUT OUTPUT FILE CONTROL SECTION SELECT IDX 1 FILE ASSIGN TO DISK usr CED IDX1 ORGANIZATION IS INDEXI ACCESS IS DYNAMIC RECORD SELECT I 200 105 DEEA DX 2 FILE ED ASSIGN TO DISK usr MULTI IDX1 ORGANIZATION IS INDEXI ACCESS IS DYNAMIC RECORD SELECT I Be IES DEZA DX 3 FILE ASSIGN TO DISK IDX1 ORGANIZATION IS INDEXI ACCESS IS DYNAMIC RECORD DATA DIVISION FILE SECTION
31. 5 2012 CASEMaker Inc 2 9 Al User s Guide 10 11 12 13 If you are using ACUCOBOL GT 9 0 edit the VS2008 project named wrundll vcproj located in the lib directory of the ACUCOBOL GT installation a Change UseOfMFC from 0 to 2 1 Use in a shared DLL b Add dmacu90 lib dmdcic lib dmapi52 lib to AdditionalDependencies for example AdditionalDependencies mpr lib rpcrt4 lib wcvt32 1ib wfsi32 lib wrunlib lib dmacu90 1ib dmdcic lib dmapi52 1ib c Use VS2008 to build the project to obtain a new wrun32 dll file NOTE To build the runtime with 64 bit ACUCOBOL GT 9 0 you must install VS2008 x64 components NOTE You cannot build the runtime with the VS2008 express edition because it does not have the MFC library NOTE We recommend using the Fx3 or 4 compiler options to generate an XFD file with the same format as previous ACUCOBOL GT versions because ACUCOBOL GT 9 0 compiler does not support some XFD syntax like the XFD COMMENT directive in XML format However to use the new XML format add DCI XML 1 to the DCI configuration file Copy the new wrun32 exe and wrun32 dll files to a directory mentioned in your execution path or just wrun32 dll if using ACUCOBOL GT 6 2 and above for example copy wrun32 exe c acucobol acugt bin copy wrun32 dll c acucobol acugt bin Set the PATH system variable for PRODUCT NAME installed Wbin directory for example set PATH c DM PROD
32. 6018 name or a word that has been CREATE TABLE to the list reserved word reserved for the database of database reserved words Apply the NAME directive to the FD field of an invalid column and recompile to create a new XFD file Journal full Add start command transaction commit rollback rolled back to code in the COBOL program internal Or set savepoint DCI COMMIT COUNT in the DCI configuration file 9D 5503 invalid key The table does not have the Create the index with correct name index index name and columns 9D 5504 Cannot use User cannot use host variable host variable in the runsql acu 9D 1310 9D 5508 do not have User cannot open I O for OPEN INPUT with that INSERT UPD table that they does not have table ATE DELETE the insert delete update privilege privilege 9D 5512 cannot issue User cannot issue select select query statement in the runsql acu 9D 5513 client server User s DCI runtime is newer User should upgrade their version than the dmserver dmserver before running new mismatch when DCI runtime dci connect invalid column COBOL FD column User need to check the FD number number table column column number and table number column number invalid XFD COBOL FD column name Compare the FD and table column name or column type does not definition Fix this problem or data type and match with table definition by either change the COBOL length does not FD or alter table match 9D 5518
33. A B C Example 1 A COBOL file has 300 fields and the following statement SELECT FILENAME ASSIGN TO customer Copyright 1995 2012 CASEMaker Inc Configuration File Variables 6 Syntax The following line must be added in the dci cfg file DCI MAX ATTRS PER TABLE 100 Example 2 Three tables will be created with the following names customer a customer b customer c DCI MAX BUFFER LENGTH DCI MAX BUFFER LENGTH is used to split a COBOL data record into multiple database tables similar to the function performed by ATTRS PER TABLE However the cutoff value used to determine where a table will be split is determined by buffer length The default value is 32640 Example 1 A COBOL record size contains 9000 bytes of data and the following statement SELECT FILENAME ASSIGN TO customer Syntax The following line must be added in the dci cfg file DCI MAX BUFFER LENGTH 3000 Example 2 Three tables will be created with the following names customer a customer b customer c Copyright 1995 2012 CASEMaker Inc 6 9 Al User s Guide DCI_MAX_DATE This variable is used to establish a high value date in order to avoid problems in cases where invalid dates have been incorrectly written to the database The default for this variable is 99991231 December 31 9999 DCI MIN DATE This variable is used to establish a low value 0 or space date in order to avoid problems th
34. ASEMaker Inc 4 11 Al User s Guide gt 2 2 2 2 Syntax 2 XFD USE VAR LENGTH Example 5 USE VAR LENGTH 05 LARGE FIELD PIC X 10000 XFD WHEN Directive for File Names The WHEN directive is used to build certain columns in DBMaker that wouldn t normally be built by default By specifying a WHEN directive in the code the field and subordinate fields in the case of a group item immediately following this directive will appear as an explicit column or columns in the database tables The database stores and retrieves all fields regardless of whether they are explicit or not Furthermore key fields and fields from the largest record automatically become explicit columns in the database table The WHEN directive is only used to guarantee that additional fields will become explicit columns when you want to include multiple record definitions or REDEFINES in a database table One condition for how the columns are to be used is specified in the WHEN directive Additional fields you want to become explicit columns in a database table must not be FILLER or occupy the same area as key fields Syntax 1 Equal to SXFD WHEN field value Syntax 2 Less than or equal to SXFD WHEN field lt value Syntax 3 Less than SXFD WHEN field lt value OCopyright 1995 2012 CASEMaker Inc XFD Directives 4 Syntax 4 Greater than or equal to SXFD WHEN field gt value Syntax 5 Greater t
35. CASEMaker Inc 4 1 Al User s Guide 4 1 4 2 Using Directive Syntax Each directive occupies the entire line located immediately before the related line of COBOL code All directives have the prefix XFD a symbol in the 7 column followed immediately by XFD Syntax 1 The following command provides a unique database name for an undefined COBOL variable Locate the directive directly above the line it affects in this case the second instance of the COBOL defined variable qty 03 QTY 9 03 01 5 03 QTY PIC SS Syntax 2 Directives may also be specified using this ANSI compliant syntax XFD NAME CAPQTY Syntax 3 More than one directive may be combined together Directives may share the same line when preceded by the prefix XFD and separated by a space or comma SXFD NAME CAPQTY ALPHA Syntax 4 Alternatively the following can be used XFD NAME CAPQTY ALPHA Copyright 1995 2012 CASEMaker Inc XFD Directives 4 4 2 Using XFD Directives Directives are used when a COBOL file descriptor is mapped to a database field The XFD prefix tells the compiler the proceeding command will be used during generation of the data dictionary XFD ALPHA Directive To store non numeric data like LOW VALUES or special codes in numeric keys this directive allows a data item that has been defined as numeric in the COBOL program to be treated as alph
36. DCI blob data When user get blob from a is null column and the data is null 9D 5519 DCI blob file User should ensure the blob does not exist file has existed 9D 5514 9D 5515 8 10 Copyright 1995 2012 CASEMaker Inc COBOL Conversions 8 Figure 8 6 Native SQL Errors Char Copyright 1995 2012 CASEMaker Inc 8 11 Al User s Guide Converting Vision Files DCI provides a sample program to convert COBOL files into RDBMS tables Before using the DCI_MIGRATE program a Vision file to be converted and an XFD data dictionary for the Vision file are required The ACUCOBOL runtime system 4 3 or higher linked to DCI must be installed and a DCI_MIGRATE object program must be ready Using DCI_Migrate This is a general purpose program that converts any COBOL vision file into a DBMaker table To run correctly the minimum DCI configuration settings must be defined to work with DBMaker LOGIN DCI_DATABASE DCI_PASSWD etc and match the XFD file name with 407 table name or use MAPPING to specify the name and location The program MIGRATE reads vision files and writes DBMaker tuples through DCI In addition after migration it checks if all records are correct by reading vision records and comparing them by reading DBMaker rows MIGRATE program will report the following Total record read successful Total record write successful Total record read unsuccessful Total reco
37. MBER FIELD MOVE HR NUMBER FIELD TO EMP ID ADD RECORDS ACCEPT ACCEPT EMP PHONE WRITE EMPLOYEE RECORD PERFORM GET NEW EMPLOYE NUMBER gt Example 2 The preceding program normally would write all fields sequentially to file The output would appear as follows ENTER EMPLOYEE ID NUMBER 1 99999 ENTER 0 TO STOP ENTRY 51100 LAVERNE HENDERSON 2221212999 ENTER EMPLOYEE ID NUMBER 1 99999 ENTER 0 TO STOP ENTRY 52231 MATTHEW LEWIS 2225551210 ENTER EMPLOYEE ID NUMBER 1 99999 ENTER 0 TO STOP ENTRY In a traditional COBOL file system records will be stored sequentially Every time a write command is executed the data is sent to the file When DCI is used the data dictionary will create a map for the data to be stored in the database In this case the record EMPLOYEE RECORD is the only record in the file 2 Example 3 The database will create a distinct column for each field in the file descriptor The table name will be HR FILE in accordance with the SELECT statement in the FILE Copyright 1995 2012 CASEMaker Inc 3 7 Al User s Guide CONTROL section The database records in the example would therefore have the following structure EMP 1 INT 6 EMP NAME EMP PHONE RTE 100 LAVERNE HENDERSON HENDERSON 2221212999 52231 MATTHEW LEWIS 2225551212 Figure 3 3 Table EMPLOYEE RECORD In this table the column EMP ID is the pr
38. Refer to the Quick Start sheet included with the DBMaker CD for installation instructions Windows Setup The DCI files must be copied from the source directory in the DCI zip file DCI OS to a target directory before proceeding to setup DCI The DCI libraries include dmdcic lib dmacu51 lib for ACUCOBOL GT 5 1 and previous versions dmacu52 lib for ACUCOBOL GT 5 2 and versions before 8 0 dmacu80 lib for ACUCOBOL GT 8 0 and dmacu90 lib for ACUCOBOL GT 9 0 DCI Setup 1 Install 2DM PRODUCT The latest DM PRODUCT NAME must be installed and configured prior to configuring DCI 2 the DCI library dmdcic lib and the DCI library for ACUCOBOL GT from the _ PRODUCT NAMEO DCI zip file into the ACUCOBOL GT installation directory copy DCINWIN32Ndmdcic lib c acucobol acugt lib a For ACUCOBOL GT 5 1 or previous versions copy DCINWIN32Ndmacu51 1ib c acucobol acugt lib b For ACUCOBOL GT 5 2 or versions before 8 0 copy DCINWIN32Ndmacu52 1ib c acucobol acugt lib c For ACUCOBOL GT 8 0 copy DCINWIN32Ndmacu80 1ib c acucobol acugt lib d For ACUCOBOL GT 9 0 copy DCINWIN32Ndmacu90 1ib c acucobol acugt lib 3 Edit the ACUCOBOL GT runtime configuration file filetbl c It should be in the same directory as the ACUCOBOL GT libraries for example c acucobol acugt lib Copyright 1995 2012 CASEMaker Inc DCI Basics 2 4 a Theoriginal filetbl c contains the entry E a
39. SEMaker Inc 3 5 Al User s Guide 3 2 Mapping Columns and Records The table that is created is based on the largest record in the COBOL file It contains all of the fields from that record and any key fields Key fields are specified in the FILE CONTROL section using the KEY IS phrase Key fields correspond to primary keys in the database table and are discussed in detail in the next section Note that DCI will create column names for the database that are case sensitive unlike table names gt Example 1 The following illustrates how data is transferred ENVIRONMENT DIVISION INPUT OUTPUT SECTION FILE CONTROL SELECT HR FILE ORGANIZATION IS INDEXED RECORD KEY IS EMP ID ACCESS MODE IS DYNAMIC DATA DIVISION FILE SECTION FD HR FILE LABEL RECORDS ARE STANDARD 01 EMPLOYEE RECORD 05 EMP ID 12 SIG c 05 EMP NAME 7 lt 05 EMP PHONE IC 200 5 WORKING STORAGE SECTION 01 HR NUMBER FIELD OS e PROCEDURE DIVISION PROGRAM BEGIN OPEN I O HR FILE ERFORM GET NEW EMPLOYEE ID ERFORM ADD RECORDS UNTIL EMP ID ZEROS CLOSE HR FLE PROGRAM DONE STOP RUN GET NEW EMPLOYEE ID IP E 3 6 Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 PERFORM INIT EMPLOYEE RECORD PERFORM ENTER EMPLOYEE ID INIT EMPLOYEE ID MOVE SPACES TO EMPLOYEE RECORD MOVE ZEROS TO EMP ID ENTER EMPLOYEE ID DISPLAY ENTER EMPLOYEE ID NUMBER 1 99999 DISPLAY ENTER 0 TO STOP ENTRY ACCEPT HR NU
40. SWD is correct See Chapter 6 PASSWD for more information Syntax The configuration file should appear as follows when the database account is set to SYSADM DCI PASSWD DCI XFDPATH DCI XFDPATH specifies the directory where data dictionaries are stored The default value is the current directory Syntax 1 If data dictionaries are stored in usr dbmaker dictionaries include this entry in the configuration file DCI XFDPATH usrdbmaker dictionaries Copyright 1995 2012 CASEMaker Inc 2 17 Al User s Guide 2 18 2 Syntax2 When specifying more than one path separate by spaces For example DCI XFDPATH usr dbmaker dictionaries usr dbmaker dictionariesl 2 Syntax3 Use double quotes in a WIN 32 environment when including embedded spaces For example DCI XFDPATH c tmp xfdlist c Way folder with space Wfdlist Copyright 1995 2012 CASEMaker Inc DCI Basics 2 2 5 Runsql Utility DCT s runsql acu program provides access to some standard SQL commands It can be called from a COBOL program or executed from the command line The SQL command is limited to 32 767 characters It may be a variable or a quoted command string in the CALL statement Runsql acu may issue most all SQL commands but those for data retrieval For example statements that return data such as SELECT are unsupported This category of statement returns an error when passed to runsql acu The global variable return
41. Table Copyright 1995 2012 CASEMaker Inc 3 3 Al User s Guide NOTE Please remember there is a limit to the maximum length of DBMaker table names and that MAPPING must be used to map XFD file dictionary definitions RESULTING FILE RESULTING TABLE COBOL CODE NAME NAME ASSIGN TO employees dat xfd pue dat usr hr employees dat SELECT DATAFILE datafile xfd 0 ASSIGN TO DISK ASSIGN TO D emp xfd emp SYS LIB EMP ASSIGN TO FILENAME user specified user specified Figure 3 2 Example Table Names Formed From Different COBOL Statements ECCE mum gt Example Table names are in turn generated from the XFD file name Another way to specify the table name is to use the XFD FILE directive XFD FILE PURCHASE FILE2 FD PURCHASE FILE 01 PURCHASE RECORD 05 DATE PURCHASED 10 YYYY PIC 9 04 10 M PIC 9 02 10 DD PIC 9 02 05 PAY METHOD PIC X 05 The final name is formed as follows compiler converts extensions and includes them with the starting name by gt replacing the with an underscore _ constructs a universal base name from the file name and directory information as specified by the CONFIG variable DCI_USEDIR_ LEVEL It reduces 3 4 Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 the base name to 32 characters and converts it to lowercase depending of DCI CASE value Copyright 1995 2012 CA
42. The following are the three CACHE variables to set in the CONFIG file DCI DEFAULT CACHE START sets the first read records to cache for START or READ The default is the maximum of 8kb record size or 5 records Copyright 1995 2012 CASEMaker Inc 6 15 Al User s Guide DCI DEFAULT CACHE NEXT sets the next read records after the first cached record for START or READ have been read or discarded The default is the maximum of 8kb record size or 5 records DCI DEFAULT CACHE PREV sets the read records for caching the previous records after the first cache record for START or READ have been read or discarded The default is DCI DEFAULT CACHE 2 Setting these variables in the DCI_ CONFIG will affect all the tables in the user s application gt Example DCI DEFAULT CACHE START 10 DCI DEFAULT CACHE NEXT 10 DCI DEFAULT CACHE PREV 5 DCI TABLESPACE This allows you to define in which tablespace to create a table It also works with wildcards It is important only when a table is first created Once the table exists DCI does not monitor the value of this variable gt Example 1 You want to create the customer table in tablespace tbs1 DCI TABLESPACE customer tbs1 2 Example 2 You want to create all tables that begin with cust in tablespace tbs1 DCI TABLESPACE cust tbs1 DCI AUTOMATIC SCHEMA ADJUST This variable directs DCI to alter the table schema definition when the
43. The number of columns in the database table and the number of fields in the COBOL program that is accessing the table are not required to match The DBMaker table can have more columns than the COBOL program references however the COBOL program may not have more fields than the DBMaker table Ensure that any extra columns are set correctly when adding new rows to a table ACUCOBOL generates XFD file names by default from the FILE CONTROL section If the SELECT statement for the file has a variable ASSIGN name ASSIGN TO filename then specify a starting name for the XFD file using a FILE directive refer to XFD FILE Directive in chapter 4 If the SELECT statement for the file has a constant ASSIGN name such as ASSIGN TO then the constant is used to generate the XFD file name If the ASSIGN phrase refers to a device and is generic such as ASSIGN TO DISK then the compiler uses the SELECT name to generate the XFD file name File names and usernames are case insensitive All file descriptors containing uppercase characters will be converted to lowercase Users must be aware of this if using a case sensitive operating system gt Example 1 If the FILE CONTROL section contains the following line of text SELECT FILENAME ASSIGN TO Customer Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 gt Example 2 DCI based on dictionary information read in customer xfd will make a DBMaker
44. UCT 5 2 bin PATHS You can also copy the c DM_PRODUCT_NAME 5 2 bin dmapi52 dll to where the wrun32 exe and wrun32 dll files are located Please update the dmapi52 dll to that directory if you have installed the new DM PRODUCT NAME patch Verify the link by entering wrun32 vv Copyright 1995 2012 CASEMaker Inc DCI Basics 2 This returns the version information for all products linked with your runtime system Make sure it shows the version of the DM PRODUCT NAMEZ interface UNIX Setup The DCI files must be copied from the source directory on the DCI zip file DCI OS to a target directory before proceeding to setup DCI The DCI libraries include libdmdcic a libdmacu51 a for ACUCOBOL GT 5 1 and previous versions libdmacu52 a for ACUCOBOL GT 5 2 and versions before 8 0 dmacu80 lib for ACUCOBOL GT 8 0 and dmacu90 lib for ACUCOBOL GT 9 0 1 Copy the DCI library libdmdcic a and the DCI library for ACUCOBOL GT to the ACUCOBOL GT installed directories For example to get DCI libraries for Linux cp dci Linux2 x86 libdmdcic a usr acucobol lib cp dci Linux2 x86 libdmapic a usr acucobol lib For linking DCI libraries with ACUCOBOL GT 5 1 or previous versions cp dci Linux2 x86 1ibdmacu51 a usr acucobol lib For linking DCI libraries with ACUCOBOL GT 5 2 or versions before 8 0 cp dci Linux2 x86 1ibdmacu52 a usr acucobol lib For linking DCI libraries wich ACUCOBOL GT 8 0 cp dci Linux2 x86 1ib
45. UI DCI FR NULL E XFD 5 B y DCI FREE XED NULL Edit the ACUCOBOL GT runtime configuration file direct c It is in the same directory as the ACUCOBOL GT libraries The original direct c contains the entry EXTRNTABL 5 EXTDATA NULL Add new entry NU extern char dci w EXTRNTABLI m LL here constraint EXTDATA DCI W NULL 6 HERE CONSTRAINT NULL char amp dci where constraint If you are using a version of ACUCOBOL GT prior to 6 0 open wrun32 mak and search for LIBS The wrun32 mak file should be in the same directory as the ACUCOBOL GT libraries for example c acucobol acugt lib a If using ACUCOBOL GT 5 1 or previous versions add the files dmacu51 lib dmdcic lib and dmapi52 lib Build the project to obtain a new wrun22 exe and wrun22 dll file 2 8 Copyright 1995 20 12 CASEMaker Inc DCI Basics 2 nmake exe f wrun32 mak wrun32 exe b Ifusing ACUCOBOL GT 5 2 or later version add the files dmacu52 lib dmdcic lib and dmapi52 lib Build the project to obtain a new wrun32 exe and wrun32 dll file nmake exe f wrun32 mak wrun32 exe If you are using ACUCOBOL GT 6 0 or 6 1 open the VS6 0 project named wrun32 dsw located in the lib directory of the ACUCOBOL GT installati
46. UM 01 EMPLOYEE RECORD 05 EMP KEY 10 EMP TYPE BICES XFD BINARY 10 EMP NUM Q B 10 EMP SUFFIX jene 05 Copyright 1995 2012 CASEMaker Inc XFD Directives 4 XFD COMMENT DCI SERIAL n Directive This directive defines a serial data field and an optional starting number n Trigger DBMaker to generate a serial number by inserting a record and supplying a 0 value for the serial field DBMaker will not generate a serial number when inserting a new row but supplying an integer value instead of a 0 value If the supplied integer value is greater than the last serial number generated DBMaker resets the sequence of generated serial numbers to start with the supplied integer value Syntax 1 SXFD COMMENT DCI SERIAL 1000 Syntax 2 XFD COMMENT DCI SERIAL 1000 Example 01 EMPLOYEE RECORD 05 EMP KEY 10 EMP TYPE BICES XFD COMMENT DCI SERIAL 250 10 EMP COUNT IC QOS 5 XFD COMMENT DCI COBTRIGGER Directive This directive defines COBOL program to be triggered by I O events like READ WRITE REWRITE or DELETE The COBOL program is automatic called before and after I O events Syntax 1 SXFD COMMENT DCI COBTRIGGER cblprogramname Syntax 2 XFD COMMENT DCI COBTRIGGER cblprogramname Copyright 1995 2012 CASEMaker Inc 4 5 Al User s Guide XFD COMMENT Directive This directive identifies comments in an XED file In this way information can be em
47. aker Inc 8 3 Al User s Guide COBOL DBMAKER COBOL DBMAKER xca Jose E ss Co Jaunes ON DECIMALG01 oies lSMAUINT 90 0 SMALLINT 9G 10comp5 DECIMAL Q0 9 n comp 1n I INTEGER 9 1 4 comp 6 SMALLINT 17 s9 n comp 1 n 1 INTEGER 9 5 9 comp 6 INTEGER 17 9 1 4 comp 4 SMALLINT PIC x n CHAR n nl max column length Figure 8 3 COBOL to DBMaker Data Type Conversion Chart 8 4 Copyright 1995 2012 CASEMaker Inc COBOL Conversions 8 8 3 Mapping DBMaker Data Types DCI reads data from the database by doing COBOL like MOVE from the native data types to the COBOL data types most of which have a CHAR representation so you can display them by using dmSQL It is not necessary to worry about exactly matching the database data types to COBOL data types PIC X nn can be used for each column with regards to database types having a CHAR representation PIC 9 9 is a closer COBOL match for databases that have INTEGER types The more you know about a database type the more flexible you can be in finding a matching COBOL type For example if a column in a DBMaker database only contains values between zero and 99 0 99 PIC 99 would be a sufficient COBOL date match Choosing COMP types can be left to the discretion of the programmer since it has little effect on the COBOL data used BINARY data types will usually be re written without change b
48. anumeric text CHAR n n 1 max column length in the database Syntax 1 XFD ALPHA Syntax 2 XFD ALPHA Moving non numeric value like A234 to the key without using the XFD ALPHA directive would be rejected by the database Example 1 Assume the KEY IS code key has been specified and we have the following record definition CODE NUM is a numeric value and since group items are disregarded in the database it is the key field 01 EMPLOYEE RECORD 05 EMP KEY 10 EMP NUM IC GS Example 2 Using the XFD ALPHA directive changes a non numeric value like A234 saves the record from rejection by the database since A234 is an alphanumeric value and CODE NUM is a numeric value Copyright 1995 2012 CASEMaker Inc 4 3 Al User s Guide 01 EMPLOYEE RECORD 05 EMP KEY SXFD ALPHA 10 EMP NUM PIC 9 5 gt Example 3 2 2 2 Now the following operation can be used without worrying about any rejection MOVE C0531 TO CODE KEY WRITE CODE RECORD XFD BINARY Directive To allow for data in a field to be alphanumeric data of any type for example LOW VALUES use the BINARY directive With LOW VALUES for example COBOL allows both LOW and HIGH VALUES in a numeric field but DBMaker does not BINARY directives transform the COBOL fields into DBMaker BINARY data types Syntax 1 SXFD BINARY Syntax 2 XFD BINARY Example This allows moving of LOW VALUES to CODE N
49. as an input parameter Indexed file File containing a list of keys that uniquely identify all records Key A unique value used to identify a record in a database See Primary Key for more details Primary key primary key consists of a column of unique or key values which can be used to identify individual records contained in a table Query In DBMaker SQL commands used to execute data query requests made by a user to obtain specific information Glossary 2 Copyright 1995 2012 CASEMaker Inc Glossary Record In COBOL a group of related fields defined in the Data Division In DBMaker a record is also referred to as a row and defines a set of related data items in table columns Relational Database A relational database is a database system where internal database tables on different databases may be related to one another by the use of keys or unique indexes Schema database table s structure as defined by its columns Data type size number of columns keys and constraints all define a table s schema Server server is a central computer that stores and handles network configuration files which also can consist of a database management system to store data database and distribute data to clients via a network connection SQL Structured Query Language is the language DBMaker and other ODBC compliant programs use to access and manipulate data Table A logical storage unit in a d
50. at can occur when invalid dates have been incorrectly written to the database The default for this variable is 00010101 January 1 LAD DCI NULL ON ILLEGAL DATE DCI NULL ON ILLEGAL DATE determines how COBOL data that is considered illegal by the database will be converted before it is stored The value 1 causes all illegal data except key fields to be converted to null before it is stored The value 0 default value causes the following conversions to occur LOW VALUES stored as the lowest possible value 0 or 99999 or DCI MIN DATE default value HIGH VALUES stored as the highest possible value 99999 or DCI MAX DATE default value Illegal SPACES stored as zero or MIN DATE in the case of a date field Illegal DATE values stored as DCI_INV_ DATE default value Illegal TIME stored as DATE default value llegal data in key fields is always converted regardless of the value of this configuration variable 6 10 Copyright 1995 2012 CASEMaker Inc Configuration File Variables 6 2 2 DCI PASSWD Once a username has been specified via the LOGIN variable a database account is associated with it password needs to be designated to this database account This can be done using the variable PASSWD Example 1 If the password you want to designate to the database account is SUPERVISOR the following must be specified in the
51. atabase that consists of columns and rows used to store records XFD file An acronym for extended file descriptor or data dictionary It also forms the file extension for the data dictionary Copyright 1995 2012 CASEMaker Inc Glossary 3 Al User s Guide Glossary Copyright 1995 2012 CASEMaker Inc Index Index A ALPHA Directive 4 3 B BINARY Directive 4 4 B TREE Files 1 1 C Column Names Maximum Length 8 2 Columns 3 5 COMMENT Directive 4 4 4 5 Configuration Basic 2 14 Configuration file variables 6 1 Copyright 1995 2012 CASEMaker Inc Configuration File Variables _DCI_MAPPING 6 7 CDI LOGFILE 6 6 DCI Table Cache 6 13 DCI AUTOMATIC SCH ADJUST 6 15 DCI DATABASE 6 3 DCI DATE CUTOFF 6 4 DCI DB MAP 6 16 DCI IGONRE MAX BUF FER LENGTH 6 15 DCI INCLUDE 6 15 DCI INV DATE 6 6 DCI JULIAN BASE DAT E 6 7 DCI LOGIN 6 6 DCI LOGTRACE 6 7 Index 1 Al User s Guide DCI MAX DATE 6 9 DCI MIN DATE 6 9 DCI NULL DATE 6 15 DCI NULL ON MIN D ATE 6 16 DCI PASSWD 6 10 DCI STORAGE CONVE NTION 6 11 DCI TABLESPACE 6 14 DCI USEDIR LEVEL 6 11 DCI USER PATH 6 12 DCI XFDPATH 6 13 DEFAULT RULES 6 5 filename RULES 6 13 D Data Dictionaries Storage Location 6 13 Data Structures 2 2 Data Types COBOL to DBMaker 8 3 DBMaker to COBOL 8 5 Not Supported 8 2 Supported 8 2 Copyright 1995 2012 CASEMa
52. ating system is unable to locate some needed shared libraries This can happen even if the shared libraries exist in the current directory Some versions require setting an environment variable which points to shared libraries on the system For example an IBM RS 6000 running 4 1 the environment variable LIBPATH must indicate the directory where shared libraries reside For HP UX the environment variable is PATH For UNIX SVR4 the environment variable is LD_LIBRARY_PATH Please consult your UNIX documentation for specific details Alternatively linking the shared libraries to the runtime with a static link resolves this error Please refer to the documentation for your C development system to find the correct flag for your environment Copyright 1995 2012 CASEMaker Inc 2 15 Al User s Guide 2 4 2 2 Basic Configuration DCI requires parameters in two configuration files The first is cblconfig the ACUCOBOL runtime configuration file The second is CONFIG file that is located in a directory determined by an environment variable see Configuration File Variables for details The DCI_CONFIG file sets parameters for DCI that determine how data appears in the database and defines certain DBA functions allowing database access The following configuration variables must be set before using DCI DATABASE DCI LOGIN DCI PASSWD XFDPATH Example Here is a basi
53. bedded in an XED file so that other applications can access the data dictionary Embedded information in the form of a comment using this directive does not interfere with processing by DCI interfaces Each comment will be recognizable in the file as having the symbol in column 1 Syntax 1 SXFD COMMENT text Syntax 2 XFD COMMENT text XFD DATE Directive DATE type data is a special data format supported by DBMaker that is not supported by COBOL To take advantage of the properties of this data type convert fields from numeric type data The DATE directive s purpose is storage of dates in fields in the database This directive differentiates dates from other numbers so that they enjoy the properties associated with dates in the RDBMS Syntax 1 XFD DATE date format string Syntax 2 XFD DATE If no date format string is specified then six digit or six character fields are retrieved as YYMMDD from the database Eight digit fields are retrieved as YYYYMMDD The date format string is a description of the desired date format composed of characters OCopyright 1995 2012 CASEMaker Inc XFD Directives 4 CHARACTER DESCRIPTION Z Dy mila ol Figure 4 1 date format string Characters Each character in a date format string is a placeholder representing the type of information stored at that location The characters also determine how many digits will be used for each type of
54. c DCI_ CONFIG file DCI LOGIN SYSADM DCI PASSWD DCI DATABASE DBMaker Test DCI XFDPATH usr dbmaker dictionaries DCI DATABASE DCI DATABASE specifies the database that will transact with DCI This database must exist Use DBMaker setup to establish it Please note database names are case sensitive by default and must be less than or equal to 128 characters Please refer to Chapter 6 DATABASE for more information Syntax The following entry must be included in the configuration file In this example we show DBMaker Test as the database to be used with DCI DCI DATABASE DBMaker Test Copyright 1995 2012 CASEMaker Inc DCI Basics 2 2 2 2 LOGIN Provide your COBOL application with a user name to ensure it has permission to access objects in the database The configuration variable LOGIN sets the username for all COBOL applications that use DCI Initially set to SYSADM to ensure full access to databases this variable is easily changed to another user name as described in Chapter 6 DCI LOGIN Syntax The DCI configuration file must include the following entry for DCI to connect with databases via the SYSADM username DCI LOGIN SYSADM DCI PASSWD Once a username has been specified via the LOGIN variable a database account is associated with it Please note by default DBMaker sets no password for SYSADM Your database administrator will know if the account information LOGIN PAS
55. code is 0 when a command has completed successfully If a command is unsuccessful the global variable return code contains an error code Syntax 1 Creating a DBMaker view runcbl runsql acu Example 1 Pausing a program before accepting SQL commands create table TEST coll char 10 col2 char 10 create view TESTW as select from TEST Syntax 2 Calling runsql acu from a COBOL program call runsgl acu using sql command Example 2 Call runsql using create view TESTW as select from TEST Copyright 1995 2012 CASEMaker Inc 2 19 Al User s Guide 2 6 2 20 Invalid Data Some data is valid for COBOL applications but invalid for DBMaker RDBMS databases Data types not accepted by RDBMS are listed here along with solutions that DCI implements to solve this problem COBOL VALUE WHERE IT IS CONSIDERED ILLEGAL LOW VALUES In USAGE DISPLAY NUMBERS and text fields HIGH VALUES In USAGE DISPLAY NUMBERS COMP 2 numbers and COMP 3 numbers SPACES In USAGE DISPLAY NUMBERS and COMP 2 numbers Zero In DATE fields Figure 2 4 Illegal COBOL Data Check the internal storage format of other numeric types to determine which Figure 2 4 category it applies to BINARY numbers and values in BINARY text fields are always legal Certain data types must be converted before DBMaker will accept them DCI converts these values as follows Illegal LOW VALUES stored as the lowest possible value
56. ct code file as shown in the following paragraph Applications may also be compiled from the source code INVD CBL also demonstrated below NOTE ACUCOBOL 4 3 or greater is needed to compile the sample application gt Running the Application 1 Setup a database in DBMaker to accept data from DCI For example we created a database called DCI using JServer Manager with all default settings Specifically SYSADM is the default login name and no password was set For information on creating and setting up a database refer to the Database Administrators Reference or the JServer Manager Users Guide 2 Located in the DCI directory use a text editor to open the DCI CFG file Set the configuration variables to appropriate values Refer to Section 2 4 Basic Configuration for details 2 Example DCI DATABASE DET DCI LOGIN SYSTEM 2 22 Copyright 1995 2012 CASEMaker Inc DCI Basics 2 DCI PASSWD DCI LOGFILE DCI STORAGE CONVENTION Dca DCI XFDPATH C DCI Run the DBMaker Server program dmserver exe When prompted select the database designated by the DCI CFG file x Database Name DBFIRM y DBFIRM DBSAMPLES DCI EXESITE MESSADMINI The database starts normally and the following window appears If any problems or error messages occur refer to the Error Message Reference or the Database Administrators Guide Database Tools Info Help Starting database Database DCI successfully started From th
57. 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 with a 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 The definition of Julian dates varies so the DATE directive allows for a flexible representation of Julian dates Many sources define a Julian day as the day of the year with January 1st being 001 January 2nd being 002 etc To use this definition use FEE day of year in the date formats Other references define a Julian day as the number of days since a specific base date This definition is represented in the DATE directive by 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 07 01 0001AD Copyright 1995 2012 CASEMaker Inc 4 7 Al User s Guide You may define your own base date for Julian date calculations by setting the configuration variable JULIAN BASE DATE DCI considers dates in the following range to be valid 01 01 0001 to 12 31 9999 If a COBOL program attempts to write a record containing a date that DCI knows is invalid DCI inserts a date value that depends on the setting specified by the DCI INV DATE DCI MIN DATE and DCI MAX DATE configuration variab
58. days of complimentary email and phone support during the evaluation period When software is registered an additional thirty days of support is included extending the total software support period to sixty days However CASEMaker continues providing email support free of charge for reported bugs after the complimentary support or registered support has expired For most products support is available beyond sixty days and may be purchased for twenty percent of the retail price of the product Please contact sales casemaker com for details and pricing CASEMaker support contact information by post mail phone or email for your area is at www casemaker com support We recommend searching the most current FAC database before contacting CASEMaker support staff Please have the following information available when phoning support for a troubleshooting enquiry or include this information in your correspondence Product name and version number Registration number Registered customer name and address Supplier distributor where product was purchased Platform and computer system configuration Specific action s performed before error s occurred Error message and number if any Any additional helpful information Copyright 1995 2012 CASEMaker Inc Introduction 1 1 3 Document Conventions This manual uses a standard set of typographical conventions for clarity and ease of use The NOTE Procedur
59. dmacu80 a usr acucobol lib For linking DCI libraries with ACUCOBOL GT 9 0 cp dci Linux2 x86 1ibdmacu90 a usr acucobol lib 2 Edit the ACUCOBOL runtime configuration file filetbl c found in the same directory as the ACUCOBOL GT libraries a The original filetbl c contains the entry ifndef USE VISION define USE VISION 1 endif Add a new entry ifndef USE DCI define USE DCI 1 endif Copyright 1995 2012 CASEMaker Inc 2 11 Al User s Guide b The original filetbl c contains the entry extern DISPATCH TBL v4 dispatch ci dispatch bt dispatch Add a new entry c The original filetbl c contains the entry Add a new entry 3 Edit the ACUCOBOL GT runtime configuration file sub85 c It is in the same directory as the ACUCOBOL GT libraries The original sub85 c contains the entry Add a new entry 2 12 Copyright 1995 2012 CASEMaker Inc DCI Basics 2 DCI GET TABLE NAME DCI GET TABLE NAME DCI SET TABLE CACHE DCI SET TABLE CACHE DCI BLOB ERROR DCI BLOB ERROR DCI BLOB PUT DCI BLOB PUT DCI BLOB GET DCI BLOB GET DCI GET TABLE SERIAL VALUE DCI GET TABLE SERIAL VALUE DCI FREE XFD DCI FREE NULL NULL Edit the ACUCOBOL GT runtime configuration f
60. e Example and Command Line conventions also have a second setting used with indentation CONVENTION DESCRIPTION Italics Italics indicate placeholders for information that must be supplied such as user and table names The word in italics should not be typed but is replaced by the actual name Italics also introduce new words and are occasionally used for emphasis in text Boldface Boldface indicates filenames database names table names column names user names and other database schema objects It is also used to emphasize menu commands in procedural steps KEYWORDS All keywords used by the SQL language appear in uppercase when used in normal paragraph text small caps Small capital letters indicate keys on the keyboard A plus sign between two key names indicates to hold down the first key while pressing the second A comma between two key names indicates to release the first key before pressing the second key NOTE Contains important information Indicates that procedural steps or sequential items will follow Many 2 Procedure tasks are described using this format to provide a logical sequence of steps for the user to follow Examples are given to clarify descriptions and commonly include 2 Example text as it will appear on the screen Command Line Indicates text as it should appear on a text delimited screen This format is commonly used to show input and output for dmSQL commands
61. e system At the prompt enter make f Makefile This compiles sub c and filetbl c and then links the runtime system If the make fails because of an out of date symbol table execute the following Then the make If the make fails for any other reason please call ACUCORP Technical Support Verify the link with the following command runcbl vv This returns version information for all products linked to your runtime system Ensure it shows the version of DCI for DM PRODUCT NAME2O NOTE You may also link your own C routines with the runtime system Copy the new runcbl file to a directory in your execution path Everyone who will be using the runtime system must have execute permission for this file The remaining files can be left were they were installed We recommend using the Fx3 or Fx4 compiler options to generate an XFD file with the same format as previous ACUCOBOL GT versions because the ACUCOBOL GT 8 0 and 9 0 compilers do not support some XFD syntax like the XFD COMMENT directive in XML format However to use the new XML format add XML 1 to the DCI configuration file Shared Libraries When re linking and executing the ACUCOBOL GT runtime an error message similar to these may result Could not load library no such file or directory Can t open shared library Copyright 1995 2012 CASEMaker Inc DCI Basics 2 That could mean the oper
62. e command prompt go to the DCI directory Define DCI_ CONFIG by entering the following at the command prompt Syntax 6a NDS DEI CONEIG C N DCI DCI CFG Run the COBOL program INVD ACU using WRUN32 Syntax 7a From the same directory enter the following command DCI gt WRUN32 C CBLCONFIG INVD ACU The file CBLCONFIG contains the command line DEFAULT HOST DCI and is used to set the default file system For more information refer to Chapter 5 Compiler and Runtime Options Copyright 1995 2012 CASEMaker Inc 2 23 Al User s Guide 9 The INVD ACU COBOL application window opens as shown below allowing data entry First revio Next Last Add pdati3eletd Clear Exit 3 INVD INVLNO INVD INVLSTKNO INVD INVLDESC INVD INVLQTY 0 INVD INVLFREE 0 INVD INVLPRICE 0000000 00 INVD MVTCODE INVD SUBTOTAL 0000000 00 LI p NOTE For instructions on adding records refer to Adding Records below gt Compiling the sample application from the source code 1 Follow Running the Application steps 1 through 6 shown above 2 Copy these definition files acucobol def acugui def crtvars def fonts def showmsg def from Acucorp Acucbl500 AcuGT sample def to the DCI directory NOTE ACUCOBOL 4 3 users should copy the definition files from Acucbl43 AcuGT sample 3 At the command prompt go to DCI directory gt S
63. ecause they are foreign to COBOL However a closer analysis of BINARY columns might allow you to find a different solution The DECIMAL NUMERIC DATE and TIMESTAMP types have no exact COBOL matches They are returned from the database in character form so the best COBOL data type equivalent would be USAGE DISPLAY The following table illustrates the best matches for database data types and COBOL data types Copyright 1995 2012 CASEMaker Inc 8 5 Al User s Guide DBMAKER COBOL DBMAKER COBOL as mmc 56 ET 900 18 BECIMALGO1 saint 9 emp SMALLINT ous DECIMAL 96 10 comps SMALLINT 9 1 4 comp 4 CHAR n n 1 PIC x n column length Figure 8 DBMaker to COBOL Data Type Conversion Chart 8 6 Copyright 1995 2012 CASEMaker Inc COBOL Conversions 8 8 4 Troubleshooting Runtime Errors Runtime errors have the format 9D xx where 9D indicates a file system error reported in the FILE STATUS variable and xx indicates a secondary error code Copyright 1995 2012 CASEMaker Inc 8 7 Al User s Guide ERROR DEFINITION INTERPRETATION SOLUTION 9D 01 There is a read error on An error occurred Recompile with Fx to the dictionary file while reading the XFD re create the dictionary file The XFD file is file corrupt 9D 02 There is a corrupt The dictionary file for Recompile with
64. ecify the value to be displayed if a user enters a low high value in the DATE field When a user inputs low high value for a DATE Copyright 1995 2012 CASEMaker Inc 6 5 Al User s Guide gt gt field in a COBOL program for example by entering 00010101 99991231 the date will be displayed using COBOL s low high value 00000000 99999999 When this variable is used the low high value of the DATE field will be displayed using the database s low high value 00010101 99991231 This rule is also applied when the DATE field is a part of a key The default value is off Syntax The following line must be added in the dci cfg file DCI GET EDGE DATES 1 INV DATE This variable is used to establish an invalid date like 2000 02 31 in order to avoid problems that can occur when an incorrect date format has been written to the database The default for this variable is 99991230 December 30 9999 DCI LOGFILE This variable specifies the pathname of the DCI log file used to write all of the I O operations executed by the interface The dci_trace log log file stored in the tmp directory is used for debugging purposes The use of a log file slows down the performance of DCI For this reason it is recommended not add this variable in the configuration file unless deemed absolutely necessary Example A sample log file entry in the Config ini file DCI LOGFILE tmp dci trace log LOGIN The variable
65. ength for a CHAR 32640 Simultaneous RDBMS connections BOO Character for column names 128 Database tables simultaneously open by a single process 256 Figure 8 1 DBMaker Database Settings Range Limits table Copyright 1995 2012 CASEMaker Inc 8 1 Al User s Guide 8 1 Using Special Directives DBMaker can use the same sort or retrieval sequence as the Vision file system but it requires that a BINARY directive be placed before each key field containing signed numeric data High and low values can create complications in key fields The DBMaker OID VARCHAR size and FILE data types are not currently supported with special directives DBMAKER DATA TYPE DIRECTIVE DATE o oS TIME o OO TIMESTAMP Usg XFDDATE LONGVARCHAR Using XFD VAR LENGH LONGVARBINARY Using XFD VAR LENGH BINARY 0000000 SERIAL UsingXFD COMMENT DCI SERIAL Figure 8 2 DBMaker Data Types Supported using Special Directives 8 2 Copyright 1995 2012 CASEMaker Inc COBOL Conversions 8 8 2 Mapping COBOL Data Types DCI establishes what it considers to be the best match for COBOL data types in the creation of all columns in a DBMaker database table Any data the COBOL date type can contain can also be contained in the database column The XFD directives that have been specified will be checked first Copyright 1995 2012 CASEM
66. er Inc Contents DG XE e terere ctt erret eter ees 7 8 _ 7 8 8 COBOL Conversions SN 8 1 Using Special Directives 8 2 8 2 Mapping COBOL Data Types 8 3 8 3 Mapping DBMaker Data Types 8 5 8 4 Troubleshooting Runtime Errors 8 7 8 5 Troubleshooting Native SQL Errors 8 9 8 6 Converting Vision Files 8 12 Tiere DEF Mirate tata 8 12 5 lt 1 I de x 1 Copyright 1995 2012 CASEMaker Inc Al DCI User s Guide vi Copyright 1995 2012 CASEMaker Inc Introduction 1 Introduction This manual is intended for software developers who want to combine the reliability of COBOL programs with the flexibility and efficiency of a relational database management system RDBMS The manual gives systematic instructions on using the DBMaker COBOL Interface DCI a program designed to allow for efficient management and integration of data with COBOL using DBMaker s database engine DCI provides a communication channel between COBOL programs and DBMaker DBMaker COBOL Interface DCI allows COBOL programs to efficiently access information stored in the DBMaker relational database COBOL programs usually store data i
67. ey want to use the related syntax in their COBOL Example 1 The following syntax listed in Chapter 4 2 is not supported SXFD COMMENT DCI SERIAL n directive 5 COMMENT DCI COBTRIGGER Directive 5 COMMENT Directive Copyright 1995 2012 CASEMaker Inc Configuration File Variables 6 SXFD COMMENT DCI SPLIT filename RULES Default management for a multi definition file The actual file name replaces filename Example All of the files will use the POST rule except for the CLIENT file when the following commands are used DCI DEFAULT RULES POST CLIENT RULES BEFORE DCI TABLE CACHE Variables By default DCI pre reads data into the client data buffer to reduce client server network traffic The default maximum pre read buffer is the smaller of 8kb record size or 5 records It is possible that user s application will read a small table and only read a few records which are less than 8kb record size For example for a table with an average record size of 20 bytes and a total of 1 000 records DBMaker will be able to read about 400 records 8kb 20 but the user s application may only read 4 or 5 records then call the START statement again In this case set the following variable to reduce the cache size and improve performance Consider the application and data s behavior carefully when using these variables or it may increase network traffic and cause reductions in performance
68. han SXFD WHEN field gt value Syntax 6 Not equal to SXFD WHEN field value Syntax 7 OTHER can only be used with the symbol In this case the field or fields after OTHER must be used only if the WHEN condition or conditions listed at the same level are not met OTHER can be used before one record definition and within each record definition once at each level It is necessary to use a WHEN directive with OTHER in the eventuality that the data in a field doesn t meet the explicit conditions specified in the other WHEN directives Otherwise the results will be undefined SXFD WHEN field OTHER Syntax 8 Value is an explicit data value used in quotes and field is a previously defined COBOL field WHEN field operator value Example Explicit data values in quotes are permitted 05 AR CODE TYPE PIC X SXFD WHEN AR CODE TYPE S 05 SHIP CODE RECORD PIC X 04 SXFD WHEN AR CODE TYPE B 05 BACKORDER CODE RECORD REDEFINES SHIP CODE RECORD SXFD WHEN AR CODE TYPE OTHER Copyright 1995 2012 CASEMaker Inc 4 13 Al User s Guide 4 14 05 OBSOLETE CODE RECORD REFEFINES SHIP CODE RECORD TABLENAME OPTION The WHEN directive has the TABLENAME option to change the table name according to the value of the WHEN directive during runtime When using the TABLENAME option in a WHEN statement be aware of the DCI DEFAULT RULES and filename RULES DCI configuration variables Example 1
69. igure 2 1 COBOL and Database Object Structures Indexed file operations are performed on records in COBOL and operations are performed on columns in a database Logically a COBOL indexed file represents a database table Each record in a COBOL file represents a table row in a database and each field represents a table column Data can have multiple definition types in COBOL while table columns in a database must associate with a particular data type such as integer character or date Copyright 1995 2012 CASEMaker Inc DCI Basics 2 gt Example A COBOL record is defined using the following format terms record 03 terms code PIC OS 03 terms rate PIC 59939 03 terms days IPTE 03 terms descript PIC ITE The COBOL record in the above example has the following representation in a database Notice how each row is an instance of the COBOL 01 level record terms record TERMS CODE TERMS RATE TERMS DAYS TERMS DESCRIPT 255 1 500 15 net 15 Figure 2 2 COBOL Records Converted to Database Rows Accessing Data ACUCOBOL GT s generic file handler interfaces with DCI and the Vision file system Vision is the standard indexed file system supplied with ACUCOBOL GT See ACUCOBOL GT s manual for more detail about Vision files DCL in combination with data dictionaries bridges data access in a COBOL based application program interface API and DBMaker s database management system Users may access data through the API Furthermore
70. ile direct c It is in the same directory as the ACUCOBOL GT libraries The original direct c contains the entry struct EXTRNTABLE EXTDATA NULL NULL Add a new entry extern char dci where constraint struct EXTRNTABLE EXTDATA DCI WHERE CONSTRAINT char amp dci where constraint NULL NULL Open the Makefile file located in usr acucobol lib If you need to link it with your own C routines add them to a SUBS line in the Makefile of your C routine See Appendix C of the ACUCOBOL GT compiler documentation for details on linking C subroutines Add HOME lib libdmdcic a and APP HOME lib libdmapic a to the line FSI_LIBS where HOME is the directory containing the DM PRODUCT NAMES installation If DM PRODUCT NAME has been installed in the directory HOME then the Makefile will contain the following string s For ACUCOBOL GT 5 1 and previous versions FSI LIBS libdmacu51 a libdmdcic a libdmapic a For ACUCOBOL GT 5 2 FSI LIBS libdmacu52 a libdmdcic a libdmapic a For ACUCOBOL GT 6 0 and 7 0 FSI LIBS libdmacu60 a libdmdcic a libdmapic a Copyright 1995 2012 CASEMaker Inc 2 13 Al User s Guide 10 For ACUCOBOL GT 8 0 FSI LIBS libdmacu80 a libdmdcic a libdmapic a For ACUCOBOL GT 9 0 FSI LIBS libdmacu90 a libdmdcic a libdmapic a Ensure you are in the directory containing the ACUCOBOL GT runtim
71. imary key as defined by the KEY IS statement of the input output section The data dictionary creates a mapping that allows it to retrieve records and place them in the correct fields A COBOL application that stores information in this way can take advantage of the backup and recovery features of the database as well as take advantage of the capabilities of SQL Identical Field Names In COBOL fields with identical names are distinguished by qualifying them with a group item DBMaker does not allow duplicate column names on a table If fields have the same name DCI will not generate columns for those fields Adding a NAME directive that associates an alternate name with one or both of the conflicting fields is a method for handling this situation Please refer to XFD NAME Directive in Chapter 4 for additional details Example In the following example you would reference PERSONNEL and PAYROLL in your program FD HR FILE LABEL RECORDS ARE STANDARD 01 EMPLOYEE RECORD 03 PERSONNEL 05 EMP ID PIC 9 6 05 EMP NAME PIC X 17 Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 05 EMP PHONE 03 PAYROLL 05 EMP ID 05 EMP NAME 05 EMP PHONE Long Field Names 90110 o ETCRONGIE 200 DBMaker supports table names up to 128 characters truncates field names longer than 128 characters In the case of the OCCURS clause described below the truncation is to the original name
72. invd Edit Data Tab Field Values Copyright 1995 2012 CASEMaker Inc 2 27 Al User s Guide 2 28 OCopyright 1995 2012 CASEMaker Inc Data Dictionaries 3 Data Dictionaries Data Dictionaries describe how extended file descriptor XFD files are created and accessed DCI avoids using SQL function calls embedded in COBOL code by using a special feature of ACUCOBOL GT When a COBOL application is compiled using the option data dictionaries are generated These are known as extended file descriptors XFD files which are based on COBOL file descriptors DCI uses the data dictionaries to map data between the fields of a COBOL application and the columns of a DBMaker table Every DBMaker table used by DCI has at least one corresponding data dictionary file associated with it NOTE Refer to Chapter 5 3 of the ACUCOBOL GT Users Guide for more detailed information and rules concerning the creation of XFDs Copyright 1995 2012 CASEMaker Inc 3 1 Al User s Guide 3 1 Assigning Table Names Database tables correspond to file descriptors in the FILE CONTROL section of the COBOL application The database tables must have unique names under 128 bytes in length 128 ASCII characters It is possible for a DBMaker table to have more columns than a COBOL program s corresponding file descriptor It is also possible to have different column orders than the COBOL program s corresponding file descriptor
73. ion Time of database start Indexes DBMaster version Signature Text Indexes Database file version ES IVF Text Indexes Database Default Directory Ma Enrainn lav ah Rada Figure 2 6 INVD Application Tables Tree Node Double clicking on the SYSADM invd table allows you to view the table s schema All of the columns and their properties can be viewed here Schema Properties Permissions Dependencies Statistics Edit Data Primary Key s INVD INVLNO Name Type Precision Scale Nullable Primary Default Constraint INVD INVLNO 10 INVD INVLSTK char 10 INVD INVLDESC char 30 INVD INVLOTY linteger INVD INVLFREE integer INVD INVLPRI decimal 9 2 INVD MVTCODE char 5 INVD SUBTOT decimal 9 2 Figure 2 7 SYSADM invd Table Schema Selecting the Edit Data tab allows you to view the values of each field Schema Properties Permissions Dependencies Statistics Modify Confirm Cancel Delete amp Eilter Page Up First Last 6 records selected 1 Edit Data INV INVD INV INYD_INY INVD_IN INVD MVT Mose Alber 1 0 4000 00 Walter Oro 1 0 4000 00 Wassity Ka 1 0 4000 00 PaulKlee 1 0 4000 00 Ludwig Mle 1 0 4000 00 Lasszio Mo 1 0 4000 00 Figure 2 8 SYSADM
74. ironment variable variable Example CALL DCI GETENV USING DCI DATABASE ws dci database DCI DISCONNECT This function disconnects a database connection Example 1 If there is only one connection in the COBOL program use the following code to disconnect from the database CALL DCI DISCONNECT Copyright 1995 2012 CASEMaker Inc DCI Functions 7 gt Example 2 If there is more than one connection the COBOL program use the following code to disconnect a specific database CALL DCI DISCONNECT USING DBNAME DCI_GET_TABLE_NAME This function gets the table name of the passed COBOL name It s not always so immediate to know the effective table name because there can be some manipulation in these cases XFD WHEN TABLENAME CALL DCI GET TABLE NAME USING ws filename ws dci file name DCI SET TABLE CACHE This function dynamically changes the cache for tables set these variables before START or READ statements 2 Example WORKING STORAGE SECTION 01 CACHE START PIC 9 5 VALUE 10 01 CACHE NEXT 9 5 VALUE 20 01 CACHE PREV PIC 9 5 VALUE 30 PROCEDURE DIVISION OPEN INPUT IDX 1 FILE MOVE SPACES TO IDX 1 KEY CALL DCI_SET TABLE CACHE USING CACHE START CACHE NEXT CACHE PREV START IDX 1 FILE KEY IS NOT LESS IDX 1 KEY PERFORM VARYING IND FROM 1 BY 1 UNTIL IND 10000 READ IDX 1 FILE NEXT AT END EXIT PERFORM END READ DISPLAY IND AT 0101 END PERFORM CLOSE IDX 1 FILE
75. ive is when the COBOL file name is not specific Syntax 1 XFD FILE filename Syntax 2 XFD FILE filename Example In this case the ACUCOBOL GT compiler makes an XFD file name called CUSTOMER xtd ENVIRONMENT DIVISION FILE CONTROL SELECT FILENAME ASSIGN TO VARIABLE OF WORKING DATA DIVISION FILE SECTION 5 FILE CUSTOMER FD FILENAME XFD NAME Directive The NAME directive assigns a DBMaker RDBMS column name to the field defined on the next line In DBMaker all column names are unique and must be less than 128 characters This directive can be used to avoid problems created by columns with incompatible or duplicate names Copyright 1995 2012 CASEMaker Inc 4 9 Al User s Guide 4 10 Syntax 1 SXFD NAME columnname Syntax 2 XFD NAME columnname Example In DBMaker RDBMS the COBOL field cus cod will map to a RDBMS field named customercode SXFD NAME customercode 05 cus cod 9015 5 XFD NUMERIC Directive The NUMERIC directive causes the subsequent field to be treated as an unsigned integer if it is declared as alphanumeric Syntax 1 XFD NUMERIC Syntax 2 XFD NUMERIC Example The field customer code will be stored as INTEGER type data in the DBMaker table xfd numeric 03 customer code PIE XFD USE GROUP Directive The USE GROUP directive assigns a group of items to a single column in the DBMaker table The default data type for the resul
76. ker Inc Database Name Specifying 6 3 DATE Directive 4 6 DCI_CONFIG 6 1 DCI DATABASE 6 3 DCI DATE CUTOFF 6 4 DCI INV DATE 6 6 DCI JULIAN BASE DAT E 6 7 DCI_LOGFILE 6 6 DCI LOGIN 6 6 DCI LOGTRACE 6 7 DCI MAPPING 3 14 6 7 DCI MAX DATE 6 9 DCI MIN DATE 6 9 DCI PASSWD 6 10 DCI STORAGE CONVE NTION 6 11 DCI USEDIR LEVEL 6 11 DCI USER PATH 6 12 DCI XFDPATH 6 13 Default Filing System 5 3 DEFAULT RULES 6 5 Index DEFAULT HOST setting 5 2 Directives 4 1 ALPHA 4 3 BINARY 4 4 COMMENT 4 4 4 5 DATE 4 6 FILE 4 9 NAME 4 9 NUMERIC 4 10 Supported 4 3 Syntax 4 2 USE GROUP 4 10 VAR LENGH 4 11 WHEN 4 12 Document Conventions 1 5 E embedded SQL 1 1 Errors Runtime 8 7 SQL 8 9 Extended File Descriptors 3 1 Copyright 1995 2012 CASEMaker Inc F Field Names Identical 3 7 Long 3 8 FILE CONTROL section 3 2 FILE Directive 4 9 File System 2 2 FILE Filename Directive 4 9 filename RULES 6 13 Filing System Options 5 2 FILLER data items 3 13 I I O Statements 1 1 Illegal DATE values 2 18 6 10 Illegal HIGH VALUES 2 18 6 10 Illegal LOW VALUES 2 18 6 10 Illegal SPACES 2 18 6 10 Illegal time 2 18 6 10 Invalid Data 2 18 Index 3 Al User s Guide Index 4 J Julian dates 4 7 K Key fields 3 5 KEY IS phrase 3 5 3 12 L Login 6 6 M Multiple Record Formats 3 9 N NAME Direc
77. key field values The section Accessing Data describes how to browse data using DBMaker SQL based tools Copyright 1995 2012 CASEMaker Inc 2 25 Al User s Guide First reviod Next Last tefres Add Ipdatipetetd Ciear Exit INVD INVLNO 1 INVD INVLSTKNO Es INVD INVLDESC Josef Albers INVD INVLQTY si INVD INVLFREE p INVD INVLPRICE 0004000 00 3 INVD MVTCODE INVD SUBTOTAL 600000000 f Figure 2 5 INVD INVLNO Key Field Sample Entry Accessing Data To browse and manipulate records created within the sample application is straightforward First we recommend that you familiarize yourself with one of the DBMaker tools dmSQL DBA Tool or JDBA Tool For information on the use of these tools refer to the Database Administrators Guide or the JDBA Tool Users Guide The following example shows how data can be accessed using JDBA Tool The INVD application must first be shut down because it places a lock on the table that has been created within the database Connect to the database with JDBA You will be able to see the table by expanding the Tables node within the database tree as shown below 2 26 Copyright 1995 2012 CASEMaker Inc DCI Basics 2 amp EDCI SYSADM Database Object Statistics Option Tool Help METEO Database DCI Tablespaces 2 General Information BB Tables BLOB frame size EB views Time of database creat
78. le connect to DCI DB2 SYSADM create table tbl cl int not null c2 int c3 char 10 primary key c1 commit disconnect Copyright 1995 2012 CASEMaker Inc 3 29 Al User s Guide 3 30 Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 accept omitted stop run Copyright 1995 2012 CASEMaker Inc 3 31 Al User s Guide 3 11 Using DCI WHERE CONSTRAINT DCI WHERE CONSTRAINT specifies an additional WHERE condition for a succeeding START operation To be compatible with Acu4gl DCI also supports the gl where constraint gt Example The following example queries city names that start with A WORKING STORAGE SECTION 01 dci where constraint pic 4095 is external PROCEDURE DIVISION to pecify dci where constraint move low values to dci where constraint open i o idx 1 file move city name a to dci where constraint inspect dci where constraint replacing trailing spaces by low values move spaces to idx l key start idx 1 file key is not less idx 1 key 3 32 Copyright 1995 2012 CASEMaker Inc XFD Directives 4 XFD Directives Directives are comments placed in COBOL file descriptors that alter how the database table is built Directives change the way data is defined in the database and they assign names to database fields Directives can also assign names to XFD files assign data to binary large object BLOB fields and add comments Copyright 1995 2012
79. les into the date field and writes the record If a COBOL program attempts to insert into a record from a table with a NULL date field zeroes are inserted into that field in the COBOL record If a date field has two digit years then years 0 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 DATE CUTOFF Also refer to the configuration variables DCI MAX DATE and DCI MIN DATE for information regarding invalid dates when the date is in a key NOTE fa field is used as part of a key the field cannot be a NULL value USING GROUP ITEMS You may place the DATE directive in front of a group item so long as you also use the USE GROUP directive Example 1 XFD DATE 05 DATE PURCHASED PIC 9 08 05 PAY METHOD PIC X 05 The date purchased column will have eight digits and will be type DATE in the database with a format of YYYYMMDD gt Example 2 5 XFD DATE USE GROUP 05 DATE PURCHASED lO 04 10 MM PICAS 02 E Copyright 1995 2012 CASEMaker Inc XFD Directives 4 2 2 2 10 DD SNO 05 PAY METHOD PIC X 05 XFD FILE Directive The FILE directive names the data dictionary with the file extension XFD This directive is required when creating a different XFD name from that specified in the SELECT COBOL statement Another case that requires this kind of direct
80. m is specified for a new file If no value has been given to this variable ACUCOBOL will use the Vision file system as default The filename HOST setting allows you to set a file system for a specific file The name of the file should replace filename in the setting The following variables in the ACUCOBOL GT configuration file allow the file system of choice to be used Syntax 1 DEFAULT HOST Syntax 2 filename HOST Copyright 1995 2012 CASEMaker Inc Compiler and Runtime Options 5 5 2 2 2 Using DCI Default File System In order to take advantage of DBMaker s reliability and features such as replication backup and integrity constraints we suggest using the DEFAULT HOST DCI to avoid use of the ACUCOBOL GT Vision file system If no file system is specified the Vision file system will be used by default Syntax 1 In this case all new files will be DBMaker files unless the new files have been designated to a different file system DEFAULT HOST DCI Syntax 2 In order to establish that all new files unless otherwise specified will be Vision files use the following DEFAULT HOST VISION Copyright 1995 2012 CASEMaker Inc 5 3 Al User s Guide 5 3 Using Multiple File Systems Filename HOST is used to associate new files to a particular file system It differs from the DEFAULT HOST variable in that it associates single data files to a file system In this way files that use a differen
81. n standard B TREE files Information stored in B TREE files are traditionally accessed through standard COBOL I O statements like READ WRITE and REWRITE COBOL programs can also access data stored in the DBMaker RDBMS Traditionally COBOL programmers use a technique called embedded SQL to embed SQL statements with COBOL source code Before compiling the source code a special pre compiler translates SQL statements into calls to the database engine These calls execute to access the DBMaker RDBMS during runtime Though this technique is a good solution for storing information on a database using COBOL programs it has some drawbacks First it implies COBOL programmers have a good knowledge of the SQL language Second a program written in this way is not portable it cannot work both with B TREE files and the DBMaker RDBMS Furthermore SQL syntax often varies among databases This makes COBOL programs embedded with SQL statements for a specific DBMaker RDBMS unable to Copyright 1995 2012 CASEMaker Inc 1 1 Al User s Guide work with another database Finally embedded SQL is difficult to implement with existing programs In fact embedded SQL requires significant application re engineering including substantial additions to the working storage data storage and reworking of each I O statement s logic There is an alternative to embedded SQL Some suppliers have developed seamless COBOL to database interfaces These i
82. nterfaces translate COBOL I O commands on the fly into SQL statements In this way COBOL programmers need not be familiar with SOL and COBOL programs can remain portable However this solution does present a performance problem In fact SQL has a different purpose than COBOL I O statements SQL is intended to be a set based ad hoc query language that can find almost any combination of data from a general specification In contrast COBOL B TREE or other data structure calls use well defined traversal keys or navigation logic or both for direct data access Therefore forcing transaction rich performance sensitive COBOL applications to operate exclusively via SQL based I O is often an inappropriate method CASEMaker s COBOL interface product DCI does not use SQL in this way DCI provides direct access and traversal to data storage in a manner similar to COBOL s own access to user replaceable COBOL file systems DCI provides seamless interfaces between COBOL programs and DBMaker file systems Information exchange between the application and the database are invisible to end users In cases when full SQL based file and data storage access is required like desktop decision support systems DSS data warehousing and 4GL applications DBMaker provides these features along with the reliability and robustness of an RDBMS CASEMaker s database and DCI products combine the power of 4GLs and navigational data structures with the ad hoc flexibili
83. obtrig Example 2 The cobolpgmname must following the LINKAGE SECTION rule LINKAGE SECTION Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 2 Example 3 Op code is valued from DCI based on I O events The record image contains the COBOL record value before after the I O events The rc error could be used to force the COBOL I O events error using the following values Copyright 1995 2012 CASEMaker Inc 3 23 Al User s Guide 3 24 Copyright 1995 2012 CASEMaker Inc Data Dictionaries 3 3 8 Using Views DCI allows the use of DBMaker views instead of a table In this case DCI users must manually create a view and be aware of the following limitations Open a view and do all DML operations when the view is a single table view and the projection column on the original table is without an expression aggregate or UDF For other kinds of views open the view as an OPEN INPUT and perform a READ operation only gt Example 1 This example illustrates creating opening a view It assumes there are 2 tables named t2 and t3 created in this way create table t2 cl char 30 c2 int create table t3 cl int Additionally these tables contain some data identification division file control select miofile assign to ws nomefile organization indexed access mode dynamic record key rec data division file section SXFD FILE miofile fd miofile 01 rec GS el
84. ogramming Interface The API is an interface between an application and an operating system Binary Large Object BLOB A large block of data stored in the database that is not stored as distinct records in a table A BLOB cannot be accessed through the database in the same way as ordinary records The database can only access the name and location of a BLOB typically another application is used to read the data Buffer A buffer is an internal memory space zone where data is temporarily stored during input or output operations Client A computer that can access and manipulate data that is stored on a central server computer Column A set of data in a database table defined as multiple records consisting of the same data type OCopyright 1995 2012 CASEMaker Inc Glossary 1 Al User s Guide Data dictionaries Also known as extended file descriptors they serve as maps links between database schema and the file descriptors in a COBOL application Directive An optional comment placed in the COBOL code that sets the proceeding field or fields to a data type other than the default DCI setting Field Part of a COBOL file descriptor roughly corresponding to a database column It is a discrete data item contained in a COBOL record File Descriptor A file descriptor is an integer that identifies a file that is operated on by a process Operations that read write or close a file use the file descriptor
85. on Add the files dmacu52 lib dmdcic lib and dmapi52 lib to the project Build the project to obtain a new wrun32 dll file If you are using ACUCOBOL GT 6 2 or 7 0 open the VS2003 project named wrundll vcproj located in the lib directory of the ACUCOBOL GT installation Add the files dmacu52 lib dmdcic lib and dmapi52 lib to the project In the property select MFC s common DLL Build the project to obtain a new wrun32 dll file If you are using ACUCOBOL GT 8 0 edit the VS2005 project named wrundll vcproj located in the lib directory of the ACUCOBOL GT installation a Change UseOfMFC from 0 to 2 i e Use MFC in a shared DLL b Add dmacu80 lib dmdcic lib dmapi52 lib to AdditionalDependencies for example AdditionalDependencies rpcrt4 lib wcvt32 lib wfsi32 lib wrunlib lib dmacu80 lib dmdcic lib dmapi52 1ib c Use VS2005 to build the project to obtain a new wrun32 dll file NOTE To build the runtime with 64 bit ACUCOBOL GT 8 0 you must install VS2005 x64 components NOTE You cannot build the runtime with VS2005 express edition because it does not have the MFC library NOTE We recommend using the Fx3 or 4 compiler options to generate an XFD file with the same format as previous ACUCOBOL GT versions because ACUCOBOL GT 8 0 compiler does not support some syntax like the XFD COMMENT directive in XML format However to use the new XML format add DCI XML XFD 1 to the DCI configuration file Copyright 199
86. op run DCI_BLOB_PUT This function enables users to more effectively use BLOB data in a COBOL program Using the DCI_BLOB_PUT command you can insert data into a BLOB When using the DCI_BLOB_PUT command you must follow the rules listed below user s table must have a BLOB long varchar long varbinary data type Users cannot set the field with BLOB type in the COBOL FD Users can only call the DCI_BLOB_PUT command before a WRITE or REWRITE command fuser does not call DCI_BLOB_PUT before a WRITE statement the default value will be inserted in the blob column fuser does not call DCI_BLOB_PUT before REWRITE statement the blob column will not be updated gt Example The following gives a practical application of the use of BLOB in the COBOL program First the user creates a table CREATE TABLE BLOBTB SB CODCLI char 8 SB PROG SERIAL IL BLOB LONG VARBINARY PRIMARY KEY sb codcli LOCK MODE ROW NOCACHE Once the table is created the user continues with the following identification division program id blobtb date written remarks Copyright 1995 2012 CASEMaker Inc DCI Functions 7 DCI GET TABLE SERIAL VALUE This function gets the serial value after a WRITE statement gt Example Copyright 1995 2012 CASEMaker Inc 7 7 Al User s Guide 02 SB CODCLI PIC 81 SXFD COMMENT dci serial 03 SB PROG PICAS OS COMES working storage
87. pes Configuration file variables are used to modify the standard behavior of DCI and are stored in a file called CONFIG Copyright 1995 2012 CASEMaker Inc 6 1 Al User s Guide 6 1 Setting DCI_CONFIG Variables It is possible to give a configuration file a different address by setting a value to an environment variable called DCI_CONFIG The value assignable to this environment variable can be either a full pathname or simply the directory where the configuration file resides In this case DCI will look for a file called DCI_CONFIG stored in the directory specified in the environmental variable If the file specified in the configuration variable doesn t exist DCI doesn t display an error and assumes that no configuration variables have been assigned This variable is set in the COBOL runtime configuration file Syntax 1 In UNIX DCI will look for the CONFIG This environment variable is used to establish the path and name of the DCI configuration file Working with the Bourne shell the following command can be used DCI CONFIG usr marc config export DCI CONFIG Syntax 2 In DOS DCI reads the configuration file called DCI_CONFIG in the directory c etc test set DCI CONFIG c etcNtest Syntax 3 In UNIX DCI utilizes the file called DCI in the directory home test DCI CONFIG home test dci export DCI CONFIG DCI CASE File names in COBOL are case insensitive but table names are case
88. pping Multiple Files It is possible at runtime to use a single XFD file for multiple files with different names If the record definitions are identical then it is unnecessary to create a separate XFD for each file The runtime configuration variable MAPPING determines file mapping to an XFD Suppose a COBOL application has a SELECT with a variable ASSIGN name such as EMPLOYEE RECORD This variable assumes different values such as 0001 and 0002 during program execution To provide a base name for the XFD use the FILE directive see XFD DATE USE GROUP gt Example If EMP is the base then the compiler generates an XFD named Emp xfd The in the following example is wildcard character that replaces any number asterisk of characters in the file name The file extension xfd is not included in the map This statement would cause the XFD emp xfd to be used for all files with names that begin with EMP Add the following entry in the runtime configuration file to ensure that all employee files each having a unique but related name use the same XFD DCI MAPPING EMP EMP MAPPING variable is read during the open file stage The and 9 wildcards can be used within the pattern as follows matches number of characters matches a single occurrence of any character EMP matches EMP00001 and EMPLOYEE but does not match EMP001 or EMP
89. r display Invoice number inv number to see the invoice details move B to inv type move 1 to inv number move 0 to inv id start invoice key is inv key read invoice next display inv articles XFD COMMENT DCI SPLIT The DCI SPLIT directive is used to define one or more table splitting points starting where the DCI interface makes a new DBMS table Example 1 A COBOL FD structure using DCI SPLIT directive In this example three DBMaker tables named INVOICE INVOICE and INVOICE B are created with fields between the split points 4 16 Copyright 1995 2012 CASEMaker Inc XFD Directives 4 Copyright 1995 2012 CASEMaker Inc 4 17 Al User s Guide 4 18 Copyright 1995 2012 CASEMaker Inc Compiler and Runtime Options 5 Compiler and Runtime Options This section describes configuration settings for ACUCOBOL GT used to specify what file system to use Copyright 1995 2012 CASEMaker Inc 5 1 Al User s Guide 5 1 Using ACUCOBOL GT Default File System Existing files opened with a COBOL application are associated with their respective file systems as defined in the ACUCOBOL GT configuration file When new files are created by a COBOL application you need to specify what file system to use The ACUCOBOL GT configuration file needs to be set so that new files use the file system of choice The DEFAULT HOST setting tells ACUCOBOL which file system to use if no other syste
90. rd write unsuccessful Total record compared successful Total record compared unsuccessful Copyright 1995 2012 CASEMaker Inc COBOL Conversions 8 DCI MIGRATE RESULT OPTIONS Displays the online help Displays the online help online help nowait Doesn t wait for user confirmation during interactive mode visdbm Converts vision files to DBMaker tables default _ dbmvis Converts DBMaker tables to vision files Figure 8 7 MMIGRATE Options Result table Syntax 1 The vision file name is the name of the Vision file to be converted and table name is the name of the DBMaker table runcbl DCI MIGRATE vision file name dbm table name options Syntax 2 Setting the environment variable named DCI MIGRATE to yes can turn off the report The report will then append a file named dbm table name log DCI MIGRATE yes Syntax 3 The record can be dumped for an unsuccessful operation by adding dump to the DCI MIGRATE setting Spaces will be considered separators Log file names with embedded spaces are not permitted DCI MIGRATE yes dump Syntax 4 Setting the environment variable named DCIMIGRATE COMMIT COUNT can change the commit count from 100 to specified number DCIMIGRATE COMMIT COUNT 200 Copyright 1995 2012 CASEMaker Inc 8 13 Al User s Guide 8 14 Copyright 1995 2012 CASEMaker Inc Glossary Glossary API Application Pr
91. t file system than the default file system can be used In order to accomplish this substitute the configuration file DEFAULT value with the name of a file without using directory names or file extensions DEFAULT HOST and filename HOST can be used together gt Example In this case file 1 and 2 will use DBMaker while the other files will use the vision file system DEFAULT HOST VISION filel HOST DCI file2 HOST DCI 5 4 OCopyright 1995 2012 CASEMaker Inc Compiler and Runtime Options 5 5 4 Using the Environment Variable In order to allow the file system to be setup during execution of a program specify the following in the COBOL code The is only used for the ACUCOBOL runtime Also be aware that specification of a file system is usually done in the runtime configuration file and NOT changed in the COBOL program NOTE Refer to the ACUCOBOL GT Users Manual chapter 2 1 and 2 2 for detailed instructions on bow to use the ACUCOBOL GT compiler and runtime Syntax 1 SET ENVIRONMENT filename HOST TO filesystem gt Syntax2 SET ENVIRONMENT DEFAULT HOST TO filesystem Copyright 1995 2012 CASEMaker Inc 5 5 Al User s Guide 5 6 Copyright 1995 2012 CASEMaker Inc Configuration File Variables 6 Configuration File Variables This section lists the acceptable ranges of data for as well as tables specifying how COBOL data types are mapped to DBMaker data ty
92. t known in advance and for this reason it is necessary to set it dynamically during runtime In cases like this it is possible to write Copyright 1995 2012 CASEMaker Inc 6 3 Al User s Guide special code in the COBOL program similar to the one listed below The following code has to be executed before the first OPEN statement has been executed CALL DCI SETENV USING DCI DATABASE DBMaker Test 2 Example 3 You can use DCI_DATABASE to connect to more than one database and dynamically switch between databases to access a table on a different database connect to DBNAME to access idx 1 file CALL DCI SETENV USING DCI DATABASE DBNAME open output idx 1 file connect to DCIDB to access idx 2 file CALL DCI SETENV USING DCI DATABASE DCIDB open output idx 2 file to switch dynamically to DBNAME connection CALL DCI SETENV USING DCI DATABASE DBNAME close idx 1 file DCI DATE CUTOFF This variable uses a two digit value and establishes the two digit years that will be interpreted by the program as being in the 20 Century and the two digit years that will be interpreted by the program as being in the 21 Century The default value for the DATE CUTOFF is 20 In this case 2000 will be added to the two digit years that are smaller than 20 or whatever value you give to this variable and will therefore make them part of the 21 Century 1900 will be added to the two digit years that are
93. tant dataset in the database column is alphanumeric CHAR n where n 1 max column length The directive may be combined with other directives if the data is stored as a different type BINARY DATE NUMERIC Combining fields into groups improves processing speed on the database so effort is made to determine which fields can be combined Copyright 1995 2012 CASEMaker Inc XFD Directives 4 2 2 2 2 Syntax 1 XFD USE GROUP Syntax 2 XFD USE GROUP Example 1 By adding the USE GROUP directive the data is stored as a single numeric field where the column name is code key 01 CODE RECORD 5 USE GROUP 05 CODE KEY 10 AREA CODE NUM OS 10 CODE NUM IAC S O Example 2 The USE GROUP directive can be combined with other directives The fields are mapped into a single DATE type data column in the database XFD DATE USE GROUP 05 DATE PURCHASED 10 NAN PIC 9 04 10 MM 992 10 DD PROMO XFD VAR LENGTH Directive VAR LENGTH directives force DBMaker to use a BLOB field to save COBOL fields This is useful if the COBOL field is over or near the maximum allowable column size for regular data types Please refer to Chapter 8 COBOL Conversions Since BLOB fields cannot be used in any key field and are slower to retrieve then normal data type fields such as CHAR we suggest you use this directive only when needed Syntax 1 SXFD USE VAR LENGTH Copyright 1995 2012 C
94. tive 4 9 NUMERIC Directive 4 10 O OCCURS Clauses 3 13 P Password 6 10 Platforms Supported 2 5 Primary Keys 3 5 R Records 3 5 REDEFINES Clause 3 12 Requirements Copyright 1995 2012 CASEMaker Inc Software 2 5 System 2 5 Runtime Configuration File 2 6 2 7 2 10 Runtime Errors 8 7 Runtime Options 5 1 S Sample Application 2 20 Schema 3 10 SELECT statement 3 2 3 6 Setup 2 6 UNIX 2 9 Windows 2 6 Shared Libraries 2 13 Software Requirements 2 5 Sources of Information 1 3 SQL Embedded 1 1 Errors 8 9 Supported Features 8 1 Supported Platforms 2 5 System Requirements 2 5 T Table Schema 3 10 Index Tables 3 2 Technical Support 1 4 U USE GROUP Directive 4 10 User Name 6 6 Copyright 1995 2012 CASEMaker Inc V VAR LENGH Directive 11 Vision file system 5 2 W WHEN Directive 4 12 X XFD files 3 1 Index 5 Al User s Guide Index 6 Copyright 1995 2012 CASEMaker Inc
95. ty of SQL based database access and reporting while delivering tremendous performance 1 2 Copyright 1995 2012 CASEMaker Inc Introduction 11 1 1 Additional Resources DBMaker provides a complete set of DBMS manuals including this one For more information on a particular subject consult one of the manuals listed below For an introduction to DBMaker s capabilities and functions refer to the DBMaker Tutorial For more information on designing administering and maintaining a DBMaker database refer to the Database Administrator s Guide For more information on DBMaker management refer to the Server Manager Users Guide For more information on DBMaker configurations refer to the Configuration Tool Reference For more information on DBMaker functions refer to the DBA Tool User Guide For more information on the dmSQL interface tool refer to the dmSQL User Guide For more information on the SQL language used in dmSQL refer to the SQL Command and Function Reference For more information on the ESQL C programming refer to ESQL C User s Guide For more information on the native ODBC API and JDBC API refer to the ODBC Programmer Guide and JDBC Programmer Guide For more information on error and warning messages refer to the Error and Message Reference Copyright 1995 2012 CASEMaker Inc 1 3 Al User s Guide 1 2 1 4 Technical Support CASEMaker provides thirty
96. yntax 4 2 4 2 Using XFD Directives nu 4 3 XFD ALPHA Directive ue 4 3 XFD BINARY Directive eococccccccnnncnnnnnnnnnnonnnnnnnnnnnnnnnnnninnninonicininnnnns 4 4 XFD COMMENT DCI SERIAL n Directive 4 5 Copyright 1995 2012 CASEMaker Inc Contents XFD COMMENT DCI COBTRIGGER Directive 4 5 XFD COMMENT Directive ns 4 6 SXED I ALTE JDit Ctive tendre re rte dein 4 6 SCRE FILE Directives annee eee 4 9 XFD NAME Directive ss 4 9 XFD NUMERIC Directive ss 4 10 XFD USE GROUP Directive ss 4 10 XFD VAR LENGTH Directive ss 4 11 XFD WHEN Directive for File Names 4 12 XFD COMMENT DCI SPLIT nn 4 16 Compiler and Runtime Options 5 1 5 1 Using ACUCOBOL GT Default File System5 2 5 2 Using DCI Default File System 5 3 5 3 Using Multiple File Systems 5 4 5 4 Using the Environment Variable 5 5 Configuration File Variables 6 1 6 1 Setting DCI CONFIG Variables 6 2 ic NORMEN AR DN BODEN PARE Ronda 6 2 DECOM COUN Taar o ere 6 3 TADA P uus un ea en 6 3 DEL DATE CUT ORE ned ue miss sr dut ne 6 4 DER AWE RULES tartas 6 5 DCI_DEFAULT_TABLESPACE nn 6 5 DCI_DUPLICATE_CONNECTION ne 6 5 DOE GET BDGE DATES n der nr 6 5 ae Cid 6 6 DO OG d Nr une 6 6 DCO nan ne 6 6 BASK ODA TE oran vec 6 7
97. yntax Enter the following line DCI gt ccb132 INVD CBL 4 The file will be compiled and will create a new object code file INVD ACU and data dictionary file INVD XFD To run the object file follow steps 6 and 7 in To run the application above 2 24 Copyright 1995 2012 CASEMaker Inc DCI Basics 2 Adding Records Once the application has been started see To run the application above it is a simple matter to add records to the application and subsequently to the database The field INVD INVLNO is a key field so a unique value is required for a record to be a valid entry All other fields may be left blank When you have finished entering values into the field click the Add button The values entered into the fields will now be saved in the DBMaker database specified by the DCI CFG variable DCI DATABASE gt Example The file descriptor for the application looks like this FD INVD LABEL RECORDS ARE STANDARD 01 INVD R 05 INVD INVLNO PIC X 10 05 INVD INVLSSTKNO PIC X 10 05 INVD INVLDESC PIC X 30 05 INVD INVLQTY PIC 9 8 05 INVD INVLFREE PIC 9 8 05 INVD INVLPRICE PIC 9 7 V99 05 INVD MVTCODE PIC 6 05 INVD SUBTOTAL PIC Once a record has been added you may browse through the entries by selecting the First Previous Next or Last buttons on the Screen window An individual record may be selected from the drop down menu at the top of the Screen window that displays all the
98. you must set DCI DEFAULT RULES POST or COBOL Alternately if you plan to use sequential reading inside record types you must set DCI DEFAULT RULES BEFORE or DBMS There are advantages and disadvantages to using this rule To have a 100 COBOL ANSI reading behavior you should use the POST or COBOL method but this method can degrade performance more records are read and all involved tables are open at the same time If you use the BEFORE or DBMS method the involved table is opened when the WHEN condition matches at the read record level 2 Example 3 In other words if you use the previous records and code the following statements OPEN INPUT INVOICE to see the customer invoice READ INVOICE NEXT DISPLAY Customer INV CUSTOMER DISPLAY Invoice number INV NUMBER to see the invoice details READ INVOICE NEXT Copyright 1995 2012 CASEMaker Inc 4 15 Al User s Guide DISPLAY INV ARTICLES If the method is POST or COBOL the open input opens both tables and read next reads thru different tables gt Example 4 The matched table is opened at the start statement level If the method is BEFORE or DBMS the code is changed as follows open input invoice to see the customer invoice move A to to to start invoice key is inv type move 1 inv number move 0 inv id inv key read invoice next display Customer inv custome

Download Pdf Manuals

Related Search

Related Contents

Enermax UCEV8  関連PDF2 テクノテスター専用プリンタ M255-A 取扱説明書  MS 251 Homeowner Chainsaw Instruction Manual    Braun HD510 User's Manual  Manuel d'installation  CHARA Technical Report - The CHARA Array of Georgia State    2 3 4 5 6 1 取扱説明書[導入編]    

Copyright © All rights reserved. Failed to retrieve file