Passing Pointers in DLL Calls

Passing a pointer as a parameter of a DLL call that executes on the display host requires some special handling in code, because the pointer value refers to a memory address on the application host. In certain cases, you may safely pass a pointer BY VALUE. You may never pass a pointer BY REFERENCE.

Using M$ALLOC

The runtime knows the size of allocated memory and can pass the contents of that memory to the thin client if the pointer is returned by a call to the M$ALLOC library routine. Then, if the DLL call on the client modifies the memory, the display host returns the modified memory back to the application host. As an example, assume you have DLL routines named SetData and GetData that take size and pointer arguments. You may use the following code:

77  PTR     USAGE POINTER.
77  ITEM-1  PIC X(100).
...
  CALL "M$ALLOC" USING 100, PTR.
  CALL "M$PUT" USING PTR, "Hello World".
  CALL "@[DISPLAY]:SetData" USING 100, BY VALUE PTR.
  ...
  CALL "@[DISPLAY]:GetData" USING 100, BY VALUE PTR.
  CALL "M$GET" USING PTR, ITEM-1.
  CALL "M$FREE" USING PTR.

The application host sends the 100-byte contents of memory to the client on the CALL to SetData. After the client fills the 100 bytes of memory with GetData, it returns the contents to the server.

Using the -Zm Compiler Option

You can use a new compiler option with the Format 7 SET statement to pass pointers to client-side DLL calls. Use this option if you don't want to add the WITH MEMORY SIZE phrase for each pointer parameter in a CALL statement. If your Format 7 SET statement returns a pointer value and you compile with the -Zm option, the Compiler generates additional code that provides the runtime with the size of the item specified in the SET statement. Once the runtime has this information, it can pass the memory contents to the thin client and then retrieve the contents after the thin client modifies them. Note that the -Zm option adds runtime overhead for each Format 7 SET statement. See Procedure Division Statements in the ACUCOBOL-GT Reference Manual for information about the SET statement.

Using the CALL Statement

The USING phrase in the Format 1 CALL statement includes a size-phrase item with which you can pass the size of a memory item along with the pointer value. Use size-phrase when the runtime and the thin client cannot automatically determine the size of the memory being pointed to. This can occur if, for example, a pointer is passed through the Linkage section or is an external item. The syntax is

[ USING { [ BY {REFERENCE} ] {parameter} size-phrase ...} ...]
               {CONTENT }    {OMITTED } 
               {VALUE   }    {NULL    }

where size-phrase is:

[WITH MEMORY SIZE { =  } memory-size]
                  { IS }

memory-size is a numeric literal or data item.

As an example, assume you have pointer PTR that points to 1024 bytes of memory. You can pass this pointer to a DLL called SetData on the display host with the following code:

CALL "@[DISPLAY]:SetData" USING BY VALUE PTR 
       WITH MEMORY SIZE 1024.