z/OSVersion 2 Release 3

Language EnvironmentVendor Interfaces

IBM

SA38-0688-30

Note

Before using this information and the product it supports, read the information in “Notices” on page923.

© Copyright International Business Machines Corporation 1991, 2019.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

Figures.............................................................................................................. xvii

Tables..............................................................................................................xxvii

About this document....................................................................................... xxxiiiUsing your documentation.....................................................................................................................xxxiiiHow to read syntax diagrams................................................................................................................ xxxivz/OS information.................................................................................................................................... xxxvi

How to send your comments to IBM................................................................ xxxviiIf you have a technical problem........................................................................................................... xxxvii

Summary of changes....................................................................................... xxxixSummary of changes for Language Environment for z/OS Version 2 Release 3 (V2R3) .....................xxxixSummary of changes for Language Environment for z/OS Version 2 Release 2 (V2R2)........................... xlSummary of changes for Language Environment for z/OS Version 2 Release 1 (V2R1) as updated

February, 2015...................................................................................................................................... xliSummary of changes for Language Environment for z/OS Version 2 Release 1 (V2R1) as updated

December, 2013....................................................................................................................................xliSummary of changes for z/OS Version 2 Release 1 (V2R1)...................................................................... xli

What Language Environment supports................................................................xliii

Part 1. Language Environment vendor interfaces for AMODE 31 / AMODE 24applications.......................................................................................................1

Chapter 1. Common interfaces and conventions........................................................................................3Common runtime environment.............................................................................................................. 3

Library not all linkable.......................................................................................................................3Reentrancy........................................................................................................................................ 3Recursion...........................................................................................................................................3AMODE/RMODE.................................................................................................................................3Member code AMODE restrictions................................................................................................... 4External names................................................................................................................................. 4General register usage at entry to callable services........................................................................4General register usage at exit from callable services...................................................................... 4Floating-point register conventions................................................................................................. 5Access register conventions............................................................................................................. 5Program mask conventions.............................................................................................................. 5Routine layout................................................................................................................................... 5Prolog information blocks...............................................................................................................10Epilog code......................................................................................................................................38Base locator table........................................................................................................................... 38CEEYEPAF — locates an XPLINK or non-XPLINK entry point PPA1 and PPA2 from a passed

DSA.............................................................................................................................................40__ep_find () — returns the address of the entry point of the function owning the dsa_p DSA.....41CEEYPPAF — locates a field in the PPA1 optional area based on a passed pointer to the

PPA1...........................................................................................................................................42Language Environment dynamic storage area (non-XPLINK).............................................................44

iii

Language Environment dynamic storage area ( XPLINK)....................................................................45Language Environment common anchor area.....................................................................................46Language Environment enclave data block......................................................................................... 69Language Environment process control block.................................................................................... 79Language Environment region control block....................................................................................... 85Example of a condition information block........................................................................................... 91Example of a machine state block....................................................................................................... 94Language Environment member list and event handler..................................................................... 97Language Environment callable services calling conventions............................................................ 98

Callable services syntax declarations............................................................................................ 99Optional parameter support...........................................................................................................99Data type definitions.......................................................................................................................99ENTRY variable............................................................................................................................. 100LABEL variable.............................................................................................................................. 101Callable service example..............................................................................................................101Invoking a callable service from C/C++....................................................................................... 101

Chapter 2. CALL linkage conventions......................................................................................................103Terminology........................................................................................................................................103Standard CALL linkage conventions.................................................................................................. 104

Register usage.............................................................................................................................. 104Stack format..................................................................................................................................104CEEVGTUN — next available byte locator service........................................................................109CEEVSSEG — return the stack segment bounds..........................................................................110Standard save area....................................................................................................................... 112Argument list format.....................................................................................................................112

FASTLINK CALL linkage conventions.................................................................................................113Register usage.............................................................................................................................. 113Stack frame mapping....................................................................................................................114Argument list format.....................................................................................................................118Leaf routines................................................................................................................................. 120Code sequences........................................................................................................................... 121

Extra Performance Linkage (XPLINK) CALL linkage conventions..................................................... 124Register usage ..............................................................................................................................124Stack frame mapping....................................................................................................................125

Chapter 3. Program initialization and termination..................................................................................147Initialization overview........................................................................................................................147Termination overview.........................................................................................................................147

Enclave termination......................................................................................................................147Process termination......................................................................................................................148

Putting initialization/termination together........................................................................................149Member interfaces for initialization...................................................................................................149

