dos_compilers/Microsoft Cobol v5/DOCS/README.DOC

  		    	  README.DOC

	    	Microsoft(R) COBOL, Version 5.0
	    (C) Copyright Microsoft Corporation, 1993


  This document contains essential information for version 5.0
  of the Microsoft COBOL Professional Development System for 
  MS-DOS(R) and Microsoft(R) Windows.  The information in this 
  document is more up-to-date than the printed documentation.

  See the DOCUPDT.DOC file for information on printed documentation 
  corrections (located in the \COBOL\DOCS sub-directory). 

========================< CONTENTS >=================================

  This file contains information on product usage and 
  restrictions organized as follows: 

	NEW FEATURES

	INSTALLATION

	PROGRAMMER'S WORKBENCH

	COMPILER AND LINKER

	ANIMATOR

	CODEVIEW

	SAMPLE PROGRAMS

	MISCELLANEOUS


===================================================================
  NEW FEATURES
  ============

  Improved Support for Microsoft Windows 3.x
  -------------------------------------------
	o  Shared run-time system (COBLIB) is now supported under
	   Windows 3.x.  The run-time system is provided as COBLIB.DLW.
      
  	o  Because the COBOL compiler uses COBLIB itself, this means 
	   that the compiler, Animator, etc., will be able to run as 
	   Windows applications, making use of extended memory. 
 
 	o  QuickWin support is now provided in a DLL. This means that
           	   dynamically called sub-programs can now make use of all
           	   COBOL screen handling techniques.

	o  COBOL 5.0 provides support for interoperability with
	   Microsoft Visual Basic 2.0 for Windows. You can write
	   Visual Basic Graphical User Interfaces and call COBOL DLL's.
	   For additional information, see the COBOL Programming for 
	   Windows book, Chapter 4 "Building Visual Basic 
	   Applications."
 
 
  Animator Improvements
  ---------------------
	o  Ability to monitor many data items. Each item is displayed 
	   in its own window on the screen.
 
	o  The "Watch" statement. This effectively performs a Step command,
	   but also displays the contents of all data items used in the
	   COBOL statement before and after execution of the Step. This saves
	   the user from having to manually query the data items used in the
	   statement.
 
	o  Set a breakpoint on a data-item, so that if the contents of the
	   data-item changes, execution of the program will stop on the
	   statement that changes the data-item.
 
	o  Set a breakpoint on a COBOL statement and specify several lines
	   of code to be executed when the breakpoint is encountered (allows
	   temporary patching of the code - the source file is not changed).
 
	o  A "base" Animator is also provided for low memory situations 
	   (ANIMBASE.EXE).
 
 
  PANELS Character Window Tool
  ----------------------------
	PANELS allows applications to create multiple windows on 
	character mode screens. Support is also provided to allow 
	ACCEPT/DISPLAY statements to be sent to the different Windows.
	This allows easier development of pull-down menus, pop-up 
	windows, etc. on character mode screens.
 
 
  Extfh/BTrieve Interface
  -----------------------
	New modules are being provided to allow programs that use standard
	COBOL file handling syntax to access BTrieve files. Another module
	is provided to allow programs that make calls to BTrieve to access
	indexed-sequential files created using the standard COBOL file
	handler (EXTFH). 
 
  COBOL Syntax Enhancements
  -------------------------
	There have been various COBOL syntax enhancements, mostly based 
	on the CODASYL Journal of Development, including:
 
	o  EVALUATE statement extended
	o  PERFORM UNTIL EXIT
	o  SET condition-name TO FALSE
	o  READ WITH WAIT
	o  READ WITH IGNORE LOCK
	o  ACCEPT/DISPLAY WITH UPPER/LOWER
	o  "C" and "R" accepted as currency signs
	o  VALUE clause extended to include "LENGTH OF identifier",
	o  "ADDRESS OF identifier" and AND'ing and OR'ing of numbers
	   (used for programming for GUI environments).
 
  Mainframe Compatibility Enhancements
  ------------------------------------
	o  Support for the DOS/VS COBOL dialect.
	o  Mainframe compatible arithmetic. A new directive has been added
                   to provide mainframe compatible results in arithmetic statements.
                   The difference is in the way intermediate results are stored 
	    during arithmetic statements.
	o  Mainframe file status codes are now supported.
	o  Obtain record length information for FILE SECTION records via
           	    negative subscripting (a common mainframe technique).
	o  Improved support for OSVS perform behavior.
 
 
  Western National Language Standards Supported
  ---------------------------------------------
	The "NLS" compiler directive has been provided to indicate that a
	program should use a specified language/territory/codepage. The
	program then uses the appropriate characters and collating sequences
	for currency signs, decimal and thousands separator and comparisons.
 
  Performance Improvements
  ------------------------
	There have been improvements in the speed and size of the code
	output by the compiler. The main performance improvements
	come from the following:

	o  Better use of 80x86 registers, leading to a general
	     20% improvement in computational operations.
	o  Speed of access to linkage section has been doubled 
	     in programs with greater than 64K of data.
	o  Improvement in CALL performance.
	o  40% speed improvement in accessing tables greater than 64K.
	o  Improvement in SEARCH performance.
	o  Improvements in file-handling performance.
	o  Use of the XM DOS Extender can improve performance of 
	     larger programs.

 
  Other Enhancements
  ------------------
	o  The compiler can now output assembler listings in a form that
                   can be input to MASM if required.
	o  Environment variables can be set up in a text file, therefore 
	    reducing the amount of DOS environment space that is needed. 
	    The variables can be read and written by COBOL programs.

  New Call-by-Name Routines
  -------------------------
       o  CBL_EXIT_PROC
       o  CBL_SUBSYSTEM
       o  CBL_COPY_FILE
       o  CBL_GET_SCR_LINE_DRAW
       o  CBL_GET_OS_INFO
       o  PC_FIND_DRIVES

  XM DOS Extender
  ------------
	o  Enable your applications to exceed the 640K DOS memory limit.
	o  Enables up to 16MB of extended memory to be made available to 
	   your application.
	o  Supports VCPI, DPMI and XMS protocols.
	o  No need to modify your programs, simply recompile and relink.

  Updated Windows 3.1 components
  ------------------------------
	o  Image Editor:  
	   With Image Editor (IMAGEDIT.EXE), you can create graphical 
	   images to represent files, windows, cursors, and other 
	   objects in your Windows applications.
	o  Dialog Editor:  
	   With Dialog Editor (DLGEDIT.EXE), you can visually design and 
	   test a dialog box on your screen instead of programmatically 
	   using DIALOG statements in your resource-definition file.
	o  Font Editor:  
	   With Font Editor (FONTEDIT.EXE), you can modify existing 
	   fonts to create new fonts for your applications.
	o  Resource Compiler:  
	   With Resource Compiler (RC.EXE) you can compile your Windows 
	   resource files and resource-definition files for inclusion 
	   in Windows .EXE's and .DLL's.

  Codeview 4.05 Debugger
  ----------------------
	Supports debugging of mixed language DOS applications including 
	Cobol, C, and MASM.


