[email protected] march 2012 session #10767 · contact for information on the product...

Copyright International Business Machines Corporation 2001, 2012

z/OS DLLs for Dummies

[email protected]

March 2012Session #10767

2Copyright International Business Machines Corporation 2001, 2012

The following are trademarks of the International B usiness Machines Corporation in the United States a nd/or other countries.

The following are trademarks or registered trademar ks of other companies.

* Registered trademarks of IBM Corporation

* All other products may be trademarks or registered trademarks of their respective companies.

Java and all Java-related trademarks and logos are trademarks of Sun Microsystems, Inc., in the United States and other countries.Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.Microsoft, Windows and Windows NT are registered trademarks of Microsoft Corporation.UNIX is a registered trademark of The Open Group in the United States and other countries.SET and Secure Electronic Transaction are trademarks owned by SET Secure Electronic Transaction LLC.

Notes :Performance is in Internal Throughput Rate (ITR) ratio based on measurements and projections using standard IBM benchmarks in a controlled environment. The actual throughput that any user will experience will vary depending upon considerations such as the amount of multiprogramming in the user's job stream, the I/O configuration, the storage configuration, and the workload processed. Therefore, no assurance can be given that an individual user will achieve throughput improvements equivalent to the performance ratios stated here. IBM hardware products are manufactured from new parts, or new and serviceable used parts. Regardless, our warranty terms apply.All customer examples cited or described in this presentation are presented as illustrations of the manner in which some customers have used IBM products and the results they may have achieved. Actual environmental costs and performance characteristics will vary depending on individual customer configurations and conditions.This publication was produced in the United States. IBM may not offer the products, services or features discussed in this document in other countries, and the information may be subject to change without notice. Consult your local IBM business contact for information on the product or services available in your area.All statements regarding IBM's future direction and intent are subject to change or withdrawal without notice, and represent goals and objectives only.Information about non-IBM products is obtained from the manufacturers of those products or their published announcements. IBM has not tested those products and cannot confirm the performance, compatibility, or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.Prices subject to change without notice. Contact your IBM representative or Business Partner for the most current pricing in your geography.

Trademarks

•IBM*

•z/OS*

•OS/390*

•Language Environment*

•MVS

3Copyright International Business Machines Corporation 2001, 2012Copyright International Business Machines Corporation 2001, 2012

Agenda

• Definitions and Terms

• A survey of similar technologies

• z/OS implementation specifics

• Usage & Samples


The big picture

• Static linking

Compilation Unit 1a

Compilation Unit 2b

Compilation Unit 2a

Compilation Unit 1b

Program P

compiler/linker

compiler/linker

compiler/linker

compiler/linker


The big picture (cont’d)

• Dynamic linking

Compilation Unit 1a

Compilation Unit 1b

Program P1

compiler/linker

compiler/linker

Compilation Unit 2b

Compilation Unit 2a

compiler/linker

compiler/linker

DLL D2

linker

DYNAMIC LINKAGEDLL D2


Definitions and Terms

• What Does a DLL do?

• What Do You Do With a DLL?


What Does a DLL do?

• Provides (usually closely related) services to applications

• Implements a library of functions and/or variables

• Chooses which of it’s functions and/or variables to make visible

• Provides a way for users to reference them

• EXPORT

• Installs into a location where the using applications can find it

• Reusable by design


What Do You Do With a DLL?

• Write applications which utilizie (usually closely related) services they provide

• Application needs to be DLL-enabled (by compiler)

• Call functions and/or reference variables

• IMPORT

• Variables may or may not be utilitized by the DLL itself

• SHAREd

• Implicitly or explicitly use the services of the DLL

• Implicit is easy – implement your application as if services were static

• Explicit is harder – implementation requires calling new run-time services

• Time of linkage completion becomes user controlled


A survey of similar technologies

• Microsoft® implementation of shared libraries

• UNIX

• Standardized explicit run-time calls in The Single UNIX®Specification, Version 2 (SUSV 2)

• Implemented in z/OS C run-time library in z/OS V1.6


What about z/OS technologies?

• z/OS XL C/C++

• Enterprise COBOL for z/OS

• Enterprise PL/I for z/OS

• High Level Assembler


