Abstract for MVS Programming: Callable Services for High-Level Languages
Summary of changes
Changes for z/OS V2R1, as updated September 2014
Changes for z/OS V2R1, as updated March 2014
z/OS Version 2 Release 1 summary of changes
Window services
Introduction to window services
Permanent data objects
Temporary data objects
Structure of a data object
What does window services provide?
The ways that window services can map an object
Example 1 — Mapping a permanent object that has no scroll area
Example 2 — Mapping a permanent object that has a scroll area
Example 3 — Mapping a temporary object
Example 4 — Mapping multiple windows to an object
Example 5 — Mapping multiple objects
Access to permanent data objects
Access to temporary data objects
Using window services
Obtaining access to a data object
Identifying the object
Permanent object
Temporary object
Specifying the object’s size
Specifying the type of access
Obtaining a scroll area
Defining a view of a data object
Identifying the data object
Identifying a window
Defining the disposition of a window’s contents
Replace option
Retain option
Defining the expected reference pattern
Identifying the blocks you want to view
Extending the size of a data object
Defining multiple views of an object
Non-overlapping views
Overlapping views
Saving interim changes to a permanent data object
Updating a temporary data object
Refreshing changed data
Updating a permanent object on DASD
When there is a scroll area
When there is no scroll area
Changing a view in a window
Terminating access to a data object
Handling return codes and abnormal terminations
Window services
CSREVW — View an object and sequentially access it
Abend codes
Return codes and reason codes
CSRIDAC — Request or terminate access to a data object
Abend codes
Return codes and reason codes
CSRREFR — Refresh an object
Abend codes
Return codes and reason codes
CSRSAVE — Save changes made to a permanent object
Abend codes
Return codes and reason codes
CSRSCOT — Save object changes in a scroll area
Abend codes
Return codes and reason codes
CSRVIEW — View an object
Abend codes
Return codes and reason codes
Window services coding examples
ADA example
C/370 example
COBOL example
FORTRAN example
Pascal example
PL/I example
Reference pattern services
Introduction to reference pattern services
How does the system manage data?
An example of how the system manages data in an array
What pages does the system bring in when a gap exists?
Example 1
Example 2
Example 3
Using reference pattern services
Defining the reference pattern for a data area
Defining the range of the area
Identifying the direction of the reference
Defining the reference pattern
Using CSRIRP when a gap exists
Choosing the number of bytes on a page fault
Examples of using CSRIRP to define a reference pattern
Removing the definition of the reference pattern
Handling return codes
Reference pattern services
CSRIRP — Define a reference pattern
Return codes and reason codes
CSRRRP — Remove a reference pattern
Return codes and reason codes
Reference pattern services coding examples
C/370 example
COBOL example
FORTRAN example
Pascal example
PL/I example
Global resource serialization latch manager services
Using the latch manager services
Syntax and linkage conventions for latch manager callable services
ISGLCRT — Create a latch set
ABEND codes
Return codes
Examples of calls to latch manager services
ISGLOBT — Obtain a latch
ABEND codes
Return codes
Example
ISGLREL — Release a latch
ABEND codes
Return codes
Example
ISGLPRG — Purge a requestor from a latch set
ABEND codes
Return codes
Example
ISGLPBA — Purge a group of requestors from a group of latch sets
ABEND codes
Return codes
Resource recovery services (RRS)
Using protected resources
Resource recovery programs
Two-phase commit protocol
Resource recovery process
Requesting resource protection and recovery
Using distributed resource recovery
Application_Backout_UR (SRRBACK)
Description
Environment
Programming requirements
High level language (HLL) definitions
Restrictions
Input register information
Output register information
Performance implications
Syntax
Parameters
ABEND codes
Return codes
Example
Application_Commit_UR (SRRCMIT)
Description
Environment
Programming requirements
High level language (HLL) definitions
Restrictions
Input register information
Output register information
Performance implications
Syntax
Parameters
ABEND codes
Return codes
Example
Additional callable services
CEA TSO/E address space services
Introduction to CEA TSO/E address space services
CEA TSO/E address space manager components
System prerequisites for the CEA TSO/E address space services
Working with TSO/E address spaces started by CEA
Communicating with programs running in the TSO/E address spaces
JSON format for TSO/E messages
Sample TSO/E messages written to the z/OS UNIX message queue
Reconnecting to CEA TSO/E address spaces
Idle time versus RECONTIME
TSO/E LOGON RECONNECT operand versus CEA reconnect
Using CEA TSO/E address space services
Invoking the CEATsoRequest API
Parameters
Requirements for callers
Understanding the request types
CeaTsoStart - Starting a new TSO/E session
CeaTsoAttn - Sending an attention interrupt to a TSO/E session
CeaTsoEnd - Ending a TSO/E session
CeaTsoPing - Sending a ping on behalf of an application
CeaTsoQuery - Querying the TSO/E address spaces
CeaTsoQueryApp - Querying TSO/E sessions by application
Return, reason, and diagnostic codes
Return codes
Reason codes
Diagnostic codes
CEAYTSOR header file
CEAXRDEF header file
Programming example
Sample compile job
zEnterprise Data Compression (zEDC)
Overview and planning of zEnterprise Data Compression (zEDC)
Requirements for zEnterprise Data Compression
Planning for zEnterprise Data Compression
Application interfaces for zEnterprise Data Compression
Invoking unauthorized interfaces for zEnterprise Data Compression
zlib for zEnterprise Data Compression
Standard zlib functions
IBM-provided zlib compatible C library
Running zlib
Invoking System z authorized interfaces for zEnterprise Data Compression
System z authorized compression services
FPZ4RZV — Rendezvous compression service
FPZ4PRB — Probe device availability compression service
FPZ4RMR — Memory registration compression service
FPZ4DMR — Deregister memory compression service
FPZ4ABC — Submit compression request
FPZ4URZ — Unrendezvous compression request
Usage example of a System z authorized service
Troubleshooting for zEnterprise Data Compression
Other callable services
IEAAFFN — Assign processor affinity for encryption or decryption
Restrictions and limitations
Requirements
Return codes
CSRL16J — Transfer control to another routine
Defining the entry characteristics of the target routine
Freeing dynamic storage associated with the caller
Programming requirements
Restrictions
Performance implications
Syntax diagram
C/370 syntax
PL/I syntax
Parameters
Return codes
Example
C/370 example program
Assembler program for use with the C/370 example
CSRSI — System information service
Description
Environment
Programming requirements
Restrictions
Input register information
Output register information
Syntax
Parameters
Return codes
CSRSIC C/370 header file
Base Control Program internal interface (BCPii) services
Base Control Program internal interface (BCPii)
BCPii setup and installation
Setting up connectivity to the support element
Levels of hardware that BCPii supports
Enable BCPii communications on the support element
Define the BCPii community name on the support element
Setting up authority to use BCPii
Program authority
General security product authority
Authority to the particular resource
Community name defined in the security product for each CPC
BCPii configuration
Setting up event notification for BCPii z/OS UNIX applications
CEA address space setup
CEA ENF security configuration
Setting up access for BCPii TSO/E REXX execs
BCPii startup and shutdown
BCPii address space does not start up at IPL
Ending the HWIBCPii address space
Restarting the HWIBCPii address space
BCPii callable services
Syntax, linkage and programming considerations
Calling formats
BCPii connection scope
Connections with address space affinity
Connections with task affinity
Linkage considerations
REXX programming considerations
Executing a BCPii REXX exec in the System REXX environment
BCPii REXX programming restrictions for the System REXX environment
Using the HWIREXX interface
Return codes from the HWIREXX service
Using the AXREXX macro
Executing a BCPii REXX exec in the TSO/E REXX environment
BCPii REXX programming restrictions for the TSO/E environment
Executing a BCPii REXX exec in an ISV-provided REXX environment
BCPii REXX programming restrictions for an ISV-provided REXX environment
REXX Programming tips
Return codes from a REXX BCPii host command
REXX return codes from the BCPii hwihost function
Sample REXX exec
Assembler programming considerations
Programming Examples
HWICMD — Issue a BCPii hardware management command
Description
Environment
Programming requirements
REXX programming considerations for the HWICMD service
Restrictions
Authorization
Syntax
Parameters
ABEND codes
Return codes
Example
HWICONN — Establish a BCPii connection
Description
Environment
Programming requirements
REXX programming considerations for the HWICONN service
Restrictions
Authorization
Syntax
Parameters
ABEND codes
Return codes
Example
HWIDISC — Release a BCPii connection
Description
Environment
Programming requirements
REXX programming considerations for the HWIDISC service
Restrictions
Authorization
Syntax
Parameters
ABEND codes
Return codes
Example
HWIEVENT — Register or unregister for BCPii events
Monitoring events occurring on a particular CPC or image
Monitoring operating system message events (Hwi_Event_OpSysMsg)
Monitoring communication availability between BCPii and the CPC
Monitoring the status of the BCPii address space
Description
Environment
Programming requirements
REXX programming considerations for the HWIEVENT service
Restrictions
Authorization
Syntax
Parameters
ABEND codes
Return codes
Example
HWILIST — Retrieve HMC and BCPii configuration-related information
Description
Environment
Programming requirements
REXX programming considerations for the HWILIST service
Restrictions
Authorization
Syntax
Parameters
ABEND codes
Return codes
Example
HWIQUERY — BCPii retrieval of SE/HMC-managed attributes
Description
Environment
Programming requirements
REXX programming considerations for the HWIQUERY service
Restrictions
Authorization
Syntax
Parameters
ABEND codes
Return codes
Example
HWISET — BCPii set SE/HMC-managed attributes
Description
Environment
Programming requirements
REXX programming considerations for the HWISET service
Restrictions
Authorization
Syntax
Parameters
ABEND codes
Return codes
Example
HWIBeginEventDelivery — Begin delivery of BCPii event notifications
Description
Environment
Programming requirements
Restrictions
Authorization
Syntax
Parameters
ABEND codes
Return codes
Example
HWIEndEventDelivery — End delivery of BCPii event notifications
Description
Environment
Programming requirements
Restrictions
Authorization
Syntax
Parameters
ABEND codes
Return codes
Example
HWIManageEvents — Manage the list of BCPii events
Description
Environment
Programming requirements
Restrictions
Authorization
Syntax
Parameters
ABEND codes
Return codes
Example
HWIGetEvent — Retrieve outstanding BCPii event notifications
Description
Environment
Programming requirements
Restrictions
Authorization
Syntax
Parameters
ABEND codes
Return codes
Example
BCPii communication error reason codes
BCPii summary tables
HWIQUERY and HWISET
HWICMD
HWIEVENT
General use C/C++ header files