===================================================================
  INSTALLATION
  ============

  Installing HIMEM.SYS
  --------------------
	For best results, LINK requires HIMEM.SYS (which is supplied
	with COBOL 5.0 but not installed by Setup). If HIMEM.SYS 
	(or some other memory manager) is not already installed on 
	your computer, follow these instructions:

	1.	Verify that HIMEM.SYS is located in the \COBOL\BIN
		directory and that \COBOL\BIN is included in the
		PATH statement in your AUTOEXEC.BAT file.

	2.	Add this statement to your CONFIG.SYS file:
	
		DEVICE = C:\COBOL\BIN\HIMEM.SYS

		The DEVICE command for HIMEM.SYS enables the use of 
		extended memory. Therefore, this command must appear 
		in your CONFIG.SYS file before any commands that 
		start device drivers, or programs that use extended 
		memory such as EMM386.EXE.

  Path Length
  -----------
	For best results, install the default \COBOL directories.
	If you choose other installation directory paths, choose
	paths of reasonable length.  Some directory paths are added
	to the PATH statement in your AUTOEXEC.BAT, which is limited
	to 128 characters.  

  Path Statement Characters
  -------------------------
	Do not use invalid path characters, such as:

		<  >  *  "  '

	in the Setup utility. 

  Source and Target Drive Specification
  -------------------------------------
	Do not specify invalid drives when prompted for the
	installation source drive or destination drive in the 
	Setup utility.

  Using NEW-VARS.BAT
  ------------------
	After the initial installation of COBOL 5.0, any subsequent
	installations will create a new NEW-VARS.BAT.  This may
	delete needed statements from the original file.  If you
	re-install COBOL 5.0, make a backup of NEW-VARS.BAT to
	merge with the new file.


