SouthWare s XFD Files and AcuXFD Converter Technology

Size: px

Start display at page:

Download "SouthWare s XFD Files and AcuXFD Converter Technology"

Morgan Perry
5 years ago
Views:

1 SouthWare s XFD Files and AcuXFD Converter Technology July 28, 2004 Copyright SouthWare Innovations, Inc.

2 Table of Contents SouthWare s AcuXFD Technology Overview SouthWare Policies Regarding XFDs Standard XFDs Non-Standard XFDs SalesMark records ExecuMate II statistics Extended Data files Install SouthWare s AcuXFD Files Tips on Using AcuODBC Limitations Tips on Setup Security Notes Example Uses Microsoft Excel Microsoft Query Optional Configuration File Entry for XFD Directory... 9 Special Notes How to find the XFD file you need Special Data Dictionary Fields SouthWare Excellence Series 1

3 SouthWare s AcuXFD Technology Overview Do you want to integrate other database technology with your SouthWare Excellence Series system? With the technology available from Acucobol you have seamless access to other technologies such as relational databases and ODBC connectivity. Acucobol uses translation data dictionaries called "Extended File Descriptors (XFDs)" to map the relationships between standard Acucobol Vision file systems and other types of file systems. An XFD for a file translates the "record-oriented" file structure of COBOL data into the "row/column-oriented" structure used by relational databases. XFDs are produced from the COBOL File Definitions (FDs) by Acucobol s compiler and generally utilize the technical data name structure found in the FDs. These XFD data names are used in the Structured Query Language (SQL) commands typically utilized by database file systems. Acucobol provides the following technology options that utilize these XFD data dictionaries: Acu4GL for INFORMIX Relational Database Management Systems Allows seamless access to INFORMIX databases - dynamically generates SQL queries as alternatives to the normal COBOL data access. Acu4GL for ORACLE Relational Database Management Systems Allows seamless access to ORACLE databases - dynamically generates SQL queries as alternatives to the normal COBOL data access. Acu4GL for SYBASE Relational Database Management Systems Allows seamless access to SYBASE databases - dynamically generates SQL queries as alternatives to the normal COBOL data access. Acu4GL for ODBC (Open Data Base Connectivity) databases Allows seamless access to ODBC databases - dynamically generates SQL queries as alternatives to the normal COBOL data access. Acu4GL for Microsoft SQL databases Allows seamless access to MSSQL databases - dynamically generates SQL queries as alternatives to the normal COBOL data access. AcuODBC Allows Acucobol Vision file systems to be accessed as ODBC databases by ODBC-compliant products such as Microsoft Word, Excel, Query, and Access. With SouthWare s AcuXFD Converter Technology you improve Acucobol s standard XFD technology: You get XFDs that have the same non-technical data names used by SouthWare s ReportMate tool. Instead of a data name like "AR-CUS-NUMBER" you get a name like "CustomerNumber" which is easier for users to identify. This is also the only way to get upper/lowercase names since Acucobol s compiler always puts uppercase names into XFDs. The actual name of the XFD file and the external file name referenced by the XFD is modified to reflect SouthWare s use of a file name that is prefixed by the Company ID. You can create custom XFDs for the variable Extended Data files you define in SouthWare. SouthWare Policies Regarding XFDs The XFD s that are released will have a name that matches the exact name of the external file name of the file. In earlier revisions of SouthWare (prior to Revision 8) XFD s were often named after the FD Copy Library instead of the External File Name. SouthWare Excellence Series 2

