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++.  While it may provide insight to other applications and platforms, it is not directly applicable to them.  It has not been tested on Windows Vista.

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 program calling PowerCOBOL sheets.
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.

System Program Units:

1. Fujitsu COBOL 3.0 program units:
   • Main Program
     For this example, the main program is AMSWIN.  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.
   • 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)
   
   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:
     
     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.
     
     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.
   
   
3. USPS Components:
   • Address Matching System Application Programming Interface (AMS API)
     USPS Developer's Kit containing functions for checking the integrity of an address, determining ZIP+4, and mailing list validation.

_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