Interfacing and Mixed-language Programming

Header-to-COPY Utility

Chapter 11: Installf Facility

16-bit:
On the 16-bit COBOL system the Installf facility enables you to create a library of routines that can be installed by the Run-time Environment (RTE) so that they are available without linking. In this way, you can merge one or more subprograms written in Assembler or Microsoft C V6.0 or later into a single library of routines.

OS/2:
On OS/2 this facility can also be used to make the operating system API routines accessible to a standard .int or .gnt program without linking.

11.1 Assembler Routines

You create a library of installable Assembler subroutines as follows:

Create your Assembler subroutines as detailed in your Programmer's Guide to Writing Programs. For example, let's suppose you have created two subroutines calcmin.obj and calcmax.obj, with public entry points CALCMIN and CALCMAX respectively.
Create an .asm file containing a line defining each of the subroutines you wish to include. Each assembler entry point that you wish to access directly from your COBOL program should have a line of the form:
```
addcall     entry-point-name
```
Assemble this file using Microsoft MASM, noting that the file installf.mac must be present in the current directory or be available on an include path. The resultant object file is known as a call definition module.

Using usrdef.asm as an example, we could make a copy of usrdef.asm called, say, usrcall.asm and insert in it the two lines:
```
addcall      CALCMIN
addcall      CALCMAX
```

An Installf library can then be created by linking as follows (in the following formats the file extensions are shown for clarity; the ones shown are the defaults).

DOS:
To create an Installf library for DOS use the command line:

link installf.obj+call-definition-module+
     subroutine-obj-modules, installf-library-name,,
     installf.lib+cobapi.lib;

where the parameters are:

`installf.obj`	An object module
`call-definition-module`	The .obj file produced in step 2 above
`subroutine-obj-modules`	Those assembler subroutines produced in step 1 above
`installf-library-name`	The name you wish to give to the resultant Installf library. This will automatically be given an .exe extension on DOS
`installf.lib`	The Installf library
`cobapi.lib`	The DOS operating system support library, supplied with COBOL

OS/2:
To create an Installf library for OS/2 use the command line:

link installf.obj+call-definition-module+
     subroutine-obj-modules,installf-library-name,,
     installf.lib+os2.lib, installf.def;

where the parameters are the same as above, with the addition of:

`os2.lib`	The OS/2 operating system support library
`installf.def`	An OS/2 Linker definition file supplied with the Object COBOL system. This creates an Installf library with a .dll extension for OS/2

Windows V3.1 or earlier

To create an Installf library for Windows, use the command line:

link winstf.obj+call-definition-module+
     subroutine-obj-modules,winstf-library-name,,
     winstf.lib+coblibw.lib+coblib+cobw,
     winstf.def /noe /nod;

where the parameters are:

`winstf.obj`	An object module supplied with Object COBOL for Windows functionality
`winstf.lib`	A library supplied with Object COBOL for Windows functionality
`coblibw.lib`	The operating system support library for Windows
`coblib`	The RTE library
`cobw`	The operating system support library for Windows and is similar to libw in the Microsoft Standard Development Kit
`winstf.def`	The Windows Linker definition file supplied with Object COBOL. This creates a Winstf library with a .dlw extension

Examples

DOS:
To create an Installf library usrlib.exe for use on DOS, enter the command:

link installf+usrcall+calcmin+calcmax,usrlib,,installf+cobapi;

OS/2:
To create the corresponding OS/2 library file usrlib.dll, enter the command:

link installf+usrcall+calcmin+calcmax,usrlib,,installf+
    os2,installf.def;

Windows V3.1 or earlier:
To create a Winstf library usrlib.dlw for Windows, enter the command:

link winstf.obj+usrcall+calcmin+calcmax,usrlib.dlw,,winstf 
     +coblibw+coblib+cobw/nod/noe,winstf.def

11.2 Microsoft C V6.0 Routines

You create a library of Microsoft C V6.0 or later subroutines as follows:

Create your C functions as detailed in the Programmer's Guide to Writing Programs. For example, let's suppose you have created a C function Calcmean in an object file calcmean.obj.
Create an .asm file containing a line defining each of the functions you wish to include. Each C function that you wish to access directly from your COBOL program should have a line of the form:
```
addcfun     c-function-name
```
Assemble this file using Microsoft MASM, noting that the file installf.mac (supplied with Object COBOL) must be present in the current directory or be available on an include path. The resultant object file is known as a call definition module.