CEESTART..................................................................................................................................... 149CEEFMAIN.....................................................................................................................................154CEEMAIN.......................................................................................................................................154CEESTART operation.....................................................................................................................155CEESIOP — set interrupt option service ......................................................................................156Signature CSECT........................................................................................................................... 157CEEBETBL — Language Environment externals table .................................................................157Event handler routines................................................................................................................. 158CEEBLLST — language list............................................................................................................ 159CEEINT interface.......................................................................................................................... 162CEEBCRLM — cancel/release load module..................................................................................164CEEBSENM — set the enclave name............................................................................................ 165CEEBSRCM — set the enclave return code modifier....................................................................166CEEPGFD — get function pointer..................................................................................................168CEEPRFD — release function pointer........................................................................................... 169

iv

CEEBADDM (also known as CEE3ADDM, __CEEBADDM) — add new members to the enclave.170CEE3CRE — create enclave.......................................................................................................... 172CEE3CSYS — creating nested enclave......................................................................................... 175CEE3MBR — member bootstrap routine...................................................................................... 177CEE3SRSA — set return save area................................................................................................179CEE3DDBC — set dummy DSA back chain...................................................................................179CEE3PLST — PLIST manipulation.................................................................................................180CEEGIN — obtain the program's invocation name.......................................................................181CEERELU — RCB lookup................................................................................................................181

Member interfaces for termination....................................................................................................182CEEBTREC (also known as CEETREC, __CEEBTREC) — explicit termination through HLL

constructs................................................................................................................................ 182CEEBTREN (also known as CEETREN, __CEEBTREN) — terminate without raising T_I_S......... 183CEEATTRM — register event handler............................................................................................184Termination sequence.................................................................................................................. 184Termination failures......................................................................................................................184T_I_S condition.............................................................................................................................185

Member event codes for initialization and termination.................................................................... 185Language Environment abend summary...........................................................................................186

CEECOPP — runtime option compiler service..............................................................................187Options processing event............................................................................................................. 189

User exits............................................................................................................................................189CEEBSHL — exit from/re-entry to Language Environment shell................................................. 189

Language Environment interface validation exit............................................................................... 190Structure of the Language Environment interface validation exit...............................................191CEEXVSEL — high-level selection criteria.................................................................................... 191Language-specific interface validation exit................................................................................. 193

Interface for preinitialization............................................................................................................. 199CEEPIPI — invocation for subroutine by address........................................................................ 199Preinitialization environment and system request block mode..................................................201

Chapter 4. Storage management............................................................................................................ 205Dynamic storage (heap) services.......................................................................................................205

Storage model...............................................................................................................................205CWI to the heap services..............................................................................................................206Process-level heap storage management................................................................................... 207Region-level heap storage management..................................................................................... 208CEEVGTSB — unconditional get heap below................................................................................210CEEV#GTS — get heap storage.................................................................................................... 211CEEV#FRS — free heap storage................................................................................................... 212CEEVHRPT — obtain dynamic heap storage report..................................................................... 212

User-created heap services............................................................................................................... 213CEEVUHCR — create a heap using user-provided storage.......................................................... 213CEEVUHGT — allocate storage from a user-created heap...........................................................215CEEVUHFR — return storage to a user-created heap.................................................................. 215CEEVUHRP — produce a storage report for a user-created heap............................................... 216

Vendor heap manager interface........................................................................................................ 216Requirements from the vendor.................................................................................................... 216What the vendor should know......................................................................................................217Activating the vendor heap manager........................................................................................... 219__vhm_event() API....................................................................................................................... 219

XPLINK DSA extension services........................................................................................................ 219CEEVXPAL — XPLINK DSA extension........................................................................................... 219__alcaxp() — XPLINK DSA extension (alloca).............................................................................. 220

XPLINK compatibility stack swapping services................................................................................ 221CEEVROND — run on downward-growing stack.......................................................................... 221CEEVRONU — run on upward-growing stack............................................................................... 222CEEVH2OS — XPLINK to OS linkage on upward-growing stack..................................................223

v

__stack_info() - stack segment ranges............................................................................................. 224CEL4SFCR - stack frame area corrupted........................................................................................... 226CELHSFCR - stack frame area corrupted...........................................................................................226Saving the stack pointer.....................................................................................................................226

Chapter 5. Condition representation.......................................................................................................229Condition representation model........................................................................................................229Data objects........................................................................................................................................230

Condition token data type (CEECTOK)......................................................................................... 230Feedback code..............................................................................................................................233

CEEGETFB — Construct a condition token given a facility ID and a message number.................... 233

Chapter 6. National language support and message handler................................................................ 235National language support.................................................................................................................235Introduction to Language Environment message services...............................................................236MSGFILE — related CWIs...................................................................................................................236

CEECLOS — close ddname............................................................................................................237CEEODMF — open an input ddname............................................................................................ 237CEEOPMF — open the MSGFILE ddname.....................................................................................238CEEQDMF — query an input ddname........................................................................................... 239CEEQUMF — query the MSGFILE ddname................................................................................... 240CEECHMF — change the MSGFILE ddname.................................................................................240Relationship between date/time and COUNTRY settings........................................................... 241

