VIII.4 The Geosupport Copy Files

This section describes an optional feature of Geosupport, its COPY files. The Geosupport COPY files contain source code layouts of the Geosupport API work areas in the COBOL, Assembler, PL/1, C and NATURAL programming languages. The use of the Geosupport COPY files can greatly facilitate user programming and is strongly recommended for all applications. The Geosupport COPY files are contained in the Geosupport COPY libraries, which are described below.

In this section, basic concepts of COPY files are explained, and the organization of the Geosupport COPY libraries is described. In Chapter VIII.5, the specific source code statements that users must code in their programs to utilize the Geosupport COPY files are described. Chapter VIII.6 describes the JCL required to compile a program that utilizes the Geosupport COPY files.

Overview of COPY Files in General

Many programming languages, including COBOL, Assembler, PL/1, C and NATURAL, have a facility for referring, within the source code of a program, to external files (generically referred to as ‘COPY files’ in this document) containing source code to be inserted into the program at compile time. (C ‘COPY files’ are usually called header files; NATURAL ‘COPY files’ are called Local Data Areas (LDAs).) Each programming language has a declarative command (‘COPY’ in COBOL and Assembler, ‘%INCLUDE’ in PL/1, ‘#include’ in C, ‘LOCAL USING’ in NATURAL) for referring to such external COPY files. During program compilation, when the compiler encounters such a command, it dynamically retrieves the source code stored in the named COPY file and processes that source code as if it were an integral part of the program source code. The source code retrieved at compile time from the COPY file serves as input to the compiler only; it is not inserted permanently into the user’s program source code file. Only the declarative statement that refers to the COPY file is permanently present in the program source code. Note: declarative statements referencing external source code COPY files are not to be confused with external program calls. Declarative statements are directives to the compiler, and are processed at source code compilation time; program calls are executable statements, performed at application execution time.

For COBOL, Assembler, PL/1 and C, COPY files must reside as members of a Partitioned Data Set (PDS) called a COPY library, which must be made accessible to the compiler by coding a SYSLIB DD statement in the JCL for the compile step. In addition, for COBOL and PL/1, an appropriate compiler option must be specified. For NATURAL, COPY files are called Local Data Areas (LDAs) and reside in the system library in each ADABAS database. The Database Administrator (DBA) must modify each NATURAL application’s security profile to make the LDAs accessible to the application.

An ideal situation in which to use COPY files is when numerous programs in an application must all describe the same data structure(s). Using this technique, a source code description of each data structure is stored centrally in a COPY library. All programs requiring one or more of the data structures need only contain declarative statement(s) referring to the appropriate member file(s) in the COPY library. This approach insures that all the programs define the given storage layout in exactly the same way, using the same data item names, data types and data lengths. This facilitates application-wide maintenance and debugging. Changes to a data structure need only be made centrally in the COPY file, rather than separately and redundantly in each program.

Of course, the source code in a program that references a COPY file must be written so that it is compatible with the source code in that COPY file. In particular, for fields that are defined in the COPY file and referred to in the program, the program must use the same data names and must assume the same data types and lengths as does the COPY file.

The Geosupport COPY Libraries

There are two Geosupport COPY libraries that collectively contain COBOL, Assembler, PL/1 and C source code COPY files for all of the Geosupport API work area layouts. Geosupport also has a set of NATURAL LDAs for the work area layouts. The use of these facilities can greatly facilitate user application programming. Among the potential productivity benefits are the following:

  • Elimination of the need for application programmers to key into their programs lengthy source code descriptions of the Geosupport work area layouts line by line.

  • Standardization of Geosupport data item names among the programs in an application, facilitating troubleshooting and the reassignment of programming staff to programs written by others.

  • Standardization of the descriptions (data types and lengths) of Geosupport data items in an application, fostering accuracy and compatibility among programs and files.

  • Simplification of the updating of programs to reflect changes to Geosupport work area layouts. Each time a program that references the Geosupport COPY libraries is recompiled, the latest versions of the work area layouts are automatically retrieved.

The Geosupport COPY libraries supporting COBOL, Assembler, PL/1 and C applications are two catalogued Partitioned Data Sets (PDSs) named A030.GEO.COPYLIB2 and A030.GEO.COPYLIB.

For NATURAL applications at DoITT, the DoITT Database Administration staff is responsible for installing the Geosupport LDAs in the system library (CSCLIB) for each ADABAS database and for making the LDAs accessible to each application that needs such access by updating the application’s profile. It is the user’s responsibility to communicate with the appropriate DoITT staff to request such installation and profile updating.

The Geosupport COPY libraries contain a complete set of COPY files for the Geosupport API work areas in COBOL, Assembler, PL/1, C and NATURAL. Each COPY file contains source code descriptions of one or more of the work areas in one of the supported programming languages, as explained below. The Geosupport COPY libraries support both batch and CICS applications.

The MSW Work Area 2s of Functions 1, and 1E, (regular WA2), 2, 3 and 3C all have the same length, 200 bytes. For each of the supported programming languages except C, the layouts of these work areas are stored together in a single COPY file, coded as redefinitions of the same memory area. (In the COBOL files, this is done using REDEFINES. In the Assembler files, it is done using an ORG to reset the Location Counter. In the PL/1 files, it is done using BASED. In the NATURAL LDAs, it is done using REDEFINE.) Except for C, each of the remaining work area layouts has its own COPY file. For C, there is a single COPY file (called a ‘header file’ in C terminology) containing the layouts of all of the work areas, including WA1.

The COW Work Area 2s are handled in a similar fashion, though they may not all have the same length.

Tables VIII-1 and VIII-2, below, list all of the MSW and COW COPY files respectively for COBOL, Assembler, PL/1, NATURAL and C. The tables indicate the work areas for which each file contains layouts, the lengths of those work areas in bytes, and the name of each file by programming language. Appendix 5 and Appendix 14 contain printouts of the MSW and COW COPY files respectively.

Important Note: As of January 1, 2020, Mainframe-Specific Work Areas (MSWs) will no longer be supported. It is therefore essential that users convert their MSW applications to th COW format. See Appendix 12

Table VIII-1: MSW COPY Files for COBOL, Assembler, PL/1, C and NATURAL

- - - - - - - - - - COPY File Name - - - - - - - -
MSW
WORK
AREA
FUNCTION(S) LENGTH
(bytes)
COBOL ASSEMBLER PL/1 C NATURAL
WA1 All 884 W1COB W1BAL W1PL1 WAC GEOLW1
WA2 1 (regular WA2), 1E (regular WA2), 2, 3 (regular WA2), 3C 200 W2COB W2BAL W2PL1 WAC GEOLW2
WA2 1 (long WA2), 1E (long WA2), 3 (long WA2) 300 W2COBL W2BALL W2PL1L WAC GEOLW2L
WA2 1A&BL (regular WA2), BN (\*) 939 W2COB1A W2BAL1A W2PL11A WAC GEOLW2LA
WA2 1A&BL (long WA2) (\**) 17,683 W2COB1AL W2BAL1AL W2PL11AL WAC GEOLW2LAL
WA2 3S 4,224 W2COB3S W2BAL3S W2PL13S WAC GEOLW23S

The COW COPY Files Table (Table VIII-2) appears on the following page.

- - - - - - - - - - COPY File Name - - - - - - - -
MSW
WORK
AREA
FUNCTION(S) LENGTH
(bytes)
COBOL ASSEMBLER PL/1 C NATURAL
WA1 All 1,200 P1COB P1BAL P1PL1 PAC GEOLP1
WA2 1 & 1E (Regular WA2), 3C (Regular WA2) 300 P2COB P2BAL P2PL1 PAC GEOLP2
WA2 2 200 P2COB P2BALL P2PL1L PAC GEOLP2
WA2 2W 4000 P2COB P2BAL P2PL1 PAC GEOLP2
WA2 3 (Regular WA2) 450 P2COB P2BAL P2PL1 PAC GEOLP2
WA2 3 (WA2 with AUXSEG option) 950 P2COB P2BAL P2PL1 PAC GEOLP2
WA2 3C (WA2 with AUXSEG option) 800 P2COB P2BAL P2PL1 PAC GEOLP2
WA2 3C (WA2 with AUXSEG option) 800 P2COB P2BAL P2PL1 PAC GEOLP2
WA2 3 (Extended WA2) 1,000 P2COB P2BAL P2PL1 PAC GEOLP2
WA2 3C (Extended WA2) 850 P2COB P2BAL P2PL1 PAC GEOLP2
WA2 3 (Extended WA2 w/AUXSEG) 1,500 P2COB P2BAL P2PL1 PAC GEOLP2
WA2 3C (Extended WA2 w/AUXSEG) 1,350 P2COB P2BAL P2PL1 PAC GEOLP2
WA2 1A & BL (Regular WA2), BN (\*) 1,363 P2COB1A P2BAL1A P2PL11A PAC GEOLP21A
WA2 1A & BL (Long WA2) (\**) 1A & BL (TPAD Long WA2) (\***) 17,750 P2COB1AL P2BAL1A P2PL11AL PAC GEOLP2AL
WA2 1A & BL & BN (Extended WA2) (****) 2,800 P2COB1AL P2BAL1A P2PL11AL PAC GEOLP2AL
WA2 1 & 1E (Extended WA2) 1,500 P2COB1AL P2BAL1A P2PL11AL PAC GEOLP2AL
WA2 1B 4,300 P2COB1AL P2BAL1A P2PL11AL PAC GEOLP2AL
WA2 3S 19,274 P2COB3S P2BAL3S P2PL13S PAC GEOLP23S
WA2 AP 1,363 P2COBAP P2BALAP P2PL1AP PAC GEOL2AP
WA2 AP (Extended WA2) 2,800 P2COBAP P2BALAP P2PL1AP PAC GEOL2APX

(*) Functions 1A, BL and BN share a single regular WA2 layout. (*) Functions 1A and BL share a single long WA2 layout. (Function BN has no long WA2 option.). (*) Functions 1A and BL share a single TPAD long WA2 layout. (Function BN has no TPAD long WA2 option.). (*) Functions 1A, BL and BN share a single extended WA2 layout.