What about z/OS before DLLs?

• C/C++

• C++ was introduced with DLL support, so all z/OS C++ code is DLL-enabled (pre-OS/390)

• C run-time has two functions:

• fetch()

• similar to explicit DLL usage

• fetchep()

• because there is no inherent variable sharing, when module being fetched contains multiple functions

• Semantics for sharing of variables is not consistent with DLLs

• Each fetch is unique



• COBOL

• Dynamic Call

• COBOL manages the load, in the manner of explicit DLL usage

• Single function

• Multiple functions possible with aliases (alternate entry points)

• No shared variables



• PL/I

• PL/I has FETCH

• PL/I manages the load, in the manner of explicit DLL usage

• Functions are NORENT

• Variables shared in (NORENT) module

• Performance implications due to lack of code / data separation



• Language Environment (LE)

• CEEFETCH, CEERELES

• Complete control for application programmer, in the manner of explicit DLL usage

• Programmer can choose to have module load scoped to a higher or lower logical level (such as thread)

• UNIX is supported

• Language-related initializations are performed, so can be used with all LE languages, including:

• C++ (constructors/destructors, implicity DLL target)

• XPLINK (implicitly DLL target)


What value do z/OS DLLs add?

• Common mechanism works with all the LE languages

• z/OS XL C/C++

• Enterprise COBOL for z/OS

• Enterprise PL/I for z/OS



What value do z/OS DLLs add? (cont’d)

• Performance

• Once loaded, linkage overhead very light-weight

• Implied reentrancy of code

• Good code vs. data separation

• Shared library potential for lower memory use

• LPA

• UNIX shared libraries



• Simplification

• Can usually switch from static linking to dynamic linking without any code changes

• Primarily packaging for library providers

• Applications using library need not relink – typically not even across new releases of library!

• Can be useful even within a (complex) application, separation ofsubcomponents

• Rarely used subcomponents may never be loaded (perhaps exceptionhandling)



• Simplification (cont’d)

• Multiple functions in a single library do not require multiple aliases (entry points) in data sets

• Sharing of variables (for languages which support it)

• Scoped to the application (LE enclave)



• UNIX filesystem targets

• LIBPATH environment variable

• for IMPLICIT and EXPLICIT references

• unless the DLL name contains a slash (/)

• MVS dataset targets too of course

• Usual program search order

• JOBLIB, STEPLIB (including UNIX environment variable)



• Portability at the language level

• Particularly true for C/C++

• SUSV2 DLL functions

• dlopen• dlclose• dlsym• dlerror


What value do z/OS DLLs subtract?

• Not the native linkage of z/OS, thus programs need to be specially built

• Compile DLL-enabled to refer to DLLs

• Compile DLLs to identify functions and variables to make visible

• Linkage completion is a function of LE, not native MVS!

• Binder support required*


What value do z/OS DLLs subtract? (cont’d)

• Not the native linkage of LE either

• z/OS is big on compatibility, defaults are non-DLL!

• Except...

• C++• XPLINK• LE AMODE 64 (LP64) implies XPLINK



• Compatibility

• Non-DLL-enabled code generally works well with DLL-enabled code

• Some exceptions, mostly related to

• Function pointers are to descriptors instead of actual functions

• Programs can have sensitivity to time-of-load of DLLs

• Especially related to static initializers and constructors



• Compatibility (cont’d)

• Well described in z/OS XL C/C++ Programming Guide – Coding: Advanced Topics

• Also in z/OS Language Environment Programming Guide – Building and Using Dynamic Link Libraries (DLLs)

• Except compatibility discussion

• Both cover other restrictions …

• Such as incompatibility with those prior z/OS technologies


How Do DLLs work?

• Descriptors – once “completed”

• Function – instead of just an V-con

• Variable – instead of just an A-con

• Non-XPLINK only -- XPLINK handles completely at DLL init

Environment ->

Function ->

Variable ->

Environment ->


How Do DLLs work? (cont’d)

• Compatibility Descriptors – before completion (numerous styles)

• Non-XPLINK vs. XPLINK

• XPLINK to XPLINK, XPLINK to non-XPLINK

• LP64 have NO compatibility!

code

code

adcon

adcon

