= jBASE JEDI Development Kit User Guide © 2006, 2016 Zumasys, Inc.Contents Documentation Conventions 1 INTRODUCTION ORGANISATION OF THIS MANUAL snssnesnuninininninennninnmninnnnnnnnnnnnned CONFIGURATION. JEDIdrivers.ini global parameters 4 MAPPING FROM DYNAMIC ARRAY TO RDBMS -sssnnninesnneninsenninininennnnnnne 5 ‘THE MAPPING SCHEMA — CSV -DEFINED 5 FULLY EXPANDEDENPLAINED 7 FullyExpanded 7 FullyExpanded 8 FollyExpanded 8 GENERATING THE MAPPING SCHEMA - JCREATECSV. JCreateCSV sequence of events. 10 u Datetime fields 3 ‘Accepted dictionary formats... VALIDATING THE SCHEMA - JCHECKSCHEMA. ‘What happens if try to write invalid data? so “ “4 there are EXCEPTIONS how does a SELECT work?, 16 How does Exception handling affect performance? 1s ‘What if don’t want the EXCEPTIONS table? 16 Thave a parameter file where records are of different formats. How can Istore that in an RDBMS? ‘How can I see what the driver is doing? SAMPLE CSV FILE. APPENDIX A - PLSORA DRIVER. INTRODUCTION 20 ORACLE REQUIREMENTS 20 Server Requirements Client Requirements. 20ORACLEDATABASE CONFIGURATION 21 ORACLEDATABASEOBIECTS 21 Tablespaces User (createuser: sq). Exception Table (CrestejBASEpkg.sal) Packages and Functions (createfunctions sql) DRIVER INSTALLATION 2 DRIVER CONFIGURATION 23 USINGTHEDRIVER 24 CREATEFILE, APPENDIX B - DB2EXP DRIVER.. INTRODUCTION 29 DB2 REQUIREMENTS 29 Server Requirements (Client Requirements. DB2 CONFIGURATION 30 DB? Database Objects DRIVERINSTALLATION 31 DRIVERCONFIGURATION 3 USINGTHEDRIVER 33 CREATE-FILE APPENDIX C - OLESQL DRIVER. IstRoDucTION 37 SQL SERVER REQUIREMENTS 37 Server Requirements Client Requirements. SQL SERVER CONFIGURATION 37 ‘SQL SERVER DATABASE ORIECTS 38 User DatabaseObjects (CreateExceptions sql). INSTALLATION38 Conricuration 39 JEDIcrivers Configuration, USING THEDRIVER 39 CREATE-FILE 30 38 38 39 40 APPENDIX C- FREQUENTLY ASKED QUESTIONS wanssiinnnnnmnnennnenncnne $4How does jBASE find the driver?... How does jBASE use the driver? ‘What happens if I try to write invalid data? How does a SELECT work if there are EXCEPTIONS?... 45 How does Exception handling affect performance? 46 ‘What ifI don’t want the EXCEPTIONS table? 46 Thave a parameter file where records are of different formats. How can I store that ? 46 How can T see what the driver is doing? 46 ‘What stored procedures does Oracle Use? .. aT ‘What stored procedures does SQL server use?. 47 ‘What happens when the driver reads? ‘What happens when the driver writes? 50 ‘What is the locking strategy? st ‘When do records get committed. si How are transactions implemented 82 ‘When are database connections opened and closed 2 How is I18N UTF-S data handled? . ‘What does the jstat commang show me?... ‘What do the following errors mean?Documentation Conventions This manual uses the following conventions: Convention BOLD UPPERCASE UPPERCASE Tralie Courier Courier Bolé Item | itemB Usage In syntax, bold indicates commands, function names, and options. In text, bold indicates keys to press, function names, menu selections, and MS- DOS commands. In syntas, uppercase indicates JBASE commands, keywords, and options BASIC statements and functions; and SQL statements and keywords. In test, uppercase also indicates JBASE identifiers such as filenames, account names, schema names, and Windows NT filenames and pathnames In syatas, italic indicates information that you supply. la text, tlie also indicates UNIX commands and options, filenames, and pathname. Courier indicates examples of source code and system output Courier Bold In examples, courier bold indicates characters thatthe user types or keys (for example, ). Brackets enclose optional items, Do not type the brackets unless indicated, Braces enclose nonoptional items from which you must select at least one Do not type the braces. ‘A vertical bar separating items indicates that you can choose ouly one item. Do not type the vertical ba ‘Three periods indicate that more of the same type of item can optionally follow. ‘A tight arrow between menu options indicates you should choose each. option in sequence. For example, “Choose File =>Exit” means you should choose File from the menu bar, aud then choose Exit from the File pull- down menu,Syntax definitions and examples are indented for ease in reading, All punetwation marks included in the syntax—for example, commas, parentheses, or quotation marks—are required unless otherwise indicated. ‘Syntax lines that do not ft on one line in this manval are continued on subsequent lines. ‘The continuation lines are indented. When entering syntax, type the entire syntax entry, including the continuation lines, on the same input line,INTRODUCTION ‘The JBASE database adheres toa similar model of the Reality’PICK database storing records as “dynamic arrays’ in ‘hashed! files. You can view these records in a manner similar to SQL using QL (iBASE’s version of the ENGLISH/ACCESS query language from Reality/PICK), However, as the jBASE query language is not (currently) ANSI SQL compliant there are those who feel the need to use a ‘relational database (typically referred to as RDBMS). With the development of the JEDI architecture in jBASE the ability to use any database to store records was made possible. The problem for most (if not all) BASE. tusets is mapping their existing record structuse on to the RDBMS. The JEDI Development Kit DK not to be confused with IDK — Java Development Kit) attempts to automate this as much as possible. There are several “drivers” (shared objects), which work in conjunction with the DK. These drivers work with their own specific RDBMS but rely on the jDK to generate the mapping between the iynamic array — on the JBASE side — and the columns in tables —oa the RDBMS side. ORGANI. ATION OF THIS MANUAL ‘This manual is split into two main sections. The first section provides generic information that is relevant to all JEDI Development Kits. The latter section provi detailed information specific to particular JDK. drivers. It is recommended for new users of the jDK to read the first seetion hefore referring to the section dedicated to the particular driver of interestCONFIGURATION The JDK driver suite relies, to some extent, on an initialisation file for critical parameters; called JEDIcrivers.ini its functions are similar to a “profile” on Unix operating systems. In fact the file is expected to be placed in /ete for global settings and if placed in SHOME itis named jEDIdrivers.ini, On Windows the file is always jEDIdrivers.ini but ean exist in °SYSTEMROOT% or *sHOMEY, jEDIdrivers.ini global parameters Below is an example of the non-driver parameters with a description (note the parameters ARE case sensitive): [General] JRLAlock = 1 PasswdsEnerypted FullyExpanded Tolsey (CSVdir = home/myuseriesy IdkHome = /home/myuserDK, ‘JdkTempPath = temp ‘This specifies that jBASE will handle the locking of secords (currently the jDK drivers do not handle locking at the RDBMS level). Specifies whether passwords for RDBMS logins are encrypted Controls how multi-values are stored aeross primary and secondary tables (more explanation later in this document). Literal separator characters between primary and secondary tables (more explanation in this documen}, Specify the directory where esv definitions are stored for controlling the mapping between attributes and columns ‘This isthe top dizectory twee where other jDK paameters/seripts/ete. are located. ‘A temporary directory where output of DK tools are ‘written during file creationMAPPING FROM DYNAMIC ARRAY TO RDBMS Generally, attributes in a dynamic array (record) are mapped to an individual column in a table (701. The Mapping schema — CSV - defined ‘The mapping for the jDK drivers is driven by csv (comma separated value) files; the fields are ColumaName Attribute Width Type Group Association Group Controlling Flag Must be a valid SQZ colnmn name Usually a single numeric (with the exception of DT types explained later in this document) Mandatory integer for character type fields AGN) -Varchar c-Char D-Date T Time DI- DateTime UTC. - Universal Time Conversion Nd- Numeric (where dis optional number of decimals) Optional group name for repeating groups. For sub-values the required format is: {multi-value ‘name|sub-value name} ‘This name will be appended to the primary table same (wit a separation character of # unless ToiSep is defined in JEDIdrivers. ful) when creating the associated table Yor | can be entered of left blank. ‘This should be entered against the field which willalways have a valve when more than one field has the same Group Association, Not Null Flag Yor | for Not Null (Le, mandatory) of N or 0 (or blank) for non-mandatory Positional multi-value For multi-value (or sub-value) fields, whieh are non-repeating you can enter the multi-value (or sub-value if within a multi-value group) position Compound Field Literal For fields like datetime you can enter the literal separation (e.g. *). The literal is applied to the field whose value appears before the literal Multiple compounds ean be defined. That last field in the compound would not have a literal (unless the value actually ends in a constant literal) This literal value does not appear in the RDBMS. ‘The driver adds/removes it when reading/writing from/to the RDBMS. Foreign Source Use this field to facilitate foreign key relationships at the RDBMS level. Format must be fable_name.colmn_name and fable_name aust exist in the RDBMS. ‘There nmust be at least two lines, the fist pointing to attribute O and at least one line pointing to aa atibute other than 9, One exception is an empty esv file, which implies a 2-columa table where the entire record (dynamic array) is stored in a BLOB type column,Fully Expanded Explained This parameter (from jEDJabivers. ini) as three settings: 0,1 and 2. It affects the way the frst multi-value (or sub-value) is handled on the target RDBMS when defining 4ssociations. Because the hash file model can read and write whole records faster than most (if not all) RDBMS an attemp: has been made to improve performance of a JEDI by reducing the number of fetches and incert/ypdate operations. EXAMPLE Suppose you have a Customer file with a Contacts field, whieh ean repeat. This would require two tables: One for the primary Customer details and Another for the repeating Contacts (ideally just a key to a Contact file/table). When typically reading an existing customer you would SELECT the columns from the Customer file (table) and the Contacts file (table): Now suppose that virtually all the Customer records never have more than one contact (even though they bave the facility to in the database). The READ operation always has to do two fetches (note, this is not necessarily true in the JDK driver suite due to the VMC_colunn behaviour previously explained) to bring back all the details. Customer File Name Address Contact #1 Contact 22 Contacte 3 FullyExpanded = 0 Using the above example the jDK forces the first multi-value to appear ia the primary table (ie, Customer). If the customer being read has only one contact the whole record is setrieved with single fetch (the VMC_Contacts column would be *1' so the driver knows no more fetches are requised). You can create Tews (the jDK ean automate some of this), which combine the first multi-value to the associated repeating table's values to make the associated set appear as one. The disadvantage of this format is the reshuffling of data ifthe first multi-value is deleted. Currently the {JDK drivers do not optimise updates therefore, it updates the whole seeord In the example below, there are three contacts associated with this customer record; the VMC_Contacts value would be 3.Customer File ‘Name ‘Addiess ‘Contact #1 Contacts Contact 22 Contact 3 FullyExpanded = 1 This is similar to zero except it repeats the first amalti-value in both the primary table (ie. Customer) and associated table (ie. Contacts). The advantage of ths is that a view is not required to query the repeating fields. The disadvantage is that if updates are made outside the BASE environment the user must be aware that the first value must be updated in two tables (e.g. in this ease Customer and Contact). ‘Keeping with the previous example VMC_Contacts value would be 3, Customer File ‘Name ‘Radiesse ‘Contact #1 Contaers File ‘Contact #1 Contact #2 Contact #3 FullyExpanded = 2 This format is move like the traditional RDBMS way of handling repesting groups. All the repeating fields are stone inthe respective table(s). There is still a YMC_colunm in the primary table for each associated group therefore the driver knows how many rows to expect. Again, in the example below VMC_Contacts value would be 3, Customer File ‘Nameaddress Contacts FileGENERATING THE MAPPING SCHEMA - JCREATECSV This command generates the comma-separated fle (CSV) used for mapping the dynamic array to the columns in a relational table. It gets its information from an exist ccan be any file that satisfies an OPEN ‘DICT’ command in BASIC): BASE supports a variety of, ictionary ofa file in {BASE (note, this dictionary formats, as does jCreateCSV. SYNTAX jCreatecsv file_name target.cev {prefix_chars} (options options: -Dinpe} dictionary type build driver valid pes: I for JDC. P or U for Prime/Unidata A option (appended to 1) for A types only (Le. do ‘not include “S* type dictionaries in the mapping) 0 overwrite previous definition refix_chars Leading characters to strip from dictionary when creating column names in comma separated file this is usefol in eases where a standard prefix has been used to key the dictionaries (many 4GLs do this) and you de not want this prefix used on the colnsnn names jCreateCSV sequence of events First, it selects, reads and vets all the dictionaries (e.. ifthe A option was used it ignores °S* type dictionaries) and ignores duplicates, Sorting is in ascending attribute order. There must beat least one definition pointing to attribute 0 (ie. the record key) Sorting isin ascending attribute order and scanned for associated groupings. Finally, it writes a resulting CSV to the CSVdir (as defined in the /EDIdrivers. ii). 10Accepted dictionary formats The classic Reality PICK style ~ A’ (or 'S") — type dictionary describes individual attributes reasonably well. Unlike the ‘D* type dictionary, it does not, support the definition of repeating groups (multi-valueisub- value fields). To accomplish this you must use the BASE Extended Dictionary. These are extra attributes, which appear afier the last ‘normal’ attribute of « Reality/PICK style dietionary, typically starting at atiribute 30 (although this is user definable) For the D* type approach you can also include “V" or T’ types to hanéle things like: Compound fields eg. DATE*TIME og, FIELD @adefning_ i, Position mili-vahues eg: EXTRACT(@RECORD, ot nn pos) For ‘A’ (or °S*) type dictionaries you can achieve similar results; Compound field example >GI*L Positional multi-values s Tiilename:Xmv_pos:sattr In the case where the field type is not explicit (ie. the Extended Dictionary is either missing or incomplete) the following rules apply: Dictionary Property Field type ‘Conversion field starts with D ‘D- DATETIME - vhere only the date is used - or DATE (some RDBMS platforms support Date type columas) Conversion stars with MT T -DATETIME - where only the time is used - oF TIME (some RDBMS platforms support Time type columns) rtDictionary Property Conversion of UTC ‘Conversion starts with MD or MR, Justification is R Justification is L Other Field type UIC - DATETIME ‘Nd- DECIMAL N-NUMBER C- CHAR Character Fixed Length IN} - VARCHAR Character Variable Length Here is an example ofa generated CSV from dictionaries often found in the JDP samples (note the Controlling value against HARDWARE was added manually afterwards), Column = Atte Width Type D. 0.10, AN FIRSTNAME, 24, AN LASTNAME, 20, AN ADDRL. 304 aN ADDR? 420, AN cary. 1 AN STATE, 6&8 aN Zz, 2 12 aN HOMETEL, 8% 16 AN WORKTEL. 9 16 AN EMAIL, 10, AN HARDWARE, 11, AN os. 2 AN. SYSTEMTYPE, 13, 24, AN, MUSERS, 14,6, AN, This definition implies two tables: Association Controlling HARDWARE, 1 HARDWARE HARDWARE HARDWARE Primary table (CUSTOMER) which holds al the fields with no Association Multi-value association - HARDIARE ~ which generates the table CUSTOMER*HARDWAREDatetime fields As RDBMS databases typically have a datetime field whereas jBASE internally uses date and time separately, itis possible to make use of both portions by defining a DT type field in the CSV. This spits the date and time into separate entities on jBASE, wiich merges on the RDBMS side. It supports the following combinations: Date and Time on separate attributes. To achieve this specify the Attribute field as date_attrtime_atm. Date and Time on the same attribute but specific multi-values. ‘Simply specify the DT type field with a single attribute Date and Time in the same field as a compound field. ‘Same as option 2 but specify a SplitChar Currently maintained at the C57 level Here as an example of all three scenarios: Column | attr | Width | Type | Association | Controlling | NotNull | Position | SplitChar cUST, 0, | 10, | AN | + , T : spiiror, | 112, | + or, fy : 1 . WVDT, x |e Dr, [> : T , compar, | 4, [> Dr, [> : T : * The above csv has a key field of CUST and three Datetime fields SPLITDT ‘The date will appear in attribute 1 and the time in attribute 2 MvDT Will appear as datetime on attribute 3 (i.e. multi-values 1 and 2) cOMPDT Will appear as date*time on attribute 4 1BVALIDATING THE SCHEMA — JCHECKSCHEMA Once you have generated the CSV run jCheckSchema against an existing file (typically a hashed file). This vill highlight any problem areas (e.g. invalid ASCTI characters in a numeric, date or time field) and automatically adjust lengths of alpha-numeric} fields (as the RDBMS world uses fixed length fields for its character field). Syntax CheckSchema file_name cev_definition {recordkey} (options options i interactive — this means that it will prompt for input where it normally make an adjustment a quiet — n0 progress is displayed (normally a percentage of records processed is shown) nm rounding factor where the length of character fields (AQN}) are rounded up to the next factor of R report only ~no adjustments are made to the CSV. What happens if I try to write invalid data? The CSV definition used when creating the file ~ and table(s)— determines what data types are valid and which fields are repeating. Unlike jBASE, it can only store values that are consistent with these data types. Some of the drivers have built-in logic for handling invalid records. The TrapErrs parameter in the {jEDIdrivers ini determines its use. Setting this variable to “I” ensures that all writes will succeed regardless of whether the record is consistent withthe CSV structure or not. The way this is handled is via an EXCEPTIONS table (created as part of the driver installation). Ths table holds the following fields: filename item update timestamp program which performed the write dynamic array record image When a jBASE application tries to read back this record it first attempts to read from the intended table. If ‘ot found it looks in the EXCEPTIONS table aad the application does not perceive aay difference in logic flow. 14Tes possible to setup auromatic emails to notify various parties when an exception occurs. Although this is outside the boundaries of BASE, the database administrator can implement this feature without interfering with the workings of the driverIf there are EXCEPTIONS how does a SELECT work? A SELECT from jBASE initiates a SELECT from the primary table, If TrapErrs is set to *1’, it includes a UNION ALL on the EXCEPTIONS table based on the current filename, How does Exception handling affect performance? The problem with relying on TrapErrs to catch your mistakes is that there is extra work needed by the driver to ensure data integrity. The following points highlight this For every read where no record is found oa the primary table, an additional SELECT is performed on the EXCEPTIONS table (te same goes for deleting records). For writes, the driver tries to detect if invalid data is being used, then calls the stored procedure to handle and update the table(s) If any update fais the driver has to then update the EXCEPTIONS table. Af performing a write on a table with no repeating groups it needs to check if the record was previously in the EXCEPTIONS table and if so delet it. Any SELECT has to include the EXCEPTIONS table to ensue all records are retrieved. What if I don’t want the EXCEPTIONS table? Set TrapErrs to 0. This means that an invalid write from jBASE will cause an error, The offending program can be coded with an ON ERROR clause and handle the error programmatically. If this is not done the application will se a write error message with: (Denore, (Retry, (Quit options T have a parameter file where records are of different formats. How can I store that in an RDBMS? Ifyou use an empty CSV file as the definition for your table, it ereates the records with @ generic record_id and record image (i.e, the dynamic array); referred to (sometimes) as 8 *BLOB* 16How can I see what the driver is doing? ‘There are two tracing methods: sereen and logfile. First, you must seta trace level: AUEDI_drivertype_TRACES Fora basic trace of VO set this environment variable to “1”. For a more detailed trace use “2 (more detail levels may be introduced later). ‘Next, you can optionally define: 2UEDI_drivertype LOGS to ‘1" and EDI_drivertype LOGFILE® to the name of the file you want to store the trace information. You can also set: ‘JEDI_drivertype DISPLAYS the same time. “1! to display the log to the screen at NOTE: if you do not set %SJEDI_chivernype LOG% it assumes %6 EDI drivertpe_DISPLAY%. SAMPLE CSV FILE ZONE, 0,10, Cyyp 1s, (CHAR(10). The first 3 Lines represent 3-part key: ZONE, CUST and SEQ. The “ ‘and “2 that separate the fields are only seen fiom the jBASE point of view CUST, 0, 10,6, yy rt (CHAR(0). All key fields have the NotNull set (which isthe default for key fields). SEQ, 0,2,M,¢ 1 NUMBER(2). The last field in the compound efinition has no SplitChar. NAME, 1,20, AM, ,,1 VARCHAR(20), Mandatory alphanumeric field on attribute 1 AREA_CODE,2,3,Nyyy1y)~ NUMBERG). First part of @ compound field on attibute 2 delimited by PHONE_NUMBER,2,7,N,,,1 NUMBER(7) on attribute 2 being the 2" part of the compound field 7, 3, 50,AN, yy 1,1 VARCHAR(50) on attribute 3 multi-value 1,TOWN, 3, 20,C, 52/2 ZIP, 3, 5,Nyy,113 COUNTRY _CODE,3,5,C,1/1/4, COUNTRY. CODE BALANCE, 4, 10,N2 CONTACT, 5,20, AN, CONTACTS, » 6,10, AN, HARDWARE, IME, 7, 6, 7, HARDWARE 0, AN, HARDWARE, SYSADMIN, 9, 20, AN, HARDWARE, NETWADMIN, 9, 20, AN, HARDWAR E,,1,2 SUBVALUES, 10,20, AN, ONEINU LTIVALUE, ,1,1 COMPDT, 11,10,DT,,,1,,* MVDT, 12, 10,DT,,,1 SEPARATEDT, 13/14, 10,D7,,, mandatory, (CHAR(20) on attribute 3 multi-value 2, mandatory. NUMBER(S) on attribute 3 multi-value 3, mandatory, (CHAR(S) on attribute 3 multi-value 4 mandatory with a foreign key constraint of COUNTRY.CODE. DECIMAL( 10,2) on attribute 4. VARCHAR(20) on attribute 5. Repeating field in associated table CUSTOMER#CONTACTS. VARCHAR(10) on attribute 6, Repeating field in associated table CUSTOMER#HARDWARE, {DATE}TIME on attribute 7. Repeating field in associated table CUSTOMER*HARDWARE, VARCHAR(20) on attribute 8, Repeating field in associated table (CUSTOMER*HARDWARE*SOFTWARE (2 sub-valued within each multi-value for HARDWARE), VARCHAR(20) on attribute 9, First sub-value in associated group (ie. positional sub-value within each multi-value for HARDWARE). VARCHAR(20) on attribute 9, Second sub-value in associated group. VARCHAR(20) on attribute 10. By placing a Positional value of 1 on a sub-value definition ‘that means the sub-values are in a non-repeating multi-value, You could repeat this definition for positions 2,3, ec, Each multi-value would have repeating sub-valne DATETIME on attribute 1 will appear as datetime. DATETIME on attribute 12, multi-valued as date}time DATETIME where the date appears on attribute 13 and the time on attribute 14. 18DATETIME in number of seconds in UTC format stored on attribute 15. DATE {TIME} appearing on attribute 16 NOTE: you do not have to define every attribute, Missing atwibutes will not be used which is useful when ‘migrating an existing fle and other attributes have become redundant. 19APPENDIX A - PLSORA DRIVER Introduction ‘The JDK PLSORA driver bridges the gap between jBASE and ORACLE wit litle or no intervention of the JBASE application developer, o that itis transparent for jBASE applications to acce: acle database. Moving the data from the traditional ‘hash fle’ environment to the RDBMS (e.g. ORACLE) environment brings with it one intrinsic point of which a user should be awate, The ‘multi-value’ environment is different to the “RDBMS” environment in th se thatthe underlying management of data is ifferent. From a high-level user perspective, they appear (and in fact are) both the same - “the application retrieves, data from the database”. The method by which the database drivers deliver and manipulate the data “under he covers" are however very di at. Put simply — performing a COUNT operation in one manufacturers database will yield the same results as perform COUNT" on the same data in a different ‘manufactures database, but the method by which the count was generated will differ Oracle Requirements Server Requirements Oracle Server version nuist be 91 Release 2 version 9.2.0.2.0 Enterprise Edition or Standard Edition, ‘You must install he Oracle OCT and PL/SQL packages on the server To determine the Oracle version aud edition, SQLPLUS” session (d the commang ‘select * from vSversioa * from an ions may be required): Client Requirements The Oracle (database) server and BASE server can reside 1 the same machine or on separate machines. I race (database) server 1d JBASE servers reside on separate machines, it will be necessary to install the Oracle Client software on the jBASE server and configure the Oracle Net Services tore database through appropriate naming method (Local Naming, Oracle Names Service or Host Naming).Oracle Database Configuration It is recommended that you use a case seusitive database to enable the different treatment of record keys like “A and ‘a’ The following parameters are recommended forthe Oracle database: Block Size~ 4096 Character Set - AL22UTFS, UTFS or WESISOSS59P1 The following parameters need to be set in the orscle initialisation (epi) file aqery_sewrite_enabled = TRUE query_rewrite integrity = TRUSTED Oracle Database Objects Create the following objects on the target databace: Tablespaces . It is recommended that two separate tablespaces are created on the Oracle database + DATA Tablespase eg: MYDATA (contains all the application Tables) + INDEX Tablespace eg. MYINDEX (contains all the application Indexes) + The tablespaces should be created with the “locally managed and auto-allocats’ options. Set the size of each tablespace to initially 1Gb (with auto-extend) fora typical application. + Use aay name forthe tablespaces, The diver fom th configuration fle reads these same. User (createuser.sql) To nun this you need to connect to a dba user (e.. system) At sqlplus @scripts/reateuser passwd = password> Ifthe PasswdsEncrypted=1 (either locally under [PLSORA] or globally under [General]) the ~ {IfORACLE_ SID jis exported then this is not requiredUsing the Driver ‘This section lists the commands that are specific to the PLSORA Driver or have extensions for the PLSORA Driver. Definitions Before you create a PLSORA type file, you must have a CSV definition to map each record fiom dywamic array to relational, For details on this, xefer to the frst section of this manval. CREATE-FILE Syntax CREATE-FILE filename TYPE=PLSORA (TABLE=tablename} (CSV=csvdefinition| BS) {EXISTINt tablename defaults to filename esvdefi parameter in the jEDIdsivers.ini file). m defaults to tablename (this definition is read from the directory specified by the CSVdir Any ‘characters inthe filename or columns will be converted to a *_* character in the database Example: ELSORA CSV=JCUSTOMER CREATE-FILE PLSCUSTOMER TY! (Executed from a telnet session) [eleeGbench csv] § CREATE-FILE PLECUSTOMER TYFESPLSCRA CSV=JCUSTORER [ 417 ] File PLECUSTOWERD created , type = FLSORA [ 417 ] File PLECUSTOWER created , type = FLSORA Disconnected feow JBASE at 10:53:54 12 JAN 2005 [cleetbench csv]§ 1s BLACCT]D BLACCT df.csy CARS.cv EQUIPKENT.cev EQUIPHENT MISTER.csv ERIC.csv BLACCTJ4 BL_ACCT 04)D —ENTCDE.csv EQUIPMENT] D — EQUIPHENT MASTER]D —JCUSTOMER.csv [eleetbench csv} JNOTE: That although the dictionary portion of the above file ~ PLSCUSTOMER]D ~ is displayed as typ. PLSORA itis in facta regular j4 hashed file, You could if you wanted to create them separately thus: CREATE-FILE DICT PLSCU TOMER 1 CREATE-FILE DATA PLSCUSTOMER TYPE. This create-file command does tree things: Creates a dictionary for the file (unless DATA has been specified) Generates a PL/SQL seript to run against Oracle by executing the jBuildOR4 command against the csv fle: JCUSTOMER csv Runs the seript, which creates the necessary table(s) and stored procedures. Weites out a stub file - PLSCUSTOMER ~ to the current working directory which will look like this: JBC__SOB JedilnitPLSORA PLSCUSTOMER In the above example our CSV looked like this: Column Atte Width Type tion Controlling, ID, o, 10, aN FIRSTNAME, 1, 24, AN LASTNAME, 2, 20, aN ADDRL, 3, 21, AN ADDR2, 4, 20, aN crry, 5, ll, aN STATE, 63, aN ZIP, 7, 12, aN 8, 16, AN s, 16, AN 10, 25, AN 15, AN, BARDWARE, 1 5, AN, BARDWARE SYSTEMTYPE, 13, 24, AN, BARDWARE NUMUSERS, 14, 6 AN, HARDWARELASTMAINT, 5, ll, DT, HARDWARE|UPDATED, 1 BALANCE, 16, 12, m2 This definition implies three tables: Primary table (PLSCUSTOMER) which holds all the fields with no Assoctation SQL> dese PLSCUSTOMER Name mull? Type NOT NULL VARCHARz (10) 1p FIRSTHAME ‘VARCHAR? (24) LASTWAME VARCHAR? (20) ADDR \VARCHARZ (21) appR2 ‘VARCHAR? (20) crry \VARCHAR2 (11) STATE VARCHAR2 (3) zp \VARCHAR2 (12) HOMETEL, VARCHAR2 (16) WORKTEL VARCHAR2 (16) emai VARCHAR2 (25) HARDUARE \VARCHAR2 (15) os. VARCHAR2 (15) SYSTENTYPE VARCHAR? (24) NUMUSERS VARCHAR2 (6) LasTMAINT \VARCHAR2 (11) BALANCE MUNBER (12,2) IC_HARDUARE MUMBER \MC_HARDUARE#UPDATED MONBER Multi-value association - HARDWARE — which generates the table PLSCUSTOMER*HARDWARE SOL> desc PLECUSTOMERFHARDUARE Name mull? Type 1D OT NULL VARCHARZ (10) VMC_HARDWARE NOT NULL NUNBER HARDUARE \VARCHAR2 (15) os \VARCHAR2 (15) SYSTENTYPE ‘VARCHARZ (24) NUMUSERS, \VARCHARZ (6) LASTHAINT \VARCHAR2 (11) VMtC_HARDUARE#UPDATED NUMBER ‘Sub-value association — UPDATED — within HARDWARE which generates the table PLSCUSTOMER*HARDWARE*UPDATED SQL> desc PLSCUSTONERSHARDUARE#UPDATED Name Null? Type D NOT NULL VARCHARz (10) VicC_HARDWARE NOT NULL NUMBER ‘VMCTHARDUARE#UPDATED NOT NULL NUMBER LASTHAINT \VARCHARZ (11)Adding some simple data tothe table using the BASE Editor: NEW “File PLSCUSTONER , Record 00000001" Command-> iff 001 DONNA oo2 JouNsoN 003 1 SUN AVENUE oo 005 SPRINGFIELD 006 oR 007 1294s 008 (503) 246-2917 00s ($55) 555-1237 010 Donwasésorestrnaa..com 013 HP) INTEL PIT 012 SOLARIS} osri 013 3BASE] ROS 014 7223 126 015 10n00\ 12945) 19001 016 9999 End of RecordThe data in Oracle shows the data in these tables (shown in a sqlplus session) SQL selec # fram YLSCIBTONER: Drs sme soa nore am sump a rm wer mn mou suse: womse uasTiane ALICE Tg SUDORRE Var ALORUREOPDLTED oouoo: nex sx 1 son sve Son oF MS (0 3) 45-2017 (58) $1207 TOMeforentbac.com suas tusk et 1000 292 2 Sl ones: * tra FLSCISTONESHHARNE: D WeANOMIE MAES srsveeree ‘mse Lisrimit var sarupeyteDuTD o0on2 ame osrt Hs ns 30 1 SQL> selec * from PLSCBTORPHRMDNARERRDATED: VOC AMOR var uepopesmoNTEO sna onan: 1 aus sw 1 28APPENDIX B - DB2EXP DRIVER Introduction ‘The DB2EXP jDK driver bridges the gap between jBASE and DB2 with litte or no intervention of the {BASE application developer, so that itis transparent for jBASE applications to access DB2 database. ‘Moving the data from tae traditional ‘hash file’ environment to the RDBMS (e.g. DB2) environmeat brings atrinsic point of which a user should be aware. The ‘multi-value’ envizoament is different to the “RDBMS' environment in the sense that the underlying management of data is different, From a high-level user perspective, they appear (and in fuct are) both the same - “the application retrieves data from the database”. The method by which the database drivers deliver and manipulate the data ‘under the covers" are however very different. Put simply ‘one manufacturers database will yield the same results as performing a ‘COUNT" on the same data in a different manufactures database, but the method by which the count was generated will differ. DB2 Requirements Server Requi ments ‘You must mia the EXCEPTIONS sal script if you plan to wse the EXCEPTIONS table (csewssed later). Client Requirements The DB2 (database) server and jBASE server can reside onthe same machine or on separate mmchines. If the DB2 (database) server and jBASE servers reside on separate machines, it will be necessary to install the DB2 Client software on the jBASE server.DB2 Configuration DB2 Database Objects Create the following objects on the target database ‘Tablespaces Tris recommended that you identify the tablespaces available forthe users that will be connecting tothe DB? database, You muy need to crested addtional tablespaces with large page sizes than the default installation Exception Table (EXCEPTIONS.sql) ‘+ Should be run using the db2 shell command connecting as the user you plan to use. 30Driver Installation ‘The major components of the DB2EXP driver include: LbDB2EXP so and ‘The actual driver files. These files need to reside in the LbDB2EXP sol JBASE ‘lib’ directory (SIBCRELEASEDIR ib) or an (Windows version Ib)DBIEXP. dll appropriate directory in the SFACOBIECTLIST path. ‘and libDB2EXP def) JEDIrivers. Configuration file for holding database and parameter (On non-Windows platforms this information. ‘would have a leading ~.” if placed in the user's SHOME) IDK tool (comprising of ‘These programs should reside in the jBASE ‘bin’ directory executables and libraries). (SIBCRELEASEDIR bin) and BASE ‘lib’ directory (SIBCRELEASEDIRUib). Equivalent bia (included in SPATH) and lib (ineluded in SIBCOBJECTLIST) will suffice, Once the driver has been installed, modify the user's environment to allow the driver to operate. Set the following environment variables: PATH Set to include the ‘SIBCRELEASEDIR bin’ directory JEDI_SOB_NOCLOSE Set to the val * for correct driver operation ‘Asa generic test, if the user cau begin an ‘db2" session, then the DB2EXP driver should operate comrecty. Driver Configuration Befove the driver can operate, you must ereate the configuration file “jEDIdriversini*. Ths file physically holds the configuration parameters, which the driver reads. Create the jEDIdrivers ini” file in one of two places: + fee © Inthe user's home directory (SHOME) It is recommended that you create the file in the “/etc” directory. This allows multiple users access tothe same configuration. It is possible to have both whereby the SHOME version will compliment and override settings from the /ete version, 31JEDIdrivers Configuration The configuration for the DB2EXP driver is controlled by a [DB2EXP] section heading in jEDIdrivers.ini The minimum requirements for connecting to the target DB2 database are: fal ddatabase_connection_string> The database_comection_string could be something like: DSN=TOOLSDBUID=peterfDATABASE=TOOLSDB ‘Note, DATABASE can be omitted and the default database will be used ‘The default parameter is the database connection identifier. You can have as many of these as you like but it is recommended you have a default so that you do not need to specity “... CONNECT: CREATE-FILE command. Additional headers could be: in the testdb = DSN=TOOLSDB UID=peterf;DATABASE=TESTDB ‘You can specify the password in the connection string or on its own (mainly if you need it encrypted). In this case an additional header is required whieh would be DB2EXP_detabase_idenifir eg. (DB2EXP_default] [DB2EXP_testdb] PasswdsEncrypted ~ | Wim9Avx8+Al= passw If the PasswdsEnerypted=l (either locally under [DB2EXP] or [DB2EXP_ciatabase_identifier] or alobally under [General]) the must be encrypted. Refer to the fst part of this manual for information on encrypting password, The following settings may also be required if you need to tailor the rdbms columa types for the appropriate sv types (D, T, TS, C, A, NO, Nu, TXT) date, time, timestamp, char, varchar, number, decimal, text eg. text= BLOBThese types are pre-configured with deft values, Using the Driver This section lists the commands that are specific to the DB2EXP Driver or have extensions for the DB2EXP Driver. Definitions Refore you create a DBIEXP type file, you must have a CSY definition to map each record from dynamic array to relational. For details on this, refer tothe frst part of this manual CREATE-FILE syntax CREATE-FILE filename TYPE=DB: P {TABLEStablename} {CSV=csvdefinition} {EXISTING=YES) {CONNECT=databas=_identifier} tablename defaults to filename cesvdefinition defaults to tablename (this definition is read from the directory specified by the CSVdir parameter in the jEDIdrivers.in fle). ‘character in the database database_indentifier defaults to “default” (refer to the section jEDIdiivers Configuration) ‘Any +" characters in the filename or columns will be converted to a *_ If EXISTING is used then the table is assumed to be an existing table and therefore will not be created (or dropped) during CREATE-FILE/DELFTE-FILE. Example: CREATE-FILE DB2CUSTOMER TYP! IBZEKP CSV=ICUSTON (Executed from a telnet session) nercurg=*: CREATE-FILE DROCUSTOMER TYPE=DBOEXP_CSV=ICUSTOMER C417 J File DEQCUSTOMERID created , tupe = DB2EXP [ 417 J File DE2CUSTOMER created . type = DB2EXP mercury-": 33NOTE: That although the dictionary portion of the above file - DB2CUSTOMER]D — is displayed as typ. DB2EXP it is in facta regular j4 hashed file. You could if you wanted to create them separately thus: CREATE-FILE DICT DB2CU CREATE-FILE DATA DBZCUSTOMER TYPE=DS2ExP C3} This create-file command does tree things: In the above example our CSV looked like this: Column 1D, FIRSTNAME, LASTNAME, ADDRL, ADDR, erry, STATE, 21e, HOMETEL, SYSTEMTYPE, NUMUSERS, LASTMAINT, BALANCE, TOMER 1 CUSTOMER Creates a dictionary for the file (unless DATA has been specified) creates the necessary table(s) on DB2, ‘Writes out a stub file - DB2CUSTOMER ~ to the current working directory which ‘will look Like this: JBC_SOB JedilnitDB2EXP DB2CUSTOMER Ate Width Ty] oO, 2, 10, 24, 20, al, 20, aw aN aN aN aN aN aN aN aN aN aN aN aN, AN, aN, aN, Dr, m2 Association Controlling FARDWARE, 1 HARDWARE EARDWARE HARDAARE BARDWARE|UPDATED, 1 34This definition implies three tables: Primary table (DB2CUSTOMER) which holds all the fields with no Association describe table DEOUSTOMER Type Tape sthena nave Length Scate tulle in Sisim vere 0 Flasmeee isi VaR BO Yes Ustrere Sisim vaRR 2 0 Yes DR Systm VaR BLO Yes gee isle VaR 20 Yes ay. Sisim VaR LO Yee State isi VaR 3 0 Yee ae. Ssi vaRoe 2 ote Avera. Ssim VaR Ie O tee HORKTEL Ssit vaRoe sO tee nL Ssit vane BO Yee BCE ysl TecIM, 2 tee Woe ROHERE SYSIEN INTEGER 40 Yee 13 record(e) selected. Multi-value association - HARDIARE ~ which generates the table DB2CUSTOMER#HARDWARE ora Sys INTEGER SSL RCE 8 Sstin WrRCR 8 Sst VERE . VeROWRENSYS Systm INEGR 4 ee PROMRENCPEATED SYS INTEGER 4 7 recordée) selected. a> ‘Sub-value association ~ UPDATED — within HARDWARE which generates the table DB2CUSTOMER#HARDWARESUPDATED leseribe table TEDCUSTOMERMPROMPRESUPDATED Type Type Length Scale Wills: 1D Ole Oh Oh O Ye Adding some simple data to the table using the BASE Editor:Fle DBDEUSTOMER , Record "00001" Ingert rs OF Record The data in DB2 shows the data in these tables (shown in a db? session): ha 8 eee eZ & i i 2 vecorde) ealected. ko => select + Fron BEOCLSTONERWFEDRE A ated WM EROAEE VI MRORREE POSTED LAGTIVINT 2 f ograerines aoe 36APPENDIX C - OLESQL DRIVER Introduction The OLESQL {DK driver attempts to bridge the zap between jBASE and SQL Server with litle or no intervention of the jBASE application developer. Moving the data from the traditional ‘hash file" envizoameat to the RDBMS (e.g. SQL Server) environment brings with it one intrinsic point of which a user should be aware, The ‘multi-value’ environment is different to the ‘RDBMS’ environment ia the sense that the underlying management of data is different. From a high-level user perspective, they appear (aad in fact are) both the same - “the application retrieves data from the database”. The method by which the database drivers deliver and manipulate the data ‘under the covers’ are however very different. Put simply — ‘manufacturers database will yield the same results as perform performing a “COUNT operation in o2 a ‘COUNT on the same data in different manufactures database, bur the method by which the count was generated will differ. SQL Server Requirements Server Requirements . ‘SQL Server version must be release 7 or higher. Client Requirements ‘© You must install the OLESQL driver on the server that has the jBASE installation ‘+The SQL Server (database) server ean also be on the same machine or on a separate machine on the same network. ‘+ Ifthe SQL Server (databace) server is installed on a separate machine to the |BASE server, it will be necessary to install the SQL Server Client software on the BASE server. SQL Server Configuration It is recommended that you use a case sensitive database to enable the different treatment of record keys like “A and ‘a’SQL Server Database Objects Create the following objects on the target database: User Use any user name and password. The driver from the configuration file reads these credentials. If desired use Windows authentication. DatabaseObjects (CreateExceptions.sql) ‘The OLESQL driver may require an EXCEPTIONS table and accompanying stored procedures installed on the database ‘You can find the *CreateExceptions.sql’ file in the OLESQL ‘zip/tar’ file, which can be run from the Query Analyzer of by using the “asa” command, Installation The major components of the OLESQL driver include: LbOLESQL all and ‘The actual driver files. These files need to reside in the IbOLESQL def JBASE ‘lib’ directory (?%IBCRELEASEDIR®6\lib) or an appropriate directory in the %4/BCOBIECTLIST% path JEDIdrivers ini Configuration file for holding database and parameter, information. JBUISOLE.exe Program used to generate the stored procedures on SQL Server ‘Templates A directory holding skeleton stored procedures used by JBuildOLE JDK tool set (comprising of These programs should reside ia the JASE “bia’ directory executables and libraries). (®6IBCRELEASEDIR®® bin) and BASE ‘lib’ directory (¢BCRELEASEDIR®6\ib), Equivalent bin (included in ‘“6PATH) and lib (included in *6BCOBJECTLIST*) will suffice, 38Once the driver has been installed, modify the users’ environment to allow the driver to operate, Set the following environment variables: oaPATH% Set to include the “°6SQL_SERVER HOME*%\bin’ directory °QJEDL_SOB_NOCLOSE% Set to the value “I' for correct driver operation ‘Asa generic test, ifthe user cau begin an “osql" session, then the OLESQL driver should operate comzectly Configuration Before the driver can operate, you must ereate the configuration file “jEDIdrivers ini". This fle physically hholds the configuration parameters, which the driver reads. Create the ‘jEDIdrivers.ini’ file in one of two places: 96SYSTEMROOT%s In the users home directory (%HOME%) jEDIdrivers Configuration The configuration for the OLESQL driver is contolled by a [OLESQL] section heading in jEDI¢rivers.ini. ‘The minima requirements for connecting to the target SQL Server database is: SQL_Server_user™ ssword> server=chost_address> {name or IP address of server if not the local host) database = “SQL Server database> {If SQL Server database is exported then this is not required} Ifthe PasswdsEnerypted=1 (either locally under [OLESQL] or globally under [General} the password must be encrypted. Refer tothe first part of this manual for information on encrypting password. It is recommended that you create the file in the %6SYSTEMROOT% directory. This allows multiple users access to the same configuration, Using the Driver This section lists the commands that are specific to the SQL. Server Driver or have extensions for the SQL Server Driver. 39Definitions Before you create an OLESQL type file, you must have a CSV definition to map each record from dynamic array to relational. For details on this, refer to the frst part of this manual. CREATE-FILE Syntax CREATE-FILE filename TYPE-OLESQL (TABLE-tablename} (CSV=csvdefinition| (EXISTING=VES) {WRITEOPTS=options) {NOWANCHAR=YES) tablename defsnlts to flename sv definition defaults to tablename (ibis definition is read from the directory specified by the CSVair parameter in the jEDIdrivers in file), Any ‘characters inthe filename or columns will be converted to an ‘_* character in the database IPEXISTING is used then the table is assumed to be an existing table and therefore will not be ereated (or dropped) during CREATE-FILE/DELFTE-FILE. options can be any combination of I (insert), U (update) or D (delete) to restrict updates to the table, This is, normally used with the EXISTING option when interfacing toa table which is not “owned” by the jBASE application. ‘The NOWANCHAR=YES option allows the creation of old (pre-wide character support) style files for backwards compatibility with drivers older than version 4.0.10, Example: CREATE-FILE OLECUSTOMER TYPE-OLESQL CSV-JCUSTOMER (Executed from a telnet session) joh peter? ~ ~->CREATE-FILE OLECUSTOMER TYPE=OLESQL CSV=JCUSTOMER PsP T File OLECUSTOMERID created , type = OLESQL [ 417 ] File OLECUSTOMER created , type = OLESL ish peter? ~ --) 40NOTE: That although the dictionary portion of the above file - OLECUSTOMERID ~ is displayed as typ OLESQL itis in facta regular j4 hashed file, You could if you wanted to create them separately thus: CREATE-FILE DICT OLECU TOMER 1 CREATE-FILE DATA OLECUSTOMER TYPE-OLESQL Cs} CUSTOMER This create-file command does tree things: Creates a dictionary for the file (unless DATA has been specified) Generates a script to run against SQL Server by executing the /BuildOLE command against the osv file: JCUSTOMER.csv Runs the script, which creates the necessary table(s) and stored procedures. Writes our a stub file - OLECUSTOMER ~ to the current working directory which will ook like this IBC__SOB JedilnitOLESQL OLECUSTOMER esv=ICUSTOMER [WANCHAR} In the above example our CSV looked like this: Atte Width Type Association Controlling 0, 10, AN FIRSTNAE, 24, ww LASTNAME, 20, WN ADDRL, 3, 21, AN ADDR2, 4, 20, aN crTy, 5, il, aN STATE, e 3, AN ZIP, 7, 12, aN HOMETEL, 8 16, aN 8, 16, AN 10, 28, aN il, 15, AN, HARDWARE, 1 22, 15, AN, HARDWARE SYSTEMTYPE, 13, 24, AN, HARDWARE, 41