   =========================================================================
                          M I C R O   F O C U S
                        S E R V E R  E X P R E S S
			   Release 5 rev 0 

                           Running Under The Linux
                        Operating System Version 2.6.5-7.191
   =========================================================================


Using SCAN64 to detect POINTER abstraction violations
-----------------------------------------------------

A POINTER in COBOL is a unknown-sized item that may only be 
operated on as a POINTER.   Direct or indirect treatment of 
POINTER data-items as non-POINTER data-types is a violation 
of the POINTER 'abstraction'.  Detecting and correcting these
violations is critical in migrating your COBOL source code to 
64 bit based COBOL systems.

The 32 bit to 64 bit migration tool SCAN64 was developed in 
order to aid detection of references to data-items defined 
as POINTERs, in ways that are inconsistant with POINTER usage.  

SCAN64 is meant to be run in the context of a Server Express 32 bit
development environment on a 32 bit application that has been 
compiled for animation.  Running SCAN64 and addressing all issues
is an important preparation for migrating 32 bit applications 
to 64 bit compilation and runtime environments.

This tutorial describes five demonstration uses of SCAN64 on simple 
example programs.  These simple examples are meant to be a 
representantive selection of bad coding practices in user applications
and once you can recognize the problems described here, your 
analysis of your own applications will be much easier (and your
future code will be 64-bit proof).

Modification of POINTERs by implicit redefinition.
--------------------------------------------------
   Run SCAN64 with no parameters to get help screen:
	  cobscan64

   Demo1.cbl is a simple cobol program that has some bad pointer ops:
	  cat demo1.cbl
	  cob -a demo1.cbl 

   The default run of SCAN64 on this program:
      	  cobscan64 demo1

   produces:
          Processing file 'demo1.int'
          **Unsafe modification of pointer at (file: demo1.cbl, line: 9)
	    Pointer  : PP (file: demo1.cbl, def: 6)
	  Finished   file 'demo1.int' - pointer problems could exist

   If you look at the source for demo1.cbl, you'll see the following
   code at line 9:
   		move low-values 	to ppg.

   This modification of the group item containing the pointer 'pp' 
   is unsafe, as the memory occupied by the pointer 'pp' is treated 
   as an AlphaNumeric.  In this case, since low-values is being
   moved, no remediation is really needed.  A purist would change 
   the code at line 9 to:
	       set pp to null

   Due to the nature of COBOL, identifying the source of modification
   of a pointer is sometimes a bit difficult.  To aid in the 
   identification of the modifier the '-m' option is provided. 

   The demo1 program run under SCAN64 with the -m option, as follows:
      	  cobscan64 -m demo1

   produces:
          Processing file 'demo1.int'
          **Unsafe modification of pointer at (file: demo1.cbl, line: 9)
	  Modifier : PPG (file: demo1.cbl, def: 5)
	  Pointer  : PP (file: demo1.cbl, def: 6)
	  Finished   file 'demo1.int' - pointer problems could exist

   		
Possible modification via CALL statements and prototypes
--------------------------------------------------------
   This demo shows how prototypes area used to validate the passing
   of pointers parameters on CALL statements and to avoid reporting
   messages if compliance of parameters is found.

   Take a look at the source code:
      cat demo2.cbl
      cob -a demo2.cbl 

   Here, without prototypes we don't know anything about CBL_ALLOC_MEM
   or CBL_FREE_MEM - any pointers provided to these routines are 
   effectively redefined to alphanumeric.  You can see this with:
      cobscan64 demo2

   which produces:
      Processing file 'demo2.int'
      **Possible unsafe modification of pointer in a 'BY REFERENCE' parameter
      **in CALL 'CBL_ALLOC_MEM' statement at (file: demo2.cbl, line: 8)
        Pointer  : PTR (file: demo2.cbl, def: 5)

      **Possible unsafe reference of pointer in a 'BY VALUE' parameter
      **in CALL 'CBL_FREE_MEM' statement at (file: demo2.cbl, line: 11)
        Pointer  : PTR (file: demo2.cbl, def: 5)
      Finished   file 'demo1.int' - pointer problems could exist

   However, if we take the prototype file "demoproto.cpy" 
   which defines the APIs CBL_ALLOC_MEM and CBL_FREE_MEM, then:
   	  cobscan64 -t demoproto.cpy demo2

   this produces:
      Processing file 'demo2.int'
      Finished   file 'demo2.int' - pointer usage is OK

   We find that no messages are generated because SCAN64 then knows
   that CBL_ALLOC_MEM and CBL_FREE_MEM are expecting pointers to 
   be passed into them and there is no danger of them being treated
   as fixed size alphanumeric.