Using usrdef.asm (also supplied with Object COBOL) as an example, we could make a copy of usrdef.asm called, say, usrcall.asm and insert in it the line:
```
addcfun      CALCMEAN 
```

An Installf library can then be created by linking as follows (in the following formats the file extensions are shown for clarity; the ones shown are the defaults).

DOS:
To create an Installf library for DOS, use the command line:

link installf.obj+call-definition-module+
     subroutine-obj-modules+
     mfc6intf.obj+mfc6dosif.obj+mfc6doslb.obj,
     installf-library-name,,
     installf.lib+llibcr.lib+cobapi.lib;

where the parameters are:

`installf.obj`	An object module supplied with Object COBOL
`call-definition-module`	The .obj file produced in step 2 above
`subroutine-obj-modules`	Those subroutines produced in step 1 above
`installf-library-name`	The name you wish to give to the resultant Installf library. This will automatically be given an .exe extension on DOS
`mfc6intf.obj`, `c6doslb.obj` and `c6dosif.obj`	C V6.0 interface modules supplied with COBOL. Note that, in this instance, the names of these interface modules reflect the version of Microsoft C you are using. If you are using V7.0 the modules have the names `mfc7intf.obj`, `c7doslb.obj` and `c7dosif.obj`.
`llibcr.lib`	The large mode DOS C run-time library supplied with C V6.0
`installf.lib`	A library supplied with the Object COBOL system
`cobapi.lib`	The DOS operating system support library, supplied with Object COBOL

OS/2:
To create an Installf library for OS/2, use the command line:

link installf.obj+call-definition-module+
     subroutine-obj-modules+
     mfc6intf.obj+c6os2if.obj+c6os2lb.obj,
     installf-library-name,,
     installf.lib+llibcp.lib+os2.lib,installf.def;

`mfc6intf.obj`, `c6os2if.obj` and `c6os2lb.obj`	C V6.0 interface modules supplied with COBOL.
`llibcp.lib`	The large mode OS/2 C run-time library supplied with C V6.0
`installf.def`	An OS/2 Linker definition file supplied with Object COBOL

This creates an Installf library with a .dll extension for OS/2.

Examples:

DOS:
To create an Installf library usrlib.exe for use on DOS, enter the command:

link installf+usrcall+calcmean+mfc6intf+c6dosif+
     c6doslb,usrlib,,installf+llibcr+cobapi;

OS/2:
To create the corresponding OS/2 library, enter the command:

link installf+usrcall+calcmean+mfc6intf+c6os2if+
     c6os2lb,usrlib,,installf+llibcp+os2,installf.def;

11.3 OS/2 API Routines

You create a library of OS/2 API subroutines as follows:

Create an .asm file containing a line defining each of the API routines you wish to include. Each API routine that you wish to access directly from your COBOL program should have a line of the form:
```
addapi      api-routine-name
```
For details on call conventions for OS/2 API, see the chapter Interfacing and Mixed-language Programming.
Assemble this file using Microsoft MASM, noting that the file installf.mac (supplied with the Object COBOL system) must be present in the current directory or be available on an include path.
Using usrdef.asm (also supplied with the Object COBOL system) as an example, we could make a copy of usrdef.asm called, say, apicall.asm and insert in it the two lines:
```
addapi      VIOGETCONFIG
addapi      DOSGETVERSION
```
if we wanted to be able to call the VIOGETCONFIG and DOSGETVERSION OS/2 API calls from our .int or .gnt program.

An Installf library can then be created for OS/2 by linking together the API call definition module together with the installf.obj file supplied with Object COBOL:

link installf.obj+call-definition-module,
    installf-library-name,,
    installf.lib+os2.lib,installf.def;

where the parameters are:

`installf.obj`	An object module supplied with Object COBOL
`call-definition-module`	The .obj file produced in step 2 above
`installf-library-name`	The name you wish to give to the resultant Installf library. This will automatically be given a .dll extension
`installf.lib`	A library supplied with Object COBOL
`os2.lib`	The OS/2 operating system support library
`installf.def`	An OS/2 Linker definition file supplied with Object COBOL

So, for example, the command:

