Chapter 6: Creating 64-bit Programs

This chapter explains how you create a 64-bit program. You can create a 64-bit program from scratch, or convert an existing 32-bit program.

6.1 Introduction

Server Express 2.0 includes both 32-bit and a 64-bit versions of both the development system and Application Server. This enables you to create new 64-bit programs, or to convert existing 32-bit programs.

64-bit COBOL programs are restricted to 32-bit sizes, but have 64-bit pointers. Therefore, COBOL elements such as Data Division sizes, offsets, Procedure Divisions, and so on, are restricted to 32-bits; however, these elements are addressed with 64-bit pointers.

Server Express 2.0 works in two modes, 64-bit or 32-bit. In 64-bit mode, the development environment and tools are enabled to work with 64-bit programs

6.2 Creating 64-bit Programs from 32-bit Programs

In general, you can take a program you have created on Server Express 1.x, recompile it with the P64 Compiler directive set, and it should run without problem as a 64-bit application. There are, however, certain circumstances in which the conversion of your program won't be as simple as this. If your program uses:

• Pointers, you need to ensure that pointers are not redefined or modified by reference. There should also be no assumptions in your record definitions about the sizes of pointers.
  
  
• A File Control Description (FCD) block that has been directly coded, the program will have to be modified to use the 64-bit FCD format. 64-bit programs need an FCD control block that has a different format to that used by 32-bit applications. See the chapter File Handler API in your File Handling book for details on the FCD. See the section File and FCD Handling below for information on the FCDs supported by different versions of Server Express and Object COBOL for UNIX.

6.3 Compiling Programs

The Compiler directive P64 enables you to create a program that can be run on a 64-bit development system (such as Server Express 2.0 in 64-bit mode) or on Application Server 2.0 in 64-bit mode. If you do not use the P64 directive when you compile your program, the program can only be run on a 32-bit development system (such as Server Express 1.x, Net Express, or Server Express 2.0 in 32-bit mode), or on Application Server 1.0 or Application Server 2.0 in 32-bit mode. Therefore, if you have developed an application on a 32-bit development system, you must recompile it, with the P64 directive set, if you want to migrate it using the Server Express 64-bit development system.

The P64 directive is set by default if you compile using the cob64 command, or using the cob command with the 64-bit working mode. For information on working modes, see the chapter Working in 32-bit and 64-bit Modes in your Server Express User's Guide.

6.4 Pointers

If you compile a program using the P64 Compiler directive (referred to in the rest of this chapter as "64-bit programs") the data-type POINTER is a different size to that in programs compiled without the P64 directive (referred to in the rest of this chapter as "32-bit programs").

To help you find invalid manipulations of the data-type POINTER in your programs, use Scan64, which is described in the chapter Scan64 in your Utilities Handbook.

6.5 Single Sourcing

To aid migration and application development, the $IF statement has been extended to enable you to find out which Compiler directives have been set when your program is compiled. In particular, you can use $IF...SET to determine whether the P64 Compiler directive has been set. For details on the $IF ... SET statement, see your Language Reference.

6.6 Library Routine Prototypes

Prototypes are provided for the COBOL library routines in Server Express 2.0. These help ensure that the library routines can run correctly in a 64-bit environment. Prototyping is an accepted way to ensure that the parameters provided to a library routine are correctly typed. See the section Using the Library Routine TYPEDEFs and CALL Prototypes in the chapter Library Routines for information on how prototyping has been implemented for the library routines.

6.7 Object Code and Intermediate Code

You cannot port executable code between 32-bit and 64-bit development systems.

Intermediate code produced by the 64-bit development cannot run on a 64-bit system that doesn't support the level of code specified by the INTLEVEL"5" directive. If a 32-bit development system supports INTLEVEL"5", the system checks that the program is not 64-bit specific before running or creating it.

6.8 File and FCD Handling

The File Control Description (FCD) is a data area which contains information about the file in use. For information on the FCD, see the section File Control Description (FCD) in the chapter File Handler API in your File Handling book.

There are two different formats of the FCD that you can directly code in your application; these are known as FCD 2 and FCD 3 (FCD 1 is obsolete and should never be used in your applications). These different FCD formats are supported on the following systems:

Platform	FCD Format
	FCD 3	FCD 2
