VIII.5 Coding API Calls When Using Geosupport COPY Files

This section describes the source code statements that COBOL, Assembler, PL/1, C and NATURAL users must code in application programs that use Geosupport COPY files. The required statements consist of declarative statements to reference the COPY files (using the file names in Table VIII-1) and statements calling the driver.

In Chapter VIII.3, the forms of calls to the driver were given using arbitrary data names for the work areas. In programs that do not use Geosupport COPY files, those names are user-selectable. In the present section, the forms of the driver calls are given again, this time with the specific data names that are required for compatibility with the COPY files. COBOL and C are the only supported languages that permit COPY file users to select their own names for the work areas (but not for the fields within the work areas). Prior to each call to the driver, the program must prime Work Area 1 with the input data to be processed by Geosupport, as described in Chapter II.3.

In Chapter VIII.3, the forms of calls to the driver were given using arbitrary data names for the work areas. In programs that do not use Geosupport COPY files, those names are user-selectable. In the present section, the forms of the driver calls are given again, this time with the specific data names that are required for compatibility with the COPY files. COBOL and C are the only supported languages that permit COPY file users to select their own names for the work areas (but not for the fields within the work areas). Prior to each call to the driver, the program must prime Work Area 1 with the input data to be processed by Geosupport, as described in Chapter II.3.

The declarative statements referencing COPY files cause the compiler to process the source code contained therein as if it were present within the application program’s own source code at the point in the program where the declarative statement is located. Application programs need only reference those Geosupport COPY files that are required for the Geosupport function(s) the program actually calls, although referencing other COPY files does no harm.

COBOL Source Code Statements

To reference Geosupport MSW COPY files, COBOL programs must contain the appropriate one (or more) of the following statements in WORKING-STORAGE:

01 ANY-NAME-FOR-WA1. COPY W1COB. WA1, all functions 01 ANY-NAME-FOR-WA2. COPY W2COB. WA2, Functions 1 & 1E & 3 (regular WA2), 2, 3C

01 ANY-NAME-FOR-WA2-L. COPY W2COBL. WA2, Functions 1& 1E & 3 (long WA2)

01 ANY-NAME-FOR-WA2-1A. COPY W2COB1A. WA2, Functions 1A & BL (regular WA2), BN

01 ANY-NAME-FOR-WA2-1AL. COPY W2COB1AL. WA2, Functions 1A & BL (long WA2)

01 ANY-NAME-FOR-WA2-3S. COPY W2COB3S. WA2, Function 3S

For COBOL programs that will be executed in the batch environment and that use Geosupport COPY files, API calls are coded as follows:

One-work-area calls, all functions: CALL ‘GBI’ USING ANY-NAME-FOR-WA1.

Two-work-area calls, Functions 1 & 1E & 3 (regular WA2), 2, 3C: CALL ‘GBI’ USING ANY-NAME-FOR-WA1 ANY-NAME-FOR-WA2.

Two-work-area calls, Functions 1 & 1E & 3 (long WA2): CALL ‘GBI’ USING ANY-NAME-FOR-WA1 ANY-NAME-FOR-WA2-L.

Two-work-area calls, Functions 1A & BL (regular WA2), BN: CALL ‘GBI' USING ANY-NAME-FOR-WA1 ANY-NAME-FOR-WA2-1A.

Two-work-area calls, Functions 1A & BL (long WA2): CALL ‘GBI’ USING ANY-NAME-FOR-WA1 ANY-NAME-FOR-WA2-1AL.

Two-work-area calls, Function 3S: CALL ‘GBI’ USING ANY-NAME-FOR-WA1 ANY-NAME-FOR-WA2-3S.

CICS programs issue calls as above but with GOAIDRV in place of GBI.

To reference Geosupport COW COPY files include the appropriate COPY files whose names begin with P1 and P2 instead of W1 and W2, e.g. P1COB instead of W1COB. Note that in the COW format, there is no long WA2 for Functions 1, 1E, and 3. Note, also, that there are additional function options in the COW format.

* To choose the appropriate COW COPY file, see Table VIII-2.*

Assembler Source Code Statements

To reference Geosupport MSW COPY files, Assembler programs must contain the appropriate one (or more) of the following statements:

For Assembler programs that will be executed in the batch environment and that use Geosupport COPY files, API calls are coded as follows:

CICS programs issue calls as above but with GOAIDRV in place of GBI.

To reference Geosupport COW COPY files include the appropriate COPY files whose names begin with P1 and P2 instead of W1 and W2, e.g. P1BAL instead of W1BAL. Note that in the COW format, there is no long WA2 for Functions 1, 1E, and 3. Note, also, that there are additional function options in the COW format.

* To choose the appropriate COW COPY file, see Table VIII-2. *

PL/1 Source Code Statements

To reference Geosupport MSW COPY files, PL/1 programs must contain the appropriate one(s) of the following statements:

For PL/1 programs that will be executed in the batch environment and that use Geosupport COPY files, API calls are coded as follows:

CICS programs issue calls as above but with GOAIDRV in place of GBI.

(Note: for either a batch or a CICS PL/1 program, the appropriate Geosupport driver (GBI or GOAIDRV respectively) must be declared as an external entry point. See Section VIII.3.)

To reference the Geosupport COW COPY files include the appropriate copy files whose names begin with P1 and P2 instead of W1 and W2, e.g. P1PL1 instead of W1PL1. Note that in the COW format, there is no long WA2 for Functions 1, 1E, and 3. Note, also, that there are additional function options in the COW format.

/* To choose the appropriate COW COPY file, see Table VIII-2. *

IBM/C Source Code Statements

To reference the Geosupport MSW COPY file IBM/C programs must contain the following statement:

#include

In the following C source code examples, the letter ‘L’ appears in upper case to facilitate distinguishing it from the numeric character ‘1’.

For C programs that will be executed in the batch environment and that use the Geosupport COPY file, API calls are coded as follows:

CICS programs issue calls as above but with GOAIDRV in place of GBI.

(Note: for either a batch or a CICS C program, the Geosupport driver (GBI or GOAIDRV respectively) must be declared as an external entry point. (See Section VIII.3.)

To reference the Geosupport COW COPY files include the PAC COPY file instead of the WAC COPY file. Note that in the COW format, there is no long WA2 for Functions 1, 1E, and 3. Note, also, that there are additional function options in the COW format.

NATURAL Source Code Statements

NATURAL Source Code Statements NATURAL programs reference Geosupport MSW LDAs by containing one or more of the following statements in DEFINE DATA:

For NATURAL MSW programs that will be executed in the batch environment and that use the Geosupport COPY files (LDAs), API calls are issued as follows:

CICS NATURAL programs issue calls as above but with GOAIDRV in place of GBI.

Natural COW NATURAL programs reference Geosupport COW LDAs by containing one or more of the following statements in DEFINE DATA:

For NATURAL COW programs that will be executed in the batch environment and that use the Geosupport COPY files (LDAs), some samples of API calls follow:

Note that there are additional function options in the COW format.

* To choose the appropriate COW COPY file (P2NATxxx), see Table VIII-2. *

CICS NATURAL programs issue calls as above but with GOAIDRV in place of GBI.