Message handling services................................................................................................................ 242CEECMIB — create a message insert area entry......................................................................... 242CEEMFNDM — return the MIB address........................................................................................ 243CEE3SMO — suppress printing of messages............................................................................... 245

C/C++-specific vendor interfaces...................................................................................................... 245__cttbl() — returns address of _LC_ctype_t structure................................................................. 245ASCII/EBCDIC mixed mode support for enhanced ASCII C-RTL................................................246__ae_thread_setmode() — set character mode: ASCII or EBCDIC.............................................247__ae_thread_swapmode() — swap character mode to ASCII or EBCDIC.................................. 248__isASCII() — determine character mode: ASCII or EBCDIC..................................................... 249__ae_autoconvert_state() — returns automatic conversion state of thread.............................. 249

Chapter 7. Condition management......................................................................................................... 251Compiler-writer interfaces (CWIs).....................................................................................................251

CEE3ERP — support for user-provided error recovery................................................................ 251CEE3RSUM — resume an interrupted program............................................................................252CEESGLN — signal invalid resume request.................................................................................. 255CEESGLT — signal a condition and terminate.............................................................................. 256CEE3SMS — set machine state.....................................................................................................257CEE3SMS2 — set machine state 2............................................................................................... 259CEEGOTO — restart execution at specified label.........................................................................260CEEHDHDL (also known as __CEEHDHDL) — register an event handler for stack frame zero

processing................................................................................................................................265CEEMRCM — move the resume cursor.........................................................................................266CEEYDSAF — find the previous DSA.............................................................................................267__dsa_prev() — chain back to previous DSA................................................................................269__far_jump() — perform far jump (C/C++ and XPLINK only).......................................................271__set_stack_softlimit() — set stack soft limit (C/C++ and XPLINK only)....................................273

Other Language Environment routines and handlers....................................................................... 274Interface to the language-specific handlers................................................................................274DSA exit routines.......................................................................................................................... 275Shunt routine................................................................................................................................ 276Attention handling........................................................................................................................ 278Error processing............................................................................................................................278

Other Language Environment condition manager topics..................................................................282

vi

Language Environment condition information block...................................................................282Errors during condition handling..................................................................................................282

HLL conventions and information...................................................................................................... 283HLL condition handling conventions............................................................................................ 283HLL condition handling information............................................................................................. 284

Language Environment-issued abends............................................................................................. 284

Chapter 8. Program management........................................................................................................... 287Loading and deleting programs in different environments...............................................................287CWI to program management process services............................................................................... 287

CEEZLOD — process load service.................................................................................................288CEEZDEL — process delete service.............................................................................................. 288

CWI to program management region services..................................................................................289CEEZLODR — region load service................................................................................................. 289CEEZDELR — region delete service.............................................................................................. 290

CWI to program management enclave services............................................................................... 291CEEPLOD — enclave level load service........................................................................................ 291CEEPLOD2 (also known as __CEEPLOD2)— enclave/thread level load service..........................292CEEPDEL — enclave level delete service..................................................................................... 295CEEPDEL2 — enclave level delete service................................................................................... 296CEEPQLD (also known as __CEEPQLD) — return information about loaded module................. 296CEEPCB_DELETE — system dependent delete service............................................................... 298CEEPCB_LOAD — system dependent load service...................................................................... 298CEEPLODT — thread level load service........................................................................................ 299CEEPDELT – thread level delete service...................................................................................... 301

Library subroutine access.................................................................................................................. 302LIBVECs.........................................................................................................................................302LIBPACKs...................................................................................................................................... 304LIBVEC descriptor (LVD)...............................................................................................................305LIBVEC initialization..................................................................................................................... 307CWI to LIBVEC low-level services................................................................................................307CEEPLVI — LIBVEC initialization...................................................................................................308CEEPLVE — verify load/delete...................................................................................................... 309CEEPLVT — LIBVEC termination...................................................................................................310

CEEPPOS — program object services................................................................................................ 311CWIs for explicit DLL reference......................................................................................................... 314

CEEPLDE — load DLL.....................................................................................................................314CEEPFDE — DLL free..................................................................................................................... 316CEEPQDF — query DLL function................................................................................................... 317CEEPQDV — query DLL variable................................................................................................... 319

CWIs for implicit DLL reference......................................................................................................... 320CEETLOC — stub for trigger load on call.......................................................................................321CEETHLOC — stub for trigger load on XPLINK call by name....................................................... 322FDCB — function descriptor control block .................................................................................. 323__bldxfd() — build an XPLINK compatibility descriptor.............................................................. 325CEETLOR — stub for trigger load on reference.............................................................................326VDCB — variable descriptor control block................................................................................... 327CEETGTFN — stub for function invocation of old code................................................................ 328