Environment Info ->

Trigger Function ->

adcon

adcon



• More about descriptors

• Must reside in writable storage of the caller

• Function @ normally constant for all callers (at least in that AS)

• Variable @ must be unique for each application (LE enclave)

• Must be identical for all modules comprising the application!

• Fixed up upon first use of referenced DLL

• All descriptors for the that DLL are fixed up for that caller



DLL Appl

{ ....

call dllFn( );

.... }

DLL

datatype X;

dllFn( )

{return;}

dllFn Addr

DLL's WSA Addr

DLL Appl's WSA

DLL's WSA

CEECAACRENT: WSA addr

X

Function Descriptor


How Do DLLs work? (cont’d)Walk-thru implicit DLL load

• Trigger functions are LE library routines

• Trigger functions obtain DLL and function name from descriptors

• Import/Export table is loaded part of each module

• Import information is in the application calling the DLL

• Contains the information needed to update all the descriptors in the DLL

• Export information is in the DLL

• Contains the information needed to identify the location of the function in the DLL

• Both the address of the function and it’s environment


Walk-thru implicit DLL load (cont’d)

Appl A calls dllfuncX1 , which resides in DLL X

Appl Amain() {

...

dllfuncX1();

...

dllfuncX2();

…

dllfuncY1();

}

Appl A WSA

V(CEETLOC)

dllfuncX1_id

V(CEETLOC)

dllfuncX2_id

V(CEETLOC)

dllfuncY1_id



Is DLL X already loaded?

No, so load it..

DLL XdllfuncX1() {…};

dllfuncX2() {…};

dllfuncX3() {…};

Appl Amain() {

...

dllfuncX1();

...

dllfuncX2();

…

dllfuncY1();

}

Appl A WSA

V(CEETLOC)

dllfuncX1_id

V(CEETLOC)

dllfuncX2_id

V(CEETLOC)

dllfuncY1_id



.. and obtain and initialize it’s environment (WSA)


dllfuncX2() {…};

dllfuncX3() {…};

DLL X WSA

Appl Amain() {

...

dllfuncX1();

...

dllfuncX2();

…

dllfuncY1();

}

Appl A WSA

V(CEETLOC)

dllfuncX1_id

V(CEETLOC)

dllfuncX2_id

V(CEETLOC)

dllfuncY1_id



.. then resolve all descriptors (and variable references) to DLL X (only) in DLL Appl A's WSA

Now complete dllfunc1 call and return back directly


dllfuncX2() {…};

dllfuncX3() {…};

DLL X WSA

Appl Amain() {

...

dllfuncX1();

...

dllfuncX2();

…

dllfuncY1();

}

Appl A WSA

V(dllfuncX1)

A(dllfuncX1 WSA)

V(dllfuncX2)

A(dllfuncX2 WSA)

V(CEETLOC)

dllfuncY1_id



Subsequent calls and references from Appl A to DLL X require no

run-time intervention


dllfuncX2() {…};

dllfuncX3() {…};

DLL X WSA

Appl Amain() {

...

dllfuncX1();

...

dllfuncX2();

…

dllfuncY1();

}

Appl A WSA

V(dllfuncX1)

A(dllfuncX1 WSA)

V(dllfuncX2)

A(dllfuncX2 WSA)

V(CEETLOC)

dllfuncY1_id


Walk-thru implicit DLL load (cont’d)Appl Amain() {

...

dllfuncX1();

...

dllfuncX2();

…

dllfuncY1();

}

Appl A WSA

Appl A now calls dllfuncY1 which resides in DLL Y

V(dllfuncX1)

A(dllfuncX1 WSA)

V(dllfuncX2)

A(dllfuncX2 WSA)

V(CEETLOC)

dllfuncY1_id


dllfuncX2() {…};

dllfuncX3() {…};

DLL X WSA

DLL Y WSA

V(CEETLOC)

dllfuncX2_id

V(CEETLOC)

dllfuncX3_id

V(CEETLOC)

dllfuncZ1_id

DLL YdllfuncY1() {

...

dllfuncX2();

...

dllfuncX3();

}



...

dllfuncX1();

...

dllfuncX2();

…

dllfuncY1();

}

Appl A WSA

