'Xerox ANS COBOL (for BPM/CP-V) Xerox 550/560 and Sigma 5-9 Computers Operations Reference Manual 9015 01G XEROX Xerox ANS COBOL (for BPM/CP-V) Xerox 550/560 and Sigma 5-9 Computers Operations Reference Manual 90 15 01G May 1976 File No.: 1 X23 XJ80. Rev. 0 'i'l Xerox Corporation, 1973. 1975 Printed in U.S.A. REVISION This publication documents the E07 version of the Xerox ANS COBOL compiler for BPM and CP-V. This is the G edition of the manual; it is identical to the F edition (90 15 01F, dated September 1973) including all revision packages (90 15 01 F-1, 3;74; -2, 5;74; and -3, 6;75), and serves to consolidate them. Vertical lines in the outer margin indicate changes made in the most recent revision. RELATED PUBLICATIONS Publication No. Xerox 550 Computer/Reference Manual 903077 Xerox 560 Computer/Reference Manual 903076 Xerox Sigma 5 Computer/Reference Manual 900959 Xerox Sigma 6 Computer/Reference Manual 90 17 13 Xerox Sigma 7 Computer/Reference Manual 900950 Xerox Sigma 8 Computer/Reference Manual 901749 Xerox Sigma 9 Computer/Reference Manual 90 17 33 Xerox Batch Processing Monitor (BPM)/BP,RT Reference Manual 900954 Xerox Batch Processing Monitor (BPM)/OPS Reference Manual 90 11 98 Xerox Control Program-Five (CP-V)/TS Reference Manual 900907 Xerox Control Program-Five (CP-V)/OPS Reference Manual 90 16 75 Xerox Control Program-Five (CP-V)/TS User's Guide 90 16 92 Xerox Control Program-Five (CP-V)/SM Reference Manual 90 16 74 Xerox ANS COBOL (for BPM/CP-V)/LN Reference Manual 90 15 00 Xerox ANS COBOL On-Line Debugger Reference Manual 903060 Xerox Sort and Merge (for BPM/CP-V)/Reference Manual 90 11 99 Xerox Data Management System (OMS) (for BPM/CP-V)/Reference Manual 90 17 38 Xerox Extended Data Management System (EDMS)/Reference Manual 90 30 12 Manual Content Codes: BP - batch processing, LN - language, OPS - operations, RP - remote processing, RT - real-time, SM - system management, SP - system programming, TP - transaction processing, TS - time-sharing, UT - utilities. The specifications of the software system described in this publication are subject to change without notice. The availability or performance of some features may depend on a specific configuration of equipment such as additional tape units or larger memory. Customersshouldconsult their Xerox soles representative for detai Is. ii CONTENTS PREFACE v Deck Structures ________~ . ___ ._ __ .. _____________ 20 Basi c Setups ____. __ __ 20 1. PROGRAMMING HINTS Segmentation Feature - ______________ 25 Inter-Program Communica~ion (Subcompile Description of Numeric Data Items ________ 1 Feature) _______. _ _____________ 31 Examples of CI Decima I Add. 1 ENTER Statement Feature _____. _ _______ 37 Table Handling 2 Co-Resident Sort Feature ___________. _ ... __ ._ __ 40 OCCURS DEPENDING ON Clause .. 2 Debug Module Object Time Switch ______. ._ _ 48 Sort 2 1/0 Considerations 2 Report Writer 3 6. XEROX ANS COBOL COMPilER COBOL/FORTRAN Interfaces_ 3 DIAGNOSTICS 49 2. COMPilER 6 7. RUN-TIME SUBROUTINES, SERVICES AND DIAG NOS TICS 65 Compilation Initiation 6 BO (Binary Object Deck) 7 Library Subroutines ____________ 65 CS(name) (COMMON-STORAGE SECTlON)_ 7 Subprogram Calls 68 DEBUG (Debugging Statements) 7 Specia I Interfaces to Hardware and D lAG (Trivial Diagnostics)_ 7 Monitor Services __________ 68 DMAP (Data Division Map) 7 COBOL Error Codes 72 DQ (Double Quotation Mark) 9 GO (Compile and Ru,) ___ 9 INDEX 83 LIB (Library Accounts) ___ 9 lO (Object Listing) ____ 9 lS (Source Listi ng) 9 MAIN (Main Program) 12 MAPS (Both Data Division Map and Procedure Division Map) 12 APPENDIX PMAP (Procedure Division Map) 12 SEG (Priority Segments) __ 12 REFERENC E TABLES 75 SEQCHK (SeqlJence Check) 12 SO (Source Output) ~ ____ 12 Standard Symbols and Codes . ____ 75 SRTx (Co-Resident Sort) __ 13 Standard Character Sets _ 75 SUB (Subprogram) 13 Control Codes__________ 75 SYN (Syntax Checking) 13 Special Code Properties __. _ __________ 75 TEST (On-Line Debugger) __ 13 Standard 8-Bit Computer Codes (EBCDIC) ___ 76 XREF (Cross-Reference Listing) 13 Stondard 7-Bit Communication Codes 1_____________________ (ANSCII) 76 Standard Symbol-Code Correspondences 77 3. INTER-PROGRAM COMMUNICATION 14 Hexadecimal Arithmetic __________ 81 Addition Table ____. _.______________ 81 Introduction 14 Multiplication Table 81 Ru I es for Usage _____ 14 4. OBJECT PROGRAM 16 FIGURES Segmented Object Programs __ __ _ 16 Object Program Structure _________________ 16 1. Sample Data Division Map Listing _______ 8 5. PROGRAM COMPILATION AND EXECUTION 18 2. Sample (Partial) Object Listing ____ 10 Compi lation of large Source Programs 18 3. Sample Source Program and Procedure COBOL Work Files _____. . _______ 18 Division Map Listing __________ 11 COBOL Library on Tape 18 Print File Handling ______ 18 4. Sample Cross-Reference Listing_ 13 iii 5. Standard Control Section of a Root 16. Inter-Program Communication - Compilation Segment Modu Ie 17 and Execution 35 6. Load Modu leMa p 17 17. ENTER Statement Feature - Compi lotion and Execution 37 7. Basic Setup - Compilation Only 20 18. ENTER Statement Feature - EKecution with 8. Basic Setup - Compilation and Execution 21 Object Decks 39 9. Basic Setup - Execution with Object Deck ___ 24 19. Co. . Resident Sort Feature - Compi lotion and Execution (Sequential Sort Teehhique) __ 40 10. Segmentation Feature - Compi lotion and Execution 25 20. Co-Resident Feature - Compi lation and Execution (Random Sort Technique) 42 11. Segmentation Feature - Load from BO Fi Ie, Execute, and Punch BO Fi Ie 27 12. Segmentation Feature - ExecuHon from Object Decks 29 TABLES 13. Inter-Program Communication - Compi lotion 1. Xero)( Buffered Line Printers Models 7440/7445 of Ma i n or Ca" i ng Program 32 and 7446 Verticol-Fomlat Control Codes __ 19 14. Inter-Program Communication - Compi lotion 2. Xerox ANS COBOL Compiler Diagnostics 49 of Subprogram or Called Program 33 3. COBOL Object Program Subroutines 65 15. Inter-Program Communication - Execution with Object Decks 34 4. COBOL Error Codes 72 iv PREFACE This manual describes the operotions and characteristics of the Xerox ANS COBOL system (under BPM and CP-V) including the compiler, librar}' subroutines, and pertinent compiler and run-time diagnostics. It is assumed that the reader hCls a good working knowledge of the COBOL language as described in the Xerox ANS COBOL (for BPM/CP-V) Refere'nce Manual and of the operation of the Xerox Control Program-Five and/or the Xerox Batch Processing Monitor. v 1. PROGRAMMING HINTS This chapter provides a number of useful hints for improving the efficiency of object programs. Description 0" Numeric Data Items Avoid Mixed-Mode Arithmetic; Statements. An arithmetic statement involving data items of more than one mode (binary, decimal, or floating) requires one or more relatively expensive conversions of the operands or the result. These conversions, which require run-time subroutines, are not needed when mixed-mode arithmetic statements are avoided. Use Binary Rather Than Decim(~1 Subscripts. The COBOL compiler requires that all subscripts be binary. The costly conversions of subscripts can be avoided if they are defined as binary rather than decimal. Minimize Exponentiation. Exponentiation involves floating-point calculation mode even when there are no floating· point operands. _Use Binary Calculations if Possible. Binary calculations are faster than decimal or floating-point calculations UIIJ much faster than mixed mode. However, since binary items cannot contain a decimal point, their use is limited. If counters (i. e., input and output record counters) and sLIbscripts are defined as binary data items, and other numeric data items as decimal, the number of costly conversions will generally be minimized without loss of the effi ci enci es of binary ar: rhmeti c. Avoid Using Decimal Items Exceeding 15 Digits. Of the several ways to describe decimal items in COBOL, some permit the compi ler to generate fewer instructions than others. For example, a data item containing 16, 17, or 18 decimal digits may require CI double precision subroutine amounting to over 20 extra instructions not needed with items of 15 digits or less. SpeCify Odd-Size Decimal Display Fields. Sigma pack and unpack instructions do not operate on even-sized dec imal display fieldf. The compiler moves an even-sized display field to a work area in order to append a high-order zero, creating an odd-size field at a cost of three to six machine instructions. These extra instructions can be saved each time the field is referenced if it is odd-size to begin with. Specify Packed Decimal if Possi;ble. Packed decimal items occupy less space than decimal display items of the same size.' Besides, they don't have-tOl)e packed and unpacked when used. Packed decimal, therefore, results in ,fewer instructions being genera1'ed for a given arithmetic statement. Specify Signed Rother Than Uns;igned Decimal Display Fields. The compi ler must generate three instructions to get rid of the sign when a decimal field is described as unsigned. This applies each time the field is stored into. To summarize, a decimal data item should be less than 16 digits long and have an odd number of digits. It shoulrl be described with a sign, and a~; packed decimal rather than decimal display. Examples of a Decimal Add Example 1: 77 A PIC 99. 77 B PIC 99. ADD A TO B" Seventeen instructions wi II be generated. Programming Hints Example 2: 77 A PIC 5999 USAGE ]S COMP-3. 77 B PIC S999 USAGE IS COMP-3. ADD A TO B. Three instructions wi" be generated. Table Handling Use indexes rather thon subscripts for referencing data items described with or subordinate to one or more OCCURS clauses. With a subscript, the displacement into the table must be calculated (subscript x entry size - entry size) each time the table item is referenced. With indexing, this calculation is made only once when the index is set. In addition, when a table is described with an INDEXED BY clause, the SEARCH statement can be used on that table, and the search routine generated by the compi ler wi" be more efficient than one written by the programmer. Subscripts, if used, should be in binary since decimal subscripts are converted to binary anyway. OCCURS DEPENDING ON Clause Keep the use of this clause to a minimum. The OCCURS DEPENDING ON clause can be used effectively with variable length records to reduce the physical size of fi les and save I/O time. However, the clause wi" increase execution time because any reference to data item with an OCCURS DEPENDING ON clause requires that its size be calculated each time it is referenced. On balance, therefore, it is recommended that the use of OCCURS DEPENDING ON be kept to a minimum. Sort If a program has an input or output procedure, or both, either the co-resident or the linked sort can be re quested. The co-resident sort, which occupies core memory at the same time as the COBOL program, can signif icantly reduce the number of input/output operations and, hence,· run-time. It should, therefore, be used when core memory is avoi lab/e. When linked sort is used, the RELEASE statements in the COBOL input procedure bui Id a ft Ie as an interface for the linked sort. When the input procedure is finished, sort replaces the CaBO L program in memory (i. e., the COBOL object program is swapped out), and sorts the file created by the input procedure into a new fi Ie, whereupon the COBOL program is brought back into core memory, replacing the sort. The RETURN statements of the output procedure read the sorted fi Ie. Co-resident sort avoids superfluous reading and writing of the two files used by sort. When the SORT verb is en countered, control is transferred to sort. Then, when sort wants to read a record, it gives control to the COBOL input procedure, which provides a record through the use of the RELEASE statement. When sort wants to write the sorted file, it gives control to the COBOL output procedure, which accepts the sorted record with RETURN state ments. Thus, unnecessary input/output is avoided. I/O Considerations Block Sequential Files. Blocking sequential files can shorten I/O and CPU times by reducing the number of physical records and increasing their size. It lessens start/stop times for tapes and compute time for setting up the I/O oper ations. A block si ze of 5000 to 7000 bytes is recommended. 2 Table Handling/OCCURS DEPENDING ON Clause/Sort/I/O Considerations Use Unlabeled or ANS-labeled Tapes Rather Than labeled Tapes. The monitor attaches control information to "0 records written labeled tape, but not to device tape or ANS-Iabeled tape. In addition, I/o on rlevice tape of ANS-Iabeled tape is double-buffered. This allows I/o operations and CPU operations to overlap. Avoid the INTO Option of the_READ Statementand the FROM Option of the WRITE Statement. Working from record areas rather than moving the re!cords to and from working storage reduces program run time. In some cases where a master file is updated, moving the input master record to the output master record can be avoided. This is accom pi ished with the SAME RECORD AREA statement that allows a record to be read, updated, and written with no record movement by the programmer. It also reduces the size of the program. Block Relative Fi les. The monitor always reads or writes a minimum of one granu Ie (512 words, 2048 bytes) from or to a relative file. The BLOCK COI'\JTAINS clauseofCOBOLshould be used to obtain a physical record size which is a multiple of granule size. This will insure optimum utilization of disk space and maximum speed. The COBOL I/o system will locate the proper granule;block and retrieve the user's record based on the relative record number suppl ied. Note: To remove a record from a relative fi Ie place a X 'FFOO' in byte 1 of the record. This will signal the COBOL I/O system that this record is a null or deleted one. All records not written when the file is created are set to I1U II by the system. Report Writer A report restart facility can be provided by programming around the OPEN statement for the report file which is being restarted. No abort wi II occur. The programmer can accept a page start parameter from a control card, count the pages skipped and when the start page is reached the logic can then go to the OPEN and start printing. No other program logic rleeds to be al tered. The OPEN can also be circumvtented for the case where there are multiple FDs for a given RD and the suppression of its output to a file is desired. COBOL/FORTRAN Interfaces COBOL to FORTRAN It is possible for COBOL to "cull" FORTRAN subprograms by means of the ENTER verb. However, certain setup routines must be called and temp variables initialized before the FORTRAN library routines can be utilized. This initial ization process is triggere!d by the COBOL program having the statement: ENTER FORT LINK This is done prior to the first call to a FORTRAN subprogram. In addition to the ENTER list of arguments, the COBOL program may contain a COMMON-STORAGE SECTION. This generates a DSECT which can be referenced in the FORTRAN subprograms by means of the statement: COMMON/TALLY/TALLY, •••• Note that the first word of TALLY cannot be referenced in the COBOL program and is not initialized. The COBOL CS option permits use of a name other than TALLY for the common-storage DSECT. FORTRAN to COBOL Calling COBOL programs from FORTRAN programs has some restrictions. First, no arguments may be specified, data communication must be via namc~d common, as indicated above. Second, COBOL does not have a verb equivalent to RETURN in FORTRAN. Third, the CALL statement in FORTRAN will use register 15 for its linkage, therefore it must be saved before the COBOL program starts executing. Report Writer/COBOL/FORTRAN Interfaces 3 In order to achieve the FORTRAN to COBOL linkage it is necessary to use a METASYMBOL routine to save register 15 upon entry into the COBOL routine and to exit from the COBOL routine. The entry point in the COBOL routine that is used in the FORTRAN CALL statement must be DEFed by uling It in an ENTER COBOL statement. The METASYMBOL routine should' be cod.d like this: SYSTEM SIG7 DEF SAVEREG DEF RETNREG S15 RES 1 SAVEREG STW,15 S15 SAVE REG!STER 15 R ~': 11 RETURN 1U COBOL RETNREG B ~'(S 15 RETURN TO FORTRAN END To use the METASYMBOL routine GO TO statements or. required in the COBOL routine to go to the two entry points. Demonstration Job The following job hos been written to illustrate COBOL/FORTRAN interfaces. !JOB XEROX,COBOL,7 . COBOL/FORTRAN !TITLE COBOL to FORTRAN !COBOL LS fLO ,GO IDENTIFICATION DEVISION. PROGRAM~ID. COB:S. DATE-WRITTEN. DEC 12, 1974. DA TE -COMPILED. REMARKS. COBOL TO FOR TRAN AND ENTRY FOR FOR TRAN . ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE~COMPUTER. XEROX-560. OBJECT-COMPUTER. XEROX-S60. INPUT-OUTPUT SECTION. FI LE -CONTROL. DATA DIVISION. WORKING-STORAGE SECTION. 77 II COMP VALUE 1. 77 12 COMP VALUE 2. 77 13 COMP VALUE 3. COMMON-STORAGE SECTION. 77 Jl COMP VALUE 11. 17 J2 COMP VALUE 12. 77 J3 COMP VALUE 13. PROCEDURE DIVISION. S-1. ENTER FORTLINK. ENTER FTEST] 11,12,13. ENTER FTEST2. STOP RUN. ENTER COBOL CTEST. CTEST. GO TO SAVE REG . DISPLAY 'CTEST ENTERED' UPON PRINTER. GO TO RETNREG. 4 COBOL/FORTRAN Interfaces