4 When XFDs are used with the Acu4GL product to create database files (i.e. MS-SQL, Oracle or Sybase) the whole definition of the database tables is related to the XFDs and any changes to an XFD has the potential to make the data in the Database tables inaccessible. Both the SouthWare programs that create, update and read this data and the other utilities that access the data will be impacted by any change to the XFD. This means that SouthWare and Developers that make any change to a file s FD or Select logic will have to be very careful to identify these changes so that corresponding changes can be made to the XFD and to Database schema related to this file. In most cases any of these changes will require either some manual changes to the schema of the database on the users computer or in the case of replicated data from the Database Director product to create a new replicated file that matches the modified file definition (as defined in both the FDs and XFDs). Standard XFDs 1. SouthWare produces the standard XFD files by compiling a special program for each application with the necessary compiler commands. This special program is named xx4gldd where "xx" is the application prefix (such as AP, AR, GL, etc.). The only purpose of the program is to provide an easy way to compile one program that contains the files to be made available for the application. The standard XFD files contain technical specifications about keys, field positioning, field types, field descriptions, etc. Notes: The files included for each application are those that SouthWare believes are likely to need XFD Data Dictionaries. The list of available XFDs may change in future releases. See the list of Standard XFDs later in this document. Certain files require special handling. For example, there are files such as the G/L interface file that utilize the same FD for multiple external files, but need to have multiple XFDs. SouthWare performs manual steps to handle these special situations. 2. SouthWare runs the AXACUXFD converter program to convert all the XFD files for standard SouthWare applications. The program asks for: - a file name of a text file that contains the names of the FDs to convert (names should include the pathname if FDs are in different directories) - the directory for the XFDs The program then: a. builds a sort file of SouthWare Data Dictionary file names and their related FD names b. for each FD builds a temporary file with the FD data names and any special COBOL datanames assigned specifically for XFD use c. adds to the temporary file the related descriptions from the SouthWare Data Dictionary d. reads each XFD file and - replaces the external file name with the name contained in the SouthWare Data Dictionary file record - finds each COBOL dataname, looks for it in the temporary file, and replaces the COBOL dataname with the adjusted SouthWare description (remove any spaces or subscripts from the Data Dictionary description). If it doesn t find a match, it leaves the COBOL dataname as the field description. SouthWare Excellence Series 3

5 BEFORE (RCUST.XFD) # rcust.xfd - generated by ACUCOBOL-GT v # Generated Tue Oct 24 07:41: # [Identification Section] XFD,04,AR-CUSTOMER-FILE,RCUST, ,00621,006 # [Key Section],0,0,000 AR-CUS-NUMBER,1,020, AR-CUS-GROUP-NUMBER AR-CUS-NUMBER,1,033, AR-CUS-SALESMAN AR-CUS-NAME,1,030,00023 AR-CUS-NAME,1,0,065 AR-CUS-ZIP-CODE,1,020,00200 AR-CUS-PHONE-NUMBER # [Condition Section] 000 # [Field Section] 0068,00072, ,00621,16,00621,+00,000,999,AR-CUSTOMER-RECORD 00000,00020,16,00020,+00,000,999,AR-CUS-GROUP-ID 00000,000,16,000,+00,000,000,AR-CUS-GROUP-NUMBER 000,000,16,000,+00,000,999,AR-CUSTOMER-KEY 000,000,16,000,+00,000,000,AR-CUS-NUMBER 00020,00033,16,00033,+00,000,999,AR-CUS-SALESMAN-KEY 00020,00003,16,00003,+00,000,000,AR-CUS-SALESMAN 00023,00030,16,00030,+00,000,000,AR-CUS-NAME 00053,022,16,022,+00,000,999,AR-CUS-ADDRESS (etc.) AFTER (RCUST.XFD) # rcust.xfd - generated by ACUCOBOL-GT v # Generated Tue Oct 24 07:41: # # [Identification Section] XFD,04,AR-CUSTOMER-FILE,RCUST,12 ## Modified: 10/24/00 07:46:30 by SouthWare's AcuXFD Converter ## Input xfd File Name: rcust.xfd ## Output xfd File Name: rcust.xfd ## FD COPY FILE Name: ARCUSTOM.FD AR-CUSTOMER-FILE ## Data Dictionary #: AR Name: Customer File ## RM External File Name: xxxrcust 00621,00621,006 # [Key Section],0,0,000 CustomerNumber,1,020, GroupNumber CustomerNumber,1,033, SalespersonNumber CustomerName,1,030,00023 CustomerName,1,0,065 ZipCode,1,020,00200 PhoneNumber # [Condition Section] 000 # [Field Section] 0068,00072, ,00621,16,00621,+00,000,999,AR-CUSTOMER-RECORD 00000,00020,16,00020,+00,000,999,AR-CUS-GROUP-ID 00000,000,16,000,+00,000,000,GroupNumber 000,000,16,000,+00,000,999,AR-CUSTOMER-KEY 000,000,16,000,+00,000,000,CustomerNumber 00020,00033,16,00033,+00,000,999,AR-CUS-SALESMAN-KEY 00020,00003,16,00003,+00,000,000,SalespersonNumber 00023,00030,16,00030,+00,000,000,CustomerName 00053,022,16,022,+00,000,999,AR-CUS-ADDRESS (etc.) This process takes quite a while to run because of the volume of data, and it requires access to source code. That s why SouthWare runs this process so you don t need to. 3. SouthWare then releases the converted files as the SouthWare Standard XFDs for standard files. These contain the same technical information as the standard XFDs except: - the external file name reflects the file name found in each company sub-directory - the field names utilize the SouthWare Data Dictionary descriptions instead of the COBOL data names. Non-Standard XFDs 4. There are also non-standard files in SouthWare that allow you to define the descriptions and types of fields and change them at any time. These include Extended Data files, SalesMark record files, and ExecuMate II statistics files. SouthWare Excellence Series 4

