/WS COBOL Language Binding Feature

About This Chapter

This chapter specifically covers the use of the COBOL language binding feature of the /Workstation on the following workstation platforms:

UNIX
MS-DOS
Windows
OS/2

The material in this chapter is intended to supplement the material presented in the programming chapters of this guide and the BEA TUXEDO /Workstation Guide.

UNIX

Programming Consideration with UNIX Clients

This section covers item specific to writing and building BEA TUXEDO System/T COBOL client programs to run under UNIX.

Writing Client Programs

COBOL client programs for UNIX workstations are the same as COBOL client programs within the System/T administrative domain. You do have available all of the ATMI functions.

Building Client Programs

Workstation client programs are compiled and link edited with the buildclient command. If you are building a UNIX /Workstation client on the native node, use the -w option. This specifies that the client should be built using the workstation libraries. On a native node, where both native and workstation libraries are present, the default is to use the native libraries. The -w option ensures that the correct libraries for a workstation client are used. On a workstation, where only the workstation libraries are present, it is not necessary to use the -w.

Figure 1 shows an example of the buildclient command line on the native node.

Fig. 1: Example of UNIX buildclient Command Lines

ALTCC=cobcc ALTCFLAGS="-I /APPDIR/include"
COBCPY=$TUXDIR/cobinclude
COBOPT="-C ANS85 -C ALIGN=8 -C NOIBMCOMP -C TRUNC=ANSI -C OSEXT=cbl"
export COBOPT COBCPY ALTCC ALTCFLAGS
buildclient -C -w -o empclient -f name.cbl -f "userlib1.a userlib2.a"

The -o option provides a name for your a.out file. Input files are specified with a -f firstfiles option in Figure 1 to indicate that they are called in ahead of system libraries. buildclient needs TUXDIR to locate system libraries. CC defaults to cc, but can be set to another compiler as in the example.

Environment Variables

Workstation clients make use of several environment variables. The following are checked by TPINITIALIZE when the workstation client attempts to join the application:

WSENVFILE: names a file containing environment variable settings to be set in the client's environment.
WSNADDR: specifies the network address of the workstation listener process through which the client gains access to the application. Use the value specified in the application configuration file for the workstation listener to be called. If the value begins with the characters ``0x,'' it is interpreted as a string of hex-digits, otherwise it is interpreted as ASCII characters.
WSDEVICE: is the device name to be used to access the network and is not required by all transport layer interfaces.
WSTYPE: is used within TPINITIALIZE when invoked by a workstation client to negotiate encode/decode responsibilities with the native site. An unspecified WSTYPE always causes encoding, even if it is also unspecified on the native site. The only way to ensure that encode/decode is turned off is to explicitly specify the same WSTYPE value for both sites.
WSRPLYMAX: is used by TPINITIALIZE to set the maximum amount of core memory that ATMI uses for buffering application replies before they are dumped to disk. The system default limit for this is 32,000 bytes. The available memory on your machine is the key factor in deciding whether you should use WSRPLYMAX to set a lower limit. Writing replies to disk causes a substantial reduction in performance.

Other environment variables may be needed by /Workstation COBOL clients on a UNIX workstation depending on what System/T features are being used.

Note: MicroFocus COBOL does not support shared objects on UNIX 3.2. LIBNSL.a is delievered as a shared object and is required by buildclient when linking a workstation client. As a result, /WS for for UNIX 3.2 is not supported.

DOS

Programming Considerations with MS-DOS Clients

This section covers items specific to writing and building BEA TUXEDO System/T COBOL client programs to run under MS-DOS.

Writing Client Programs

COBOL client programs for MS-DOS workstations are the same as COBOL client programs within the System/T administrative domain. You have available all of the ATMI functions.

Building Client Programs

The COBOL source files that call ATMI functions must be compiled with the COBOL compiler using LITLINK option. Workstation client object files are link edited with the buildclt command. While the syntax of the command is straightforward, the usage varies according to the compilation system used. Figure 2 shows a sample. buildclt command line.

Fig. 2: Example of MS-DOS buildclt Command Lines

