Abstract for Language Environment Vendor Interfaces
Summary of changes
Summary of changes
Summary of changes
Summary of changes for z/OS Version 2 Release 1 (V2R1)
Language Environment vendor interfaces for AMODE 31 / AMODE 24 applications
Common interfaces and conventions
Common runtime environment
Library not all linkable
Reentrancy
Recursion
AMODE/RMODE
Member code AMODE restrictions
External names
General register usage at entry to callable services
General register usage at exit from callable services
Floating-point register conventions
Access register conventions
Program mask conventions
Routine layout
Prolog information blocks
Epilog code
Base locator table
CEEYEPAF — locates an XPLINK or non-XPLINK entry point PPA1 and PPA2 from a passed DSA
__ep_find () — returns the address of the entry point of the function owning the dsa_p DSA
CEEYPPAF — locates a field in the PPA1 optional area based on a passed pointer to the PPA1
Language Environment dynamic storage area – non-XPLINK
Language Environment dynamic storage area – XPLINK
Language Environment common anchor area
Language Environment enclave data block
Language Environment process control block
Language Environment region control block
Example of a condition information block
Example of a machine state block
Language Environment member list and event handler
Language Environment callable services calling conventions
Callable services syntax declarations
Optional parameter support
Data type definitions
ENTRY variable
LABEL variable
Callable service example
Invoking a callable service from C/C++
CALL linkage conventions
Terminology
Standard CALL linkage conventions
Register usage
Stack format
CEEVGTUN — next available byte locator service
CEEVSSEG — return the stack segment bounds
Standard save area
Argument list format
FASTLINK CALL linkage conventions
Register usage
Stack frame mapping
Argument list format
Leaf routines
Code sequences
Extra Performance Linkage (XPLINK) CALL linkage conventions
Register usage
Stack frame mapping
Program initialization and termination
Initialization overview
Termination overview
Enclave termination
Process termination
Putting initialization/termination together
Member interfaces for initialization
CEESTART
CEEFMAIN
CEEMAIN
CEESTART operation
CEESIOP — set interrupt option service
Signature CSECT
CEEBETBL — Language Environment externals table
Event handler routines
CEEBLLST — language list
CEEINT interface
CEEBCRLM — cancel/release load module
CEEBSENM — set the enclave name
CEEBSRCM — set the enclave return code modifier
CEEPGFD — get function pointer
CEEPRFD — release function pointer
CEE3ADDM — add new members to the enclave
CEE3CRE — create enclave
CEE3CSYS — creating nested enclave
CEE3MBR — member bootstrap routine
CEE3SRSA — set return save area
CEE3DDBC — set dummy DSA back chain
CEE3PLST — PLIST manipulation
CEEGIN — obtain the program's invocation name
CEERELU — RCB lookup
Member interfaces for termination
CEETREC — explicit termination through HLL constructs
CEETREN — terminate without raising T_I_S
CEEATTRM — register event handler
Termination sequence
Termination failures
T_I_S condition
Member event codes for initialization and termination
Language Environment abend summary
CEECOPP — runtime option compiler service
Options processing event
User exits
CEEBSHL — exit from/re-entry to Language Environment shell
Language Environment interface validation exit
Structure of the Language Environment interface validation exit
CEEXVSEL — high-level selection criteria
Language-specific interface validation exit
Interface for preinitialization
CEEPIPI — invocation for subroutine by address
Preinitialization environment and system request block mode
Storage management
Dynamic storage (heap) services
Storage model
CWI to the heap services
Process-level heap storage management
Region-level heap storage management
CEEVGTSB — unconditional get heap below
CEEV#GTS — get heap storage
CEEV#FRS — free heap storage
CEEVHRPT — obtain dynamic heap storage report
User-created heap services
CEEVUHCR — create a heap using user-provided storage
CEEVUHGT — allocate storage from a user-created heap
CEEVUHFR — return storage to a user-created heap
CEEVUHRP — produce a storage report for a user-created heap
Vendor heap manager interface
Requirements from the vendor
What the vendor should know
Activating the vendor heap manager
__vhm_event() API
XPLINK DSA extension services
CEEVXPAL — XPLINK DSA extension
__alcaxp() — XPLINK DSA extension (alloca)
XPLINK compatibility stack swapping services
CEEVROND — run on downward-growing stack
CEEVRONU — run on upward-growing stack
CEEVH2OS — XPLINK to OS linkage on upward-growing stack
__stack_info() - stack segment ranges
Saving the stack pointer
Condition representation
Condition representation model
Data objects
Condition token data type (CEECTOK)
Feedback code
CEEGETFB — Construct a condition token given a facility ID and a message number
National language support and message handler
National language support
Introduction to Language Environment message services
MSGFILE — related CWIs
CEECLOS — close ddname
CEEODMF — open an input ddname
CEEOPMF — open the MSGFILE ddname
CEEQDMF — query an input ddname
CEEQUMF — query the MSGFILE ddname
CEECHMF — change the MSGFILE ddname
Relationship between date/time and COUNTRY settings
Message handling services
CEECMIB — create a message insert area entry
CEEMFNDM — return the MIB address
CEE3SMO — suppress printing of messages
C/C++-specific vendor interfaces
__cttbl() — returns address of _LC_ctype_t structure
ASCII/EBCDIC mixed mode support for enhanced ASCII C-RTL
__ae_thread_setmode() — set character mode: ASCII or EBCDIC
__ae_thread_swapmode() — swap character mode to ASCII or EBCDIC
__isASCII() — determine character mode: ASCII or EBCDIC
__ae_autoconvert_state() — returns automatic conversion state of thread
Condition management
Compiler-writer interfaces (CWIs)
CEE3ERP — support for user-provided error recovery
CEE3RSUM — resume an interrupted program
CEESGLN — signal invalid resume request
CEESGLT — signal a condition and terminate
CEE3SMS — set machine state
CEE3SMS2 — set machine state 2
CEEGOTO — restart execution at specified label
CEEHDHDL — register an event handler for stack frame zero processing
CEEMRCM — move the resume cursor
CEEYDSAF — find the previous DSA
__dsa_prev() — chain back to previous DSA
__far_jump() — perform far jump (C/C++ and XPLINK only)
__set_stack_softlimit() — set stack soft limit (C/C++ and XPLINK only)
Other Language Environment routines and handlers
Interface to the language-specific handlers
DSA exit routines
Shunt routine
Attention handling
Error processing
Other Language Environment condition manager topics
Language Environment condition information block
Errors during condition handling
HLL conventions and information
HLL condition handling conventions
HLL condition handling information
Language Environment-issued abends
Program management
Loading and deleting programs in different environments
CWI to program management process services
CEEZLOD — process load service
CEEZDEL — process delete service
CWI to program management region services
CEEZLODR — region load service
CEEZDELR — region delete service
CWI to program management enclave services
CEEPLOD — enclave level load service
CEEPLOD2 — enclave/thread level load service
CEEPDEL — enclave level delete service
CEEPDEL2 — enclave level delete service
CEEPQLD — return information about loaded module
CEEPCB_DELETE — system dependent delete service
CEEPCB_LOAD — system dependent load service
CEEPLODT — thread level load service
CEEPDELT – thread level delete service
Library subroutine access
LIBVECs
LIBPACKs
LIBVEC descriptor (LVD)
LIBVEC initialization
CWI to LIBVEC low-level services
CEEPLVI — LIBVEC initialization
CEEPLVE — verify load/delete
CEEPLVT — LIBVEC termination
CEEPPOS — program object services
CWIs for explicit DLL reference
CEEPLDE — load DLL
CEEPFDE — DLL free
CEEPQDF — query DLL function
CEEPQDV — query DLL variable
CWIs for implicit DLL reference
CEETLOC — stub for trigger load on call
CEETHLOC — stub for trigger load on XPLINK call by name
FDCB — function descriptor control block
__bldxfd() — build an XPLINK compatibility descriptor
CEETLOR — stub for trigger load on reference
VDCB — variable descriptor control block
CEETGTFN — stub for function invocation of old code
CWIs to find the writable static area (WSA)
CEEPFWSA — find writable static area (WSA)
__fnwsa() —- CWI to find a writable static area
__static_reinit() — CWI to reinitialize writable static area
CEEDLLF — DLL failure control block
Debugging and performance analysis
Language Environment-provided CWIs for the debug tool
__setHookEvents() — specify execute hook events for target process
CEE3CBTS — pass component broker connector parameters
CEEBFBC — build feedback code routine
CEEKRGPM — register pattern match routine
CEEQFBC — query feedback code routine
CEEQLOD — query modules loaded with enclave level load service
CEETGCAA — get next CAA pointer
CEETSFB — translate standard feedback token
CEETSFC — translate standard feedback code
Debug tool-provided event handlers
Debug tool event handler
Language Environment actions for the interactive debug tool
Language Environment interactive debug data areas
Execute hook support
Performance analysis support
Profile tool event handler
Language Environment actions for profiler
DFSORT interface
DFSORT interface description
CEE3SRT — call DFSORT
ILC within SORT exits
Error handling within SORT exits
Messages and conditions
Math library
Calling math services from an application
Math service condition handling requirements
Member-specific condition handling
Data types and their abbreviations
CWI conventions for scalar math services
Register interface
Conventional interface
Condition token values for math services
Math services
Scalar math services
Degree input/output trigonometry functions
Entry point names for scalar bit manipulation routines
Message ID — message text for math library
Language Environment math services — value of inserts
Language Environment conversion services
Terminology
CEEYCVHE — E-format output conversion routine
CEEYCVHF — F-format output conversion routine
CEEYCVHI — decimal to float input conversion routine
Dump and tracing services
Dump services
CEE3DMP — runtime environment dump service
CEESDMP — symbolic dump of a routine
CEETRCB — traceback utility
CEETBCK — traceback utility (replaces CEETRCB)
Member language dump exit
CEELDMP — single line message dump service
CEEVDMP — variable dump service
CEEHDMP — hexadecimal storage dump service
CEEBDMP — control block dump service
Other dump-related CWIs
CEE3CDO — check dump options
CEEKSNP — produce a SNAP dump
CEEURTB — produce a user routine traceback
Tracing services
Global and member-specific tracing
CEEKCTRC — add a trace table entry
Subsystem considerations
CICS and POSIX
Background information
Terminology
Running a program under CICS
Language Environment-CICS and Language Environment-batch program models
Language Environment-CICS interface
Languages supported
Extended runtime language interface
Flowchart of activities
Language Environment-CICS interface routines' DSA
Partition initialization (Language Environment enablement)
Partition termination (Language Environment disablement)
Establish ownership type call
Thread initialization
Thread termination
Run unit (program) initialization
Run unit (program) termination
Run unit (program) begin invocation
Run unit (program) end invocation
Error recovery
Determine working storage and static storage
Perform GOTO call
CEECTCB — set TCB+X'144' routine
CEECCICS — partition initialization changes
IMS considerations
IMS to Language Environment
Language Environment to IMS — CEETDLI
Implementation
Anchor support
Anchor service
Fetch the anchor routine
Set the anchor routine
CEEARLU — anchor lookup
Anchor considerations
Bypassing anchor lookup, set, or reset
Member language information
OS services — restricted use
Structure of executable programs
Central control blocks
Event handler
Event handler calls
Event code 1 — handle condition represented by the CIB event
Event code 2 — perform enablement for this stack frame event
Event code 3 — handle condition according to language defaults event
Event code 4 — runtime options event
Event code 5 — main-opts event
Event code 6 — event handler utilities event
Event code 7 — dump event handler event
Event code 8 — new load module event
Event code 9 — new condition event
Event code 10 — resume from a condition handler event
Event code 11 — DSA exit routines event
Event code 12 — national language change event
Event code 13 — country code change event
Event code 14 — main routine invocation event
Event code 15 — atterm event
Event code 16 — Debug Tool event
Event code 17 — process initialization event
Event code 18 — enclave initialization event
Event code 19 — enclave termination event
Event code 20 — query/build feedback code event
Event code 21 — process termination event
Event code 22 — DLL initialization event
Event code 23 — stack frame zero processing event
Event code 24 — POSIX events event
Event code 25 — static object constructor event
Event code 26 — region initialization event
Event code 27 — region termination event
Event code 28 — identify module entry point event
Event code 29 — determine enclave work area lengths event
Event code 31 — determine working storage (CICS only) event
Event code 32 — perform GOTO validation (CICS only) event
Event code 33 — member needs options processing event
Event code 34 — command line equivalent event
Event code 35 — default options event
Event code 36 — static destructor event
Event code 37 — preallocated storage event
Event code 38 — normal resume in DSA event
Event code 39 — interrupt received event
Event code 40 — get/release function pointer event
Event code 41 — cancel/release load module event
Event code 42 — automatic destructor event
Event code 44 — member program mask event
z/OS UNIX System Services support
Thread management functions
CEEOPAI
CEEOPAD
CEEOPAGD
CEEOPAGS
CEEOPAGW
CEEOPASD
CEEOPASS
CEEOPASW
CEEOPC
CEEOPE
CEEOPEQ
CEEOPJ
CEEOPO
CEEOPS
Signal handling CWIs
CEEOKILL
Thread keyed data CWIs
CEEOPGS
CEEOPKC
CEEOPKD
CEEOPSS
Thread cancellation CWIs
CEEOPCPO
CEEOPCPU
Thread synchronization — mutex and read-write locks
CEEOPMD
CEEOPMI
CEEOPML
CEEOPML2
CEEOPMT
CEEOPMU
CEEOPMU2
CEEOPRL
CEEOPRL2
CEEOPRT
CEEOPRU
CEEOPRU2
CEEOPWL
CEEOPWL2
CEEOPWT
CEEOPXD
CEEOPXG
CEEOPXI
CEEOPXS
Thread synchronization — condition variables
CEEOPCB
CEEOPCD
CEEOPCI
CEEOPCS
CEEOPCT
CEEOPCW
CEEOPDD
CEEOPDG
CEEOPDI
CEEOPDS
Process control functions support
CEEOEXEC
CEEOFORK
CEEOSPWN
Miscellaneous utilities
CEEOEXIT
CEEOXEXE
Support for POSIX functions getenv(), setenv(), and clearenv()
Errors
CEEBENV
COBOL-specific vendor interfaces
ILBOLLDX — OS/VS COBOL library load/delete exit
IGZCXCC — COBOL call/cancel routine
IGZXAPI — COBOL file and runtime information query routine
IGZCXSF — COBOL extract side file routine
PL/I-specific vendor interfaces
IBMPXSF — PL/I extract side file routine
C/C++ special purpose interfaces for IEEE floating-point
IEEE binary floating-point introduction
IEEE decimal floating-point introduction
Selection of fdlibm or fdlibm replacement functions
IEEE floating-point functions
__chkbfp() — check IEEE facilities usage
__fp_btoh() — convert from IEEE floating-point to hexadecimal floating-point
__fp_cast() — cast between floating-point data types
__fp_htob() — convert from hexadecimal floating-point to IEEE floating-point
__fp_level() — determine type of IEEE facilities available
__fp_read_rnd() — determine rounding mode
__fp_setmode() — set IEEE or hexadecimal mode
__fp_swapmode() — set IEEE or hexadecimal mode
__fp_swap_rnd() — swap rounding mode
__fpc_rd() — read floating-point control register
__fpc_rs() — read floating-point control register and change rounding mode field
__fpc_rw() — read and write the floating-point control register
__fpc_sm() — set floating-point control register rounding mode field
__fpc_wr() — write the floating-point control register
__isBFP() — determine application floating-point mode
__to_xx() – C/C++ compiler casting support
Language Environment vendor interfaces for AMODE 64 applications
Common interfaces and conventions for AMODE 64 applications
Common runtime environment
Library not all linkable
Reentrancy
Recursion
AMODE/RMODE
Member code AMODE restrictions
External names
Routine layout
Prolog information blocks
PPA2 in support of XPLINK
Language Environment dynamic storage area
Language Environment control block mappings
Language Environment library anchor area
Language Environment library control area
Language Environment common anchor area
Language Environment debugger interfaces area
Language Environment enclave data block
Language Environment process control block
Language Environment region control block
Compiler-writer interfaces (CWIs) supported for AMODE 64 applications
CALL linkage convention for AMODE 64 applications
Terminology
XPLINK CALL linkage conventions for AMODE 64 applications
Register usage and linkage
Stack format
Program initialization and termination for AMODE 64 applications
Initialization overview
Termination overview
Enclave termination
Process termination
Putting initialization and termination together
Member interfaces for initialization
CELQSTRT
CELQMAIN
CELQFMAN
CELQBST operation
CELQETBL — Language Environment externals table
CELQLLST — Language Environment language list
Signature CSECT
Initialization parameter list
Member interfaces for termination
CEECOPP — Runtime Option Compiler Service
Storage management for AMODE 64 applications
Vendor heap manager interface for AMODE 64 applications
Requirements from the vendor
Support provided for the vendor heap manager interface
Activating the vendor heap manager
__vhm_event()
__alcaxp() — AMODE 64 DSA extension (alloca)
Memory object dump priority
Memory object user tokens
Saving the stack pointer
Condition representation for AMODE 64 applications
Condition representation model
Data objects
Condition token data type
Feedback code
National language support and message services for AMODE 64 applications
National language support
Language Environment message services
C/C++-specific vendor interfaces
Condition management for AMODE 64 applications
Application programming interfaces (APIs)
__dsa_prev() — Chain back to previous DSA
__ep_find() — returns the address of the entry point of the function owning the dsa_p DSA
__far_jump() — Perform far jump
Language Environment shunt routine for AMODE 64 applications
Establishing a program interrupt shunt service
Other Language Environment condition manager topics
Language Environment condition information block
Errors during condition handling
Language Environment-issued abends
Debugging and performance analysis for AMODE 64 applications
Language Environment-provided functions for the debug tool
__le_debug_set_resume_mch() — set resume machine state
__setHookEvents() — specify execute hook events for target process
Debug tool-provided event handlers
Debug tool event handler
Language Environment actions for the interactive debug tool
Language Environment interactive debug data areas
Execute hook support
Performance analysis support
Profile tool event handler
Language Environment actions for profiler
Anchor support for AMODE 64 applications
Preinitialized Environments for Authorized Programs for AMODE 64 applications
Creating Preinitialized Environments for Authorized Programs
Creating a user-managed environment
Creating a system-managed environment
Preinitialized Environments for Authorized Programs tasks
Executing a routine in Preinitialized Environments for Authorized Programs
Calling a main routine
Calling a subroutine
Using runtime options
Selecting an environment
Providing recovery
Terminating Preinitialized Environments for Authorized Programs
Examples of using Preinitialized Environments for Authorized Programs
Using Preinitialized Environments for Authorized Programs in service request block (SRB) mode
Using Preinitialized Environments for Authorized Programs in cross-memory mode
CELAAUTH macro
CELAAUTH environments
Syntax for REQUEST=USERINIT
Syntax for REQUEST=USERCALL
Syntax for REQUEST=USERTERM
Syntax for REQUEST=MNGDINIT
Syntax for REQUEST=MNGDCALL
Syntax for REQUEST=MNGDUPDT
Syntax for REQUEST=MNGDTERM
CELAAUTH general notes
ABEND codes
Return and reason codes
Options control block and supplementary options control block
Options control block
Supplementary options control block
CALL linkage argument examples
FASTLINK CALL linkage argument examples
XPLINK CALL linkage argument examples