CWIs to find the writable static area (WSA)...................................................................................... 329CEEPFWSA — find writable static area (WSA)............................................................................. 329__fnwsa() —- CWI to find a writable static area.......................................................................... 330__static_reinit() — CWI to reinitialize writable static area.......................................................... 332

CEEDLLF — DLL failure control block.................................................................................................333

Chapter 9. Debugging and performance analysis...................................................................................337Language Environment-provided CWIs for the debug tool...............................................................337

__setHookEvents() — specify execute hook events for target process...................................... 337CEE3CBTS — pass component broker connector parameters.................................................... 339

vii

CEEBFBC — build feedback code routine.................................................................................... 341CEEKRGPM — register pattern match routine..............................................................................343CEEQFBC — query feedback code routine................................................................................... 344CEEQLOD — query modules loaded with enclave level load service.......................................... 345CEETGCAA — get next CAA pointer..............................................................................................347CEETSFB — translate standard feedback token.......................................................................... 347CEETSFC — translate standard feedback code............................................................................348CEL4CASR — call service routines for non-XPLINK applications................................................ 349CEL4RGSR — enable service routine............................................................................................350CELHCASR — call service routines for XPLINK applications....................................................... 352

Debug tool-provided event handlers................................................................................................. 353Debug tool event handler............................................................................................................. 353

Language Environment actions for the interactive debug tool......................................................... 360Language Environment interactive debug data areas.......................................................................361

Execute hook support...................................................................................................................361Performance analysis support........................................................................................................... 362

Profile tool event handler............................................................................................................. 362Language Environment actions for profiler..................................................................................365

Chapter 10. DFSORT interface................................................................................................................ 367DFSORT interface description............................................................................................................367CEE3SRT — call DFSORT.................................................................................................................... 367ILC within SORT exits......................................................................................................................... 369Error handling within SORT exits....................................................................................................... 369

Messages and conditions............................................................................................................. 369

Chapter 11. Math library..........................................................................................................................371Calling math services from an application........................................................................................ 371Math service condition handling requirements.................................................................................371

Member-specific condition handling............................................................................................371Data types and their abbreviations....................................................................................................372CWI conventions for scalar math services........................................................................................ 372

Register interface......................................................................................................................... 372Conventional interface................................................................................................................. 373

Condition token values for math services......................................................................................... 373Math services..................................................................................................................................... 374

Scalar math services.................................................................................................................... 375Degree input/output trigonometry functions...............................................................................380Entry point names for scalar bit manipulation routines.............................................................. 381

Message ID — message text for math library.................................................................................... 382Language Environment math services — value of inserts........................................................... 383

Language Environment conversion services..................................................................................... 385Terminology.................................................................................................................................. 385CEEYCVHE — E-format output conversion routine...................................................................... 386CEEYCVHF — F-format output conversion routine...................................................................... 388CEEYCVHI — decimal to float input conversion routine.............................................................. 392

Chapter 12. Dump and tracing services..................................................................................................397Dump services....................................................................................................................................397

CEE3DMP — runtime environment dump service........................................................................398CEESDMP — symbolic dump of a routine.....................................................................................398CEETRCB — traceback utility........................................................................................................399CEETBCK — traceback utility (replaces CEETRCB)......................................................................401Member language dump exit........................................................................................................411CEEKLDMP (also known as CEELDMP, __CEEKLDMP) — single line message dump service..... 411CEEVDMP — variable dump service............................................................................................. 412CEEHDMP — hexadecimal storage dump service........................................................................415CEEBDMP — control block dump service.....................................................................................416

viii

Other dump-related CWIs................................................................................................................. 418CEE3CDO — check dump options.................................................................................................419CEEKSNP (also known as __CEEKSNP)— produce a SNAP dump...............................................419CEEURTB — produce a user routine traceback............................................................................421

Tracing services..................................................................................................................................423Global and member-specific tracing............................................................................................424CEEKCTRC — add a trace table entry........................................................................................... 425

Chapter 13. Subsystem considerations.................................................................................................. 427CICS and POSIX................................................................................................................................. 427Background information.................................................................................................................... 427

Terminology.................................................................................................................................. 427Running a program under CICS....................................................................................................429Language Environment-CICS and Language Environment-batch program models...................430