COBCPY=C:\TUXEDO\COBINC
COBDIR=C:\COBOL\LBR;C:\COBOL\EXEDLL
PATH=C:\C700\BIN;C:\COBOL\EXEDLL;...
TUXDIR=C:\tuxedo
INCLUDE=C:\TUXEDO\INCLUDE;C:\NET\TOOLKIT\INCLUDE;C:\C700\INCLUDE
LIB=C:\NET\TOOLKIT\LIB;C:\C700\LIB;C:\TUXEDO\LIB;C:\COBOL\LIB
buildclt -C -o EMP.EXE -f EMP+MFC7INTF+C7DOSIF+C7DOSLB \
	-f "/NOE/NOI/SE:300/CO/ST:10000"  -l "LLIBSOCK LLIBCE"

buildclt has the following options:

-o name: the file name of the executable file being created. The default is client.exe.
-f firstfiles: one or more object files to be included before the System/T libraries. -f can also be used to pass options to the compiler or linker. If more than one file name is specified, the names are separated by white space and the list is enclosed in quotation marks. The -f option can appear more than once.
-l libfiles: specifies libraries to be included after the System/T libraries. If more than one file name is specified, the names are separated by white space and the list is enclosed in quotation marks. The -l option can appear more than once.

After the client programs have been developed and tested they can be moved to the MS-DOS workstations where they will be available to users.

Environment Variables

Workstation clients make use of several environment variables. The following are checked by TPINITIALIZE when the client attempts to join the application:

WSENVFILE: names a file containing environment variable settings to be set in the client's environment. All of the other environment variables needed by client programs can be contained in this file.
WSNADDR: specifies the network address of the workstation listener process through which the client gains access to the application. Use the value specified in the application configuration file for the workstation listener to be called. If the value begins with the characters ``0x'', it is interpreted as a string of hex-digits, otherwise it is interpreted as ASCII characters.
WSTYPE: is used within TPINITIALIZE when invoked by a workstation client to negotiate encode/decode responsibilities with the native site. An unspecified WSTYPE always causes encoding, even if it is also unspecified on the native site. The only way to ensure that encode/decode is turned off is to specify the same WSTYPE value for both sites.
WSRPLYMAX: is used by TPINITIALIZE to set the maximum amount of core memory that ATMI uses for buffering application replies before they are dumped to disk. The system default limit for this is 32,000 bytes. The available memory on your machine is the key factor in deciding whether you should use WSRPLYMAX to set a lower limit. Writing replies to disk causes a substantial reduction in performance.

Other environment variables may be needed by /Workstation COBOL clients on a MS-DOS workstation depending on what System/T features are being used.

Windows

Programming Considerations with the Windows DLL

This section covers items specific to writing and building BEA TUXEDO System/T client programs to run under Microsoft Windows. They are intended to supplement the material presented in the programming chapters of this guide and the BEA TUXEDO /Workstation Guide.

Writing Client Programs

The ATMI calls used in Windows client programs are the same as described in the programming chapters of this guide.

Building Client Programs

The COBOL source files that call ATMI functions must be compiled with the COBOL compiler using LITLINK option. Workstation client object files are link edited with the buildcltcommand. While the syntax of the command is straightforward, the usage varies according to the compilation system used. Figure 3 shows a sample. buildclt command line.

Fig. 3: Example of Windows buildclt Command Lines

COBCPY=C:\TUXEDO\COBINC
COBDIR=C:\COBOL\LBR;C:\COBOL\EXEDLL
PATH=C:\COBOL\EXEDLL;...
TUXDIR=C:\tuxedo
LIB=C:\NET\TOOLKIT\LIB;C:\MSVC\LIB;C:\TUXEDO\LIB;C:\COBOL\LIB
buildclt -C -W -o EMP.EXE -f EMP \
	-f "/NOD/NOI/NOE/CO/SE:300" -d EMP.DEF -l WLIBSOCK
For Windows NT:
buildclt -C -W -o EMP.EXE  \
  -f empobj -d emp.def

buildclt has the following options:

-W: specifies that the client should be built using Windows libraries.
-d deffile: specifies the module definition file used for linking a Windows program.
-o name: the file name of the executable file being created. The default is client.exe.
-f firstfiles: one or more object files to be included before the System/T libraries. -f can also be used to pass options to the compiler or linker. If more than one file name is specified, the names are separated by white space and the list is enclosed in quotation marks. The -f option can appear more than once.
-l libfiles: specifies libraries to be included after the System/T libraries. If more than one file name is specified, the names are separated by white space and the list is enclosed in quotation marks. The -l option can appear more than once.

Figure 4 is the module definition file used in the Windows buildclt command line.

Fig. 4: Example of a Windows Module Definition File