6 SalesMark records SalesMark records are given a generic XFD (msupp.xfd) with data names such as: F1-30ALPHA for the 1st field (30 chars) F6-20ALPHA for the 6th field (20 chars) F13-8NUMERIC for the 13th field (8 digits) etc. The different types of records (Client, Prospect, etc.) have different field names within SouthWare, but the record types are all in the same file. This "msupp.xfd" file is distributed with the other standard XFDs. We chose not to create multiple XFDs since all records of all types will always appear when you access data with a product such as AcuODBC (since AcuODBC can t screen records). In some products you could create queries or forms with specific field names for a particular record type, then use record selection criteria to include only records that match the type. ExecuMate II statistics ExecuMate II statistics records are given a generic XFD (xmst2.xfd) with data names such as: AMOUNT-1 for statistics amount 1 AMOUNT-2 for statistics amount 2 etc. The different types of statistics have different field names within SouthWare, but the types are all in the same file. This "xmst2.xfd" file is distributed with the other standard XFDs. We chose not to create multiple XFDs since all records of all types will always appear when you access data with a product such as AcuODBC (since AcuODBC can t screen records). In some products you could create queries or forms with specific field names for a particular record type, then use record selection criteria to include only records that match the type. Extended Data files The creation of specific XFDs related to each Extended Data file is handled on your system at the same time that the SouthWare Data Dictionary is updated for these custom fields. When you define Extended Data fields you are asked if you want to update the ReportMate Data Dictionary when you exit the program. When you say "Yes" the program moves the descriptions and other information to SouthWare s Data Dictionary. If you have loaded the SouthWare Extended Data templates (xdmaster.tem, xdtrans.tem, xdhist.tem and xdusrkey.tem) into your SouthWare run directory (example: c:\swrun} the program will then try to create appropriate XFDs for your Extended Data record types. The program checks to see if there is a default configuration XFD-DIRECTORY. If there is not a default directory the converter program asks you to enter the directory for the XFDs to be created. The program then: - Removes all XFD files for Extended Data. - Creates an XFD file for each related file in the Data Dictionary based on the information in the Data Dictionary. The naming convention for the XFD matches the SouthWare filename: SouthWare Excellence Series 5