Language Environment-CICS interface............................................................................................. 431Languages supported................................................................................................................... 431Extended runtime language interface..........................................................................................432Flowchart of activities.................................................................................................................. 435Language Environment-CICS interface routines' DSA.................................................................436Partition initialization (Language Environment enablement)......................................................436Partition termination (Language Environment disablement)...................................................... 439Establish ownership type call.......................................................................................................440Thread initialization...................................................................................................................... 444Thread termination.......................................................................................................................445Run unit (program) initialization...................................................................................................446Run unit (program) termination................................................................................................... 450Run unit (program) begin invocation............................................................................................451Run unit (program) end invocation...............................................................................................454Error recovery............................................................................................................................... 460Determine working storage and static storage............................................................................461Perform GOTO call........................................................................................................................ 462

CEECTCB — set TCB+X'144' routine..................................................................................................464CEECCICS — partition initialization changes..................................................................................... 465IMS considerations............................................................................................................................ 465

IMS to Language Environment..................................................................................................... 465Language Environment to IMS — CEETDLI.................................................................................. 467Implementation............................................................................................................................467

Chapter 14. Anchor support....................................................................................................................469Anchor service....................................................................................................................................469

Fetch the anchor routine.............................................................................................................. 469Set the anchor routine.................................................................................................................. 470

CEEARLU — anchor lookup................................................................................................................ 471Anchor considerations....................................................................................................................... 471Bypassing anchor lookup, set, or reset............................................................................................. 472

Chapter 15. Member language information............................................................................................473OS services — restricted use..............................................................................................................473Structure of executable programs.....................................................................................................474Central control blocks........................................................................................................................ 474Event handler..................................................................................................................................... 475Event handler calls.............................................................................................................................475

Event code 1 — handle condition represented by the CIB event................................................ 475Event code 2 — perform enablement for this stack frame event................................................ 477Event code 3 — handle condition according to language defaults event....................................478Event code 4 — runtime options event.........................................................................................479Event code 5 — main-opts event..................................................................................................480Event code 6 — event handler utilities event...............................................................................481

ix

Event code 7 — dump event handler event..................................................................................485Event code 8 — new load module event...................................................................................... 488Event code 9 — new condition event............................................................................................489Event code 10 — resume from a condition handler event...........................................................490Event code 11 — DSA exit routines event.................................................................................... 491Event code 12 — national language change event...................................................................... 492Event code 13 — country code change event.............................................................................. 493Event code 14 — main routine invocation event..........................................................................493Event code 15 — atterm event..................................................................................................... 494Event code 16 — z/OS Debugger event........................................................................................495Event code 17 — process initialization event...............................................................................495Event code 18 — enclave initialization event...............................................................................496Event code 19 — enclave termination event................................................................................498Event code 20 — query/build feedback code event.................................................................... 499Event code 21 — process termination event............................................................................... 500Event code 22 — DLL initialization event..................................................................................... 501Event code 23 — stack frame zero processing event.................................................................. 502Event code 24 — POSIX events event.......................................................................................... 504Event code 25 — static object constructor event........................................................................ 507Event code 26 — region initialization event................................................................................. 509Event code 27 — region termination event.................................................................................. 509Event code 28 — identify module entry point event....................................................................510Event code 29 — determine enclave work area lengths event....................................................511Event code 31 — determine working storage (CICS only) event................................................. 511Event code 32 — perform GOTO validation (CICS only) event.................................................... 512Event code 33 — member needs options processing event........................................................513Event code 34 — command line equivalent event.......................................................................513Event code 35 — default options event........................................................................................514Event code 36 — static destructor event..................................................................................... 514Event code 37 — preallocated storage event...............................................................................515Event code 38 — normal resume in DSA event............................................................................516Event code 39 — interrupt received event................................................................................... 517Event code 40 — get/release function pointer event...................................................................519Event code 41 — cancel/release load module event...................................................................520Event code 42 — automatic destructor event..............................................................................521Event code 44 — member program mask event..........................................................................522

Chapter 16. z/OS UNIX System Services support.................................................................................. 525Thread management functions..........................................................................................................525

CEEOPAI........................................................................................................................................525CEEOPAD.......................................................................................................................................526CEEOPAGD ................................................................................................................................... 526CEEOPAGS ....................................................................................................................................527CEEOPAGW .................................................................................................................................. 528CEEOPASD ....................................................................................................................................529CEEOPASS ....................................................................................................................................530CEEOPASW ...................................................................................................................................530CEEOPC ........................................................................................................................................ 531CEEOPE ........................................................................................................................................ 533CEEOPEQ ......................................................................................................................................533CEEOPJ .........................................................................................................................................534CEEOPO ........................................................................................................................................536CEEOPS ........................................................................................................................................ 536

Signal handling CWIs......................................................................................................................... 537CEEOKILL ..................................................................................................................................... 537

Thread keyed data CWIs....................................................................................................................539CEEOPGS ......................................................................................................................................539CEEOPKC ......................................................................................................................................540

x