Explicit and Implicit definitions of POINTERs in CALL prototypes
----------------------------------------------------------------
   This demo shows how prototypes are used to create implicit
   definitions of pointers within the scanned programs and how
   incompatible parameters are reported.

   Again take a look at the source code for demo:
	  cat demo3.cbl
	  cob -a demo3.cbl 

   The parameter to pay attention to is the 'ptrnum-g' group item.
   Without prototypes for the various calls used within this program
   this source file will pass through SCAN64 just fine:
   	  cobscan64 demo3

   giving:
	  Processing file 'demo3.int'
	  Finished   file 'demo3.int' - pointer usage is OK

   However with prototype it doesn't quite pass through:
   	  cobscan64 -m -t demoproto.cpy demo3

   giving:
	Processing file 'demo3.int'
	**Possible unsafe modification of 'BY REFERENCE' pointer parameter
	**in CALL 'CBL_ALLOC_MEM' statement at (file: demo3.cbl, line: 10)
	  Modifier : PTRNUM-G (file: demo3.cbl, def: 5)
	  Pointer  : MEM-PTR a formal parm 
	  		(file: demoproto.cpy, def: 17, ref: 29, no: 1)
		     in CALL prototype of CBL_FREE_MEM 
		     	(file: demoproto.cpy, def:28)
		     as implicitly def'd by CALL at (file: demo3.cbl, line: 10)

	**Possible unsafe modification of 'BY VALUE' pointer parameter
	**in CALL 'CBL_FREE_MEM' statement at (file: demo3.cbl, line: 13)
	  Modifier : PTRNUM-G (file: demo3.cbl, def: 5)
	  Pointer  : MEM-PTR a formal parm 
			(file: demoproto.cpy, def: 17, ref: 29, no: 1)
		     in CALL prototype of CBL_FREE_MEM 
		     	(file: demoproto.cpy, def:28)
		     as implicitly def'd by CALL at (file: demo3.cbl, line: 13)

	**Unsafe modification of pointer at (file: demo3.cbl, line: 17)
	  Modifier : PTRNUM (file: demo3.cbl, def: 6)
	  Pointer  : MEM-DUMMY-PTR 
	  		(file: demoproto.cpy, def: 19)
		     of formal parm MEM-DUMMY-PTR-G 
		     	(file: demoproto.cpy, def: 18, ref: 32, no: 1)
		     in CALL prototype of CBL_DUMMY_ALLOC_MEM 
		     	(file: demoproto.cpy, def:31)
		     as implicitly def'd by CALL at (file: demo3.cbl, line: 15)

	Finished   file 'demo3.int' - pointer problems could exist

   There are two kinds of warning that we find here.

   First at line 10 and 13, the calls to CBL_ALLOC_MEM and CBL_FREE_MEM
   expects a pointer directly, they are instead being provided a group
   item containing a pic x(4).  This essentially redefines the formal
   parameter pointer MEM-PTR as an Alphanumeric and is a source code 
   problem.  If pointers are expected by an API, then pointers must 
   be provided.

   At line 17, the problem is a bit more complicated, though the 
   reason is roughly the same as in the first two cases.

   The reported problem stems from the call at line 15, where the
   call to 'CBL_DUMMY_ALLOC_MEM' expects a group item containing
   a pointer, however the caller is actually passing in a group item 
   containing a pic x(4).
   
   Because of the 'messy' nature of group definitions and redefinitions
   within them, this is not reported directly, instead SCAN64 creates 
   an implicit pointer definition at the data location in the user's 
   program that the call prototype would have expected a pointer to 
   be defined.  Any operations on the memory that this implicitly 
   defined pointer occupies that are not consistant with pointer 
   usage are then flagged as needing attention..

   Specifically, the statement at line 17 is an invalid modification
   of the implicitly defined pointer's memory location. 


