Micro Focus Relativity Designer for Windows
Micro Focus Product Name

Welcome to Relativity

  • Relativity Overview
  • Getting Started
Online resources

Online resources

  • Micro Focus Home Page
  • Micro Focus Channel on YouTube
  • Micro Focus SupportLine
  • Micro Focus Product Updates
  • Micro Focus Knowledge Base
  • Micro Focus Community Forums
  • Micro Focus Training Store
Provide feedback

Provide feedback

  • Contacting Micro Focus
  • Email us feedback regarding this Help


Relativity Overview

The Relativity product set enables the construction of a true relational database using existing COBOL application data. Relativity provides a full-featured, Windows Open Services Architecture (WOSA), Open Database Connectivity (ODBC)-compliant relational database engine. Thus, Relativity allows SQL-based client access to COBOL application data without moving, converting, replicating, or re-engineering COBOL data files.

With Relativity providing SQL-based access to COBOL data files, any ODBC-enabled client/server development application or tool can be chosen to build applications for ad hoc reporting, decision support, and specialized data processing functions. Relativity enables any working application to benefit from client/server technology without rewriting or migrating that application.

The Relativity product set consists of three main software components:

  • Relativity Designer
  • Relativity DBA
  • Relativity Database Management System
Parent topic: Micro Focus Relativity Designer for Windows


Relativity Designer

The Relativity Designer is an interactive, Windows-based tool that enables the COBOL application developer to define and maintain a relational database system of tables using COBOL data.

The Relativity Designer creates the Relativity catalog by performing the following functions:

  • Automatically extracts the definitions of data files from the COBOL programs into the Relativity catalog.
  • Collects information regarding the data from the application developer.
  • Allows the developer to define relational tables from existing COBOL data items within records of existing COBOL files.

If an owner group has been assigned to the catalog, only users who are members of that owner group may open the data source associated with the catalog using the Relativity Designer. Assignment of an owner thus protects the sensitive data in the catalog exposed by the Relativity Designer from access by users who are not owners. A password-protected log on procedure validates user identities whenever a Relativity data source is opened, as explained in Providing Data Security.

Parent topic: Relativity Overview
Related concepts
Relativity DBA
Relativity Database Management System


Relativity DBA

The Relativity DBA (Database Administrator) is an interactive, Windows-based tool that enables the system administrator at the end-user location to maintain and manage the Relativity database and the security of the Relativity database.

The Relativity DBA provides the following functions:

  • Defining and authorizing users of the database.
  • Restricting the view of the data for individual groups of users.
  • Maintaining the linkages between tables and physical COBOL data files.
  • Defining date constants.
  • Merging security and connection information into a new catalog (an optional function controlled by the catalog developer).
  • Producing reports on security and connections.

The Relativity DBA can be used only by users who have the Use Administrator privilege set for the catalog, or by the catalog owner (who has all privileges set by default). The owner may grant this privilege to one or more administrative groups - see Defining Group Privileges.

Parent topic: Relativity Overview
Related concepts
Relativity Designer
Relativity Database Management System
Related reference
Defining Group Privileges


Relativity Database Management System

The Relativity Database Management System (DBMS) connects Windows client-based tool products to COBOL data files. It processes SQL requests from the ODBC-enabled application (or tool) and performs the necessary actions to respond to the request with data obtained from the COBOL data files.

The Relativity DBMS comes in two variants: single-tier and a client/server. The single-tier product is named the Relativity Data Manager. The client/server product is named the Relativity Data Client and Relativity Data Server.

Relativity Data Manager

The Relativity Data Manager is a single-tier version of the Relativity DBMS. By single-tier, we mean that the product is installed on a single machine. In this configuration, the COBOL data files are installed on the same machine as the ODBC-enabled application and the Relativity Data Manager.

Relativity Data Client and Relativity Data Server

The Relativity Data Client and Relativity Data Server are a client/server version of the Relativity DBMS. In this configuration, the COBOL data files are typically not on the same machine as the ODBC-enabled application. In this case, the Relativity Data Client is installed on the same machine as the ODBC-enabled application, and the Relativity Data Server is installed on the same machine as the COBOL data files. The Data Server needs to be installed only once and on only the server machine, that is, the machine with the COBOL data files. The Data Client needs to be installed on each client machine that needs access to the data on the server machine. The Data Client sends the SQL requests from the ODBC-enabled application to the Data Server, which then processes the requests and returns only the resulting rows to the Data Client, which in turn returns them to the ODBC-enabled application.

Parent topic: Relativity Overview
Related concepts
Relativity Designer
Relativity DBA


Micro Focus End User License Agreement

  • RELATIVITY DATA MANAGER v12.17
  • RELATIVITY DATA SERVER v12.17
  • RELATIVITY DBA v12.17
  • RELATIVITY DESIGNER v12.17
  • RM/COBOL DEPLOYMENT SYSTEM v12.17
  • RM/COBOL DEVELOPMENT SYSTEM v12.17
  • RM/COBOL RUNTIME SYSTEM v12.17
  • RM/COBOL SDK v12.17
  • RM/INFOEXPRESS SERVER v12.17
  • WOW EXTENSIONS v12.17
  • XCENTRISITY BUSINESS INFORMATION SERVER v12.17
  • XML EXTENSIONS V12.17

IMPORTANT: LICENSOR IS PROVIDING THIS LICENSED SOFTWARE TO LICENSEE (THE ORIGINAL PURCHASER EITHER AS AN INDIVIDUAL OR ON BEHALF OF ANOTHER LEGAL ENTITY AS ITS EMPLOYEE OR AUTHORIZED AGENT) FOR ITS USE SUBJECT TO LICENSEE’S AGREEMENT TO THE TERMS AND CONDITIONS SET FORTH BELOW. THESE TERMS AND CONDITIONS MAY BE DIFFERENT FROM THE END USER LICENSE AGREEMENT(S) THAT ACCOMPANIED EARLIER RELEASES OF THE LICENSED SOFTWARE. PLEASE READ THEM CAREFULLY TO ENSURE FULL UNDERSTANDING BEFORE PROCEEDING, AS THEY MAY CONTAIN ADDITIONAL RESTRICTIONS ON YOUR USE OF THE SOFTWARE. PLEASE DIRECT ANY QUESTIONS TO THE MICRO FOCUS LEGAL DEPARTMENT AT LEGALDEPT@MICROFOCUS.COM. IF YOU DO NOT AGREE TO THE TERMS AND CONDITIONS OF THIS LICENSE AGREEMENT, YOU WILL NOT BE AUTHORIZED TO USE THE LICENSED SOFTWARE. BY CLICKING THE ACCEPT BUTTON OR SIMILAR ACCEPTANCE MECHANISM DURING INSTALLATION, OR BY COPYING OR USING THE LICENSED SOFTWARE, LICENSEE ACKNOWLEDGES THAT IT HAS READ THIS LICENSE AGREEMENT, UNDERSTOOD IT, AND AGREED TO BE BOUND BY ITS TERMS AND CONDITIONS. THE LICENSED SOFTWARE IS LICENSED NOT SOLD.

For this End User License Agreement ("License Agreement") the following terms shall have the meanings given below:

"Documentation" means the Licensor user documentation that is included with the Licensed Software.

"Licensee" means the single legal entity or person that rightfully acquires the Licensed Software from Licensor or from a distributor or reseller of Licensor.

"License Options" means those license options set forth in Annex 1 to this License Agreement.

"Licensor" means the Micro Focus legal entity authorized to license the Licensed Software in the country in which Licensee acquires the Licensed Software.

"Licensed Software" means the object code version of the Licensor computer program(s) listed above, their Documentation, and other supplemental materials, as provided to Licensee by Licensor, including but not limited to any software security keys relating thereto. The Documentation may be delivered electronically and may only be available in the English language. The Licensed Software will be accompanied by a license key where required for activation and use of the Licensed Software. The Licensed Software shall also include, and this License Agreement shall govern the use of any update to the Licensed Software that Licensee receives pursuant to a separate support and/or maintenance purchase as described in Section 6 below, unless such update contains or comes with a different end user license agreement, in which case such end user license agreement shall supersede this License Agreement and govern the use of such software license without need for a mutually executed amendment to this License Agreement as set forth in Section 17 of this License Agreement. This License Agreement does not grant Licensee the right to any updates to the Licensed Software unless provided by Licensor under Section 6 and/or Section 7 below.

"Product Order" means a document that has been (i) executed by Licensee describing each Licensed Software license to be purchased, and (ii) accepted by Licensor. Licensor will accept the Product Order by either confirming Licensor's acceptance in writing or by delivering the Licensed Software to Licensee, whichever occurs first. A Product Order may also mean a written quote, or if referred to as such, a solution order, issued by Licensor describing each Licensed Software license purchased that is accepted by Licensee within the validity period of the quote either by Licensee executing and returning the quote or a solution order, to Licensor, by Licensee issuing a purchase order or other written confirmation of acceptance to Licensor in conformance with the quote, and/or by Licensee paying to Licensor all fees set forth in the quote. Each Product Order shall constitute a separate agreement and shall incorporate therein this License Agreement. In the event of any conflict between the terms and conditions of this License Agreement and the terms and conditions of any Product Order, the conflicting terms and conditions of the Product Order shall govern. In no event shall any terms and conditions contained in a purchase order or similar document issued by Licensee in connection with this License Agreement or with a Product Order apply and any such document issued shall be only for the administrative purposes of identifying the Licensed Software ordered, the number of licenses, and the price to be paid and shall have no other legal effect. Licensor for purposes of this paragraph shall mean Licensor or, if applicable, one of Licensor's authorized resellers from whom Licensee purchases the Licensed Software, provided however that any conflicting or additional terms in a Product Order accepted by an authorized reseller of Licensor shall have no effect unless such terms have been agreed by Licensor in writing.

"Warranty Period" means a period of ninety (90) days from delivery of the Licensed Software to Licensee.

  1. GRANT OF LICENSE; LICENSE CONDITIONS. For payment of the applicable non-refundable license fees identified on the Product Order and subject to Licensee's compliance with the terms and conditions set forth in this License Agreement, Licensor grants solely to Licensee, as an end user, a personal, perpetual (unless a subscription/term license has been purchased by Licensee), non-transferable, non-sublicensable and non?exclusive license to use the Licensed Software solely for its own internal use and benefit. Licensee's use and operation of the Licensed Software and the license grant provided to the Licensed Software is subject to Licensee being in possession of a valid license key where required for the Licensed Software to run. Licensee agrees that Licensor is not liable or responsible for lost or broken license keys or media or the provision of replacement license keys or media and/or new license keys or media unless Licensee is current on support and maintenance for the applicable license and then only to the extent set forth in the applicable annual support and/or maintenance agreement and only to the extent Licensor then has sufficient rights from any applicable third party suppliers, if necessary, to provide such replacement. If not current on support and maintenance for the applicable license, replacement or new license keys or media may be available for purchase at Licensor's then current list fees for applicable new licenses.

    Different License Options are available from Licensor as set forth or referred to in Annex 1. The applicable License Option and license count to be purchased by Licensee for the Licensed Software shall be identified in the Product Order or otherwise identified in writing by Licensor. Licensed Software is also subject to additional terms and conditions as set forth in the "Specific Software Terms" located in Annex 2. Any conflicting terms and conditions shall be resolved according to the following order of precedence: Annex 2, Annex 1, and the main body of the License Agreement.

  2. USE RESTRICTIONS. Except as may be otherwise specifically permitted in Annex 1 or Annex 2 to this License Agreement, Licensee agrees not to:
    • 2.1 Copy and/or distribute the Licensed Software, in whole or in part, for internal use without paying Licensor the applicable additional fees required by Licensor, except (i) for making a reasonable number of archival back-up copies; or (ii) as expressly authorized by Licensor in writing; or (iii) for making a reasonable number of copies of the Documentation supplied to Licensee by Licensor in electronic form. Licensee shall reproduce and affix all copyright and other proprietary rights notices appearing in or on the Licensed Software, including notices of all third party suppliers.
    • 2.2 Use the Licensed Software for timesharing, facilities management, outsourcing, hosting, service bureau use, or for providing other application service (ASP) or data processing services to third parties or for like purposes.
    • 2.3 Modify the Licensed Software or provide any person with the means to do the same.
    • 2.4 Create derivative works of the Licensed Software, or translate, disassemble, recompile or reverse engineer the Licensed Software or attempt to do so (except to the extent applicable law specifically permits such activity).
    • 2.5 Alter, destroy, or otherwise remove any proprietary notices or labels on or embedded within the Licensed Software or Documentation.
    • 2.6 Use the Licensed Software in a manner other than as specifically permitted in this License Agreement.
  3. AUDITS. Licensor or an Auditor (as defined below) has the right to verify Licensee's compliance with this License Agreement (and please see Micro Focus License Compliance Charter - http://supportline.microfocus.com/licensing/licVerification.aspx). Licensee agrees to:
    • A. Implement internal safeguards to prevent any unauthorized copying, distribution, installation, or use of, or access to, the Licensed Software and associated support and maintenance, or breach of the terms or conditions of this License Agreement;
    • B. Take all necessary steps to destroy or erase all Licensed Software codes, programs and other proprietary information before disposing of any media containing the Licensed Software;
    • C. Keep records sufficient to certify Licensee's compliance with this License Agreement including serial numbers and license keys of the Licensed Software, hypervisor logs where applicable, and the location, model (including quantity and type of processor) and serial number of all machines on which the Licensed Software is installed or from which the Licensed Software is accessed, and the names (including corporate entity) and number of users that are accessing the Licensed Software, and, upon request of Licensor, provide and certify metrics and/or reports based upon such records and account for, among other things, numbers of copies (by product and version) and network architectures as they may reasonably relate to Licensee's licensing and deployment of the Licensed Software and associated support and maintenance;
    • D. Upon Licensor's request, Licensee shall furnish Licensor or an independent auditor chosen at Licensor's sole discretion ("Auditor"), within seven (7) days of the request, with a completed questionnaire provided by Licensor or the Auditor, and with a written statement, in a format required by Licensor, signed by a director of Licensee, certifying the accuracy of any information provided;
    • E. Allow a Licensor representative or an Auditor to inspect and audit Licensee's computers and records, during Licensee's normal business hours, for compliance with the licensing terms for Licensor's software products and associated maintenance. Upon Licensor's (and Auditor's if applicable) presentation of their signed written confidentiality statement form, Licensee shall fully cooperate with such audit and provide any necessary assistance and access to records and computers; and
    • F. In the event that Licensee has or at any time has had unlicensed installation, use of, or access to the Licensed Software or has otherwise breached the license granted (a "Non-Compliance"), without prejudice to any other rights or remedies Licensor may have, including without limitation injunctive relief, Licensee shall, within thirty (30) days, purchase sufficient licenses and or subscriptions and associated support and maintenance to cure the Non-Compliance, without benefit of any otherwise applicable discount, by paying Licensor's current (as of the date of such additional purchase) list license fees and 12-month support and maintenance fees to Licensor for such additional licenses, plus Licensor's current (as of the date of such additional purchase) list term license and support and maintenance fees and interest (compounded at 1.5% monthly or the maximum rate permitted by applicable law if lower) for such additional licenses for the time period from the commencement of the Non-Compliance until payment of the aforementioned fees. The aforementioned interest shall be payable even if an invoice was not issued at the time the Non-Compliance commenced. If a material license shortfall of 5% or more is found, Licensee shall also reimburse Licensor for the reasonable cost of such audit in addition to other amounts due. The obligations in this Section 3 shall apply to both Licensee's Non-Compliance and any third party's Non-Compliance.
  4. DOCUMENTATION. One (1) electronic copy of Licensor's standard Documentation, describing Licensor's recommended use and application of the Licensed Software, will be furnished or made available on Licensor's website free of additional charge to Licensee by Licensor with the Licensed Software. Printed copies of any Documentation may be available for purchase from Licensor or its authorized distributors. Additional copies of standard Documentation may be available on Licensor's website.
  5. TERM OF LICENSE. This License Agreement and Licensee's license for the Licensed Software is perpetual, unless a subscription/term license has been purchased by Licensee (in which case the term of the license shall be as set forth in the Product Order, specified in Annex 1 or Annex 2, or as otherwise agreed in writing between the Licensee and Licensor), and is subject to earlier termination as provided in this Section 5. If Licensee has purchased a subscription/term license, Licensee's license to the Licensed Software shall automatically terminate upon expiry of such subscription/term. Licensor may terminate this License Agreement and Licensee's license to the Licensed Software immediately by giving Licensee written notice of termination in the event that either (i) Licensee breaches any term or condition of this License Agreement and Licensee has failed to remedy such breach within ten (10) days of the date of notice from Licensor to Licensee or (ii) Licensee is wound up, has a receiver appointed or has applied for or enters into liquidation or bankruptcy or analogous process or processes. Termination shall be without prejudice to any other rights or remedies Licensor may have. In the event of any termination Licensee will have no right to keep, access, or use the Licensed Software or any copy of the Licensed Software for any purpose and Licensee shall destroy and erase all copies of such Licensed Software in its possession or control, and forward written certification to Licensor that all such copies of Licensed Software have been destroyed or erased. Termination shall not entitle the Licensee to any refund or reimbursement of any kind of previously paid fees. The rights and obligations of the parties contained in Sections 3, 8, 9, 10, 11, 12, and 13, and other sections that by their nature are intended to survive, will survive the termination or expiration of this License Agreement.
  6. SUPPORT AND MAINTENANCE. Where Licensee purchases support and/or maintenance services, Licensee's initial support and/or maintenance term will begin upon delivery to Licensee of the Licensed Software and continue for one (1) year thereafter (or the length of the term if less than a year for any subscription/term license) unless otherwise specified in the applicable annual support and/or maintenance agreement, Product Order, or other written agreement executed between Licensor and Licensee. Where Licensee purchases support and/or maintenance for any Licensed Software, Licensee hereby agrees that it shall purchase such support and/or maintenance services for all of Licensee's licensed units of such Licensed Software product. Support and/or maintenance services provided by Licensor will be subject to Licensor's then current applicable standard annual support and/or maintenance agreement unless otherwise agreed by the parties in writing.
  7. LIMITED WARRANTY. Licensor warrants for the Warranty Period (i) that if the Licensed Software is supplied via media, then the media will be free from defects in materials or workmanship under normal use and (ii) that the copy of the Licensed Software delivered to Licensee conforms in all material respects to the Documentation. As the sole and exclusive remedy for not meeting part (i) of the above warranty, Licensor's sole obligation shall be to repair or replace free of charge any defective media on which the Licensed Software is delivered if the media is returned to Licensor by Licensee during the Warranty Period. As the sole and exclusive remedy for not meeting part (ii) of the above warranty, Licensor shall repair or replace the Licensed Software free of charge so that it conforms with the warranty or, if Licensor reasonably determines that such remedy is not economically or technically feasible, Licensee shall be entitled to a full refund of the license fee and any maintenance fee paid by Licensee with respect to that particular Licensed Software. Upon such refund Licensee's license to use such Licensed Software will terminate. The warranty set forth in this Section 7 shall not apply if the defect in the Licensed Software is the result of: (a) the Licensed Software not being used in accordance with the Documentation, this License Agreement or with the platform(s) for which the Licensed Software has been designed and licensed by Licensor; or (b) the Licensed Software having been altered, modified or converted by Licensee or any third party except as may be specified in the Documentation; or (c) the malfunctioning of Licensee's equipment; or (d) accident or abuse; or (e) service by any unauthorized person; or (f) other software used by Licensee which has not been provided by Licensor or for which the Licensed Software is not designed and licensed for operation; or (g) Third Party Software (as defined herein); or (h) any other cause occurring after initial delivery of the media to Licensee unless caused directly by Licensor. The foregoing states the complete and entire remedies that Licensee has under this warranty. Licensor shall have no responsibility for any warranty claims made outside of the Warranty Period. The foregoing warranty shall not apply to any free-of-charge Licensed Software including updates, though issues with such software may be eligible for support under applicable support terms and conditions.
  8. DISCLAIMER OF WARRANTY. The Licensed Software cannot be tested in every possible operating environment, therefore Licensor does not warrant that the functions contained in the Licensed Software will meet Licensee's requirements, that operation of the Licensed Software will be uninterrupted, or that the Licensed Software is error free. EXCEPT AS SET FORTH HEREIN AND TO THE EXTENT PERMITTED BY LAW, ALL OTHER WARRANTIES, EXPRESSED OR IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, QUALITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE EXCLUDED ON THE PART OF LICENSOR AND ITS THIRD-PARTY SUPPLIERS. Licensee acknowledges that Licensee is responsible for the selection of the Licensed Software to achieve Licensee's intended results and for the installation and/or use of, and results obtained from, the Licensed Software.
  9. LIMITATION OF LIABILITY. ANY LIABILITY OF LICENSOR SHALL BE LIMITED IN THE AGGREGATE TO THE AMOUNTS PAID BY LICENSEE FOR THE LICENSED SOFTWARE GIVING RISE TO THE APPLICABLE CLAIM. THIS LIMITATION APPLIES TO ALL CAUSES OF ACTION, INCLUDING WITHOUT LIMITATION BREACH OF CONTRACT, BREACH OF WARRANTY, NEGLIGENCE, STRICT LIABILITY, MISREPRESENTATION AND OTHER TORTS. IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR SIMILAR DAMAGES NOR FOR ANY LOSS OF PROFITS, CONTRACTS, DATA, OR PROGRAMS, OR THE COST OF RECOVERING SUCH DATA OR PROGRAMS, EVEN IF INFORMED OF THE POSSIBILITY OF SUCH DAMAGES IN ADVANCE. LICENSOR’S LIMITATIONS OF LIABILITY ARE NOT CUMULATIVE. LICENSEE’S REMEDIES IN THIS LICENSE AGREEMENT ARE LICENSEE’S EXCLUSIVE REMEDIES.

    NONE OF LICENSOR’S THIRD-PARTY SUPPLIERS SHALL BE LIABLE FOR ANY INJURY, LOSS OR DAMAGE, WHETHER DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL NOR FOR ANY LOSS OF PROFITS, CONTRACTS, DATA, OR PROGRAMS, OR THE COST OF RECOVERING SUCH DATA OR PROGRAMS, EVEN IF INFORMED OF THE POSSIBILITY OF SUCH DAMAGES IN ADVANCE.

    LICENSEE AGREES THAT, IN ENTERING INTO THIS LICENSE AGREEMENT, EITHER IT DID NOT RELY ON ANY REPRESENTATIONS (WHETHER WRITTEN OR ORAL) OF ANY KIND OTHER THAN THOSE EXPRESSLY SET OUT IN THIS LICENSE AGREEMENT, OR IF IT DID RELY ON ANY REPRESENTATIONS, THAT IT SHALL HAVE NO REMEDY AGAINST LICENSOR IN RESPECT OF SUCH REPRESENTATIONS.

    LICENSEE FURTHER ACKNOWLEDGES THAT THE LIMITATIONS OF LIABILITY IN THIS SECTION ARE AN ESSENTIAL ELEMENT OF THIS LICENSE AGREEMENT AND THAT, IN THE ABSENCE OF SUCH LIMITATIONS, THE PRICING AND OTHER TERMS AND CONDITIONS SET FORTH HEREIN WOULD BE SUBSTANTIALLY DIFFERENT.

    NEITHER THIS LICENSE AGREEMENT NOR ANYTHING IN THIS SECTION 9 SHALL EXCLUDE OR RESTRICT THE LIABILITY OF LICENSOR OR ITS THIRD-PARTY SUPPLIERS TO ANY EXTENT NOT PERMITTED BY LAW.

  10. HIGH-RISK USES. The Licensed Software is not fault tolerant, nor designed, manufactured or intended for use in hazardous environments requiring fail-safe performance (including, without limitation, the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life support machines, or weapons systems) in which failure of the Licensed Software could lead directly or indirectly to death, personal injury or severe physical or environmental damage. Licensor and its suppliers shall have no liability for any use of the Licensed Software in any high-risk situations.
  11. OWNERSHIP. Licensor (or its affiliates) and where applicable Licensor's third party suppliers have and will retain all ownership rights to the Licensed Software, together with any complete or partial copies thereof. Such ownership rights include without limitation all patent rights, copyrights, trademarks, trade secrets, service marks, related goodwill, and confidential and proprietary information relating thereto. This License Agreement does not convey any proprietary interest to Licensee with respect to the Licensed Software other than the license specified herein.
  12. THIRD PARTY SOFTWARE AND COMPONENTS. The Licensed Software may come with and/or require certain named third party software programs that Licensee shall license directly from the third party subject to such third party's terms and conditions (for example Adobe Acrobat or Microsoft Internet Explorer) ("Third Party Software"). Any Third Party Software is provided by the licensor of the Third Party Software solely under a direct license between such third party and Licensee under such third party's terms and conditions. Therefore the obligations, duties and rights of Licensor and Licensee under this License Agreement do not apply to such Third Party Software. Additionally, Licensor has embedded in some Licensed Software certain run time or other elements provided by third party suppliers to Licensor ("Third Party Components"). Such Third Party Components may also be loaded on the Licensed Software media. Third Party Components are licensed to Licensee pursuant to this License Agreement. Third Party Components may also include open source software, details of which (where applicable) may be found (i) in a file accompanying the applicable Licensed Software or (ii) in the applicable Documentation. Licensee may only access Third Party Components of the Licensed Software in the course of using the Licensed Software. Licensee may not make or attempt any direct access to any such Third Party Components other than with the Licensed Software. All limitations, restrictions and obligations applicable to the Licensed Software set forth in this License Agreement shall apply to Licensee's use of the Third Party Components. The Third Party Software and Third Party Components are the property of its respective third party supplier to Licensor. Such third party suppliers own all copies of the Third Party Software and Third Party Components, however made. Licensee agrees not to contest the ownership of the Third Party Software and Third Party Components nor use any trademark or service mark belonging to such third party suppliers. Licensee agrees that such third party suppliers are intended third party beneficiaries of all terms and conditions of this License Agreement intended to protect intellectual property rights in the Licensed Software (including the Third Party Components) and limit certain uses thereof. Nothing in this License Agreement shall restrict, limit or otherwise affect any rights or obligations Licensee may have, or conditions to which Licensee may be subject, under any applicable open source licenses to any open source code contained in the Licensed Software.
  13. NOTICE TO U.S. GOVERNMENT END USERS. The Licensed Software and Documentation are deemed to be "Commercial Items," as defined at 48 C.F.R. §2.101, consisting of "Commercial Computer Software" and "Commercial Computer Software Documentation," as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7207, as applicable. Consistent with such sections, the Licensed Software and Documentation are licensed to U.S. Government end users (i) only as Commercial Items, and (ii) with only those rights as are granted pursuant to this License Agreement. Manufacturer is Micro Focus (US), Inc., 700 King Farm Blvd., Suite 125, Rockville, MD 20850 as or on behalf of Licensor.
  14. LICENSE FEES AND PAYMENT TERMS. Licensee agrees to pay the applicable end user license fees for the Licensed Software within thirty (30) days of the date of invoice or such other date as agreed in writing by the parties. End user license fees are non-refundable except as provided in Section 7 above, or in the Specific Software Terms below, and shall be paid without deduction, including without limitation, of any withholding tax. End user license fees are exclusive of any applicable transportation charges, value added and other applicable taxes and duties and all such amounts shall be paid or reimbursed by Licensee. Outstanding past-due amounts shall accrue interest at the rate of 1.5% per month compounded or, if lower, the maximum rate allowed by applicable law. Licensee shall be liable for any such interest and all related collection costs, whether or not an action has been filed. Licensor may decline to enter into any additional Product Orders if any such past-due balance, interest and collection costs are not paid.
  15. RELATED SERVICES. Licensee shall be responsible for obtaining and installing all proper hardware and support software (including operating systems) and for proper installation and implementation of and training concerning the Licensed Software. In the event that Licensee retains Licensor to perform any services with respect to the Licensed Software (for example: installation, implementation, maintenance, consulting and/or training services), Licensee and Licensor agree that such services shall be subject to Licensor's then current standard terms, conditions and rates for such services unless otherwise agreed in writing by Licensor.
  16. PRIVACY. If the Licensed Software contains features that may allow Licensee to collect data from, control and/or monitor computers running the Licensed Software deployed by Licensee without notice to or knowledge by users of the Licensed Software, then: (i) Licensee is solely responsible for, and assumes all liability with respect to, the collection of data with respect to its users of the Licensed Software including, without limitation, notifying such users and complying with all data collection, privacy and other regulations, laws, industry standards and rights of others applicable to any such activity; and (ii) Licensee shall indemnify and hold Licensor harmless from and against any damages, claims, losses, settlements, attorneys' fees, legal fees and court costs and other expenses related to any such activities or any claims in connection therewith. To the extent permitted by law, by entering into this License Agreement, Licensee hereby expressly consents to (i) Licensor sending information to Licensee from time to time advertising the various products that Licensor provides, whether or not such products are provided under this License Agreement; (ii) the use of Licensee's name in Licensor customer lists, promotional materials and/or press releases; and (iii) the collection and use by Licensor of information about the computer system on which the Licensed Software is installed (e.g. product version, serial number) for internal security and licensing purposes; Licensor does not use this information to identify individuals utilizing such software.
  17. MISCELLANEOUS. Licensor may assign this License Agreement (in whole or in part) to any member of Licensor's group of companies or to a purchaser of the intellectual property rights in the Licensed Software, but otherwise neither this License Agreement nor any rights hereunder may be assigned (any change of control merger, sale or other transfer of all, or substantially all, of the assets of Licensee shall be included in the meaning of an assignment) nor duties delegated by either party, and any attempt to do so will be void.

    If Licensee acquires the Licensed Software in North America, the laws of the state of Maryland govern this License Agreement and the licenses granted hereunder and the parties hereto consent and agree that they shall be subject to the exclusive jurisdiction of the State and/or Federal courts sitting in the State of Maryland in any action based on this License Agreement or concerning the licenses granted, or the products licensed, hereunder. Each party waives any right it may have to object to such venue, including objections based on personal jurisdiction or forum non conveniens (inconvenient forum). The parties agree that the Uniform Computer Information Transaction Act or any version thereof, adopted by any state, in any form ("UCITA"), shall not apply to this License Agreement. To the extent that UCITA is applicable, the parties hereby opt out of the applicability of UCITA pursuant to the opt-out provision(s) contained therein. If Licensee acquires the Licensed Software in France, Germany or Japan, this License Agreement is governed by the laws of the country in which Licensee acquired the Licensed Software. In the rest of the world the laws of England govern this License Agreement. The aforesaid applicable law shall apply without regard to conflicts of laws provisions thereof, and without regard to the United Nations Convention on the International Sale of Goods. Other than for North American transactions, this License Agreement, the licenses granted hereunder, and the parties hereto, shall be subject to the exclusive jurisdiction of the courts of the country determining the applicable law as aforesaid. In the event of a dispute, the prevailing party shall have the right to collect from the other party its reasonable costs and necessary disbursements and attorneys' fees incurred in enforcing this License Agreement.

    This License Agreement is in addition subject to any United States, United Kingdom or European Union laws, regulations and other restrictions regarding export or re-export of computer software and technology. Licensee agrees not to export or re-export any Licensed Software or derivative thereof in contradiction to any such applicable restriction. In particular but without limitation, Licensee acknowledges that Licensor's products and/or technology are subject to the U.S. Export Administration Regulations (the "EAR") and Licensee agrees to comply with the EAR. Licensee will not export or re-export Licensor's products, directly or indirectly, to: (1) any countries that are subject to US or applicable export restrictions; (2) any end user who Licensee knows or has reason to know will utilize Licensor's products in the design, development or production of nuclear, chemical or biological weapons, or rocket systems, space launch vehicles, and sounding rockets, or unmanned air vehicle systems; or (3) any end user who has been prohibited from participating in export transactions by any applicable agency of government. By downloading or using the Licensed Software, Licensee is agreeing to the foregoing and Licensee is representing and warranting that Licensee is not located in, under the control of, or a national or resident of any such country or on any such list.

    Licensor may identify Licensee by name and/or logo as a licensee of Licensor for investor relations, analyst relations, and public relations purposes, and in online and printed sales and marketing materials. Any other use of Licensee's name or logo, or a description of Licensee's use of the Licensed Software, shall be subject to Licensee's prior consent. Within eight (8) weeks after installation of the Licensed Software, upon Licensor's written request Licensee will provide Licensor with input to a written description of Licensee's use of the Licensed Software including details of the business challenge, software solution, and results realised from the installation of the Licensed Software. The input shall be provided by a representative of Licensee (who is knowledgeable of the Licensed Software and its performance after installation) during a meeting with a representative of Licensor (at a reasonable time to be agreed by the parties). The meeting may be conducted by telephone. This input may be used internally within Licensor and in confidential sales situations. Any other use of this input shall be subject to Licensee's prior consent.

    Except for the Product Order, this License Agreement is the complete and exclusive statement of agreement between the parties relating to the license for the Licensed Software and supersedes all proposals, communications, purchase orders, and prior agreements, verbal or written, including without limitation prior end user license agreements in relation to the Licensed Software between the parties and end user license agreements embedded in such Licensed Software. No employee, agent, or representative of Licensor has the authority to bind Licensor to any oral representation or warranty concerning the Licensed Software. No representation or statement not expressly contained in this License Agreement nor any supplement, modification, or amendment of this License Agreement will be binding on either party unless executed in writing by a duly authorized representative of Licensor and Licensee (excluding any distributor or reseller of Licensor) to this License Agreement. No waiver of any right under this License Agreement will be effective unless in writing, signed by a duly authorized representative of the party to be bound (excluding any distributor or reseller of Licensor). No waiver of any past or present right arising from any breach or failure to perform will be deemed to be a waiver of any future right arising under this License Agreement. If any provision in this License Agreement is invalid or unenforceable, that provision will be construed, limited, modified or, if necessary, severed, to the extent necessary, to eliminate its invalidity or unenforceability, and the other provisions of this License Agreement will remain unaffected. Each party acknowledges that in entering into this License Agreement it has not relied on any representations, agreements, warranties or other assurances (other than those repeated in this License Agreement and the Product Order) and waives all rights and remedies which but for this section 17 would be available to it. Nothing in this section 17 excludes liability for fraudulent misrepresentation.

    If Licensee is situated in Italy, by placing or executing a Product Order, Licensee declares to have read and to have explicitly approved the following clauses of the License Agreement: 5. Term of License, 6. Support and Maintenance, 7. Limited Warranty, 8. Disclaimer of Warranty, 9. Limitation of Liability, 10. High-Risk Uses, 16. Privacy, 17. Miscellaneous, Annex 1, and Annex 2.

ANNEX 1, LICENSE OPTIONS

DEFINITIONS

For this License Agreement, the following additional definitions shall apply:

"Batch Processing" means the execution of one or more tasks, transactions or programs by a computer system without the continuous interaction of the end user with the Licensed Software for the entire period during which each such task, transaction or program is being executed by the system. Batch processing includes situations where a queue of jobs is processed as resources become available and is in contrast to transaction or interactive processing.

"Blades" means multiple server modules housed in a single chassis each with its own CPU, hard disk and memory.

"Core" means a physical (not virtual) subunit within a CPU on a single chip that handles the main computational activities of a computer. A CPU may have one or more Cores and therefore be a "Multicore CPU" if it has more than one Core.

"CPU" (Central Processor Unit) means a data processing unit, normally identified with a single microchip mounted on a single circuit board and can comprise several Cores.

"Hard Partitioning" means using hard physical partitioning to physically segment a single larger server or machine into separate and distinct smaller systems where each separate system acts as a physically independent, self-contained server or machine with its own CPUs, operating system, separate boot area, memory, input/output subsystem and network resources (each known as a "Hard Partition"). Examples of Hard Partitioning methods include: Dynamic System Domains (DSD) -- enabled by Dynamic Reconfiguration (DR), Solaris Zones (also known as Solaris Containers, capped Zones/Containers only), LPAR (adds DLPAR with AIX 5.2), Micro-Partitions (capped partitions only), vPar, nPar, Integrity Virtual Machine (capped partitions only), Secure Resource Partitions (capped partitions only), and Fujitsu's PPAR.

"Platform" means a hardware chipset (e.g., PA-RISC, Itanium, x86, or SPARC) and operating system (e.g., Windows, Linux, Solaris, AIX, or HP-UX) combination.

"Soft Partitioning" means using an operating system resource manager to segment and limit the number of Cores, CPUs, or other processing devices utilized by the Licensed Software by creating areas where processor resources are allocated and limited within the same operating system (each such area known as a "Soft Partition"). Examples of such Soft Partitioning include: Solaris 9 Resource Containers, AIX Workload Manager, HP Process Resource Manager, Affinity Management, Oracle VM, and VMware.

"Update" means the definition for such term set forth in Licensor's then current applicable standard annual support and/or maintenance agreement.

"Upgrade" means any change in the licensed Platform for the Licensed Software or a successor product to the Licensed Software.

"Virtual Machine" means a software implementation that can run its own operating system and execute programs like a physical machine where the software running inside the virtual machine is limited to the resources and abstractions provided by the virtual machine.

LICENSE OPTIONS

  1. Development License Options
    1. Named User or Developer License. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on a single machine or server for use solely by the number of named users expressly authorized by Licensor in the Product Order for whom Licensee has paid the applicable license fee . A named user must only be one named person and such named person has the right to unlimited access to the Licensed Software on such single machine or server. A Named User License is not based on concurrent users, but instead on an actual named user basis. Licensor reserves the right at any time to require Licensee to provide a list of the named users. Licensee may change a named end user provided that the change is made either (i) permanently, or (ii) temporarily to accommodate the use of the Licensed Software by a temporary worker while the named user is absent, but in each case no more than once every 30 days.
  2. Deployment License Options.
    1. Server License Options. There are two options for server-based licenses. Please note that server-based licenses may only be installed on one machine or server. Additional licenses are therefore required to be purchased by Licensee for use of the Licensed Software on more than one machine for any purpose, including disaster recovery, load-balancing, clustering, fail-over, training, or testing. Licensed Software may be licensed solely for evaluation, disaster recovery, fail-over, training, or testing purposes and in such case will be subject to the applicable License Option terms and conditions set forth in this Annex 1.
      1. Concurrent User License. Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on a single machine or server for use by the maximum number of Concurrent Users for whom Licensee has paid the applicable license fee. Concurrent Users are individuals who are actively using any device or other software program that may access the Licensed Software either directly, or indirectly through any other software program, regardless of how such access occurs or if such user uses any hardware or software that reduces the apparent number of users who are using the Licensed Software, such as by using a terminal service. The Licensed Software may not be used or accessed by any other software or hardware device that does not require an individual to use or access it including, without limitation, Batch Processing. Licensee may only use the Licensed Software on or access the Licensed Software from one server at any one time. Subject to the prior written consent of Licensor and to payment of additional license fees, Licensee may permit the public and/or Licensee' customers to access and use the Licensed Software via the internet and/or Licensee' terminals in connection with Licensee' internal business purposes (for example to access internet banking from Licensee) but not for the public' and/or Licensee' customers' own internal use.
      2. Server License for CPUs (or Core License). Licensed Software provided under this License Option gives Licensee the right to install the Licensed Software on a single machine or server ("Host Server") and have the Licensed Software executed by up to the total number of CPUs, Cores, Integrated Facility for Linux processors ("IFLs"), Blades or other processing devices specified for the license in the applicable Product Order ("License Specification"). If the number of Cores is not specified for a CPU in the event a CPU is specified in the License Specification, such CPU shall be considered to be single-Core. A Server License for CPUs license covering all CPUs, Cores, IFLs, Blades and other processing devices that are contained in and/or can be accessed by the Host Server ("Total Processors") is required with all applicable license fees paid, even if one or more of such CPUs, Cores, IFLs, Blades or other processing devices are not accessing or running the Licensed Software. For example, if 32 Cores are the Total Processors on the Host Server, but only 16 Cores are utilized to execute the Licensed Software, a 32-Core Server License for CPUs license is required notwithstanding the fact that 16 of the 32 Cores may not actually be accessing the Licensed Software. Each Core on a multi-core CPU requires a Server License for CPUs license covering each such Core. For example a Host Server with Total Processors consisting of a single quad-core CPU will require a 4-Core Server License for CPUs license and payment of the license fees applicable to all 4 Cores.

        The Licensed Software is for use by an unlimited number of Licensee's internal users, other software devices and hardware devices. A Server License for CPUs is the only license authorized for use or access by Licensee for any Batch Processing. Licensor reserves the right at any time to require Licensee to provide a specification of the Host Server. Licensee may change the designated Host Server provided that the new Host Server's specifications are authorized under the applicable Server License for CPUs license, including, but not limited to, the Total Processors in, and thus the Server License for CPUs licenses required for, the new Host Server do not exceed the License Specification(s) for the Server License for CPUs license(s) used for the old Host Server plus any new Server License for CPUs license(s) purchased by Licensee for use on the new Host Server. Licensee is required to purchase a license for the Total Processors on each Host Server that accesses or uses the Licensed Software either directly or indirectly through any other software program, regardless of how such access occurs, or if the Host Server, CPU or operator uses any hardware or software that reduces the apparent number of CPU, Cores, IFLs, Blades or other processing devices that are using the Licensed Software, such as by using a terminal service. Subject to the prior written consent of Licensor and to payment of additional license fees, Licensee may permit the public and/or Licensee's customers to access and use the Licensed Software via the internet and/or Licensee's terminals in connection with Licensee's internal business purposes (for example to access internet banking from Licensee) but not for the public's and/or Licensee's customers' own internal use.

    2. Test License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely for Licensee's internal testing purposes on a single computer system subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. At no time may Licensee use the Licensed Software for development, commercial, or production purposes, nor may Licensee reproduce or distribute the Licensed Software or any software application programs created with it. Licensee's results of benchmark or other performance tests run on or using the Licensed Software may not be disclosed to any third party without Licensor's prior written consent. If Licensee uses the Test Licenses for any purpose other than for Licensee's internal testing purposes, the Test License shall terminate automatically and without notice. Upon such termination, Licensee may convert the terminated Test License to a standard license type listed above by paying the applicable conversion fee. In relation to Licensed Software provided pursuant to this Test License Option, this Section shall prevail over any contrary provisions set forth in this License Agreement. For the avoidance of doubt, a "test" license as described above is not a license to use Licensor's software quality or "testing" products, however such products may be available under this Test License Option.
    3. Disaster Recovery License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely on a Cold Disaster Recovery System subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. A Cold Disaster Recovery System is a computer system that is used only (i) if a disaster arises and the original production, test, or development system is unavailable, (ii) for the purposes of disaster recovery testing and/or (iii) for system diagnostics or maintenance of the Cold Disaster Recovery System itself. Licensed Software provided under this option cannot be used (a) concurrently with any Deployment License for the Licensed Software except while the original production, test, or development system is being recovered; (b) in production, test, or development environments except in a disaster recovery situation: or (c) for load-balancing, failover, testing (other than disaster recovery testing), clustering, or training purposes. Additional copies for use in production, test, and/or development environments, or for load-balancing, failover, clustering, or training purposes, or for installation in any computer system that is in use must be purchased separately. Cold Disaster Recovery Licenses shall terminate automatically without notice if the Licensed Software provided under this License Option is installed on anything other than a Cold Disaster Recovery System, if Licensee ceases to use the Licensed Software for disaster recovery purposes, or if Licensee is otherwise in violation of the restrictions set forth in this section.
    4. Failover License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely on a single standby failover server in standby, non-production mode subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. Licensee may not use the Licensed Software for production, testing (other than failover testing), development, or training except during periods when one or more copies of the Licensed Software for which Licensee has purchased a Deployment License are nonfunctional. Licensee may not use the Licensed Software for load-balancing or clustering, for which a separate license is required to be purchased by Licensee.
    5. Training License Option Licensed Software provided under this License Option gives Licensee a limited license to use the Licensed Software solely for Licensee's internal training purposes on a single computer system subject to this section and the restrictions applicable to the type of license purchased as specified in the applicable Product Order (e.g., Server License for CPUs, etc.). In the event of a conflict, the terms and conditions in this section shall prevail. At no time may Licensee use the Licensed Software for development, testing, or production purposes, nor may Licensee reproduce or distribute the Licensed Software or any software application programs created with it.
  3. Evaluation License Option Licensed Software provided under this License Option gives Licensee a term license to use the Licensed Software within Licensee during the evaluation term specified in writing by Licensor, solely for evaluation and testing purposes on a single computer system and not for development, commercial, or production purposes. Licensee may not reproduce or distribute the Licensed Software. Licensee's results of benchmark or other performance tests run on or using the Licensed Software may not be disclosed to any third party without Licensor's prior written consent. At any time during the evaluation term or upon completion thereof, Licensee may, upon written notification to Licensor and payment of the applicable license fee, replace the evaluation license with a license to use the Licensed Software pursuant to one of the other applicable options listed in Annex 1. In the absence of such notification by Licensee, the evaluation license shall automatically terminate at the end of the evaluation term and Licensee shall return, or, if Licensor so directs, delete and destroy all such Licensed Software and provide Licensor with written confirmation of such deletion and destruction being completed. Licensor may, in its sole discretion, grant Licensee an extension to the evaluation term subject to receiving a written request and reasons for such request from Licensee prior to expiration of the evaluation term. Licensor will specify any such agreed extension in writing to Licensee. Licensed Software provided by Licensor free of license fee charge shall be deemed to be provided pursuant to this Evaluation License Option unless otherwise agreed in writing. In the absence of any contrary period specified in writing by Licensor, the evaluation term shall be deemed to be thirty (30) days. In relation to Licensed Software provided pursuant to this Evaluation License Option, this Section shall prevail over any contrary provisions set forth in this License Agreement.

ANNEX 2, SPECIFIC SOFTWARE TERMS

Additional Restrictions. Licensee agrees not to:

  1. Copy and/or distribute the Licensed Software, in whole or in part, to third parties, or use the Licensed Software for the benefit of any third party, or permit use or access by any third party to all or part of the Licensed Software without first paying Licensor any applicable additional fees required by Licensor and entering into a separate distribution license agreement with Licensor. For the avoidance of doubt, third party(ies) include without limitation contractors, outsourcers, Licensee's customers and the public.
  2. Transfer, ship or use the Licensed Software outside the continent in which it was originally licensed to Licensee without first paying Licensor any applicable additional fees required by Licensor. For purposes of the foregoing, "continent" shall mean North America, South America, Europe, Africa, Asia, Australia, or Antarctica.
  3. Install, access or use the Licensed Software on a Platform other than the Platform for which the Licensed Software was originally licensed to Licensee. Additional licenses for use of the Licensed Software on a Platform other than the one set forth in the applicable Product Order may be available upon payment of an additional license fee.
  4. Assign, sell, rent, lease, lend, sublicense, outsource or otherwise transfer the Licensed Software to any third party, or authorize or appoint any third party to do so, or otherwise allow a third party to directly or indirectly use or access the Licensed Software, without Licensee first paying Licensor the applicable additional fees required by Licensor.
  5. Install, use, or access the Licensed Software on, in, or from a Hard Partition, Soft Partition, or Virtual Machine, except where Licensee is otherwise expressly authorized in each instance by Licensor in the applicable Product Order or otherwise in writing separate from this License Agreement (the "Authorization") which in each event will be subject to Licensee's payment to Licensor of additional applicable fees required by Licensor and Licensee's written confirmation to Licensor of Licensee's planned installation environment signed by a director or officer of Licensee (accompanied by all information as Licensor reasonably requires to verify). W here authorized in accordance with the foregoing and to the extent applicable to the subject license: (i) such Hard Partition, Soft Partition, or Virtual Machine, may only be tied to one physical machine and shall be considered the entire machine for licensing purposes ; and (ii) Licensee shall provide to Licensor, at such times as Licensor may reasonably request, confirmation that Licensee's computer systems comply with the applicable Authorization and the requirements of the License Agreement. Such confirmation shall be signed by a director or officer of Licensee and shall be accompanied by all information as Licensor reasonably requires to verify that Licensee is utilizing the Licensed Software in compliance with the terms and conditions of the License Agreement, including without limitation any relevant hypervisor logs. The foregoing is in addition to Licensor's rights under the Audits section of the License Agreement .

RM/COBOL Development System . Licensee shall not use the Licensed Software, nor reproduce or distribute any files supplied as part of the Licensed Software, in order to create a compiler, interpreter, runtime support product or any other product that is generally competitive with or a substitute for the Licensed Software or any other Licensor product.

This Licensed Software may include or generate limited licenses for RM/COBOL Runtime System, or other application deployment product. If such licenses are included or generated, these limited licenses are provided solely for use by the licensed user(s) of the Licensed Software in order to unit test an application developed with the Licensed Software on the same machine or server used to develop the application and may not be used for system testing, production or deployment. Any use of this limited license outside of the development and unit testing of such applications is not permitted.

RM/COBOL Runtime System, RM/COBOL Deployment System . With any valid and properly granted license to this Licensed Software, Licensee may reproduce and distribute internally, in whole or in part, subject to the applicable license option as described in Annex 1 and the applicable Product Order, any software application program created by Licensee using the corresponding development product for the Licensed Software (if separately licensed to Licensee by Micro Focus) ("Licensee Application Software"). In such event Licensee shall (a) include Licensor's copyright notice for the Licensed Software on any product label and as a part of any sign-on message for such Licensee Application Software product; and (b) indemnify, hold harmless and defend Licensor and its third-party suppliers from and against any claims or lawsuits, including attorneys' fees, legal fees and court costs that arise out of, or result from, the use or distribution of such Licensee Application Software.

Licensee can only reproduce and distribute Licensee Application Software to third parties after entering into a separate distribution agreement with Licensor. Usage and distribution of the Licensee Application Software arises both by the explicit distribution of any Licensee Application Software and by the implicit distribution and usage of any of the Licensee Application Software's functionality when linked into another software application program. Access and/or use of data, results and/or output obtained and/or generated, either directly or indirectly, and in any format whatsoever, through the use of any Licensed Software (such as when a user accesses an application that calls or uses output from another application running the Licensed Software, whether or not on the same machine or server) are deemed to be access and/or use of such Licensed Software. Licensor offers specific production licensing options for distribution to third parties which vary depending upon the license fees paid by Licensee and Licensee should contact its Licensor sales representative for more details.

Xcentrisity Business Information Server . Where this Licensed Software is licensed on a concurrent user basis, such license may indicate that it is for local area network usage ("LAN") or wide area network usage ("WAN"). A LAN license may only be installed and used on one server, whereas a WAN license may be installed and used on any number of servers, both subject to the number of concurrent users licensed

All-or-None Support and Maintenance . Where Licensee purchases support and/or maintenance for the Licensed Software, Licensee hereby agrees that it shall purchase such support and/or maintenance services for all of Licensee's licensed units of such Licensed Software including all related development and deployment product licenses.

Updates and Upgrades . Upon delivery to Licensee of any Update and/or Upgrade, the license granted to such prior version and/or release being updated or upgraded shall terminate after a ninety (90) day transition period from such delivery and only the license to such Update or Upgrade shall continue unless (i) Licensee has paid to Licensor the applicable additional fees required by Licensor to use both versions, or (ii) in the case of an Update that is provided to Licensee at no additional charge from Licensor pursuant to support and/or maintenance for which Licensee has separately contracted, Licensee provides written notice to Licensor during the aforementioned transition period of its election not to use the Update but instead remain with the prior version and Licensee's de-installation and destruction of such Update.

Editions . Any reference to a Licensed Software product in this License Agreement shall also apply to such product's various editions or variants except where otherwise specifically stated.

Bundles/Suites . If the Licensed Software is licensed as part of a bundle or suite of multiple products, and the applicable Product Order specifies the License Option and license count for the bundle or suite (but not the individual product components of the bundle or suite), then each product in the suite or bundle shall share such license type and count. Individual products in the bundle or suite cannot be used by multiple users if only one user license is purchased (for user-based licenses) and cannot be installed on multiple devices or servers if only one device or server license is purchased (for device or server-based licenses).

Academic Editions/Users . Where Licensed Software is licensed under Licensor's Academic Program, in addition to the above terms and conditions:

(i) Licensee shall not use the Licensed Software for any purpose other than for non-commercial education or academic research activities.

(ii) Licensee shall not copy the Licensed Software, nor shall Licensee distribute, transfer or assign the Licensed Software without specific permission from Licensor.

(iii) License management: If Licensee is the academic institution using the Licensed Software for teaching purposes, Licensee will manage all student licenses through a license server provided by Licensor in accordance with guidelines provided by Licensor. Licensee agrees to provide reports describing the number of licenses Licensee has issued in each period upon Licensor's request.

Batch-Only Licenses . Where any Licensed Software is designated as "Batch-Only" using such description or similar terminology, such Licensed Software may only be used to perform batch processing.

PRE-EXISTING LICENSES. FROM COMMENCEMENT OF THIS LICENSE AGREEMENT, IF THE LICENSED SOFTWARE SUBJECT TO THIS LICENSE AGREEMENT IS THE MOST CURRENT VERSION OF THE LICENSED SOFTWARE LICENSED BY LICENSEE, THE "LICENSED SOFTWARE" SHALL ALSO INCLUDE, AND THIS LICENSE AGREEMENT SHALL APPLY TO, ANY PRE-EXISTING LICENSES FOR ANY EARLIER VERSION OF THE LICENSED SOFTWARE LICENSED BY LICENSEE AND REPLACE ANY PRIOR END USER LICENSE AGREEMENTS APPLICABLE THERETO ("PRIOR EULA(S)"). NOTWITHSTANDING THE FOREGOING, IF THE EARLIER VERSION INCLUDES DIFFERENT COMPONENTS, ANY TERMS SPECIFICALLY APPLICABLE TO THOSE COMPONENTS IN THE APPLICABLE PRIOR EULA SHALL CONTINUE TO APPLY TO SUCH COMPONENTS. "ANY VERSION OF THE LICENSED SOFTWARE" SHALL ALSO INCLUDE THE RELATED DEVELOPMENT AND DEPLOYMENT PRODUCTS OF SUCH LICENSED SOFTWARE.

ENDS


The Micro Focus Community

In addition to this product documentation, visit the to browse the Knowledge Base, read articles and blogs, as well as discuss this product with other users and Micro Focus specialists.


Contacting Micro Focus

Our Web site gives up-to-date details of contact numbers and addresses.

  • Further Information and Product Support
  • Information We Need
  • Creating Debug Files
Parent topic: Micro Focus Relativity Designer for Windows


Further Information and Product Support

Additional technical information or advice is available from several sources.

The product support pages contain a considerable amount of additional information, such as:

  • The Product Updates section of the Micro Focus SupportLine Web site, where you can download fixes and documentation updates. Go to Micro Focus Product Updates
  • The Examples and Utilities section of the Micro Focus SupportLine Web site, including demos and additional product documentation. Go to https://supportline.microfocus.com/examplesandutilities/index.aspx.
  • The Support Resources section of the Micro Focus SupportLine Web site, that includes troubleshooting guides and information about how to raise an incident. Go to https://supportline.microfocus.com/supportresources.aspx

To connect, enter https://www.microfocus.com/en-us/home/ in your browser to go to the Micro Focus home page, then click Support & Services > Support. Type or select the product you require from the product selection dropdown, and then click Support Login.

Note: Some information may be available only to customers who have maintenance agreements.

If you obtained this product directly from Micro Focus, contact us as described on the Micro Focus Web site, https://www.microfocus.com/support-and-services/contact-support/. If you obtained the product from another source, such as an authorized distributor, contact them for help first. If they are unable to help, contact us.

Also, visit:

  • The Micro Focus Community Web site, where you can browse the Knowledge Base, read articles and blogs, find demonstration programs and examples, and discuss this product with other users and Micro Focus specialists.
  • The Micro Focus YouTube channel for videos related to your product..
Parent topic: Contacting Micro Focus
Related information
Micro Focus SupportLine
Examples and Utilities
Support Resources
Micro Focus Community
White Papers and Webinars
Micro Focus YouTube Channel


Information We Need

However you contact us, please try to include the information below, if you have it. The more information you can give, the better Micro Focus SupportLine can help you. But if you don't know all the answers, or you think some are irrelevant to your problem, please give whatever information you have.

  • The name and version number of all products that you think might be causing a problem.
  • Your computer make and model.
  • Your operating system version number and details of any networking software you are using.
  • The amount of memory in your computer.
  • The relevant page reference or section in the documentation.
  • Your serial number . To find out these numbers, look in the subject line and body of your Electronic Product Delivery Notice email that you received from Micro Focus.
  • Your Relativity catalog and data files.
Parent topic: Contacting Micro Focus


Creating Debug Files

If you encounter an error when compiling a program that requires you to contact Micro Focus SupportLine, your support representative might request that you provide additional debug files (as well as source and data files) to help us determine the cause of the problem. If so, they will advise you how to create them.

Parent topic: Contacting Micro Focus


Getting Started

  • Starting and Stopping the Relativity Designer
    The Relativity Designer runs in Windows. Use this section for details on how to start and stop it properly.
  • Relativity Catalogs
    The function of a Relativity catalog is similar to that of the 'system catalog' in a relational database management system. It serves as a repository for information regarding the structure of relational tables.
  • Configuring Relativity Data Sources
    Microsoft's Open Database Connectivity (ODBC) interface requires that a data source be configured in order to allow data access.
  • Configuring the Workspace
    Configure the look and feel of Relativity Designer to suit the way that you work.
  • Setting Options
    Relativity allows you to specify default settings for various configuration preferences, including data sources, date formats, and COBOL types.
Parent topic: Micro Focus Relativity Designer for Windows


Starting and Stopping the Relativity Designer

The Relativity Designer runs in Windows. Use this section for details on how to start and stop it properly.
  • Starting the Relativity Designer
  • Exit the Relativity Designer
Parent topic: Getting Started


Starting the Relativity Designer

Windows 7 and earlier

To start the Relativity Designer, from your Windows desktop, click Start > All Programs > RMCOBOL > Relativity v12 > Designer.

Windows 10 and later

To start the Relativity Designer, from your Windows desktop, click Start > RM Relativity v12 > Designer.

Next you need to either create a new data source, or log on to an existing one.

Parent topic: Starting and Stopping the Relativity Designer
Related reference
Setting up a New Data Source
Opening an Existing Data Source


Exit the Relativity Designer

To exit the Relativity Designer:

  • On the File menu, click Exit.
  • Click Close (Close) on the title bar.
Parent topic: Starting and Stopping the Relativity Designer


Relativity Catalogs

The function of the Relativity catalog is similar to that of the "system catalog" in a relational database management system. It serves as a repository for information regarding the structure of relational tables as well as operational information required by runtime components of Relativity, such as the query optimizer. Additionally, the Relativity catalog contains complete information regarding the physical COBOL data file structure (that is, the COBOL file definition, or FD information) and information produced by the database design process (Relativity Designer) that defines the association between COBOL data files and data elements, and the relational tables and their constituent columns. Finally, security information about users, groups, and privileges is stored in the catalog. Together, all of this information allows Relativity to present the COBOL data files through an ODBC interface of an ODBC-enabled application as a relational database of well-normalized tables substantially independent of the original COBOL data file structure of the application.

The Catalog Explorer pane is the focal point in the Relativity Designer main window when a Relativity data source, whose definition specifies the catalog, is opened. Many of the activities related to structuring the COBOL data, so that it can be viewed in a relational table, is performed from here.

Parent topic: Getting Started
Related reference
Relativity Designer Window


Configuring Relativity Data Sources

Microsoft's Open Database Connectivity (ODBC) interface requires that a data source be configured in order to allow data access.

Configuring a data source involves setting the data source name (DSN) by which the data source will be known, optionally entering a textual description of the data source, entering any additional information required by a specific ODBC driver for connecting to the actual data, and setting any options supported by the specific ODBC driver. Data source configuration applies both to setting up a new data source or modifying an existing data source.

  • In single-tier (that is, non-client/server) versions of Relativity, the Data Manager data source can be configured within the Relativity Designer. In client/server versions of Relativity, only the Data Client data source can be configured within the Relativity Designer.
  • In client/server versions of Relativity, the Data Server data source is configured using the Relativity Server Administrator, a separate utility provided with the Relativity DBMS. The Data Client data source is subsequently associated with the Data Server data source from within the Relativity Designer.
Note: If you installed the Relativity Server Administrator utility, you can start this program from within the Relativity Designer by clicking Relativity Server Admin on the Tools menu. The Select Server dialog box is displayed. (For more information, see the Server Administrator Help file, which is available by clicking Help on the Select Server dialog box.)

Data source configuration also can be performed outside of Relativity, using the ODBC Administrator functions available on 32-bit Windows from the Windows Control Panel (see the Data Sources (ODBC) applet; under Administrative Tools in the Control Panel).

On a 64-bit Windows 7 machine, the ODBC Administrator will only be able to configure the 64-bit Data Sources of the 64-bit Data Client. In order to create 32-bit Data Sources for the Data Manager or the 32-bit Data Client, you must use the 32-bit ODBC Administrator program. Unfortunately, this program is not in the Windows Control Panel. You must run C:\Windows\SysWOW64\odbcad32.exe. (We recommend that you create a short-cut to this program on your desktop.)

On a 64-bit Windows 10 machine, the 32-bit ODBC Administrator program can be used directly. From the Start menu, select [image] (Settings). In the Windows Settings window, type ODBC in the Find a setting search box and select Set up ODBC data sources (32-bit).

The ODBC Administrator, a standard ODBC program, requires selection of a particular ODBC driver.

Note: The Relativity Designer allows easy and quick access to the ODBC Data Source Administrator. To start the program, click ODBC Control Panel or ODBC Control Panel (64-bit) on the Tools menu. The ODBC Data Source Administrator dialog box is displayed.

Since data source configuration is always specific to a selected ODBC driver, any method of starting the process requires that you complete the same tasks when configuring a Relativity data source. For more information about configuring a Relativity data source, choose one of the following tasks:

  • Single-tier and Client/Server Data Sources
  • Relativity Drivers
  • Setting up a New Data Source
  • Opening an Existing Data Source
  • Closing a Data Source
Parent topic: Getting Started


Single-tier and Client/Server Data Sources

One of the finer points of using Relativity is the distinction between single-tier and client/server data sources. For the Relativity Designer, a single-tier data source is needed when the COBOL data files reside on the same machine as the Relativity Designer. In this case, the Relativity Data Manager should be installed and the Relativity (*.rcg) driver should be used to create the data source.

However, when the COBOL data files reside on a different machine from the Relativity Designer, the Relativity Data Server must be installed on the machine with the COBOL data files, and the Relativity Data Client must be installed on the machine with the Relativity Designer. During the installation of the 32-bit Relativity Data Client, select a Custom Installation and on the Data Client Installation Type page, select Database Administrator.

Before a client data source is created, the server data source to which it will connect must exist. Start the Relativity Designer and, from the Tools menu, select Relativity Server Admin, and use this utility to create a server data source. After the server data source exists, then a client data source can be created that references the server data source. (See the Relativity Server Admin help file for more details on creating a server data source.)

Note: The server data source needs to be created only once. When the Relativity Data Client is installed on subsequent machines, a Standard Installation can be used from the Installation Type page, which will cause the Server Administrator not to be installed. When a client data source is created on that machine, it will be able to connect to the already existing server data source.
Parent topic: Configuring Relativity Data Sources
Related tasks
Setting up a New Data Source
Opening an Existing Data Source
Closing a Data Source
Related reference
Relativity Drivers


Relativity Drivers

Driver is a term that ODBC uses to describe the software that connects an ODBC-enabled application to a database management system (DBMS) such as SQL Server. For Relativity, especially for the single-tier Data Manager, the driver is the entire database management system. For the client/server variant of Relativity, the Data Client is closer to what ODBC means as a driver, and the Data Server is closer to what ODBC means as a database management system.

Largely, the driver in use is not important to an ODBC-enabled application such as the Relativity Designer. The only time it becomes important is when a data source is created. At that point, the ODBC administrator will request the driver to use, and it will access the Data Source Creation routine in the driver and let it complete the process.

Thus, it is important to understand the types of Relativity drivers in order to properly understand how to answer the question of which Relativity driver to use:

Relativity (*.rcg)
This is the primary Relativity driver, and it is the name of the single-tier Relativity Data Manager. In a single-tier environment, this is the preferred driver to use with the Relativity Designer.
Relativity for ADO (.rcg)
This is also a single-tier Relativity Data Manager, but it implements a version of the ODBC API that works better with the Microsoft ADO product set, such as Excel. It is not recommended to use this driver with the Relativity Designer.
Relativity Client
This is the client-side driver for the Relativity Data Client. If the data files being accessed are on a remote (server) machine, it is recommended that a Relativity Data Server be installed on the server, and the Relativity Data Client be installed on the machine with the Relativity Designer, in which case the Relativity Client is the driver to use.
Relativity Client for ADO
This is the client-side driver for the Relativity Data Client, but it implements a version of the ODBC API that works better with the Microsoft ADO product set, such as Excel. It is not recommended to use this driver with the Relativity Designer.
Relativity Client (64-bit)
This is the client-side driver for the Relativity Data Client to use with 64-bit ODBC-enabled applications. The Relativity Designer is 32-bit ODBC-enabled and will not work with this driver.
Relativity Client for ADO (64-bit)
This is the client-side driver for the Relativity Data Client to use with 64-bit ODBC-enabled applications, but it implements a version of the ODBC API that works better with the Microsoft ADO product set. The Relativity Designer is 32-bit ODBC-enabled and will not work with this driver.
Relativity Server
This driver appears on Windows machines that have the Relativity Data Server installed. It is used to create the server-side data sources, but is not intended for direct use. Do not use a Data Source created by this driver with the Relativity Designer. Instead, use the Relativity Client driver instead.
Parent topic: Configuring Relativity Data Sources
Related tasks
Setting up a New Data Source
Opening an Existing Data Source
Closing a Data Source
Related reference
Single-tier and Client/Server Data Sources


Setting up a New Data Source

An ODBC data source name is used to refer to the database, indirectly through the Relativity catalog.

To set up a new data source:
  1. Start the Relativity Designer.

    If you are prompted to log on to an existing database, click Cancel.

    The Relativity Designer window opens.

  2. On the File menu, click Create New Data Source.

    The Create New Data Source dialog box is displayed.

  3. Select the type of data source:
    1. Select one of File Data Source, User Data Source (only available to the current Windows account on this machine), System Data Source (available to all Windows accounts on this machine).
    2. Click Next.
  4. Select the data source driver:
    1. Select the required driver: Relativity Data Manager (32-bit), Relativity Data Manager for ADO (*.rcg), Relativity Client (*.rcg), or Relativity Client for ADO (*.rcg), then click Next.
      Note: For use with Relativity Designer, we recommend the Relativity Data Manager (32-bit) or the Relativity Client (*.rcg) drivers.
    2. Click Finish.

    The DSN tab of the Relativity dialog box is displayed.

  5. In the Data Source Name field, enter a name for the data source.
  6. In the Description field, enter a description (optional).
  7. If the Micro Focus Relativity Data Manager (32-bit) driver was selected in step 4, in the Catalog section, do one of the following:
    • To use an existing catalog file, click Select Catalog, navigate to an .rcg file, then click Open.
    • To create a new catalog file, click Create Catalog, navigate to its required location, enter a file name, then click Open.
  8. If the Micro Focus Relativity Client driver was selected in step 4, do the following:
    1. If the Server Name field does not contain the name of the data server, click the Servers button, then click New and enter the network name of the data server machine.
    2. In the Server Name field, select the name of the machine on which the data server is running.
    3. In the Server DSN field, select the name of the server data source.
  9. Click OK.
    Note: These options are the minimum required to create the data source; for a more comprehensive explanation of all the options on this dialog box, refer to the Relativity Data Manager Help file.

    The Open Existing Data Source dialog box is displayed. If necessary, locate the name of the new data source and select it.

  10. Click Connect.
    • If this is a new catalog, it is now open.
    • If this is an existing catalog, and security has been defined, the Database Logon dialog box is displayed. Enter valid logon credentials, then click Login to open the catalog.
Parent topic: Configuring Relativity Data Sources
Related tasks
Opening an Existing Data Source
Closing a Data Source
Related reference
Single-tier and Client/Server Data Sources
Relativity Drivers


Opening an Existing Data Source

Note: You cannot open a data source if another user has it open in either Relativity Designer or Relativity DBA.
  1. Start the Relativity Designer.

    The Relativity Designer window opens.

    Note: When you start Relativity Designer, you are prompted to open the last opened data source. If you choose to open that data source, you do not need to follow the further instructions; if you do not choose to open the last data source, click Cancel and continue.
  2. On the File menu, select one of the following:
    • Connect to <data source last opened> - use this option to open the same data source as was opened in your last session.
    • Connect to Existing Data Source - use this option to open a data source that has already been configured.

      The Open Existing Data Source dialog box is displayed. (If you selected Connect to <data source last opened>, skip the next step.)

    Shortcut: Click the data source to the right of Recent DSN, select the required data source, then click Connect.
  3. On the Open Existing Data Source dialog box, click the data source currently shown, select the data source to open, and then click Connect.

    If the catalog associated with this data source has no security (that is, no group owner), the catalog is opened immediately; if this is the case, you are advised to add some privileges to the catalog - see Catalog Ownership and procedures on how to define catalog ownership.

    If the catalog has a group owner, the Database Logon dialog box is displayed.

  4. Complete the fields in the Database Logon dialog box, then click Connect:
    • UserId - the name of the owning group or the name of a user in the owner group.
    • Password - the group/user may not have a password set; if not, leave this field blank.

    The data source is opened, and you are connected to the catalog.

Parent topic: Configuring Relativity Data Sources
Related tasks
Setting up a New Data Source
Closing a Data Source
Related reference
Single-tier and Client/Server Data Sources
Relativity Drivers


Closing a Data Source

To close a data source, do one of the following:

  • On the File menu, click Close Current Data Source.

  • To the right of the Current DSN box, click Close.

When you close a data source, the Relativity Designer window remains open, allowing you to reopen the data source, open another data source, set up a new data source, or exit the Relativity Designer.

Parent topic: Configuring Relativity Data Sources
Related tasks
Setting up a New Data Source
Opening an Existing Data Source
Related reference
Single-tier and Client/Server Data Sources
Relativity Drivers


Configuring the Workspace

By default, the Relativity Designer window has four discrete areas, as shown in Relativity Designer Window. You can configure certain elements of this to suit your needs.

The Catalog Explorer, Properties pane, and the Status pane can all be undocked, and then moved to different locations within the window. Within the Work area, you can also perform similar docking and resizing of tabs, within the confines of the Work area; this is useful if you want to display two FDs side by side, for comparison.

You can also alter the appearance of the Relativity Designer window by applying a theme.

  • Relativity Designer Window
  • Setting a Theme for the Relativity Designer Window
Parent topic: Getting Started


Relativity Designer Window

The Relativity Designer window has four discrete areas:

1. The Catalog Explorer
This is the main navigational tool to allow you to move between most areas of the catalog.
All main objects within the catalog are displayed in this pane in one of three main sections:
  • File Definitions - The list of active FDs within the catalog. From this section, you can see the primary key for the FD, create any record types to associate with the FD, and generate table definitions from the FD.
  • Table Definitions - Displays the tables within the catalog as an alphabetical list. From this section you can also create new table definitions. It is also where you can create and configure multiple tables from the definitions.
  • User Groups and Users - The list of current groups and their users. From this section you can create new groups and users, and edit or delete existing ones.

2. Work area

This is the main area where you work on the contents of your FDs and tables. It is a tabbed area that allows you to open many FDs, tables, and settings dialogs (from the Tools menu) at once, so you can work on things concurrently.

3. Properties pane

This pane displays detailed information on elements of the catalog, such as individual data items and table definitions.

4. Status pane

The Status pane displays an audit trail of system responses to your catalog operations. Click each of the tabs (Errors, Warnings, Info, and Time) to toggle that particular information on and off. You can also save off the current information to a text file, or clear the messages down.

Another salient section of the screen is the Current DSN indicator. Not only does it show which catalog you are currently logged on to, but it also enables you to quickly connect to other catalogs.

Parent topic: Configuring the Workspace
Related reference
Setting a Theme for the Relativity Designer Window


Setting a Theme for the Relativity Designer Window

  1. On the Tools menu, point to Theme and select one of the available themes.

    The theme is applied to the Relativity Designer window.

Parent topic: Configuring the Workspace
Related information
Relativity Designer Window


Setting Options

Relativity allows you to specify default settings for various configuration preferences, including data sources, date formats, and COBOL types.

To display the Options pane:

  1. On the Tools menu, click Options.
  2. In the Options pane, click one of the option tabs to display the corresponding preferences:
  • General Options
    The General tab contains options that enable the user to specify general behavior and contents of Relativity Designer.
  • File Options
    The File page contains options that enable the user to specify the behavior and contents of the FD form.
  • Table Options
    The Table tab contains options that enable the user to specify the behavior and contents of the Table form.
  • Catalog Options
    The Catalog tab contains options that enable the user to specify the way in which the COBOL data file will be interpreted by Relativity.
  • Date Format Options
    Because the COBOL language does not have a representation for date and time values, many storage formats have been used to represent date and/or time values. Each date and time format is represented in Relativity as a COBOL data item transform.
  • COBOL Data Types Options
    The COBOL Data Types tab contains options that enable the user to specify settings for COBOL data types, such as COMP-6, COMPUTATIONAL, numeric edited, and alphanumeric edited.
  • Advanced Options
    The Advanced tab contains miscellaneous options for the advanced user.
Parent topic: Getting Started


General Options

The General tab contains options that enable the user to specify general behavior and contents of Relativity Designer.

The following table describes the options available on the General tab.

Option | Description
Open Last Data Source on Startup | When this tick-box is selected, Relativity Designer remembers the last data source that was open, and attempts to open it again the next time it starts.
Show Start Page on Startup | When this tick-box is selected, the Start Page tab is open when you first open a data source.
Require Catalog have Owner Group | When this tick-box is selected, if a catalog does not have an owner group when you log on, you are prompted to add a new group, which will become the owner group.
Default maximum rows returned in Show Data | Set the maximum number of rows that are returned when you preview table data. You can adjust this temporarily when previewing the data.
Automatically grant 'SELECT' access in granting other table/column privileges | When this tick-box is selected, 'SELECT' access is automatically granted when granting other table/column privileges. When this tick-box is not selected, 'SELECT' access must be granted manually each time.
Save layout | Relativity Designer remembers certain screen sizings and positions.
Parent topic: Setting Options


File Options

The File page contains options that enable the user to specify the behavior and contents of the FD form.

The following table describes the options available on the File tab.

Option | Description
Multi-File label length | The maximum length of the Multi-File Label Column Name string used when multi-file support is enabled for an FD. If you exceed the length when prompted, multi-file support is not enabled.
Omit hyphen in column names | When this tick-box is selected, hyphens are omitted from the default column names. When this tick-box is not selected, hyphens are replaced by underscores.
Camel case column names | When this tick-box is selected, default column names are in camel case. When this tick-box is not selected, column names are in upper case.
Edit Default Values | If selected, the Default Value option in the Properties pane is editable. Default values are used when tables, which allow updates and inserts, are defined. If this option is not selected, the Default Value column is not displayed in the FD form.
Parent topic: Setting Options
Related reference
Defining Conditions
User Data Type attribute
Default Column Name attribute
Transform attribute
Defining Null Information
Supporting Multi-file Tables


Table Options

The Table tab contains options that enable the user to specify the behavior and contents of the Table form.

The following table describes the options available on the Table tab.

Option | Description
Inherit comments from FD | When this tick-box is selected, newly added columns inherit any comments from their corresponding data items in the FD.
Show logical order transform | When selected, the LogicalOrder transform is available in the Properties pane (Column Transform option), in the table form.
Parent topic: Setting Options
Related tasks
Enabling the LogicalOrder Column Transform


Catalog Options

The Catalog tab contains options that enable the user to specify the way in which the COBOL data file will be interpreted by Relativity.

The following table describes the options available on the Catalog page.

Option | Description
Translate spaces as zeroes Translates space characters and binary zeros to zero characters in the data source.
Note: This option has no effect on data items that are either all or part of a key.

There are three possible states that may be selected for this option:

  • Never - returns an error when this condition is encountered. This is the default.
  • Yes, Except for Record Key Data Items - corrects the condition for all data items except for record keys, which will still return an error.
  • Always - corrects the condition in all instances.
    Note: Selecting the Always state will result in some numeric data items not being available to participate in SQL indexes.
Interpret unsigned numbers as positive Interprets numeric data not having explicitly correct negative sign values for the data type as positive (even though the data do not have explicitly correct positive sign values).
There are three possible states that may be selected for this option:
  • Never - returns an error when this condition is encountered. This is the default.
  • Yes, Except for Record Key Data Items - corrects the condition for all data items except for record keys, which will still return an error.
  • Always - corrects the condition in all instances.
    Note: Selecting the Always state will result in some numeric data items not being available to participate in SQL indexes.
Invalid Numerics Return NULL Returns a NULL value for any column based on a data item containing invalid numeric data.
There are three possible states that may be selected for this option:
  • Never - returns an error when this condition is encountered. This is the default.
  • Yes, Except for Record Key Data Items - corrects the condition for all data items except for record keys, which will still return an error.
  • Always - corrects the condition in all instances.
    Note: Selecting the Always state will result in some numeric data items not being available to participate in SQL indexes.
Invalid Dates Return NULL Returns a NULL value for any date or date/time column based on a data item containing invalid date ranges either because the underlying numeric data is invalid, or the month or day is out of range.
There are three possible states that may be selected for this option:
  • Never - returns an error when this condition is encountered. This is the default.
  • Yes, Except for Record Key Data Items - corrects the condition for all data items except for record keys, which will still return an error.
  • Always - corrects the condition in all instances.
    Note: Selecting the Always state will result in some numeric data items not being available to participate in SQL indexes.
Automated LogicalOrder Transform Indicates that a LogicalOrder column transform will be placed automatically on every text column of a data source.
There are three possible states that may be selected for this option:
  • Never - causes the LogicalOrder transform not to be placed automatically on every text column of a data source. This is the default.
  • Yes, Except for Record Key Data Items - applies the transform to all text columns except where it would result in the loss of an index on the table.
  • Always - causes the LogicalOrder transform to be placed automatically on every text column of a data source.
Comment | This area is a free-format text field that will be stored inside the catalog. The Relativity Designer will display the comment on its Help About form, if there is a comment. One possible use for this text field would be catalog version information.
Parent topic: Setting Options


Date Format Options

Because the COBOL language does not have a representation for date and time values, many storage formats have been used to represent date and/or time values. Each date and time format is represented in Relativity as a COBOL data item transform.

Since many application data sources are internally consistent in the date and time formats used, use the options on this tab to limit the number of choices displayed within Relativity (typically in the Transform column of the FD form).

The following table describes the options available on the Date Format tab.

Option | Description
Enable Date/Time Transforms on Table Columns | When selected, the date/time transforms available in the FD form are also available in the table definition form. Selecting this option is discouraged.
YYMMDD Format Transforms | When selected, the date transform YYMMDD choices are available.
MMDDYY Format Transforms | When selected, the date transform MMDDYY choices are available.
DDMMYY Format Transforms | When selected, the date transform DDMMYY choices are available.
YYDDD Format Transforms | When selected, the date transform YYDDD choices are available.
YYYY Format Transforms | When selected, the date transform YYYY is available for any YY form chosen. For example, if YYMMDD Format Transforms is selected, then selecting YYYY Format Transforms causes YYMMDD and YYYYMMDD date transforms to be available.
Days Format Transforms | When selected, the date transform Days is available. The transform represents the number of days since a specific day.
HHMM Format Transforms | When selected, the time transform HHMM choices are available. In addition, if Date/Time Format Transforms is selected, HHMM forms of any date transforms are also available. For example, if YYMMDD Format Transforms is selected, then selecting HHMM Format Transforms causes both YYMMDD and YYMMDDHHMM date transforms to be available.
HHMMSS Format Transforms | When selected, the time transform HHMMSS is available. In addition, if Date/Time Format Transforms is selected, HHMMSS forms of any date transforms are also available. For example, if YYMMDD Format Transforms is selected, then selecting HHMMSS Format Transforms causes both YYMMDD and YYMMDDHHMMSS date transforms to be available.
HHMMSShh Format Transforms | When selected, the time transform HHMMSShh is available. In addition, if Date/Time Format Transforms is selected, HHMMSShh forms of any date transforms are also available. For example, if YYMMDD Format Transforms is selected, then selecting HHMMSShh Format Transforms causes both YYMMDD and YYMMDDHHMMSShh date transforms to be available.
Date/Time Format Transforms | When selected, combinations of the selected date and time transforms are available. For example, if Date/Time Format Transforms, YYMMDD Format Transforms, and HHMMSShh Format Transforms are selected, both YYMMDD and YYMMDDHHMMSShh date transforms are available.
Configurable Format Transforms | When selected, the end-user configurable 6-digit (and 8-digit, if the Include YYYY Forms option is selected) date transforms are available. See Defining Date Constants .
Period Begin/End Format Transforms | When selected, the YYMM01, YYMM31, YY001 and YY365 (and YYYYMM01, YYYYMM31, YYYY001 and YYYY365 if YYYY Format Transforms is selected) date transforms are available. These transforms assume the first or last day of a month or year.
9s Complement (date transform modifier) | When selected, the 9s Complement modifier is available. This modifier subtracts the value of the COBOL data item from all 9's before computing the date or time value using the modified transform.
10s Complement (date transform modifier) | When selected, the 10s Complement modifier is available. This computes the 9s Complement modifier, and then and adds 1 to that value before computing the date or time value using the modified transform. Note: The 10s Complement of a zero value is defined to be zero.
3m Complement (date transform modifier) | When selected, the transforms incorporating the 3m Complement, which complements the value of the COBOL data item with respect to 3,000,000 based on a date format of CYYMMDD, are available.
NCR Complement (date transform modifier) | When selected, the NCR Complement modifier is available. This modifier compliments the value of the COBOL data item with respect to 30,000 based on a date format of MMDDYY.
+ Subscript (date transform modifier) | When selected, the YYDDD, YYDDDHHMM, YYDDDHHMMSS, YYDDDHHMMSShh, YYMMDD, YYMMDDHHMM, YYMMDDHHMMSS, YYMMDDHHMMSShh date transforms are available. Additionally, if this is selected, all of the YYYY formats of the date transforms are available. All of these transforms allow access to combined date and OCCURS items.
Parent topic: Setting Options
Related reference
Modifiers for Date and Time Transforms
Special Date and Date Time Transforms


COBOL Data Types Options

The COBOL Data Types tab contains options that enable the user to specify settings for COBOL data types, such as COMP-6, COMPUTATIONAL, numeric edited, and alphanumeric edited.

The options selected in the tab determine the choices available in the Item Type list displayed in the Add COBOL Data Item Redefinition dialog box.

The following table describes the options available on the COBOL Types page.

Option | Description
Include Micro Focus COBOL data types | Select this tick-box to include Micro Focus COBOL data types in the list of data types displayed in the Item Type list in the Add COBOL Data Item Redefinition dialog box. Selecting this box also displays the Data File Format box on the Data Source page. If the data files to be accessed through this catalog do not include any Micro Focus COBOL data types, do not select this tick-box.
Include RM/COBOL data types | Select this tick-box to include RM/COBOL data types in the list of data types displayed in the Item Type list in the Add COBOL Data Item Redefinition dialog box. If the data files to be accessed through this catalog do not include any RM/COBOL data types, do not select this tick-box.
Include EBCDIC data types | When this tick-box is selected, the catalog includes the EBCDIC data types.
Include alphanumeric edited data types | When this tick-box is selected, the catalog includes the alphanumeric edited data type described by the PICTURE character-string; for example, PIC XBXBX.
Include data types specific to RM/COBOL (74) | When this tick-box is selected, the catalog includes the COMP-3 and COMP data types with a special positive sign convention.
Include data types specific to RM/COBOL (74) found in the RM/COS operating system | When this tick-box is selected, the catalog includes the special COMP-3 and COMP data types with regard to minus and positive sign conventions in the RM/COS operating system.
Computational data types | When this tick-box is selected, the catalog includes the signed decimal COBOL data type described by the USAGE IS COMPUTATIONAL clause.
Computational No Sign data types | When this tick-box is selected, the catalog includes COMP-6 data type extension found in RM/COBOL.
Include numeric edited data types | When this tick-box is selected, the catalog includes the numeric edited data type described by the PICTURE character-string; for example, PIC Z9.99.
Include floating point data types | When this tick-box is selected, the catalog includes the floating point COBOL data types described by the USAGE IS COMP-1 and COMP-2 clause. Note Floating point data types will appear in the Item Type list in the Add COBOL Data Item Redefinition dialog box only if the Micro Focus Types tick-box is selected.
Include JUSTIFIED data types | When this tick-box is selected, the catalog accepts data items described with the JUSTIFIED clause.
Binary Byte Storage Mode | When this tick-box is selected, BINARY usage (and other binary usages, such as COMP-4, COMP-5, and possibly COMP) are assumed to use byte storage mode . If this tick-box is not selected, binary usage items are assumed to use word storage mode . Note: In word storage mode, the same number of bytes is assigned regardless of whether the data item is signed or unsigned. In byte storage mode, the number of bytes assigned is dependent on whether the data item is signed or unsigned.
Parent topic: Setting Options
Related reference
Redefining Data Items


Advanced Options

The following table describes the options available on the Advanced tab.

Option | Description
Catalog Expires | By selecting this tick-box and entering an expiration date in the Date box, you can make access to a catalog unavailable after a specified date. By default, the date entered in the Date box is the current date. You can type a different date in this box or you can click the Calendar button to select a date from the calendar. You also can enter a date format other than the default format. Note: The catalog expiration date feature does not affect the catalog owner's access to the catalog.
Verbosely Log Importer | When this tick-box is selected, trace import process verbosely. Use only under the direction of Micro Focus Support staff.
Parent topic: Setting Options


Preparing the COBOL Source

  • Importing COBOL File Definitions into Relativity
    Use the COBOL FD Importer to import the source COBOL definitions that the relational tables are derived from.
  • Maintaining Character Sets
    Maintain a list of character sets that Relativity is able to recognize.
  • Define Nonstandard Character Sets
    Map nonstandard character sets to ones Relativity is familiar with in order to show data that originated from a source that Relativity is unable to recognize.
Parent topic: Micro Focus Relativity Designer for Windows


Importing COBOL File Definitions into Relativity

The Relativity Designer uses the COBOL FD Importer to import new COBOL FDs from a COBOL source file, a compiled object file, or a Relativity symbol table file to a catalog. The import process allows you to selectively add FDs to a catalog; after which, you can augment the file definitions to create your table definitions.

The COBOL FD Importer is also used if you need to update existing definitions in a catalog if your COBOL source definitions have changed. There is also another importer, the Data Source Importer, which you use to merge existing elements from other catalogs into one central catalog.

  • Creating a Relativity Symbol Table
  • Importing from a COBOL Source File or Relativity Symbol Table
  • Extraction Restrictions
Parent topic: Preparing the COBOL Source
Related tasks
Merging from Another Relativity Data Source
Updating FDs from a COBOL Source File or Relativity Symbol Table


Creating a Relativity Symbol Table

The Relativity Designer includes the COBOL FD Importer to import COBOL FDs into a catalog. As part of that process, a Relativity symbol table file (or .rst file) is automatically generated.

A Relativity symbol table file contains one or more file definitions (FDs) extracted from a COBOL source file; you can select which of these FDs to import into the catalog. An .rst file can also be used to populate other catalogs with the same FDs if the COBOL source is not available.

The extraction process extracts information from the file control entry (SELECT clause), file description entry (FD entry), and the associated data description entries for each file described in the COBOL source file, and creates the Relativity symbol table file using this information.

The COBOL FD Importer also extracts information about Working-Storage Section and Linkage Section data description entries, since these may include record description entries of interest to Relativity.

When generating an .rst file from COBOL source, you should only use files that compile cleanly. Also, there are a number of restrictions placed on the source code that can pass through the extraction process; see Extractions Restrictions for details.

Parent topic: Importing COBOL File Definitions into Relativity
Related reference
Importing from a COBOL Source File or Relativity Symbol Table
Extraction Restrictions


Importing from a COBOL Source File or Relativity Symbol Table

  1. With a catalog open in the Relativity Designer, on the File menu, click Import COBOL FDs.

    The COBOL FD Importer tab is displayed.

  2. If the current data source is a Client/Server data source, the Remote tick-box is selected: this allows you to select files on the Data Server machine during file import selection. If you want to select files on your local machine for import, ensure Remote is not selected.
  3. In the Import FDs From field, select the type of import:
    • Import from a COBOL source (.cbl) file:
      CAUTION:
      Only use a source file that contains well-formed COBOL syntax that compiles cleanly.
      Note: The New CST file compiled from COBOL source option is only available if you have Visual COBOL or Enterprise Developer installed.
      1. In the Import FDs From field, select New RST file compiled from COBOL source.
      2. To the right of the File to Import field, click [image] (Select file to import), then use the Open dialog box to select a .cbl file.
      3. If necessary, enter the appropriate compiler (directive) options in the Compilation Options field.
      4. If the FD within the source includes references to copy files, to the right of the Source/Copy Path field, click [image] (Select file to import) and select the folder(s) in which the copy files reside.
        Note: If you are having issues with the import, you may be requested to perform it with Keep Temporary Files after Import selected, which retains the temporary files created during the import process; SupportLine can use the .lst and .err.xml temporary files to help troubleshoot import issues.
    • Import from an RM/COBOL object (.cob) file:
      Prerequisite: The object file must have been compiled with at least the Y (or Y=1) compiler option.
      1. In the Import FDs From field, select Existing COB file.
      2. To the right of the File to Import field, click [image] (Select file to import), then use the Open dialog box to select a .cob file.
    • Import from an Relativity Symbol Table (.rst) file:
      1. In the Import FDs From field, select Existing RST file.
      2. To the right of the File to Import field, click [image] (Select file to import), then use the Open dialog box to select an .rst file.
  4. Click Read File and Record Descriptions.

    A further two tabs are displayed. The Items to Import tab displays the FDs found in the selected file, and the Messages tab contains output from the extractor process.

  5. In the Items to Import tab, select the file definition(s) to import.
    Note: If you need to import other COBOL items from the source that are not part of the file definition (e.g. working-storage items), click Show Advanced Import Options, then select from the additional items displayed.
  6. Click Add to Catalog.

    The selected file definitions are now displayed in the Catalog Explorer.

Parent topic: Importing COBOL File Definitions into Relativity
Related concepts
Creating a Relativity Symbol Table
Related reference
Extraction Restrictions


Extraction Restrictions

Depending on the import type selected in the Import FD From field of the Importer, there are a number of restrictions.

The following restrictions and problems exist in the extraction process when using the RM/COBOL Source File using RST Schema Extractor (.cbl -> .rst) option:

  • Empty groups generate a syntax error and the entire COBOL source is not imported into the catalog.
  • Data items with a USAGE Clause of Pointer are not supported. They will result in a syntax error and prevent the COBOL source from being imported into the catalog.
  • The source format extensions introduced in RM/COBOL 11, including longer source lines and changing of the right margin, are not supported, will result in syntax errors, and prevent the COBOL source from being imported into the catalog.
The following restrictions and problems exist in the extraction process for when using the RM/COBOL Object File (*.cob) option:
  • Object files must have been compiled with the Y (or Y=1) compiler option.
  • Empty groups are ignored and are not imported into the catalog.
  • The following relational-operators for the VALUE clause are not supported: GREATER THAN, >, LESS THAN, <, GREATER THAN OR EQUAL TO, >=, LESS THAN OR EQUAL TO, <=, and LIKE, and their NOT variations. Condition items with these relational operators are ignored and not imported into the catalog. For more information, see Relation Condition in Chapter 5 and VALUE Clause, Format 2 in Chapter 4 of the RM/COBOL Language Reference Manual.
  • Data items with USAGE Clause of Pointer generate an import error and the entire COBOL source is not imported into the catalog.
  • RM/COBOL object programs do not contain the original level numbers for data items defined in a record description. Therefore, level numbers are generated during import in increments of 5. The generated level numbers are stored in the catalog during import and cannot be changed.
Parent topic: Importing COBOL File Definitions into Relativity
Related concepts
Creating a Relativity Symbol Table
Related reference
Importing from a COBOL Source File or Relativity Symbol Table


Maintaining Character Sets

Character sets provide a means of associating language characters with an 8-bit number to represent those characters in a data file. It is possible that the character set used to represent the data within a COBOL data file is different from the character set used by the ODBC application receiving the data.

The Character Set Maintenance dialog box provides Relativity with a mechanism for translating between the two character sets. However, Relativity must know the character set that is being used within the data file to represent the characters. This character set is initially determined when the FD is imported by setting the Character Set field, shown when Show Advanced Import Options is selected during a COBOL FD import. The character set may then be modified after import.

For more information and procedures on how to maintain character sets, choose from one of the following topics:

  • Adding a Standard Character Set
  • Adding a Non-standard Character Set
  • Changing Existing Character Sets for a Data Source
  • Changing the Location of the Euro Character in a Character Set
Parent topic: Preparing the COBOL Source


Adding a Standard Character Set

Relativity supports a large number of standard character sets. Before one of these standard character sets can be used, it must be added to the data source.

  1. From the Tools menu, click Character Sets.

    The Character Sets tab opens, displaying a list of character sets already in the catalog.

  2. Click Add a character set.

    The Add a Character Set to Catalog section is displayed.

  3. Click the box to the right of From standard character set, select one of the standard character sets, then click Add.

    It is added to the list of character sets already in the catalog.

  4. Click Save.

    The changes are saved.

  5. Close the Character Sets tab.
Parent topic: Maintaining Character Sets
Related reference
Adding a Non-standard Character Set
Changing Existing Character Sets for a Data Source
Changing the Location of the Euro Character in a Character Set


Adding a Non-standard Character Set

Occasionally, the data stored in a file does not match any of the supported character sets. In such cases, a nonstandard character set must be defined and imported into the Relativity data source before it can be used. To define a nonstandard character set, see Define Nonstandard Character Sets.

  1. From the Tools menu, click Character Sets.

    The Character Sets tab opens, displaying a list of character sets already in the catalog.

  2. Click Add a character set.

    The Add a Character Set to Catalog section is displayed.

  3. Click [image] to the right of From CS File, then use the Open dialog box to select a .cs file that contains the nonstandard character set.
  4. Click Add.

    To see a list of errors that can occur when a character set is imported into a Relativity data source, see Error Messages when Importing a Character Set.

    The new character set is added to the list of character sets already in the catalog.

  5. Click Save.

    The changes are saved.

  6. Close the Character Sets tab.
Parent topic: Maintaining Character Sets
Related reference
Adding a Standard Character Set
Changing Existing Character Sets for a Data Source
Changing the Location of the Euro Character in a Character Set
Error Messages When Importing a Character Set
Define Nonstandard Character Sets


Changing Existing Character Sets for a Data Source

If the actual character set that describes the characters in a data source's files is different from the character set Relativity has recorded, the Character Set Maintenance dialog box can be used to change it.

  1. From the Tools menu, click Character Sets.

    The Character Sets tab opens, displaying a list of character sets already in the catalog.

  2. Click Modify FD character sets.

    The Modify FD character sets section is displayed.

  3. In the list of current character sets, select the character set to change from.

    A list of files currently using that character set are listed.

  4. In the list of current character sets, select the character set to change to.

    By default, in the File Definition list, all files are selected to replace the old character set with the new one.

  5. In the Native and Source columns, clear the selections that you do not want to change, then click Replace.
  6. Click Save.

    The changes are saved.

  7. Close the Character Sets tab.
    Note: To show the updated details in the Catalog Explorer, you may need to click [image] (Refresh).

Shortcut:

To quickly change the character set of a particular FD file, select the required entry in the Catalog Explorer, then update the Source Character Set and Native Character Set properties in the Properties pane.

Parent topic: Maintaining Character Sets
Related reference
Adding a Standard Character Set
Adding a Non-standard Character Set
Changing the Location of the Euro Character in a Character Set


Changing the Location of the Euro Character in a Character Set

Some COBOL applications supported the Euro character before the International Standard Organization decided its value in standard character sets. In these instances, Relativity needs to modify its understanding of the value of the character in the standard character set.

  1. From the Tools menu, click Character Sets.

    The Character Sets tab opens, displaying a list of character sets already in the catalog.

  2. In the list of current character sets, select the required character set.
  3. Click the field in the Euro column, then enter a numerical value (between 0 and 255) that will correspond to the Euro character.
  4. Click Save.

    The changes are saved.

  5. Close the Character Sets tab.
Parent topic: Maintaining Character Sets
Related reference
Adding a Standard Character Set
Adding a Non-standard Character Set
Changing Existing Character Sets for a Data Source


Define Nonstandard Character Sets

Relativity supports many standard character sets. If you need to define a character set that is nonstandard, however, Relativity has the ability to map data stored in one character set to a different character set for display purposes. This is usually necessary when data that was initially stored using one character set standard must be displayed using another character set standard; for example, data stored on a UNIX server using an ISO 8859 standard character set that must be displayed on Windows using a Code Page standard character set. ISO 8859 and Code Page character set standards are similar, but not identical, in the 8-bit values that are used to represent the different display characters. When the standards disagree on the 8-bit values (known as Code Points), the actual character displayed (known as a Glyph) will be incorrect.

To describe a character set, Relativity uses a derivation of the Unicode Consortium's Format A character set definitions.

When the mapping tables are created between two character sets, unused Code Points and Code Points with unmatched Glyphs have a simple, one-to-one mapping between the two character sets. This mapping proceeds from the lowest Code Point to the highest and is symmetrical. That is, a character that is read and mapped through these mapping tables will have the correct value stored on a subsequent UPDATE operation.

If the data within a file does not match any of the character sets already defined in Relativity, then the character set of the data file must be installed in the Relativity data source. By so doing, Relativity can build the mapping tables later.

  • Unicode Consortium's Format A
  • Supported Standard Character Sets
  • Defining a Nonstandard Character Set
  • Modifying an Existing Relativity Character Set
  • Importing a Standard Character Set Not Supported by Relativity
  • Error Messages When Importing a Character Set
Parent topic: Preparing the COBOL Source


Unicode Consortium's Format A

Standard character sets in the Unicode Consortium's Format A are available from ftp://ftp.unicode.org/Public/MAPPINGS. To locate the character set you need, use one of the following methods:

  • If the character set is a standard Microsoft Windows Code Page, change to the directory, VENDORS/MICSFT/WINDOWS.
  • If the character set is an ISO 8859 character set, change to the directory, ISO8859.
  • If the character set is none of the above, explore the other directories in ftp://ftp.unicode.org/Public/MAPPINGS in order to locate the desired character set.
  • If you cannot find the character set you need, you must define a nonstandard character set or modify an existing Relativity character set.

Relativity augments this format with a Charset and EndCharset clause to allow more than one character set to appear in the character set source file.

A character set source file is a simple text file with the extension of .cs. Comments may appear anywhere in the file and are introduced with the hash character (#) and extend to the end of the line. Numeric values may begin with '0x' to indicate a hexadecimal constant, a '0' only to indicate an octal constant, or '1' through '9' to indicate a decimal constant. Strings are delimited by quotes ("").

One or more character sets may be in this file. The format of each character set is:

Charset "Character Set Name" character-set-number
code-point-value unicode-value
code-point-value unicode-value
.
.
.
EndCharset

where:

Character Set Name is a string that is the name of the character set to display in the Relativity Designer.

character-set-number is the number to assign to the character set. For character sets installed via the Relativity Designer, this value is ignored and assumed to be zero.

code-point-value is the 8-bit numeric value of the Glyph in the character set. A code-point-value that is not present in the character set is assumed to be unused.

unicode-value is the 16-bit numeric value of the Glyph in the Unicode standard. This value also may be a Unicode constant, in which case, it will be delimited by a less than symbol (<) and a greater than symbol (>). The most commonly used of these is the constant <NOT USED>, which indicates that the Code Point does not have a Glyph assigned to it.

Parent topic: Define Nonstandard Character Sets
Related reference
Supported Standard Character Sets
Defining a Nonstandard Character Set
Modifying an Existing Relativity Character Set
Importing a Standard Character Set Not Supported by Relativity
Error Messages When Importing a Character Set


Supported Standard Character Sets

Relativity supports the following standard character sets:

Windows Latin 1 | MS-DOS Cyrillic CIS-1 | MS-DOS Hebrew
Windows Latin 2 | MS-DOS Turkish | EBCDIC US Canada
Windows Latin 5 | MS-DOS Portuguese | EBCDIC International
Windows Cyrillic | MS-DOS Icelandic | EBCDIC Greek
Windows Greek | MS-DOS French Canada | EBCDIC Latin 5 Turkish
Windows Baltic Rim | MS-DOS Greek | ISO 8859-1
Windows Hebrew | MS-DOS Greek 1 | ISO 8859-2
Windows Arabic | MS-DOS Greek 2 | ISO 8859-5
MS-DOS Latin US | MS-DOS Baltic Rim | ISO 8859-6
MS-DOS Latin 1 | MS-DOS Russian | ISO 8859-7
MS-DOS Latin 2 | MS-DOS Arabic | ISO 8859-8
MS-DOS Cyrillic | MS-DOS Arabic ASMO |
Parent topic: Define Nonstandard Character Sets
Related reference
Unicode Consortium's Format A
Defining a Nonstandard Character Set
Modifying an Existing Relativity Character Set
Importing a Standard Character Set Not Supported by Relativity
Error Messages When Importing a Character Set


Defining a Nonstandard Character Set

  1. Using a text editor, edit a new file in which to place the character set. Name the file with the extension, .cs
  2. Insert the following line at the beginning of the file:

    Charset "Character Set Name" 0x0

    For Character Set Name, substitute the name for the character set that is to be visible from within the Select Character Set dialog box.

  3. Insert up to 256 lines into the file, one for each character in the character set being described. On each line there must be two entries, separated by a space or a tab, with an optional third entry, also separated by a space or tab. The first entry on the line must be the 8-bit Code Point value for the entry. This corresponds to the numeric value of the character being described. The second entry is the 16-bit Unicode character for the character being defined. The third entry is an optional comment for the line, preceded by a hash (#) character.

    For example, if the character set had a Euro Sign at position 128, the line for it would be:

    128 8364 #EURO SIGN

    Or, using hexadecimal notation:

    0x80 0x20AC #EURO SIGN

    For Code Points where there is not a defined character, use the text <NOT USED> for the second entry.

    Note: A Unicode character may be used only once in a character set. If it appears twice, an error indicating a duplicate Unicode character will be generated during import. Unique Unicode characters are necessary for all defined Code Points in order to generate mapping tables that can be used to translate characters both to and from the new character set. Rather than arbitrarily assigning Unicode characters to unused Code Points, either leave them out of the character set definition or use <NOT USED> as the Unicode character entry. When Relativity encounters the <NOT USED> entry, it creates an association in the character set being defined with unused or unmatched entries in the target character set. In this manner, if an undefined character is present in the data, it will be translated consistently.
  4. Following the lines describing the character set, insert the following line:

    EndCharset

  5. Save the file and import it into the Relativity data source.

To see a list of errors that can occur when a character set is imported into a Relativity data source, see Error Messages when Importing a Character Set.

Parent topic: Define Nonstandard Character Sets
Related reference
Unicode Consortium's Format A
Supported Standard Character Sets
Modifying an Existing Relativity Character Set
Importing a Standard Character Set Not Supported by Relativity
Error Messages When Importing a Character Set


Modifying an Existing Relativity Character Set

  1. Edit the file relcs.cs in the installation directory.
  2. Locate the character set to modify.
  3. Select and copy the lines Charset and EndCharset of the desired character set and all the text in between.
  4. Create a text file in which to place the modified character set and paste in the text from Step 3.
  5. Locate the Charset line and change the text between the quotes to the name for the character set that is to be visible from within the Select Character Set dialog box. Change the number at the end of the line to 0x0.
  6. Locate the lines for the Code Points to be changed in the character set. This can be done by examining first entry on each the line. This value is the numeric value for the character in the character set. For example, in most Latin-based character sets, the capital letter A has the Code Point value of 65 (or 0x41 hexadecimal).
  7. Change the second entry on the line to the Unicode value for the new character to be at this Code Point. For example, if you want the character at Code Point 65 to be interpreted as a capital letter A with an Acute, change the line to the following:

    0x41 0x00C1 #LATIN CAPITAL LETTER A WITH ACUTE

  8. If necessary, insert a new line with the Code Point and Unicode entries for new Code Points.
    Note: A Unicode character may be used only once in a character set. If it appears twice, an error indicating a duplicate Unicode character will be generated during import. Unique Unicode characters are necessary for all defined Code Points in order to generate mapping tables that can be used to translate characters both to and from the new character set. Rather than arbitrarily assigning Unicode characters to unused Code Points, either leave them out of the character set definition, or use <NOT USED> as the Unicode character entry. When Relativity encounters the <NOT USED> entry, it creates an association in the character set being defined with unused or unmatched entries in the target character set. In this manner, if an undefined character is present in the data, it will be translated consistently.
  9. Save the file and import it into the Relativity data source.

To see a list of errors that can occur when a character set is imported into a Relativity data source, see Error Messages when Importing a Character Set.

Parent topic: Define Nonstandard Character Sets
Related reference
Unicode Consortium's Format A
Supported Standard Character Sets
Defining a Nonstandard Character Set
Importing a Standard Character Set Not Supported by Relativity
Error Messages When Importing a Character Set


Importing a Standard Character Set Not Supported by Relativity

  1. FTP to the site ftp.unicode.org.
  2. Change to the directory Public/MAPPINGS .
  3. Locate the character set you want, as follows:
    • If the character set is a standard Microsoft Windows Code Page, change to the directory, VENDORS/MICSFT/WINDOWS
    • If the character set is a standard Microsoft DOS Code Page, change to the directory, VENDORS/MICSFT/PC
    • If the character set is an ISO 8859 character set, change to the directory, ISO8859.
    • If the character set is none of the above, explore the other directories in ftp.unicode.org/Public/MAPPINGS in order to locate the desired character set.
    • If you cannot find the character set you want, you must define a nonstandard character set or modify an existing Relativity character set.
  4. Locate the file for the desired character set and download the file to your local machine. Name it with the extension .cs.
  5. Edit the file with a text editor, taking care to delete any control characters, usually marked with the characters ^D, from the file.
  6. Insert the following line at the beginning of the file:

    Charset "Character Set Name" 0x0

    For Character Set Name, substitute the name for the character set that is to be visible from within the Select Character Set dialog box.

  7. At the end of the file, insert the following line:

    EndCharset

  8. Examine the remaining lines for any that are missing the second entry on the line. This second entry is the 16-bit Unicode character for the character being defined. In the definitions available on ftp.unicode.org, unused Code Points are left blank with the comment of UNDEFINED. Insert <NOT USED> as the second entry on the line.
    Note: A Unicode character may be used only once in a character set. If it appears twice, an error indicating a duplicate Unicode character will be generated during import. Unique Unicode characters are necessary for all defined Code Points in order to generate mapping tables that can be used to translate characters both to and from the new character set. Rather than arbitrarily assigning Unicode characters to unused Code Points, either leave them out of the character set definition, or use <NOT USED> as the Unicode character entry. When Relativity encounters the <NOT USED> entry, it creates an association in the character set being defined with unused or unmatched entries in the target character set. In this manner, if an undefined character is present in the data, it will be translated consistently.
  9. Save the file and import it into the Relativity data source.

To see a list of errors that can occur when a character set is imported into a Relativity data source, see Error Messages when Importing a Character Set.

Parent topic: Define Nonstandard Character Sets
Related reference
Unicode Consortium's Format A
Supported Standard Character Sets
Defining a Nonstandard Character Set
Modifying an Existing Relativity Character Set
Error Messages When Importing a Character Set


Error Messages When Importing a Character Set

The following errors may be produced when importing a nonstandard character set into a Relativity data source:

Redefinition of Character
Indicates that the value used in the code-point-value has appeared previously in the character set definition. A common cause of this problem is the omission of a unicode-value or code-point-value, causing the charset compiler to misinterpret the value. The code-point-value and unicode-value must appear in pairs.
Syntax Error
Indicates that the character set does not conform to the format of a character set definition. This usually indicates that a numeric constant was not detected where it was expected.
Unicode constant too large
Indicates that a unicode-value was larger than can be stored in 16-bits.
Code Point constant too large
Indicates that a code-point-value was larger than can be stored in 8-bits. This message may indicate a missing value from a code-point-value and unicode-value pair.
Illegal constant
Indicates that a decimal constant contained a nonnumeric character.
Illegal hex constant
Indicates that a hexadecimal constant contained a non-hex character.
Illegal octal constant
Indicates that an octal constant contained a non-octal character.
Illegal string constant
Indicates that a string constant did not terminate before the end of a line.
Unknown unicode constant
Indicates that a Unicode constant is unrecognized.
Unknown keyword
Indicates that either the keyword Charset or EndCharset was not located where expected.
Keyword too long
Indicates that a keyword was expected in the character set source file, but it was too large to be processed.
String constant too long
Indicates that a string constant was too large to be processed.
Illegal Unicode constant
Indicates that a Unicode constant did not have a closing delimiter (>) before the end of a line.
Unicode constant too long
Indicates that a Unicode constant was too long to be processed.
In Character Set Name, Unicode unicode-value duplicated at positions code-point-value and code-point-value
Indicates that the character set with the name Character Set Name has the same Unicode character in multiple Code Point locations. In order to create symmetrical mapping tables, a Unicode character may be used only once per character set.
Parent topic: Define Nonstandard Character Sets
Related reference
Unicode Consortium's Format A
Supported Standard Character Sets
Defining a Nonstandard Character Set
Modifying an Existing Relativity Character Set
Importing a Standard Character Set Not Supported by Relativity
Adding a Non-standard Character Set


Augmenting the COBOL File Definition in the FD Form

After you have imported the file definitions into the Relativity catalog, you are ready to use the Catalog Explorer to augment the FD in preparation for creating the table definitions.

As the import process is not capable of providing all the information regarding the meaning and logical structure of the COBOL file definitions, you must manually provide these yourself.
  • Defining Default Column Names
    Use the Edit Default Column Names tool to define column names that are compatible with SQL naming standards. During the import process, Relativity also pre-emptively removes any common prefixes applied to the data names in an attempt to maintain compatibility.
  • Redefining Data Items
    Explicitly redefine data items to more accurately reflect what the data represents.
  • Defining Conditions
    Condition variables are data items in your file definitions that contain 88-level conditions. The conditions are used within record types, to determine the columns that should be included in a table. If your imported FD does not already contain such items, you must define them manually.
  • Defining Record Types
    Record types are subsets of a complete file definition, which are useful when the FD describes a data file that contains different types of records. Use record types to only include the data items pertaining to a particular type of record, filtering out the other items.
  • Defining Record Type Filters
    Define the filters that utilize the created record types. These filters are specified as logical expressions composed of factors (containing the 88-level condition-names) and the logical operators NOT, AND, and OR.
  • Defining Default Values
    Define default values used in write operations if an item is not represented by a column in an SQL INSERT statement. The value will be limited to the range of values that is valid for the underlying COBOL data type.
  • Defining Custom Data Types
    Define a common set of column characteristics that can be applied to one or more columns, for any tables in your catalog.
  • Specifying Treatment of the OCCURS Clause
    Use the available techniques for handling the mapping of repeating data items in COBOL to normalized relational tables.
  • Using Functions and Transforms
    Define both internal functions and transforms to act on COBOL data items.
  • Defining Item Sets
    Define items sets, which are composed of two or more data items in a COBOL record that contain identical information, but that have been identified as a set of redundant data items.
  • Defining Null Information
    Define the relationship between COBOL data-item values and the SQL NULL value.
  • Specifying Comments
    Specify comments for data items displayed in the FD form. Tables can also inherit the comments within an FD.
  • Filtering File Definitions
    You can apply a filter to the data items currently displaying in the FD. Populate the Filter items text box with the full or partial name from the COBOL Name column to apply the filter; clear any text from the Filter items text box to remove the filter.
  • Exporting File Definitions
    You can export the file definition displayed in the FD form to a COBOL source file suitable for use by a COPY statement in a COBOL program.
Parent topic: Micro Focus Relativity Designer for Windows


Defining Default Column Names

In Relativity, each data item defined in a file definition (FD) has a default SQL column name based on its COBOL data-name. Most COBOL programs have a data-name for a data item that reflects COBOL coding standards meant to communicate information to the programmer. SQL column names, however, must communicate meaning to the end-user.

Unfortunately, COBOL and SQL have different coding standards for names, and therefore the default SQL column names generated by Relativity takes this into account. An example of this is the hyphen (-) character: since this is a legal character in COBOL, but not in SQL, Relativity removes the hyphens in the default column names.

The first step in augmenting the COBOL file definitions is examining the default column names for each item and altering them to be the desired SQL column name, which includes making them meet SQL's coding requirements for column names, and avoiding reserved words.

One way to change the default column name for a data item is to edit the name directly in the Default Column Name column. Alternatively, use the Edit Default Column Names tool to perform a search and replace.

Whichever method you employ, you cannot use spaces for column names that are to be used in tables. You can use spaces for the names in the FD's Default Column Name column, but when you select the column for inclusion in a table definition, you must enter a valid column name that does not contain any spaces.

  • Editing Default Column Names
Parent topic: Augmenting the COBOL File Definition in the FD Form
Related reference
Defining Conditions
User Data Type attribute
Default Column Name attribute
Transform attribute
Defining Default Column Names
Pattern Matching
Rules for Insertable Tables


Editing Default Column Names

Instead of editing each default column name manually, use the Edit Default Column Names tool to batch-edit column names.

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. In the Default Column Name header, click [image] (Edit default column names).

    The Edit Default Column Names dialog box is displayed.

  3. In the Source section, select the source names from which to generate the amended column names:
    • Current column names - the names currently displayed in the Default Column Name column.
    • COBOL data item names - the original COBOL data-names, as displayed in the COBOL Name column.
  4. In the Apply to items section, select which column names are affected:
    Note: Subscript, condition, function, and FILLER items are ignored.
    • Only selected items - the items currently selected in the form.
    • All items - all items in the form.
  5. In the Find & Replace section, select the part of the item that is affected:
    • Replace prefix - The replace string in a prefix of a COBOL data-name. This option is not available when replacing current column names.
    • Replace suffix - The replace string is a suffix of a COBOL data-name. This option is not available when replacing current column names.
    • Replace anywhere - The replace string can appear anywhere. This option reveals two further options: Text search - the replace string should be treated purely as text, and Regular Expression search - the replace string contains regular expression characters, and should be processed as such.
  6. In the Hyphens & case section, select the treatment of hyphens and character case:
    Note: This section is only enabled when the source is set to COBOL data item names.
    • Remove hyphens - hyphens are removed from the string.
    • Replace with underscores - hyphens are replaced by underscores.
    • Camel case - characters are converted to camel case. All spaces and hyphens are removed, and the letter following the space or hyphen is capitalized; all other letters are lower case; for example, PRODUCT-KEY would become ProductKey.
    • Upper case - all characters are converted to upper case.
  7. In the Replace and With fields, enter the strings to search and replace, including any regular expression characters when performing a regular expression search.
  8. Click Apply.

    The changes are made in the Default Column Name column.

  9. Click Save to Catalog.
Parent topic: Defining Default Column Names
Related reference
Pattern Matching
Regular Expression Syntax Used in Pattern Matching


Redefining Data Items

Some file definitions do not contain all the implicit item definitions that exist in an application database. For example, an elementary data item in the file definition might be moved to a Working-Storage Section group item that is used to further subdivide the item for processing. Reference modification is another means of implicit redefinition or subdivision.

When it is necessary to expose these implicit subdivisions and redefinitions in the relational tables, the data items involved must be explicitly redefined within the Relativity Designer.

  • Redefining a Data Item
Parent topic: Augmenting the COBOL File Definition in the FD Form
Related reference
Defining Conditions
User Data Type attribute
Default Column Name attribute
Transform attribute
COBOL Data Types Options


Redefining a Data Item

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. Right-click the data item in the FD form for which a redefine is needed, then select Add Redefines.

    The Add redefines for <data-item> dialog box is displayed. The options displayed depend on the type of data item selected.

  3. In the COBOL Name field, enter a new data-name for the redefined item.
  4. The Item Type field defaults to the data item type being redefined. If required, click the type and select a different type.

    The remaining options applicable to the type are displayed.

  5. The Length field defaults to the length of the data item being redefined. If required, alter the length of the new item.
  6. The Ref. start field refers to the offset, and defaults to 1 for all types except RM/COBOL (1974) COMP-1 items. If you are redefining one of these types, you can change to offset so that the item is only partially redefined.
  7. In the Numeric section, which is only available for numeric items, change the following values, if required:
    • Precision - specifies the number of decimal digits and is constrained based on the data type and the length selected.
    • Scale - specifies the position of the decimal point from the right end of the new data item in terms of decimal digits. The absolute value of a negative scale factor specifies the number of digits to the right of the decimal point.

    The COBOL data description of the redefined item is displayed, and is updated as you alter the values.

  8. Click Add.

    The redefined item is added to the file definition.

  9. In the Default Column Name column, enter a column name for the redefined item.
  10. Click Save to Catalog.
Parent topic: Redefining Data Items


Defining Conditions

Records within COBOL data files often contain data items that are tested for specific values, in a COBOL program's Procedure Division. In order for Relativity to test data items, they must be conditional variables, in that they have one or more 88-level COBOL items associated with it. The following FD shows two conditional variables, with a number of 88-level items associated with each.

88-level items may already exist in the COBOL source, in which case they will be present in the FD after import. If they are not, and you need to perform a certain action depending on the value of a conditional variable (for example, apply a certain record type), you must create the 88-level conditions manually.

Conditional variables and conditions are used in conjunction with record types. Using the FD example above, the 03 OF-ORDER-TYPE conditional variable has two 88-level items (CREDIT and CASH). These items will each have different values assigned to them, and in turn may be associated with different record types, one including credit card details and the other not. When OF-ORDER-TYPE is set to the same value as the 88-level item CREDIT, the credit card record type is used to represent that record.

88-level conditions can include separate values for evaluating true and evaluating false. When setting the values, you can manually enter alphanumeric characters or hexadecimal values, or you can select standard COBOL literals such as LOW- and HIGH-VALUES. Manually entered values can be a single value, a range of values, or a number of separate values where each is evaluated.

Once you have defined conditional variables and their required condition values, create some record types that specify the condition values in their record type filters (see Defining Record Types and Defining Record Type Filters), or use the conditions to produce null information within a table (see Defining Null Information).

  • Adding a Condition
  • Editing a Condition
  • Deleting a Condition
Parent topic: Augmenting the COBOL File Definition in the FD Form
Related tasks
Defining Record Type Filters
Creating a Table Filter
Related reference
Defining Record Types
Defining Null Information
Defining Columns on Repeating Data Items


Adding a Condition

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. Right-click the data item in the FD form for which a condition is needed, then select Add 88.

    The Add condition under <data-item> dialog box is displayed. The options display depend on the data item type.

  3. In the Condition (88) Name field, type a condition name.
  4. In the Value field, enter the value which would result in a true condition.

    For alphanumeric types, the value can also be one of the standard COBOL literals or a hexadecimal representation: click Entered and select the appropriate value type. See entered numerics and hexadecimal condition values for more information.

  5. To create a range of values, repeat the same process for the Thru field.
  6. To add more values (not within a range), click [image] (Add New Value), then repeat the previous steps to add the value details.

    To move between the values, click the navigational arrows.

    These values are ones that will cause the evaluate as True if the value of the data item (condition variable) matches. The evaluation can also check specific values to evaluate False.

  7. To also set a false value for the condition, select Set to False, and then select the value type and value (if applicable).
  8. Click Apply.

    An 88-level entry is added to the FD.

  9. Click Save to Catalog.
    Tip: To view the values of the condition once saved, select it, and then view the details in the Properties pane.
Parent topic: Defining Conditions
Related tasks
Defining Record Type Filters
Related reference
Editing a Condition
Deleting a Condition
entered numerics
Hexadecimal condition values


Editing a Condition

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. Right-click the required 88-level condition and select Edit a condition item.

    The Edit condition <condition-name> dialog box is displayed.

  3. Edit the condition details, as appropriate, and then click Apply.
  4. Click Save to Catalog.

    The condition details are updated.

Parent topic: Defining Conditions
Related reference
Adding a Condition
Deleting a Condition


Deleting a Condition

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. Right-click the required 88-level condition and select Delete a condition item.

    A confirmation dialog box is displayed.

  3. Click Yes to confirm.

    The condition is deleted.

  4. Click Save to Catalog.
Parent topic: Defining Conditions
Related reference
Adding a Condition
Editing a Condition


Defining Record Types

Record types are subsets of a complete file definition, which are useful when the FD describes a data file that contains different types of records. Use record types to only include the data items pertaining to a particular type of record, filtering out the other items.

This type of scenario within a COBOL program would often be solved within the Procedure Division code, using IF statements to query the purpose of the data item to determine how it should be processed.

In Relativity, you must use conditional variables and 88-level conditions to query the values of data items, and then associate the relevant value with a record type. The association is made using the record type filter, which allows you to evaluate a data item 'true' or 'false' based on one or more values.

Define a record type by selecting the relevant data items to include (which are ultimately your table's column names), and apply a filter based on an 88-level condition. The record type then enables you to create a table definition that uses only the data items that you are interested in.

Record types are optional, and only filter out information for as long as the record type is applied to a table definition; no data items are permanently removed from the FD.

Indications that your FD may contain different record types, and could benefit from record types, are the presence of multiple 01 entries, or one or more REDEFINES clauses.

  • Adding a Record Type
  • Editing a Record Type
  • Renaming a Record Type
  • Deleting a Record Type
Parent topic: Augmenting the COBOL File Definition in the FD Form
Related tasks
Defining Record Type Filters
Related reference
Defining Conditions
User Data Type attribute
Default Column Name attribute
Transform attribute
Defining Conditions
Handling Multiple Record Types
Defining Record Type Filters
Defining Table Filters


Adding a Record Type

  1. In the Catalog Explorer, double-click the File Definitions node.

    The catalog's file definitions are displayed.

  2. Expand the relevant file definition, right-click Record Types and select New Record Type.

    The New Record Type dialog box is displayed.

  3. Type a name for the record type and click Add.

    The <file-definition-name> tab is displayed, and immediately applies the record type, as indicated by the record type selector displayed at the top of the pane.

  4. In the In Selected column, select each field to belong to the record type.
    Note: Selecting a parent node automatically selects all of its child nodes. If you do not want all of the child nodes, select the parent node for a second time to deselect child nodes.
  5. Click Save to Catalog.

    The record type is saved. Next, you must apply a filter to the record type in order for it to be selected for use by an appropriate condition variable.

Parent topic: Defining Record Types
Related reference
Editing a Record Type
Renaming a Record Type
Deleting a Record Type


Editing a Record Type

  1. In the Catalog Explorer, double-click the File Definitions node.

    The catalog's file definitions are displayed.

  2. Expand the relevant file definition, expand Record Types, then double-click required record type.
    Shortcut: If the containing file definition is already open, select the record type using the record type indicator displayed above the FD form.

    The record type is applied to the file definitions, with the included fields displayed in bold.

  3. Update the selection by selecting or clearing the fields in the In Record column.
  4. Click Save to Catalog.
Parent topic: Defining Record Types
Related reference
Adding a Record Type
Renaming a Record Type
Deleting a Record Type


Renaming a Record Type

  1. In the Catalog Explorer, double-click the File Definitions node.

    The catalog's file definitions are displayed.

  2. Expand the relevant file definition, and then expand the Record Types group.

    The record types for the file definition are displayed.

  3. Right-click the required record type and click Rename Record Type.

    The Rename Record Type dialog box is displayed.

  4. In the New Name field, type a name for the record type, then click Change.
Parent topic: Defining Record Types
Related reference
Adding a Record Type
Editing a Record Type
Deleting a Record Type


Deleting a Record Type

Warning: You can only delete a record type if it is not being used in a current table definition.
  1. In the Catalog Explorer, double-click the File Definitions node.

    The catalog's file definitions are displayed.

  2. Expand the relevant file definition, and then expand the Record Types group.

    The record types for the file definition are displayed.

  3. Right-click the required record type and click Delete Record Type.

    The record type is deleted immediately; no need to save to the catalog.

Parent topic: Defining Record Types
Related reference
Adding a Record Type
Editing a Record Type
Renaming a Record Type


Defining Record Type Filters

A record type filter defines criteria used to determine if a record within a data file will use the particular record type associated with the filter. A relational table that is based on a record type will only contain rows corresponding to records that evaluate true against the record type filter.

A record type filter is edited in a right-hand pane of the Designer window, and the filter itself is depicted as a tree. The top level of the tree is a list of AND-based factors; each factor must be TRUE for the filter to include the record with the record type.

Each factor can be a single condition, or it can be an OR list containing multiple conditions, one of which must be TRUE for the factor to be true.

A condition consists of a condition item (an 88-level item) and a desired result: TRUE when the condition item is TRUE, or FALSE when the condition item is not true (effectively, a NOT operation).

The following example shows a filter with two factors: one factor contains a single condition (CASH = True) and the other factor is an OR list that contains two conditions (FARGO-FREIGHT = True and WILD-GOOSE-EXPRESS = True). Both factors must evaluate TRUE for the record to be used in the record type: that is, CASH must evaluate to TRUE, and either FARGO-FREIGHT or WILD-GOOSE-EXPRESS must evaluate TRUE.

  • Adding a Factor to a Record Type Filter
Parent topic: Augmenting the COBOL File Definition in the FD Form
Related tasks
Adding a Condition
Related reference
Defining Record Types
Defining Conditions
Defining Table Filters
Analyzing Table Definition Errors


Adding a Factor to a Record Type Filter

Each record type filter comprises zero or more factors. Filters that contain no factors allow all records to be used with the record type.
  1. In the Catalog Explorer, double-click the File Definitions node.

    The catalog's file definitions are displayed.

  2. Expand the relevant file definition, expand Record Types, then double-click required record type.
    Shortcut: If the containing file definition is already open, select the record type using the record type indicator displayed above the FD form.

    The record type is applied to the file definitions, with the included fields displayed in bold. The <record-type-name> filter is displayed in the right-hand pane, and the FD editor enters edit mode for the record type.

  3. Click [image] (Add Factor) to the right of the AND operator.

    An empty factor is displayed.

  4. Click [image] and select a 88-level condition name.
  5. Click [image] and select the desired outcome:
    • Select True so that when the value of the 88-level condition matches its conditional variable, the filter is applied to the record.
    • Select False so that when the value of the 88-level condition does not match its conditional variable, the filter is applied to the record. This is the equivalent of a NOT operator.

      You can define further factors that have an AND or OR relationship with the one you just created.

  6. To define an AND relationship:
    1. Click [image] (Add Factor) to the right of AND.

      A new factor is displayed beneath the current one.

    2. Repeat steps 4 and 5 above to define the factor.
    3. Repeat step 6 to add more AND factors.
  7. To define an OR relationship:
    1. Click [image] (Add Condition) to the right of an existing factor.

      An OR + is displayed above the existing factor, and a new factor is added beneath the existing one.

    2. Repeat steps 4 and 5 above to define a new factor.
    3. To add further conditions to the OR relationship, click [image] (Add Condition) to the right of OR and define the condition.
  8. Click Save to Catalog.

    The filter is immediately applied to the file definition.

Parent topic: Defining Record Type Filters


Defining Default Values

The Default Value property, displayed in the Properties pane when a data item is selected, is used in write operations if the item is not represented by a column in an SQL INSERT statement.

This value is editable if you select the Edit default values option on the File tab of the Options pane.

Depending on the COBOL type, you can select from a list of figurative constants, or you can enter your own default appropriate to the data type. The value will be limited to the range of values that is valid for the underlying COBOL data type.

  • Defining a Default Value
Parent topic: Augmenting the COBOL File Definition in the FD Form


Defining a Default Value

To be able to edit the default value, you must first select the Edit default values option on the File tab of the Options pane.
  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. Select the data item in the FD form to display its properties in the Properties pane.
  3. Expand the Default Value property group.

    Note: The IsEnabled property indicates if the default value is currently editable.
  4. Click the current value for Default Value Type, and then select from the list of available options.

    The options available are dependent on the type of data item selected.

  5. If you selected Entered as the Default Value Type, enter the default text in the Default Value property, then press Enter.
  6. Click Save to Catalog to save the changes; alternatively, click Revert to revert back to the last saved property value.
The value you entered is used for any SQL write operations if the data item is not represented by a column in an SQL INSERT statement.
Parent topic: Defining Default Values


Defining Custom Data Types

Relativity provides the facility to define custom data types for SQL column descriptions. Relativity custom data types are similar to domains in some relational database management systems. A custom data type allows you a quick way to apply a common set of characteristics to one or more columns - those characteristics include the data type, length, default value, whether the column allows null values, whether the column is constrained to certain values, and, for numeric type columns, the precision and scale.

Using custom data types can add consistency to your tables. They also make it easy to adjust column properties, as you only have to make the required changes in one place, instead of having to edit each individual column that shares a particular type. Custom data types, once defined, can be associated with a COBOL data item as the default type to use when a column is based on that data item.

  • Creating a Custom Data Type
  • Editing a Custom Data Type
  • Deleting a Custom Data Type
Parent topic: Augmenting the COBOL File Definition in the FD Form
Related reference
Defining Conditions
User Data Type attribute
Default Column Name attribute
Transform attribute
Transforms


Creating a Custom Data Type

  1. On the Tools menu, click Custom Data Types.

    The Custom Data Types tab is displayed.

  2. To define a new data type, click New.

    The Custom Data Type dialog box is displayed.

  3. In the Data Type Name field, type a descriptive name for this user data type.
  4. In the SQL Data Type field, click Char and select the required data type.
  5. Depending on the data type selected, complete the following options when enabled:
    • Length - the maximum number of characters for the length of the column value.
    • Digits - the number of decimal digits in the column value.
    • Decimal Places - the number of decimal digits to the right of the decimal point in the column value.
  6. If required, in the Default Value field, specify the default column value.

    The default value is used for columns of this type when, for example, a column value is not specified in an SQL INSERT statement.

  7. In the Transform field, click <None> and select the required transform.

    The value <None> indicates that no column transform is desired, but an item transform may be associated with the data item upon which columns of this user data type are based.

  8. Select the Nullable tick-box if the user data type allows the column to be set to null.
  9. Select the Constrained tick-box if the user data type constrains the column value to one of the true values of an 88-level condition-name associated with the data item upon which the column is based.
  10. Click Accept to add the new user data type.
  11. Click Save to Catalog.
Note: To edit an existing data type, double-click the data type, edit the details as necessary, then click Accept. To delete an existing data type, right-click the entry on the Custom Data Types tab and click Delete. (Note that you can only delete a user type that is unused.)
Parent topic: Defining Custom Data Types
Related reference
Editing a Custom Data Type
Deleting a Custom Data Type
Rules for Insertable Tables


Editing a Custom Data Type

  1. On the Tools menu, click Custom Data Types.

    The Custom Data Types tab is displayed.

  2. Right-click the type name for the existing data type to delete, then click Edit.

    The Custom Data Type dialog box is displayed.

  3. Edit the appropriate fields, and then click Accept.

    The user type is updated. If the data type is currently in use, a message is displayed informing you which file definitions are affected.

  4. Click Save to Catalog.

    The changes are saved to the catalog.

Parent topic: Defining Custom Data Types
Related reference
Creating a Custom Data Type
Deleting a Custom Data Type


Deleting a Custom Data Type

Restriction: You can only delete a custom user type if it is not being used in any of the file definitions in the catalog.
  1. On the Tools menu, click Custom Data Types.

    The Custom Data Types tab is displayed.

  2. Right-click the type name for the existing data type to delete, then click Delete.
  3. Click Yes to confirm.

    The user type is deleted.

  4. Click Save to Catalog.

    The changes are saved to the catalog.

Parent topic: Defining Custom Data Types
Related reference
Creating a Custom Data Type
Editing a Custom Data Type


Specifying Treatment of the OCCURS Clause

In COBOL, an OCCURS clause specifies a repeating data item or group of data items. The relational model does not include the concept of repeating items except as rows of a relational table, thus providing a simpler (or "normalized") data model. Relativity provides several techniques for handling the mapping of repeating data items in COBOL to normalized relational tables.

The following techniques may be used in any combination to properly specify the treatment of the OCCURS clause by Relativity:

  • Coinciding OCCURS: - two or more separate OCCURS clauses, each specifying the same number of occurrences can sometimes be thought of as being a single COBOL table accessed by a single subscript item. Marking these OCCURS as coinciding produces an effect similar to this in the relational table. See Identifying Parallel OCCURS Clauses for more information.
  • Multiple Rows vs. Flattening: - the default behavior of Relativity is to map repeating items to multiple rows. There are instances, however, in which each occurrence defined by an OCCURS clause has unique significance, and as such the default behavior is not desired. These cases should be identified and, at table definition time, separate columns can be added for one, some, or all occurrences by binding the subscript item associated with the OCCURS clause to one or more specific occurrences. This technique is sometimes called flattening the OCCURS. For more details, see Flattening OCCURS.
  • Unused Occurrences Elimination: - unused occurrences resulting from an OCCURS clause should not become rows in a relational table. Correctly eliminating unused occurrences can provide a significant boost in the performance of Relativity. For more information, see Eliminating Unused Occurrences.
  • Identifying Coinciding OCCURS Clauses
  • Flattening OCCURS
  • Eliminating Unused Occurrences
  • Identifying Implicit OCCURS DEPENDING ON Clauses
Parent topic: Augmenting the COBOL File Definition in the FD Form
Related reference
Defining Relational Tables in the Table Form
Defining Columns on Repeating Data Items
Defining Insertable Tables
Determining Occurrence Count
OCCURS Rule


Identifying Coinciding OCCURS Clauses

In Relativity, identifying coinciding OCCURS clauses means identifying two or more separate OCCURS clauses in a record description entry that each specify the same number of occurrences and where the COBOL tables created by the OCCURS clauses can be thought of as really being a single COBOL table accessed by a single subscript item.

Records within COBOL data files often contain two or more data items having the clause OCCURS x TIMES, with x typically being the same number for both data items. A good example of this would be values broken down by month, with OCCURS 12 TIMES being attributed to each value recorded per month.

A relational database must contain only single-valued columns; therefore, Relativity's default behavior for a COBOL OCCURS clause is to derive one row in a relational table for each occurrence of the COBOL data item. For example, the data item QUANTITY-SOLD-PER-MONTH occurs 12 times in the FD would result in 12 rows in a relational table for each COBOL record.

This effect may not be desirable in the generated table, especially when you consider when two (or more) such data items are included in a relational table: each COBOL record produces the number of rows that is determined by multiplying the integers in the OCCURS clauses; if three data items within a COBOL data file are each associated with an OCCURS 12 TIMES clause, then the three data items produce 12 x 12 x 12 or 1,728 rows in a relational table.

The identification of data items having coinciding OCCURS characteristics enables Relativity to generate 12 rows containing columns for the three selected data items.

  • Marking Items as Coinciding OCCURS
  • Removing Coinciding OCCURS Items
Parent topic: Specifying Treatment of the OCCURS Clause
Related tasks
Marking Items as Coinciding OCCURS
Related reference
Defining Conditions
User Data Type attribute
Default Column Name attribute
Transform attribute


Marking Items as Coinciding OCCURS

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. Select the first data item entry that contains a coinciding OCCURS, right-click and select Identify coinciding OCCURS.

    The Identify Coinciding OCCURS dialog box is displayed, with the current item (already selected) and the other data items containing OCCURS clauses. The current item is marked as the master table, in that other coinciding items are indexed through this one.

  3. In the Coincides column, select the other items that coincide, and then click Apply.
    Note: You cannot select other subscripted items that contain subscript conditions.

    The Coincides with column is updated in the file definition, to indicate the coinciding data items. Also, the subscript item for each coinciding item (other than the master one) is removed, as it is no longer required.

  4. Click Save to Catalog.
Parent topic: Identifying Coinciding OCCURS Clauses
Related reference
Identifying Coinciding OCCURS Clauses


Removing Coinciding OCCURS Items

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. Select the data item entry marked as the 'master table' for the coinciding OCCURS clauses, right-click and select Identify coinciding OCCURS.

    The Identify Coinciding OCCURS dialog box is displayed, showing the data items marked as coinciding.

  3. In the Coincides column, clear the items that no longer coincide, and then click Apply.

    The Coincides with column is updated in the file definition, to indicate the data items no longer coincide.

  4. Click Save to Catalog.
Parent topic: Identifying Coinciding OCCURS Clauses


Flattening OCCURS

Relativity's normal treatment of a COBOL OCCURS clause is to derive one row in a relational table for each occurrence of the repeating data item. However, there may be situations in which it is desirable to treat repeating data items as one or more columns, rather than as multiple rows. An example situation would be one in which the months of a year need to display as twelve columns in a single row rather than as a separate row for each month. This is called "flattening" the OCCURS.

To achieve this behavior in the table, it is necessary to prepare for handling repeating data items during the augmentation phase. The necessary preparation is to create subscript conditions.

The process is similar to that of creating a standard condition item, but you create an 88-level condition for each occurrence in the OCCURS limit, giving each condition a unique (subscripted) value - in the 'months' example given above, that would be 12 separate 88-level conditions, with values 1-12.

Tip: A special procedure exists to aid the creation of multiple conditions: use the Serialize option to automatically create multiple conditions based on the OCCURS limit.

Once you have created the necessary subscript conditions, when you add the subscripted data item to a table definition, you are prompted to bind the columns and the conditions - see Binding a Column to a Subscript.

  • Adding Subscript Conditions to Flatten the OCCURS
Parent topic: Specifying Treatment of the OCCURS Clause
Related tasks
Binding a Column to a Subscript


Adding Subscript Conditions to Flatten the OCCURS

To flatten the OCCURS, you need to create a level-88 condition for each subscript of the particular data item. These subscript conditions are used to bind table columns to the actual subscripted data.

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. Right-click the subscript in the FD form, then select Add 88.

    The Add condition under subscript of <data-item> dialog box is displayed.

  3. In the Condition (88) Name base field, type a condition name. This base name will be appended with -n, where n is the subscript number.
  4. Select Serialize.

    Serialize automatically creates the required number of subscript conditions (based on the value of the OCCURS clause). If you do not select this option, you must create each (single integer) condition separately, using the [image] (Add New Value) option for each new entry.

  5. Click Apply.

    The subscript conditions are added to the FD, underneath the SUBSCRIPT of <data-item> entry.

  6. Click Save to Catalog.

When you add the subscripted data item to a table definition, you can now use these subscript conditions to bind the subscripted data to a column - see Binding a Column to a Subscript. Also, if you have coinciding OCCURS (see Identifying Coinciding OCCURS), they can use these subscript conditions too.

Parent topic: Flattening OCCURS
Related tasks
Binding a Column to a Subscript


Eliminating Unused Occurrences

Unused occurrences associated with an OCCURS clause should not become rows in a relational table. If, for example, you have a COBOL data file with 10,000 records, each of which contains an OCCURS 20 TIMES clause and you do not eliminate the unused occurrences, the result of the normalization would be a table containing 200,000 rows. If all occurrences in every record are active, then this is the necessary size of the table. However, it is often the case that the OCCURS clause specifies an upper bound on the number of active occurrences, not the actual number of active occurrences. The performance of Relativity in such cases can be significantly improved by eliminating the unused occurrences.

There are three alternatives for dealing with unused occurrences of a repeating data item:

  1. Use a variable number of occurrences within the COBOL program by specifying the OCCURS clause with the DEPENDING ON phrase. Relativity will then only use the active occurrences indicated by the value of the data item specified by the DEPENDING ON phrase.
  2. Use an existing data item in the record that specifies the number of active occurrences; that is, an implicit Occurs Depending On variable, to limit the number of occurrences considered by Relativity. See Identifying Implicit OCCURS DEPENDING ON for more information.
  3. Use table filters to discard occurrences with null values (for example, spaces or zeroes might indicate null values). See Defining Table Filters for more information.
Parent topic: Specifying Treatment of the OCCURS Clause
Related reference
Identifying Implicit OCCURS DEPENDING ON Clauses
Defining Table Filters


Identifying Implicit OCCURS DEPENDING ON Clauses

Some application files describe data arrays with an OCCURS clause without the DEPENDING ON phrase. However, the files have uninitialized or otherwise invalid data in some of the occurrences. For example:

03 NUMBER-OF-STYLES PIC 99.
03 STYLE-STORAGE OCCURS 25.
 05 FIELD-A ...
 05 FIELD-B ...
 05 FIELD-C ...

Because of the limitations on the use of the DEPENDING ON phrase, the COBOL Procedure Division statements test the data item NUMBER-OF-STYLES to limit the occurrences used. For such situations in the Relativity Designer, you must link the data array with a controlling item that exists within the file definition: the controlling item is a numeric item that specifies the number of occurrences.

  • Identifying the OCCURS DEPENDING ON Control Item
  • Changing or Removing the OCCURS DEPENDING ON Control Item
Parent topic: Specifying Treatment of the OCCURS Clause
Related reference
Defining Conditions
User Data Type attribute
Default Column Name attribute
Transform attribute
Eliminating Unused Occurrences


Identifying the OCCURS DEPENDING ON Control Item

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. Select the group-level data item that does not contain the DEPENDING ON phrase, right-click and select Identify OCCURS DEPENDING ON control item.

    The Select Control Item dialog box is displayed.

  3. In the Control Item field, click [image] and select the control item from the numeric items displayed.
    Note: If the control item is not a part of your file definition (perhaps it is a working-storage item), you will need to re-import the file definition using Advanced Import Options, which allows you to import additional data items not part of an FD.
  4. Click Apply.

    The Occurs property for the group-level item, within the Properties pane, now indicates that it depends on the value of the control item.

  5. Click Save to Catalog.
Parent topic: Identifying Implicit OCCURS DEPENDING ON Clauses
Related reference
Changing or Removing the OCCURS DEPENDING ON Control Item


Changing or Removing the OCCURS DEPENDING ON Control Item

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. Select the group-level data item containing the OCCURS DEPENDING ON clause, right-click and select Identify OCCURS DEPENDING ON control item.

    The Select Control Item dialog box is displayed.

  3. In the Control Item field, click [image] and select a new control item from the numeric items displayed, or select <None> to remove the current control item.
  4. Click Apply.

    The Occurs property for the group-level item is updated to reflect the change.

  5. Click Save to Catalog.
Parent topic: Identifying Implicit OCCURS DEPENDING ON Clauses
Related reference
Identifying the OCCURS DEPENDING ON Control Item


Using Functions and Transforms

The Relativity Designer provides both internal functions and transforms to act on COBOL data items. In determining when to use an internal function and when to use a transform, consider the following points:
  • Internal functions are used to synthesize a COBOL data item using the value or values of one or more other COBOL data items within the same FD. These synthesized COBOL data items may be used as any other COBOL data item. Transforms are used to "transform", or convert, existing COBOL data items.
  • An internal function can operate on more than one COBOL data item. A transform can operate only on a single COBOL data item.
  • An internal function must be applied to the COBOL data item in the FD. A transform can be applied to the COBOL data item in the FD or at the column level. If the transform is applied at the FD level, all the columns that use that COBOL data item will use the transformed item. If the transform is applied at the column level, only those columns with the transforms will be affected. In the case of a data item that will always be transformed, such as a date data item, it is better to apply the transform at the FD level. If the data item sometimes needs to be transformed, and other times not, it is better to apply the transform at the column level.
  • An internal function may have another function as an argument.

For detailed information on using internal functions and transforms, see the following topics:

  • Transforms
  • Internal Functions
Parent topic: Augmenting the COBOL File Definition in the FD Form


Transforms

Transforms specify a data transformation for a COBOL data item value to or from a relational database column value.

It is common for COBOL products to have a limited set of formats used for storing dates. When specifying date formats options, it is prudent to use only those date formats used by your COBOL programs in order to avoid invalid transforms.

The list of date transforms that are available to choose from is controlled by the settings on the Date Format tab. Availability is also controlled by the size of the underlying COBOL data item. For example, on an item with a PIC 9(6) you will not see 8-digit transforms such as YYYYMMDD.

To apply a transform to a data item, click the required cell in the Transform column and select one of the transforms listed; the data is transformed when the table is generated or when data is written back into the data file.

  • Hexadecimal Transforms
  • Standard Date and Time Transforms
  • User-Configurable Date Transforms
  • Math Transforms
  • Special Date and Date Time Transforms
  • LogicalOrder Column Transforms
Parent topic: Using Functions and Transforms
Related reference
Defining Conditions
User Data Type attribute
Default Column Name attribute
Transform attribute
Defining Date Constants
Defining Custom Data Types
Previewing Table Data
Defining Transforms on Columns
Analyzing Table Definition Errors


Hexadecimal Transforms

The Hexadecimal transform passes the hexadecimal value of the COBOL data. The column should be defined as char and be twice the size of the COBOL record field; that is, a field containing a PIC S9(5) COMP-3 data item, which is a three-byte field, will return six bytes of hexadecimal information.

The Hexadecimal transform is useful for tracking down problem data. For example, if you have a column that returns the SQL error "Invalid Numerics", you can use the Hexadecimal transform and see what data is in the field.

Parent topic: Transforms


Standard Date and Time Transforms

The following list includes all of the standard date and time formats supported by Relativity. All of these transforms will return an SQL Date, SQL Time, or SQL Date/Time value. The following transforms may be modified using transform modifiers.

Note: For information on the date and time transform modifiers, see Modifiers for Date and Time Transforms.
HHMM | YYYYDDDHHMM | MMDDYYYYHHMM
HHMMSS | YYYYDDDHHMMSS | MMDDYYYYHHMMSS
HHMMSShh | YYYYDDDHHMMSShh | MMDDYYYYHHMMSShh
YYDDD | YYYYMMDD | DDMMYY
YYDDDHHMM | YYYYMMDDHHMM | DDMMYYHHMM
YYDDDHHMMSS | YYYYMMDDHHMMSS | DDMMYYHHMMSS
YYDDDHHMMSShh | YYYYMMDDHHMMSShh | DDMMYYHHMMSShh
YYMMDD | MMDDYY | DDMMYYYY
YYMMDDHHMM | MMDDYYHHMM | DDMMYYYYHHMM
YYMMDDHHMMSS | MMDDYYHHMMSS | DDMMYYYYHHMMSS
YYMMDDHHMMSShh | MMDDYYHHMMSShh | YYYYDDD
MMDDYYYY | DDMMYYYYHHMMSShh |
  • Modifiers for Date and Time Transforms
Parent topic: Transforms


Modifiers for Date and Time Transforms

There are four modifiers for the standard date and time transforms. These must also be enabled in the same way as you enable the date and time transforms, by using the Date Format tab:

9s Complement
Subtracts the value of the COBOL data item from all 9's, before computing the date or time value using the modified transform. The transforms incorporating this modifier are not listed unless the 9s Complement option is selected on the Date Format tab in the Options pane.
10s Complement
Computes the 9s Complement and adds 1 to that value before computing the date or time value using the modified transform.
Note: The 10s Complement of a zero value is defined to be zero.

The transforms incorporating this modifier are not listed unless the 10s Complement option is selected on the Date Format tab in the Options pane.

3M Complement
Complements the value of the COBOL data item with respect to 3,000,000 based on a date format of CYYMMDD.

The transforms incorporating this modifier are not listed unless the 3M Complement option is selected on the Date Format tab in the Options pane.

+ Subscript
Adds the value of the associated subscript less one for a date data item that is associated with an OCCURS table (but not subordinate to the OCCURS clause). This transform modifier is useful when the COBOL data record contains a starting date item and an OCCURS table, where each entry in the OCCURS table is information about a date based on the starting date and the number of days equivalent to its occurrence number less one. By using this transform modifier with the appropriate date format transform on the date item and including both the date item and one or more items that are subordinate to the OCCURS clause in a table, the multiple rows generated for the OCCURS clause will each contain the correct date.

The transforms incorporating this modifier are not listed unless the + Subscript option is selected on the Date Format tab in the Options pane.

Parent topic: Standard Date and Time Transforms
Related reference
Date Format Options


User-Configurable Date Transforms

The following date transforms handle the situation where the date is stored in the COBOL data item as either 6 digits or 8 digits, but the end-user configures the actual format of dates stored in the data item. Such situations occur, for example, when the COBOL program allows the end-user to configure the date format for local conventions such as:

6-digit forms | 8-digit forms | Locale Example
YYMMDD | YYYYMMDD | Japan
MMDDYY | MMDDYYYY | U.S.A.
DDMMYY | DDMMYYYY | Germany

Within the design phase of the catalog, you choose the appropriate 6- or 8-digit transform. Then the end-user of the catalog, by using the Date Constants dialog box in the Relativity DBA program, can select the format that configures Relativity to match the format configured for the COBOL program that built the local files.

The YY Dates section in the Date Constants dialog box is used to configure 6-digit forms.

The YYYY Dates section in the Date Constants dialog box is used to configure 8-digit forms.

Parent topic: Transforms


Math Transforms

The Math transforms include the following:

  • 9s Complement. Subtracts the value of the COBOL data from all 9's.
  • 10s Complement. Subtracts the value of the COBOL data from all 9's and adds 1 to that value.
  • Value - 1. Subtracts one from the value of the COBOL data.
  • Value + 1. Adds one to the value of the COBOL data.
  • Div 100 (Read only). Divides the value of the COBOL data by 100.
  • Mod 100 (Read only). Returns the remainder of the COBOL data divided by 100.
Parent topic: Transforms


Special Date and Date Time Transforms

Several special date and date/time transforms are available.

The following transforms convert a date or date/time where the date is specified as the number of days since the base date specified in the Base Date for Days Count value on the Date Constants pane:
  • Days
  • DaysHHMM
  • DaysHHMMSS
  • DaysHHMMSShh
The following transforms return the first day of the month for a given year and month:
  • YYYYMM01
  • YYMM01
  • MMYY01
  • MMYYYY01
The following transforms return the last day of the month for a given year and month:
  • YYMM31
  • YYYYMM31
  • MMYY31
  • MMYYYY31
The following transforms return the first day of the year for a given year:
  • YY001
  • YYYY001
The following transforms return the last day of the year for a given year:
  • YY365
  • YYYY365
Parent topic: Transforms
Related reference
Date Format Options


LogicalOrder Column Transforms

Bi-directional text in languages such as Hebrew and Arabic may be represented within the computer in one of two ways: logical order or visual order.

ODBC applications expect that Relativity will supply the text in logical order, so they can automatically convert it to visual order when it comes time to display the text. Relativity also treats text from application files as being in logical order, and performs no transformations on it when returning it to the application program. It is possible, however, that the COBOL application received the text in visual order from the terminal, performed no translations on it, and stored the text in the application's file still in visual order. When the ODBC application attempts to convert the text that is already in visual order to visual order again, the resulting text is not displayed properly. Although an ODBC translation DLL can be employed to translate the visual order to logical order, any sorting of the data via an index or an ORDER BY operation will have already been performed before the translation DLL is called; thus, the order of the data will not be correct.

Relativity offers the LogicalOrder column transform as an alternative to the ODBC translation DLL. The LogicalOrder column transform is used to convert visual order text to logical order text before returning it to the ODBC application. Likewise, logical order text that is written into a column by the ODBC application will be converted back to visual order before storage into the COBOL data file, so the COBOL application can use it.

Notes

  • Data that is stored in visual order does not sort properly, and Relativity will not build an index on a column with a LogicalOrder transform, even though the underlying data file has a key on the data item. However, as the data that the column returns is now in logical order, performing an ORDER BY operation on the column will cause the information to sort properly.
  • If the LogicalOrder column transform is in use, a translation DLL should not be used.
  • Enabling the LogicalOrder Column Transform
  • Apply the LogicalOrder Column Transform on an Entire Data Source
  • Apply the LogicalOrder Column Transform on an Individual Column
Parent topic: Transforms


Enabling the LogicalOrder Column Transform

  1. From the Tools menu, select Options.
  2. In the Options dialog box, select Table.
  3. On the Table page, check the Show LogicalOrder Transform check box.
  4. Click OK to save the options and close the dialog box.
Parent topic: LogicalOrder Column Transforms
Related reference
Apply the LogicalOrder Column Transform on an Entire Data Source
Apply the LogicalOrder Column Transform on an Individual Column
Table Options


Apply the LogicalOrder Column Transform on an Entire Data Source

After enabling the LogicalOrder column transform, follow these steps to automatically apply the transform on every text column in every table of a data source:

  1. In the Catalog window, double-click the File Definitions node.

    The catalog's file definitions are displayed.

  2. Double-click the required file definition.

    The file definition is displayed.

  3. In the Properties pane, examine the Native Charset option - this option must be set to Hebrew 7-bit Old Code, or code pages 862, 864, or 708. If it does not, do one of the following before continuing:
    • Change the Advanced Properties Native Character Set to the desired character set.
    • To change the character set for a single file, use the Update FDs from Source command from the Tools menu and import the FD again. Click Show Advanced Import Options in the Items to Import tab and select the proper character set from the Character Set list.
    • To change the character set of multiple files, click Character Sets on the Tools menu, and make the needed changes.
  4. On the Tools menu, click Options.
  5. In the Options pane, click the Catalog tab.
  6. Click the current option selected for Automated Logical Transform and select Always to apply the transform to all text columns, or select Yes, Except For Record Key Data Items to apply the transform to all text columns, except where it would result in the loss of an index on the table.
Parent topic: LogicalOrder Column Transforms
Related reference
Enabling the LogicalOrder Column Transform
Apply the LogicalOrder Column Transform on an Individual Column


Apply the LogicalOrder Column Transform on an Individual Column

After enabling the LogicalOrder column transform, follow these steps to apply the transform on individual columns of a table:

  1. In the Catalog window, double-click the Tables node.

    The catalog's table definitions are displayed.

  2. Double-click the required table definition.

    The table definition is displayed, showing the current table columns.

  3. Select the required column.

    The column properties are displayed in the right-hand Properties pane.

  4. In the Properties pane, click [image] next to Column Transform and select LogicalOrder.

  5. Click Save to Catalog.
Parent topic: LogicalOrder Column Transforms
Related reference
Enabling the LogicalOrder Column Transform
Apply the LogicalOrder Column Transform on an Entire Data Source


Internal Functions

Internal functions are part of the Relativity DBMS. An internal function is used to synthesize a COBOL data item using the value or values of one or more other COBOL data items within the same COBOL file definition (FD). A synthesized COBOL data item, known as a function item, may be used as any other COBOL data item. Unlike a transform, an internal function may operate on more than one COBOL data item.

The following internal functions can be added to an FD form.

  • AirlineDate
    AirlineDate is a specialized internal function that computes a date from an "airline travel date", a transaction date, and a transaction type.
  • CombineDateTime
    The CombineDateTime internal function allows two data items to be combined into a single date/time stamp value.
  • Complement
    The Complement internal function performs a conditional arithmetic complement on a data item.
  • ComputeCenturyDate
    The ComputeCenturyDate internal function computes a date from data items and/or constants containing the century, the year of the century, the month, and the day of the month or year.
  • ComputeCenturyDateTime
    The ComputeCenturyDateTime internal function computes a date and time data item from data items and/or constants containing the century, the year, the month, the day of the month or year and optional data items or constants containing the hour or the day, the minute of the hour, the second of the minute, and the hundredth of the second.
  • ComputeDate
    The ComputeDate internal function computes a date from data items and/or constants containing the year, the month, and the day of the month.
  • ComputeDateTime
    The ComputeDateTime internal function computes a date and time data item from data items and/or constants containing the year, the month, the day of the month or year and optional data items or constants containing the hour or the day, the minute of the hour, the second of the minute, and the hundredth of the second.
  • ComputeODO
    The ComputeODO internal function computes an occurrence count from the record length, the record offset of the (single) argument, and the length and span of the argument. The argument must be a repeating data item at the end of the record.
  • ComputeTime
    The ComputeTime internal function computes a time data item from data items and/or constants containing the hour of the day, the second of the minute, and the hundredth of the second.
  • IsNumeric
    The IsNumeric internal function evaluates the data item supplied as an argument to determine whether its value is a valid numeric value.
  • IsValidDate
    The IsValidDate internal function evaluates the data item supplied as an argument to determine whether its value conforms to that item's date transform.
  • LogicalAnd
    The LogicalAnd internal function does a logical "and" operation on two to twenty 88-level condition-names or logical internal functions (IsNumeric, LogicalAnd, LogicalOr).
  • LogicalOr
    The LogicalOr internal function does a logical "or" operation on two to twenty 88-level condition-names or logical internal functions (IsNumeric, LogicalAnd, LogicalOr).
  • Synthesize a Data Item Using an Internal Function
Parent topic: Using Functions and Transforms


AirlineDate

AirlineDate is a specialized internal function that computes a date from an "airline travel date", transaction date, and a transaction type (PIC X). The resulting date is formed by using the day and month of the travel date. If the travel month is less than the transaction month and the transaction type = "1", then add 1 to the transaction year to produce the resulting year.

The YYYYMMDD transform may be applied to resulting data item.

Note: This internal function is available only if the Airline Date Function option is enabled in the Relativity Designer file.
 AirLineDate(Travel-Date, Transaction-Date, Transaction-Type)
Argument | Description
Travel-Date | PIC X(5) in the form DDMMM.
Transaction-Date | Must have a date transform.
Transaction-Type | PIC X. If equal "1" and the travel month is less than transaction month, add 1 to transaction year to produce resulting year.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


CombineDateTime

The CombineDateTime internal function allows two data items to be combined into a single date/time stamp value.

The YYYYMMDDHHMMS transform may be applied to resulting data item.

CombineDateTime(Date-Data-Item,Time-Data-Item)
Argument | Description
Date-Data-Item | A valid date data item.
Time-Data-Item | A valid time data item.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


Complement

The Complement internal function performs a conditional arithmetic complement on a data item.

 Complement(Numeric-Data-Item,Condition-Name)
Argument | Description
Numeric-Data-Item | Numeric data item to be conditionally complemented.
Condition-Name | 88-level condition-name to determine if complement happens. If Condition-Name is true, the function returns the complement of the value of Numeric-Data-Item. If the Condition-Name is false, the function returns the value of Numeric-Data-Item.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


ComputeCenturyDate

The ComputeCenturyDate internal function computes a date from data items and/or constants containing the century, the year of the century, the month, and the day of the month or year. When a constant zero is supplied for the month, ComputeCenturyDate computes a date from data items and/or constants containing the year and the days of the year.

The YYYYMMDD transform may be applied to resulting data item.

 ComputeCenturyDate(Century,Year,Month,Day)
Argument | Description
Century | A data item or constant containing the century, divided by 100. The value contained in this argument is multiplied by 100 and added to the value contained in the Year argument to compute the actual year of the date.
Year | A data item or constant containing the year of the century. Note It is assumed that this value will be in the range of 0 through 99, but it is not enforced.
Month | A data item or constant containing the month. Note: If the month argument is a constant zero (0), the Day argument will be treated as the day of the year. Otherwise, the Day argument will be treated as the day of the month.
Day | A data item or constant containing the day of the month or year.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


ComputeCenturyDateTime

The ComputeCenturyDateTime internal function computes a date and time data item from data items and/or constants containing the century, the year, the month, the day of the month or year and optional data items or constants containing the hour of the day, the minute of the hour, the second of the minute, and the hundredth of the second.

The YYYYMMDDHHMMSShh transform may be applied to the resulting data item.

ComputeCenturyDateTime(Century,Year,Month,Day [,Hour[,Minute [,Second [,Hundredth]]]]
Argument | Description
Century | A data item or constant containing the century, divided by 100. The value contained in this argument is multiplied by 100 and added to the value contained in the second argument to compute the actual year of the date.
Year | A data item or constant containing the year of the century. Note: It is assumed that this value will be in the range of 0 through 99, but it is not enforced.
Month | A data item or constant containing the month. Note: If the month argument is a constant zero (0), the Day argument will be treated as the day of the year. Otherwise, the Day argument will be treated as the day of the month.
Day | A data item or constant containing the day of the month or year.
Hour | An optional data item or constant containing the hour of the day. Default is 00:00:00.00.
Minute | An optional data item or constant containing the minute of the hour. Default is Hour:00:00.00.
Second | An optional data item of constant containing the second of the minute. Default is Hour:Minute:00.00.
Hundredth | An optional data item or constant containing the hundredth of the second. Default is Hour:Minute:Second.00.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


ComputeDate

The ComputeDate internal function computes a date from data items and/or constants containing the year, the month, and the day of the month. When a constant zero is supplied for the month, ComputeDate computes a date from data items and/or constants containing the year and the days of the year.

The YYYYMMDD transform may be applied to resulting data item.

 ComputeDate(Year,Month,Day)
Argument | Description
Year | A data item or constant containing the year. The precision of the data item (rather than its value) will be used to determine whether the year contains two or more than two digits. This in turn will determine whether to use the YY or YYYY date constants when evaluating the value of the data item. See the Date Constants dialog box and Defining Date Constants topics.
Month | A data item or constant containing the month. Note: If this argument is a constant zero (0), then the Day argument will be treated as the day of the year. Otherwise, the Day argument will be treated as the day of the month.
Day | A data item or constant containing the day of the month or year. (See the previous argument).
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


ComputeDateTime

The ComputeDateTime internal function computes a date and time data item from data items and/or constants containing the year, the month, the day of the month or year and optional data items or constants containing the hour or the day, the minute of the hour, the second of the minute, and the hundredth of the second.

The YYYYMMDDHHMMSShh transform may be applied to the resulting data item.

ComputeDateTime(Year,Month,Day[,Hour[,Minute[,Second[,Hundredths]]]])
Argument | Description
Year | A data item or constant containing the year. The precision of the data item (rather than its value) will be used to determine whether the year contains two or more than two digits. This in turn will determine whether to use the YY or YYYY date constants when evaluating the value of the data item. See the Date Constants dialog box and Defining Date Constants topics.
Month | A data item or constant containing the month. Note: If this argument is a constant zero (0), then the Day argument will be treated as the day of the year. Otherwise, the Day argument will be treated as the day of the month.
Day | A data item or constant containing the day of the month or year (see the previous argument).
Hour | An optional data item or constant containing the hour of the day. Default is 00:00:00.00.
Minute | An optional data item or constant containing the minute of the hour. Default is Hour:00:00.00.
Second | An optional data item or constant containing the second of the minute. Default is Hour:Minute:00.00.
Hundredth | An optional data item or constant containing the hundredth of the second. Default is Hour:Minute:Second.00.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


ComputeODO

The ComputeODO internal function computes an occurrence count from the record length, the record offset of the (single) argument, and the length and span of the argument. The argument must be a repeating data item at the end of the record.

The function accepts one argument. The argument is a repeating data item. This function exists for the situation in which the repeating item is declared to have a fixed number of occurrences, but it really has a variable number of occurrences. The function computes the occurrence count from the record length. The only place it should be used is in conjunction with the ODO button in the Relativity Designer.

For example:

FD  VARIABLE-FILE  RECORD IS VARYING IN SIZE FROM 22 TO 40
                   CHARACTERS DEPENDING ON VARIABLE-LENGTH.
01  VARIABLE-RECORD.
    03  SOME-MISC-STUFF           PIC X(20).
    03  A-REPEATING-ITEM          OCCURS 10 TIMES.
        05  ANOTHER-ONE           PIC X.
        05  AND-ONE-MORE          PIC 9.

In this example, the record contains one to ten occurrences of A-REPEATING-ITEM, but the item is declared as a fixed number of occurrences. The ComputeODO function would take A-REPEATING-ITEM as its argument and compute the occurrences from the record length. For example, if a particular record were 28 bytes long, the value of the function would be four (4).

ComputeODO(Data-Item)
Argument | Description
Data-Item | A repeating data item at the end of the record.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


ComputeTime

The ComputeTime internal function computes a time data item from data items and/or constants containing the hour of the day, the second of the minute, and the hundredth of the second.

The HHMMSShh transform may be applied to the resulting data item.

ComputeTime(Hour, Minute[, Second[, Hundredth]])
Argument | Description
Hour | A data item or constant containing the hour of the day.
Minute | A data item or constant containing the minute of the hour.
Second | An optional data item or constant containing the second of the minute. Default is Hour:Minute:00.00.
Hundredth | An optional data item or constant containing the hundredth of the second. Default is Hour:Minute:Second.00.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


IsNumeric

The IsNumeric logical internal function evaluates the data item supplied as an argument to determine whether its value is a valid numeric value. If the data item is numeric, the function returns the value 1, which is the logical value of true. If the data item is not numeric, the function returns the value 0, which is the logical value of false.

IsNumeric(Data-Item)
Argument | Description
Data-Item | Any data item.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


IsValidDate

The IsValidDate logical internal function evaluates the data item supplied as an argument to determine whether its value conforms to that item's date transform. If the date item value represents a valid date, the function returns the numeric value 1, which is the logical value of true. If the data item value does not represent a valid date, the function returns the numeric value 0, which is the logical value of false.

 IsValidDate(Date-Data-Item)
Argument | Description
Date-Data-Item | A valid date data item. Note: Must have a date transform set.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


LogicalAnd

The LogicalAnd logical internal function does a logical "and" operation on two to twenty 88-level condition-names or logical internal functions (IsNumeric, LogicalAnd, LogicalOr). If all of the arguments are true, the function returns the numeric value 1, which is the logical value of true. If any of the arguments are false, the function returns the numeric value 0, which is the logical value of false.

LogicalAnd(Condition-Name-Or-Logical-Internal-Function,…)
Argument | Description
Condition-Name-Or-Logical-Internal-Function | Two to twenty 88-level condition-names or logical internal functions.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


LogicalOr

The LogicalOr logical internal function does a logical "or" operation on two to twenty 88-level condition-names or logical internal functions (IsNumeric, LogicalAnd, LogicalOr). If any of the arguments are true, the function returns the numeric value 1, which is the logical value of true. If all of the arguments are false, the function returns the numeric value 0, which is the logical value of false.

LogicalOr(Condition-Name-Or-Logical-Internal-Function,…)
Argument | Description
Condition-Name-Or-Logical-Internal-Function | Two to twenty 88-level condition-names or logical internal functions.
Parent topic: Internal Functions
Related tasks
Synthesize a Data Item Using an Internal Function


Synthesize a Data Item Using an Internal Function

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the file definition on which to define the internal function.

    The <file-definition-name> tab is displayed.

  2. Select the data item that forms the first argument for the internal function, then right-click and select Add Function.

    The Add Function dialog box will be displayed:

  3. In the Function field, select the required function.
  4. In the grid, complete the details for each parameter, then click Apply:
    • In the Argument column, select a data item from the FD; or:
    • In the Constant column, enter a constant value.
    Note: If the Optional column contains a tick, the parameter is not required.
  5. Click Save to Catalog.

The new synthesized data item appears in the FD grid with a COBOL name of Func:<FUNCTIONNAME> and a Default Column Name of FunctionName_Of <FirstArgument>. If you are adding multiple internal functions of the same type, be sure edit the Default Column Name to something distinctive so that you can distinguish them later.

Parent topic: Internal Functions


Defining Item Sets

An item set is composed of two or more data items in a COBOL record that contain identical information but that have been identified to Relativity as a set of redundant data items. Redundant data items include situations such as where one data item is identical to the first characters of another data item. One place where redundant data items are defined is in keys, where different keys provide different look-up capabilities in a file. Using Relativity, an item set becomes one data item in a relational database table.

Identifying redundant data items as an item set provides two advantages to Relativity:

  • The Relativity DBMS is more likely to be able to choose an efficient index for accessing the data.
  • When writing data with SQL UPDATE or INSERT statements, the redundant data will be maintained consistently by deriving its value from a single column value.

Item sets are maintained in the Properties pane for items pertaining to a set.

  • Configuring Items in an Item Set
Parent topic: Augmenting the COBOL File Definition in the FD Form
Related reference
Defining Conditions
User Data Type attribute
Default Column Name attribute
Transform attribute


Configuring Items in an Item Set

  1. In the Catalog Explorer, double-click the File Definitions node, then double-click the required file definition.

    The <file-definition-name> tab is displayed.

  2. Maintain item sets using the following:
    • Add an item to an item set:
      1. Select the item to be added.
      2. In the Advanced section of the Properties pane, expand Redundancy Set.

        The inner Redundancy Set option indicates if the item is already a member of an item set.

      3. Click [image] and select <New> to create a new item set, or select an existing item set.

        The data item is added to the item set.

      4. Select Covers Redundancy if current item covers the entire memory segment of the redundancy set.
    • Remove an item from an item set:
      1. Select the item to be removed.
      2. In the Advanced section of the Properties pane, expand Redundancy Set.

        The Redundancy Set option indicates the item set with which the item is already a member.

      3. Click [image] and select <None>.

        The data item is removed from the item set.

Note: The changes are saved to the catalog automatically.
Parent topic: Defining Item Sets


Defining Null Information

Null information is the means of specifying the relationship between COBOL data-item values and the SQL NULL value. This information is represented by the Null Value and Not Null properties, in the Properties pane when a data item is selected on the FD form.

The Null Value property specifies the condition item that must evaluate true to produce a null value, or will be stored when a null is written, in an SQL column, for that data item. The null definition is made by selecting one of the 88-level condition-names within the FD form; it doesn't need to be directly associated with the data item with which you are defining the null value, but it will be the conditional variable that is evaluated to determine the null value.

Similarly, if you also select the Not Null tick-box, then the evaluation must be false for that data item to be defined null.

If the original source for the file description did not include the necessary 88-level condition-name definition, use the Relativity Designer to add the condition-name. For more information on adding condition items, see Defining Conditions.

A column in a relational table that is based on a data item with null information set is automatically marked as Nullable in the corresponding Properties pane in the table definition. If the condition specified by the condition-name in the FD form is true for a record, then the column will contain null for the row(s) derived from that record.

Null information can also be set within custom data types, where the Nullable property indicates that the data type defines columns that allow nulls.

Parent topic: Augmenting the COBOL File Definition in the FD Form
Related reference
Defining Conditions
User Data Type attribute
Default Column Name attribute
Transform attribute
Building a New Record
Handling Multiple Record Types
Rules for Insertable Tables
Subscript Rule
File Options
Defining Conditions
Using the Nullable Columns Report


Specifying Comments

The Comment column within the FD form enables you to add comments pertaining to the data items defined in the FD form.

This functionality is useful for a developer to maintain a user-friendly definition of the data item, or maybe indicate the uses of a data item that may not be obvious. This can be especially useful for FDs that are imported from another source.

The FD comments can also be inherited by the table definitions if the Inherit Comments from FD tick-box is selected in the Table tab in the Options pane. Imported comments are displayed in the Properties pane when you select a column name in a table definition.

Parent topic: Augmenting the COBOL File Definition in the FD Form
Related reference
Defining Conditions
User Data Type attribute
Default Column Name attribute
Transform attribute


Filtering File Definitions

You can apply a filter to the data items currently displaying in the FD. Populate the Filter items text box with the full or partial name from the COBOL Name column to apply the filter; clear any text from the Filter items text box to remove the filter.

Parent topic: Augmenting the COBOL File Definition in the FD Form


Exporting File Definitions

When displaying a file definition in the work area, you can click [image] (Export the file description...) to export the FD to a text file; this includes any augmentation that has occurred to the original FD within Relativity Designer. This file can be used like any other COPY file in your COBOL source.

Parent topic: Augmenting the COBOL File Definition in the FD Form


Defining Relational Tables in the Table Form

Taking the file definitions displayed in an FD form (and any augmentation performed on that FD), you can create a table definition, which maps the data items to columns in a relational table. The table definition is also associated with one or more COBOL data files, which provides the row content of the generated relational table. Each time a COBOL data file is associated with a table definition it is called a table instance.

  • Creating and Editing Table Definitions
    Create a table definition from one of the augmented file definitions and a COBOL data file. Within the definition, you can update it a number of ways in order to produce the desired table.
  • Defining Columns on Repeating Data Items
    If you have flattened the OCCURS clauses in the file definition, you must bind the subscript conditions to the table columns.
  • Handling Multiple Record Types
    Table definitions are derived from the data items in a file definition. You can choose to select from only a subset of those data items by associating it with one or more record types.
  • Defining Table Filters
    Define table filters within a table definition to further limit the COBOL records used as rows in a table.
  • Defining Transforms on Columns
    Transforms can be applied to column data from the table definition.
  • Building Writable Tables
    Design tables that can be modified using the SQL statements INSERT, DELETE, and UPDATE, thus updating the underlying COBOL data files.
  • Establishing Table Instances
    Configure the connections between table instances and the COBOL data files that supply the table data.
  • Supporting Multi-file Tables
    Multi-file table support allows the records of more than one COBOL data file to be combined into a single table.
  • Previewing Table Data
    You can preview the overall design of the table, to see how it looks when viewed by an external ODBC application.
Parent topic: Micro Focus Relativity Designer for Windows
Related reference
Specifying Treatment of the OCCURS Clause


Creating and Editing Table Definitions

Create a table definition from one of the augmented file definitions and a COBOL data file. Within the definition, you can update it a number of ways in order to produce the desired table.
  • Creating a Table Definition
  • Editing a Table Definition
  • Copying a Table Definition
  • Deleting a Table Definition
Parent topic: Defining Relational Tables in the Table Form
Related reference
Defining Columns on Repeating Data Items
Defining Table Filters
Defining Transforms on Columns
Handling Multiple Record Types
Previewing Table Data
SQL Reserved Words


Creating a Table Definition

  1. In the Catalog Explorer, double-click the File Definitions node.

    The catalog's file definitions are displayed.

  2. Expand the relevant file definition, right-click Table Definitions and select New Table Definition.
    Note: The Catalog Explorer also contains a Table Definitions node, where all tables (regardless of which file definition they are derived) are listed; you can also right-click this node and select New Table Definition.

    The Table Definition Source dialog box is displayed.

  3. Define the table properties:
    1. If you invoked the dialog box from the File Definitions node, the appropriate file definition is already specified, but if required, in the File Definition field, click [image] and select the file definition.
    2. If the file definition contains record types, in the Record Type field, [image] and select a record type. (If you select a record type, only the fields within the record type are available to select as table columns; this step is optional.)
    3. In the Table Definition Name field, type a name for the table definition.
    4. If there is COBOL data file information available in the file definition, the Link to data file (optional) tick-box is selected, and the File Path field displays the file name of the COBOL data file name. If Link to data file (optional) is selected, a table instance is created automatically with the same name as the table definition, and a file name using the File Path value. Do not select this option if you do not want to create a table instance immediately; however, note that a table instance is necessary to supply the records for the rows of the table.
    5. The File Path field has defaulted to the file path and name of the data file specified for the file definition in the COBOL source; if required, update the path and file name for the data file that is to supply the data for the table.
      Note: You can clear the Link to data file option and create a table definition with no data file defined; you can add one or more data files later, when defining a table instance.
    6. Click Create Table.

      At this point, the table definition is created. If Link to data file (optional) was selected, a table instance with the same name is created. Note that when you specify a table name in a SQL statement, you are specifying a table instance name. It is possible to create multiple table instances on the same table definition, each with a different COBOL data file name. This is one way that you can support multiple companies using one Relativity catalog; see Supporting Multi-file Tables for another method.

    The Add Columns to Table Definition grid is displayed.

  4. Select or clear the following tick-boxes, as appropriate:
    • Show Group Items - all group items, including 01-level items, from the file definition are available.
    • Show 88s - All condition items are available.
    • Allow Duplicates - Allows a data item to be added to the table definition more than once; subsequent data items (and their corresponding column names) are appended with _n where n is the incremental count of that data item's frequency.
      Note: Allowing duplicates within a table precludes it from being writable; see Same Item Rule.
  5. In the left-hand column, select each COBOL name to include in the table. (Remember: each selected COBOL name equates to a table column.)
    Note: If you select two COBOL names that result in duplicate column names, you must edit one of the column names.
  6. Click Add Selected Columns.

    The table definition grid, with its selected columns, is displayed.

    At this point, there are a number of edits you can make before the table definition is saved to the catalog:
    • Rename the column names
      • Double-click the required cell in the Column Name column and amend the text, as appropriate, then press Enter.
    • Change the order of the columns:
      • Select a row in the grid, then use [image] (Move Column Down) and [image] (Move Column Up) to change the order of the column in the finished table.
    • Add or remove columns:
      • To add a column, click Add Column, then select one or more columns from the Add Columns to Table Definition section and click Add Selected Columns.
      • To remove a column, select the appropriate row in the grid, then click [image] (Remove Selected Column).
    • Set update and insert permissions:
      • To allow SQL UPDATE statements to be performed on the table, click Allow Updates.
      • To allow SQL INSERT or DELETE statements to be performed on the table, click Allow Inserts.

      These settings are in addition to the privileges you are required to set for a user. Both must be set before the statements can be successfully executed.

      Note: If you select either of these options on a table that is not writable, a warning is displayed, and the reason that the table is not writable is displayed in the Status pane; see Building Writable Tables for more information.
    • Create a table filter based on a conditional variable:
      • See Defining Table Filters.
    • Apply a column filter:
      • To limit the columns displayed in the table definition grid, in the text box to the left of [image] (Column Filter), enter the text that is common to the desired column names, then click [image] or press Enter.
  7. Click Save to Catalog.

    Once the table definition has been saved to the catalog, you can preview the table data.

Parent topic: Creating and Editing Table Definitions
Related reference
Copying a Table Definition
Deleting a Table Definition
Defining Custom Data Types
Handling Multiple Record Types
SQL Reserved Words
Building Writable Tables
Defining Table Filters
Same Item Rule
Related information
Editing a Table Definition


Editing a Table Definition

  1. In the Catalog Explorer, double-click the File Definitions node.

    The catalog's file definitions are displayed.

  2. Expand the relevant file definition, then expand the Table Definitions node.
  3. Double-click the relevant table definition.
    Note: The Catalog Explorer also contains a Table Definitions node, where all tables (regardless of which file definition they are derived) are listed; you can also expand this node and double-click the relevant table definition.

    The <table-def-name> Table pane is displayed.

  4. Perform one or more of the following edits:
    • Create a new table instance:
      1. In the Catalog Explorer, right-click the table definition and select New Table Instance.

        The Create Table Instance for <table-def-name> dialog box is displayed.

      2. In the Table Name field, enter a unique name for the table instance.
      3. In the File Path field, enter the path and file name for the data file that is to supply the data for the table instance.
      4. Click Add.
    • Change the data file used for a table instance:
      1. In the Catalog Explorer, expand the table definition and the required table instance.

        The data file entry is displayed.

      2. Right-click the data file name and select Edit File.

        The Edit File dialog box is displayed.

      3. If the data file is used in multiple table instances, and you want to change all instances, click Edit Path for all linked uses?.
      4. In the New Path field, enter the path and file name for the data file that is to supply the data for the table.
      5. Click Apply.

        The appropriate table instances are updated.

    • Rename the column names:
      • Double-click the required cell in the Column Name column and amend the text, as appropriate, then press Enter.
    • Change the order of the columns:
      • Select a row in the grid, then use [image] (Move Column Down) and [image] (Move Column Up) to change the order of the column in the finished table.
    • Add columns:
      • To add a column, click Add Column, then select one or more columns from the Add Columns to Table Definition grid and click Add Selected Columns.

    • Remove columns:
      • To remove a column, select the appropriate row in the grid, then click [image] (Remove Selected Column).
    • Set update and insert permissions:
      • To allow SQL UPDATE statements to be performed on the table, click Allow Updates.
      • To allow SQL INSERT or DELETE statements to be performed on the table, click Allow Inserts.

      These settings are in addition to the privileges you are required to set for a user. Both must be set before the statements can be successfully executed.

      Note: If you select either of these options on a table that is not writable, a warning is displayed, and the reason that the table is not writable is displayed in the Status pane; see Building Writable Tables for more information.
    • Create a table filter based on a conditional variable:
      • See Defining Table Filters.
    • Apply a column filter:
      • To limit the columns displayed in the grid, in the text box to the left of [image] (Column Filter), enter text that is common to the desired column name and click [image] or press Enter.
    • Rename the table definition:
      1. In the Catalog Explorer, right-click the table definition and select Rename Table Def.

        The Edit Table Definition Name dialog box is displayed.

      2. Enter a new name for the table definition, then click OK.

        The table definition is renamed.

  5. Some of the above edits require you to save to the catalog; if the Save to Catalog option is available, click it.

    The table definition changes are saved to the catalog.

Parent topic: Creating and Editing Table Definitions
Related tasks
Creating a Table Filter
Related reference
Creating a Table Definition
Copying a Table Definition
Deleting a Table Definition
Defining Table Filters
Building Writable Tables
Handling Multiple Record Types
Previewing Table Data
Defining Columns on Repeating Data Items


Copying a Table Definition

  1. In the Catalog Explorer, double-click the File Definitions node.

    The catalog's file definitions are displayed.

  2. Expand the relevant file definition, then expand the Table Definitions node.
  3. Right-click the required table definition and select Copy Table Definition.
    Note: The Catalog Explorer also contains a Table Definitions node, where all tables (regardless of which file definition they are derived) are listed; you can also right-click this node and select Copy Table Definition.

    The Copy Table Definition dialog box is displayed.

  4. In the To field, enter the name of the new table definition.
  5. Click Copy Table.

    A copy of the table definition (and any of its existing table instances) is displayed.

Parent topic: Creating and Editing Table Definitions
Related reference
Creating a Table Definition
Deleting a Table Definition
Related information
Editing a Table Definition


Deleting a Table Definition

  1. In the Catalog Explorer, double-click the File Definitions node.

    The catalog's file definitions are displayed.

  2. Expand the relevant file definition, then expand the Table Definitions node.
  3. Right-click the required table definition and select Delete Table Definition.
    Note: The Catalog Explorer also contains a Table Definitions node, where all tables (regardless of which file definition they are derived) are listed; you can also right-click this node and select Copy Table Definition.

    A confirmation box is displayed if the table definition contains table instances.

  4. Click OK.

    The table definition and any table instances are deleted.

Parent topic: Creating and Editing Table Definitions
Related reference
Creating a Table Definition
Copying a Table Definition
Related information
Editing a Table Definition


Defining Columns on Repeating Data Items

The OCCURS clause in COBOL data definitions presents a challenge when designing relational tables because the concept of the OCCURS clause is not available in the relational model.

The default behavior for subscripted items is to generate multiple rows for a COBOL record, one for each subscript of a data item. There are a number of ways of changing this behavior in the augmentation process - refer to Specifying Treatment of the OCCURS Clause for the different techniques.

Within the table definitions, if you are creating columns for individual subscripts, you must bind them to the specially-created conditions that were created in the file definition.

  • Binding a Column to a Subscript
Parent topic: Defining Relational Tables in the Table Form
Related reference
Specifying Treatment of the OCCURS Clause
Creating and Editing Table Definitions
Defining Conditions


Binding a Column to a Subscript

Binding a column to a subscript condition enables you to display subscripted data in table columns. The initial part of this process is carried out in the file definition - see Flattening OCCURS.

  1. In the Catalog Explorer, double-click the Table Definitions node.

    The catalog's table definitions are displayed.

  2. Double-click the required table definition.

    The table definition is displayed.

    Tip: If the column derived from the data item containing the OCCURS is already defined, remove it: select the column name, click [image] (Remove Selected Column), click Yes to confirm, then click Save to Catalog.
  3. In the Table form, click Add Column, select a subscripted data item that contains subscript conditions (see Adding Subscript Conditions to Flatten the OCCURS) and click Add Selected Columns.

    The Bind Subscripts to Columns dialog box is displayed.

    The Base Column Name(s) displays the base column name used for each subscripted data item associated with the subscript conditions. (Multiple data items are associated if you have coinciding OCCURS - see Identifying Coinciding OCCURS Clauses.)

  4. In the Columns field, select one of the following:
    • Single - one column per subscripted item is created, and multiple rows (based on the subscript range) are used in the table.
    • Multiple - enables you to create one column for each subscript (creating the 'flattening OCCURS' effect). Selecting this option and selecting all subscript conditions automatically binds the condition to the appropriate column.
  5. If columns are being created on Coinciding OCCURS items or are items that are subordinate to a group with an OCCURS, then a Group By field is displayed below Select all: in Group By, select one of the following:
    • Index - columns are ordered according to their subscript (all _1 columns, then all _2 columns, etc...)
    • Data Name - columns are ordered alphabetically (col-name_1, col-name_2, etc...)
  6. Click Add.

    The columns are added to the table definition.

  7. Click Save to Catalog.

The binding between the column and the subscript condition is displayed in the Properties pane:

Parent topic: Defining Columns on Repeating Data Items
Related reference
Flattening OCCURS
Adding Subscript Conditions to Flatten the OCCURS


Handling Multiple Record Types

Table definitions are derived from the data items in a file definition. You can choose to select from only a subset of those data items by associating it with one or more record types.

When you create a new table definition, you can associate it with one record type from the FD, or no record type.

When you associate it with a record type, only those data items in the record type are initially available to select as table columns. If you select no record type, all data items in the FD are available for selection.

However, after the initial selection, if you used a record type, you can use other record types configured for the FD to select further columns that did not belong to the original record type. Use the Record Type drop-down list in the table definition to make other data items available for selection.

Parent topic: Defining Relational Tables in the Table Form
Related reference
Defining Record Types
Defining Null Information
Using the Nullable Columns Report
Defining Table Filters


Defining Table Filters

A record type filter is applied in the FD to distinguish between multiple record types, enabling you to build table definitions that include only a targeted set of records (based on the value of a specific data item in each record). Sometimes, it is also desirable to further limit the COBOL records used as rows once the table definition has been created, and for that you need to define a table filter.

For example, an employee payroll master file might have a single record type containing all employee information, but separate tables for active and inactive employees are desired. A table filter may be used for this purpose. Whilst a separate record type could be defined in the FD form for each table, this seems unnecessary in most cases, where the need is only for additional filter factors.

A table filter defines the criteria that determine the records to be viewed in the Table form. Remember that a table filter is in addition to the record type filter; the record type filter is in effect for the record type being used to define the table. so you do not have to re-select the filter factors already in the record type filter when applying a table filter.

  • Creating a Table Filter
  • Editing a Table Filter
  • Deleting a Table Filter
Parent topic: Defining Relational Tables in the Table Form
Related reference
Eliminating Unused Occurrences
Defining Record Type Filters
Creating and Editing Table Definitions
Editing a Table Definition
Defining Record Types
Handling Multiple Record Types


Creating a Table Filter

  1. In the Catalog Explorer, double-click the Table Definitions node.

    The catalog's table definitions are displayed.

  2. Double-click the required table definition.

    The table definition is displayed.

  3. Click Create Table Filter.

    The Table Filter pane is displayed on the right-hand side.

  4. Click [image] (Add Factor) to the right of the AND operator.

    An empty factor is displayed.

  5. Click [image] and select an 88-level condition name.

    The condition names in this list are associated with data items in the FD form. If an appropriate condition name is not already defined, you must a create it in the FD form; see Creating a Condition Item.

  6. Click [image] and select the desired outcome:
    • Select True so that when the value of the 88-level condition matches its conditional variable, the filter is applied to the record.
    • Select False so that when the value of the 88-level condition does not match its conditional variable, the filter is applied to the record. This is the equivalent of a NOT operator.

      You can define further factors that have an AND or OR relationship with the one you just created.

  7. To define an AND relationship:
    1. Click [image] (Add Factor) to the right of AND.

      A new factor is displayed beneath the current one.

    2. Repeat steps 5 and 6 above to define the factor.
    3. Repeat step 7 to add more AND factors.
  8. To define an OR relationship:
    1. Click [image] (Add Condition) to the right of an existing factor.

      An OR + is displayed above the existing condition, and a new condition is added beneath the existing one.

    2. Repeat steps 5 and 6 above to define the condition.
    3. To add further factors to the OR relationship, click [image] (Add Condition) to the right of OR and define the condition.
  9. Click Save to Catalog.

    The filter is immediately applied to the table definition.

Parent topic: Defining Table Filters
Related reference
Deleting a Table Filter
Defining Conditions
Related information
Editing a Table Filter


Editing a Table Filter

  1. In the Catalog Explorer, double-click the Table Definitions node.

    The catalog's table definitions are displayed.

  2. Double-click the required table definition.

    The table definition is displayed.

  3. Click Edit Table Filter.

    The Table Filter pane is displayed on the right-hand side.

  4. Edit the factors, as required.
  5. Click Save to Catalog.

    The filter is applied to the table definition.

Parent topic: Defining Table Filters
Related reference
Deleting a Table Filter
Related information
Creating a Table Filter


Deleting a Table Filter

  1. In the Catalog Explorer, double-click the Table Definitions node.

    The catalog's table definitions are displayed.

  2. Double-click the required table definition.

    The table definition is displayed.

  3. Click Edit Table Filter.

    The Table Filter pane is displayed on the right-hand side. To delete a filter, you remove all the factors within it.

  4. Click [image] (Remove Factor) to the right of each factor within the filter.
  5. Click Save to Catalog.

    The filter is removed from the table definition.

Parent topic: Defining Table Filters
Related information
Creating a Table Filter
Editing a Table Filter


Defining Transforms on Columns

A transform is used to 'transform' (or convert) an existing data item value to and/or from a relational database column value. Transforms can be applied to the data item in the FD or at the column level (as described here).

Transforms applied at FD level affect all table definitions containing the data item the transform is applied to. Transforms applied at the column level only affects that column, in that table definition.

CAUTION:
If a transform is set at both FD level and column level, it is first transformed using the FD level transformation, and then again using the column level transformation, which may produce undesired results.
  1. In the Catalog window, double-click the Tables node.

    The catalog's table definitions are displayed.

  2. Double-click the required table definition.

    The table definition is displayed, showing the current table columns.

  3. Select the required column.

    The column properties are displayed in the right-hand Properties pane.

  4. In the Properties pane, click [image] next to Column Transform and select the required transform.

    Note: The list of available transforms is based on the column's data type. It may be necessary to change the Data Type property for the column to make the desired transform available.
  5. Click Save to Catalog.
Parent topic: Defining Relational Tables in the Table Form
Related reference
Creating and Editing Table Definitions
Transforms


Building Writable Tables

Relativity allows the contents of COBOL data files to be modified by using the INSERT, DELETE, and UPDATE statements of ODBC SQL.

In order to support these SQL statements, the tables must be writable. The Relativity Designer must follow several rules when defining tables and their association with COBOL application files for a table to be writable. If these rules are not followed, a table can only be read.

Many of the rules will be enforced at design-time (the augmentation stage) by the Relativity Designer; others will be detected and enforced when an attempt is made to actually modify a table.

Restrictions beyond those imposed by the RDBMS may be intentionally imposed by the Relativity Designer by using the Relativity security features. Defining the Relativity security and privilege capabilities becomes much more important when the end-user of the database can modify data files; see Defining Security for Relativity Catalogs for more information.

The rules for defining writable tables fall into two general categories:
  • Rules for determining whether or not rows can be inserted into and deleted from a particular table - see Rules for Insertable Tables.
  • Rules for determining whether or not a particular column in an existing row can be updated through SQL - see Update Rules.
  • Defining Insertable Tables
    Marking a table as insertable allows SQL INSERT and DELETE statements to be attempted, which, if successful, will update the underlying COBOL data file. Its success depends on a set of rules that each insertable table must follow.
  • Building a New Record
    When performing an SQL INSERT statement, Relativity needs to construct a new COBOL record.
  • Rules for Insertable Tables
    Insertable tables are tables that allow SQL INSERT and DELETE statements to affect the table. In order to be insertable, there are a number of rules that must be adhered to otherwise the statements will fail.
  • Determining Occurrence Count
    The occurrence count of every repeating data item must be determined each time a record is inserted.
  • Determining Record Type
    When a table is defined on multiple record types, the Relativity DBMS must determine the appropriate record type on each SQL INSERT statement.
  • Modifying an Existing Record
    The Relativity DBMS allows updates to tables that contain columns defined on repeating data items.
  • Update Rules
    There are a number of rules that apply to SQL UPDATE operations in Relativity.
  • Using the Nullable Columns Report
    The Nullable Column report is helpful tool in identifying the nullable settings in effect for numeric and date columns in your Relativity catalog.
Parent topic: Defining Relational Tables in the Table Form
Related reference
Editing a Table Definition
Defining Security for Relativity Databases
Rules for Insertable Tables
Update Rules


Defining Insertable Tables

Marking a table as insertable allows SQL INSERT and DELETE statements to be attempted, which, if successful, will update the underlying COBOL data file. Its success depends on a set of rules that each insertable table must follow.

Within the table form, you define a table as insertable by selecting the Allow Inserts tick-box. which allows an ODBC application to attempt an INSERT on the table.

In order for the INSERT to be successful, the table must, in general, have a format that will allow a single COBOL data record to be populated and written into the COBOL data file. To create the underlying COBOL data record based on the information provided in the INSERT statement, there are a number of rules that must be adhered to; Refer to Rules for Insertable Tables for a full list of rules.

Note:
  • An SQL INSERT statement does not have to specify column values for all columns of the table. For columns not specified, NULL is implied; therefore, those columns not specified must be marked as nullable in the Properties pane:

  • The Relativity DBMS must create a COBOL data record that would generate the new row implied by that SQL INSERT statement. Since the relational table derived from the COBOL record may not have columns based on all the data items in the record, the Relativity DBMS must be able to synthesize values for all those data items not represented in a relational row of the table.

    This synthesis is accomplished through various, sometimes subtle, means. The most obvious method is default values for columns or data items - see Defining Custom Data Types. More subtle methods are those based on making table filters and record type filters true by setting appropriate values from condition-names into their conditional variables in the data record - see Defining Record Types and Defining Table Filters.

Essentially, the rules for insertable tables must guarantee that the Relativity DBMS can derive a value for every data item in the inserted data record in the event of partial information provided in the column values specified by the INSERT statement.

Relativity also allows SQL DELETE statements, but only if the table is marked as an insertable table.

Parent topic: Building Writable Tables
Related reference
Specifying Treatment of the OCCURS Clause
Determining Occurrence Count
Determining Record Type
Rules for Insertable Tables
Building a New Record
Defining Custom Data Types
Defining Record Type Filters
Defining Table Filters


Building a New Record

When performing an SQL INSERT statement, Relativity needs to construct a new COBOL record.

It needs to determine the length of the new record and the value of every byte in the new record. The resulting record must be a valid record for the file to which it is to be written. It must also produce a row of the table on which the INSERT statement is operating.

To be a valid record, the record must "look like" one of the record types that a COBOL application might write to the file. It must have the correct length, and all data items which would be set by a COBOL application statement. All variable-occurrence repeating data items must have occurrence counts that are between the minimum and maximum values.

To produce a row of the table means that the record must satisfy the table filter, if any, and also the record type filter for one of the record types on which the table is defined. The user would also expect that the column values returned from a SELECT statement of this row would match the column values supplied on the INSERT statement, except that columns omitted from the INSERT statement may have null or default values.
Note: The Constrained property selected in a Custom Data Types limits the column value during an SQL INSERT or SQL UPDATE operation to one of the true values indicated by an 88-level condition-name defined on the data item associated with the column. You can add condition items if the program does not already contain them.
The Relativity DBMS will select a record type (if the table is defined on multiple record types) and use the single 01-level item in that record type. This item will determine the record length and record layout. All areas of the record not covered by items in the record type will be set to spaces. Items belonging to the record will receive values as follows:

  • If a column is associated with a data item, the data item will receive its value from the column, either a user-specified column value or the column's default value.

  • If no column is associated with an item, and if the table filter or record type filter determines a single value for an item, the item will be set to the value so determined. See the discussion of filters in Determining Record Type for more information about how a filter determines an item value.

  • If no column is associated with a data item but the data item has a default value, the item will be set to its default value.

  • If an item receives no value by any of the above means, the item will be set to zero if it is numeric. Nonnumeric items will not be set explicitly; the record area will be initialized to spaces before any items are set.

In addition, an item may receive a value indirectly, as follows:
  • When a value is stored in a function item that is reversible (that is, its parameters can be computed from the stored value), the function's parameters are stored into the function item's arguments.
  • If a column is associated with an item that has an associated null condition-name, when the column value is stored, the conditional variable data item associated with the null condition-name must also be set appropriately.
  • If necessary, the Relativity DBMS may set values in unset items to force the table filter and record type filter expressions to be "true".
Parent topic: Building Writable Tables
Related reference
Defining Null Information
Determining Record Type
Handling Multiple Record Types
Only One 01 Rule


Rules for Insertable Tables

You must mark the table as insertable from the table definition pane.

If the table is not currently insertable, you can continue to mark it so, but refer to the reason(s) why you received the message above, then use the following topics to make the table insertable:

  • Subscript Rule
    For writable tables, no column may be defined on a subscript item.
  • Repeating Item Rule
    For writable tables, columns defined on a repeating data item must have its subscripts bound to constants.
  • OCCURS Rule
    For writable tables, it must be possible for the Relativity DBMS to determine the value of every "OCCURS … DEPENDING ON" control item (ODO control item); that is, the occurrence count must be determined.
  • Same Item Rule
    For writable tables, no two columns may be defined on the same item or on overlapping items within the same record type.
  • Record Type Rule
    For writable tables, when a table is defined on multiple record types, it must be possible for the Relativity DBMS to determine the correct record type to use when inserting each record.
  • Only One 01 Rule
    For writable tables, unless all of the columns in a table are bound to items that are located in the same 01-level item, each record type on which a table is defined must explicitly contain exactly one item at the 01 level.
  • Overlap Rule
    For writable tables, in each record type on which a table is defined, none of the elementary data items may overlap except in the case of explicit redefinition within the same 01 record description.
  • Null Condition Rule
    For writable tables, for each item in every record type on which the table is defined, if the item has a null condition and it is not defined on the data item itself, then the condition must have a "SET TO FALSE" value.
  • Filter Rule
    For writable tables, it must be possible for the Relativity DBMS to ensure, for the table filter and for each record type filter, that the filter expression is true.
  • Key Rule
    For writable tables, during an insert, values for unique keys must be determined.
  • Nullable Columns Rule
    For writable tables, any column that is going to store an SQL NULL value must have a null condition-name.
Parent topic: Building Writable Tables
Related tasks
Creating a Custom Data Type
Related reference
Defining Default Column Names
Defining Null Information
Handling Multiple Record Types
Nullable Columns Rule
Using the Nullable Columns Report
Subscript Rule
Repeating Item Rule
OCCURS Rule
Same Item Rule
Record Type Rule
Overlap Rule
Null Condition Rule
Filter Rule
Key Rule


Subscript Rule

For writable tables, no column may be defined on a subscript item.

In this example, neither of the highlighted items should be moved to a table and still have that table be writable. The subscript items do not really exist in the underlying COBOL data file. If you need to view subscript items, consider creating a table for retrieving data and a separate table for writing. The separate table for writing must not include any repeating data items with unbound subscripts.

Parent topic: Rules for Insertable Tables
Related reference
Defining Null Information
Building Writable Tables
Rules for Insertable Tables


Repeating Item Rule

For writable tables, columns defined on a repeating data item must have its subscripts bound to constants.

Note that this does not prohibit columns defined on variable-length groups. It is not required that a column be bound to every occurrence of a repeating data item.

This example shows how all of an item's subscripts can be bound. The data item, SF-DOLLAR-SALES-PER-MONTH, has condition-names set for each value that the subscript can contain. In this case the values are 1 through 12. See Defining Columns on Repeating Data Items for more details on how subscripts are bound.

Parent topic: Rules for Insertable Tables
Related reference
Building Writable Tables
Rules for Insertable Tables


OCCURS Rule

For writable tables, it must be possible for the Relativity DBMS to determine the value of every "OCCURS … DEPENDING ON" control item (ODO control item); that is, the occurrence count must be determined.

The following example uses an OCCURS DEPENDING ON:

03 NUMBER-OF-STYLES PIC 99.
03 STYLE-STORAGE OCCURS 1 TO 9 TIMES
                  DEPENDING ON NUMBER-OF-STYLES INDEXED by STYLE-I1
   05 FIELD-A ...
   05 FIELD-B ...
03 FIELD-C ...

Some application files describe data arrays with an OCCURS clause without the DEPENDING ON phrase. However, the files have uninitialized or otherwise invalid data in some of the occurrences.

Because of the limitations on the use of the DEPENDING ON phrase, the COBOL Procedure Division statements test the data item NUMBER-OF-STYLES to limit the occurrences used. If this is the case, the DEPENDING ON item must be identified.

Parent topic: Rules for Insertable Tables
Related reference
Specifying Treatment of the OCCURS Clause
Determining Occurrence Count
Identifying Implicit OCCURS DEPENDING ON Clauses
Building Writable Tables
Rules for Insertable Tables


Same Item Rule

For writable tables, no two columns may be defined on the same item or on overlapping items within the same record type.
Relativity prohibits this situation because the information written would not be the same information retrieved on a subsequent read. Consider if you had two columns defined on PF-PRICE-PER-UNIT. A value of 12.95 was placed in one column, and 13.95 in the other column. This row was then inserted into a table. If you were to immediately read that same row, there would be no way to return 12.95 and 13.95 to the columns, since only one COBOL record was written.
Note: In the table definition editor, multiple columns can be defined on the same data item when Allow Duplicates is selected.

Parent topic: Rules for Insertable Tables
Related reference
Building Writable Tables
Rules for Insertable Tables


Record Type Rule

For writable tables, when a table is defined on multiple record types, it must be possible for the Relativity DBMS to determine the correct record type to use when inserting each record.

This is only an issue if multiple record types are assigned to the same table. In this example, the table is defined on the record types: NSize, and PSize.

Relativity must be able to determine from the filters and data provided which record type was intended to be written to. The assumption is that only one of the record types will be valid.

Parent topic: Rules for Insertable Tables
Related reference
Defining Record Types
Handling Multiple Record Types
Building Writable Tables
Rules for Insertable Tables


Only One 01 Rule

For writable tables, unless all of the columns in a table are bound to items that are located in the same 01-level item, each record type on which a table is defined must explicitly contain exactly one item at the 01 level.

This 01-level item determines the length of inserted records which use that record type unless the file definition includes a record size Working-Storage Section item.

This example shows multiple 01-level items (PRODUCT-RECORD, BACK-ORDER-RECORD and DISCONTINUED-RECORD) included in the same record type (BACK-ORDER-RECORD). A table that contained this record type could not be written to unless all of the columns are derived from items belonging to a single 01 level item. That is, all must belong to PRODUCT-RECORD, all must belong to BACK-ORDER-RECORD, or all must belong to DISCONTINUED-RECORD. This is the only way that the correct 01 level can be selected for the COBOL WRITE or REWRITE. A simple rule to follow for writable tables is to define a record type for each level 01.

This rule does not imply that the 01 Level that is part of the record type must be part of the table. Adding a 01 Level to a table with any other items will probably violate the Same Item Rule.

Parent topic: Rules for Insertable Tables
Related reference
Defining Record Types
Same Item Rule
Building Writable Tables
Rules for Insertable Tables


Overlap Rule

For writable tables, in each record type on which a table is defined, none of the elementary data items may overlap except in the case of explicit redefinition within the same 01 record description.

That is, an overlap may not occur for elementary data items described in different 01 record descriptions as a result of implicit or explicit redefinition, regardless of whether a column is bound to either or both of the overlapping items.

In the example, PF-BACK-ORDER-QUANTITY and PF-REPLACEMENT-NUMBER overlap:

Parent topic: Rules for Insertable Tables
Related reference
Building Writable Tables
Rules for Insertable Tables


Null Condition Rule

For writable tables, for each item in every record type on which the table is defined, if the item has a null condition and it is not defined on the data item itself, then the condition must have a "SET TO FALSE" value.

Relativity Designer supports setting the "SET TO FALSE" value through the Add 88 and Edit Condition dialog boxes.

In this example, the condition CASH is the null condition value for the data item OF-CREDIT-CARD-NUMBER. CASH has a Set to False value of 2. Any write of a record not containing a column based on OF-ORDER-TYPE and where OF-CREDIT-CARD-NUMBER is null will set CASH to true. Any write where OF-CREDIT-CARD-NUMBER is not null will set OF-ORDER-TYPE to be the "SET TO FALSE" value of the condition CASH (that is, 2). This is why the "SET TO FALSE" value is required for writability for tables with nullable columns.

Parent topic: Rules for Insertable Tables
Related reference
Building Writable Tables
Rules for Insertable Tables
Defining Null Information


Filter Rule

For writable tables, it must be possible for the Relativity DBMS to ensure, for the table filter and for each record type filter, that the filter expression is true.

This may require that some condition-names have "SET TO FALSE" values.

In this example, the 88-level condition-name items BACKORDER and DISCONTINUED must both be false in order for a write to the record type PRODUCTS. The PF-PRODUCT-CATEGORY data item (on which the 88-level condition-name items are defined) must be represented in the table, or have a default value that would set these 88-level condition-name items to false.

Parent topic: Rules for Insertable Tables
Related reference
Building Writable Tables
Rules for Insertable Tables


Key Rule

For writable tables, during an insert, values for unique keys must be determined.

This does not require that a column be defined for all of the data items in every key. Nor does it preclude part of the key from using default values, or part of the key being defined in the filter. It is also allowable to have no parts of the key defined by columns. This could happen if you have a key that used spaces as a valid value for some form of counter or header record. This would allow only one insert, but would be valid for updating. Some front-end tools may have different requirements. As an example, Microsoft Access wants to be able to determine a unique index before it will allow updates or inserts in datasheet view.

In this example, the data items, the following highlighted items make up the primary key. All of these data items should be accounted for in any tables that will allow write operations. They may be accounted for as a column, as part of the record type filter, or as part of the table filter.

Parent topic: Rules for Insertable Tables
Related reference
Building Writable Tables
Rules for Insertable Tables


Nullable Columns Rule

For writable tables, any column that is going to store an SQL NULL value must have a null condition-name.

If you have a table with multiple record types, it is possible to mark columns as nullable without an underlying null condition-name. This supports the case where the item upon which the column is based is not part of the record type being written for a particular INSERT statement or for a numeric item that is set to return a null value if it contains non-numeric data. Setting a column as nullable does not by itself allow a null value to be stored. It is safer to assign a null condition-name to any data item that might receive a null value. If you mark a column as nullable without having a null condition-name, and a null value is written, the write operation will fail with an error.

In this example, the PF-PRODUCT-SIZE data item has a null condition-name. This allows the column PRODUCTSIZE to be nullable. If a write operation is executed on this table, Relativity will know what value to store in the COBOL data file if the column contains a null value.

Parent topic: Rules for Insertable Tables
Related reference
Building Writable Tables
Rules for Insertable Tables
Defining Null Information
Handling Multiple Record Types
Using the Nullable Columns Report


Determining Occurrence Count

The occurrence count of every repeating data item must be determined each time a record is inserted.
The Relativity DBMS will try the following:
  • If a column is defined on the ODO control item, the value will be set explicitly on each INSERT statement. The column must either not be marked as nullable or have a default value.
  • If a column is defined on a variable-length group that contains the repeating data item, the occurrence count will be computed from the length of the column value.
  • If neither of the above applies, but the ODO control item has a default value, the item's default value will be used.
Note: One of these conditions must be applicable or the table is not insertable.
Parent topic: Building Writable Tables
Related reference
Specifying Treatment of the OCCURS Clause
Building Writable Tables
Identifying Implicit OCCURS DEPENDING ON Clauses
OCCURS Rule


Determining Record Type

When a table is defined on multiple record types, the Relativity DBMS must determine the appropriate record type on each SQL INSERT statement.

The technique by which the Relativity DBMS accomplishes this can be quite involved. It can be thought of as a process whereby the Relativity DBMS builds a record according to each record type and then tests the table filters and record type filters, until both of these filter expressions are true or until all of record types have been tried. In the latter case, the SQL INSERT statement will fail.

The Relativity DBMS may test both the value of a factor and set items to make the filter result true. To understand what the Relativity DBMS must do, it is necessary to review exactly what a filter expression is.

A filter expression consists of one or more factors connected with logical AND operators. Each factor consists of one or more filter subexpressions connected with logical OR operators. Each subexpression is either a condition-name or a logically complemented condition-name.

Therefore, for a filter expression to be true, each factor must be true. For a factor to be true, at least one of the subexpressions of the factor must be true. For a subexpression to be true, the condition-name must be either false or true, depending on whether it is complemented or not, respectively. A factor that consists of a single subexpression is a very special case since it requires that the condition-name in this subexpression be true or (if complemented) false. Thus, requiring that the filter expression be true may force particular values be stored in the data items on which such condition-names are defined. The Relativity DBMS may use that fact to determine the values of some items in the record.

The complemented condition-names in a filter are a problem. Some, but not all, condition-names define a "SET TO FALSE" value. To set these condition-names to false, the Relativity DBMS can set the data item to the "SET TO FALSE" value. For other condition-names, the Relativity DBMS cannot determine any particular value to set; the value must be determined some other way.

As a result, if a filter expression contains factors with multiple subexpressions, or if some of the subexpressions are complemented condition-names that do not specify "SET TO FALSE" values, the Relativity DBMS cannot force the filter expression to be true. If the table definition and/or file definition do not provide some other means to cause the filter's value to be "true", the filter expression may never be true. Under such conditions, it may not be possible to insert any rows in the table.

Lastly, some record types may be excluded from consideration by examining which columns are given values (not null), either explicitly or a column default. If a column is defined on an item that is absent in one or more record types, the column is null for any record with one of these record types. Therefore, if an INSERT statement sets a column to a (not null) value, these record types may be ignored; their filters need not be tested.

Note The Nullable Column utility provides a way to determine the status of null information within the catalog.

Parent topic: Building Writable Tables
Related reference
Handling Multiple Record Types
Using the Nullable Columns Report


Modifying an Existing Record

Unlike SQL INSERT statements, SQL UPDATE statements do not create records. Therefore, the problems that the Relativity DBMS faces for an INSERT operation do not apply. As a general rule, the Relativity DBMS allows any table to be updated if the user marks it updatable in the Relativity Designer using the Allow Updates check box on the Table Form toolbar. Some restrictions on the columns that can be updated, however, do apply.

In particular, the Relativity DBMS allows updates to tables that contain columns defined on repeating data items. Note that such tables contain two sorts of columns:

  1. Columns defined on repeating data items, which may be different on each row.
  2. Columns defined on non-repeating data items, when items are shared by several rows.

Therefore, an update to the latter sort of column would change multiple rows. The Relativity DBMS does not permit updates to the latter sort of column in such a table.

Hence, if a record contains both repeating and nonrepeating data items, the Relativity DBMS allows the user to update the nonrepeating data items via a table that has no columns defined on repeating data items, or to update the repeating data items via a table that has repeating data.

For more information on the rules that apply to updating existing records, see Update Rules.

Parent topic: Building Writable Tables
Related reference
Update Rules
Building Writable Tables


Update Rules

The following rules apply to SQL UPDATE operations when modifying an existing record in Relativity:
  • A column cannot be updated if it is defined on a subscript item.
  • If any column is defined on a repeating data item with unbound subscripts, then the only columns that are updatable are those defined on repeating data items with the same unbound subscripts.
  • A column cannot be updated if it is associated with a data item that overlaps the file's primary key.
  • A column cannot be updated if it is associated with a data item that overlaps the file key which the Relativity DBMS is using and if the file's primary key permits duplicates.
  • A column cannot be updated (or inserted, for that matter) if it is a date type (not a date-time type) and it specifies a date-time transform function or it is defined on a data item that specifies a date-time transform function.
Parent topic: Building Writable Tables
Related reference
Modifying an Existing Record
Building Writable Tables


Using the Nullable Columns Report

The Nullable Column report is helpful tool in identifying the nullable settings in effect for numeric and date columns in your Relativity catalog.

This is especially useful if you are creating writable tables as one of the requirements of a successful SQL UPDATE or INSERT operation is that columns not explicitly specified in the command must be nullable; see Nullable Columns Rule.

A nullable column is one that may be null. Null is not a value; it indicates the absence of a value. Since the rules of ODBC dictate that an error be returned if a numeric column contains non-numeric data, nullable settings can affect which columns can participate in an index, or as earlier mentioned, be a requirement of SQL UPDATE and INSERT operations.

There are a number of ways in which a column is marked as nullable:

  • In the Catalog tab of the Options pane, the Invalid Numerics Return NULL and Invalid Dates Return NULL options can be selected to set invalid numerics or dates to null.
  • If the column is derived from a data item that has a null value defined in the FD - see Defining Null Information.
  • Mark the column as Nullable in the Properties pane from the table definition - see Defining Insertable Tables.
  • Running the Nullable Columns Report
Parent topic: Building Writable Tables
Related reference
Defining Null Information
Catalog Options
Defining Record Types
Nullable Columns Rule
Running the Nullable Columns Report


Running the Nullable Columns Report

  1. On the Tools menu, click Nullable Columns Report.

    The Nullable Columns Report tab is displayed, and the report is automatically run, showing the breakdown of nullable columns in each table.

  2. Do one of the following:
    • To save the report as a .txt file, click Save, then use the Select File for Exported Messages dialog box to name and save the file.
    • To re-run the report, click Refresh.
  3. To close the report, click Close Without Saving.
Parent topic: Using the Nullable Columns Report
Related reference
COBOL Data Types Options
Catalog Options


Establishing Table Instances

Relativity must know the physical access name information for the COBOL data file that contains the actual data. The table instance consists of two important items:
  • The path name (that is, the physical COBOL data file-name) of a COBOL data file.
  • The table name by which SQL statements can reference the data in the file.
Note: Should file labels be in effect, the table instance also includes the name of the file label associated with the table instance.

Relativity distinguishes between the name of a table definition and the actual SQL table name. The table definition is manipulated in the Table form and is normally called a table within the Relativity Designer. Thus, several physical files that share the same COBOL file definition can be described by one Relativity table definition. The table instance is what an ODBC-enabled application actually "perceives" as a relational table.

Note: When a new table definition is added, a default table connection having a table name that is the same as the table definition name is created using the path name associated with the file definition, if there is one. When a table definition is renamed using the Rename command on the Table menu, an option is also provided to modify the table name in such a table connection.
  • Creating a Table Instance
  • Editing a Table Instance
  • Deleting a Table Instance
Parent topic: Defining Relational Tables in the Table Form


Creating a Table Instance

Use the following instructions to create the table instance, and then preview and manipulate its data.

  1. In the Catalog Explorer, double-click the Table Definitions node.

    The catalog's table definitions are displayed.

  2. Right-click the relevant table definition and select New Table Instance.
    Note: If you do not have privileges to create a table instance for that definition, the option is not displayed. You must get the catalog owner or another administrator with grant privileges on that table definition to grant the Create privilege.

    The Create Table Instance for <table-def> dialog box is displayed.

  3. In the Table Name field, type a unique name for the table instance. (The field background remains red until the name is unique.)
  4. In the File Path field, enter the full path and file name to the (first) COBOL data file to be used.
  5. Click Add.

    The table instance is created.

  6. To view the data, right-click the table instance and select View Data.

    The data is displayed.

  7. Use the following tools to further manipulate the display:
    • Max Rows - the maximum number of rows shown in the table preview. (You can set this default in the Tools > Options > General menu.)
    • Max Errors - the maximum number of errors encountered before the preview stops showing more rows (up to the Max Rows value).
    • Filter on Column - show only records that contain a specific value in a particular column: select the column in the drop list, then in the Filter string field type the string on which to filter.
    • Query Builder - a GUI tool used to define SQL queries for the preview; see Using the Query Builder for more information.
  8. To exit the preview, click [image] on the <table-name> data tab.
Parent topic: Establishing Table Instances
Related reference
Editing a Table Instance
Deleting a Table Instance


Editing a Table Instance

When editing a table instance, you can change the connection to one or more COBOL data file associated with the instance, and also change the labels used for multi-file instances.

  1. In the Catalog Explorer, double-click the Table Definitions node.

    The catalog's table definitions are displayed.

  2. Double-click the relevant table definition, then double-click the table instance to edit.

    The COBOL data file(s) associated with table instances are displayed.

  3. Right-click a data file and select Edit File.

    The Edit File dialog box is displayed.

  4. If other table instances connect to the same data file, the Edit Path for all linked uses tick-box is displayed: check this option to automatically update those other connections.
  5. In the New Path field, type the full path and file name to the data file.
  6. If the table instance uses multiple files, you can change the label for this data file: in the Label for this source field, update the label.
  7. Click Apply.

    The connection to the data file is updated.

Parent topic: Establishing Table Instances
Related reference
Creating a Table Instance
Deleting a Table Instance


Deleting a Table Instance

  1. In the Catalog Explorer, double-click the Table Definitions node.

    The catalog's table definitions are displayed.

  2. Right-click the relevant table definition and select Delete Table Instance.
    Note: If you do not have privileges to create a table instance for that definition, you are also unable to delete one, and the option is not displayed. You must get the catalog owner or another administrator with grant privileges on that table definition to grant the Create privilege.
  3. Click Yes to confirm deletion.

    The table instance is deleted

Parent topic: Establishing Table Instances
Related reference
Creating a Table Instance
Editing a Table Instance


Supporting Multi-file Tables

Multi-file table support allows the records of more than one COBOL data file to be combined into a single table.

If your COBOL application has data from several different business units, stored in different COBOL data files on the same machine, you can connect them to the same table definition.

Each table connection has a different table name that must be used in the SQL statement to indicate which data file is to be accessed. Sometimes, however, it is desirable to query the data in all business units. While it is possible to use separate table connections and to combine the resulting rows in the ODBC application, Relativity uses multi-file table support to perform this process automatically and at a record level, making use of the file keys.

The combining of records can occur in one of two ways. Either the records from each individual file are processed into rows separately, with each file being processed completely before proceeding to the next file, or the records from the individual files are read using the same key on each file and merged into one sorted record stream as if they were from a single file.

To control which method to use, and, in the ODBC application, to be able to distinguish the business unit from which the row originated, a special file definition item called a "file label" is added to the file's FD using the Designer. A given FD may have only one file label item. A file label item can have a column defined on it, and this column will be part of the indexes defined on the table. Assuming that columns are completely defined on all the file key parts, at least two indexes will be created for each file key: one with the file label column as the most significant part of the index, and one with the file label column as the least significant part of the index. If a query uses the index that has the file label column as the most significant column, then rows from each file will be grouped together. If a query uses the index that has the file label column as the least significant column, then the rows from each file will be returned merged together.

Note: To understand the difference between grouping records and merging records based on an index, consider two decks of playing cards, with each deck having different backs so that it is possible to tell which deck a card came from. If one deck of cards is placed on top of the other, the cards are grouped together by deck. But, if the cards are shuffled together, then they are merged. If the cards were then sorted into suits by their value without looking at which deck each card came from, then the cards are merged based on an index (their suit and value).

In Relativity, consider a table based on two files. Using the index that returns rows grouped together, the ODBC application would first see all the rows from the first file, and then the rows from the second. Using the index that merges the two files together, the ODBC application would see rows coming back from the two files mixed together.

When a COBOL data file is added to a multi-file table, it is assigned a value for its file label. This is the value that is returned in the file label column. Note that while it is usually desirable to assign the same file label value to all the files from the different business units, Relativity does not require or enforce this.

  • Enabling Multi-File Support
  • Configuring Tables for Multi-File Support
Parent topic: Defining Relational Tables in the Table Form


Enabling Multi-File Support

Multi-file support is enabled per file definition, and can then be applied to table definitions within the FD that utilize multiple files.

You can also right-click a table instance entry in the Table Definitions node and select Enable Multi-file.

  1. In the Catalog Explorer, select the required file definition, and then in the Properties pane, select Multi-File Enabled.

    The Enable Multi-File on FD dialog box is displayed.

  2. Type a name for the multi-file label column, and click Apply.

    Note: The maximum length of the file label can be configured from the Tools > Options > File pane (Multi-File Label Length option).

    In the FD, a new item, Label:<label-name>, is available.

    Multi-file support is now enabled for any tables derived from this file definition. When you create a table definition, use the new item to create an additional column for the file label.

Parent topic: Supporting Multi-file Tables
Related reference
Configuring Tables for Multi-File Support


Configuring Tables for Multi-File Support

To configure tables that use more than one data file, multi-file support for the file definition must have been enabled . The following instructions assume that this has already been done, and that the table instance requiring multiple files has already been created.

You will now add all required files to the table instance and label each one of them.

  1. In the Catalog Explorer, double-click the Table Definitions node.

    The table definitions are displayed.

  2. Expand the table definition containing the multi-file table instance, then expand the table instance.
  3. If the table instance already contains a data file, label the initial data file:
    1. Right-click the data file and select Edit File.

      The Edit File dialog box is displayed.

    2. In the Label for this source field, type a name by which this file will be identified, then click Apply.

  4. Add and label further data files:
    1. Right-click the table instance, then select Add File Source.

      The Add Additional File Source dialog box is displayed.

    2. In the File Path field, enter the path and file name of the next data file.
    3. In the Label for this File field, type a name by which this file will be identified, then click Add.

    4. Repeat these steps to add further files.

    The changes are saved to the catalog immediately.

    As long as the column representing the file label is defined in the table definition, data from each of the files is identified with the labels just entered.

Parent topic: Supporting Multi-file Tables
Related reference
Enabling Multi-File Support


Previewing Table Data

During the design and testing of a table definition, it is often necessary to verify the effect of a change or overall table design. The Preview Table Data form allows you to display table data in a grid so that you can see that the results are what you expected.

You can also use the Query Builder whilst in preview mode to display a subset of the table (based on the columns), and change the ordering. This can be very helpful in detecting and resolving any errors that may have occurred.

  • Previewing Table Data from the Table Form
  • Using the Query Builder
  • Analyzing Table Definition Errors
Parent topic: Defining Relational Tables in the Table Form
Related reference
Creating and Editing Table Definitions
Transforms
Analyzing Table Definition Errors


Previewing Table Data from the Table Form

  1. In the Catalog Explorer, double-click the Table Definitions node.

    The catalog's table definitions are displayed.

  2. Double-click the required table definition.

    The table definition is displayed.

  3. Click [image] (Preview Table Data).

    The <table-name> data tab is displayed showing a preview of how the table would look in an ODBC-enabled application.

  4. Use the following tools to further manipulate the display:
    • Max Rows - the maximum number of rows shown in the table preview. (You can set this default in the Tools > Options > General menu.)
    • Max Errors - the maximum number of errors encountered before the preview stops showing more rows (up to the Max Rows value).
    • Filter on Column - show only records that contain a specific value in a particular column: select the column in the drop list, then in the Filter string field type the string on which to filter.
    • Query Builder - a GUI tool used to define SQL queries for the preview; see Using the Query Builder for more information.
  5. To exit the preview, click [image] on the <table-name> data tab.
Parent topic: Previewing Table Data
Related reference
Using the Query Builder
Related information
Analyzing Table Definition Errors


Using the Query Builder

The Query Builder is available when you are viewing the table data.

The Query Builder allows you to design a simple query to retrieve data from specific columns of a table instance. The ability to define a query on a selected table is highly useful; for example, you can easily find erroneous data in your table by using the sort and specific criteria options to exclude data that you do not want to see.

Use the selection table at the top of the pane to select the columns to include, and the sort method and criteria of those columns, and then click Execute Query to run the underlying SQL on the table.

You can further narrow down the results by limiting the amount of rows displayed (Max Rows), or stop displaying results if a certain number of data errors are retrieved (Max Errors).

Specifying criteria

When building an entry in the Criteria row of the Query Builder form, you can use any expression that evaluates to a single value, True or False. An expression is any combination of operators, literal values, and names of columns.

The most commonly used conditions for numeric and date columns are the comparison operators, as defined below:

Operators | Definition
> | Greater than
> | Less than
= | Equal to
>= | Greater than or equal to
<= | Less than or equal to
<> | Not equal to
Between | Numeric range
Parent topic: Previewing Table Data
Related information
Previewing Table Data from the Table Form
Analyzing Table Definition Errors


Analyzing Table Definition Errors

The nature of table design and testing is likely to produce occasional table definition errors. If Relativity encounters these types of errors, they will be reported in the Status pane. This error process may also be triggered by file and/or table definition errors that interfere with Relativity's ability to correctly create an adequate table structure.

If the file and table definitions do not describe the data actually in the COBOL data file correctly, the table preview may display rows that have no data values in the grid cells. The following is a partial list of some typical situations where this might occur:
  • Nonnumeric data in an area described as numeric. The solution for this might involve defining or editing a record type filter to prevent incorrect physical records from generating rows. Otherwise, the fault might be in the actual data description.
  • A transform (typically a date transform) that is attempting to transform invalid data.
Parent topic: Previewing Table Data
Related reference
Using the Query Builder
Defining Record Type Filters
Previewing Table Data
Transforms
Related information
Previewing Table Data from the Table Form


Maintaining the Relativity Database

A Relativity database is comprised of two distinct parts:

  • The Relativity symbol table file (.rst file).
  • The catalog file (.rcg file), which contains the augmented file definitions and the generated relational tables.

The Relativity Designer supplies mechanisms that allow you to maintain both of these parts.

A Relativity symbol table file is created from the file and record descriptions when you import from a COBOL source or from an existing .rst file. From time to time, you will be required to update these when your source FDs change or further FDs are added to the database.

You can further augment these descriptions by adding more data items, condition items, date transforms, and so on. See Augmenting the COBOL File Definition on the FD Form for more information.

After the file definitions have been prepared, you can define the relational tables by associating the columns in the table with COBOL data items from the FD. The relational tables allow SQL generated by an ODBC-enabled application to access the COBOL data in a relational manner. For more information, see Defining Relational Tables on the Table Form.

  • File Definition Maintenance
    File definition maintenance is required if your imported FDs have changed at source, or you are merging additional FDs from other catalogs.
  • Relational Maintenance
    Maintain certain elements of a catalog that you plan to distribute.
Parent topic: Micro Focus Relativity Designer for Windows
Related reference
Augmenting the COBOL File Definition in the FD Form
Defining Relational Tables in the Table Form


File Definition Maintenance

After the COBOL file definitions have been imported into the Relativity catalog, you may need to provide further maintenance from within the Relativity Designer. Consider the following examples:

  • Record layouts for a file definition have changed from when the information was originally added to the catalog, and so the modified file definition information needs to be merged from the COBOL source into the existing catalog information. See Updating COBOL Data File Definitions for more information.
  • Several designers each design and test a Relativity catalog, and then the results are required in a single catalog for the end-user. (Relativity does not permit multi-user access of the catalog by designer developers.) In this scenario, you would merge file and table definition objects from one or more Relativity catalogs into the current catalog. See Merging Definitions from Another Relativity Catalog for more information.
  • Updating COBOL Data File Definitions
    You can use the Relativity Designer to update the file definitions already in a Relativity catalog.
  • Merging Definitions from Another Relativity Catalog
    The Relativity Designer can merge files, table definitions, and user data type objects from multiple Relativity catalogs.
Parent topic: Maintaining the Relativity Database


Updating COBOL Data File Definitions

You can use the Relativity Designer to update the file definitions already in a Relativity catalog. If the COBOL data file definitions have changed in the COBOL source since they were imported into the catalog, you should update the catalog definitions in order to maintain an accurate reflection of the data.

The process requires you to firstly re-import the FD from the updated source. This does not destroy or modify the definition existing in the Relativity catalog: a backed-up version of the file definitions and tables are taken - appending 'Previous' to the existing FDs, and appending 'OLD' to the table definitions.

The second part of the process is to use the merge editor to determine the actions required for any differences found between the original and updated FDs. Many items may be automatically matched, but you may need to match some manually. Once all the items are matched, new table definitions are created from the original FD's table using the matched FD items.

You may abort the update by closing the merge editor, and by deleting the new file definition and its associated table definitions from the Catalog Explorer.

Once the new table definitions have been created (and inspected), you can delete the original file definition and its associated table definitions from the Catalog Explorer. Alternatively, you can keep the previous file definition and tables, but in order to update the file definition again, these previous entries must be removed.

  • Updating FDs from a COBOL Source File or Relativity Symbol Table
Parent topic: File Definition Maintenance
Related reference
Merging Definitions from Another Relativity Catalog


Updating FDs from a COBOL Source File or Relativity Symbol Table

  1. With a catalog open in the Relativity Designer, on the Tools menu, click Update FDs from Source.

    The COBOL FD Importer tab is displayed in 'Updating FD from Source' mode. If you opened the COBOL FD Importer tab from the File menu, this mode is not enabled and you will be unable to perform the merge process with existing file definitions.

  2. In the Import FDs From field, select the type of update:
    • Update from a COBOL source (.cbl) file:
      CAUTION:
      Only use a source file that contains well-formed COBOL syntax that compiles cleanly.
      1. In the Import FDs From field, select RM/COBOL Source File using RST Schema Extractor (.cbl -> .rst).
      2. To the right of the Files to Import field, click [image] (Select file to import), then use the Open dialog box to select a .cbl file.
      3. If necessary, enter the appropriate compiler (directive) options in the Compilation Options field.
      4. If the FD includes copy files, click [image] (Select file to import) and select the folder(s) in which the copy files(s) reside.
        Note: If you are having issues with the update, you may be requested to perform it with Keep Temporary Files after Import selected, which retains the temporary files created during the update process; SupportLine can use the .lst and .err.xml temporary files to help troubleshoot update issues.
    • Update from an RM/COBOL object (.cob) file:
      1. In the Import FDs From field, select RM/COBOL Object File (*.cob).
      2. To the right of the Files to Import field, click [image] (Select file to import), then use the Open dialog box to select a .cob file.
    • Update from an Relativity Symbol Table (.rst) file:
      1. In the Import FDs From field, select RST Schema File (*.rst).
      2. To the right of the Files to Import field, click [image] (Select file to import), then use the Open dialog box to select an .rst file.
  3. Click Read File and Record Descriptions.

    A further two tabs are displayed. The Items to Import tab displays the FDs found in the selected file, and the Messages tab contains output from the Schema Extractor process.

  4. In the Items to Import tab, select the file definition(s) to update, then click Add to Catalog.
    Note: If you need to import other COBOL items from the source that are not part of the file definition (e.g. working-storage items), click Show Advanced Import Options, then select from the additional items displayed.

    For each selected file definition, an additional Update... tab containing a merge editor is displayed. Each FD is compared with the original FD, and an attempt is made to auto-resolve each field in the record.

  5. For each tab, deal with any items that require attention, as indicated by 'Unmatched' in the Matches column:
    1. Click the row containing Unmatched in the Matches column.

      Details of the difference between the original and new field are displayed.

    2. Click Unmatched, and then select a new status:
      • Select New if the item is a new addition to the FD.
      • Select Delete if the item is to be deleted from the FD.

    Once all unmatched fields are resolved, the Complete Merge for FD option becomes available.

  6. Click Complete Merge for FD.

    The updated file definition is now displayed in the Catalog Explorer. The existing file definition is still available in the Catalog Explorer, but has (Previous) appended to its name, and any tables associated with the previous FD have 'OLD' appended to their name. You can delete this file definition if it is no longer required, but first you must delete any existing table definitions for that file definition.

Parent topic: Updating COBOL Data File Definitions


Merging Definitions from Another Relativity Catalog

The Relativity Designer can merge files, table definitions, and user data type objects from multiple Relativity catalogs.

This capability permits several designers each to design and test their own Relativity catalogs, and then merge the file and table definitions into a single catalog, for an end-user. Relativity does not permit multi-user access of a single catalog by designers/developers, and so the merge process is ideal.

  • Merging from Another Relativity Data Source
Parent topic: File Definition Maintenance
Related reference
Updating COBOL Data File Definitions


Merging from Another Relativity Data Source

  1. With the catalog that is to be the destination of the merge open in the Relativity Designer, on the Tools menu, click Merge from Another Relativity Data Source.

    The Open Existing Data Source dialog box is displayed.

  2. On the Open Existing Data Source dialog box, click the data source currently shown, select the data source that is the source of the merge, and then click Connect.

    If the catalog associated with this data source has no security (that is, no group owner), the catalog is opened immediately; if this is the case, you are advised to add some privileges to the catalog - see Catalog Ownership and procedures on how to define catalog ownership.

    If the catalog has a group owner, the Database Logon dialog box is displayed.

  3. Complete the fields in the Database Logon dialog box, then click Login:
    • UserId - the name of the owning group or the name of a user in the owner group.
    • Password - the group/user may not have a password set; if not, leave this field blank.

    The Data Source Importer tab is opened, displaying the items you may import on the Tables and the Files tabs.

  4. To import a table, click the Tables tab, and in the Tables to merge column, select one or more tables to be imported.

    If the table name conflicts with an existing table name in the catalog, you must edit the table name in the Merged Table Name column.

    Note: When a table is selected, its associated file definition is also selected, ready to import.
  5. To import a file definition, click the Files tab, and in the Files to merge column, select one or more files to be imported.

    If the file name conflicts with an existing file definition in the catalog, you must edit the name in the Merged File Name column.

  6. To import a user data type, click the User Data Types tab, select one or more data types to be imported.

    If the file name conflicts with an existing file definition in the catalog, you must edit the name in the Merged Data Type Name column.

  7. Click Save to Catalog.

    The selected items are imported, and displayed in the Catalog Explorer.

  8. Close the Data Source Importer tab.
Parent topic: Merging Definitions from Another Relativity Catalog


Relational Maintenance

In the same way that further maintenance of the file definitions may be required, maintenance activities may also be required on the way that the file definitions relate to the generated relational tables. Such maintenance may include defining date constants and preparing catalogs for distribution.

  • Defining Date Constants
    Relativity provides a number of options that interpret the way in which COBOL dates are translated to SQL dates. These options, collectively known as date constants, are stored in the Relativity catalog.
  • Distributing Catalogs
    If you are going to distribute a Relativity catalog to end-users, there are a number of conditions that you must comply with.
  • Distributing Updated Catalogs
    If you distribute catalogs to end-users, there will be occasions when you need to send out updates to that catalog.
Parent topic: Maintaining the Relativity Database


Defining Date Constants

Relativity provides a number of options that interpret the way in which COBOL dates are translated to SQL dates. These options, collectively known as date constants, are stored in the Relativity catalog.

Date constants control the conversion in certain transforms and internal functions of COBOL data item values to SQL column date values.

The date constants can be adjusted using the Relativity Designer or the Relativity DBA to reflect common algorithms used in COBOL procedural code.

The values and structures of the date constants can be changed by appropriate actions in the Date Constants dialog box:

  • Define Base Date for Days Count
    The Base Date for Days Count constant specifies the date used to interpret date values that are represented as an integer number of days from a base date in the Gregorian calendar.
  • Define the Structure and Base Year for YY Dates
    The 'YY' Dates Date Structure constant specifies the structure to be used for COBOL data items that were associated with a six-digit date transform when the catalog was designed, and the 'YY' Base Year constant specifies the base year used to interpret date values containing a two-digit year.
  • Define the Structure and Base Date for YYYY Dates
    The 'YYYY' Dates Date Structure specifies the structure to be used for COBOL data items that were associated with an eight-digit date transform when the catalog was designed, and the 'YYYY' Base Year constant specifies the base year used to interpret date values containing a four-digit year.
Parent topic: Relational Maintenance
Related reference
Transforms


Define Base Date for Days Count

The Base Date for Days Count constant specifies the date used to interpret date values that are represented as an integer number of days from a base date in the Gregorian calendar.

The default base date is December 30, 1899, and so an integer value of zero in the COBOL data item thus represents this date, and an integer value of two in the COBOL data item represents the date January 1, 1900. Negative values are allowed in a signed COBOL data item to represent dates prior to the specified base date.

  1. On the Tools menu, click Date Constants.

    The Date Constants tab is displayed.

  2. In the Base Date for Days Count section, click [image] and use the calendar to select a date.
  3. Click Save to save the changes to the catalog.
    Tip: If you click Defaults, the base date reverts back to December 30, 1899.
Parent topic: Defining Date Constants
Related concepts
Define the Structure and Base Year for YY Dates
Define the Structure and Base Date for YYYY Dates


Define the Structure and Base Year for YY Dates

The 'YY' Dates Date Structure constant specifies the structure to be used for COBOL data items that were associated with a six-digit date transform when the catalog was designed, and the 'YY' Base Year constant specifies the base year used to interpret date values containing a two-digit year.

The six-digit date transform is specified during catalog design when the structure of end-user COBOL dates, with two-digit years, varies for different end-user sites. Each end-user site can set this variable to the structure used in its files. The default structure is YYMMDD (a two-digit year, followed by a two-digit month of the year, followed by a two-digit day of the month).

The default base year is 1900, and is added to a two-digit year value obtained from a COBOL data item when computing a column date value and is subtracted from the column date year value when computing a COBOL data item that contains a two-digit year.

Additionally, if you have six-digit dates that span centuries, use the Use 'YY' Century Cutoff constant to specify the century cutoff year, which is used to interpret date values containing a two-digit year that are considered to be in the next century if lower than the specified cutoff.

The default value is 1900. Using the default, all two-digit years are considered to be in the twentieth century (nineteen hundreds). If the value of 'YY' Century Cutoff is greater than 1900, then the value of 'YY' Base Year must be equal to 1900. The value of 'YY' Century Cutoff is only used when it is greater than 1900.

  1. On the Tools menu, click Date Constants.

    The Date Constants tab is displayed.

  2. In the 'YY' Dates section, in the Date Structure field, select one of the available structures:
    • YYMMDD
    • MMDDYY
    • DDMMYY
  3. Select Use 'YY' Base Year, and in the Base Year field, enter a value (up to four digits) for the base year.
  4. If you have six-digit dates that span centuries, select Use 'YY' Century Cutoff, and in the Century Cutoff field, enter a value (up to four digits) for the cutoff.

    For example, setting this constant to 1930 would cause any two-digit years between 0-29 to be interpreted to be in the next century (for example, 2029).

  5. Click Save to save the changes to the catalog.
    Tip: If you click Defaults, the structure reverts to YYMMDD, the base year reverts to 1900.
Parent topic: Defining Date Constants
Related concepts
Define Base Date for Days Count
Define the Structure and Base Date for YYYY Dates


Define the Structure and Base Date for YYYY Dates

The 'YYYY' Dates Date Structure specifies the structure to be used for COBOL data items that were associated with an eight-digit date transform when the catalog was designed, and the 'YYYY' Base Year constant specifies the base year used to interpret date values containing a four-digit year.

The eight-digit date transform is specified during catalog design when the structure of end-user COBOL dates, with four-digit years, varies for different end-user sites. Each end-user site can set this variable to the structure used in its files. The default structure is YYYYMMDD (a four-digit year, followed by a two-digit month of the year, followed by a two-digit day of the month).

The default base year is 0. The base year is added to a four-digit year value obtained from a COBOL data item when computing a column date value and is subtracted from the column date year value when computing a COBOL data item that contains a four-digit year.

  1. On the Tools menu, click Date Constants.

    The Date Constants tab is displayed.

  2. In the YYYY Dates section, in the Date Structure field, select one of the available structures:
    • YYYYMMDD
    • MMDDYYYY
    • DDMMYYYY
  3. In the 'YYYY' Base Year field, enter a value (up to four digits) for the base year.
  4. Click Save to save the changes to the catalog.
    Tip: If you click Defaults, the structure reverts to YYYYMMDD, and the base year reverts to zero.
Parent topic: Defining Date Constants
Related concepts
Define Base Date for Days Count
Define the Structure and Base Year for YY Dates


Distributing Catalogs

If you are going to distribute a Relativity catalog to end-users, you will need to comply with a number of conditions. (Instructions for performing each of these tasks can be found in the appropriate Relativity Client/Server Installation Guide.)

  • For client/server installations, the data server must be installed at the end-user site, on the same machine as the user data. The data client software must be installed on the individual machines with the ODBC applications.
  • For single-tier installations, the data manager must be installed on the same machine as the end-user data and the ODBC applications. If the user-data resides on a file server, it is possible to access it with data manager installed on multiple machines, but the Relativity DBMS must be installed on every Windows system that is to access the catalog. It is highly desirable for the catalog to reside on the file server with the user-data.
  • The catalog must be delivered on appropriate media for the end-user.
  • You may also choose to install the Relativity DBA on selected Windows machines, which will allow end-users to maintain security of the catalog.
  • For client/server installations, a server data source must be created that associates the data source name with the catalog.
  • For each Windows system that is to access the catalog, an ODBC data source must be created. For client/server installations, a client data source must be created that associates the data source name with the server data source. For single-tier installations, a single-tier data source must be created that associates the data source name with the catalog.
Parent topic: Relational Maintenance


Distributing Updated Catalogs

If you distribute catalogs to end-users, there will be occasions when you need to send out updates to that catalog.

There are multiple ways to accomplish this:

  • If you do not distribute the Relativity DBA, the end-user cannot modify your catalog; therefore, you just send an updated catalog and replace the end-user's existing catalog.
  • If you do allow your end-user access to the Relativity DBA, then you may wish to preserve changes made by the end-user when you distribute an updated catalog.

The Catalog Merge capability, distributed with the Relativity DBA, generally takes any changes made by the DBA and merges them into a new catalog, preserving Users, Privileges, and Connections modified and added by the end-user. For procedures on using Catalog Merge, see Merging a Catalog.

Note: Both the existing and modified catalogs must have owners in order to run this merge process.
  • Merging a Catalog
  • Rules File for Merging a Catalog
  • Sample Rules File
Parent topic: Relational Maintenance


Merging a Catalog

The updated catalog must be distributed on media appropriate for the end-user and the catalog must be in place prior to executing the catalog merge. The updated catalog either must be published to ODBC (that is, a data source created specifying it as the catalog) prior to executing the catalog merge, or the RELDBUTL.INI control file contains a CONNECT section that will create the data source prior to the merge.

The merge utility is a standalone executable that is distributed with Relativity DBA. It must be executed from a Windows command prompt, as it contains a command line parameter specifying a rules file; for example:

C:\RELDBXX\RELDBUTL.EXE C:\users\public\documents\RELDBUTL.INI
Note: C:\RELDBXX indicates the Relativity installation path.
Parent topic: Distributing Updated Catalogs
Related concepts
Rules File for Merging a Catalog
Sample Rules File


Rules File for Merging a Catalog

When distributing updated catalogs, there must be an accompanying rules file for the merge process. The rules file is an INI format file having the name RELDBUTL.INI. It can contain sections for changed file and table definition names. The minimum entries in the rules file are the names of the two data sources to merge. The format for entries is the following:

PARAMETER=value

[CATALOG] section specifies the data source names as well as the user IDs and passwords that are to be merged. The parameters are:

OLD
The customer's existing data source.
OLDUID
The customer's existing user ID.
OLDPWD
The customer's existing password.
NEW
The updated catalog's new data source.
NEWUID
The customer's new user ID.
NEWPWD
The customer's new password.

[FD] section provides a method of explaining file definition name changes. There should be an entry in this section for every FD name that has changed. The format is oldname=newname. There is no need to list unchanged file definitions; they are merged automatically.

[TABLE] section provides a method of explaining table name changes. There should be an entry in this section for every table name that has changed. The format is oldname=newname. There is no need to list unchanged table names as they are merged automatically.

[COLUMNS] section provides a method of explaining column name changes. There should be an entry in this section for every column name that has changed. The format of this section header is the keyword COLUMNS followed by a colon followed by the old name of the table. The format of the entries in the section is oldcolumn=newcolumn.

[CONNECT] section, which is optional, allows the new data source to be created as part of the merge process. The parameters are:

DESC
Can be any text that describes the data source.
CATALOG
The full access path to where the catalog will be located.
DSN
Data Source Name. This is the ODBC data source name for the new catalog.
DRIVER
The Relativity DBMS used for the new catalog.

[MESSAGES] section, which is optional, is provided to allow the Relativity Merge Utility to change the messages displayed on the screen as the merge is taking place. You may choose to provide any of these messages; you do not have to provide all. If a message is not found, the default will be used. The sample rules file (see link below) uses the defaults. The valid messages and when they are displayed are:

LOGON1
The message displayed while the Logon dialog box for the user's existing catalog is displayed.
LOGON2
The message displayed while the Logon dialog box for the new catalog is displayed. (One use for this may be to provide a new user ID and password if the DBA has changed.)
STATUS
The message displayed while the actual merge is running.
COMPLETE
The message displayed following a successful merge. (One use for this message may be to remind the user to remove any media, or to run the next step in a process.)
INCOMPLETE
The message displayed following an aborted merge process. (One use for this message may be how to proceed if errors were encountered during the merge.)
LOG
Creates a log file at the end of the merge process. The only entry in the log file is a complete or incomplete message. If you have specified COMPLETE and INCOMPLETE messages, those will be used. If not, the default for these messages will be used.

Here are the default messages that will be used if none are provided:

LOGON1
Please log on to your existing catalog.
LOGON2
Please log on to new catalog.
STATUS
This process may take some time.
COMPLETE
Relativity Merge Complete.
INCOMPLETE
Relativity Merge NOT Complete.
Parent topic: Distributing Updated Catalogs
Related concepts
Merging a Catalog
Sample Rules File


Sample Rules File

The following is an example of sample rules file:

C:\users\public\documents\RELDBUTL.INI
[CONNECT]
DESC=New Data Source
CATALOG=C:\MYDATA\MYCATALOG.RCG
DSN=MYDATA
DRIVER=Relativity for RM (*.rcg)
[CATALOG]
OLD=JMB
NEW=JMBTEST
[FD]
[TABLE]
[MESSAGES]
LOGON1=Please log on to your existing data source.
LOGON2=Please log on to new data source, user=Mike, password=Mike.
STATUS=Processing, please wait...
COMPLETE=Merge Complete. Remove media.
INCOMPLETE=Relativity Merge NOT Complete. Please call for support.
Parent topic: Distributing Updated Catalogs
Related concepts
Merging a Catalog
Rules File for Merging a Catalog


Defining Security for Relativity Databases

  • Securing Relativity Databases
    Relativity provides security that protects data in the database tables against unauthorized disclosure, alteration, or destruction.
  • Catalog Ownership
    Relativity catalogs can only be designed by a catalog owner. Furthermore, only the owner initially has the ability to create groups and users, and assign privileges to those groups.
  • Defining Groups and Users
    Define the groups and users to which you can grant privileges.
  • Defining Group Privileges
    Define privileges to groups of users to determine their access to the tables defined within a Relativity database.
Parent topic: Micro Focus Relativity Designer for Windows


Securing Relativity Databases

Relativity provides security that protects data in the database tables against unauthorized disclosure, alteration, or destruction.

For security purposes, a unit of data (or data object) ranges from an entire database to a specific column within a table of the database. A given user has different access privileges on different units of data. Access privileges (or privileges, for short) are the mechanism that provides data security for a Relativity database.

To provide data security, the person responsible for designing the databases must:

  1. Define groups and users. The first step in effective database administration is to design and establish the group structure; that is, the users and groups of users who are authorized access to the tables within the database. Groups and users are the basis for establishing such security. An individual user is identified by a user name. A group of users is identified by a group name. Each user name and group name within a Relativity database must be unique.
  2. Define catalog ownership. Catalog ownership is a role given to a particular group. Catalog owners are the only users that can log on to the database's catalog in Relativity Designer to design the relational tables, and grant access and privileges to those tables to other groups of users. Ownership is assigned to the first group defined, but it can be changed to another group, if required.
  3. Define group privileges. Catalog owners can grant specific permissions for groups, allowing other groups to access and update table data. This is similar to the GRANT/REVOKE facilities in other relational database management systems.

    In a Relativity catalog, privileges are assigned to a group of users. All users within a group inherit the privileges of the group. Not all groups associated with the Relativity database need access to all the data in the database. A group of users is given privileges only to the data that is necessary for the group to carry out its work.

    When granting privileges, it may be helpful to think of them in terms of a hierarchy, with the group that is the owner of the catalog having the highest level permissions, the group with administrator privileges having the next level of permissions, and a user group having the lowest level permission (the ability to access only one or more tables or columns).

Note: Relativity supports a set of stored procedures, identified with the prefix, DBA-, only if the user is the owner or a database administrator of the Relativity catalog. The DBA stored procedures deal with table definitions, table connections, and file names. All of the stored procedures are ODBC driver-specific. For more information, see Stored Procedures in the For Advanced Users | Relativity-Specific topic in the Relativity DBMS Help file.
Parent topic: Defining Security for Relativity Databases
Related reference
Catalog Ownership
Defining Groups and Users
Defining Group Privileges


Catalog Ownership

Relativity catalogs have an ownership property that restricts catalog design to only those users assigned to the owner group.

By default, a catalog has no owner when it is first created, which means that anyone can log on and make changes. However, as soon as the first group is added to the catalog, it automatically becomes the owner of that catalog, and only users assigned to that group can log on to the Relativity Designer and design the catalog.

You can configure Relativity Designer to check that a catalog has an owner when you log on (Tools > Options > General > Require Catalog have Owner Group), and if it does not, you are prompted to add the group that will become the owner group.

Once a catalog has an owner group, all of its users are automatically granted all privileges for the database, and can perform every operation that supports a Relativity database. They can perform such tasks as:

  • Creating groups of users for this database.
  • Granting other privileges to the group executing the Relativity Designer.
  • Granting another group the authority to grant specified privileges to other groups.
  • Revoking privileges from a group.
  • Change the Owner of Catalog
Parent topic: Defining Security for Relativity Databases
Related reference
Securing Relativity Databases
Defining Groups and Users
Defining Group Privileges


Change the Owner of Catalog

Use these steps to change the owning group of the catalog.

  1. In the Catalog Explorer pane, right-click the User Groups and Users node and select Change Owner.

    The Change Owner Group dialog box is displayed, and shows the current owning group.

  2. Click the Group Name field and select a group.
  3. In the Password field, if one exists, type the password for the group. An asterisk (*) character is displayed for each character entered. If the group has no password, leave this field blank.
  4. Click Apply to save the changes.

    The new owning group now has all privileges for the database, and the previous owning group cannot log on to the Relativity Designer, which is why a change of owner closes the connection to the catalog; reconnect with credentials for the new owning group.

Parent topic: Catalog Ownership
Related reference
Defining Groups and Users


Defining Groups and Users

To access or configure data within a Relativity database, you need to belong to a group that has been granted privileges to perform that function or access that data. Groups and users for a Relativity database are configured using the User Groups and Users section within the Catalog Explorer pane.

There is also an additional group, the <PUBLIC> group, that is default for all catalogs. The <PUBLIC> group is only applicable to the table access privilege, but is a quick way to grant table or column access to all users of a database; see Enable Public Table Access Privileges.

For detailed information on defining groups and users, choose from the following topics:

  • Add a User Group to the Catalog
  • Add a User to a Group
  • Delete a Group from the Catalog
  • Delete a User from a Group
  • Change a Group Name and Password
  • Change a User Name and Password
Parent topic: Defining Security for Relativity Databases
Related tasks
Change the Owner of Catalog
Related reference
Securing Relativity Databases
Catalog Ownership
Defining Group Privileges
Enable Public Table Access Privileges


Add a User Group to the Catalog

If this is the first group to be added, it is automatically set as the owner group of the catalog and has all privileges granted automatically; you can only set group privileges on subsequent groups added.

  1. In the Catalog Explorer pane, right-click the User Groups and Users node, then click New Group.

    The Add New Group dialog box is displayed.

  2. In the Group Name field, type the name of the group to be added to the catalog.
  3. In the Password field, type a password for the group. An asterisk (*) character is displayed for each character entered. This field is optional.
  4. If you entered a password, in the Verify Password box, type the password for a second time. An asterisk (*) character is displayed for each character entered.
  5. (Optional) Select the Expires On tick-box, then click [image] and use the calendar to enter an expiry date.

    Access to any of the catalog's tables, for any user within this group, will be refused after the stated expiry date.

  6. Click Add to add the new group.

    The new group is now displayed in the User Groups and Users node. You can now add one or more users to the group.

Parent topic: Defining Groups and Users
Related information
Add a User to a Group
Delete a Group from the Catalog
Delete a User from a Group
Change a Group Name and Password
Change a User Name and Password


Add a User to a Group

  1. In the Catalog Explorer pane, double-click the User Groups and Users node.
  2. Right-click the required group, and select New User.

    The Add User to <group> dialog box is displayed.

  3. In the New User Name field, type the name of the user to be added to the selected group.
  4. In the Password field, type a password for the user. An asterisk (*) character is displayed for each character entered. This field is optional.
  5. If you entered a password, in the Verify Password box, type the password for a second time. An asterisk (*) character is displayed for each character entered.
  6. (Optional) Select the Expires On tick-box, then click [image] and use the calendar to enter an expiry date for the user.

    Access to any of the catalog's tables will be refused for this user after the stated expiry date.

  7. Click Add to add the new user to the group.

    The new user is now displayed in the User Groups and Users node, underneath the appropriate group.

Parent topic: Defining Groups and Users
Related information
Add a User Group to the Catalog
Delete a Group from the Catalog
Delete a User from a Group
Change a Group Name and Password
Change a User Name and Password


Delete a Group from the Catalog

Note: You cannot delete the Owner group.
  1. In the Catalog Explorer pane, double-click the User Groups and Users node.
  2. Right-click the required group, and select Delete Group.

    A confirmation box is displayed. If users still exist in the group, they will also be deleted.

  3. Click Yes to confirm.

    The group is deleted.

Parent topic: Defining Groups and Users
Related information
Add a User Group to the Catalog
Add a User to a Group
Delete a User from a Group
Change a Group Name and Password
Change a User Name and Password


Delete a User from a Group

  1. In the Catalog Explorer pane, double-click the User Groups and Users node.
  2. Expand the group that the user belongs to, and then select the user entry.
  3. Right-click the required user, and select Delete.

    A confirmation box is displayed.

  4. Click Yes to confirm.

    The user is deleted from the group.

Parent topic: Defining Groups and Users
Related information
Add a User Group to the Catalog
Add a User to a Group
Delete a Group from the Catalog
Change a Group Name and Password
Change a User Name and Password


Change a Group Name and Password

  1. In the Catalog Explorer pane, double-click the User Groups and Users node.
  2. Right-click the required group, and select Rename Group.

    The Rename Group dialog box is displayed.

  3. In the Group Name field, edit the current name.
  4. In the Password field, type a password for the group. An asterisk (*) character is displayed for each character entered. This field is optional.
  5. In the Verify Password box, type the password for a second time. An asterisk (*) character is displayed for each character entered.
  6. Click Save.

    The password is updated.

Tip: To remove a password from the group, click Save without entering a new password in either the Password or Verify Password fields.
Parent topic: Defining Groups and Users
Related information
Add a User Group to the Catalog
Add a User to a Group
Delete a Group from the Catalog
Delete a User from a Group
Change a User Name and Password


Change a User Name and Password

  1. In the Catalog Explorer pane, double-click the User Groups and Users node.
  2. Expand the required group to display the users.
  3. Right-click the user, and select Rename User.

    The Rename User dialog box is displayed.

  4. In the User Name field, edit the current name.
  5. In the Password field, type a password for the group. An asterisk (*) character is displayed for each character entered. This field is optional.
  6. In the Verify Password box, type the password for a second time. An asterisk (*) character is displayed for each character entered.
  7. Click Save.

    The password is updated.

Tip: To remove a password from the user, click Save without entering a new password in either the Password or Verify Password fields.
Parent topic: Defining Groups and Users
Related information
Add a User Group to the Catalog
Add a User to a Group
Delete a Group from the Catalog
Delete a User from a Group
Change a Group Name and Password


Defining Group Privileges

Groups are assigned privileges to a Relativity database with the appropriate actions on the Privileges tab. The granting of a privilege to a group of users provides a mechanism to protect data in a database. Instead of having access to all the data in a database, a granted privilege restricts the user's access only to the data needed to carry out the user's work.

Privileges are assigned by the catalog owner, to other groups; therefore, you must add at least one additional group (that is not the catalog owner) to be able to set privileges.

There is also an additional group, the <PUBLIC> group that is only applicable to the table access privilege, but is a quick way to grant table or column access to all users of a database; see Enable Public Table Access Privileges.

When assigning privileges, there are three choices for each pairing of a group and a privilege, table, or column:

  • Granted. The group has the selected privilege, but cannot grant it to other groups.
  • With Grant. The group has the selected privilege and can grant that privilege to other groups.
  • Not Granted. The group does not have the selected privilege. This is implied by the absence of a selection.

To access a group's privileges, in the Catalog Explorer, expand User Groups and Users, and then double-click the required group. Note, you cannot access or edit the privileges for the Owner group as that group automatically has maximum privileges assigned.

The group's privileges appear in the middle pane, and the group's properties are displayed in the right-hand pane.

For detailed information on enabling privileges, choose from the following topics:

  • Administrator Privileges
  • Create Users Privilege
  • Create Tables Privilege
  • Table Access Privileges
  • Column Access Privileges
  • Enable Public Table Access Privileges
Parent topic: Defining Security for Relativity Databases
Related reference
Securing Relativity Databases
Catalog Ownership
Defining Groups and Users


Administrator Privileges

The four Administrator privileges available for a group all pertain to database administration operations:

  • Use Administrator. Enabling the Use Administrator privilege allows the group granted the privilege to use the Relativity DBA software on the specified catalog.
  • Create Group. Enabling the Create Group privilege permits the group granted the privilege to add new database groups to the catalog.
  • Date Constants. Enabling the Date Constants privilege allows the group granted the privilege to change the existing (default) values for the date constants of the database in the catalog. These date constants include 'Days' Base Date, 'YYYY' Base Year, 'YY' Base Year, 'YY' Century Cutoff, and configurable date formats.
  • Reports. Enabling the Reports privilege permits the group granted the privilege to create and use reports for information in the catalog. Note that the Reports functionality is currently unavailable.
Note: The Administrator privileges cannot be assigned to the <PUBLIC> group.
  • Enable Administrator Privileges
Parent topic: Defining Group Privileges


Enable Administrator Privileges

  1. In the Catalog Explorer pane, expand the User Groups and Users node.
  2. Double-click the group for which privileges are to be assigned.

    The Privileges tab for the selected group is displayed.

  3. Select the Admin tab.

    The Use Administrator, Create Group, Reports, and Date Constants privileges are displayed. (Initially, a group has no Administrator privileges, so no privileges are selected.)

  4. Select the appropriate tick-boxes (Grant or With Grant) for each of the privileges, or leave the tick-boxes clear to not grant a privilege.
    Note: With Grant enables the group to also grant those selected privileges to other groups.
  5. Click Save to Catalog to save the changes; alternatively, click Revert to revert back to the last available saved privileges.
Restriction: The Reports functionality is not yet available.
Parent topic: Administrator Privileges


Create Users Privilege

Enabling the Create Users privilege allows the group granted the privilege to add new users to a specific database group in the catalog and to delete existing users from a specific group.

Because the Create Users privilege is granted only for specific groups, it is possible to have specialized administrators of the database. For example, there could be a SalesAdmin group that is granted the privilege to create new users only for the Sales group. The director of sales would then be made a member of the SalesAdmin group so that the director could add users to or delete users from the Sales group without having to request such changes from the main administrator.

Note: The Create Users privilege cannot be assigned to the <PUBLIC> group.
  • Enable the Create Users Privilege
Parent topic: Defining Group Privileges


Enable the Create Users Privilege

  1. In the Catalog Explorer pane, expand the User Groups and Users node.
  2. Double-click any group within the node.

    The Privileges tab for the selected group is displayed.

  3. Select the Users tab.

    The database groups defined for the current catalog (except the owner group) are displayed in the Group Name column.

  4. For each group, select the appropriate tick-boxes (Create Users or With Grant) for each of the groups, or leave the tick-boxes clear so that the group is unable to create users.
    Note: Selecting these options allow the group selected in step 2 the ability to create users in the other groups in the database (shown in step 3). The With Grant option enables group members to also grant or revoke the privilege of creating users for other groups.
  5. Click Save to Catalog to save the changes; alternatively, click Revert to revert back to the last available saved privileges.
Parent topic: Create Users Privilege


Create Tables Privilege

Enabling the Create Tables privilege allows the group granted the privilege to add, edit, and delete table instances between the Relativity table definitions and the physical COBOL data files.

Note: The Create Tables privilege cannot be assigned to the <PUBLIC> group.
  • Enable the Create Tables Privilege
Parent topic: Defining Group Privileges


Enable the Create Tables Privilege

  1. In the Catalog Explorer pane, expand the User Groups and Users node.
  2. Double-click the group for which privileges are to be assigned.

    The Privileges tab for the selected group is displayed.

  3. Select the Tables tab.

    The table definitions for the current database are displayed:

  4. For each table, select the appropriate tick-boxes (Create Table or With Grant), or leave the tick-boxes clear so that the group is unable to create table instances.
    Note: Create Table enables members of the group selected in step 2 to add, edit, and delete table instances between the Relativity table definition and the physical COBOL data file, and With Grant enables group members to also grant or revoke the privilege for other groups.
  5. Click Save to Catalog to save the changes; alternatively, click Revert to revert back to the last available saved privileges.
Parent topic: Create Tables Privilege


Table Access Privileges

In a Relativity database, a given group may have access rights or privileges to a table instance in order to perform SQL operations such as SELECT, INSERT, UPDATE, or DELETE. Table privileges can apply to the whole table, or to each column of a table. If the owner wants to grant access to only specific columns of a table, then use Column privileges, but to grant table-wide privileges select one or more of the following:

  • All - enabling the All privilege allows all table privileges to the group
  • Select - enabling the Select privilege allows the group granted the privilege to access all of the columns of a specified table, including any columns added to that table later.
  • Insert - enabling the Insert privilege permits the group granted the privilege to insert into all columns of a specified table, including any columns added to that table later.
  • Update - enabling the Update privilege allows the group granted the privilege to update all columns of a specified table, including any columns added to that table later.
  • Refer - enabling the Refer privilege allows the group granted the privilege to reference all columns of a specified table in integrity constraints, including all columns added to that table later. Integrity constraints may be specified in CREATE TABLE statements and could be used in a way that would obtain information about columns in another table for which a user would not otherwise have privileges.
  • Delete - enabling the Delete privilege permits the group granted the privilege to delete a row from a specified table. Since deleting a row of a relational table is equivalent to deleting all columns of that row, this privilege exists only as a Table privilege; there is no corresponding Column Delete privilege.

Each table privilege also has a with Grant privilege (the w/G tick-box), which enables the group to also grant that particular privilege to other groups when using Relativity DBA.

  • Enable Table Access Privileges
Parent topic: Defining Group Privileges
Related tasks
Enable Column Access Privileges
Related reference
Column Access Privileges
Privileges Options


Enable Table Access Privileges

  1. In the Catalog Explorer pane, expand the User Groups and Users node.
  2. Double-click the group for which privileges are to be assigned.

    The Privileges tab for the selected group is displayed.

  3. Select the Tables tab.

    The table instances for the current database are displayed:

  4. For each table instance, select the appropriate tick-boxes, or leave the tick-boxes clear so that the group selected in step 2 is unable to perform the privilege on the particular table instance.
    Note: w/G (With Grant) enables group members to also grant or revoke the privilege for other groups.
  5. Click Save to Catalog to save the changes; alternatively, click Revert to revert back to the last available saved privileges.
Note: These options grant privileges for the entire table; to grant privileges for individual columns, click Columns and set the privileges per column.
Parent topic: Table Access Privileges


Column Access Privileges

In a Relativity database, a given group may have access rights or privileges to a column within a table. In order to perform an SQL operation, such as SELECT, INSERT, or UPDATE on a column within a table, the user must belong to a group granted the corresponding privilege for the columns affected by the operation.

The following Column privileges are available for a group:

  • Select - enabling the Select privilege permits the group granted the privilege to access specified columns of a specified table.
  • Insert - enabling the Insert privilege allows the group granted the privilege to insert into specified columns of a specified table.
  • Update - enabling the Update privilege permits the group granted the privilege to update specified columns of a specified table.
  • Refer - enabling the Refer privilege allows the group granted the privilege to reference specified columns of a specified table in integrity constraints. Integrity constraints may be specified in CREATE TABLE statements and could be used in a way that would obtain information about columns in another table for which a user would not otherwise have privileges.
Note: There is no Column Delete privilege because the SQL DELETE statement deletes a row of a table, thus requiring delete privilege on all columns. You must use the Table Delete privilege described in Table Privileges to grant the privilege to delete rows of a table.
  • Enable Column Access Privileges
Parent topic: Defining Group Privileges
Related tasks
Enable Column Access Privileges
Related reference
Table Access Privileges
Privileges Options


Enable Column Access Privileges

  1. In the Catalog Explorer pane, expand the User Groups and Users node.
  2. Double-click the group for which privileges are to be assigned.

    The Privileges tab for the selected group is displayed.

  3. Select the Tables Access tab.

    The table instances for the current database are displayed

  4. Click Columns to the right of the appropriate table instance.

    A further set of privileges is displayed, one set for each column in the table instance. If any of the privileges are already granted at the table level, Revoke (and not Grant) is displayed, and the result of selecting such a column tick-box will revoke that privilege.

  5. For each column, select the appropriate tick-boxes to grant or revoke privileges for that particular column.
  6. Click Close.
  7. Click Save to Catalog to save the changes; alternatively, click Revert to revert back to the last available saved privileges.
Parent topic: Column Access Privileges
Related reference
Column Access Privileges
Table Access Privileges
Privileges Options


Enable Public Table Access Privileges

  1. In the Catalog Explorer pane, right-click the User Groups and Users node, then select Public Privileges.

    The Public Privileges tab is displayed, showing only the Table Access tab.

  2. For each table instance, select the appropriate tick-boxes, or leave the tick-boxes clear so that the privilege is governed by the individual group settings.

    Instead of granting access to the whole table, you can grant access to specific columns only.

  3. Click Columns to the right of the appropriate table, and then select the required column privileges.
  4. Click Save to Catalog to save the changes; alternatively, click Revert to revert back to the last available saved privileges.
Parent topic: Defining Group Privileges


Reference Information

  • Database Logon Window
    The Database Logon dialog box appears when you start the Relativity Designer that contains one or more databases.
  • File Menu Commands
    The commands displayed on the File menu of the Relativity Designer window depend on whether a data source has been opened and selected for processing.
  • Tools Menu Commands
    The Tools menu of the Relativity Designer window contains a wide range of options for all facets of Relativity Designer.
  • Help Menu Commands
    The Help menu of the Relativity Designer window contains links to version details, and the Help files associated with Relativity Designer.
  • Pattern Matching
    The adding, editing, and deleting of various strings used in Relativity is controlled by the matching of patterns.
  • SQL Reserved Words
    There are a number of SQL reserved words that you are prevented from using for your column and table names.
Parent topic: Micro Focus Relativity Designer for Windows


Database Logon Window

The Database Logon dialog box appears when you start the Relativity Designer that contains one or more databases.

It enables you to connect to the last database catalog that was accessed in your previous session. If you want to log on to a different database, you can click Cancel, where you are taken to the Relativity Designer main window, and if configured to display, the Start page.

The Database Logon dialog box contains the following options:

Option | Description
UserId | Enter user the user name of a user that belongs to one of the groups associated with the database catalog.
Password | Enter the password that corresponds to the user name entered.
Login | Click Login to log on to the last database accessed, after entering valid logon credentials
Cancel | Click Cancel to cancel logon to the last database accessed. The main Relativity Designer window is then displayed, enabling you to log on to other databases.
Parent topic: Reference Information


File Menu Commands

The commands displayed on the File menu of the Relativity Designer window depend on whether a data source has been opened and selected for processing.
Option | Description
Connect to <data-source> | Connects to the last database you were logged on to. Enter valid logon credentials when prompted, to load the catalog.
Connect to Existing Data Source | Displays the Open Existing Data Source dialog box, which enables you to select an existing data source. Enter valid logon credentials when prompted, to load the catalog.
Create New Data Source | Displays the Create new Data Source dialog box, which enables you to add a new Relativity data source. For more information, see Setting up a New Data Source.
Close Current Data Source | Closes the current data source, as identified in the Current DSN box in the top-right of the Relativity Designer window. Any tab that is open that contains data source information is also closed.
Import COBOL FDs | Displays the COBOL FD Importer tab, which enables you to import COBOL file descriptions into the catalog. See Importing COBOL Data File Definitions.
Exit | Terminates the execution of the Relativity Designer.
Parent topic: Reference Information


Tools Menu Commands

The Tools menu of the Relativity Designer window contains the following commands.

Option | Description
Start Page | Displays the Start Page tab, which displays an introduction to Relativity, and quick links to some common tasks you may require. You can configure this page to display automatically when you open Relativity Designer; see the Options > General tab.
Options | Display the Options tab, which is a collection of further tabs covering various preferences for the Relativity Designer. These settings become the default settings for the appropriate options. See Setting Options.
Custom Data Types | Displays the Custom Data Types tab, which enables you to define custom SQL data types. See Defining User Data Types.
Date Constants Displays the Date Constants tab, which enables you to change the values of the following:
  • The four date constants, 'Days' Base Date, 'YYYY' Base Year, 'YY' Century Cutoff, and 'YY' Base Year.
  • The structure of two date constants ('YY' Dates and 'YYYY' Dates).
For more details, see Defining Date Constants.
Character Sets | Displays the Character Sets tab, which lists the character sets in use in a Relativity data source. This tab also allows you to add both standard and nonstandard character sets to the current Relativity data source, and modify the character set associated with file definitions. See Maintaining Character Sets and Defining Nonstandard Character Sets.
Nullable Column Report | Displays a list of all columns within the catalog that are marked as nullable. This helps when you are creating writable tables. See Using the Nullable Columns Report.
Merge from Another Relativity Data Source | Displays the Data Source Importer tab (once you have successfully logged on to another database), which enables you to import file, table, and user data type definition objects from another database catalog. See Importing Definitions from Another Relativity Catalog.
Update FDs from Source | Runs the COBOL FD Importer, which enables you to update the file definitions in a catalog if the source definitions have changed.
Relativity Admin Applet | Runs the Relativity Admin utility, which enables you to set some system-wide options.
ODBC Control Panel | Display the ODBC Data Source Administrator (32-bit) dialog box, where you can configure Relativity data sources.
ODBC Control Panel (64-bit) | Display the ODBC Data Source Administrator (64-bit) dialog box, where you can configure Relativity data sources.
Theme | Enables you to pick from a number of themes that can be applied to the look of the Relativity Designer window.
Parent topic: Reference Information
Related reference
Defining Date Constants


Help Menu Commands

The Help menu of the Relativity Designer window contains the following commands.

Option | Description
Contents | Launches the Relativity Designer Help file.
DBMS Help File | Launches the Relativity Data Manager (DBMS) Help file.
About | Display the About dialog box, which includes the version number, copyright specifications, catalog version number, and licensing information of the Relativity Designer product that is currently running.
Parent topic: Reference Information


Pattern Matching

The adding, editing, and deleting of various strings used in Relativity is controlled by the matching of patterns.

Pattern matching provides a tool for string comparison between a pattern and a table name, a path name, a file label (if file labels are in effect), or a column name. These are collectively called "searched strings" in the examples provided.

In the Relativity Designer, pattern matching is used for the following purposes:

  • To replace selected characters in all column names defined by default in the FD form.
  • To replace or restore selected characters in table names during COBOL FD merge operations.

Relativity pattern matching uses the concept of regular expressions. Regular expressions extend the conventional search criteria.

To view a table that shows the list of character(s) in a pattern and what they match in the searched string, refer to Regular Expression Syntax Used in Pattern Matching.

For examples of pattern matching, refer to Pattern Matching Examples.

  • Regular Expression Syntax Used in Pattern Matching
  • Pattern Matching Examples
Parent topic: Reference Information
Related tasks
Editing Default Column Names
Related reference
Defining Default Column Names


Regular Expression Syntax Used in Pattern Matching

A regular expression is a pattern of text that consists of ordinary characters, for example, letters a through z, and special characters.
Character(s) | Matches in searched string
pattern | Matches pattern anywhere in the name.
\ | Marks the next character as either a special character, a literal, a back reference, or an octal escape. For example, 'd' matches the character "d". ' \d' matches a digit character. The sequence '\\' matches "\" and "\(" matches "(".
. | Matches any single character.
^ | Matches the position at the beginning of the searched string. For example ^CF matches any string starting 'CF'.
$ | Matches the position at the end of the searched string. For example EZ$ matches any string ending 'EZ'.
? | Matches the preceding subexpression zero or one time. For example, "mast(er)?" matches "mast" or "master". Also, see below for additional uses of '?'.
* | Matches the preceding subexpression zero or more times. For example, zo* matches "z" and "zoo".
+ | Matches the preceding subexpression one or more times. For example, 'zo+' matches "zo" and zoo", but not "z".
{n} | Matches exactly n times, where n is a nonnegative integer. For example, 'o{2}' matches the two o's in "zoo", but not the o in "zero".
{n,} | Matches at least n times, where n is a nonnegative integer. For example, 'o{2,}' matches all the o's in "zooooom" but not the o in "zero".
{n,m} | Matches at least n times and at most m times, where n and m are nonnegative integers ( n <= m). For example, 'o{2,4}' matches the first four o's in "zooooom", but not the o in "zero".
? | When '?' immediately follows any of the qualifiers (*, +, ?, {n}, {n,}, {n,m}), the matching pattern is non-greedy. While the default pattern matching is to match as much of the searched string as possible, a non-greedy pattern matches as little of the searched string as possible. For example, 'o+?' matches a single o in "zooom", while 'o+' matches all the o's.
(pattern) | Matches pattern as a subexpression and remembers the match. The remembered match can be used in a following back reference (described below) or in the replacement string of a search and replace operation. To match the parentheses characters ( and ), use '\(' and '\)'.
x|y | Matches either x or y. For example, 'MAST(ER|FILE)' matches either "MASTER" or "MASTFILE".
[charlist] | Matches any single character in charlist. For example, '[aeiou]' matches the e in "Relativity".
[^charlist] | Matches any single character not in charlist. For example, '[^aeiou]' matches the R in "Relativity".
[a-z] | Matches any single character in the specified character range. For example, '[a-z]' matches any lowercase alphabetic character in the range "a" through "z", inclusive.
[^m-z] | Matches any single character not in the specified character range. For example, '[^m-z]' matches any character except those in the range "m" through "z", inclusive.
\b | Matches a word boundary (the position between a word and a space). For example, "le\b" matches the "le" of "file" in the searched string "lengthy file name", not the "le" in "lengthy".
\B | Matches a non-word boundary. For example, "le\B" matches the "le" of "lengthy" in the searched string "lengthy file name", not the "le" in "file".
\d | Matches a digit character (equivalent to [0-9]).
\D | Matches a non-digit character (equivalent to [^0-9]).
\s | Matches a white space character.
\S | Matches a nonwhite space character.
\w | Matches any word character including underscore (equivalent to [A-Za-z0-9_]).
\W | Matches any non-word character (equivalent to [^A-Za-z0-9_]).
\num | Matches a back reference to a remembered match, where num is a positive integer. For example, '(.)\1' matches two consecutive identical characters.
Parent topic: Pattern Matching
Related reference
Pattern Matching Examples


Pattern Matching Examples

For more information on pattern matching, choose one of the following examples:

  • Pattern Match Anywhere
  • Pattern Match at Beginning
  • Pattern Match at Ending
  • Pattern Match Entire Searched String
  • Match the Beginning of a String
  • Match the Ending of a String
  • Pattern Match Any Single Character
  • Pattern Match Zero or More Characters
  • Pattern Match Any Single Digit
  • Pattern Match Special Character
  • Pattern Match Any Character in a Range
  • Pattern Match Any Character Outside a Range
  • Use Back References in Replacement Strings
Parent topic: Pattern Matching
Related reference
Regular Expression Syntax Used in Pattern Matching


Pattern Match Anywhere

The pattern of character-string matches with a similar character-string found anywhere in searched string. The following examples illustrate the matching of a pattern located anywhere in the searched string.
Pattern | Searched String | Result
SALES | BSALES | Match
SALES | SALESFIL | Match
SALES | JSALESFL | Match
SALES | SALEFL | No match
SALES | salesfil | No match
Parent topic: Pattern Matching Examples
Related reference
Pattern Match at Beginning
Pattern Match at Ending
Pattern Match Entire Searched String
Match the Beginning of a String
Match the Ending of a String
Pattern Match Any Single Character
Pattern Match Zero or More Characters
Pattern Match Any Single Digit
Pattern Match Special Character
Pattern Match Any Character in a Range
Pattern Match Any Character Outside a Range
Use Back References in Replacement Strings


Pattern Match at Beginning

The pattern of ^character-string matches with a similar character-string found at the beginning of the searched string. The following examples illustrate the matching of a pattern located at the beginning of the searched string.

Pattern | Searched String | Result
^SALES | BSALES | No match
^SALES | SALESFIL | Match
^SALES | JSALESFL | No match
^sales | SALESFL | No match
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Ending
Pattern Match Entire Searched String
Match the Beginning of a String
Match the Ending of a String
Pattern Match Any Single Character
Pattern Match Zero or More Characters
Pattern Match Any Single Digit
Pattern Match Special Character
Pattern Match Any Character in a Range
Pattern Match Any Character Outside a Range
Use Back References in Replacement Strings


Pattern Match at Ending

The pattern of character-string$ matches with a similar character-string found at the end of the searched string. The following examples illustrate the matching of a pattern located at the end of the searched string.

Pattern | Searched String | Result
SALES$ | BSALES | Match
SALES$ | SALESFIL | No match
SALESR | JSALESFL | No match
Sales$ | PRSALES | No match
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Beginning
Pattern Match Entire Searched String
Match the Beginning of a String
Match the Ending of a String
Pattern Match Any Single Character
Pattern Match Zero or More Characters
Pattern Match Any Single Digit
Pattern Match Special Character
Pattern Match Any Character in a Range
Pattern Match Any Character Outside a Range
Use Back References in Replacement Strings


Pattern Match Entire Searched String

The pattern of ^character-string$ matches with a similar character-string representing the entire searched string. The following examples illustrate the matching of a pattern equivalent to the entire searched string.

Pattern | Searched String | Result
^SALES$ | BSALES | No match
^SALES$ | SALESFIL | No match
^SALES$ | JSALESFL | No match
^SALES$ | SALES | Match
^sales$ | SALES | No match
^sales$ | sales | Match
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Beginning
Pattern Match at Ending
Match the Beginning of a String
Match the Ending of a String
Pattern Match Any Single Character
Pattern Match Zero or More Characters
Pattern Match Any Single Digit
Pattern Match Special Character
Pattern Match Any Character in a Range
Pattern Match Any Character Outside a Range
Use Back References in Replacement Strings


Match the Beginning of a String

The pattern of ^ represents a match at the beginning of the searched string. The following examples illustrate a match at the beginning of the searched string, allowing the insertion of the replacement string at the beginning of the searched string.

Pattern | Searched String | Replace with resort\
^ | salesfil | resort\salesfil
^ | orderfil | resort\orderfil
^ | cust2fil | resort\custfil
^ | CUST2FIL | resort\CUST2FIL
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Beginning
Pattern Match at Ending
Pattern Match Entire Searched String
Match the Ending of a String
Pattern Match Any Single Character
Pattern Match Zero or More Characters
Pattern Match Any Single Digit
Pattern Match Special Character
Pattern Match Any Character in a Range
Pattern Match Any Character Outside a Range
Use Back References in Replacement Strings


Match the Ending of a String

The pattern of $ represents a match at the end of the searched string. The following examples illustrate a match at the end of the searched string, allowing the insertion of the replacement string at the end of the searched string.

Pattern | Searched String | Replace with .INX
$ | SALESFIL | SALESFIL.INX
$ | ORDERFIL | ORDERFIL.INX
$ | CUST2FIL | CUST2FIL.INX
$ | salesfil | salesfil.INX
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Beginning
Pattern Match at Ending
Pattern Match Entire Searched String
Match the Beginning of a String
Pattern Match Any Single Character
Pattern Match Zero or More Characters
Pattern Match Any Single Digit
Pattern Match Special Character
Pattern Match Any Character in a Range
Pattern Match Any Character Outside a Range
Use Back References in Replacement Strings


Pattern Match Any Single Character

The pattern of . matches with any single character in the searched string. The following examples illustrate the matching a single character in the searched string.

Pattern | Searched String | Result
CUST.FIL | CUST1FIL | Match
CUST.FIL | CUST2FIL | Match
CUST.FIL | CUST45FIL | No match
PROD.FIL | PROD1FIL | Match
PROD.FIL | PROD2FIL | Match
PROD.FIL | PRODAAFIL | No match
Prod.fil | PROD3FIL | No match
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Beginning
Pattern Match at Ending
Pattern Match Entire Searched String
Match the Beginning of a String
Match the Ending of a String
Pattern Match Zero or More Characters
Pattern Match Any Single Digit
Pattern Match Special Character
Pattern Match Any Character in a Range
Pattern Match Any Character Outside a Range
Use Back References in Replacement Strings


Pattern Match Zero or More Characters

Use the * character after the . character to represent a match with zero to more characters in the searched string. The following examples illustrate the matching of patterns containing the asterisk (*) character.

Pattern | Searched String | Result
\budget\.* | \budget\salesfil | Match
\budget\.* | \designer\orderfil | No match
\designer\.* | \designer\cust2fil | Match
\designer\.* | \budget\cust2fil.dat | No match
\.*\orderfil | \budget\orderfil | Match
\.*\orderfil | \designer\prod2fil | No match
\.*\prod2fil | \prod2fil | No match
\budget\.* | \designer\salesfil | No match
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Beginning
Pattern Match at Ending
Pattern Match Entire Searched String
Match the Beginning of a String
Match the Ending of a String
Pattern Match Any Single Character
Pattern Match Any Single Digit
Pattern Match Special Character
Pattern Match Any Character in a Range
Pattern Match Any Character Outside a Range
Use Back References in Replacement Strings


Pattern Match Any Single Digit

The pattern of \d represents a match with any digit, 0 through 9, within the searched string. The following examples illustrate the matching of patterns containing \d.

Pattern | Searched String | Result
CUST\dFIL | CUST1FIL | Match
CUST\dFIL | CUST2FIL | Match
CUST\dFIL | CUSTAFIL | No match
CUSTFIL\d | CUSTFIL3 | Match
CUSTFIL\d | CUST1FIL | No match
Custfil\d | CUSTFIL9 | No match
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Beginning
Pattern Match at Ending
Pattern Match Entire Searched String
Match the Beginning of a String
Match the Ending of a String
Pattern Match Any Single Character
Pattern Match Zero or More Characters
Pattern Match Special Character
Pattern Match Any Character in a Range
Pattern Match Any Character Outside a Range
Use Back References in Replacement Strings


Pattern Match Special Character

When a special character, such as ? * or [ is preceded by a backslash (\), a match occurs if that special character is present in the indicated position of the searched string. The following examples illustrate the matching of patterns containing one of the special characters.

Pattern | Searched String | Result
CUST\*FIL | CUST*FIL | Match
CUST\*FIL | CUST2FIL | No match
Cust\*fil | CUST*FIL | No match
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Beginning
Pattern Match at Ending
Pattern Match Entire Searched String
Match the Beginning of a String
Match the Ending of a String
Pattern Match Any Single Character
Pattern Match Zero or More Characters
Pattern Match Any Single Digit
Pattern Match Any Character in a Range
Pattern Match Any Character Outside a Range
Use Back References in Replacement Strings


Pattern Match Any Character in a Range

The following examples illustrate the matching of patterns containing a range of characters. The pattern representation of a range consists of two characters separated by a hyphen and enclosed in brackets. For example, [1-5] indicates a range from '1' through '5'. The presence of any one of the characters in the range results in a match.

Pattern | Searched String | Result
CUST[1-5]FIL | CUST1FIL | Match
CUST[1-5]FIL | CUST4FIL | Match
CUST[1-5]FIL | CUST6FIL | No match
CUST1FL[A-Z] | CUST1FLB | Match
CUST1FL[A-Z] | CUST1FL2 | No match
CUST1FL[A-Z] | CUST1FLw | No match
CUST1FL[a-z] | CUST1FL4 | No match
CUST1FL[a-d0-9] | CUST1FL4 | Match
CUST1FL[A-D0-9] | CUST1FLL | No match
cust1fl[A-D0-9] | CUST1FLa | No match
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Beginning
Pattern Match at Ending
Pattern Match Entire Searched String
Match the Beginning of a String
Match the Ending of a String
Pattern Match Any Single Character
Pattern Match Zero or More Characters
Pattern Match Any Single Digit
Pattern Match Special Character
Pattern Match Any Character Outside a Range
Use Back References in Replacement Strings


Pattern Match Any Character Outside a Range

The following examples illustrate the matching of patterns outside a range of characters. The presence of the caret ( ^ ) character after the left bracket and before the range pattern indicates that a match occurs when a character is not within the specified range. For example, [^4-9] indicates any character outside the range of '4' through '9'.

Pattern | Searched String | Result
CUST[^4-9]FIL | CUST1FIL | Match
CUST[^4-9]FIL | CUST2FIL | Match
CUST[^4-9]FIL | CUST6FIL | No match
CUS1FL[^A-Z] | CUST1FLA | No match
CUST1FL[^a-z] | cust1fla | No match
CUS1FL[^A-Z] | CUST1FL4 | Match
CUST1FL[^A-Z] | CUST1FLX | No match
CUST1FL[^a-z] | CUST1FLB | Match
CUST1FL[^a-z] | CUST1FLc | No match
CUST1FL[^a-z] | CUST1FL3 | Match
CUST1FL[^4-9A-D] | CUST1FL4 | No match
CUST1FL[^4-9A-D] | CUST1FLW | Match
CUST1FL[^4-9A-D] | CUST1FLg | Match
cust1fl[^4-8a-e] | CUST1FLA | No match
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Beginning
Pattern Match at Ending
Pattern Match Entire Searched String
Match the Beginning of a String
Match the Ending of a String
Pattern Match Any Single Character
Pattern Match Zero or More Characters
Pattern Match Any Single Digit
Pattern Match Special Character
Pattern Match Any Character in a Range
Use Back References in Replacement Strings


Use Back References in Replacement Strings

The following examples illustrate the use of back references in a replacement string. Use the parentheses characters within the searched string to cause the subexpressions contained within the parentheses to be remembered. Subexpressions are numbered from left to right, starting with 1. Therefore, to refer to the leftmost remembered subexpression, use \1 in the replacement string, \2 for the second leftmost, and so forth.

Pattern | Searched String | Replacement | Result
(.+)(\d)(\.dat|\.DAT) | custfil5.dat | \1new\2\3 | Custfilenew5.dat
(First|1st)(.+)(Last|Final) | FirstThenLast | \3\2\1 | LastThenFirst
(First|1st)(.+)(Last|Final) | 1stThenFinal | \3\2\1 | FinalThen1st
Parent topic: Pattern Matching Examples
Related reference
Pattern Match Anywhere
Pattern Match at Beginning
Pattern Match at Ending
Pattern Match Entire Searched String
Match the Beginning of a String
Match the Ending of a String
Pattern Match Any Single Character
Pattern Match Zero or More Characters
Pattern Match Any Single Digit
Pattern Match Special Character
Pattern Match Any Character in a Range
Pattern Match Any Character Outside a Range


SQL Reserved Words

The following table contains a list of SQL reserved words that Relativity prevents you from using as a column name or table name when creating a new table. This is necessary because some ODBC-enabled applications can not handle these words as column or table names.

ADD

ALL

ALTER A

AND

ANY

AS

ASC

AVG

BETWEEN

BY

CASCADE

CHECK

COUNT

CREATE

CROSS

DEFAULT

DELETE

DESC

DISTINCT

DROP

EXISTS

FOREIGN

FROM

FULL

GRANT

GROUP

HAVING

IF

IN

INDEX

INNER

INSERT

INTO

IS

JOIN

KEY

LEFT

LIKE

MAX

MIN

NOT

NULL

ON

OR

ORDER

OUTER

PRIMARY

PUBLIC

REFERENCES

RESTRICT

REVOKE

SELECT

SET

SUM

SVBEGIN

SVEND

TABLE

TO

UNION

UNIQUE

UPDATE

USER

VALUES

VIEW

WHERE

Parent topic: Reference Information
Related reference
Creating and Editing Table Definitions


Glossary of Terms

The glossary terms used in Relativity are listed below alphabetically.
  • 88-level
  • catalog
  • Character Set
  • COBOL Name property
  • COBOL table
  • coinciding OCCURS
  • CombineDateTime
  • Comment property
  • Complement
  • ComputeCenturyDate
  • ComputeCenturyDateTime
  • ComputeDateTime
  • ComputeODO
  • ComputeTime
  • condition item
  • condition-name
  • conditional variable
  • Constrain property
  • custom data types
  • Custom Data Type property
  • data item
  • data source
  • data-name
  • database
  • date constants
  • Default Column Name property
  • Default Value property
  • entered numerics
  • domain
  • file label item
  • filter subexpression
  • filter
  • function item
  • function
  • Hexadecimal condition values
  • indexed file
  • internal function
  • ISAM file
  • IsNumeric
  • IsValidDate
  • item set
  • LogicalAnd
  • LogicalOr
  • Not Null property
  • null
  • Null Value property
  • nullable
  • ODBC data type
  • ODBC-enabled application
  • ODBC
  • ODO control item
  • Open Database Connectivity
  • property
  • RDBMS
  • record type filter
  • record type
  • Redefined By property
  • Redefines property
  • redundant data items
  • relational database management system
  • relational database
  • relational table
  • Relativity Data Client
  • Relativity Data Manager
  • Relativity Data Server
  • Relativity DBMS
  • repeating data item
  • SQL
  • Standard character sets
  • Structured Query Language
  • subscript item
  • subscripted data item
  • table
  • table definition
  • table filter
  • table name
  • transform
  • Transform property
  • Value property
Parent topic: Micro Focus Relativity Designer for Windows


88-level

A means of defining a condition-name in COBOL data description entries.

Parent topic: Glossary of Terms
Related reference
condition-name
Complement
internal function
conditional variable
Constrain property
data item
LogicalAnd
LogicalOr
record type
record type filter


catalog

The function of the Relativity catalog is similar to that of the "system catalog" in a relational database management system. It serves as a repository for information regarding the structure of relational tables as well as operational information required by runtime components of Relativity, such as the Query Optimizer.

Additionally, the Relativity catalog contains complete information regarding the physical COBOL data file structure (that is, the COBOL file definition, or FD information) and information produced by the database design process (Relativity Designer) that defines the association between COBOL data files and data elements, and the relational tables and their constituent columns. Together, all of this information allows Relativity to present the COBOL data files through the ODBC interface of an ODBC-enabled application as a Relativity database of well-normalized tables substantially independent of the original COBOL data file structure of the application. See also Relativity DBMS and relational table.

Parent topic: Glossary of Terms
Related reference
relational database management system
ODBC-enabled application
ODBC
Relativity DBMS
data source
database
date constants
data item
internal function
SQL
transform


Character Set

Typically, a character set is a collection of graphical symbols, called Glyphs, which are used to communicate in a language. In order to represent the Glyphs in a computer, they must be associated with a numerical value, called a Code Point, for storage. In modern computers, the Code Points are stored in individual, 8-bit bytes of memory allowing 256 Glyphs to be represented. Relativity uses the term "character set" to refer to Glyphs and their associated Code Points.

On IBM PCs, the term "Code Page" is commonly used to describe this mapping of Glyphs to Code Points. However, on UNIX-based machines, it is more common to use the ISO 8859 standard to describe this mapping. Relativity provides character sets for both of these standards.

Relativity uses the character set of each file in order to interpret the Code Points stored within it. For example, if your data is in English and resides on Windows or DOS, selecting the character set for Code Page 437 would be appropriate. If your data is in English and resides on UNIX, the character set for ISO 8859-1 (otherwise known as Latin 1) would be appropriate.

Parent topic: Glossary of Terms


COBOL Name property

The COBOL Name property is the name of the FD entry and the data description entries for each record in the COBOL data file. The following items are displayed as the COBOL Name properties for data items in the FD form.

  • FD level indicator followed by a COBOL data filename.
  • Level-number 01 followed by a COBOL record-name.
  • Level-number 02 and above followed by the COBOL data-name of a group data item or elementary data item.
  • Function items defined by Func: followed by the name of the internal function.
  • A subscript item defined by SUBSCRIPT OF followed by the name of the item of which it is subscript.

Indentation of the abbreviated data descriptions gives a visual representation of the hierarchical structure of the data items contained in the record.

Parent topic: Glossary of Terms


COBOL table

A COBOL group or elementary data item described with the OCCURS clause. Contrast with relational table. See also table and repeating data item.

Parent topic: Glossary of Terms
Related reference
data item
repeating data item
table
relational table
database
subscripted data item
subscript item
table filter


coinciding OCCURS

Two or more separate OCCURS clauses in a record description entry that each specify the same number of occurrences and where the COBOL tables created by the OCCURS clauses can be thought of as really being a single COBOL table accessed by a single subscript item.

Parent topic: Glossary of Terms
Related reference
subscript item
table


CombineDateTime

An internal function that allows two data items to be combined into a single date/time stamp value. The first argument should be a date data item. The second argument should be a time data item.

The YYYYMMDDHHMMS transform may be applied to resulting data item.

Parent topic: Glossary of Terms
Related reference
data item
internal function
transform


Comment property

In the FD form, the Comment property contains comments pertaining to the data item defined by this row in the FD form. The comment is changed by clicking in the grid cell. See Specifying Comments for more information.

This property is totally owned by the catalog developer for use in the Relativity Designer. It is a good place to maintain a user-friendly definition of the data item. Another use of this property might be to discuss the uses of a data item that may not be obvious.

Parent topic: Glossary of Terms
Related reference
Specifying Comments


Complement

An internal function that performs an arithmetic complement on a numeric data item. The first argument is the data item to be complemented; the second argument is an 88-level condition-name. If the 88-level condition-name value is false, the arithmetic complement is not performed.

Parent topic: Glossary of Terms
Related reference
88-level
condition-name
internal function


ComputeCenturyDate

The ComputeCenturyDate internal function computes a date from data items and/or constants containing the century, the year of the century, the month, and the day of the month or year. When a constant zero is supplied for the month, ComputeCenturyDate computes a date from data items and/or constants containing the year and the days of the year.

The YYYYMMDD transform may be applied to resulting data item.

Parent topic: Glossary of Terms
Related reference
data item
internal function
transform


ComputeCenturyDateTime

The ComputeCenturyDateTime internal function computes a date and time data item from data items and/or constants containing the century, the year, the month, the day of the month or year and optional data items or constants containing the hour or the day, the minute of the hour, the second of the minute, and the hundredth of the second.

The YYYYMMDDHHMMSShh transform may be applied to the resulting data item.

Parent topic: Glossary of Terms
Related reference
data item
internal function
transform


ComputeDateTime

An internal function that computes a date and time data item from data items and/or constants containing the year, the month, the day of the month or year and optional data items or constants containing the hour or the day, the minute of the hour, the second of the minute, and the hundredth of the second.

The YYYYMMDDHHMMSShh transform may be applied to the resulting data item.

Parent topic: Glossary of Terms
Related reference
data item
internal function
transform


ComputeODO

An internal function that computes an occurrence count from the record length, the record offset of the (single) argument, and the length and span of the argument. The argument must be a repeating data item at the end of the record.

Parent topic: Glossary of Terms
Related reference
internal function
repeating data item


ComputeTime

An internal function that computes a time data item from data items and/or constants containing the hour of the day, the second of the minute, and the hundredth of the second.

The HHMMSShh transform may be applied to the resulting data item.

Parent topic: Glossary of Terms
Related reference
data item
internal function
transform


condition item

A named subset of values that a conditional variable may assume. The condition item is true when the conditional variable assumes any of the true values. The condition item is false when the conditional variable assumes any other value. A condition item may optionally specify a single preferred value for which the condition item is false when the conditional variable assumes that value. The declaration of a condition item includes a condition-name that is used to refer to the condition item.

In Relativity, a column may be defined on a condition item, in which case the column has a value of 0 for false, and 1 for true. Relativity also uses condition items for specifying null values, specifying filters, and binding subscripts. To help support these uses of condition items, the Relativity Designer allows definition of additional condition items that were not in the COBOL source program.

Parent topic: Glossary of Terms
Related reference
condition-name
null
conditional variable
data item
SQL


condition-name

A user-defined word that names a condition item. In COBOL, a condition-name is declared in an 88-level description entry following the data description entry of its associated conditional variable.

Note: Relativity does not make use of the alternative COBOL meaning of condition-name where the condition-name is assigned to the status of a switch or device.
Parent topic: Glossary of Terms
Related reference
88-level
Complement
internal function
condition item
null
conditional variable
Constrain property
data item
filter subexpression
filter
LogicalAnd
LogicalOr
record type
record type filter


conditional variable

A data item that has one or more condition-names associated with it. The value of the conditional variable is used to determine whether the condition item named by the condition-name is true or false by comparing it to the values assigned to the condition-name.

Parent topic: Glossary of Terms
Related reference
condition-name
88-level
data item
condition item


Constrain property

A property that limits the value that a column may have during an INSERT or UPDATE operation to one of the true values indicated by an 88-level condition-name defined on the data item associated with the column. If the program did not define the appropriate 88-level condition-name(s), the Relativity Designer may be used to add the necessary condition-name(s).

Parent topic: Glossary of Terms
Related reference
88-level
condition-name
data item


custom data types

A Relativity representation of a domain. A custom data type, which is defined by the user, is a named set of properties for a column, including its ODBC data type, length, default value, whether the column allows null values, whether the column is constrained to certain values, and, for numeric type columns, the precision and scale. After a custom data type is defined, it can be used in place of ODBC data types in column definitions, thus giving all columns with the same user data type similar characteristics.

Parent topic: Glossary of Terms
Related reference
domain
ODBC data type
data-name
transform
ODBC
relational table
null


Custom Data Type property

In the FD form, the Custom Data Type property is the user data type that will be assigned by the Relativity Designer when the data item is used as a column in a table. Assign default data types to data items in the FD form by selecting the appropriate type in the Custom Data Type column.

Parent topic: Glossary of Terms
Related reference
Defining a User Data Type


data item

A named unit of data (excluding literals) defined by the COBOL program in a data description entry. The declaration of a data item includes a data-name that is used to refer to the data item. The Relativity Designer allows additional data items to be defined that redefine data items defined by the COBOL source program. See also repeating data item.

Parent topic: Glossary of Terms
Related reference
function
internal function
transform
COBOL table
repeating data item
table
CombineDateTime
ComputeCenturyDate
ComputeCenturyDateTime
ComputeDateTime
ComputeTime
conditional variable
condition item
Constrain property
88-level
condition-name
data-name
database
catalog
date constants
data source
SQL
function item
Relativity DBMS
ODO control item
record type
record type filter


data source

In Relativity, a data source is the connection known to ODBC between a Windows workstation and a Relativity catalog. A data source name (DSN) is used to identify the data source on the workstation. See also database and ODBC-enabled application.

Note: In client/server configurations of Relativity, a data source is defined on both the client workstation and on the server. The client data source is known to ODBC by its DSN and specifies the connection to the server data source. The server data source provides the connection to the Relativity catalog.
Parent topic: Glossary of Terms
Related reference
catalog
ODBC-enabled application
ODBC
database
date constants
data item
Relativity DBMS
SQL
relational database


data-name

A user-defined word that names a data item.

Parent topic: Glossary of Terms
Related reference
data item
repeating data item
domain
transform
custom data types
item set
redundant data items
relational table
ODO control item


database

In this document, particularly when qualified by "Relativity", a database refers to a relational database of tables and columns accessible as an ODBC data source, where the value for a column is derived from a data item in a COBOL file. An ODBC data source name is used to refer to the database, indirectly through the Relativity catalog that describes the database. The Relativity Designer is used to create and maintain the catalog. The Relativity DBA may be used to maintain a subset of the catalog relating to end-user administration features such as table connections, security, and date constants.

Parent topic: Glossary of Terms
Related reference
data source
catalog
ODBC-enabled application
ODBC
date constants
data item
Structured Query Language
relational database
relational database management system
relational table
COBOL table
table


date constants

Values stored in the Relativity catalog that control the conversion in a date transform or an internal function of COBOL data item values to SQL column date values. The date constants can be adjusted using the Relativity Designer or Relativity DBA to reflect common algorithms used in COBOL procedural code.

Parent topic: Glossary of Terms
Related reference
database
catalog
data item
data source
internal function
SQL
transform


Default Column Name property

In the FD form, the Default Column Name property is the SQL column name that will be assigned by the Relativity Designer when the data item is used as a column in a table. When the Default Column Name property is first generated, it is derived from the COBOL data-name according to a set of rules for defining default column names.

The column name may be changed after a column is created by using the Column Name property in the Table form.

Column names may not be SQL reserved words.

Parent topic: Glossary of Terms


Default Value property

In the Properties pane when viewing an FD form, the Default Value property is the value that is used in write operations if the item is not represented by a column in an SQL INSERT statement. This value is set by selecting the column row of the selected item in the FD form, then typing or selecting the value in the Default Value property. This property is only editable if the Edit default values option is selected in the File tab of the Options pane. See Defining Default Values for more information.

Parent topic: Glossary of Terms
Related reference
Defining Default Values


entered numerics

When adding condition items, if you are specifying an Entered numeric value, enter the COBOL numeric literal for the associated value. For example, 489, +12.75, -3.28, or -3.22E+12. The leading sign character is allowed only if the associated data item is signed. The decimal point is allowed only if the associated data item has digits to the right of the decimal point. The exponential notation is allowed only for associated data items with floating point numbers.

An Entered nonnumeric value is specified in the text box as the string of characters against which the conditional variable is to be compared. It is similar to a COBOL nonnumeric literal, except that the delimiting quotes are omitted and embedded quote characters are not doubled (that is, each occurrence of a quote character in the string represents one quote character in the resultant value as opposed to a COBOL nonnumeric literal where each pair of quote characters represents one quote character in the resultant value).

Parent topic: Glossary of Terms


domain

A named set of characteristics of a column including the data type, default value, constraints on the values in the column, and whether null values are allowed for the column. See also ODBC data type, and user data type.

Parent topic: Glossary of Terms
Related reference
ODBC data type
custom data types
data-name
transform
null


file label item

A file label item is a special file definition item used in multi-file table support. Multi-file table support allows the records of more than one COBOL file to be combined to constitute the rows of a single table. A file label item controls the way in which the records are combined, and provides a way to distinguish the business unit from which the row originated in the ODBC application.

A given FD may have only one file label item. A file label item can have a column defined on it and this column will be part of the indexes defined on the table.

Parent topic: Glossary of Terms
Related reference
ODBC
table


filter subexpression

A connecting logical operator (AND or OR), an optional negation logical operator (NOT), and a condition-name used to compose a filter expression that specifies the condition under which a record passes through the filter. If a filter has no subexpressions, then all records pass through the filter.

Parent topic: Glossary of Terms
Related reference
filter
condition-name
record type filter
table
table filter


filter

A set of criteria applied to records in order to obtain a subset of records that will be used to supply rows to a table. Relativity uses two types of filters: record type filter and table filter. Relativity filters use an expression composed of a filter subexpression or several filter subexpressions to specify the condition under which a record passes through the filter.

Parent topic: Glossary of Terms
Related reference
filter subexpression
condition-name
record type filter
table
table filter


function item

A data item that has been synthesized using an internal function.

Parent topic: Glossary of Terms
Related reference
internal function
data item


function

See internal function.

Parent topic: Glossary of Terms
Related reference
data item
internal function
transform


Hexadecimal condition values

When adding condition items, if you are specifying a Hexadecimal value, it is specified as a string of pairs of hexadecimal digits (0-9, A-Z), where each consecutive pair of hexadecimal digits specifies one character of the resultant value. For example, the string 0A0D would represent a value containing the ASCII character NL (newline) followed by CR (carriage return), the string 48494A4B would represent a conditional value containing the ASCII string HIJK, and the string F7F3F9 would represent a value containing the EBCDIC string 739. The Hexadecimal option is only allowed for nonnumeric data items.

Parent topic: Glossary of Terms


indexed file

A file having a permanent logical file structure in which each record is identified by a value of one or more keys within that record.

Parent topic: Glossary of Terms
Related reference
ISAM file


internal function

A conversion process, built into Relativity DBMS, that is used to synthesize a COBOL data item using the value or values of one or more other COBOL data items within the same COBOL file definition (FD). The other COBOL data items, which may include a previously defined internal function, are specified as arguments to internal functions. The result of the internal function is used as the value for the synthesized COBOL data item, also known as a function item. Unlike a transform, an internal function may operate on more than one COBOL data item. Compare to transform.

Parent topic: Glossary of Terms
Related reference
data item
function
transform
CombineDateTime
Complement
88-level
condition-name
ComputeCenturyDate
ComputeCenturyDateTime
ComputeDateTime
ComputeODO
repeating data item
ComputeTime
date constants
catalog
SQL
function item
Relativity DBMS
IsNumeric
IsValidDate
LogicalAnd
LogicalOr


ISAM file

A term used to refer to an indexed file.

Parent topic: Glossary of Terms
Related reference
indexed file


IsNumeric

An internal function that evaluates the data item supplied as an argument to determine whether its value is a valid numeric value. If the data item is numeric, the function returns the value one, which is the logical value of true. If the data item is not numeric, the function returns the value zero, which is the logical value of false.

The IsNumeric internal function evaluates the data item supplied as an argument to determine whether its value is a valid numeric value. If the data item is numeric, the function returns the value 1, which is the logical value of true. If the data item is not numeric, the function returns the value 0, which is the logical value of false.

Parent topic: Glossary of Terms
Related reference
internal function


IsValidDate

An internal function that evaluates the data item supplied as an argument to determine whether its value conforms to that item’s date transform. If the date item value represents a valid date, the function returns the numeric value one, which is the logical value of true. If the data item value does not represent a valid date, the function returns the numeric value zero, which is the logical value of false.

The IsValidDate internal function evaluates the data item supplied as an argument to determine whether its value conforms to that item’s date transform. If the date item value represents a valid date, the function returns the numeric value 1, which is the logical value of true. If the data item value does not represent a valid date, the function returns the numeric value 0, which is the logical value of false.

Parent topic: Glossary of Terms
Related reference
internal function


item set

Two or more data items in a COBOL record that contain identical information but that have been identified to Relativity as sets of redundant data items. Redundant data items include situations such as where one data item is identical to the first characters of another data item. One place where redundant data items are defined is in keys, where different keys provide different look-up capabilities in a file. Using Relativity, an item set becomes one data item in a relational table.

Parent topic: Glossary of Terms
Related reference
data-name
redundant data items
relational table


LogicalAnd

The LogicalAnd internal function does a logical "and" operation on two to twenty 88-level condition-names or logical internal functions (IsNumeric, LogicalAnd, LogicalOr). If all of the arguments are true, the function returns the numeric value 1, which is the logical value of true. If any of the arguments are false, the function returns the numeric value 0, which is the logical value of false.

Parent topic: Glossary of Terms
Related reference
88-level
condition-name
internal function


LogicalOr

The LogicalOr internal function does a logical "or" operation on two to twenty 88-level condition-names or logical internal functions (IsNumeric, LogicalAnd, LogicalOr). If any of the arguments are true, the function returns the numeric value 1, which is the logical value of true. If all of the arguments are false, the function returns the numeric value 0, which is the logical value of false.

Parent topic: Glossary of Terms
Related reference
88-level
condition-name
internal function


Not Null property

In the FD form, the Not Null property, when set, indicates that an SQL column defined on this item is null when the null condition is false. The Not Null property is initially not set, indicating that an SQL column defined on this item is Null when the Null condition is true. See Defining Null Information.

Parent topic: Glossary of Terms
Related reference
Defining Null Information


null

A value used in SQL to indicate that the column data value is incorrect, inapplicable, or unavailable. See also condition item and null.

Parent topic: Glossary of Terms
Related reference
condition item
condition-name
SQL
nullable
ODBC data type
custom data types
domain


Null Value property

In the FD form, the Null Value property describes the data value that will produce a null, or will be stored when a null is written, in an SQL column using this data item. The representation of a null for a data item in the FD form is selected from a list of condition-names. The conditional variable associated with a condition-name in the list does not have to be the data item on the FD form for which the Null Value property is being defined. See Defining Null Information.

Parent topic: Glossary of Terms
Related reference
Defining Null Information


nullable

An indicator that the column data value may be set to null.

Parent topic: Glossary of Terms
Related reference
null
ODBC data type


ODBC data type

An SQL definition that governs the type of data that is valid for a column in a relational table. The following lists the data type names preassigned to ODBC data types in Relativity:

  • Exact numeric data types are bit, smallint, integer, and decimal.
  • Approximate numeric data types are single and double.
  • Character (or text) data types are char, varchar, and longvarchar.
  • Unstructured binary data type is longvarbinary.
  • Date/time data types are date, time, and timestamp.

The preassigned data type names for the ODBC data type appear in a bold font on the Table form. See also user data type.

Parent topic: Glossary of Terms
Related reference
domain
custom data types
nullable
null


ODBC-enabled application

A Windows-based client application program (or tool) that has been designed to use the ODBC interface to access data external to the application. The ODBC interface requires that a data source be configured in order to allow data access. Examples of such programs include MS-Access, MS-Excel, Lotus 1,2,3, Crystal Reports, PowerBuilder, and so forth.

Parent topic: Glossary of Terms
Related reference
catalog
relational database management system
ODBC
Relativity DBMS
data source
database
Structured Query Language
Relativity Data Client
Relativity Data Server
SQL
relational database


ODBC

Abbreviation for Open Database Connectivity, a Microsoft Windows interface allowing applications to access data in database management systems (DBMS) using Structured Query Language (SQL). See also ODBC-enabled application.

Parent topic: Glossary of Terms
Related reference
catalog
relational database management system
ODBC-enabled application
Relativity DBMS
data source
database
file label item
table
relational table
custom data types
Structured Query Language
SQL
transform


ODO control item

The data item referenced by the data-name specified in the DEPENDING ON phrase of the OCCURS clause.

Parent topic: Glossary of Terms
Related reference
data-name
data item


Open Database Connectivity

A Microsoft interface allowing applications to access data in database management systems (DBMS) using Structured Query Language (SQL). Abbreviated ODBC.

Parent topic: Glossary of Terms
Related reference
SQL


property

The term property refers to information about a Relativity form, such as the: FD form, Table form, Edit Users form, or Edit Privileges form.

Parent topic: Glossary of Terms


RDBMS

Abbreviation for relational database management system, a program or set of programs for managing a relational database. Such a system normally includes a query capability that implements a query language. A common choice for the query language is Structured Query Language (SQL). See also Relativity DBMS.

Parent topic: Glossary of Terms
Related reference
relational database
Relativity DBMS
SQL


record type filter

A filter associated with a record type that determines the conditions controlling the subset of records from the file that conform to that record type. When a table is based on the record type, only records that satisfy the specified conditions contribute rows to that table. Those records may be further filtered by a table filter if a table filter is associated with the table. Record type filters are specified on the Record Type Properties form accessed from the FD form in the Relativity Designer.

Parent topic: Glossary of Terms
Related reference
filter
filter subexpression
table
table filter
record type
88-level
condition-name
data item


record type

A particular layout of a record area when multiple layouts exist because of redefinition or varying interpretation of data items in the record area. Normally, record types are distinguished by a record type indicator data item that is either outside any redefinition or exists in every redefinition. Relativity uses an 88-level condition-name defined on the record type indicator to distinguish record types. If the program did not define the appropriate 88-level condition-name(s), the Relativity Designer may be used to add the necessary condition-name(s). See also record type filter.

Parent topic: Glossary of Terms
Related reference
88-level
condition-name
data item
record type filter


Redefined By property

In the FD form, the Redefined By property is the COBOL data-name of any data item having a data description with the REDEFINES clause that specifies this data item. See Redefining Data Items and Defining Record Types.

Parent topic: Glossary of Terms
Related reference
Redefining Data Items
Defining Record Types


Redefines property

In the FD form, the Redefines property is the COBOL data-name that appears in the REDEFINES clause of the data description for a data item that contains the REDEFINES clause. See Redefining Data Items and Defining Record Types.

Parent topic: Glossary of Terms
Related reference
Redefining Data Items
Defining Record Types


redundant data items

See item set.

Parent topic: Glossary of Terms
Related reference
item set
data-name
relational table


relational database management system

A program or set of programs for managing a relational database. Such a system normally includes a query capability that implements a query language. A common choice for the query language is Structured Query Language (SQL). Abbreviated RDBMS. See also Relativity DBMS.

Parent topic: Glossary of Terms
Related reference
catalog
ODBC-enabled application
ODBC
Relativity DBMS
SQL
relational database
database


relational database

A type of database that defines multiple and complex relations among different data using tables (rows and columns of data). In a relational database, the rows of a table represent records (collections of information about separate items) and columns represent data items (particular attributes of a record). Relationships among data items are not physically stored. Instead, data is stored in tables, and relationships between two or more records are established by matching the values of columns common to those tables. See also relational database management system.

Parent topic: Glossary of Terms
Related reference
RDBMS
Relativity DBMS
SQL
database
relational database management system
Relativity Data Manager
Relativity Data Server
data source
ODBC-enabled application


relational table

A set of rows where each row contains the same number of columns. In any one column of a table, all the rows have the same value type in that column. Contrast with COBOL table. See also database and table.

Parent topic: Glossary of Terms
Related reference
item set
data-name
redundant data items
ODBC
custom data types
COBOL table
database
table
table definition
table filter


Relativity Data Client

The Relativity Data Client is the component of the Relativity DBMS that resides on the Windows client machine and provides the ODBC interface for the two-tier or client/server configuration of Relativity. ODBC-enabled applications running on the client machine access Relativity data on the server machine using the interface implemented in the Data Client. The Data Client is, essentially, the ODBC Driver for Relativity in this configuration. See also Relativity Data Server.

Parent topic: Glossary of Terms
Related reference
ODBC-enabled application
Relativity DBMS
Relativity Data Server


Relativity Data Manager

The Relativity Data Manager is used in the single-tier (or non-client/server) configuration of Relativity where the complete Relativity DBMS resides on a single Windows machine. This component implements the ODBC interface, the file to relational database transformations, and the application data file access routines. All the data files to be accessed must be accessible from the Windows machine, either because the files exist on disk drives attached to that machine or are accessible using the Windows network file system.

Parent topic: Glossary of Terms
Related reference
relational database
Relativity DBMS


Relativity Data Server

The Relativity Data Server is the component of a two-tier or client/server Relativity DBMS that resides on the remote server machine and implements the file to relational database transformations and the application data file access routines. This component runs on the remote machine that has access to the COBOL data files, either directly or through the network file system of the remote machine. See also Relativity Data Client.

Parent topic: Glossary of Terms
Related reference
Relativity Data Client
ODBC-enabled application
Relativity DBMS
relational database


Relativity DBMS

The Relativity DBMS (Database Management System) is software that implements an ODBC-compliant and relational database view of actual, operational COBOL data files. The Relativity DBMS also can take instructions from the ODBC-enabled application to access and change data in the COBOL data files. The ODBC-enabled application issues a high-level command, called an SQL statement, describing the data that the application wants to access. The Relativity DBMS performs the same actions a COBOL program would perform in order to extract that data and then returns the data to the ODBC-enabled application in the form of "rows".

The Relativity DBMS comes in two different configurations. In the single-tier or non-client/server configuration, the complete Relativity DBMS resides on a single Windows machine. The single-tier configuration component of the Relativity DBMS is referred to as the Relativity Data Manager. In the two-tier or client/server configuration, the Relativity DBMS is split into two components so that the DBMS can reside on two machines. The two-tier components of the Relativity DBMS are referred to as the Relativity Data Client and the Relativity Data Server. See also data source and catalog.

Parent topic: Glossary of Terms
Related reference
catalog
relational database management system
ODBC-enabled application
ODBC
internal function
data item
transform
RDBMS
relational database
SQL
Relativity Data Client
Relativity Data Server
Relativity Data Manager
data source


repeating data item

A data item having a data description entry that either contains the OCCURS clause or is subordinate to a data description entry that contains the OCCURS clause. See COBOL table. A repeating data item is also referred to as a subscripted data item, since such data items generally require a subscript when specified in COBOL source statements.

Parent topic: Glossary of Terms
Related reference
COBOL table
data item
table
ComputeODO
internal function
data-name
subscripted data item
subscript item


SQL

Abbreviation for Structured Query Language, a language to access data in a database management system (DBMS). See also ODBC.

Parent topic: Glossary of Terms
Related reference
date constants
catalog
data item
internal function
transform
null
condition item
Open Database Connectivity
RDBMS
relational database
Relativity DBMS
relational database management system
data source
ODBC-enabled application
ODBC
table name


Standard character sets

Windows Latin 1

Windows Latin 2

Windows Latin 5

Windows Cyrillic

Windows Greek

Windows Baltic Rim

Windows Hebrew

Windows Arabic

MS-DOS Latin US

MS-DOS Latin 1

MS-DOS Latin 2

MS-DOS Cyrillic

MS-DOS Cyrillic CIS-1

MS-DOS Turkish

MS-DOS Portuguese

MS-DOS Icelandic

MS-DOS French Canada

MS-DOS Greek

MS-DOS Greek 1

MS-DOS Greek 2

MS-DOS Baltic Rim

MS-DOS Russian

MS-DOS Arabic

MS-DOS Arabic ASMO

MS-DOS Hebrew

EBCDIC US Canada

EBCDIC International

EBCDIC Greek

EBCDIC Latin 5 Turkish

ISO 8859-1

ISO 8859-2

ISO 8859-5

ISO 8859-6

ISO 8859-7

ISO 8859-8

Parent topic: Glossary of Terms


Structured Query Language

A language to access data in a database management system (DBMS). Abbreviated SQL. See also ODBC.

Parent topic: Glossary of Terms
Related reference
ODBC
database
ODBC-enabled application


subscript item

A data item created by the Relativity Designer for each COBOL table. A subscript item, while not an actual part of the record, represents the subscript used to access repeating data items in the record. A column may be based on the subscript item by dragging the subscript item to a relational table in the Table form. Subscript items are given the data-name "SubscriptItem", and they are shown in the FD form immediately following any data item described with the OCCURS clause.

Parent topic: Glossary of Terms
Related reference
coinciding OCCURS
table
repeating data item
COBOL table


subscripted data item

A repeating data item (q.v.).

Parent topic: Glossary of Terms
Related reference
repeating data item
COBOL table


table

In Relativity, a table is usually a relational table composed of rows and columns. In certain cases, made clear by explicit qualification or context, a table is a COBOL table of repeating data items defined by use of the OCCURS clause. See also table filter.

Parent topic: Glossary of Terms
Related reference
COBOL table
data item
repeating data item
file label item
ODBC
filter
filter subexpression
record type filter
table filter
coinciding OCCURS
subscript item
relational table
database


table definition

A table definition is created by the Relativity Designer to define the structure of a relational table associated with a COBOL data file.

Parent topic: Glossary of Terms
Related reference
table name
relational table


table filter

A filter associated with a table that determines the conditions controlling the subset of records from the file that contribute rows in that table. If the table is based on one or more record types, the table filter is applied after the record type filters, if any, associated with those record types. A table filter is appropriate when either record types are not used or the table is a subset of the records belonging to the record type upon which the table is based.

Table filters are specified on the Table Filter Properties pane accessed from the table definition form.

Parent topic: Glossary of Terms
Related reference
filter
filter subexpression
record type filter
table
COBOL table
table filter
relational table


table name

A table name is the name of an SQL table.

Parent topic: Glossary of Terms
Related reference
table definition
SQL


transform

A process of converting a single COBOL data item value to or from a relational database column value. An example would be taking a COBOL PIC 9(8) data item that contains 19970129 and converting it to an ODBC date column that contains January 29, 1997. Compare to internal function.

Parent topic: Glossary of Terms
Related reference
data item
function
internal function
CombineDateTime
ComputeCenturyDate
ComputeCenturyDateTime
ComputeDateTime
ComputeTime
date constants
catalog
SQL
Relativity DBMS
domain
data-name
custom data types
ODBC


Transform property

In the FD form, the Transform property specifies a data transformation for a COBOL data item value to and/or from a relational database column value. Change the transform in the Transform property by clicking in the grid cell and then selecting a transform from the list.

The choices available in the Transform column are determined by the settings selected on the Date Format tab in the Options pane.

Parent topic: Glossary of Terms
Related reference
Defining Transforms on Data Items
Transforms


Value property

In the FD form, the Value property displays the value in the VALUE clause of a condition-name or the argument list of a function item. Click on the item row in the FD form to see the complete value entry in the Value property; see Adding Condition Items.

Parent topic: Glossary of Terms
Related reference
Defining Conditions


Copyright and Legal Information

  • Copyright and Trademarks
Parent topic: Micro Focus Relativity Designer for Windows


Copyright and Trademarks

© Copyright 1984 - 2020 Micro Focus or one of its affiliates. The software and information contained herein are proprietary to, and comprise valuable trade secrets of, Micro Focus, which intends to preserve as trade secrets such software and information. This software is an unpublished copyright of Micro Focus and may not be used, copied, transmitted, or stored in any manner other than as expressly provided in a written instrument signed by Micro Focus and the user. This software and information or any other copies thereof may not be provided or otherwise made available to any other person.

Micro Focus has made every effort to ensure that this book is correct and accurate, but reserves the right to make changes without notice at its sole discretion at any time. The software described in this document is supplied under a license and may be used or copied only in accordance with the terms of such license, and in particular any warranty of fitness of Micro Focus software products for any particular purpose is expressly excluded and in no event will Micro Focus be liable for any consequential loss.

Reference to third party companies, products and web sites is for information purposes only and constitutes neither an endorsement nor a recommendation. Micro Focus provides this information only as a convenience to users. Micro Focus makes no representation whatsoever regarding the content of any other web site or the use of any such third party products. Micro Focus shall not be liable in respect of your use or access to such third party products/web sites.

No part of this publication, with the exception of the software product user documentation contained on a CD-ROM, may be copied, photocopied, reproduced, transmitted, transcribed, or reduced to any electronic medium or machine-readable form without prior written consent of Micro Focus. Contact your Micro Focus representative if you require access to the modified Apache Software Foundation source files.

Licensees may duplicate the software product user documentation contained on a CD-ROM, but only to the extent necessary to support the users authorized access to the software under the license agreement. Any reproduction of the documentation, regardless of whether the documentation is reproduced in whole or in part, must be accompanied by this copyright statement in its entirety, without modification.

U.S. GOVERNMENT RESTRICTED RIGHTS. It is acknowledged that the Software and the Documentation were developed at private expense, that no part is in the public domain, and that the Software and Documentation are Commercial Computer Software provided with RESTRICTED RIGHTS under Federal Acquisition Regulations and agency supplements to them. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFAR 252.227-7013 et. seq. or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted Rights at FAR 52.227-19, as applicable. Contractor is Micro Focus, One Irvington Center, 700 King Farm Boulevard, Suite 400, Rockville, Maryland 20850. Rights are reserved under copyright laws of the United States with respect to unpublished portions of the Software.

2020-06-17

Parent topic: Copyright and Legal Information