>> Rodney Roberts IS & Education Professional Homepage   >> Programming Tutorials And Downloads






Science makes it known,
Engineering makes it work,
Art makes it beautiful.


  Combining Fujitsu COBOL 3.0, PowerCOBOL 3.0, and the USPS Address Matching System API

This page is the next step after Using Fujitsu COBOL 3.0 to call the USPS Address Matching System API; it is presumed that the reader is already familiar with the compiling, linking, and Run-Time Environment Initialization concepts discussed on that page.  The goal is to combine Fujitsu's PowerCOBOL 3.0 Windows GUI capabilities with the USPS Address Matching System API (AMS API).   Combining PowerCOBOL 3.0 Windows GUI capabilities with the AMS API can be somewhat challenging.   This page briefly describes the major challenges and how to meet them.

This documentation only directly applies to Win32, Fujitsu PowerCOBOL 3.0, and C++.  It should provide insight to other applications and platforms, though it may not be directly applicable to them.  It has not been tested on Windows Vista, Win7.


Fujitsu's COBOL 3.0 is a conventional 3rd generation COBOL85 Win32 programming environment.   Fujitsu's PowerCOBOL is a graphical programming environment that allows COBOL programmers to develop GUI applications with event-driven structures.   Fujitsu refers to the GUI application windows as sheets.

Using Fujitsu's PowerCOBOL 3.0 Windows GUI capabilities with the USPS Address Matching System API presented two challenges:

  1. PowerCOBOL sheets calling COBOL subroutines, not C and C++ functions (as in the AMS API), is documented.   Also, ran into problems using non-default compiler options NOALPHAL and DLOAD (see Using Fujitsu COBOL 3.0 to call the USPS Address Matching System API for details) for compiling PowerCOBOL sheets.  (C++ is case sensitive; by default COBOL is case insensitive, automatically makes all identifiers and keywords upper-case).   According to the Fujitsu documentation, COBOL 3.0 programs can invoke both PowerCOBOL sheets and C++ functions.   As a workaround, use a COBOL 3.0 main program to serve as the unifying interface between PowerCOBOL sheets and the AMS API.   In other words, the main program is a non-GUI COBOL 3.0 "wrapper" (alternatively, executive or dispatcher) program coordinating the calls between the PowerCOBOL sheets and the AMS API.
  2. Using COBOL 3.0 to invoke PowerCOBOL sheets.   Could not find within the Fujitsu documentation how to successfully link COBOL 3.0 main program with PowerCOBOL sheets.   Necessary for above mentioned workaround.
The prototyped application using the AMS API will be validating and updating mailing lists at the file level.   Since the user will be primarily working at the file level (mailing lists manipulation) and not at the record level, the workaround mentioned in challenge 1 should be satisfactory.


The software design to meet challenge 1 can be summarized in the diagram below:

Software Design Diagram