CEEOPKD ......................................................................................................................................542CEEOPSS ...................................................................................................................................... 542

Thread cancellation CWIs..................................................................................................................544CEEOPCPO ................................................................................................................................... 544CEEOPCPU ................................................................................................................................... 545

Thread synchronization — mutex and read-write locks....................................................................546CEEOPMD .....................................................................................................................................546CEEOPMI ......................................................................................................................................548CEEOPML ......................................................................................................................................551CEEOPML2 ................................................................................................................................... 553CEEOPMT ..................................................................................................................................... 553CEEOPMU .....................................................................................................................................555CEEOPMU2 ...................................................................................................................................556CEEOPRL ...................................................................................................................................... 557CEEOPRL2 .................................................................................................................................... 559CEEOPRT ...................................................................................................................................... 559CEEOPRU ......................................................................................................................................561CEEOPRU2 ................................................................................................................................... 562CEEOPWL ..................................................................................................................................... 563CEEOPWL2 ................................................................................................................................... 565CEEOPWT .....................................................................................................................................565CEEOPXD ......................................................................................................................................567CEEOPXG ......................................................................................................................................569CEEOPXI .......................................................................................................................................571CEEOPXS ...................................................................................................................................... 573

Thread synchronization — condition variables..................................................................................575CEEOPCB ......................................................................................................................................575CEEOPCD ......................................................................................................................................577CEEOPCI .......................................................................................................................................578CEEOPCS ......................................................................................................................................579CEEOPCT ...................................................................................................................................... 581CEEOPCW .....................................................................................................................................583CEEOPDD ..................................................................................................................................... 585CEEOPDG ..................................................................................................................................... 586CEEOPDI ...................................................................................................................................... 588CEEOPDS ......................................................................................................................................589CEEOPTW......................................................................................................................................590

Process control functions support.....................................................................................................593CEEOEXEC ....................................................................................................................................593CEEOFORK ................................................................................................................................... 595CEEOSPWN .................................................................................................................................. 597

Miscellaneous utilities....................................................................................................................... 599CEEOEXIT .....................................................................................................................................599CEEOXEXE ....................................................................................................................................600

Support for POSIX functions getenv(), setenv(), and clearenv().......................................................600Errors.............................................................................................................................................601CEEBENV ......................................................................................................................................601

Chapter 17. COBOL-specific vendor interfaces...................................................................................... 605ILBOLLDX — OS/VS COBOL library load/delete exit..........................................................................605IGZCXCC — COBOL call/cancel routine............................................................................................. 607IGZXAPI — COBOL file and runtime information query routine........................................................608IGZCXSF — COBOL extract side file routine...................................................................................... 620IGZACALL — calls Enterprise COBOL V5.1 or later programs from Language Environment

conforming assembler ................................................................................................................. 623

Chapter 18. PL/I-specific vendor interfaces...........................................................................................625IBMPXSF — PL/I extract side file routine.......................................................................................... 625

xi

Chapter 19. C/C++ special purpose interfaces for IEEE floating-point................................................. 629IEEE binary floating-point introduction.............................................................................................629IEEE decimal floating-point introduction.......................................................................................... 629Selection of fdlibm or fdlibm replacement functions....................................................................... 630IEEE floating-point functions.............................................................................................................631

__chkbfp() — check IEEE facilities usage.................................................................................... 631__fp_btoh() — convert from IEEE floating-point to hexadecimal floating-point........................ 631__fp_cast() — cast between floating-point data types................................................................ 632__fp_htob() — convert from hexadecimal floating-point to IEEE floating-point........................ 633__fp_level() — determine type of IEEE facilities available.......................................................... 634__fp_read_rnd() — determine rounding mode............................................................................ 635__fp_setmode() — set IEEE or hexadecimal mode......................................................................636__fp_swapmode() — set IEEE or hexadecimal mode.................................................................. 637__fp_swap_rnd() — swap rounding mode....................................................................................638__fpc_rd() — read floating-point control register........................................................................ 639__fpc_rs() — read floating-point control register and change rounding mode field...................639__fpc_rw() — read and write the floating-point control register.................................................640__fpc_sm() — set floating-point control register rounding mode field....................................... 641__fpc_wr() — write the floating-point control register................................................................ 642__isBFP() — determine application floating-point mode............................................................ 643__to_xx() – C/C++ compiler casting support............................................................................... 643

Part 2. Language Environment vendor interfaces for AMODE 64 applications....... 649

Chapter 20. Common interfaces and conventions for AMODE 64 applications.................................... 651Common runtime environment..........................................................................................................651