Was DLL Y already loaded?

No, so LE loads it, initializes WSA and updates all DLL Y descriptors in Appl A, just as it did for DLL X

V(dllfuncX1)

A(dllfuncX1 WSA)

V(dllfuncX2)

A(dllfuncX2 WSA)

V(dllfuncY1)

A(dllfuncY1 WSA)


dllfuncX2() {…};

dllfuncX3() {…};

DLL X WSA

DLL Y WSA

V(CEETLOC)

dllfuncX2_id

V(CEETLOC)

dllfuncX3_id

V(CEETLOC)

dllfuncZ1_id

DLL YdllfuncY1() {

...

dllfuncX2();

...

dllfuncX3();

}



...

dllfuncX1();

...

dllfuncX2();

…

dllfuncY1();

}

Appl A WSA

Execution procedes with dllfuncY1 , which itself calls

dllfuncX2 which resides in DLL X

V(dllfuncX1)

A(dllfuncX1 WSA)

V(dllfuncX2)

A(dllfuncX2 WSA)

V(dllfuncY1)

A(dllfuncY1 WSA)


dllfuncX2() {…};

dllfuncX3() {…};

DLL X WSA

DLL Y WSA

V(CEETLOC)

dllfuncX2_id

V(CEETLOC)

dllfuncX3_id

V(CEETLOC)

dllfuncZ1_id

DLL YdllfuncY1() {

...

dllfuncX2();

...

dllfuncX3();

}



...

dllfuncX1();

...

dllfuncX2();

…

dllfuncY1();

}

Appl A WSA

Was DLLX already loaded? Yes!So LE need not load DLLX or

allocate and initialize WSA for it.It just needs to update all DLL X descriptors in DLL Y, just as it did for DLL X descriptors in Appl A.

V(dllfuncX1)

A(dllfuncX1 WSA)

V(dllfuncX2)

A(dllfuncX2 WSA)

V(dllfuncY1)

A(dllfuncY1 WSA)


dllfuncX2() {…};

dllfuncX3() {…};

DLL X WSA

DLL YdllfuncY1() {

...

dllfuncX2();

...

dllfuncX3();

}

DLL Y WSA

V(dllfuncX2)

A(dllfuncX2 WSA)

V(dllfuncX3)

A(dllfuncX3 WSA)

V(CEETLOC)

dllfuncZ1_id


Usage

• C DLL application and DLL

• Compile with options:

• DLL, RENT, LONGNAME, and possibly EXPORTALL for DLLs

• #pragma export preferred to EXPORTALL

• DLL(CALLBACKANY) – enhanced compability at a price!

• For XPLINK and LP64

• LONGNAME is defaulted

• DLL is superfluous, CALLBACKANY not supported (“not required”)


Usage (cont’d)

• C++ DLL application and DLL

• Compile with options:

• None except possibly EXPORTALL for DLLs

• _Export keyword preferred to EXPORTALL

• LONGNAME is defaulted

• DLL is superfluous, but available for DLL(CALLBACKANY)

• LONGNAME applies only to non-C++ linkages

• CALLBACKANY applies only to non-C++ non-XPLINK linkages


Usage (cont’d)

• COBOL

• Compile DLL application with options:

• DLL, RENT, NOEXPORTALL

• CALL literal gets resolved from side deck (implicit)

• CALL identifier causes COBOL to do explicit call, requires DLL (module) name to match function name

• Compile DLL with options:

• DLL, RENT, EXPORTALL


Usage (cont’d)

• PL/I

• Compile DLL application with options:

• RENT

• CALL statement or function reference (implicit)

• ENTRY constant on a FETCH statement, causes COBOL to do explicit call, requires DLL (module) name to match PROC name

• Compile DLL with options:

• DLLINIT, RENT

• DLLINIT is equivalent to coding OPTIONS(FETCHABLE) on all non-MAIN procedures


Usage (cont’d)


• Use Language Environment provided macros

• Must assemble with GOFF option

• You’re no dummy!


Usage for HLASMExport/Call requires:• GOFF• >= ZOSV1R1(PM3)/ZOSV1R5(PM4SUB2)

non-XPLink XPLink AMODE 64

Function Prolog(EXPORT=)

