Model 204
Using the External Call Facility
By James Damon
Invoking External Applications from User Language
Suppose a COBOL application exists, either written by someone in your organization or available from an outside source. You would like to use this application to verify account numbers, addresses, or something similar. The application might even return the geographic coordinates, the latitude and longitude associated with a street address, using its own proprietary database. The data that you want to pass to this application is stored in a Model 204 file; it is accessed and maintained by various User Language applications. However, the COBOL application was not written to access a Model 204 file.
Introducing the Version 5.1 External Call Facility
If this COBOL application or any other external application is written to support standard parameter passing, then an OS/390 or z/OS site can invoke the application from Model 204 V5R1 User Language even though it was not written to access a Model 204 file. This new feature is named the External Call Facility (ECF). In addition to COBOL, external applications can be written in PL/I, C, PASCAL, FORTRAN, or assembly language.
Using ECF you can invoke an external application from User Language and pass data from User Language to the external application via User Language images. Data in those images can be modified by the external application and returned to the User Language program via the original image or images. The external application may also read and write external, non-Model 204 files during its processing. When applications such as these are available, either from third-party vendors or from other departments or entities within your organization, the ECF feature provides an important way of extending the power of Model 204 beyond User Language.
Preparing to use ECF
To prepare your Online to use an external module, the application in Figure 1 is run once by USER0 or another authorized user to define and load the module. Once this is done any user can invoke the external module by using the EXTERNAL CALL statement.
Figure 1. Preparing a module for ECF
BEGIN * The next statement defines the external module EXTERNAL MODULE ECFCOBOL DDNAME=your.loadlib.dsname CALL CHECK('MODULE ECFCOBOL') * The next statement loads the external module EXTERNAL LOAD ECFCOBOL CALL CHECK('LOAD ECFCOBOL') SUBROUTINE CHECK(%FUNC IS STRING LEN 20) IF $STATUS NE 0 THEN PRINT %FUNC WITH $STATUS AT 20 WITH $STATUSD AT 30 PRINT ' FROM $ECFSTAT: ' WITH $ECFSTAT END IF END
The new parameters and statistics introduced in Model 204 to support ECF are documented in the Version 5.1 manuals:
Using ECF
Figure 2 is an example of a simple User Language program, which invokes a simple external COBOL application, previously defined and loaded by the program in Figure 1, to validate an account number using ECF.
Figure 2. Invoking a COBOL application via ECF
PROCEDURE ECFTEST BEGIN IMAGE PARMS HALFWORD IS BINARY LEN 2 ALIGN ACCTNO IS STRING LEN 10 RESULT IS STRING LEN 20 END IMAGE PREPARE IMAGE PARMS %PARMS:ACCTNO = $READ('ACCTNO?') * The next statement invokes the external application EXTERNAL CALL ECFCOBOL WITH PARMS CALL CHECK('CALL ECFCOBOL') IDENTIFY IMAGE PARMS PRINT 'RESULT: ' WITH %PARMS:RESULT SUBROUTINE CHECK(%FUNC IS STRING LEN 20) IF $STATUS NE 0 THEN PRINT %FUNC WITH $STATUS AT 20 WITH $STATUSD AT 30 PRINT ' FROM $ECFSTAT: ' WITH $ECFSTAT END IF END T REQUEST END PROCEDURE
Examining the external COBOL application
The source code in Figure 3 is the external COBOL application, which validates an account number and verifies that it starts with the character string, ABC. The application returns GOODACCT, if true, or BADACCT, if false. This application was compiled and link edited into an APF load library and the resulting load module was named ECFCOBOL.
Figure 3. Examining the ECFCOBOL application
IDENTIFICATION DIVISION. PROGRAM-ID. ECFCOBOL. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. DATA DIVISION. WORKING-STORAGE SECTION. 01 MISC. 05 FIRST3 PIC X(3). LINKAGE SECTION. 01 COBPARMS. 05 HALFWORD PIC X(2). 05 ACCOUNTNO PIC X(10). 05 RESULT PIC X(20). PROCEDURE DIVISION USING COBPARMS. MAIN-LINE SECTION. MOVE ACCOUNTNO TO FIRST3. IF FIRST3 IS EQUAL "ABC" THEN MOVE "GOODACCT" TO RESULT ELSE MOVE "BADACCT" TO RESULT END-IF. EXIT. GOBACK.
From a Model 204 terminal session, you would invoke the User Language procedure ECFTEST and see results similar to those in Figure 4.
Figure 4. Interacting with the COBOL application from Model 204
INCLUDE ECFTEST $$ACCTNO? 1531325 RESULT: BADACCT CPU=0.175 CNCT=3603 DKRD=13 DKWR=81 SQRD=137 SQWR=282 NTBL=3 QTBL=32 STBL=151 VTBL=9 PDL=564 FSCB=128 CNCT=5 CPU=4 OUT=3 - IN=1 RQTM=1470 DKPR=1 ECLOAD=1 ECCALL=1 ECCNCT=1197
INCLUDE ECFTEST $$ACCTNO? ABC1235 RESULT: GOODACCT CPU=0.180 CNCT=3664 DKRD=13 DKWR=81 SQRD=139 SQWR=287 NTBL=3 QTBL=32 STBL=151 VTBL=9 PDL=564 FSCB=128 CNCT=5 CPU=4 OUT=3 - IN=1 RQTM=1393 DKPR=1 ECLOAD=1 ECCALL=1 ECCNCT=1182
Summary
This simple example merely introduces what will be for many customers a very powerful and robust feature whose ease of use and flexibility are demonstrated in this article. A complete description of the feature along with the parameters and statistics associated with it can be found in the previously mentioned manuals. Additional examples are also included in the manuals.
CCA Education
Take a Class This Spring!
For those of you living in or visiting the United Kingdom this spring, have a look at the Model 204 classes schedule offered by our office in Slough, Berkshire, England.
For those of you living in or visiting the United States this spring, have a look at the Model 204 classes schedule offered by our office in Framingham, Massachusetts, USA.
No matter where in the world you work, if enough people at your site want to take a CCA product class, a CCA instructor can bring the class to you.
If you are training a new employee in System 1032, and would like them to have formal instruction, please contact System 1032 Customer Support.
To make customized class arrangements, please Contact Education Services.
System 1032
News and Announcements
By Tym Stegner
In this article I will highlight and announce several maintenance software and documentation updates that are of interest to System 1032 customers.
System 1032 MAIL TOOLS Documentation
The documentation for System 1032 Mail Tools that was mentioned in the February 2003 edition of CCAPRINT for the System 1032 Mail Tools interface is now available on the S1032 FTP server at FOX.CCA-INT.COM. After you log on to the Anonymous account, change the directory to [.CCAPRINT] to access the PDF file.
System 1032 V9.81-1 Maintenance Release
CCA is pleased to announce a maintenance release of System 1032, V9.81-1! System 1032 V981-1 requires a minimum of OpenVMS V7.1.
In addition to product maintenance this release also provides two new features:
The updated Release Notes for System 1032 V9.81-1 will be available soon in the root directory on the FOX.CCA-INT.COM FTP site.
ODBC Driver V041 Maintenance Release
CCA is also pleased to announce the release of System 1032/ODBC Driver V041!
The System 1032 ODBC Driver V041 requires a minimum of System 1032 V9.80 and at least OpenVMS V7.1. The ODBC Driver, dictionary, or data source updates are not required.
Highlights included in the release are:
A new feature of the V041 release is the ability of the ODBC server to write its own errors to a log file, similar to the S1032_ERR log file for the base system. To activate the feature, define the logical S1032ODBC_ERR to a file.
The updated Release Notes for ODBC Driver V041 will be available soon in the ODBC subdirectory on the FTP.CCA-INT.COM FTP site.
FTP Hardware Upgrade
The System 1032 FTP server itself was upgraded from a microVAX-II to an Alpha AXP-150 (code-named Jensen, the first-released, smallest horsepower Alpha). Now System 1032 Customer Support can run the CSWS web server from this machine. Please contact us via email with any suggestions for System 1032 web-based content to:
Copyright © 2008 Computer Corporation of America. All right reserved. Published in the United States of America.
Copyright 2008