Constant and variable indexing
------------------------------
   This demo shows how indexing is detected and reported, with 
   an example of how statically indexing compares with dynamic/variable
   indexing.

   Take a look at the source code for demo:
	cat demo4.cbl
	cob -a demo4.cbl 

   In this program, the record structure is such that:
        - item1-1(2) and item1-3(2) are redefined by 
	  ptr2-notmod-1 and ptr2-notmod-2, respectively
   and  - item1-2(2,1) and item1-2(2,2) are redefined by
	  ptr2-mod-1 and ptr2-mod-2

   Running this through SCAN64:
	cobscan64 -m demo4

   Yielding:

	Processing file 'demo4.int'
	**Unsafe modification of pointer at (file: demo4.cbl, line: 26)
	  Modifier : ITEM1-2 (file: demo4.cbl, def: 13)
	  Pointer  : PTR2-MOD-1 (file: demo4.cbl, def: 18)

	**Unsafe modification of pointer at (file: demo4.cbl, line: 27)
	  Modifier : ITEM1-2 (file: demo4.cbl, def: 13)
	  Pointer  : PTR2-MOD-1 (file: demo4.cbl, def: 18)

	**Unsafe modification of pointer at (file: demo4.cbl, line: 27)
	  Modifier : ITEM1-2 (file: demo4.cbl, def: 13)
	  Pointer  : PTR2-MOD-2 (file: demo4.cbl, def: 19)

	Finished   file 'demo4.int' - pointer problems could exist

   We get no reports on prt2-notmod-[12], however the static indexing
   for item1-2 at line 26 produces a warning of unsafe modification 
   for ptr2-mod-1, and the run-time indexing of item1-2 at line 27
   produces warnings for both ptr2-mod-1 and ptr2-mod-2 (since it is 
   variable indexing we cannot determine statically what pointers 
   are really affected).
        

Constant and variable reference modification
--------------------------------------------
   This demo shows how static and dynamic reference modification
   is detected and reported.

   Take a look at the source code for demo:
	cat demo5.cbl
	cob -a demo5.cbl

   In this program, the record p1 is accessed via a reference 
   modification, both statically and dynamically.

   Running this through SCAN64:
	cobscan64 -m demo5

   Yielding:
	Processing file 'demo5.int'
	**Unsafe modification of pointer at (file: demo5.cbl, line: 12)
	  Modifier : P1 (file: demo5.cbl, def: 6)
	  Pointer  : PTR2-1 (file: demo5.cbl, def: 8)

	**Unsafe modification of pointer at (file: demo5.cbl, line: 13)
	  Modifier : P1 (file: demo5.cbl, def: 6)
	  Pointer  : PTR2-1 (file: demo5.cbl, def: 8)

	**Unsafe modification of pointer at (file: demo5.cbl, line: 13)
	  Modifier : P1 (file: demo5.cbl, def: 6)
	  Pointer  : PTR2-2 (file: demo5.cbl, def: 9)

	**Unsafe modification of pointer at (file: demo5.cbl, line: 14)
	  Modifier : P1 (file: demo5.cbl, def: 6)
	  Pointer  : PTR2-1 (file: demo5.cbl, def: 8)

	**Unsafe modification of pointer at (file: demo5.cbl, line: 14)
	  Modifier : P1 (file: demo5.cbl, def: 6)
	  Pointer  : PTR2-2 (file: demo5.cbl, def: 9)

	Finished   file 'demo5.int' - pointer problems could exist

   We see that the first static reference modification at 
   line 11 pass through fine (correctly), however the second 
   static ref mod at line 12 will overwrite the first byte of
   ptr2-1 and so is reported as a violation.
   In the following cases at line 13 and line 14, at check time
   we have no idea of the contents of the variable 'refm' so 
   any pointer within the record 'p1' could be changed, so 
   SCAN64 reports possible violations of the two pointers
   ptr2-1 and ptr2-2 at these lines.



   =========================================================================
   Copyright (C) 1984-2001 Micro Focus International Ltd.    All rights reserved.
   @(#)scan64.txt.app	2.1
   =========================================================================