CEEENTRYEDCPRLG EDCXPRLG CELQPRLG

Function Epilog CEETERMEDCEPLG EDCXEPLG CELQEPLG

DSA mapping EDCDSADCEEDSADSASZ includes

arguments

CEEDSADSASZ includes

argumentsCall (I ) Function(CBN, CBR only) CEEPCALL EDCXCALL CELQCALL

Declare (I/E )Variable

CEEPDDAdeclare/DC to

define WSA var, optional I/E

= =

Refer to (I/E )Variable

CEEPLDAload reg w/@WSA

var, I/ (local)E= =


Usage

• Binder

• Bind your DLL application with options:

• REUS=RENT

• INCLUDE the side deck(s) from DLLs in the set of object modules to bind

• After final autocall, unresolved DLL references are picked up from the side deck(s)

• Bind you DLL with options:

• REUS=RENT

• DYNAM=DLL, which tells binder to:

• Write IMPORT statements to SYSDEFSD (the definition side-deck)

• Creates IEWBLIT (Loader Information Table) in module

• Create IEWBCIE (Compiler Import / Export table) in module


Sample – C (implicit)

DLL application (siggy.c)

DLL (sigdll.c)

#include <signal.h>

#include <stdio.h>

extern int sigcaught;

int dllsig(int);

main() {

int rc;

...

rc = dllsig(SIGUSR1);

...

raise(SIGUSR1);

if ( sigcaught ) {

printf("signal %d caught\n", sigcaught);

}

...

}

#define _XOPEN_SOURCE_EXTENDED 1

#include <signal.h>

#include <stdlib.h>

#include <errno.h>

int sigcaught = 0;

void dllcatch(int);

int dllsig(int sig) {

struct sigaction sa;

int rc;

errno = 0;

sa.sa_handler = dllcatch ;

sa.sa_flags = 0;

sigemptyset(&sa.sa_mask);

rc = sigaction(sig, &sa, NULL);

return errno;

}

void dllcatch (int signum) {

sigcaught = signum;

}


Sample – C (cont’d)

• c89 -Wc,dll,expo -osigdll -Wl,dll sigdll.c

• c89 -Wc,dll -o siggy siggy.c sigdll.x


Sample – COBOL (implicit)

DLL Application (MyCOBOLAppl.cbl) DLL (MyCOBOLDllFn.cbl)IDENTIFICATION DIVISION.

PROGRAM-ID. 'MyCOBOLAppl'.

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

INPUT-OUTPUT SECTION.

FILE-CONTROL.

DATA DIVISION.

FILE SECTION.

WORKING-STORAGE SECTION.

01 TODAYS-DATE-YYYYMMDD PIC 9(8).

PROCEDURE DIVISION.

Display 'MyCOBOLAppl: Entered'

MOVE FUNCTION CURRENT-DATE(1:8) TO TODAYS-DATE-YYYYMMDD

Call 'MyCOBOLDllFn' using todays-date-yyyymmdd

Display 'MyCOBOLAppl: Done'

GOBACK.

IDENTIFICATION DIVISION.

PROGRAM-ID. 'MyCOBOLDllFn' .

ENVIRONMENT DIVISION.

CONFIGURATION SECTION.

INPUT- OUTPUT SECTION.

FILE- CONTROL.

DATA DIVISION.

FILE SECTION.

WORKING-STORAGE SECTION.

LINKAGE SECTION.

01 TODAYS-DATE- YYYYMMDD PIC 9(8).

PROCEDURE DIVISION using todays-date- yyyymmdd.

Display 'MyCOBOLDllFn: Entered'

Display 'MyCOBOLDllFn: Todays date is ' todays-date-yyyymmdd

Display 'MyCOBOLDllFn: Done'

GOBACK.


Sample – COBOL (cont’d)

• cob2 -o MYCOBOLD \-Wl,dll -qDLL,RENT,EXPORTALL,LIST \MyCOBOLDLLFn.cbl

• cob2 -o MYCOBOLA \-qDLL,RENT,NOEXPORTALL,LIST \MyCOBOLAppl.cbl \MYCOBOLD.x

[email protected] march 2012 session #10767 · contact for information on the product...

Documents