Abstract for MVS Programming: Assembler Services Guide
Summary of changes
Summary of changes for z/OS Version 2 Release 1 (V2R1) as updated February 2015
z/OS Version 2 Release 1 summary of changes
Introduction
Linkage conventions
Saving the calling program's registers
Caller-provided save area
Linkage convention for floating point registers
Linkage convention for the floating point control register
Linkage conventions for vector registers
System-provided linkage stack
Using the linkage stack
Example of using the linkage stack
Using a caller-provided save area
If not changing ARs or bits 0–31 of the 64–bit GPRs
Example
If changing the contents of bits 0-31 of the 64-bit GPRs but not changing ARs
Example of F5SA
Example of F8SA
If starting in AMODE 64
Example
If changing ARs without using the linkage stack
Example
Establishing a base register
Linkage procedures for primary mode programs
Primary mode programs receiving control
Primary mode programs returning control
Primary mode programs calling another program
Linkage procedures for AR mode programs
AR mode programs receiving control and using the linkage stack
AR mode programs returning control and using the linkage stack
AR mode programs receiving control and not using the linkage stack
AR mode programs returning control and not using the linkage stack
AR mode programs calling another program
Conventions for passing information through a parameter list
Program in primary ASC mode
Programs in AR mode
Subtask creation and control
Creating the task
Priorities
Address space priority
Task priority
Subtask priority
Assigning and changing priority
Stopping and restarting a subtask (STATUS macro)
Task and subtask communications
Program management
Residency and addressing mode of programs
Residency mode definitions
Addressing mode definitions
Linkage considerations
Floating point considerations
Passing control between programs with the same AMODE
Passing control between programs with different AMODEs
Passing control between programs with all registers intact
Defining the entry characteristics of the target routine
Freeing dynamic storage associated with the caller
Load module structure types
Simple structure
Dynamic structure
Load module execution
Passing control in a simple structure
Passing control without return
Preparing to pass control
Passing control
Passing control with return
Preparing to pass control
Passing control
Analyzing the return
How control is returned
Return to the control program
Passing control in a dynamic structure
Bringing the load module into virtual storage
Location of the load module
The search for the load module
Using an existing copy
Using the LOAD macro
Passing control with return
Using the LINK or LINKX macro
Using CALL, BALR, BASR, or BASSM
How control is returned
Passing control without return
Passing control using a branch instruction
Using the XCTL or XCTLX macro
APF-authorized programs and libraries
Additional Entry Points
Entry Point and Calling Sequence Identifiers as Debugging Aids
Retrieving Information About Loaded Modules
Using the CSVINFO macro
Serialization
Coding a MIPR for the CSVINFO macro
Installing the MIPR
MIPR environment
Recovery for MIPR provided by CSVINFO
Entry specifications
Registers at entry
Return specifications
Registers at exit
CSVINFO service coding example
Understanding 31-bit addressing
Virtual storage
Addressing mode and residency mode
Requirements for execution in 31-bit addressing mode
Rules and conventions for 31-bit addressing
Mode sensitive instructions
BAL and BALR
LA
LRA
Branching instructions
Use of 31-bit addressing
Planning for 31-bit addressing
Converting existing programs
Writing new programs that use 31-bit addressing
New programs below 16 megabytes
New programs above 16 megabytes
Writing programs for MVS/370 and MVS systems with 31-bit addressing
SPLEVEL macro
Dual programs
Addressing mode and residency mode
Addressing mode - AMODE
Residency mode - RMODE
AMODE and RMODE combinations
AMODE and RMODE combinations at execution time
Determining the AMODE and RMODE of a load module
Assembler H support of AMODE and RMODE
AMODE and RMODE in the object module
AMODE and RMODE assembler instructions
Linkage editor and binder support of AMODE and RMODE
Linkage editor RMODE processing
Loader support for AMODE and RMODE
System support of AMODE and RMODE
How to change addressing mode
Establishing linkage
Using the BASSM and BSM instructions
Calling and returning with BASSM and BSM
Using pointer-defined linkage
Using an ADCON to obtain a pointer-defined value
Using the LOAD macro to obtain a pointer-defined value
Using supervisor-assisted linkage
Linkage assist routines
Example of using a linkage assist routine
Using capping - linkage using a prologue and epilogue
Performing I/O in 31-bit addressing mode
Using the EXCP macro
Using EXCPVR
Example of performing I/O while residing above 16 megabytes
Understanding the use of central storage
Central storage considerations for user programs
Load real address (LRA) instruction
GETMAIN macro
DAT-off routines
Resource control
Synchronizing tasks (WAIT, POST, and EVENTS macros)
Synchronizing tasks (Pause, Release, and Transfer)
Pause elements and pause element tokens
Using the services
Serializing access to resources (ISGENQ macro)
Naming the resource
Defining the scope of a resource
Local and global resources
Determining the resulting scope
Requesting exclusive or shared control
Limiting concurrent requests for resources
Processing the requests
Duplicate requests for a resource
Releasing the resource
ENQ and DEQ conditional and unconditional requests
ISGENQ conditional and unconditional requests
Avoiding interlock
Serializing access to resources through the ISGENQ macro
Collecting information about resources and their requestors (ISGQUERY and GQSCAN macros)
How ISGQUERY returns resource information
How GQSCAN returns resource information
How area size determines the information GQSCAN returns
How scope and token values determine the information GQSCAN returns
How GRS determines the scope of an ENQ or RESERVE request
Program interruption services
Specifying user exit routines
Using the SPIE macro
Program interruption control area
Program interruption element
Using the ESPIE macro
The extended program interruption element (EPIE)
Environment upon entry to user's exit routine
Functions performed in user exit routines
Requesting percolation from an ESPIE exit
Providing recovery
Understanding general recovery concepts
Deciding whether to provide recovery
Understanding errors in MVS
Understanding recovery routine states
Understanding the various routines in a recovery environment
Mainline routine
Recovery routine
Retry routine
Choosing the appropriate recovery routine
Floating point implications
Summary of recovery routine states
Understanding recovery routine options
Understanding how routines in a recovery environment interact
Writing recovery routines
Understanding what recovery routines do
Saving the return address to the system
Checking for the SDWA
Establishing addressability to the parameter area
Checking important fields in the SDWA
Checking the contents of the parameter area
Saving serviceability data
Requesting a dump
Correcting or minimizing the error
Deciding to retry or percolate
Recovery routines that retry
What the retry routine does
Recovery routines that percolate
Understanding the means of communication
Setting up, passing, and accessing the parameter area
Deciding what to include in the parameter area
Passing the parameter area
Accessing the parameter area
Using the SDWA
Updating the SDWA
Using the SETRP macro to update the SDWA
Symptom data required in the SDWA for dump suppression
Important fields in the SDWA
Special considerations for ESTAE-type recovery routines
RB considerations
Linkage stack considerations
Recovery routine
Retry routine
Deactivating an ESTAE-type recovery routine
Outstanding I/Os at the time of failure
Additional considerations specific to ESTAE-type recovery routines
Using ARRs
Understanding the recovery environment
Register contents
Register contents on entry to a recovery routine
Register contents on return from a recovery routine
Register contents
Other environmental factors in recovery
Environment on entry to an ESTAE-type recovery routine
Authorization
SDWA storage key
Dispatchable unit mode
AMODE
ASC mode
Interrupt status
DU-AL
Program mask
Condition of the linkage stack
Restricted environments
Environment on entry to a retry routine from an ESTAE-type recovery routine
Authorization
SDWA storage key
Dispatchable unit mode
AMODE
ASC mode
Interrupt status
DU-AL
Program mask
Condition of the linkage stack
Summary of environment on entry to an ESTAE-type recovery routine and its retry routine
Linkage stack at time of retry
Understanding recovery through a coded example
Understanding advanced recovery topics
Invoking RTM (ABEND macro)
Providing multiple recovery routines
Providing recovery for recovery routines
Providing recovery for multitasking programs
Using STAE/STAI routines
Dumping virtual storage (ABEND, SNAPX, SNAP, and IEATDUMP macros)
ABEND dumps
Obtaining a symptom dump
Suppressing dumps that duplicate previous dumps
Symptoms provided by a recovery routine
When a dump is not suppressed
SNAP dumps
Finding information in a SNAP dump
Obtaining a summary dump for an ABEND or SNAP dump
Transaction dumps
Reporting symptom records (SYMRBLD and SYMREC macros)
Writing symptom records to Logrec data set
The format of the symptom record
Symptom strings — SDB format
Building a symptom record using the SYMRBLD macro
Building a symptom record using the ADSR and SYMREC macros
Programming notes for section 1
Programming notes for section 2
Programming notes for section 2.1
Programming notes for section 3
Programming notes for section 4
Programming notes for section 5
Virtual storage management
Explicit requests for virtual storage
Obtaining storage through the GETMAIN macro
Obtaining storage through the STORAGE macro
Releasing storage through the FREEMAIN and STORAGE macros
Using the CPOOL macro
Subpool handling
Implicit requests for virtual storage
Reenterable load modules
Reenterable macros
Non-reenterable load modules
Freeing of virtual storage
Using the 64-bit address space
What is the 64-bit address space?
Why do you use virtual storage above the bar?
Memory objects
Using large pages
Using assembler instructions in the 64-bit address space
64-bit binary operations
How z/Architecture processes S/390 instructions
z/Architecture instructions that use the 64-bit GPR
64-bit addressing mode (AMODE)
Non-modal instructions
Modal instructions
Setting and checking the addressing mode
Linkage conventions
Register 15 contents on entry
Pitfalls to avoid
IARV64 services
Protecting storage above the bar
Relationship between the memory object and its owner
Creating memory objects
Example of creating a memory object
Using a memory object
Discarding data in a memory object
Releasing the physical resources that back pages of memory objects
Freeing a memory object
Example of freeing a memory object
Creating a guard area and changing its size
Example of creating a memory object with a guard area
An example of creating, using, and freeing a memory object
Callable cell pool services
Comparison of CPOOL macro and callable cell pool services
Storage considerations
Link-editing callable cell pool services
AMODE 24 or 31
AMODE 64
Using callable cell pool services
Handling return codes
Callable cell pool services coding example
AMODE 24 or 31
AMODE 64
Data-in-virtual
When to use data-in-virtual
Factors affecting performance
Creating a linear data set
Using the services of data-in-virtual
Identify
Access
Map
Save, savelist, and reset
Unmap
Unaccess
Unidentify
The IDENTIFY service
The ACCESS service
The MAP service
The SAVE service
The SAVELIST service
The RESET service
Effect of RETAIN mode on RESET
The UNMAP service
The UNACCESS and UNIDENTIFY services
Sharing data in an object
Miscellaneous restrictions for using data-in-virtual
DIV macro programming examples
General program description
Data-in-virtual sample program code
Data-in-virtual sample program code (continued)
Data-in-virtual sample program code (continued)
Data-in-virtual sample program code (continued)
Data-in-virtual sample program code (continued)
Executing the program
Using access registers
Access lists
Types of access lists
Writing programs in AR mode
Coding instructions in AR mode
Manipulating the contents of ARs
Loading an ALET into an AR
Loading the value of zero into an AR
The ALESERV macro
Adding an entry to an access list
Deleting an entry from an access list
Issuing MVS macros in AR mode
Example of using SYSSTATE
Using X-macros
Formatting and displaying AR information
Data spaces and hiperspaces
What are data spaces and hiperspaces?
What can a program do with a data space or a hiperspace?
How does a program obtain a data space and a hiperspace?
How does a program move data into a data space or hiperspace?
Who owns a data space or hiperspace?
Can an installation limit the use of data spaces and hiperspaces?
How does a program manage the storage in a data space or hiperspace?
Differences between data spaces and hiperspaces
Comparing data space and hiperspace use of physical storage
Which one should your program use?
An example of using a data space
An example of using a hiperspace
Creating and using data spaces
Manipulating data in a data space
Rules for creating, deleting, and managing data spaces
Creating a data space
Choosing the name of a data space
Specifying the size of a data space
Identifying the origin of a data space
Example of creating a data space
Establishing addressability to a data space
Examples of moving data into and out of a data space
Extending the current size of a data space
Releasing data space storage
Paging data space storage areas into and out of central storage
Deleting a data space
Using callable cell pool services to manage data space areas
Sharing data spaces among problem-state programs with PSW key 8-F
Sharing data spaces through the PASN-AL
Example of mapping a data-in-virtual object to a data space
Mapping a data-in-virtual object to a data space
Using data spaces efficiently
Example of creating, using, and deleting a data space
Dumping storage in a data space
Using checkpoint/restart
Creating and using hiperspaces
Standard hiperspaces
Shared and non-shared standard hiperspaces
Creating a hiperspace
Example of creating a standard hiperspace
Transferring data to and from hiperspaces
Read and write operations for standard hiperspaces
Obtaining additional HSPSERV performance
Extending the current size of a hiperspace
Releasing hiperspace storage
Deleting a hiperspace
Example of creating a standard hiperspace and using it
Using data-in-virtual with hiperspaces
Mapping a data-in-virtual object to a hiperspace
An example of mapping a data-in-virtual object to a hiperspace
Using a hiperspace as a data-in-virtual object
An example of a hiperspace as a data-in-virtual object
Using checkpoint/restart
Window services
Data objects
Permanent
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
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
Link-editing callable window services
Window services coding example
Sharing application data (name/token callable services)
Understanding name/token pairs and levels
Name/token pairs
Levels for name/token pairs
Determining what your program can do with name/token pairs
Deciding what name/token level you need
Task-level name/token pair
Home-level name/token pair
Owning and deleting name/token pairs
Using checkpoint/restart with name/token pairs
Link-editing name/token services
Processor storage management
Freeing virtual storage
Releasing storage
Protecting a range of virtual storage pages
Loading/paging out virtual storage areas
Virtual subarea list (VSL)
Page service list (PSL)
Defining the reference pattern (REFPAT)
How does the system handle the data in an array?
What pages does the system bring in when a gap exists?
Using the REFPAT macro
Identifying the data area and direction of reference
Defining the reference pattern
Choosing the number of bytes on a page fault
Examples of using REFPAT to define a reference pattern
Removing the definition of the reference pattern
Sharing data in virtual storage (IARVSERV macro)
Understanding the concepts of sharing data with IARVSERV
Storage you can use with IARVSERV
Obtaining storage for the source and target
Defining storage for sharing data and access
Changing storage access
How to share and unshare data
Accessing data in a sharing group
Example of sharing storage with IARVSERV
Use with data-in-virtual (DIV macro)
Diagnosing problems with shared data
Converting a central to virtual storage address (IARR2V macro)
Timing and communication
Checking for timer synchronization
Obtaining time of day and date
Converting between time of day and date and TOD clock formats
Interval timing
Obtaining accumulated processor time
Writing and deleting messages (WTO, WTOR, DOM, and WTL)
Routing the message
Altering message text
Writing a multiple-line message
Embedding label lines in a multiple-line message
Communicating in a sysplex environment
Writing to the programmer
Writing to the system log
Deleting messages already written
Retrieving console information (CONVCON and CnzConv macros)
Using console names instead of console IDs
Determining the name or ID of a console
Validating a console name or ID and obtaining the active system name
Translating messages
Allocating data sets for an application
Creating install message files
Creating a version record
Creating message skeletons
Message skeleton format
Message text in a skeleton
Validating message skeletons
Allocating storage for validation run-time message files
Compiling message files
Invoking the message compiler
Checking the message compiler return codes
Updating the system run-time message files
Using MMS translation services in an application
Determining which languages are available (QRYLANG macro)
Retrieving translated messages (TRANMSG macro)
Example of displaying messages
Using message parameter blocks for new messages (BLDMPB and UPDTMPB macros)
Support for additional languages
Example of an application that uses MMS translation services
Data compression and expansion services
Services provided by CSRCESRV
Using these services
Services provided by CSRCMPSC
Compression and expansion dictionaries
Building the CSRYCMPS area
Determining if the CSRCMPSC macro can be issued on a system
Compression processing
Expansion processing
Dictionary entries
Compression dictionary entries
Character entry generic form (DSECT CMPSCDICT_CE)
Character entry CCT=0 (DSECT CMPSCDICT_CE)
Character entry CCT=1 (DSECT CMPSCDICT_CE)
Character entry CCT>1 (DSECT CMPSCDICT_CE)
Alphabet entries (DSECT CMPSCDICT_CE)
Format 1 sibling descriptor (DSECT CMPSCDICT_SD)
Expansion dictionary entries
Unpreceded entry (DSECT CMPSCDICT_UE)
Preceded entry (DSECT CMPSCDICT_PE)
Sibling descriptor extension entry (DSECT CMPSCDICT_SDE)
Dictionary restrictions
Other considerations
Compression dictionary examples
Example 1
Example 2 for more than 5 children
Example 3 for children with the same value
Expansion dictionary example
Accessing unit control blocks (UCBs)
Detecting I/O configuration changes
Scanning UCBs
Obtaining UCB information for a specified device
Obtaining eligible device table information
Using the EDTINFO macro
Setting up and using an internal reader
Allocating the internal reader data set
Opening the internal reader data set
Sending job output to the internal reader
Obtaining a job identifier
Closing the internal reader data set
Using the symbol substitution service
What are symbols?
Types of symbols
Examples of user symbols
Calling the ASASYMBM service
Setting up the ASASYMBP mapping macro
Providing a symbol table to ASASYMBM
Setting up the symbol table
Rules for entering symbols in the symbol table
Using symbols in programs
Example 1
Operation
Example 2
Operation
Example 3
Operation
Example 4
Operation
Using system logger services
What is system logger?
The log stream
Coupling facility log stream
DASD-only log stream
The system logger configuration
The system logger component
Overview of system logger services
Summary of system logger services
Define authorization to system logger resources
Authorization for system logger application programs
64 bit virtual addressing support for system logger services
Synchronous and asynchronous processing
How system logger handles gaps in the log stream
Dumping on data loss (804–type) conditions
Define a log stream to allow additional dumping
Define a log stream to allow additional dumping using LIKE
Update a log stream to allow additional dumping
Connect to a log stream and request additional dumping
Browsing a log stream and request additional dumping
Deleting log data from a log stream and request additional dumping
Using the system logger answer area (ANSAREA parameter)
Using ENF event code 48 in system logger applications
IXGINVNT: Managing the LOGR policy
Defining a model log stream in the LOGR couple data set
Defining a log stream as DASD-only
Upgrading an existing log stream configuration
Upgrading a log stream from DASD-only to coupling facility
Updating an existing structure-based log stream to another structure
Sample procedures to update an existing structure-based log stream to another structure
Renaming a log stream dynamically
Updating a log stream's attributes
IXGCONN: Connecting to and disconnecting from a log stream
Examples of ways to connect to the log stream
Additional considerations for connecting to a DASD-only log stream
How system logger allocates structure space for a new log stream at connection time
Connect process and staging data sets
Requesting authorization to the log stream for an application
Requesting a write or import connection - IMPORTCONNECT parameter
Specifying user data for a log stream
System logger processing at disconnection and expired stream token
Disconnection for an application
Last disconnection for log stream on a system
Last disconnection for a system in the sysplex
Expired log stream token
IXGWRITE: Writing to a log stream
The log block buffer
Ensuring chronological sequence of log blocks
Write triggers
When is data committed to the log stream?
When the log stream coupling facility storage limit is reached
When the staging data set storage limit is reached
When the staging data set is formatting
Limiting asynchronous IXGWRITE requests
IXGBRWSE: Browsing/reading a log stream
IXGBRWSE terminology
IXGBRWSE requests
Browsing both active and inactive data
Browsing for a log block by time stamp
Browsing multiple log blocks
Return and reason code considerations
Using IXGBRWSE and IXGWRITE
Using IXGBRWSE and IXGDELET requests together
IXGDELET: Deleting log blocks from a log stream
Using the BLOCKS parameter
IXGIMPRT: Import log blocks
Making sure log blocks are imported in sequence - Understanding log block identifiers
How do I know what the length of the control information is?
Example: How log block identifiers are generated
Making sure log data is safe to import
IXGQUERY: Get information about a log stream or system logger
The safe import point: Using IXGQUERY and IXGIMPRT together
Coupling facility log streams and the safe import point
DASD-only log streams and the safe import point
The coupling facility list structure version number
Using the coupling facility version number
IXGOFFLD: Initiate offload to DASD log data sets
Managing a target log stream: Using IXGIMPRT, IXGOFFLD, and IXGQUERY together
IXGUPDAT: Modify log stream control information
Rebuilds and IXGUPDAT processing
Setting up the system logger configuration
Reading data from log streams in data set format
Is my application eligible for the LOGR subsystem?
Preparing to use the LOGR subsystem
Using the LOGR subsystem
JCL for the LOGR Subsystem
LOGR SUBSYS dynamic allocation considerations
When things go wrong - Recovery scenarios for system logger
When a system logger application fails
When an MVS system or sysplex fails
Recovery performed for DASD-only log streams
When the system logger address space fails
When the coupling facility structure fails
Damage to or failure of the coupling facility structure
Loss of connectivity to the coupling facility structure
A coupling facility becomes volatile
When the coupling facility space for a log stream becomes full
When a staging data set becomes full
When a log stream is damaged
When DASD log data set space fills
When unrecoverable DASD I/O errors occur
When unrecoverable DASD I/O errors occur during offload
When staging data set unrecoverable DASD I/O errors occur
Unicode instruction services: CSRUNIC
Transactional execution
Nonconstrained transactions
Constrained transactions
Planning to use transactional execution
Transactional execution debugging
Transactional execution diagnostics
Using the unit verification service
Functions of unit verification
Check groups - Function code 0
Check units - Function code 1
Return unit name - Function code 2
Return unit control block (UCB) addresses - Function code 3
Return group ID - Function code 4
Indicate unit name is a look-up value - Function code 5
Return look-up value - Function code 6
Convert device type to look-up value - Function code 7
Return attributes - Function code 8
Specify subpool for returned storage - Function code 10
Return unit names for a device class - Function code 11
Callers of IEFEB4UV
Input to and output from unit verification service routines
Input parameter list
Input and output data structures
Register 15 if request fails
Requesting function code 0 (check groups)
Input
Output
Requesting function code 1 (check units)
Input
Output
Requesting function code 2 (return unit name)
Input
Output
Requesting function code 3 (return UCB addresses)
Input
Output
Requesting function code 4 (return group ID)
Input
Output
Requesting function code 5 (indicate unit name is a look-up value)
Input
Output
Requesting function code 6 (return look-up value)
Input
Output
Requesting function code 7 (convert device type to look-up value)
Input
Output
Requesting function code 8 (return attributes)
Input
Output
Requesting function code 10 (specify subpool for returned storage)
Input
Output
Requesting function code 11 (return unit names for a device class)
Input
Output
Requesting multiple functions - Examples
Example 1 - Function codes 0 and 1
Input
Output
Example 2 - Function codes 3 and 10
Input
Output
Example 3 - Function codes 1 and 5
Input
Output