===================================================================
  PROGRAMMER'S WORKBENCH
  ======================

  Segmented Programs
  ------------------
	Segmented COBOL programs cannot be run from PWB.

  Using Library Routines (call-by-name) for Mouse
  -----------------------------------------------
	Do NOT use the mouse support Library Routine CBL_TERM_MOUSE 
	under PWB for builds using Shared Runtime System (this call 
	is handled by the runtime system).  Use of this call under PWB 
	may cause your system to hang.

  Windows .DLL Projects
  ---------------------
	If you debug a Windows .DLL project, to change from the 
	debug build options to the release build options, do the 
	following:

	1. Close the debug project you are working on.
	2. Choose "Use Release Option" from the Build Options dialog
	     box.
	3. Create a new project (.MAK file) for the Windows .DLL
	     using the release options.


===================================================================
  COMPILER AND LINKER
  ===================

  ANSI Standard for String Literals
  ---------------------------------
	The ANSI Standard for string literals rule is enforced 
	in COBOL version 5.0. COBOL versions 4.5 and earlier 
	did not enforce this rule. For this reason, programs 
	compiled with earlier versions of COBOL that do not 
	conform to this rule may produce a syntax error. 

	For more information and the exact wording of this 
	ANSI rule, see the "Continuation of Lines" section in
	the COBOL Language Reference book Chapter 2, page 77.

  By-Value Parameter Passing in CALL Statements
  ---------------------------------------------
	Dynamically linked COBOL programs cannot pass parameters by
	value, only by reference.  Statically linked COBOL 
	Programs can pass parameters either way. 

  Sequential File Data Compression 
  --------------------------------
	To compress data in a sequential file, you must compile
	using the CALLFH directive.

  Using WINDOWS.78 in a COBOL Program
  -----------------------------------
	When WINDOWS.78 is used in a COBOL program, the directive 
	REMOVE(IGNORE) must be used to avoid a compiler error.  

	For an example of how to use the REMOVE(IGNORE) directive,
	refer to SYSMETS.CBL--a sample program located in the
	\COBOL\SAMPLES\WINDOWS directory.


===================================================================
  ANIMATOR
  ========

  Animating Sub-Programs
  -------------------------
	To animate a program which is called by another program, 
	you must compile using the PARAMCOUNTCHECK directive.  
	For more information, Refer to System Reference, 
	Appendix D (Directives of Compiler), page 578.

  Using Animator From PWB
  -----------------------
	If you receive a 198 error while animating under PWB, this is probably
	caused by insufficient system memory needed to load your program and
	Animator.  The best solution to this is to ensure Animator has access to
	extended memory by checking the "USE XM for COMPILE and ANIMATE"
	check box on the COBOL Compiler options screen in PWB.

	The program can also be animated from the command line.  
	In a very large program, or when using certain animator 
	functions, ANIMBASE may have to be used in place of ANIMATOR.

  Using the Cobol Compiler Icon with the ANIM directive
  -----------------------------------------------------
	1.  Click on the Cobol Compiler icon

	2.  Type the filename and ANIM directive as you would 
	    at the command line. When the compile finishes 
	    successfully, LINK is executed automatically.
  
	3.  Make LINK the active window to allow LINK to process.  

	4.  Select the OK button from the Application Terminated
	    dialog box.


