CBL_MEM_VALIDATE

Validates memory allocations, monitored freed memory, and, if the operating system supports it, compacts memory heaps.
Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_MEM_VALIDATE" using by value     flags
                              by reference param
                              returning    status-code

Parameters:

flags
Using call prototype (see Key): cblt-x4-comp-5
Picture: pic x(4) comp-5.
param
Group predefined as :
01 cblt-mem-validate-param
   03 cblte-mv-version  cblt-x4-comp-5 *> pic x(4) comp-5.
   03 cblte-mv-flags    cblt-x4-comp-5 *> pic x(4) comp-5.
   03 cblte-mv-type     cblt-x4-comp-5 *> pic x(4) comp-5.
   03 cblte-mv-size     cblt-os-size   *>32-bit: pic x(4) comp-5.
                                       *>64-bit: pic x(8) comp-5.
   03 cblte-mv-address  cblt-pointer   *> pointer

On Entry:

flags
Validation control flags:
Bit 0
0 No action
1 Validate all memory allocations
Bit 1
0 No action
1 Validate all freed memory
2-30 Reserved for future use. Must be set to zero.
Bit 31
0 No action
1 Compact memory
cblte-mv-version
Parameter block version; must be zero.

On Exit:

param
Fields are set only if the routine returns 1000
cblte-mv-flags
Information flags:
Bit 0
0 cblte-mv-address not set
1 cblte-mv-address contains address of corrupted memory block
Bit 1
0 cblte-mv-address is user data address
1 cblte-mv-address is memory header address
Bit 2
0 cblte-mv-size not set
1 cblte-mv-size contains size of corrupt memory block
Bit 3
0 cblte-mv-type not set
1 cblte-mv-type contains type of corrupt memory block
Bit 4
0 Corruption in allocated memory
1 Corruption in freed memory
Bit 5
0 Corruption detected by run-time system
1 Corruption detected by operating system
Bits 6-31
Reserved for future use.
status-code
Status of operation:
0 All memory allocations are intact
1000 Memory corruption detected
1009 Invalid parameter specified

Comments:

Use this routine to validate memory allocations, monitored freed memory, and, if the operating system supports it, to compact memory heaps. Use this routine in preference to the validate memory strategy, set using the memory_strategy run-time tunable.

If you set the Compact memory flag, the routine attempts to compact memory to the extent that the operating system allows. There is no information flag setting that indicates the result.

Example:

       program-id. CblMemValidateExample as "CblMemValidateExample".

       environment division.
       configuration section.

       data division.
       working-storage section.
       01 cbl-mem-flags pic x(4) comp-5 value zero.
        01 cbl-mem-params.
           05  cbl-mem-version pic x(4) comp-5 value zero.
           05  cbl-mem-mv-flags pic x(4) comp-5 value zero.
           05  cbl-mem-mv-type pic x(4) comp-5 value zero.
           05  cbl-mem-mv-size pic x(4) comp-5 value zero.
           05  cbl-mem-mv-addr usage pointer value null.
       01 cbl-mem-return-code pic x(2) comp-5 value zero.
       01 any-key pic x.
       
       procedure division.
           
	  *Call directly setting the bits
           call 'CBL_MEM_VALIDATE' using by value H'00000001'
                                         by reference cbl-mem-params
                                   returning cbl-mem-return-code.
           display 'CBL_MEM_VALIDATE setting bits returned: '
                   cbl-mem-return-code.
           
	  *Same call using variable to set flags
       move 1 to cbl-mem-flags 
           call 'CBL_MEM_VALIDATE' using by value cbl-mem-flags
                                         by reference cbl-mem-params
                                   returning cbl-mem-return-code.
           display 'CBL_MEM_VALIDATE using variable returned: '
                   cbl-mem-return-code.
       accept any-key.
       
           goback.

       end program CblMemValidateExample.