Library not all linkable.................................................................................................................. 651Reentrancy....................................................................................................................................651Recursion...................................................................................................................................... 651AMODE/RMODE............................................................................................................................ 651Member code AMODE restrictions............................................................................................... 651External names............................................................................................................................. 651Routine layout...............................................................................................................................652Prolog information blocks............................................................................................................ 654

Language Environment dynamic storage area.................................................................................. 665Language Environment control block mappings............................................................................... 666

Language Environment library anchor area................................................................................. 666Language Environment library control area.................................................................................668Language Environment common anchor area............................................................................. 670Language Environment debugger interfaces area....................................................................... 672Language Environment enclave data block................................................................................. 675Language Environment process control block.............................................................................676Language Environment region control block............................................................................... 677

Chapter 21. Compiler-writer interfaces (CWIs) supported for AMODE 64 applications.......................679CEEBADDM (also known as CEE3ADDM, __CEEBADDM) — add new members to the enclave...... 680CEEBSRSA — set return save area.....................................................................................................682__CEEBSRCM() — set the enclave return code modifier................................................................... 682CEEBTREC (also known as CEETREC, __CEEBTREC) — explicit termination through HLL

constructs......................................................................................................................................684CEEBTREN (also known as CEETREN, __CEEBTREN) — terminate without raising T_I_S.............. 685CEEHDHDL (also known as __CEEHDHDL) — register an event handler for stack frame zero

processing..................................................................................................................................... 686CEEHSGL (also known as __CEEHSGL) -- Raise a signal.................................................................. 686CEEHSGLT (also known as __CEEHSGLT) -- Signal a condition and terminate................................689CEEKHDP2 (also known as __CEEKHDP2) -- hexadecimal dump service....................................... 690

xii

CEEKLDMP (also known as CEELDMP, __CEEKLDMP) — single line message dump service.......... 693CEEKSNP (also known as __CEEKSNP)— produce a SNAP dump.................................................... 693CEEMCMIB (also known as CEECMIB, __CEEMCMIB) — create a message insert area entry........ 695CEEMURTB (also known as CEEURTB, __CEEMURTB) — produce a user routine traceback.......... 696CEEPDEL2 (also known as __CEEPDEL2) -- Enclave-level delete service....................................... 697CEEPFWSA (also known as __CEEPFWSA) -- Find writable static area (WSA)................................ 698CEEPLOD2 (also known as __CEEPLOD2)— enclave/thread level load service............................... 699CEEPQLD (also known as __CEEPQLD) — return information about load module...........................702CELQTBCK (also known as __CELQTBCK) -- 64-bit traceback service............................................ 703

Chapter 22. CALL linkage convention for AMODE 64 applications........................................................ 707Terminology........................................................................................................................................707XPLINK CALL linkage conventions for AMODE 64 applications........................................................707

Register usage and linkage...........................................................................................................708Stack format..................................................................................................................................708

Chapter 23. Program initialization and termination for AMODE 64 applications.................................. 725Initialization overview........................................................................................................................725Termination overview.........................................................................................................................725

Enclave termination......................................................................................................................725Process termination......................................................................................................................726

Putting initialization and termination together................................................................................. 726Member interfaces for initialization...................................................................................................726

CELQSTRT..................................................................................................................................... 727CELQMAIN.................................................................................................................................... 729CELQFMAN....................................................................................................................................729CELQBST operation.......................................................................................................................730CELQETBL — Language Environment externals table .................................................................730CELQLLST — Language Environment language list...................................................................... 731Signature CSECT........................................................................................................................... 732Initialization parameter list.......................................................................................................... 733

Member interfaces for termination....................................................................................................734CEECOPP — Runtime Option Compiler Service.................................................................................735

Chapter 24. Storage management for AMODE 64 applications.............................................................739Vendor heap manager interface for AMODE 64 applications........................................................... 739

Requirements from the vendor.................................................................................................... 739Support provided for the vendor heap manager interface.......................................................... 740Activating the vendor heap manager........................................................................................... 740__vhm_event().............................................................................................................................. 741

__alcaxp() — AMODE 64 DSA extension (alloca).............................................................................. 741Memory object dump priority............................................................................................................ 742Memory object user tokens............................................................................................................... 742Saving the stack pointer.....................................................................................................................742__CEL4SFCR - stack frame area corrupted....................................................................................... 743

Chapter 25. Condition representation for AMODE 64 applications....................................................... 745Condition representation model........................................................................................................745Data objects........................................................................................................................................745

Condition token data type............................................................................................................ 745Feedback code..............................................................................................................................748

Chapter 26. National language support and message services for AMODE 64 applications................749National language support.................................................................................................................749Language Environment message services........................................................................................ 749C/C++-specific vendor interfaces...................................................................................................... 750

Chapter 27. Condition management for AMODE 64 applications..........................................................751

xiii