7 Install SouthWare s AcuXFD Files To use SouthWare s AcuXFD Technology you need the following components installed: Standard SouthWare XFDs should be loaded into a separate XFD directory (or directories). Because it will be necessary to manage future changes to XFD files it is suggested that only XFDs that are actually being used be loaded into the users XFD Directory. (See Note on Page 3). The distribution media has several subdirectories that correspond to different SouthWare Applications. For example: ap, ar and gl. The XFD files that correspond to each application are in that subdirectory. In addition each sub-directory includes an additional sub-directory orig.xfds that contains the XFD files that were created by the AcuCorp compiler before they were modified by replacing the field names with the ReportMate field names. The orig.xfds files should not be needed, but are available for backup and debugging purposes. A properly-installed Acucobol product (such as AcuODBC or AcuODBC Server) that utilizes XFDs should be ready to run. If you need XFDs for Extended Data files: - The xdmaster.tem, xdtrans.tem, xdhist.tem and xdusrkey.tem template files must be loaded into your run directory (example c:\swrun) Optionally you should set up the default XFD directory in your Acucobol configuration file (see separate section in this document). Here are suggested steps to accomplish this setup: 1. Create the XFD subdirectory(ies) on your system. If you will load all XFDs into a single directory Use a name such as "SWXFD" to make it easily identifiable. MKDIR C:\SWXFD or mkdir /usr/swxfd If you will load XFDs into multiple directories Be aware that the more XFD Files you have in a single directory the slower performance will be. It is recommended that you create a subdirectory that contains only those XFD Files that you will actually be using.... Anther option is to combine the xfd files for multiple applications into a single directory. Remember that the more XFD Files you have in a single sub-directory the slower the ODBC processes will execute. 2. Copy the XFD files from the SouthWare media into the new directory(ies). The distribution media for the XFD files includes application subdirectories. In addition under each subdirectory there is an additional subdirectory (orig.xfd) that contains the XFD files that were produced by the compiler before they were modified to include the ReportMate descriptions. COPY D:\ap\*.XFD C:\SWAPXFD COPY D:\ar\*.XFD C:\SWARXFD SouthWare Excellence Series 6

8 COPY D:\gl\*.XFD C:\SWGLXFD.... or corresponding UNIX commands 3. Copy the Extended Data template files to your run directory: COPY D:\*.tem C:\swrun 4. Load your AcuCorp product as per the AcuCorp documentation 5. Add the XFD-DIRECTORY directive to your Acucobol configuration file as explained in a later section of this document. Tips on Using AcuODBC AcuODBC provides ODBC drivers that allow ODBC products to access Acucobol Vision files via XFD mapping. With AcuODBC you can easily access SouthWare data from Microsoft Windows applications such as Microsoft Word, Excel, Access, and MS Query. Other Windows products may work with AcuODBC, but you should test them with AcuODBC and SouthWare files before assuming you can use them. See the "XFD Files - AcuODBC Connection Notes" section in this document for a list of errors we experienced. Limitations There is no limit of XFD files per directory, but the more XFD files that you have in a single directory the slower accessing the records will be. If you followed our suggested installation procedures you created multiple separate directories to load all the XFDs. In SouthWare s testing we encountered limitations in the ODBC standard that might prevent you from accessing large records such as Excellence Period History - the records are too large for ODBC. See the "XFD Files - AcuODBC Connection Notes" section in this document for a list of errors we experienced. You may also encounter other undocumented limitations. Tips on Setup Install AcuODBC as described in the AcuODBC documentation. You must set up Data Source Names (DSN) through the Windows Control Panel. We recommend the following setup: Open the Windows Control Panel and then open Administrative Tools and double-click on ODBC Data Sources. Depending on the version of Windows you have, ODBC Data Sources may be accessible from the control panel. Set up a Master Data Source Name for each XFD directory - Select to "Add" User DSN as the Driver - Select AcuODBC or AcuODBC Driver). - Enter a Data Source Name - Example: SouthWare IS and SV Files for DM Company" - Enter the XFD Directory - Example: C:\SWISXFD and C:\SWSVXFD - Enter the Data Directory SouthWare Excellence Series 7

9 - Example: C:\SWRUN\DM for the DM Company. If you will be accessing any AL files via ODBC, you should add C:\SWRUN to the Data Directory list. - For Data File Extention enter.fil It is not necessary to access the other tabs unless you have installed AcuODBC Server or AcuServer. NOTE: If you have multi-companies, it is easier to create a separate User DNS for each company. It is also important to create each company s XD XFD s in a separate directory to ensure that the fields defined are accurate. Security Notes With the AcuODBC driver and a compatible ODBC product you can access any SouthWare files for which you have an XFD. All SouthWare application security features are circumvented by ODBC!!! If you allow a user access to SouthWare files via AcuODBC you may only control their access by using non-southware methods such as: - removing XFDs for files they shouldn t see - removing lines from XFDs for fields they shouldn t see - creating separate XFD directories and Data Sources that contain only XFDs they should be able to use - using security or permission features available with your operating system or ODBC product The AcuODBC driver allows a user to create a Data Source that allows write permission ("N"o to Read-Only). If you write to SouthWare files via AcuODBC you are solely responsible for the validation of the data!!!! SouthWare programs are not in control of changes you make with ODBC, and you could create errors that are unrecoverable and unsupportable. WE RECOMMEND THAT YOU DO NOT USE AcuODBC TO WRITE TO SOUTHWARE FILES!!! If you find it necessary to ignore this recommendation, we strongly advise that you research the creating and updating of these records in the SouthWare source code to make sure that you are not creating problems in the SouthWare data files that will be very difficult to trace and fix!!! Example Uses Here are some notes on using AcuODBC in Microsoft Windows products. Please see the "Working with Windows Applications" chapter in the AcuODBC documentation for detailed instructuions on how to access data via other Microsoft products. Microsoft Excel (spreadsheet) Here s how to access SouthWare data from within a Microsoft Excel spreadsheet: - Position the cursor in the cell that should contain the first incoming data field Select the Data via Microsoft Query SouthWare Excellence Series 8