System Program Units: (limited source code available for download below)

  1. Fujitsu COBOL 3.0 program units:
    • Main Program
      For this example, the main program is AMSWIN (a command console program).  When executed, it immediately displays the Main Menu PowerCOBOL sheet after initializing itself.  If the AMS API is successfully opened, the Main Menu (see below) allows access to PowerCOBOL sheets utilizing AMS API functions; otherwise access is allowed to PowerCOBOL sheets unrelated to the AMS API functions.

      Compiled with NOALPHAL (do not convert user-defined names' lower case letters to upper-case), DLOAD (Dynamic Load), MAIN (main program) options.
    • INVKSHT
      Subroutine to invoke PowerCOBOL sheets via the _POWEROPENSHEET call (_POWEROPENSHEET is a Fujitsu function).   AMSWIN determines which PowerCOBOL sheet to present to user, calls INVKSHT; INVKSHT then determines and passes parameters (DLL-NAME, SHEET-NAME) to _POWEROPENSHEET.
      001040     CALL "_POWEROPENSHEET" USING DLL-NAME
      001050                                  SHEET-NAME.
                   
      DLL-NAME is the fully qualified file name of the .DLL file containing the name of the PowerCOBOL sheet to be opened.
      SHEET-NAME is the name of the PowerCOBOL sheet (GUI application window)

      Compiled with ALPHAL, DLOAD, NOMAIN options.

      (this is an earlier version of INVKSHT available at COBOL Files - Combining Fujitsu COBOL 3.0, PowerCOBOL 3.0, Silverfrost FTN95, and Numerical Recipes: The Art of Scientific Computing; however, the values of DLL-NAME and SHEET-NAME are hard-coded in both versions and therefore incompatible)

    It should be noted that while the Fujitsu documentation recommends that both the calling program and called program be compiled with the same compiler options, it is not necessary.   Both AMSWIN and INVKSHT use different ALPHAL compiler options.  It is recommended to use the defaults for compiling and linking PowerCOBOL sheets.

  2. Fujitsu PowerCOBOL 3.0 sheets:
    • Main Menu
      Presents to user a menu of various functions to manipulate, extract, or update mailing lists.
    • Function 1
      Some function to convert mailing lists from one format to another.
      (not the focus of this discussion, shown for demonstration purpose only)
    • Function 2
      Another function to manipulate a mailing list..
      (not the focus of this discussion, shown for demonstration purpose only)
    • Function Validate Mailing List
      The central PowerCOBOL sheet for this discussion, shown below:
      Validate Mailing List User Interface
      The sheet is used to select a mailing list file, verify that it is a mailing list, and allows the user to select one of three options.   When the user clicks the validate button, control is returned to the Main Program (AMSWIN), bypassing the Main Menu.   The Main Program reads the mailing list file, passing each record (which contains a single address) to the AMS API z4adrinqSTD Address Inquiry function, as shown by the red arc in the software design diagram above.
    • Address Status (shown below, sheet title "AMS API Address Display/Correct")
      This is an important support sheet for the Validate Mailing List function.   If the AMS API z4adrinqSTD Address Inquiry function determines that an address is ambiguous or invalid, that information can be presented to the user with this sheet.
      Address Inquiry function
      The purple arc in the software design diagram above represents the flow.

    PowerCOBOL sheets receive system data through a Fujitsu predefined Linkage Section, precluding parameter passing to the PowerCOBOL sheet with the USING clause of the CALL statement.   Therefore data defined by the calling program that is to be accessed by the PowerCOBOL sheet must be declared as EXTERNAL and GLOBAL in both the calling program and the called program.

    (The predefined Linkage Section serves a similar purpose as the variable declaration in the C statement
    int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)
    or the D statement
    extern (Windows) BOOL DllMain(HINSTANCE hInstance, ULONG ulReason, LPVOID pvReserved))

    PowerCOBOL sheets compiled and linked using default options.

  3. Include Files:
    Common code used in more than one source code file.  Usually used for data declarations.  In this application, some (not all) are used as GLOBAL EXTERNAL data declarations for passing data between main program and PowerCOBOL 3.0 sheets.
    • COMDATA.COB - Mailing List Common Data (System State, Error Codes, File meta-data, etc.); GLOBAL EXTERNAL
    • CNSTNTS.COB - GLOBAL constants, defined in the DATA DIVISION, CONSTANT SECTION (CONSTANT SECTION is a FUJITSU COBOL85 extension).
    • USPSFILE.COB - Mailing List input file Select Assign statement.  Placed in ENVIRONMENT DIVISION, INPUT-OUTPUT SECTION, FILE-CONTROL.
    • USPSLIST.COB - Mailing List input File Descriptor and record layout.  Placed in DATA DIVISION, FILE SECTION.  Record layout is designed so it can be used with several different mailing list input formats; GLOBAL EXTERNAL.
    • OUTFILE.COB - Mailing List output file Select Assign statement.  Placed in ENVIRONMENT DIVISION, INPUT-OUTPUT SECTION, FILE-CONTROL.
    • OUTREC.COB - Mailing List output File Descriptor and record layout.  Placed in DATA DIVISION, FILE SECTION.  Record layout is designed so it can be used with several different mailing list input/output formats; for example, as a CSV input file to Bulk Mailer.
    • AMSZ4PRM.COB - (AMS-API-ZIP4-PARM) COBOL implementation of USPS AMS API ZIP4_PARM structure used for functions z4adrinq (...) and z4xfrinq (...).   Placed in DATA DIVISION, WORKING-STORAGE SECTION of main program or LINKAGE SECTION of COBOL 3.0 subprogram; not used in PowerCOBOL 3.0 sheets.
    • Z4GBLPRM.COB - AMS API Common Data, used to pass address data and ZIP4 call results between program units.   Placed in DATA DIVISION, WORKING-STORAGE SECTION; GLOBAL EXTERNAL.
    • STADDR.COB - Address manipulation record.   Placed in DATA DIVISION, WORKING-STORAGE SECTION; GLOBAL EXTERNAL.
    • EASBMPRM.COB - Electronic Address Sequencing parameter record.   Placed in DATA DIVISION, WORKING-STORAGE SECTION; GLOBAL EXTERNAL.
    • OSEXEC.CBL - Fields used for executing external commands.   Placed in DATA DIVISION, WORKING-STORAGE SECTION; GLOBAL EXTERNAL.   © Fujitsu Software Corporation, cannot reproduce here; consists of two 01 fields of 128 bytes each.


  4. Miscellaneous COBOL 3.0 Subprograms:
    • ADRBRKDN.COB - uses data from both COMDATA.COB (GLOBAL EXTERNAL) and STADDR.COB (GLOBAL EXTERNAL); subprogram ADRBRKDN source file contains subprograms SUBBRKDN and ADD2PREV; therefore SUBBRKDN and ADD2PREV can access ADRBRKDN's local GLOBAL variables.  Breaks full street address down into its individual components.
    • FCSVFLD.COB - uses data from COMDATA.COB (GLOBAL EXTERNAL); extract comma separated value(s) from Address Field record.
    • CSV2ICTY.COB - uses data from both COMDATA.COB (GLOBAL EXTERNAL) and AMSZ4PRM.COB (LINKAGE SECTION); copies Comma Separated Value City field to AMS API ZIP4 City field.
    • STA2CSV.COB - uses data from both COMDATA.COB (GLOBAL EXTERNAL) and STADDR.COB (GLOBAL EXTERNAL); subprogram STA2CSV contains subprograms WPLEN and WORD2CSV; therefore, WPLEN and WORD2CSV can access STA2CSV's local GLOBAL variables.


  5. USPS Components:
    • Address Matching System Application Programming Interface (AMS API)
      USPS Developer's Kit containing functions (dynamic link library ZIP4_W32.DLL) for checking the integrity of an address, determining ZIP+4, and mailing list validation.