link installf+apicall,apilib,,installf+os2,installf.def

creates an Installf library apilib.dll which would enable the two API routines to be called.

To assist you in creating Installf libraries supporting most of the standard OS/2 API routines, Object COBOL contains four INCLUDE-files: dos.inc, vio.inc, kbd.inc and mou.inc, containing definitions for a large number of API routines. The cobolapi.dll file, also supplied, is an Installf library which supports all the API routines listed in the four .inc files.

11.4 Windows API Routines

You create a library of Windows API subroutines as follows:

Create an .asm file containing a line defining each of the API routines you wish to include. Each API routine that you wish to access directly from your COBOL program should have a line of the form:
```
addapi      api-routine-name
```
For details on call conventions for Windows API, see the chapter Interfacing and Mixed-language Programming.
Assemble this file using Microsoft MASM, noting that the file winstf.mac (supplied with the Object COBOL system) must be present in the current directory or be available on an include path.
For example, we can make a copy of usrdef.asm (also supplied with the Object COBOL system) called, say, apicall.asm and insert in it the two lines:
```
addapi      GetCurrentTime
addapi      GetVersion
```
to call the GetCurrentTime and GetVersion Windows API routines from our .int or .gnt program.

Link the API call definition module together with the winstf.obj file supplied with Object COBOL, as follows:

link winstf.obj+call-definition-module,
     winstf-library-name,,
     winstf.lib+cobw.lib,winstf.def /noe /nod;

where the parameters are:

`winstf.obj`	An object module supplied with Object COBOL for Windows functionality
`call-definition-module`	The .obj file produced in step 2 above
`winstf-library-name`	The name you want for the resulting Winstf library
`winstf.lib`	A library supplied with Object COBOL
`cobw.lib`	The Windows operating system support library
`winstf.def`	An Windows Linker definition file supplied with Object COBOL

So, for example, the command:

link winstf+apicall,apilib.dll,,winstf+cobw,winstf.def /noe /nod

creates an Winstf library apilib.dll which enables the two API routines to be called.

11.5 Mixing User-written and OS/2 API Routines

You can create a library containing both user written routines and OS/2 API routines. You simply combine the three methods detailed above. So for OS/2 you could use the command:

link installf+usrcall+calcmin+calcmax+calcmean+mfc6int+
    c6os2if+c6os2lb,usrlib,,installf+llibcp+os2,installf.def;

to create a single Installf library usrlib.dll, giving access to user subroutines CALCMIN, CALCMAX and CALCMEAN and to OS/2 API routines VIOGETCONFIG and DOSGETVERSION. usrcall is your call definition module containing all the entry point definitions for each type of Installf function.

11.6 Using Installf Libraries in Your Application

Before you can access any of the routines inside an Installf library, you must install the library into the RTE. This is done by making an explicit call to the Installf library near the start of your application code.

DOS:
On DOS, to install an Installf library, you use the COBOL statement:

call "usrlib.exe"

Windows V3.1 or earlier:
On Windows, to install an Installf library, you use the COBOL statement:

call "usrlib.dlw"

OS/2:
On OS/2, to install an Installf library, you use the COBOL statement:

call "usrlib.dll"

Alternatively, you can install the routines by specifying them in the Build Configuration file (see the chapter Using Build for details).

Once the library has been installed, the routines written in Assembler can be freely called in the same way as you would call them in a COBOL application (see the chapter Interfacing and Mixed-language Programming for more information). The routines written in C can be called using the same name as the C function, without the need for the underscore prefix.

If any of your assembler subroutines need direct access to the video screen for reading or writing, then, if you wish to animate a program that calls those routines, you must make sure that the user screen, rather than the Animator screen, is visible when you perform the screen access. There are two ways of doing this. The first is to use the FLASH-CALLS Animator directive .

The second way is for your assembler subroutine to make a far call to a routine called _USRSCRN in module installf.obj. After this call the user screen is guaranteed to be visible. If you are not animating, this call has no effect.

OS/2:
For OS/2 API routines, the call to _USRSCRN is made automatically.

The call to _USRSCRN does not affect any of the machine registers apart from the flag register.

An application can use one or more Installf libraries. If a routine-name is defined in more than one library, the first definition of the routine is used.

Interfacing and Mixed-language Programming

Header-to-COPY Utility