XE550 BURROUGHS INGRES EQUEL/COBOL RELEASE 2.0.4/U.S.A. RELEASE TECHNICAL NOTES COPYRIGHT (C) 1984 BURROUGHS CORPORATION DETROIT, MICHIGAN 48232 COPYRIGHT (C) 1984 RELATIONAL TECHNOLOGY, INC. BERKELEY, CALIFORNIA 94705 THE WITHIN SPECIFICATION IS NOT INTENDED TO BE, NOR SHOULD SUCH BE CONSTRUED AS AN AFFIRMATION OF FACT, REPRESENTATION OR WARRANTY, BY BURROUGHS CORPORATION OF ANY TYPE, KIND, OR CHARACTER. THE WITHIN INFORMATION, AND RELATED MATERIALS ARE FURNISHED PURSUANT AND SUBJECT TO THE TERMS AND CONDITIONS OF A DULY EXECUTED LICENSE AGREEMENT. THE ONLY WARRANTIES MADE BY BURROUGHS WITH RESPECT TO THE PRODUCTS DESCRIBED IN THIS MATERIAL ARE SET FORTH IN THE ABOVE MENTIONED AGREEMENT. BURROUGHS CORPORATION DETROIT, MICHIGAN 48323 TABLE OF CONTENTS SECTION DESCRIPTION PAGE ------- ------------------------------------------ ---- 1.0 INTRODUCTION 3 2.0 DOCUMENTATION 4 3.0 SOFTWARE FEATURES 5 4.0 SOFTWARE INSTALLATION PROCEDURE 6 5.0 LIMITATIONS 9 6.0 FCF REPORTING PROCEDURE 10 7.0 KNOWN PROBLEMS 12 8.0 SOFTWARE INDEX 13 XE550 BURROUGHS INGRES EQUEL/COBOL PAGE 3 LEVEL 2.0.4/U.S.A. - RELEASE TECHNICAL NOTES 1.0 INTRODUCTION The Burrough's INGRES EQUEL/COBOL package is designed to provide the applications developer with an interface between the INGRES database management system and the COBOL programming language. The EQUEL/COBOL package contains a preprocessor which enables the COBOL programmer to directly embed QUEL statements into COBOL code, for ease of understanding and use. Virtually all QUEL statements can be embedded into an EQUEL/COBOL program, enabling all necessary database operations to be easily specified. The description of how to use INGRES EQUEL/COBOL is contained in the documentation which accompanies this release. This release letter describes the technical features for the XE550 INGRES EQUEL/COBOL preprocessor package. Please read the entire release letter before proceeding to the installation procedure outlined in Section 4.0. A copy of this letter can be found in the directory on [D1] labeled: Releasenotes.XE550.ECB. XE550 BURROUGHS INGRES EQUEL/COBOL PAGE 4 LEVEL 2.0.4/U.S.A. - RELEASE TECHNICAL NOTES 2.0 DOCUMENTATION 2.1 REFERENCE DOCUMENTS The following document describes the use of the INGRES EQUEL/COBOL preprocessor in detail, including the interface to the XE550 COBOL Run-Time System: 1176476 - XE550 Systems, INGRES EQUEL/COBOL User's Guide The following document should be referenced for all ques- tions relating to standard COBOL (apart from EQUEL considerations): 1175890 - XE550 COBOL Language Manual (also contains Native Code Generator information) The following is a list of all documents available for the XE550 INGRES Database Management System: 1175940 - XE550 INGRES Installation & Operations Guide 1176435 - XE550 Introduction to INGRES 1176443 - XE550 INGRES Self-Instruction Guide 1175957 - XE550 INGRES Reference Manual 1175965 - XE550 INGRES EQUEL/C User's Guide 1175973 - XE550 INGRES Query by Forms (QBF) User's Guide 1175981 - XE550 INGRES Visual Forms Editor (VIFRED) User's Guide 1176005 - XE550 INGRES Report by Forms (RBF) User's Guide 1175999 - XE550 INGRES Report Writer Reference Manual 1176457 - XE550 INGRES Demonstration 1176468 - XE550 INGRES Application Notes Some purchasers of INGRES EQUEL/COBOL may receive a pre- liminary copy of the EQUEL/COBOL manual. Those getting a preliminary version will receive a completed manual at a later date. Should the finished manual fail to arrive within a reasonable amount of time, contact your local Burrough's support person and ask him/her to follow up on this for you. XE550 BURROUGHS INGRES EQUEL/COBOL PAGE 5 LEVEL 2.0.4/U.S.A. - RELEASE TECHNICAL NOTES 3.0 SOFTWARE FEATURES EQUEL (Embedded QUEL) is an embedding of the INGRES query language QUEL into a procedural programming language. This allows QUEL commands, as described in the "INGRES Reference Manual," to be embedded within a COBOL program. EQUEL is implemented by using a preprocessor to translate the QUEL statements into calls to a run-time library, which provides the interface to INGRES. EQUEL/COBOL is provided as the COBOL interface to INGRES because it has significant advantages for the user. It is easier to learn, and use, than a "call-type" interface. The form of the language is similar across all programming languages and it is independent of the actual form of the interface to INGRES. Because EQUEL is essentially the same in all languages, EQUEL statements used in COBOL, BASIC, PASCAL and C programs are all interchangeable. Also, the interface presented to the user is independent of the actual implementation of the interface to INGRES. EQUEL/COBOL provides: - QUEL syntax for interface to INGRES databases - Type conversion - Run-time error processing - Interrupt handling - Access to INGRES forms constructs EQUEL/COBOL may be used with the standard XE550 COBOL Run- Time System, or with the XE550 COBOL Native Code Generator for more efficient operation. No special considerations are necessary. XE550 BURROUGHS INGRES EQUEL/COBOL PAGE 6 LEVEL 2.0.4/U.S.A. - RELEASE TECHNICAL NOTES 4.0 SOFTWARE INSTALLATION PROCEDURE In order to successfully install INGRES EQUEL/COBOL, you MUST have previously loaded BOTH the standard INGRES Database Management System software and the standard CENTIX COBOL release onto your system. The EQUEL/COBOL product WILL NOT install if you have not previously loaded the above mentioned software. INGRES EQUEL/COBOL is installed in two stages. During the first stage of installation, the System Load Utility will copy the INGRES EQUEL/COBOL partition to [d1]INGRESEQUELCOBOL and then append an entry to [d1]CENTIXProducts, naming the partition which contains the INGRES EQUEL/COBOL software. (Please refer to the 'System Load Utility' release letter for information regarding the first stage of installation.) The second stage of installation is performed by centrEASE, which copies the INGRES EQUEL/COBOL software into the 'Root' file system. The following steps should be followed in order to load INGRES EQUEL/COBOL thr((ough the centrEASE facility: STEPS IN LOADING INGRES EQUEL/COBOL 1.) Initiate centrEASE (Type 'saf') 2.) Type a '5', 'Install CENTIX Products', and select the appropriate number to install INGRES EQUEL/COBOL. Once the above has completed, you may exit from centrEASE. Please note that the entire procedure above should take about fifteen (15) minutes to complete. After step 2 has completed, INGRES EQUEL/COBOL will be completely installed. XE550 BURROUGHS INGRES EQUEL/COBOL PAGE 7 LEVEL 2.0.4/U.S.A. - RELEASE TECHNICAL NOTES 4.0 SOFTWARE INSTALLATION PROCEDURE (CONT) It is possible that the 'Install CENTIX Products' step will fail if the directions shown above are not followed explicitly. An appropriate message will be displayed, and an exit status will be shown through centrEASE. A successful installation returns an exit status of 0, while all installation errors return an exit status of 2. The two most common errors in the install step are: - "INGRES EQUEL/COBOL install: you must install INGRES sys- tem files before EQUEL/COBOL files." REMEDY: The standard XE550 INGRES Database Management System MUST be installed prior to EQUEL/COBOL. Reload the INGRES release and then reload INGRES EQUEL/COBOL. Re-boot the system and perform steps 1 & 2 above, again. - "INGRES EQUEL/COBOL install: The installation failed. Be sure the directories ingres/bin, ingres/files, and ingres/ lib exist." MEANING: The directory "ingres" is the home directory of the "ingres" user account. The files on the INGRES EQUEL/COBOL cartridge are loaded into the indicated directories under the INGRES home dir- ectory. REMEDY: The standard XE550 INGRES Database Management System MUST be installed prior to EQUEL/COBOL, and configured according to standard procedures. Reload INGRES and then reload INGRES EQUEL/COBOL. Reboot the system and perform steps 1 & 2 above, again. Other errors in the install step should not occur while using centrEASE, but only through a manual installation. The install procedure also modifies the following CENTIX COBOL files: /usr/lib/cobol/userdefines.h /usr/lib/cobol/usercall.c /usr/lib/cobol/usercallinit.c /usr/lib/cobol/rts5 XE550 BURROUGHS INGRES EQUEL/COBOL PAGE 8 LEVEL 2.0.4/U.S.A. - RELEASE TECHNICAL NOTES 4.0 SOFTWARE INSTALLATION PROCEDURE (CONT) COBOL variables required for EQUEL/COBOL are added to the files "userdefines.h", "usercall.c", and "usercallinit.c" by the install procedure. The latter two files are recompiled, and their object modules are added to produce a new COBOL run-time system "rts5". The new COBOL run-time system is created with the following statement (done in the directory /usr/lib/cobol): ld /lib/crt0.o rts5.o usercallinit.o usercall.o \ `cat rts5.o-list` -lm -lc -o rts5 C-language modules may be added in a similar manner by modi- fying the "user*" files above, recompiling the "usercall.c" and "usercallinit.c" files, appending the names of the C modules you wish to add to the "rts5.0-list" file in the directory /usr/lib/cobol, and executing the above "ld" statement. See the appropriate CENTIX COBOL documentation for more information. For a list of the files contained with this release, see Section 8.0 - INDEX. XE550 BURROUGHS INGRES EQUEL/COBOL PAGE 9 LEVEL 2.0.4/U.S.A. - RELEASE TECHNICAL NOTES 5.0 LIMITATIONS XE550 INGRES EQUEL/COBOL has three major limitations in this release. They are as follows: 1.) This version of INGRES EQUEL/COBOL is only compatible with CENTIX level B3.00 system software and release 2.0 of the INGRES software. Systems having and earlier release of CENTIX and/or INGRES must upgrade before installing this release of EQUEL/COBOL. 2.) The system administrator may add external C-language modules to the EQUEL/COBOL run time system file "/usr/lib/cobol/rts5" by the means described in the "INSTALLATION" section. This capability should not be allowed for other users of the system. 3.) The file "~ingres/files/eqdefMF.cbl" contains a list of COBOL variables used by EQUEL/COBOL. All of them begin with "II". These variables must NOT be used by the COBOL programmer, or unexpected results may occur. XE550 BURROUGHS INGRES EQUEL/COBOL PAGE 10 LEVEL 2.0.4/U.S.A. - RELEASE TECHNICAL NOTES 6.0 FCF REPORTING PROCEDURE All software problems, software deficiencies, or suggestions for improvements should be reported by submitting a "Field Communication Form 3027057" (FCF), to your local Burroughs support personnel. The FCF should be reviewed for completeness and forwarded to the following address: Burroughs Corporation Product Assurance and Support PO Box 235 Downingtown, PA 19335 Attn: FCF Coordinator All information which would be helpful in understanding and analyzing the reported situation should be included with the FCF. This can be in the form of descriptions, computer listings, media containing programs and data, etc. Please include a listing of the file '[sys]Sys.Version' with ALL FCFs submitted. Certain problem situations are given below, together with appropriate information to be submitted for each. For a hang or crash condition: - a printout from MPLog or the logfile itself. - any observations of abnormal operation prior to the problem. - applicable crash files for FP... crashdump.sys, for workstation... ws>crashdump.sys, for CP... CPxx.crash, where xx is the number of the borad. - an indication of front panel LED status code. - an indication of LED lights on the back of each board. For execution conditions: - any data neccessary to demonstrate the problem. - a list of erroneous output with the errors indicated and corrections noted. XE550 BURROUGHS INGRES EQUEL/COBOL PAGE 11 LEVEL 2.0.4/U.S.A. - RELEASE TECHNICAL NOTES 6.0 FCF REPORTING PROCEDURE (Continued) For problems which reoccur, but cannot be reproduced on demand: - a clear and detailed description of the situation. - log file (where applicable) - any data which may be available for this type of problem, including listings, etc. When completing the FCF, please keep the following points in mind: - Only one problem should be reported per FCF. - The FCF form is to used for reporting system software problems, errors in documentation, or suggestions for new software features. Do not use it to ask questions or request information from Product Assurance & Support. - The information should be as clear and legible as pos- sible. - All attachments submitted with the FCF should be clearly marked with the FCF number. If you wish anything to be returned to you, including any media you may have submitted, you MUST indicate so on the FCF form, and the piece of media. If you do not, your media will not be returned. XE550 BURROUGHS INGRES EQUEL/COBOL PAGE 12 LEVEL 2.0.4/U.S.A. - RELEASE TECHNICAL NOTES 7.0 KNOWN PROBLEMS 1.) EQUEL/COBOL variable d(ata types "comp-1" and comp-2" are mentioned in the documentation but are not supported in this release. 2.) In EQUEL/COBOL the command "set_equel ("errordisp"=0)" does not suppress printing of the last error message. 3.) In EQUEL/COBOL when two "set_equel ("errormode"=0)" are used, the first error message is suppressed correctly, but the second error message is not suppressed. XE550 BURROUGHS INGRES EQUEL/COBOL PAGE 13 LEVEL 2.0.4/U.S.A. - RELEASE TECHNICAL NOTES 8.0 SOFTWARE INDEX The following is a list of files associated with this release of Burroughs INGRES EQUEL/COBOL: ProductContent Within the CENTIX partition: /filelist /install /EQUEL-COBOL/bin/cobcomp /EQUEL-COBOL/bin/eqcbl /EQUEL-COBOL/files/eqdefMF.cbl /EQUEL-COBOL/lib/cbruntimelib