===================================================================
  CODEVIEW
  ========

  Arithmetic Data Types
  ---------------------
	Comp-1, Comp-2, and External Floating Point Data Items are 
	not supported.

  Array Subscripts
  ----------------
	Index names are not supported as subscripts.

  Conditional Breakpoints
  -----------------------
	When a breakpoint expression is entered that contains
	blanks, the expression must be quoted or parenthesized.
	For instance, to use

		a + 1

	as a breakpoint expression, enter

		bp ?(a + 1)
	or
		bp ?"a + 1"

	The BP= Command (Break on change) will only accept
	single data items, such as:

		bp= b(1)
		bp= x

	Multiple-term expressions are not allowed. For example:

		bp= (a + b)
		bp= (a + 1)
		bp= (a * 5 + x(2))

	Indexed data items are allowed, but only if the index 
	is a literal:

		bp= q(5)
		bp= a(1)

  CVPACK Configuration
  --------------------
	Codeview uses CVPACK.EXE.  There are two possible versions of
	CVPACK which can be installed for use with COBOL 5.0: 

		CVPACKX.@XE and CVPACK.@XE.

	CVPACKX.@XE takes advantage of extended memory. CVPACK.@XE is 
	strictly for Real Mode use when an extended memory manager
	is NOT present.  One of these files will be installed as CVPACK.EXE,
	depending upon installation options that you choose. 

	During Setup, on the CVPACK Configuration screen, if you 
	choose "yes" to use the extended version of CVPACK, CVPACKX.@XE 
	is installed as CVPACK.EXE, and CVPACK.@XE is installed as 
	CVPACKR.EXE.  If you choose "no",  CVPACK.@XE is installed as
	CVPACK.EXE, and CVPACKX.@XE is installed as CVPACKX.EXE.

  Double-Quoted Integers
  ----------------------
	Double-quoted integers used in relational operations,
	such as:

		"5" = 5

	are not recognized.

  Numeric Literals
  ----------------
	Leading zeroes are required in decimals.  For instance, 0.01 
	is accepted as a valid numeric literal; .01 is not.

  Radix Settings
  --------------
	If n16 is set, and a data item consists completely of
	hex digits, the item will not be read as a symbol, but
	as a hex number.  For instance, the conditional breakpoint
		bp ?a
	will treat "a" as the number 10.

  Registers Window Flag
  ---------------------
	PL and NC flags are not supported in the registers window.

  Reserved Words
  --------------
	The following are CodeView reserved words, and may not be
	used as identifiers anywhere in programs which are to be
	debugged:
		main
		winmain
		entgqq
		_main


===================================================================
  SAMPLE PROGRAMS
  ===============

  MOUSMENU.CBL Program
  --------------------
	The sample file C:\cobol\samples\mousmenu.cbl should be run 
	in a full-screen DOS box in Windows. The mouse will not 
	function correctly in a windowed DOS box.


====================================================================
  MISCELLANEOUS
  =============

  386 Minimum Requirement
  -----------------------
	An 80386 or higher processor is recommended for the
	following utilities:

	PWB		Microsoft Programmer's WorkBench
	CV		Microsoft CodeView
	LINK		Microsoft Segmented Executable Linker
	EXEHDR	Microsoft EXE File Header Utility
	IMPLIB		Microsoft Import Library Manager
	LIB		Microsoft Library Manager
	NMAKE	Microsoft Program Maintenance Utility
	HELPMAKE	Microsoft Help File Maintenance Utility
	BSCMAKE	Microsoft Browser Database Maintenance Utility
	SBRPACK	Microsoft Browse Information Compactor
	CVPACK	Microsoft Debugging Information Compactor
	RM		Microsoft File Removal Utility
	UNDEL		Microsoft File Undelete Utility
	EXP		Microsoft File Expunge Utility
	WX/WXSRVR	Microsoft WX/WXServer Utility

  BTrieve
  -------
	When using BTrieve to access information on a server, 
	if the current working drive is not mapped to the server 
	that you are using, the file specification must include 
	the server path (drive letter).

	For example: If the current working drive is C and the
	server drive is F, then the "select" statement on page
	133 of the System Reference would look like this:

		select testfile-1 assign to "f:\test-1.dat"

  Conversion Utilities
  --------------------
	TABX, Convert3, and Convert5 are to be used only to
	convert files from another dialect, and will not
	run if EMM386 is installed.

  H2CPY
  -----
	Do not use H2CPY on WINDOWS.H.  The WINDOWS.78 and 
	WINDOWS.CPY files are provided in \cobol\samples\windows as correct
	conversions of WINDOWS.H.

  Microsoft C 7.0
  ---------------
	Mixed-Language programming using Microsoft C/C++ 7.0 and 
	COBOL 5.0 is possible. However, floating point data types 
	can only be used in one or the other language; not both.  
	This restriction avoids link errors caused by conflicts in 
	the C and COBOL floating point support libraries.

  User-Created Libraries
  ----------------------
	Libraries created using LIB.EXE cannot be used in the
	"lib" field of a LINK command unless the calling programs
	were compiled with the LITLINK compiler directive.
	If LITLINK is not used, the user-created libraries should
	be placed in the .OBJ field of the LINK command in order
	to be linked statically.