Server Express 2.0 64-bit	Y	N
Server Express 2.0 32-bit	Y	Y
Server Express 1.1 32-bit	N	Y
Server Express 1.0 32-bit	N	Y
Net Express 3.0 and earlier versions	N	Y
OCDS	N	Y

FCD 2 is not supported on 64-bit Server Express. This has the following effects on application conversion:

• Applications that use FCD structures, either through explicit declaration and creation, or by using the syntax CALL program USING filename, have to be converted to handle FCD 3 when compiled and run as a 64-bit application.
  
  
• Applications that use the FCDREG directive need to be aware that various data-items including pointers and record sizes within the FCD have different sizes, and that reference modification of these fields results in different values on a 32-bit environment and a 64-bit one.
  
  
• The copyfile xfhfcd.cpy has been changed to define an FCD 3 record if the program is compiled with the P64 directive. If the program is not compiled with the P64 directive xfhfcd.cpy, as previously, defines an FCD 2 record. The FCD 3 record is directly and unconditionally defined in the file xfhfcd3.cpy and the FCD 2 record is directly and unconditionally defined in the file xfhfcd2.cpy. For details on the xfhfcd.cpy and xfhfcd2.cpy copyfiles see the chapter File Handler API in your File Handling book

6.8.1 Single Sourcing and Dual FCD Support

All system components supplied with the 32-bit development system support FCD 2 and FCD 3. System components supplied with the 64-bit development system only support FCD 3; no system components can support FCD 2, due to the incompatibilities in pointer size. 32-bit and 64-bit system components are single sourced, meaning that the components work with FCD 3 on 64-bit systems if compiled with P64, or work with both FCD 2 and FCD 3 on 32-bit systems if compiled with NOP64. We recommend that you take this single-sourcing approach when developing your own applications.

However, some programs in your application might provide interfaces to other components in your application, and these interfaces might include FCD structures. In this case you might need to provide gradual transition to full FCD 3 support; at run time, therefore, your program will need to accept both FCD 2 and FCD 3 formats, and to distinguish them as necessary. For example, if there are few references to FCD fields within your code, the following source code model might be suitable:

	linkage section.
	01  fcd-user		pic x.
	01  fcd2.
		copy "xfhfcd2".
	01  fcd3.
		copy "xfhfcd3".
        procedure division using fcd-user.
	    set address of fcd3		to address of fcd-user
	    if  fcd-version of fcd3 = 0
	        *> Dealing with FCD2..
      $if P64 set
      		display "Error: cannot accept FCD2 on 64 bit platform"
      		exit program
      $end
		      set address of fcd2 	to address of fcd-user
	    end-if

Every time a field of the FCD is referenced you must add code that does something like the following:

    if  ( fcd-version of fcd3 not = 0 
	      and fcd--line-sequential of fcd3)
	   or  ( not fcd-version of fcd3 = 0
	      and fcd--line-sequential of fcd2 )
	      	*> Do line sequential manipulation
	   end-if

If, however, the bulk of the code in your component directly references the FCD structure, you could internally use only the FCD 3 structure and, if necessary, establish mappings, to and from FCD 2 at entry and exit gateways to the component. For example:

        working-storage section.
        78  78-fcd3-map-to-fcd3         value 0.
        78  78-fcd3-map-from-fcd3       value 1.

	78  78-fcd3-map-error-none      value 0.
	78  78-fcd3-map-error-64bit     value -1.
	78  78-fcd3-map-error-func      value -2.
	78  78-fcd3-map-error-reladdr   value -3.
        01  fcd3-work.
                copy "xfhfcd3".
        linkage section.
        01  fcd-user            pic x.
        procedure division using fcd-user.
	    *> Entry Gate map FCD2 (if necessary) to FCD3
            call 'fcd3map' using fcd-user
                                  fcd3-work
                         by value 78-fcd3-map-to-fcd3 size 1
	    if  return-code not = 0 
      		display "Error: cannot convert FCD formats"
      		exit program
	    end-if

	    *> Operate on the FCD as FCD3 only
	    *> ....
		
	    *> Exit Gate map FCD3 (if necessary) to FCD2
            call 'fcd3map' using fcd-user
                                 fcd3-work
                         by value 78-fcd3-map-from-fcd3 size 1
            exit program.