Application programming interfaces (APIs)......................................................................................751__dsa_prev() — Chain back to previous DSA............................................................................... 751__ep_find() — returns the address of the entry point of the function owning the dsa_p DSA... 754__far_jump() — Perform far jump.................................................................................................755

Language Environment shunt routine for AMODE 64 applications.................................................. 757Establishing a program interrupt shunt service...........................................................................757

Other Language Environment condition manager topics..................................................................758Language Environment condition information block...................................................................758Errors during condition handling..................................................................................................758

Language Environment-issued abends............................................................................................. 759

Chapter 28. Debugging and performance analysis for AMODE 64 applications................................... 761Language Environment-provided functions for the debug tool........................................................ 761

__le_debug_set_resume_mch() — set resume machine state................................................... 761__setHookEvents() — specify execute hook events for target process...................................... 762

Debug tool-provided event handlers................................................................................................. 767Debug tool event handler............................................................................................................. 767

Language Environment actions for the interactive debug tool......................................................... 772Language Environment interactive debug data areas.......................................................................773

Execute hook support...................................................................................................................773Performance analysis support........................................................................................................... 774

Profile tool event handler............................................................................................................. 774Language Environment actions for profiler..................................................................................777

Chapter 29. DFSORT interface for AMODE 64 applications................................................................... 779DFSORT 64-bit interface description................................................................................................ 779__CEEYSORT — call DFSORT for AMODE 64 applications.................................................................779SORT User Exit Routines for AMODE 64 Applications...................................................................... 781ILC within SORT exits......................................................................................................................... 782Error handling within SORT exits....................................................................................................... 782

Chapter 30. Anchor support for AMODE 64 applications.......................................................................783

Chapter 31. Member language information for AMODE 64 applications...............................................785Event handler..................................................................................................................................... 785Event handler calls.............................................................................................................................785

Event code 1 — handle condition represented by the CIB event................................................ 786Event code 2 — perform enablement for this stack frame event................................................ 787Event code 3 — stack frame zero handle condition..................................................................... 788Event code 5 — main options processing.....................................................................................789Event code 6 — event handler utilities event...............................................................................789Event code 7 — dump event handler event..................................................................................793Event code 11 — DSA exit routines event.................................................................................... 797Event code 14 — main routine invocation event..........................................................................798Event code 18 — enclave initialization event...............................................................................799Event code 19 — enclave termination event................................................................................801Event code 23 — stack frame zero processing event.................................................................. 801

Chapter 32. Preinitialized Environments for Authorized Programs for AMODE 64 applications.......... 803Creating Preinitialized Environments for Authorized Programs....................................................... 803

Creating a user-managed environment....................................................................................... 803Creating a system-managed environment...................................................................................804Preinitialized Environments for Authorized Programs tasks....................................................... 804

Executing a routine in Preinitialized Environments for Authorized Programs..................................805Calling a main routine...................................................................................................................805Calling a subroutine......................................................................................................................806Using runtime options.................................................................................................................. 806Selecting an environment.............................................................................................................806

xiv

Providing recovery........................................................................................................................ 806Terminating Preinitialized Environments for Authorized Programs..................................................807Examples of using Preinitialized Environments for Authorized Programs....................................... 807

Using Preinitialized Environments for Authorized Programs in service request block (SRB)mode........................................................................................................................................ 807

Using Preinitialized Environments for Authorized Programs in cross-memory mode................807CELAAUTH macro...............................................................................................................................808

CELAAUTH environments.............................................................................................................808Syntax for REQUEST=USERINIT.................................................................................................. 811Syntax for REQUEST=USERCALL..................................................................................................814Syntax for REQUEST=USERTERM................................................................................................ 818Syntax for REQUEST=MNGDINIT.................................................................................................821Syntax for REQUEST=MNGDCALL................................................................................................ 826Syntax for REQUEST=MNGDUPDT............................................................................................... 830Syntax for REQUEST=MNGDTERM...............................................................................................833CELAAUTH general notes............................................................................................................. 836ABEND codes................................................................................................................................ 836Return and reason codes..............................................................................................................836

Appendix A. Options control block and supplementary options control block.......853Options control block.............................................................................................................................. 853Supplementary options control block.....................................................................................................900

Appendix B. CALL linkage argument examples................................................... 905FASTLINK CALL linkage argument examples..........................................................................................905XPLINK CALL linkage argument examples............................................................................................. 910

Appendix C. Accessibility...................................................................................919Accessibility features.............................................................................................................................. 919Consult assistive technologies................................................................................................................ 919Keyboard navigation of the user interface.............................................................................................. 919Dotted decimal syntax diagrams.............................................................................................................919

Notices..............................................................................................................923Terms and conditions for product documentation................................................................................. 924IBM Online Privacy Statement.............................