Linking:

The answer to challenge 2 (Using COBOL 3.0 to invoke PowerCOBOL sheets) was relatively simple to find.   Use a tool of your choice (even Vernon D. Buerg's MS-DOS program LIST will do the job) to examine the various Fujitsu libraries (*.LIB), you will find that F5BBRUNS.DLL contains routine _POWEROPENSHEET.   When linking, F5BBRUNS.DLL must be included in the Linked File List.   The PowerCOBOL sheets .DLLs do not need to be included in the Linked File List (one of the parameters to _POWEROPENSHEET specifies the PowerCOBOL sheet's .DLL, as does the OPENSHEET method).   Only the main program .OBJ file, COBOL .lib files, F5BBRUNS.lib file, and the ZIP4_W32.lib file (USPS AMS API) need to be specified in the linker, as shown in the screenshot below:

WINLINK - Linking Main Program

_POWEROPENSHEET must also be defined in the entry information section of the Run-Time Environment Initialization File COBOL85.CBR.   This is the last line as shown below.

[AMSWIN]
@IconName=COB85EXE
@ScrnSize=(80,24)
@CnslWinSize=(80,24)
@CnslBufLine=100
@WinCloseMsg=ON
@EnvSetWindow=UNUSE
@AllFileExclusive=NO
@CBR_PrintTextPosition=TYPE1
@CBR_TextAlign=BOTTOM
[AMSWIN.ENTRY]
z4openSTD=ZIP4_W32.DLL
z4closeSTD=ZIP4_W32.DLL
z4adrinqSTD=ZIP4_W32.DLL
_POWEROPENSHEET=F5BBRUNS.DLL
      



ATTENTION:
When doing a Google Search for "COBOL AMS API" you may find several
references for Google Docs with the same terms and even graphics used in my
Fujitsu COBOL pages.   THE Google Docs ARE NOT MINE.   They may have
links for downloadable executable files which may or may not contain malware,
adware, or other undesirable features.   Example addresses are:
https://docs.google.com/document/d/1eeXg8lPjGBtAdP7IfE5MdebjnEE8X0W3wAyEMWw1eLo/edit?pref=2&pli=1
https://docs.google.com/document/d/1pE3ESiOnkQoowG_XvLoZgxRSXDKnPQw2Drk4EBBe2gY/edit?pref=2&pli=1
https://docs.google.com/document/d/1mjzJ_6pWqFmacRxzD5Fg7Wy7zCjxTVleghVYGsJUaGY/edit?pref=2&pli=1

Exercise Caution

 

Any and all © copyrights, ™ trademarks, or other intellectual property (IP) mentioned here are the property of their respective owners.  No infringement is intended.

Feel free to use any of the above in your project (without violating any intellectual property rights); please give credit (same idea as Copyleft).

Website is supported on DESKTOP platforms only; layout may be off when viewed using VMware running Ubuntu Linux running FireFox.

Page best viewed with Mozilla FireFox 3.6.13 (or higher), Safari 5.1.7, and Google Chrome Version 40.0.2214.94 (or higher).

NOTE - Later versions of Fujitsu PowerCOBOL may be better equipped for calling C++ functions.


Free web hosting provided by:

Award Space Web Hosting


Free Web Hosting Free Web Hosting. Free Web Hosting , & GigaRocket Web Hosting



>> Rodney Roberts IS & Education Professional Homepage   >> Programming Tutorials And Downloads