10 - Select Data, Import External Data, New Database Query (this calls the Microsoft Query function) - Select the appropriate SouthWare Data Source to Use ("SouthWare I/S and S/V Files for DM Company" in our example above) - A list of the SouthWare Table Names (files) then appears (see the last section in this document for a description of each file). - Select to Add the Table you want to use, then Close the list. - A scrolling list of the fields contained in the file appears within Microsoft Query. Select each field you want to send to the spreadsheet by double-clicking on the field in the list. Each field you select will appear as a column on the bottom of the screen. - After you have selected all fields to be sent to the spreadsheet you may add selection Criteria if you want to include only selected records. Send the data back to the spreadsheet - When you re ready to send the columns of data back to the spreadsheet select File, Return Data to Microsoft Excel from the menu. - The data is placed into columns of the spreadsheet. - Now you re ready to use it! To Refresh SouthWare data in a spreadsheet - If you want to get current values for the SouthWare data: - position the cursor within one of the cells containing SouthWare data - select Data, Refresh Data This will update the cells that were originally created from SouthWare data. Microsoft Query (inquiry tool) (See the "Select the Data via Microsoft Query" notes under Microsoft Excel.) Note: When you install Microsoft Office you must select to install Data Access files in order to get MS Query loaded onto your system. Optional Configuration File Entry for XFD Directory You may create a line in your Acucobol configuration file that defines the directory that contains your XFD files. This directory is used by the SouthWare Extended Data XFD build process to know where to put the XFDs. If you don t create this configuration line the process will ask you to define the directory each time you run it. Note: If you loaded your XFDs into multiple directories you should pick the directory where you want Extended Data XFDs to go. Use any text editor to edit the Acucobol configuration file (default name of "cblconfi") in the "etc" directory on your system. Enter the following line: XFD-DIRECTORY = directory where directory is the full pathname to the directory for the XFD files. For example, on a UNIX system you might add the entry: XFD-DIRECTORY = /usr/swrun/swqqxfd SouthWare Excellence Series 9

11 On a DOS/Windows system you might add the entry: XFD-DIRECTORY = C:\swrun\SWqqXFD Special Notes How to find the XFD file you need - Access SouthWare s Environment Manager (XX05) - View files for a specific application - The XFD name will match the SouthWare filename NOTE: Most SouthWare files have a corresponding XFD file. There are some applications and files where SouthWare has not created a corresponding XFD file (examples include: Notes files, TaskWise task details and certain AL files). Special Data Dictionary Fields: There may be a field that is viewable in a SouthWare program or in the SouthWare Data Dictionary that does not exist in the XFD file. Often, SouthWare has added special data dictionary fields to enhance ReportMate and other SouthWare tools. These fields are either calculated fields or fields that exist in other files. Accessing the Environment Manager (XX05) and viewing a Data Dictionary field will help you to determine if that field actually exists in a file. If a field does not exist in the file it will have a Cobol Dataname that begins with WS. This information exists in the SouthWare Data Dictionary and can be printed on a ReportMate report using RM02 as the primary file. SouthWare Excellence Series 10

Acu4GL COBOL-to-RDBMS Interface

Acu4GL COBOL-to-RDBMS Interface EXECUTIVE OVERVIEW Acu4GL is a patented interface technology designed to bridge the worlds of third-generation COBOL and fourth-generation Structured Query Language (SQL).