Procedure

To call a Windows API function:

1. Determine the name of the desired function and the DLL containing the function by looking at Microsoft's documentation. Also determine if both ANSI and Unicode versions are supported. For example:

   Unicode:  Implemented as GetUserNameW (Unicode) and GetUserNameA (ANSI)
   Required DLL:  AdvAPI32.DLL

2. Find the parameters for the desired function in the documentation. For example, the parameters for GetUserName are:

   lpBuffer: Pointer to the buffer to receive the null-terminated string containing the user's logon name

   nSize: On input, this variable specifies the size of the lpBuffer buffer, in TCHARs. On output, the variable receives the number of TCHARs copied to the buffer, including the terminating null character.

3. In your ACUCOBOL-GT program's Working-Storage Section, create a variable for each of the Windows API function parameters. For example:

   77 user-name PIC X(40).
   77 var-size PIC 9(9) COMP-5.

4. Set the DLL calling convention for the function in your program's Procedure Division. For example:

   set environment "dll_convention" to 1.

5. Load the DLL containing the Windows API function. For example:

   Call "advapi32.dll"
   On exception go to err-load

6. Call the Windows API function. For example:

   Set var-size to size of user-name.
   call "GetUserNameA" using
   by reference user-name
   by reference var-size

   Other functions have parameters requiring the use of BY VALUE instead of BY REFERENCE. Read the Microsoft documentation carefully to make sure you pass parameters the proper way.

7. Terminate any strings that will be returned by the function. For example:

   inspect user-name replacing all low-values by space.

8. Cancel or unload the DLL if appropriate. For example:

   cancel "advapi32.dll"

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

These general steps should be enough to get you started.