General Rules

  1. You must load the DLL to call it's function. (Even if it is already loaded by the system, you must implement it.) There are three ways to load a DLL in ACUCOBOL-GT: you can CALL it, use the "-y" runtime option, or use the SHARED_LIBRARY_LIST configuration variable. These are described fully in the section Calling DLLs from COBOL of this chapter.
  2. If you CALL a DLL, you can enter any of the following: 
    CALL "MyDll"
CALL "MyDll.dll" 
CALL "C:\MyDir\MyDll.dll"

    We recommend the middle option. The last won't work if your system is mobile. If you set CODE_PREFIX, the runtime looks for the DLL in the CODE_PREFIX directory. If it is not found, it also tries the Windows system directory.

  3. You must indicate the DLL calling convention in your COBOL program. The vast majority of the time, the convention for Windows API DLLs is WINAPI also known as stdcall. You can specify calling conventions in ACUCOBOL-GT in several ways:
    • Using the DLL_CONVENTION variable. To indicate WINAPI/stdcall, you would set DLL_CONVENTION to "1".
    • Using the SHARED_LIBRARY_LIST variable
    • In the CALL statement for individual library functions
    • Setting the CODE_MAPPING variable to "1", then using configuration entries to specify the calling convention for individual functions
    • Using the "-y" runtime option

      See Loading DLLs with the CALL Statement for a description of the nuances of specifying calling conventions.

  4. You must indicate "A" or "W", ANSI/wide, in the function name if both ANSI and Unicode versions of the function are available. See Microsoft Documentation for a more detailed description.
  5. You must adhere to case sensitivity of the function name.
  6. You must terminate any strings that you pass to a function. Use x"00" (LOW-VALUES) as in the following examples: 
    STRING "My example" LOW-VALUES DELIMITED BY SIZE INTO target-string.

    or

    INSPECT target-string REPLACING TRAILING SPACES BY x"00".
  7. Do not use literals with Windows functions.
  8. You must map your ACUCOBOL-GT handle to the Windows handle. For example: 
    INQUIRE acuhandle SYSTEM HANDLE IN syshandle

    Then "syshandle" can be passed on to the Windows API function. You declare the handle in Working-Storage like this:

    77 syshandle USAGE PIC X(4) COMP-N.
  9. You should cancel the DLL when finished using it. For example: 
    CANCEL "mydll.dll".

    Note that DLLs loaded with "-y" or SHARED_LIBRARY_LIST cannot be cancelled or unloaded.

  10. Always pass string variables BY REFERENCE. In C, BY REFERENCE is indicated by an "&". You can also use BY REFERENCE when the data type is prefixed with LP, as in LPSTR.

    You can pass a numeric value BY REFERENCE or BY VALUE, depending on how the function is implemented. See Microsoft Documentation for more information.

    CALL a function BY CONTENT to make a copy of it and provide an address to the copy. This lets users read, not modify, content.

  11. Most Windows API functions return only "true" or "false" when they succeed or fail. You must call GetLastError for specific reasons.
  12. Whatever memory you allocate via ACUCOBOL-GT's M$ALLOC routine, it is your responsibility to release/free via M$FREE.
Parent topic: Calling a Windows API Function from ACUCOBOL-GT