NAME            EMP
DESCRIPTION     "EMPLOYEE CLIENT ATMI"
EXETYPE         WINDOWS
CODE            PRELOAD MOVEABLE DISCARDABLE
DATA            PRELOAD FIXED MULTIPLE
HEAPSIZE        15000
STACKSIZE       15000
EXPORTS         WordProc

Building ACCEPT/DISPLAY Clients

To build an executable client for an ACCEPT/DISPLAY application (like CSIMPAPP, for example), use the procedure shown in Figure 5.

Fig. 5: Building ACCEPT/DISPLAY clients

a) compile the COBOL module and create a file.obj
	cobol file.cbl omf(obj) litlink;
b) use the following link statement
	link FILE+cblwinaf,,,\
	     wcobatmi+cobws+wtuxws+ \
	     lcobol+lcoboldw+cobw+cobfp87w+  \
	     wlibsock,FILE.def  /nod/noe;
For Windows NT the link statement is:
	cbllink -oEMP.exe EMP.obj  \
	     cobws.lib ncobatmi.lib wtuxws32.lib  \
	     libcmt.lib user32.lib

Blocking Network Behavior

Refer to the BEA TUXEDO /Workstation Guide.

Restoring the Environment

Refer to the BEA TUXEDO /Workstation Guide.

OS/2

Programming Considerations with OS/2 Clients

This section covers items specific to writing and building BEA TUXEDO System/T COBOL client programs to run under OS/2. They are intended to supplement the material presented in the programming chapters of this guide and the BEA TUXEDO /Workstation Guide.

Writing Presentation Manager Client Programs

The ATMI calls used in Presentation Manager client programs are the same as described in the programming chapters of this guide. They must, however, be incorporated into Presentation Manager modules.

Blocking Network Behavior

Refer to the BEA TUXEDO /Workstation Guide.

Building Client Programs

The COBOL source files that call ATMI functions must be compiled with the COBOL compiler using LITLINK option and must use the OPTLINK calling convention. There is an example of the use of the OPTLINK calling convention in $TUXDIR/apps/CSIMPAPP/ws/os2/csimpcl.cbl. Workstation client object files are link edited with the buildcltcommand. While the syntax of the command is straightforward, the usage varies according to the compilation system used. Figure 6 shows a sample buildclt

Fig. 6: Example of OS/2 Presentation Manager buildclt Command Lines

COBCPY=C:\TUXEDO\COBINC
COBDIR=C:\COBOL\LBR;C:\COBOL\EXEDLL
PATH=C:\COBOL\EXEDLL;...
TUXDIR=C:\tuxedo
LIB=C:\TCPIP\LIB;C:\IBMCPP\LIB;C:\TOOLKT2\OS2LIB;C:\TUXEDO\LIB;C:\COBOL\LIB
buildclt -C -P -o emp.exe -f emp.obj -d emp.def

buildclt has the following options:

-P: specifies that the client should be built using OS/2 Presentation Manager libraries.
-o name: the file name of the executable file being created. The default is client.exe.
-d deffile: specifies the module definition file used for linking a Windows program.
-f firstfiles: one or more object files to be included before the System/T libraries. -f can also be used to pass options to the compiler or linker. If more than one file name is specified, the names are separated by white space and the list is enclosed in quotation marks. The -f option can appear more than once. The first file can define the main entry. Use -f"/m<main>" to specify.
-l libfiles: specifies libraries to be included after the System/T libraries. If more than one file name is specified, the names are separated by white space and the list is enclosed in quotation marks. The -l option can appear more than once.

Figure 7 shows the module definition file used in the OS/2 Presentation Manager buildclt command line.

Fig. 7: Example of an OS/2 Presentation Manager Module Definition File

NAME            EMP WINDOWAPI
PROTMODE
EXETYPE         OS2
HEAPSIZE        15000
STACKSIZE       15000
EXPORTS         EMPWNDPROC

Figure 8 shows a sample OS/2 character-mode buildclt command line.

Fig. 8: Example of OS/2 Character-Mode buildclt Command Lines

COBCPY=C:\TUXEDO\COBINC
COBDIR=C:\COBOL\LBR;C:\COBOL\EXEDLL
PATH=C:\COBOL\EXEDLL;...
TUXDIR=C:\tuxedo
LIB=C:\TCPIP\LIB;C:\MSVC\LIB;C:\TUXEDO\LIB;C:\COBOL\LIB
buildclt -C -O -o emp.exe -f emp.obj

buildclt has the following option:

-O: specifies that the client should be built using OS/2 character-mode libraries.