Chapter 27. Using system logger services. IBM z/OS Version 2 Release 3

Chapter 27. Using system logger services

This chapter covers the information you need to write a system logger application, including the following topics: v

“What is system logger?”

v

“The system logger configuration” on page 466.

v

“Overview of system logger services” on page 469.

v

“IXGINVNT: Managing the LOGR policy” on page 480.

v

“IXGCONN: Connecting to and disconnecting from a log stream” on page 486.

v

“IXGWRITE: Writing to a log stream” on page 491.

v

“IXGBRWSE: Browsing/reading a log stream” on page 495.

v

“IXGDELET: Deleting log blocks from a log stream” on page 500.

v

“IXGIMPRT: Import log blocks” on page 501.

v

“IXGQUERY: Get information about a log stream or system logger” on page 503.

v

“IXGOFFLD: Initiate offload to DASD log data sets” on page 507.

v

“IXGUPDAT: Modify log stream control information” on page 508.

v

“Setting up the system logger configuration” on page 509.

v

“Reading data from log streams in data set format” on page 509.

v

“When things go wrong — Recovery scenarios for system logger” on page 515.

What is system logger?

System logger is a set of services that allows an application to write, browse, and delete log data. You can use system logger services to merge data from multiple instances of an application, including merging data from different systems across a sysplex.

For example, suppose you are concurrently running multiple instances of an application in a sysplex, and each application instance can update a common database. It is important for your installation to maintain a common log of all updates to the database from across the sysplex, so that if the database should be damaged, it can be restored from the backup copy. You can merge the log data from applications across the sysplex into a log stream, which is simply a collection

of data in log blocks residing in the coupling facility and on DASD (see Figure 110 on page 464).

© Copyright IBM Corp. 1988, 2017

463

Application

Instance 1

Log stream log block

4 log block

3 log block

2 log block

1

Figure 110. System Logger Log Stream

Application

Instance

2

The log stream

A log stream is an application specific collection of data that is used as a log. The data is written to and read from the log stream by one or more instances of the application associated with the log stream. A log stream can be used for such purposes as a transaction log, a log for re-creating databases, a recovery log, or other logs needed by applications.

A system logger application can write log data into a log stream, which is simply a collection of data. Data in a log stream spans two kinds of storage: v Interim storage , where data can be accessed quickly without incurring the overhead of DASD I/O.

v DASD log data set storage , where data is hardened for longer term access.

When the interim storage medium for a log stream reaches a user-defined threshold, the log data is offloaded to DASD log data sets.

There are two types of log streams; coupling facility log streams and DASD-only log streams. The main difference between the two types of log streams is the storage medium system logger uses to hold interim log data: v In a coupling facility log stream, interim storage for log data is in coupling

facility list structures. See “Coupling facility log stream” on page 465.

v In a DASD-only log stream interim storage for log data is contained in local storage buffers on the system. Local storage buffers are data space areas

associated with the system logger address space, IXGLOGR. See “DASD-only log stream” on page 466.

Your installation can use just coupling facility log streams, just DASD-only log streams, or a combination of both types of log streams. The requirements and preparation steps for the two types of log streams are somewhat different; see

“Setting up the system logger configuration” on page 509.

Some key considerations for choosing either coupling facility log steams or

DASD-only log streams are: v The location and concurrent activity of writers and readers to a log stream's log data

464

z/OS MVS Assembler Services Guide

v The volume of log data written to a log stream.

Coupling Facility log streams are required when:

1.

You require more than one concurrent log writer or log reader to the log stream from more than one system in the sysplex.

2.

You are recording high volumes of log data being to the log stream.

You can use DASD-only log streams when:

1.

You require no more than one concurrent log writer or log reader to the log stream from more than one system in the sysplex.

2.

You are recording low volumes of log data to the log stream.

Note:

Since DASD-only log streams always use staging data sets, high volume writers of log data may be throttled back by the I/O required to record each record sequentially to the log stream's staging data sets.

With z/OS Release 3 and higher, you can also upgrade existing coupling facility

log streams to use a different coupling facility structure. See “Updating an existing structure-based log stream to another structure” on page 483.

Coupling facility log stream

Figure 111 shows how a coupling facility log stream spans two levels of storage;

the coupling facility for interim storage and DASD log data sets for more permanent storage. When the coupling facility space for the log stream fills, the data is offloaded to DASD log data sets. A coupling facility log stream can contain data from multiple systems, allowing a system logger application to merge data from systems across the sysplex.

Log stream

Sys 1

Youngest data Oldest data

Application

Structure

Coupling Facility

DASD log data sets

Figure 111. Log Stream Data on the Coupling Facility and DASD

When a system logger application writes a log block to a coupling facility log stream, system logger writes it first to a coupling facility list structure. System logger requires that a coupling facility list structure be associated with each log stream. When the coupling facility structure space allocated for the log stream reaches the installation-defined threshold, system logger moves (offloads) the log

Chapter 27. Using system logger services

465

blocks from the coupling facility structure to VSAM linear DASD data sets, so that the coupling facility space for the log stream can be used to hold new log blocks.

From a user's point of view, the actual location of the log data in the log stream is transparent.

DASD-only log stream

Figure 112 shows a DASD-only log stream spanning two levels of storage; local

storage buffers for interim storage, which is then offloaded to DASD log data sets for more permanent storage.

A DASD-only log stream has a single-system scope; only one system at a time can connect to a DASD-only log stream. Multiple applications from the same system can, however, simultaneously connect to a DASD-only log stream.

Log stream

Sys 1

Youngest data Oldest data

Application

SYS1 local storage buffers

DASD log data sets

Figure 112. Log Stream Data in Local Storage Buffers and DASD Log Data Sets

When a system logger application writes a log block to a DASD-only log stream, system logger writes it first to the local storage buffers for the system and duplexes it to a DASD staging data set associated with the log stream. When the staging data set space allocated for the log stream reaches the installation-defined threshold, system logger offloads the log blocks from local storage buffers to

VSAM linear DASD data sets. From a user's point of view, the actual location of the log data in the log stream is transparent.

Both a DASD-only log stream and a coupling facility log stream can have data in multiple DASD log data sets; as a log stream fills log data sets on DASD, system logger automatically allocates new ones for the log stream.

The system logger configuration

The system logger configuration you use depends on whether or not you use a coupling facility.

Coupling facility log stream configuration

: Figure 113 on page 467 shows all the

parts involved when a system logger application writes to a coupling facility log

466

z/OS MVS Assembler Services Guide

stream. In this example, a system logger application runs on two systems in a sysplex. Both instances of the application write data to the same log stream,

TRANSLOG. Each system contains a system logger address space. A system logger application uses system logger services to access the system logger capabilities.

When a system logger application writes data to a coupling facility log stream, system logger writes the data to a coupling facility list structure associated with the log stream. Then, when the coupling facility structure fills with data, system logger offloads the data to DASD log data sets.

You can optionally elect to have coupling facility data duplexed to DASD staging data sets for a coupling facility log stream.

Sysplex

Sys 1

Application

1 s t

S y e m g g l o e r

Local

Storage buffers

Coupling Facility Structure

TRANSLOG Log Stream

SYS1/TRANSLOG

Staging

Data Set

LOGR couple data set

Local

Storage buffers

Sys 2

s t

S y e m g g l o e r

Application

2

DASD log data sets

SYS2/TRANSLOG staging data set

Figure 113. A Complete Coupling Facility Log Stream Configuration

DASD-only log stream configuration

: Figure 114 on page 468 shows all the parts

involved when a system logger application writes to a DASD-only log stream.

System logger writes the data to the local storage buffers on the system, duplexing it at the same time to the DASD staging data sets associated with the log stream.

Then, when the staging data set fills with data, system logger offloads the data to

DASD log data sets. Note that where duplexing to DASD staging data sets is an option for a coupling facility log stream, it is a required automatic part of a

DASD-only log stream. A system logger application uses system logger services to access the system logger capabilities.

Chapter 27. Using system logger services

467

Sysplex

Sys 1

Application

S t e y s m g g l o e r

Local

Storage buffers

DASD staging data sets

SYS1 staging data set

LOGR couple data set

Figure 114. A DASD-Only Configuration

For general configuration information, see the following references: v The LOGR couple data set (LOGR policy) in z/OS MVS Setting Up a Sysplex v Log data on the coupling facility in z/OS MVS Setting Up a Sysplex v Log data on DASD log data sets in z/OS MVS Setting Up a Sysplex v

Duplexing log data in z/OS MVS Setting Up a Sysplex

The system logger component

The system logger component resides in its own address space on each system in a sysplex. Some of the component processing will differ, depending on whether a given log stream is a coupling facility log stream or a DASD-only log stream. The system logger component does the following: v Provides a set of system services that allows a system logger application to use the system logger component. See z/OS MVS Programming: Assembler Services

Reference IAR-XCT.

v Maintains information in the LOGR policy about the current use of log streams and if used, coupling facility list structures.

v For coupling facility log streams, system logger interacts with cross-system extended services (XES) to connect to and use the coupling facility for system logger applications.

v Obtains local storage buffer space. For a coupling facility log stream, local storage buffers can be used for duplexing log data. For a DASD-only log stream, local storage buffers are used as interim storage for log data before it is offloaded to DASD log data sets.

v Offloads data to DASD log data sets as follows:

For coupling facility log streams

, system logger offloads log data from the coupling facility to DASD log data sets as the coupling facility structure space associated with the log stream reaches the installation-defined thresholds.

For DASD-only log streams

, system logger offloads log data from the local storage buffers to DASD log data sets as the DASD staging data set space reaches the installation-defined thresholds.

468

z/OS MVS Assembler Services Guide

v Automatically allocates new DASD log data sets for log streams.

v

Maintains a backup copy of (duplexes) log data that is in interim storage for recovery. Log data in interim storage is vulnerable to loss due to system or sysplex failure because it has not yet been hardened to DASD log data sets.

System logger duplexes interim storage log data for both coupling facility and

DASD-only log streams.

v Produces SMF record type 88 for system logger accounting on a single system.

Record type 88 focuses on the usage of interim storage (coupling facility or local storage buffers) and log stream data for a system in the sysplex. Using the record can help an installation avoid the STRUCTURE FULL or STAGING DATA

SET FULL exceptions, and perform other tuning and/or capacity planning analysis.

See z/OS MVS System Management Facilities (SMF) for more information on record type 88 and system logger accounting. Sample program IXGRPT1 in

SYS1.SAMPLIB shows an example of producing a report from SMF record type

88.

v Ensures that:

– When the last connection from a system disconnects from the log stream, all log data written by that system to the log stream is offloaded to DASD log data sets.

System logger also deletes any staging data sets in use for a system at this time.

– When the last connection to a coupling facility log stream in the sysplex disconnects, all coupling facility log data is offloaded to DASD log data sets and the coupling facility space is returned to XES for reallocation.

v Provides recovery support in the event of application, system, sysplex, or coupling facility structure failure for coupling facility log streams. (See

“Recovery performed for DASD-only log streams” on page 516 for information

about recovery for DASD-only log streams.)

Overview of system logger services

This information provides an overview of general information about system logger services, including: v

“Summary of system logger services.”

v

“Define authorization to system logger resources” on page 470.

v

“Synchronous and asynchronous processing” on page 474.

v

“How system logger handles gaps in the log stream” on page 475.

v

“Using the system logger answer area (ANSAREA parameter)” on page 478.

v

“Using ENF event code 48 in system logger applications” on page 480.

Summary of system logger services

System logger provides the following set of services:

IXGINVNT

Define and maintain log stream and coupling facility structure information

in the LOGR policy dynamically. See page “IXGINVNT: Managing the

LOGR policy” on page 480.

You can also use the IXCMIAPU utility to specify log stream and structure definitions in the LOGR policy. IXCMIAPU also enables you to request a report of current log stream definitions.

Chapter 27. Using system logger services

469

IXGCONN

Connect and disconnect an application to and from a log stream. See page

“IXGCONN: Connecting to and disconnecting from a log stream” on page

486.

IXGWRITE

Write user-defined log data to a log stream. See page “IXGWRITE: Writing to a log stream” on page 491.

IXGBRWSE

Browse (read) data from a log stream. See page “IXGBRWSE:

Browsing/reading a log stream” on page 495.

IXGDELET

Delete data from a log stream. See page “IXGDELET: Deleting log blocks from a log stream” on page 500.

IXGIMPRT

Import (write) log blocks to a log stream, with a log block identifier and

time stamp. See page “IXGIMPRT: Import log blocks” on page 501.

IXGQUERY

Retrieve information from a log stream. See page “IXGQUERY: Get information about a log stream or system logger” on page 503.

IXGOFFLD

Initiate an offload of log data from the coupling facility structure for coupling facility log streams and from local storage buffers for DASD-only

log streams to DASD log data sets. See page “IXGOFFLD: Initiate offload to DASD log data sets” on page 507.

IXGUPDAT

Modify the UTC time stamp maintained in the control information for a

log stream. See page “IXGUPDAT: Modify log stream control information” on page 508.

The following services contain parameters for both authorized and unauthorized programs: v IXGCONN v IXGBRWSE v IXGWRITE v

IXGDELET

All other system logger services and their parameters can be used by any program.

All the unauthorized guidance for System Logger is contained in this chapter. See the z/OS MVS Programming: Authorized Assembler Services Guide for guidance on using the authorized services.

Define authorization to system logger resources

Installations need to define authorization to system logger resources for both the system logger address space and logging functions and applications using the system logger services: v For information on authorization for the system logger address space, see the chapter on planning for system logger functions in z/OS MVS Setting Up a

Sysplex.

470

z/OS MVS Assembler Services Guide

v If you are using the IXCMIAPU utility to update the LOGR couple data set, you must define authorization to system logger resources for IXCMIAPU users. See the chapter on planning for system logger functions in z/OS MVS Setting Up a

Sysplex.

v To define authorization for system logger application programs, see

“Authorization for system logger application programs.”

Authorization for system logger application programs

IBM recommends that installations use System Authorization Facility (SAF) to control access to system logger resources, such as log streams and coupling facility structures associated with log streams.

Define access for applications to the classes and resources for each service, as

shown in Table 38. Note that only applications writing to coupling facility log

streams need access to coupling facility structures.

Table 38. Required SAF authorization for system logger resources

System logger service

IXGINVNT REQUEST=DEFINE TYPE=LOGSTREAM

Access type SAF class and resource

ALTER RESOURCE(log_stream_name) CLASS(LOGSTRM)

IXGINVNT REQUEST=UPDATE TYPE=LOGSTREAM

IXGINVNT REQUEST=DELETE TYPE=LOGSTREAM

IXGINVNT REQUEST=DEFINE TYPE=LOGSTREAM

IXGINVNT REQUEST=UPDATE TYPE=LOGSTREAM

STRUCTNAME=structure_name

IXGINVNT REQUEST=DEFINE TYPE=LOGSTREAM

LIKE=like_log_stream_name DASDONLY=NO and when

like_log_stream_name has a structure name, that is,

like_structure_name

IXGINVNT REQUEST=DEFINE TYPE=LOGSTREAM

ALTER

UPDATE

ALTER

UPDATE

ALTER

RESOURCE(log_stream_name) CLASS(LOGSTRM)

RESOURCE(IXLSTR.structure_name) CLASS(FACILITY)

RESOURCE(log_stream_name) CLASS(LOGSTRM)

RESOURCE(IXLSTR.like_structure_name)

CLASS(FACILITY)

RESOURCE(log_stream_name) CLASS(LOGSTRM)

RESOURCE(IXGZAWARE_CLIENT) CLASS(FACILITY) IXGINVNT REQUEST=UPDATE TYPE=LOGSTREAM

ZAI=YES

IXGINVNT REQUEST=DEFINE TYPE=STRUCTURE

UPDATE

ALTER

IXGINVNT REQUEST=DELETE TYPE=STRUCTURE

IXGINVNT REQUEST=CHECKDEF TYPE=LOGSTREAM READ

IXGINVNT REQUEST=CHECKDEF TYPE=STRUCTURE

IXGCONN REQUEST=CONNECT AUTH=WRITE

IXGCONN REQUEST=CONNECT AUTH=READ

UPDATE

READ

RESOURCE(MVSADMIN.LOGR) CLASS(FACILITY)

RESOURCE(MVSADMIN.LOGR) CLASS(FACILITY)

RESOURCE(log_stream_name) CLASS(LOGSTRM)

RESOURCE(log_stream_name) CLASS(LOGSTRM)

64 bit virtual addressing support for system logger services

System logger provides 64-bit addressing mode support for IXGBRWSE,

IXGWRITE, and IXGIMPRT with the BUFFER64 keyword. The BUFFER64 keyword allows callers to pass a data buffer whose address is a 64-bit address. The 64-bit address can be anywhere in 64-bit storage, above or below the bar. BUFFER64 is mutually exclusive with the BUFFER keyword. The size of the input field (4 bytes) specified on the BUFFLEN parameter remains unchanged.

If you code the IXGBRWSE, IXGWRITE, or IXGIMPRT services with the BUFFER64 keyword, you then must recompile the modules invoking these services.

Chapter 27. Using system logger services

471

You can call any of the system logger services in AMODE 64, but all addresses passed to the services will be in 31-bit addresses, except for those coded in the

BUFFER64 keyword on the IXGBRWSE, IXGWRITE, and IXGIMPRT services.

The following example shows a program in which system logger services are invoked using the BUFFER64 keyword:

TITLE ’IXGASM64 - Logger Services Samples’

IXGASM64 CSECT ,

IXGASM64 AMODE 31

IXGASM64 RMODE ANY

*

* IXGASM64 - Logger Services Samples for Amode 64 and BUFFER64.

*

* This program contains samples of how to invoke Logger Services in

* 64 bit mode and samples of the use of the BUFFER64 keyword.

*

* This program runs on z/OS Release 1.6 or higher.

It has been tested

* on that release and all services returned a successful return code.

*

* Note that for your installation, you may have to do considerable

* setup for this program to run correctly.

*

* It does not need to run Authorized, although various security

* permissions may need to be granted for it to run successfully.

*

* This program is REENTRANT.

*

* It is entered in AMODE 31 and switches to AMODE 64.

R15 is assumed

* to point to the entry point.

*

* It will alter Registers 14, 15, 0, and 1.

*

* General Initialization

*

J PROLOG

DC AL1(20)

DC C’IXGASM64 SAMPLE PGM ’

PROLOG BSM 14,0

BAKR 14,0

LAE 12,0

LR 12,15

USING IXGASM64,12

L 00,SIZDATD+4

LA 15,0

CPYA 01,12

STORAGE OBTAIN,LENGTH=(0),SP=(15),LINKAGE=SYSTEM

LAE 13,0(,01)

USING DATD,13

LLGTR 12,12 Static area register

LLGTR 13,13 Data area register

* Specify AMODE 64 for Macros, establish 64-bit Mode, obtain storage

* above the Bar, and then place data in the storage.

SYSSTATE ASCENV=ANY,AMODE64=YES,ARCHLVL=,OSREL=

SAM64

IARV64 REQUEST=GETSTOR,SEGMENTS=1,ORIGIN=ORIGIN,

LG

RETCODE=RETCODE,RSNCODE=RSNCODE

2,ORIGIN

MVC BUFFER64(50,2),TESTDATA

* Prepare for issuing IXGxxxxx Services

LA 08,40 x

472

z/OS MVS Assembler Services Guide

ST 08,ANSLEN

MVC STRUCTNAME(16),STRUCT

MVC STREAMNAME(26),STREAM

* Issue IXGxxxxx Services

IXGINVNT REQUEST=DELETE,TYPE=LOGSTREAM,

ANSLEN=ANSLEN,ANSAREA=ANSAA,STREAMNAME=STREAMNAME,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGINVNT REQUEST=DEFINE,TYPE=LOGSTREAM,DASDONLY=YES,

ANSLEN=ANSLEN,ANSAREA=ANSAA,STREAMNAME=STREAMNAME,

STG_SIZE=16,LS_SIZE=16,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGCONN REQUEST=CONNECT,STREAMNAME=STREAMNAME,AUTH=WRITE,

STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGWRITE BUFFER64=(2),BLOCKLEN=50,

STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGOFFLD STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN, X

X

X

X

X

X

X

X

X

X

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGCONN REQUEST=DISCONNECT,

STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGCONN REQUEST=CONNECT,AUTH=WRITE,IMPORTCONNECT=YES,

STREAMNAME=STREAMNAME, x

X x x

X STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

STCK STCK1

IXGUPDAT GMT_TIMESTAMP=STCK1,

STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGQUERY CHECKCONNSTATUS=YES,

STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN, x

X x

X

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGBRWSE REQUEST=START,OLDEST,BROWSETOKEN=BROWSETOKEN,

STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

STCK STCK1

IXGIMPRT BUFFER64=(2),BLOCKLEN=50,BLOCKID=BLOCKID,

GMT_TIMESTAMP=STCK1,LOCALTIME=STCK1,

STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGBRWSE REQUEST=READCURSOR,BROWSETOKEN=BROWSETOKEN,

BUFFER64=(2),BUFFLEN=50,DIRECTION=OLDTOYOUNG,

BLKSIZE=RETURNSIZE,RETBLOCKID=RETBLOCKID,

STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGBRWSE REQUEST=END,BROWSETOKEN=BROWSETOKEN,

STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN, x

X x

X

X x x x x x

X

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGDELET BLOCKS=ALL,

STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGCONN REQUEST=DISCONNECT,

STREAMTOKEN=STREAMTOKEN,ANSAREA=ANSAA,ANSLEN=ANSLEN,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

IXGINVNT REQUEST=DELETE,STREAMNAME=STREAMNAME,TYPE=LOGSTREAM, x

ANSAREA=ANSAA,ANSLEN=ANSLEN,

RETCODE=RETCODE,RSNCODE=RSNCODE,MF=(E,PLIST,COMPLETE)

X

* Cleanup and return to caller

L 00,SIZDATD+4 x

X x

X

Chapter 27. Using system logger services

473

LA

LR

15,0

01,13

CPYA 01,13

STORAGE RELEASE,LENGTH=(0),ADDR=(1),SP=(15),LINKAGE=SYSTEM

SLR 15,15

PR

* Static data

STATDATA DS

SIZDATD DS

DC

0F

0A

AL1(0)

DC

DC

TESTDATA DC

AL3(DYNSIZE)

A(DYNSIZE)

STREAM DC

STRUCT DC

BLOCKID DC

DC

BUFFER64 EQU 0

CL50’TEST DATA FOR TESTCASE IXGASM64

CL26’LOGGER.STREAMA

CL16’LIST01 ’

’

A(0)

A(256)

Blockid is 8 bytes in length

* Dynamic Data

DATD DSECT

SA00001 DS

RSNCODE

RETCODE

ANSLEN

DS

DS

DS

36F

F

F

F

RETURNSIZE DS F

DS 0D

STCK1 DS

ORIGIN DS

CL8

CL8

RETBLOCKID DS CL8

Save area must be first in DATD

STRUCTNAME DS CL16

STREAMNAME DS CL26

STREAMTOKEN DS CL16

IXGANSAA DSECT=NO

BROWSETOKEN DS CL4

PLIST DS

BUFFER DS

CL256

CL50

ORG *+1-(*-DATD)/(*-DATD)

ENDDATD DS 0X

DYNSIZE EQU ((ENDDATD-DATD+7)/8)*8

IXGASM64 CSECT ,

END

’

Synchronous and asynchronous processing

Depending on the operating environment, an event control block (ECB) can be resident in one of two places: the home address space (in private storage) or in common storage.

Use the MODE parameter on the IXGWRITE, IXGBRWSE, and IXGDELET services to choose one of the following: v MODE=SYNC v

MODE=SYNCECB v MODE=SYNCEXIT v MODE=ASYNCNORESPONSE

The following conditions shows where the ECB might appear in an environment that includes a caller address space, a server address space, and the system logger address space. In these conditions, the server provides services to the caller.

v Choosing MODE=SYNC

474

z/OS MVS Assembler Services Guide

Choose MODE=SYNC to specify that the request be processed synchronously.

When control returns to the caller, all processing on behalf of the request is complete.

v Choosing MODE=SYNCECB

Choose MODE=SYNCECB to specify that the request be processed synchronously, if possible. If the system logger request cannot be completed synchronously, processing on behalf of the request might still be in progress when control returns to the caller (see MODE=ASYNCNORESPONSE). When the asynchronous processing for the request completes, the ECB specified on the system logger request is posted. Once the ECB is posted, the caller can examine the answer area to verify whether the request completed successfully.

v Choosing MODE=ASYNCNORESPONSE

Choose MODE=ASYNCNORESPONSE on the IXGWRITE and IXGDELET requests to specify that the request be processed asynchronously. The caller will not be informed when the request completes. The answer area returned in the

ANSAREA parameter and mapped by IXGANSAA is not valid when you specify MODE=ASYNCNORESPONSE.

When a system logger request cannot be completed synchronously, system logger indicates this by returning to the invoking program with a specific return code

X’4’ and reason code X’401’ (IxgRetCodeWarning and

IxgRsnCodeProcessedAsynch, re: macro IXGCON).

Before system logger returns control to the caller it schedules an SRB to complete processing of the request. While the SRB runs independent of the requesting task, the SRB might encounter an error from which it cannot recover. The SRB ensures that the error condition is percolated to the task that issued the system logger request.

Note:

Depending on the exploiter's structure, this task might not be the same task that originally issued the IXGCONN request to connect to a log stream.

Prior to percolating the error to the requesting task, system logger issues the

SETRP macro, specifying SERIAL=YES. System logger also places additional diagnostic information in the SDWA, as follows:

SDWACMPC

The completion code, set to X’1C5’.

SDWACRC

The reason code, set to X’85F’.

SDWACOMU

The ECB address specified on the ECB keyword when system logger was invoked.

If the caller receives a return code indicating that system logger will process the request asynchronously, the application cannot free certain storage areas.

Reference information:

See z/OS MVS Programming: Assembler Services Reference

IAR-XCT for the specific service's return code.

How system logger handles gaps in the log stream

System logger might find data unexpectedly missing from or inaccessible in a log stream. These areas of missing information are called gaps and result from the following:

Chapter 27. Using system logger services

475

v System, sysplex, or coupling facility failure where the data could not be recovered.

v

A DASD log stream data set being deleted.

v DASD I/O errors occurring during processing of an IXGBRWSE request to read log data.

If system logger encounters a gap during the processing of an IXGBRWSE or

IXGDELET service, it returns a return and reason code to the caller of the system logger service to report the condition and indicate whether the service completed successfully. The other system logger services, IXGINVNT, IXGCONN, and

IXGWRITE, are not affected by gaps in the log stream data.

See Table 39 and Table 40 for a summaries of how IXGBRWSE and IXGDELET

services handle gaps in the log stream.

Table 39. How IXGBRWSE Requests Handle Gaps in a Log Stream

IXGBRWSE Request

START SEARCH=search

READBLOCK SEARCH=search

START STARTBLOCKID=startblockid

READBLOCK BLOCKID=blockid

READCURSOR

START OLDEST

RESET POSITION=OLDEST

START YOUNGEST

Request Results

Request completes with a non-zero return code and reason code.

System logger positions the cursor at or reads the next youngest log block or a block with an identical time stamp, if there is one.

Request completes with a non-zero return code and reason code.

System logger positions the cursor at or reads the next youngest log block, if one exists.

Request fails with a non-zero return and reason code. No block is returned.

Request completes with a non-zero return code and reason code.

System logger reads the next valid block after the gap in the specified direction, if there is one.

When the oldest log block is within a gap of log data, the request completes with a non-zero return code and reason code.

System logger positions or resets the cursor to the oldest valid block in the log stream.

The service completes without errors.

RESET POSITION=YOUNGEST

Table 40. How IXGDELET Requests Handle Gaps in a Log Stream

IXGDELET Request

BLOCKS=ALL

BLOCKS=RANGE

Request Results

This request is unaffected by gaps in the log stream. The service completes successfully.

If the block specified is at the start of the range specified, the service fails with a non-zero return and reason code. No data is deleted.

System logger returns the block identifier of the first accessible block toward the young end of the log stream.

If the block specified is not within a gap, the service completes successfully.

Dumping on data loss (804–type) conditions

The new DIAG option on the IXGINVNT service and IXCMIAPU TYPE(LOGR) utility along with the new DIAG options on the IXGCONN, IXGDELET and

IXGBRWSE services allow additional diagnostic data to be obtained when a log stream loss of data condition is encountered.

476

z/OS MVS Assembler Services Guide

The following shows the default settings for all the services and the relationship between the service specifications in terms of whether or not Logger will request a dump for certain loss of data type conditions.

Default settings:

DEFINE LOG STREAM

IXGCONN (CONNECT)

IXGBRWSE (START)

IXGDELET

DIAG(NO)

DIAG(NO_DIAG)

DIAG(NO_DIAG)

DIAG(NO_DIAG)

Assuming a data loss (804) type condition was encountered on an IXGDELET request or on any IXGBRWSE request for a browse session, the following shows whether or not a dump would be taken by Logger for this condition, where:

No

No dump is taken for the condition.

Yes

Dump is taken for the condition.

DEFINE LOG STREAM NO

-----------------

YES

-----------------

IXGCONN CONNECT NO_DIAG NO YES NO_DIAG NO YES

----------------------------------------------------------------

IXGBRWSE START NO_DIAG

NO

YES

IXGDELET NO_DIAG

NO

YES no no no no no no no no no no no no no no no no no no no no yes no no yes no yes no no no yes no yes no no no yes

Note:

The specification on DIAG(YES) in the log stream definition also results in additional non-abend diagnostics being collected for the log stream. For more information, see 'Enabling additional log stream diagnostics' in z/OS MVS

Diagnosis: Reference.

Define a log stream to allow additional dumping

v IXGINVNT

Specify IXGINVNT REQUEST=DEFINE,TYPE=LOGSTREAM,...,DIAG=YES v IXCMIAPU Utility Program

Specify DEFINE LOGSTREAM ... DIAG(YES)

Define a log stream to allow additional dumping using LIKE

v IXGINVNT

Specify IXGINVNT

REQUEST=DEFINE,TYPE=LOGSTREAM,NAME=like.log.stream,...,DIAG=YES

Then IXGINVNT REQUEST=DEFINE,TYPE=LOGSTREAM,LIKE=like.log.stream

v IXCMIAPU Utility Program

Specify DEFINE LOGSTREAM NAME (like.log.stream) ... DIAG(YES)

Then DEFINE LOGSTREAM LIKE(like.log.stream)

Update a log stream to allow additional dumping

v IXGINVNT

Specify IXGINVNT REQUEST=UPDATE,TYPE=LOGSTREAM,...,DIAG=YES v IXCMIAPU Utility Program

Chapter 27. Using system logger services

477

Specify UPDATE LOGSTREAM ... DIAG(YES)

The update will take affect as each system obtains its first connection to the log stream. For example, assume there are two systems in an installation's sysplex,

SYSA and SYSB, and SYSA had a connection to the log stream prior to the update request and SYSB did not have any connections to the log stream. If SYSB establishes a new (first) connection to the log stream, then the DIAG options will be in affect on SYSB. The DIAG settings prior to the update request will remain in affect on SYSA even if there is another connection to the log stream on SYSA.

However, if all the connections to the log stream on SYSA are disconnected and then a new (first) connection is established to the logstream on SYSA, then the new

DIAG options would then be in affect on SYSA.

Connect to a log stream and request additional dumping

v

IXGCONN

Specify IXGCONN REQUEST=CONNECT,...,DIAG=YES

Assuming the log stream that is being connected has been defined as DIAG(YES), then Logger will provide a dump when a loss of data condition is encountered on browse and delete requests, unless the specific browse (start) or delete request specifies otherwise.

Browsing a log stream and request additional dumping

v IXGBRWSE

Specify IXGBRWSE REQUEST=START,...,DIAG=YES when IXGCONN

REQUEST=CONNECT,...,DIAG=NO_DIAG v

IXGCONN

Specify IXGCONN REQUEST=CONNECT,...,DIAG=YES then no specific DIAG options need to be coded on the IXGBRWSE REQUEST=START invocation.

Assuming the log stream that is being browsed has been defined as DIAG(YES), then Logger will provide a dump when a loss of data condition is encountered on any browse for this browse session.

Deleting log data from a log stream and request additional dumping

v IXGDELET

Specify IXGDELET,...,DIAG=YES when IXGCONN

REQUEST=CONNECT,...,DIAG=NO_DIAG v

IXGCONN

Specify IXGCONN REQUEST=CONNECT,...,DIAG=YES then no specific DIAG options need to be coded on the IXGDELET invocation.

Assuming the log stream that is having log data deleted has been defined as

DIAG(YES), then Logger will provide a dump when a loss of data condition is encountered on this delete request.

Using the system logger answer area (ANSAREA parameter)

Every system logger service issued must include an answer area output field specified on the ANSAREA parameter. In this answer area, mapped by the

IXGANSAA macro, system logger returns status and diagnostic data.

Some generic answer area fields include:

478

z/OS MVS Assembler Services Guide

ANSAA_PREFERRED_SIZE

The optimal size for the answer area field specified on the ANSAREA parameter. IXGCONN REQUEST=CONNECT returns this value.

The answer area must be at least 40 bytes long. If you specify a field that is less than that, the service fails with a non-zero return code. To ascertain the optimal answer area size, look at the ANSAA_PREFERRED_SIZE field of the answer area returned by the first system logger service your application issues, either the IXGINVNT or IXGCONN REQUEST=CONNECT service.

ANSAA_ASYNCH_RETCODE

For asynchronously processed requests, system logger returns the return code in this field.

ANSAA_ASYNCH_RSNCODE

For asynchronously processed requests, system logger returns the reason code in this field.

ANSAA_DIAGx

Diagnostic data. The content of these fields depend on any return and reason codes returned for a request.

Specific service indicators include:

ANSAA_BLKFROMINACTIVE

Indicates that the log block returned from an IXGBRWSE request came from the inactive portion of the log stream. For MULTIBLOCK=YES requests, this flag indicates that at least one log block returned in the buffer came from an inactive portion of the log stream. Flag IXGBRMLT_FROMINACTIVE in

IXBRMLT (from the IXGBRMLT macro) indicates which log blocks were in the inactive portion. This field is only valid for IXGBRWSE requests that result in a log block being returned.

ANSAA_DYNMGMTOFENTRYTOELACTIVE

Indicates that system logger is dynamically managing the entry-to-element ratio for the coupling facility structure. The structure was defined in a LOGR couple data set. This field is only valid for IXGCONN requests, and is undefined when ANSA_DASDONLYLOGSTREAM is on.

ANSAA_DASDONLYLOGSTREAM

This flag in ANSAA_FLAGS1 indicates whether a log stream is DASD-only. It is output from an IXGCONN REQUEST=CONNECT service.

ANSAA_BROWSEMULTIBLOCK

This flag in ANSAA_FLAGS1 indicates whether this level of system logger supports IXGBRWSE MULTIBLOCK=YES requests. It is valid only for an

IXGBRWSE REQUEST=START service.

ANSAA_BLKFROMDASD

This flag in ANSAA_FLAGS1 indicates that the log block returned from an

IXGBRWSE request came from a log stream DASD offload data set. For

MULTIBLOCK=YES requests, this flag indicates that at least one log block returned in the buffer came from a log stream DASD offload data set. Flag

IXGBRMLT_FROMDASD in IXBRMLT (from the IXGBRMLT macro) indicates which log blocks were read from DASD. This field is only valid for IXGBRWSE requests that result in a log block being returned.

For a complete description of the IXGANSAA macro, see z/OS MVS Data Areas in the z/OS Internet library (www.ibm.com/systems/z/os/zos/library/bkserv).

Chapter 27. Using system logger services

479

Using ENF event code 48 in system logger applications

System logger issues ENF event code 48 to broadcast status changes in the system logger address space, log streams, and coupling facility structures. Since these status changes can affect the outcome of system logger service requests, IBM

recommends

that you use ENF event code 48 to receive notification of these status changes, using the ENFREQ service to listen for event 48. Note that your program must be authorized to use the ENFREQ service. Applications should issue the

ENFREQ service to listen for event 48 before connecting to a log stream.

Applications that do not want to use ENF event code 48 or that are unauthorized and cannot use ENFREQ will still receive logger service return and reason codes indicating failure or resource shortages. These applications can then simply set a timer and then retry the requests to see if the problem has resolved itself.

References:

v See the z/OS MVS Programming: Authorized Assembler Services Guide for guidance about using the ENFREQ macro.

v See the z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG for reference information on the ENFREQ macro.

Note:

The following topic has been moved to Coding a system logger complete exit for IXGBRWSE, IXGWRITE, and IXGDELET in z/OS MVS Programming:

Authorized Assembler Services Guide.

IXGINVNT: Managing the LOGR policy

The IXGINVNT service allows your application program to manage and update the LOGR policy dynamically. You can also use the IXCMIAPU utility to manage the LOGR policy (see z/OS MVS Setting Up a Sysplex). The reason and return codes for both the IXGINVNT service and the IXCMIAPU utility are documented with the reference information on the IXGINVNT service in z/OS MVS Programming:

Assembler Services Reference IAR-XCT.

For guidance on specifying information in the LOGR couple data set using

IXGINVNT or IXCMIAPU, see the system logger chapter of z/OS MVS Setting Up a

Sysplex.

Using IXGINVNT, your application program can: v

Define and update log streams definitions using REQUEST=DEFINE or

REQUEST=UPDATE with TYPE=LOGSTREAM.

v Define a coupling facility structure associated with a log stream using

REQUEST=DEFINE with TYPE=STRUCTURE.

v Check whether a particular log stream or logger (coupling facility) structure definition exists in the LOGR policy using REQUEST=CHECKDEF.

v Delete log stream and coupling facility structure definitions using

REQUEST=DELETE.

Defining a model log stream in the LOGR couple data set

Use the MODEL parameter on the IXGINVNT REQUEST=DEFINE service to define a dummy log stream that other log stream definitions can reference. Using a model allows you to specify common log stream characteristics for many log streams only once.

480

z/OS MVS Assembler Services Guide

This can streamline the process of defining new log streams in the LOGR policy, because you can specify the name of the model log stream on the LIKE keyword when you issue the IXGINVNT service to define a new log stream. Note that any explicit definitions for the log stream you are defining override the definitions of the model log stream.

Figure 115 shows how you can use the IXGINVNT service to define a log stream as

a model and then define a log stream modeled after it. The LS_DATACLAS parameter specifying the data class for the log data sets for log stream STREAM1 overrides the LS_DATACLAS specified in the IXGINVNT request for log stream

MODEL1.

IXGINVNT REQUEST=DEFINE

TYPE=LOGSTREAM,

STREAMNAME=MODEL1,

STRUCTNAME=STRUCT1,

MODEL=YES,

HLQ=SYSPLEX1,

STG_DUPLEX=YES,

DUPLEXMODE=COND,

STG_DATACLAS=STGDATA,

STG_MGMTCLAS=STGMGMT,

STG_STORCLAS=STGSTOR,

LS_MGMTCLAS=LSMGMT,

LS-STORCLAS=LSSTOR,

LS_DATACLAS=LSDATA,

STG_MGMTCLAS=LSMGMT,

STG_STORCLAS=LSSTOR,

ANSAREA=ANSAREA,

ANSLEN=ANSLEN,

RETCODE=RETCODE,

RSNCODE=RSNCODE

IXGINVNT REQUEST=DEFINE

TYPE=LOGSTREAM,

STREAMNAME=STREAM1,

LS_DATACLAS=LSDATA1

LIKE=MODEL1,

ANSAREA=ANSARE1,

ANSLEN=ANSLE1,

RETCODE=RETCDE,

RSNCODE=RSNCDE

Figure 115. Define a Log Stream as a Model and then Model a Log Stream After It

You cannot connect to a model log stream or use it to store log data. It is strictly for use as a model to streamline the process of defining log streams.

You can use the LIKE parameter to reference a log stream that has not been defined as a model log stream using the MODEL parameter. Any log stream can be referenced on the LIKE parameter.

Defining a log stream as DASD-only

You can define a log stream as either a coupling facility log stream or DASD-only log stream using the DASDONLY parameter on the IXGINVNT

REQUEST=DEFINE TYPE=LOGSTREAM service (see “The log stream” on page

464).

Specify or default to DASDONLY=NO, to define a coupling facility log stream. You must also specify a structure name on the STRUCTNAME parameter in the log stream definition for a coupling facility log stream.

Chapter 27. Using system logger services

481

Specify DASDONLY=YES, to define a DASD-only log stream, which is not associated with a coupling facility structure. When you define a DASD-only log stream, you can also specify MAXBUFSIZE to define the maximum buffer size that can be written to the DASD-only log stream. (For a coupling facility log stream,

MAXBUFSIZE is specified on the IXGINVNT REQUEST=DEFINE

TYPE=STRUCTURE request to define the maximum log block size that can be written to the log stream.)

Note that a DASD-only log stream is single-system in scope - only one system may write to a DASD-only log stream.

For set up steps for a DASD-only log stream, see the system logger chapter in z/OS

MVS Setting Up a Sysplex.

Upgrading an existing log stream configuration

You can upgrade a DASD-only log stream to use coupling facility storage, making it a coupling facility log stream, or you can upgrade an existing structure-based log stream to use a different coupling facility structure. To upgrade to a structure-based log stream, associate the structure with the log stream by updating the log stream definition in the LOGR policy. Use the UPDATE request on either the IXGINVNT service or the IXCMIAPU utility to specify the name of the coupling facility structue with the STRUCTNAME parameter. All connectors to either the DASD-only log stream or the existing structure-based log stream being upgraded must be disconnected in order to make the upgrade. No failed or active connections can exist for the log stream.

When updating an existing log stream configuration, the GROUP attribute must be taken into account.

For details about updating the GROUP parameter, see "Parameters for

REQUEST=UPDATE" under the topic of IXGINVNT in z/OS MVS Programming:

Assembler Services Reference IAR-XCT.

For examples of log stream configuration changes, see Upgrading an existing log stream configuration in z/OS MVS Setting Up a Sysplex.

Upgrading a log stream from DASD-only to coupling facility

You can upgrade a log stream defined as DASD-only (DASDONLY=YES parameter on the log stream definition) to a coupling facility log stream. Do this by issuing the IXGINVNT REQUEST=UPDATE service with the STRUCTNAME parameter to associate a structure with the log stream.

To upgrade a log stream from DASD-only to coupling facility, the following must be true: v The structure specified on the STRUCTNAME parameter must be defined in a structure definition in the LOGR policy.

v All connections (active or failed) to the log stream must be disconnected.

Before connecting to or issuing any system logger services against an upgraded log stream, you must also make sure that the structure associated with the log stream is specified in the CFRM policy couple data set.

For guidance on upgrading a DASD-only log stream to a coupling facility based one, see the system logger chapter in z/OS MVS Setting Up a Sysplex.

482

z/OS MVS Assembler Services Guide

Updating an existing structure-based log stream to another structure

You can update an existing structure-based log stream to use a different coupling facility structure. Do this by issuing the IXGINVNT REQUEST=UPDATE service with the STRUCTNAME parameter to identify the new structure to be associated with the log stream.

To upgrade a structure-based log stream to use a new coupling facility structure, the following must be true: v The LOGR couple data set must be formatted at a z/OS Version 1 Release 2

(HBB7705) level or later.

v The IXGINVNT request must be submitted on a system at z/OS Version 1

Release 3 or later.

v The structure specified on the STRUCTNAME parameter must be defined in a structure definition in the LOGR policy.

v All connections (active or failed) to the log stream must be disconnected.

Before connecting to or issuing any system logger services against an upgraded log stream, you must also make sure that the structure associated with the log stream is specified in the CFRM policy couple data set.

Sample procedures to update an existing structure-based log stream to another structure:

You can use one of the these sample procedures to perform a non-destructive or destructive update of an existing structure-based log stream to another structure.

Steps for a non-destructive update of an existing structure-based log stream:

Use this sample procedure to perform a non-destructive update, which will maintain any existing log stream data.

1.

Define a new new-structure-name structure definition in the CFRM policy that has the appropriate SIZE, INITSIZE, and other attributes defined, and ensure that this new structure is in the current CFRM policy for the sysplex.

2.

Define a new new-structure-name structure in the LOGR policy with attributes

MAXBUFSIZE, AVGBUFSIZE, and LOGSNUM, as needed.

3.

Cause the exploiter to disconnect from the persistent-log-stream log stream.

4.

Confirm that no connections remain to the log stream in the sysplex. For example, you can issue the following system command:

DISPLAY LOGGER,L,LSN=persistent-log-stream

The status will be AVAILABLE when there are no more connections.

5.

Update the persistent-log-stream log stream definition in the LOGR policy to map it to the newly defined new-structure-name structure. For example:

IXCMIAPU type(logr)

UPDATE LOGSTREAM NAME(persistent-log-stream) STRUCTNAME(new-structure-name)

6.

Cause the exploiter to connect to the persistent-log-stream log stream.

7.

Confirm that the exploiter is connected on the expected z/OS images. For example:

DISPLAY LOGGER,L,LSN=persistent-log-stream

Chapter 27. Using system logger services

483

Steps for a destructive update of an existing structure-based log stream:

Use this sample procedure to perform a destructive update, which will delete the log stream and any existing data.

1.

Cause the exploiter to disconnect from the original-log-stream log stream.

2.

Confirm that no connections remain to the log stream in the sysplex. For example, you can issue the following system command:

DISPLAY LOGGER,L,LSN=original-log-stream

The status will be AVAILABLE when there are no more connections.

3.

Delete the original-log-stream log stream from the LOGR policy.

4.

Delete the original-structure structure from the LOGR policy.

5.

Redefine the structure in the LOGR policy with the original-structure name and attributes MAXBUFSIZE, AVGBUFSIZE, and LOGSNUM, as needed.

6.

Redefine the log stream in the LOGR policy with the original-log-stream name and map it to the redefined original-structure structure.

7.

Cause the exploiter to connect to the newly defined original-log-stream log stream.

8.

Confirm that the exploiter is connected on the expected z/OS images. For example:

DISPLAY LOGGER,L,LSN=original-log-stream

Renaming a log stream dynamically

You can rename a log stream dynamically using the NEWSTREAMNAME keyword on the IXGINVNT REQUEST=UPDATE request. Since many logging programs use a fixed log stream name, this function can be very useful for log stream recovery. For example, if a log stream fails, the system might not be able to perform any logging for the log stream that has failed. Using the log stream rename function, you can rename the failing log stream and then use IXGINVNT

REQUEST=DEFINE to define a new log stream with the old name in order to start logging again. This function allows you to perform the following functions: v Save the current data in a renamed log stream and start logging quickly by defining a new log stream with the expected name v Let existing services and utilities access the data in the renamed log stream to reduce the effect of having some data missing from the log stream v Perform problem diagnosis, such as data missing conditions, on the original

(renamed) log stream resources at the same time that new work continues

You must have an active primary TYPE=LOGR couple data formatted at an

HBB7705 level or higher in order to specify the NEWSTREAMNAME parameter.

For information, see: v Renaming a log stream dynamically in z/OS MVS Setting Up a Sysplex.

v IXGINVNT – Managing the LOGR inventory couple data set in z/OS MVS

Programming: Assembler Services Reference IAR-XCT.

v The IXCMIAPU UPDATE LOGSTREAM request in z/OS MVS Setting Up a

Sysplex.

Updating a log stream's attributes

You can update certain attributes of a DASD-only or coupling facility log stream using either the IXGINVNT UPDATE service or the IXCMIAPU utility. The updates are immediately reflected in the log stream definition in the LOGR couple

484

z/OS MVS Assembler Services Guide

data set, but some remain pending and do not take effect until specific events occur during processing as described in this section.

The following attributes can be updated while there is an outstanding (active or failed-persistent) connection to the log stream. Some of the updates will not take effect immediately if there is an outstanding connection. In order to update these attributes, the LOGR couple data set must be formatted at least at a certain format level. See LOGR parameters for format utility in z/OS MVS Setting Up a Sysplex for more details.

Note:

If this requirement is not met, the UPDATE request fails.

Pending updates will take effect at different points for each log stream attribute as follows: v The RETPD and AUTODELETE attribute updates take effect when a new offload data set is allocated (data set switch event) or on the subsequent first connection to the log stream in the sysplex.

v The LS_DATACLASS, LS_SIZE, LS_MGMTCLASS, LS_STORCLASS, and

LS_ALLOCAHEAD attribute updates will remain pending until a new offload data set is allocated (data set switch event) or on the subsequent first connection to the log stream in the sysplex. For a coupling facility log stream, the update also takes effect during the next structure rebuild (user-managed or system-managed).

v The LOWOFFLOAD, HIGHOFFLOAD, OFFLOADRECALL, STG_DATACLAS,

STG_MGMTCLAS, STG_STORCLAS, STG_SIZE, and WARNPRIMARY attribute updates remain pending until the subsequent first connection to the log stream in the sysplex. For a coupling facility log stream, the update also takes effect during the next structure rebuild (user-managed or system-managed). The

STG_DATACLAS, STG_MGMTCLAS, STG_STORCLAS, and STG_SIZE attribute updates are also committed when a new staging data set needs to be allocated following one of the preceding conditions. In the case of a DASD-only logstream, the HIGHOFFLOAD, LOWOFFLOAD, OFFLOADRECALL, and

WARNPRIMARY attribute updates are also committed on the next offload data set switch.

v The LOGGERDUPLEX, STG_DUPLEX, and DUPLEXMODE attribute updates for a structure-based logstream remain pending until the subsequent first connection to the log stream in a sysplex or until the next successful structure rebuild

(user-managed).

v The MAXBUFSIZE attribute update remains pending until the subsequent first connection to the DASD-only log stream in the sysplex.

v The ZAI and ZAIDATA attributes can be updated while there is an outstanding connection to the log stream. In this case, the change will immediately be reflected in the log stream definition. The updated specification will take effect on the following logger events for this log stream:

1.

On the subsequent first connection to the log stream on a system (z/OS image).

2.

As a result of a SETLOGR FORCE,ZAICONN,LSN= command on the target system. or

3.

As a result of a SETLOGR FORCE,ZAICONN,ALL command when there is a connection to this log stream currently using the ZAI=YES setting on the target system.

Chapter 27. Using system logger services

485

Note:

Since the updated value can be used on a system by system basis, the installation should ensure the proper actions are taken on all the systems with connections to the log stream in order to make use of the current value.

IXGCONN: Connecting to and disconnecting from a log stream

Use the IXGCONN service to connect to or disconnect from a log stream. An application must issue IXGCONN with REQUEST=CONNECT before it can read, write, or delete data in a log stream.

When the IXGCONN REQUEST=CONNECT request completes, it returns a unique connection identifier, called a STREAMTOKEN, to the calling program. The application uses the token in subsequent logger service requests to identify its connection to the log stream.

In the answer area (IXGANSAA) returned by IXGCONN, bit

Ansaa_DynMgmtOffEntryToEleActive is on when system logger is dynamically managing the entry-to-element ratio. See the system logger chapter in z/OS MVS

Setting Up a Sysplex for information about dynamic management of the entry-to-element ratio.

For IXGCONN REQUEST=CONNECT AUTH=WRITE, bit

Ansaa_WriteTriggersReturned indicates IXGWRITE requests may have the

Ansaa_WriteTriggers filled in the answer area of the IXGWRITE. See “Write triggers” on page 492 for additional information.

Note:

The following services contain parameters for both authorized and unauthorized programs: IXGCONN, IXGBRWSE, IXGWRITE, and IXGDELET. All other system logger services and their parameters can be used by any program. All the unauthorized guidance for system logger is contained in this chapter. The following topics have moved to the Authorized Assembler Services Guide: v Connecting as a resource manager in z/OS MVS Programming: Authorized

Assembler Services Guide

v Using ENF event 48 when a connect request is rejected in z/OS MVS

Programming: Authorized Assembler Services Guide

v Coding a resource manager exit for IXGCONN in z/OS MVS Programming:

Authorized Assembler Services Guide.

Examples of ways to connect to the log stream

An application can connect to the log stream in different ways. Some of these are: v One connection per address space : Once a program has connected to a log stream, any task running in the same address space shares the connect status and can use the same stream token to issue other system logger services. Any task in the address space can disconnect the entire address space from the log stream by issuing the IXGCONN REQUEST=DISCONNECT service.

v One connection per program : One or more tasks in a single address space can issue IXGCONN REQUEST=CONNECT individually to connect to the same log stream and receive separate stream tokens. Each program must disconnect from the log stream individually.

v Multiple systems connecting to a log stream

: Multiple address spaces on one or more MVS systems can connect to a single coupling facility log stream, but each one must issue IXGCONN individually to connect and then disconnect from the log stream. Each one receives a unique stream token; address spaces cannot share a stream token.

486

z/OS MVS Assembler Services Guide

When an application issues IXGCONN to connect to a coupling facility log stream, the system logger address space connects to the coupling facility list structure for the log stream.

Each task that issues IXGCONN REQUEST=CONNECT to connect to a log stream must later issue IXGCONN REQUEST=DISCONNECT to disconnect from the log stream. When a task disconnects from the log stream, the stream token that identified the connection is invalidated. Any requests that use the stream token after the disconnect will be rejected.

If a task that issued the IXGCONN REQUEST=CONNECT request ends before issuing a disconnect request, system logger will automatically disconnect the task from the log stream. This means that the unique log stream connection identifier, or the STREAMTOKEN, will no longer be valid. The application will receive an

“expired logstream token” error response if it then uses this same STREAMTOKEN after the task has been disconnected on subsequent logger service requests.

Additional considerations for connecting to a DASD-only log stream

If you are writing an application for a DASD-only log stream, you must keep in mind that a DASD-only log stream is single-system in scope, meaning that only

one system at a time can connect to a DASD-only log stream. (See “The log stream” on page 464 for a description of the two different types of log streams.)

Multiple applications from the same system can connect to a DASD-only log stream, but only from one system at a time. An application trying to connect to a

DASD-only log stream that already has another system connected will fail. A second system cannot connect to the DASD-only log stream until the first one disconnects.

The ANSAA_DASDONLYLOGSTREAM flag in the IXGANSAA mapping macro indicates whether a log stream is DASD-only.

When an application issues the IXGCONN request to connect to a DASD-only log stream, the STUCTNAME, AVGBUFSIZE, and ELEMENTSIZE will be returned containing hexidecimal zeros, because they are all coupling facility structure related fields.

How system logger allocates structure space for a new log stream at connection time

The first IXGCONN request in a sysplex issued for a coupling facility log stream initiates the allocation of coupling facility space for the log stream.

If there are multiple coupling facility log streams assigned to one coupling facility structure, system logger divides the structure space evenly between each log stream that has applications connected to it via IXGCONN. This means that the first log stream that has an IXGCONN service issued against it gets 100% of the coupling facility structure space available. When a second log stream mapping to the coupling facility structure has an IXGCONN service issued against it, system logger divides the structure evenly between the two log streams. The first log stream's available coupling facility space will be reduced by half to reapportion the rest of the space to the second log stream. This can result in some of the data being off-loaded to DASD if the coupling facility space allocated to a log stream reaches its high threshold as a result of the reapportionment of the structure space.

Chapter 27. Using system logger services

487

For example, if an installation defines two log streams to a single structure in the

LOGR policy, but only one of the log streams actually has a connected application, then that one log stream can use the entire coupling facility structure. When the second log stream connect occurs against the coupling facility structure, the space is gradually divided between the two log streams. Likewise, when the last disconnect is issued against one of the two log streams, all coupling facility structure space is again available to the first log stream.

Note that this process of reallocation of coupling facility space and subsequent offloading of coupling facility data might not take place immediately after the log stream connect. The reallocation of space might occur gradually, with an offloading taking place some time after the original log stream connect.

Connect process and staging data sets

Coupling Facility Log Streams

: If an installation defines DASD staging data sets for a coupling facility log stream, the data sets are created, if necessary, during connection processing for the first IXGCONN request issued against a log stream from a particular system.

DASD-Only Log Stream:

For a DASD-only log stream, the staging data set is automatically created during the first connect issued against the log stream. A staging data set is not optional for a DASD-only log stream.

Requesting authorization to the log stream for an application

Use the AUTH parameter to specify whether the application issuing IXGCONN should have read or write access to the log stream: v

If you specify AUTH=READ for an application, that application will only be able to issue IXGCONN, IXGBRWSE, and IXGQUERY requests. For AUTH=READ, the caller must have SAF read access to RESOURCE(log_stream_name) in

CLASS(LOGSTRM).

v If you specify AUTH=WRITE for an application, that application can issue any system logger service. For AUTH=WRITE, the caller must have SAF UPDATE access to RESOURCE(log_stream_name) in CLASS(LOGSTRM).

Requesting a write or import connection - IMPORTCONNECT parameter

Use the IMPORTCONNECT parameter to specify whether a connection is a write or an import connection. The IMPORTCONNECT parameter is only valid with

AUTH=WRITE.

v A write connection , (AUTH=WRITE IMPORTCONNECT=NO) specifies that you want to use the IXGWRITE request to write to a log stream. You must specify or default to IMPORTCONNECT=NO at connect time in order to use the

IXGWRITE request against a log stream.

You can have multiple write connects against a log stream, but only if there is no import connection established for that log stream anywhere in the sysplex.

Once one or more applications connect to a log stream as a write connection, any subsequent attempts to connect as an import connection will fail.

You cannot use the IXGIMPRT service against a log stream that has been connected to as a write connection from anywhere in the sysplex.

An import connection

, (AUTH=WRITE IMPORTCONNECT=YES) specifies that you want to use the IXGIMPRT request to import log data from one log stream to another, maintaining the same log block identifier and UTC time stamp. You

488

z/OS MVS Assembler Services Guide

might do this to create a copy of a log stream. You must specify

IMPORTCONNECT=YES at connect time in order to use the IXGIMPRT request against a log stream.

You can have only one import connection for a log stream from anywhere in the sysplex. An import connection cannot coexist with a write connection. Once an application connects to a log stream as an import connect, all subsequent

AUTH=WRITE IMPORTCONNECT=YES|NO connect requests will fail.

You cannot use the IXGWRITE service against a log stream that has been connected to as an import connection.

You cannot have both a write and an import connection to a log stream and you cannot issue both write and import requests to the same log stream.

Specifying user data for a log stream

System logger allows 64 bytes of user specified data to be associated with a log stream and stored in the LOGR policy. The user data can be: v Specified or changed using the USERDATA parameter on the disconnect request of IXGCONN.

v Read using the USERDATA output parameter on the connect request of

IXGCONN.

If an application codes the USERDATA parameter on a connect request when there is no user data associated with the log stream, IXGCONN returns a USERDATA field containing all zeros.

Only one copy of the log stream user data exists and any application connected to the log stream can update this copy when they disconnect. If you will have multiple connectors to a log stream, you should consider using serialization or another protocol to protect the USERDATA field.

System logger processing at disconnection and expired stream token

If your program runs authorized (supervisor state, system PKM), see Writing an

ENF event 48 listen exit in z/OS MVS Programming: Authorized Assembler Services

Guide for more details related to log stream disconnect processing and expired stream tokens.

Disconnection for an application

When an application issues IXGCONN REQUEST=DISCONNECT to disconnect from a log stream for a specific STREAMTOKEN, system logger rejects any new requests from that application for the specific STREAMTOKEN.

If the application disconnects with outstanding asynchronous requests, the disconnect is accepted. Asynchronous requests then complete without notifying the disconnecting application.

Last disconnection for log stream on a system

System logger rejects any new requests from the system for that log stream. All the log data from this system is then offloaded to DASD log stream data sets. This may include log data written from other systems connected to the log stream. For coupling facility log streams, the coupling facility resident data is offloaded to

DASD log data sets. For DASD-only log streams, the log data in local storage buffers is written to DASD log data sets.

Chapter 27. Using system logger services

489

If the application disconnects with outstanding asynchronous requests, the disconnect is accepted. Asynchronous requests then complete without notifying the disconnecting application.

Last disconnection for a system in the sysplex

System logger offloads all the log data to DASD log stream data sets.

For coupling facility log streams, the coupling facility resident data is offloaded to

DASD log data sets. Any coupling facility resources allocated for a coupling facility log stream are released. If a coupling facility structure is being shared among multiple log streams, the structure space is re-divided evenly among coupling facility log streams with connected applications at that time.

For DASD-only log streams, the log data in local storage buffers is offloaded to

DASD log data sets.

Expired log stream token

There are conditions that will cause a log stream connection token to no longer be valid. This means that the unique log stream connection identifier, or the

STREAMTOKEN, is no longer considered valid by system logger and the application receives an "expired log stream token" error response (refer to

IxgRsnCodeExpiredStmToken in IXGCON macro) for Logger service requests using a stream token as input.

An expired log stream token can be the result of an application explicitly or implicitly disconnecting from a log stream, or it can be the result of an action within system logger from either the CFRM policy, system environmental conditions, or from internal or system logger component errors. When an application encounters an "expired stream token" condition unexpectedly, then it should re-connect to the log stream and obtain a valid stream token before making any subsequent Logger service requests.

An expired log stream can occur under the following conditions: v The log stream connector disconnects from the log stream by issuing an

IXGCONNREQUEST=DISCONNECT,STREAMTOKEN=xstreamtoken and then issues another system logger services attempting to use the same

STREAMTOKEN value.

v The task (represented by a TCB or Task Control Block) that connected to the log stream terminates. This is often a problem that surfaces early in the coding of an application. Typically the application creates an initialization task to obtain resources. That task connects to the log stream, stores the log stream in persistent storage, and then terminates.

Because in this situation the "owning" task ended (through an end-of-task resource management operation), system logger automatically disconnects from the log stream. The correction for this is to connect to the log stream from a task that does not terminate until the log stream is no longer needed.

v Any job step task (JST) terminates within the address space that has a connection to the log stream. System logger treats any job step task termination in a manner similar to an address space termination. That is, all log stream connections are disconnected and logger associations are terminated with the address space.

If this condition occurs and there remains an expected use of a log stream, a new log stream connection will be required.

v Based on how and where the log stream token is maintained in the connector's storage, the system might pass an incorrect log stream to system logger. If the

490

z/OS MVS Assembler Services Guide

incorrect log stream token meets the format expected by system logger, then a return code X'04', reason code X'82D' (IxgRsnCodeExpiredStmToken) condition is returned. Otherwise, the incorrect log stream token results in the return code

X'08', reason code X'806' (IxgRsnCodeBadStmToken) condition.

An expired log stream token not caused by application can occur under the following conditions: v For coupling facility log streams, that you are not currently using, Logger can also disconnect a requestor when certain structure failure conditions occur.

v After an I/O or access error occurs for a staging data set, if system logger is unable to allocate a new data set for DASD-only log streams, system logger automatically disconnects the log stream.

v System logger disconnects all connectors on the target system as a result of an operator SETLOGR FORCE,DISConnect,LSN=logstreamname command.

v

When the system logger address space terminates and is restarted while the log stream connector was persistent (that is the application address space and connecting task remained intact) then any subsequent use of a log stream token obtained before system logger terminated would be considered expired.

v Severe error conditions can also occur within the Logger component that might cause the log stream to be disconnected unexpectedly.

Note that system logger will not disconnect a connector for log stream offload data set allocation errors or data set "full" conditions. The allocation of log stream offload data sets does not result in an "expired log stream token" condition.

IXGWRITE: Writing to a log stream

Use the IXGWRITE service to write data from the user's buffer to a log stream. The way system logger processes an IXGWRITE request depends on whether the log stream is coupling facility or DASD-only:

For coupling facility log streams

, system logger writes the data to the coupling facility structure space associated with the log stream when an IXGWRITE request is issued. System logger also duplexes the data to either local storage buffers or staging data sets.

For DASD-only log streams

, system logger writes the data to interim storage in local storage buffers for the system associated with the log stream. It is simultaneously duplexed to DASD staging data sets. The safe import point for a

DASD-only log stream is changed for every successful write request.

The log block buffer

Before you issue the IXGWRITE service to write your data to the log stream, you must place the data in a buffer to form the log block. This buffer must follow these guidelines: v The storage key for the buffer, specified on the BUFFKEY parameter, must be one of the following:

– If the caller is in problem program state, the buffer must be in the same storage key as the caller's PSW key.

– If the caller is running in supervisor state, the buffer can be in any key (0 through 15).

v The buffer must be either ALET qualified (BUFFALET parameter), or reside in the caller's primary address space.

Chapter 27. Using system logger services

491

v The buffer length specified on the BUFFLEN parameter must not exceed the maximum buffer size defined in the LOGR policy for the coupling facility structure.

The format of the data in the log block is entirely the choice of the application; system logger does not have rules about how data looks in a log block.

For each log block written to the log stream, IXGWRITE returns a unique log block identifier which can be used on subsequent IXGDELET and IXGBRWSE requests to search for, delete, read, or set the browse cursor position to that log block.

Ensuring chronological sequence of log blocks

When an application writes log blocks to a log stream, system logger generates a time stamp for the block, in both local and Coordinated universal time (UTC), showing the time that system logger processed the block. The local time stamp is the local time of the system where the IXGWRITE was issued. Note that local time stamps can repeat because of daylight saving time. In such a case of duplicate time stamps, system logger will return the first block with a matching time stamp that it finds.

Log blocks are placed in the log stream in the order they were received by system logger. System logger generates a UTC time stamp for each log block it receives.

Note that the order in which the log blocks are received is not necessarily the same order in which log blocks were written, because when multiple applications write to the same log stream, the log blocks might not be received in the same order that they were written.

An application imbedded time stamp will not affect the order of the log blocks in the log stream. If an application needs to ensure that log blocks are received into the log stream in the order written, IBM recommends that applications serialize on the log stream before they write to it.

Applications can optionally request that IXGWRITE return the time stamp that system logger generates for a log block using the TIMESTAMP parameter.

Write triggers

In the answer area (IXGANSAA) returned by IXGWRITE, bit

Ansaa_WriteTriggersReturned indicates that the Ansaa_WriteTriggers section has been filled in.

The write triggers are returned for successful IXGWRITE requests (RETCODE = 0 or 4) and show log stream primary storage consumption information.

ANSAA_STRUCTUSEPERCENT is returned for coupling facility structure based log streams and indicates the percentage of CF structure elements in use (between

0 and 100) for the log stream.

ANSAA_STAGINGUSEPERCENT is returned for DASDONLY log streams and for

CF structure based log streams that duplex to staging data sets. The value indicates the percentage of staging data set space in use (between 0 and 100).

The flags ANSAA_WRITEABOVEHIGHOFFLOAD,

ANSAA_WRITEELEVATEDCAPACITY and

ANSAA_WRITEIMMINENTCAPACITY are filled in based on current primary storage usage and log stream definition HIGHOFFLOAD percentage. For CF

492

z/OS MVS Assembler Services Guide

structure based log streams, the flags are based on

ANSAA_STRUCTUSEPERCENT. For DASDONLY log streams, the flags are based on ANSAA_STAGINGUSEPERCENT. ANSAA_WRITEABOVEHIGHOFFLOAD indicates the usage is greater than HIGHOFFLOAD.

ANSAA_WRITEELEVATEDCAPACITY indicates the usage above the 1/2 point between HIGHOFFLOAD and the log steam imminent threshold.

ANSAA_WRITEIMMINENTCAPACITY indicates the usage above the imminent threshold. The derived value for the imminent threshold is the 2/3 point between

HIGHOFFLOAD and 100% full.

When is data committed to the log stream?

When you issue the IXGWRITE service to write data to a log stream, you cannot consider the data committed until system logger returns control to the user with a successful return code. Particularly when dealing with a coupling facility log stream, you should never rely on a block ID associated with uncommitted data.

For example, consider the following scenario involving a coupling facility log stream:

1.

Application 1 issues an IXGWRITE service, and the data is written to the coupling facility.

2.

Before the data can be duplexed to staging data sets and control returned to the user, application 2 issues IXGBRWSE for that block of data and successfully reads the data.

3.

Now, suppose the coupling facility fails - the data that application 2 read was never committed and is now lost! Application 2 is using log data which no longer exists.

4.

At this point, system logger might assign the identical block ID to a different log block and applications 1 and 2, which are trying to share a log, are now out of sync.

For a DASD-only log stream there is less likelihood of losing data, because log data is duplexed automatically to a staging data set. Data is committed when the log data has been written to local storage buffers and duplexed to the staging data set. Note that for a DASD-only data set, log data cannot be browsed until it is committed.

See “Synchronous and asynchronous processing” on page 474 for more details on

the methods used by system logger to provide return code information to the invoking program. When an IXGWRITE request cannot be completed synchronously, system logger indicates this by returning to the invoking program with the specific return code X'4' and reason code X'401' (IxgRetCodeWarning and

IxgRsnCodeProcessedAsynch, re: macro IXGCON). IXGWRITE requests that are completed synchronously will result in system logger returning a return code X'0' or a return code of X'4' with a reason code other than X'401' (IxgRetCodeOK, or

IxgRetCodeWarning and not IxgRsnCodeProcessedAsynch).

When the log stream coupling facility storage limit is reached

An IXGWRITE request will be rejected with return code X'08' and reason code

X'0860' when the storage limit for the coupling facility structure associated with a coupling facility log stream is reached. Although the data offload to DASD process generally ensures that data gets written to DASD before the coupling facility structure fills up, this condition can occur due to sudden bursts of activity or when

Chapter 27. Using system logger services

493

another log stream is activated and defined to the coupling facility. When this happens, system logger offloads data from the coupling facility to DASD immediately.

Applications should not issue any further write requests until the temporary condition has been resolved. Applications that do not want to use ENF event code

48 or that are unauthorized and cannot use ENFREQ would still receive system logger service return and reason codes indicating failure or resource shortages.

These applications can then set a time and then retry the requests to see if the problem has resolved itself.

If system logger is unable to offload the log data because of log data set directory space shortages or other log stream offload issues, then the IXGWRITE request may also be rejected with return code X'08' and reason code X'085C' or X'085D'.

You can retry your IXGWRITE (or IXGIMPRT) request periodically or wait for the

ENF signal that the log stream is available, or disconnect from this log stream and connect to another log stream. For additional actions related to log stream offloads, refer to system messages IXG257I, IXG261E, IXG262A and IXG301I.

When the staging data set storage limit is reached

If the staging data set storage limit for a coupling facility or DASD-only log stream connection is reached, an IXGWRITE request will be rejected with a return code of

X'08' and a reason code of X'0865'. When this happens, system logger initiates the offload process to move log data to DASD log data sets and delete corresponding staging data set log data immediately. When offload processing completes, write requests can complete successfully and the staging data set is available to hold duplexed log data again.

Applications should not resume issuing write requests until the temporary condition has been resolved. Applications that do not want to use ENF event code

48 or that are unauthorized and cannot use ENFREQ will still receive logger service return and reason codes indicating failure or resource shortages. These applications can then set a timer and then retry the requests to see if the problem has resolved itself.

If system logger is unable to offload the log data because of log data set directory space shortages or other log stream offload issues, then the IXGWRITE request may also be rejected with return code X'08' and reason code X'085C' or X'o85D'.

You can retry your IXGWRITE (or IXGIMPRT) request periodically or wait for the

ENF signal that the log stream is available, or disconnect from this log stream and connect to another log stream. For additional actions related to log stream offloads refer to system messages IXG257I, IXG261E, IXG262A and IXG301I.

When the staging data set is formatting

An IXGWRITE request will be rejected with a return code of X'08' and a reason code of X'0868 ' while the log stream's staging datasets are being formatted. The first application to connect to a log stream on a particular system causes logger to format the log stream's staging data sets on that system. Each system has its own set of staging datasets. Applications should not resume issuing write requests until the temporary condition has been resolved. Applications that do not want to use

ENF event code 48 or that are unauthorized and cannot use ENFREQ will still receive system logger service return and reason codes indicating failure or resource shortages. These applications can simply set a timer and retry the requests to see if the problem has resolved itself.

494

z/OS MVS Assembler Services Guide

Limiting asynchronous IXGWRITE requests

The number of concurrent IXGWRITE requests for each connector to a log stream that requires asynchronous logger activity is limited. The limit is decided before the log block write request is accepted. If the amount of previous in-flight asynchronous writes is above the acceptable limit, then the newly requested write is rejected (the log data is not placed in the log stream). The limit of the connections for authorized IXGWRITE invokers is 10,000, and for unauthorized

IXGWRITE invokers is 2000. An unauthorized invoker is the caller who is in supervisor state and has a PSW key 8 or larger.

Logger counts the number of IXGWRITE requests that require logger asynchronous activity based on a log stream connection. As the asynchronous activity is needed for an IXGWRITE request, logger increases the count for that log stream connector, and logger decreases this count when the asynchronous write activity completes.

Examples of logger asynchronous activity for a write request include, but are not limited to, IXGWRITE threads that are waiting on completion of logger's XES write

(IXLLIST WRITE) requests or logger's staging data set I/O (via Media Manager) requests.

If logger and the storage media used to hold the log blocks cannot keep pace with the incoming write requests, logger can eventually reach an asynchronous write threshold of 2000 for unauthorized callers or 10,000 for authorized callers. The limits are triggered for a short period of any new IXGWRITE requests for the log stream connector. IXGWRITE requests that complete synchronously are not included in the limit counting. However, when the limit is reached, all new

IXGWRITE requests for the invoker are rejected with return code X'08', reason code

X'0867'. For information about the return code X'08', reason code X'0867', see

Return and Reason codes table in IXGWRITE in z/OS MVS Programming: Authorized

Assembler Services Reference EDT-IXG.

Logger allows new or reissued IXGWRITE requests for this connector when the number of in-flight asynchronous writes is adequately reduced. The number is no more than 85% of the limit threshold in-flight, which must be no more than 1700 for unauthorized callers and 8500 for authorized callers. A logger ENF signal 48 is issued at this point indicating the log stream resources are available. Then, logger can track sufficient write requests and only reject the requests whose write rate and volume are beyond the limitation of logger.

Logger writes software symptom records to logrec and to logger's component trace area when logger has encountered this limit condition and when the limit is resolved. Sample portions of logger symptom records for these conditions after running EREP reports as the following output:

5752SCLOG RIDS/IXGF2WRT RIDS/IXGINLPA#L LVLS/709

FLDS/RETCODE VALU/H00000004 FLDS/REASON VALU/H04030017

IXGF2WRT ASYNC LIMIT REACHED

5752SCLOG RIDS/IXGF2WRT RIDS/IXGINLPA#L LVLS/709

FLDS/RETCODE VALU/H00000004 FLDS/REASON VALU/H04030018

IXGWRITE ASYNC LIMIT RELIEVED

IXGBRWSE: Browsing/reading a log stream

Use the IXGBRWSE macro to read and browse a log stream for log block information. Applications can: v Start a browse session and select the initial cursor position - (REQUEST=START) v Reset the browse cursor position - (REQUEST=RESET)

Chapter 27. Using system logger services

495

v Read consecutive log blocks - (REQUEST=READCURSOR) v

Select and read a specific log block - (REQUEST=READBLOCK) v End a browse session - (REQUEST=END)

IXGBRWSE reads the specified log block into an output buffer specified by the application.

IXGBRWSE terminology

Before you can read information from the log stream, you start a browse session using the REQUEST=START request of IXGBRWSE. A browse session lasts from the time that an application issues IXGBRWSE REQUEST=START until it issues

IXGBRWSE REQUEST=END. A log stream can have multiple browse sessions occurring at the same time.

The REQUEST=START request returns a browse token, which is a unique 4-byte identifier for a particular browse session. Subsequent IXGBRWSE requests in a browse session use the browse token to identify the session to system logger. Once an application issues the REQUEST=END request, the browse session ends and system logger will no longer accept IXGBRWSE requests with the browse token for that session.

The browse cursor indicates where in the log stream IXGBRWSE will resume browsing on the next request. Each browse session has a browse cursor.

IXGBRWSE requests

REQUEST=START

starts the browse session for the application and sets the browse cursor to the desired starting point. You can specify the browse cursor position for a session using one of the following optional parameters: v OLDEST - which is the default, starts the browse session at the oldest (earliest) log block.

v YOUNGEST - starts the browse session at the youngest (latest) log block. Note that the record that is the youngest when the browse session starts might no longer be the youngest record at the end of the browse session because of concurrent write activity to the log stream.

v STARTBLOCKID - specifies that the browse session start at a specified log block identifier. The block identifier for a log block is returned by system logger when it is written to the log stream (IXGWRITE) in the field specified by the

RETBLOCKID parameter.

v

SEARCH - specifies that the browse session start at the log block with the

specified time stamp. See “Browsing for a log block by time stamp” on page 497

for details on how IXGBRWSE processes time stamps.

Field ANSAA_BROWSEMULTIBLOCK in the answer area will be set on if the level of system logger supports MUTLIBLOCK=YES requests for

REQUEST=READCURSOR.

REQUEST=RESET

positions the browse cursor to either the oldest or youngest

(POSITION=OLDEST or POSITION=YOUNGEST) log block in the log stream.

REQUEST=READBLOCK

reads a selected log block in the log stream. You identify the block you want to read by either the block identifier (BLOCKID parameter) or the time stamp (SEARCH parameter). The block identifier for a log

496

z/OS MVS Assembler Services Guide

block is returned by system logger in the field specified by the RETBLOCKID parameter when the log block is written to the log stream (IXGWRITE).

REQUEST=READCURSOR

reads the next oldest or youngest log block or blocks in the log stream, depending on the direction specified on the request

(DIRECTION=OLDTOYOUNG or YOUNGTOOLD). The block or blocks read also depends on the position of the cursor at the time you issue the request. The

MULTIBLOCK value determines whether one or more blocks will be returned.

Applications must take into account that reading a series of consecutive log blocks using REQUEST=READCURSOR might not yield blocks in sequence by local time stamp. This can happen, for example, because of daylight saving time.

Browsing both active and inactive data

Using the VIEW parameter on IXGBRWSE, you can choose to browse just active log data or both active and inactive log data. Active data is data that has not been deleted via IXGDELET. Inactive data is data that has been deleted via IXGDELET but is still in the log stream because of a retention period specified in the log stream definition in the LOGR couple data set. See z/OS MVS Setting Up a Sysplex for information about the retention period.

VIEW=ACTIVE

Specifies that the browse request browse just active data. VIEW=ACTIVE is the default.

VIEW=ALL

Specifies that the browse request browse all data, both active and inactive.

The flag ANSAA_BLKFROMINACTIVE in the answer area indicates if the returned log block (or any of the returned log blocks when MULTIBLOCK=YES is specified) came from inactive data. If MULTIBLOCK=YES is specified,

IXGBRMLT_FROMINACTIVE will indicate if a particular log block came from inactive data.

The VIEW parameter can be specified on both the REQUEST=START and

REQUEST=RESET requests of IXGBRWSE. For the duration of a browse session, the VIEW specification remains in effect.

Browsing for a log block by time stamp

System logger generates a time stamp in both local and Coordinated universal time

(UTC) for each log block in the log stream. The time stamp is returned in the

TIMESTAMP output field when the block is written to the log stream using

IXGWRITE. Note that the local time stamp is the local time of the system where the IXGWRITE was issued.

You can use either the local or UTC time stamp on the SEARCH keyword to search for a system logger generated time stamp. You can specify the SEARCH keyword on the following IXGBRWSE requests: v REQUEST=START, to set the cursor at a particular log block. or

REQUEST=READBLOCK (to read a particular log block), v REQUEST=START, to set the cursor at a particular log block.

When you use a time stamp as a search criteria, IXGBRWSE searches in the oldest-to-youngest direction, searching for a log block with a matching time stamp.

If no match is found, IXGBRWSE reads the next latest (younger) time stamp. When

Chapter 27. Using system logger services

497

you search by time stamp, the search always starts with the oldest log block in the log stream. Searches by time are not sensitive to the current browse cursor position.

See Figure 116 for an example.

If the time stamp specified is older than any time stamp in the log stream, then the oldest time stamp is returned.

If the time stamp specified is younger than any existing time stamps, the request is rejected and the caller receives a return code of X'08' and a reason code of X'0804'.

Logstream

9:00 10:00 11:00

Browse direction:

OLDEST

Figure 116. Searching for a Log Block by Time

YOUNGEST

Given the example log stream in Figure 116, system logger would do the following:

v If you specify 8:00 on the SEARCH keyword, this is older (earlier) than any log block in the log stream and IXGBRWSE will set the cursor at or returns the oldest time stamp, in this case, 9:00.

v If you specify 10:30 on the SEARCH keyword, IXGBRWSE sets the cursor at or returns the next latest (youngest) log block, 11:00.

v If you specify 12:00 on the SEARCH keyword, this time stamp is younger (later) than any existing log block and IXGBRWSE rejects the request with a return code of X'08' and a reason code of X'0804'.

Browsing multiple log blocks

Use IXGBRWSE REQUEST=READCURSOR with MULTIBLOCK=YES to read a set of consecutive log blocks in the specified direction and view. Mapping macro

IXGBRMLT provides a mapping at the start of the buffer area (IXGBRMHD), that indicates the number of log blocks that are returned plus an offset to the last

IXGBRMLT area in the buffer. IXGBRMLT also provides a mapping of the information returned for each log block on a MULTIBLOCK=YES request.

You can control how much information is returned about each log block with the

RETBLOCKINFO parameter. When RETBLOCKINFO=NO is specified, system logger will return only enough information about each log block to allow the invoker to navigate through the buffer. If RETBLOCKINFO=YES is specified, system logger will return more information about each log block in the output buffer, but it will use more space in the caller's buffer since more information per log block is returned.

MAXNUMLOGBLOCKS can be used to limit the number of log blocks that will be returned in the buffer area. When a non-zero value is specified, system logger will

498

z/OS MVS Assembler Services Guide

not return more than this requested number of log blocks, even if there are more log blocks that meet the browse parameter criteria. If enough room is provided in the caller's buffer and there are sufficient log blocks that meet the browse criteria, system logger will return the requested maximum number of log blocks. If there is not enough room in the buffer, or there are fewer log blocks remaining than the requested maximum number, system logger will return as many of the remaining log blocks as fit into the caller's buffer.

Return and reason code considerations

On IXGBRWSE REQUEST=READCURSOR requests, more than one log block may be returned to the requestor. Logger may encounter different conditions for different log blocks.

The following return and reason codes may be issued to indicate the particular condition: v IXGBRWSE MODE=SYNCECB or MODE=SYNCEXIT requests that are processed asynchronously will result in a return code of X'04' and a reason code of X'401', and will be handled in the same manner as MULTIBLOCK=NO requests.

v When an IXGBRWSE request results in a return code of X'0' with a reason code of X'0', then the return and reason codes are always 0 for each IXGBMRLT for the log blocks, and data is always returned.

v When an IXGBRWSE request results in a return code of X'04' with a reason code of X'416', data is always returned. Any combination of return code X'04' and reason code X'4xx' or return code X'00' and reason code X'000' may be returned in the output buffer area.

v If a return code of X'04' with a reason code of X'417' is returned, then only the last IXGBMRLT has a return code of X'08'. There may be an earlier log record with an IXGBMRLT return code X'04' and reason code X'4xx'.

v It is possible to have some log records read back and then get an IXGBRMLT return and reason code that requires a wait for an ENF 48 event. The

IXGBRWSE return code would be X'04' with a reason code of X'417', and the last

IXGBRMLT would contain the ENF 48 condition (8/8xx).

v When the browse request reaches the end of log after moving some data into the buffer, the last IXGBRMLT will have a return code of X'08' with a reason code of

X'848' and IXGBRWSE will have a return code of X'04' with a reason code of

X'417'. If another IXGBRWSE is issued and there are still no more log records to read, the IXGBRWSE service will have a return code of X'08' with a reason code of X'848'. The buffer area is undefined for this return/reason code, so you cannot trust its contents.

Using IXGBRWSE and IXGWRITE

If you have applications issuing IXGWRITE and IXGBRWSE requests concurrently for the same coupling facility log stream, ensure that the browse requests are issued only for committed log data. Data is committed to the log stream when system logger returns control to the application following an IXGWRITE request with a successful return code. This is important because data can be lost due to system or coupling facility failure between the time data appears on the structure associated with the log stream and a commit occurs. If you read uncommitted data that is subsequently lost, applications sharing the same log stream can have

different versions of log data. See also “When is data committed to the log stream?” on page 493.

Chapter 27. Using system logger services

499

Using IXGBRWSE and IXGDELET requests together

If you issue IXGDELET and IXGBRWSE requests concurrently, be careful not to delete information before you try to read it. An IXGDELET request can also affect a browse session for a log stream by deleting a requested log block or the log block where the browse cursor is positioned. When an application issues an IXGBRWSE request for log data which has been deleted, the IXGBRWSE request will return non-zero return and reason codes.

Applications might want to provide serialization on the log stream or some other installation protocol to prevent deletes (IXGDELET service) from being performed by other applications on the log stream during a browse session.

IXGDELET: Deleting log blocks from a log stream

Using the IXGDELET service, you can mark some or all of the log blocks in the log stream for deletion. For a coupling facility log stream, the group of blocks you specify for deletion can reside on both the coupling facility and DASD log data sets. For a DASD-only log stream, the group of blocks you specify for deletion can reside on both the local storage buffers and DASD log data sets. The way system logger processes log data that is marked for deletion depends on the level of the current primary LOGR couple data set for the sysplex and whether a retention period and automatic deletion have been specified for a log stream in the LOGR couple data set. See Deleting log data and log data sets in z/OS MVS Setting Up a

Sysplex for more information.

Note:

The following topic has been moved to Delete requests and resource manager exit processing in z/OS MVS Programming: Authorized Assembler Services

Guide.

Using the BLOCKS parameter

If you specify BLOCKS(ALL) to delete all of the blocks in the log stream, system logger immediately marks as deleted all the blocks that exist at the time of the request. If other applications are writing to the log stream concurrently with the delete request, there might be log blocks in the log stream even after the

IXGDELET BLOCKS(ALL) request is processed.

When you want to delete a subset of log blocks, specify BLOCKS(RANGE) and a block identifier on the BLOCKID parameter. System logger marks as deleted all

the log blocks older (written earlier) than the specified log block.

See Figure 117 on page 501 for an illustration of how BLO CKS(RANGE) works. Note that the

block specified in BLOCKID is not deleted.

500

z/OS MVS Assembler Services Guide

Log stream

Log blocks:

9:00

Block ID: 1

OLDEST

10:00 10:30 11:00 12:00

Block ID: 4 Block ID: 5

YOUNGEST

IXGDELET BLOCKS=RANGE BLOCKID=3

Log stream

Log blocks:

9:00 10:00 10:30 11:00 12:00

Block ID: 1 Block ID: 2 Block ID: 3 Block ID: 4 Block ID: 5

OLDEST

Figure 117. Deleting a Range of Log Blocks

YOUNGEST

IXGIMPRT: Import log blocks

Use the IXGIMPRT service to write data to a log stream, specifying a log block identifier and UTC time stamp for each log block. This service can be used to import copies of log data from one log stream to another, preserving the UTC time stamp and log block identifier assigned when the log block was written to the source log stream. The source log stream is the original log stream, the log stream are importing blocks from. The log stream you import blocks to is the target log

stream

.

In order to use the IXGIMPRT service, the connection to the log stream must be an import connection, issued with AUTH=WRITE IMPORTCONNECT=YES. Note that when you specify AUTH=WRITE IMPORTCONNECT=YES for a connection, you cannot issue the IXGWRITE request against the connected log stream. See

“IXGCONN: Connecting to and disconnecting from a log stream” on page 486 for

information about the IMPORTCONNECT parameter.

You must be in task mode to issue the IXGIMPRT service or else the request is rejected.

Making sure log blocks are imported in sequence -

Understanding log block identifiers

When you import data to a log stream (using IXGIMPRT), the requests are issued with a log block identifier and UTC time stamp identical to the matching log block

Chapter 27. Using system logger services

501

in the source log stream. The application must make sure to import these log blocks in ascending log block/UTC time stamp order.

For example, if the importing application has log blocks with identifiers 1, 2, and 4 ready to import, the application might need to wait and check for log block 3 before importing 1, 2, and 4 into a log stream. Once log block 4 has been imported, log block 3 can never be imported into the log stream (unless you delete and redefine the log stream). In order to determine whether it is importing log blocks in the correct order, the application must understand the way system logger generates log block identifiers.

The block identifier consists of the logical relative byte address of the log block in relation to the start of the log stream. The first log block written to a log stream is assigned a block identifier of one. Whenever a system logger application writes a log block successfully to the log stream, system logger adds additional control information to the log block. To generate the sysplex-wide unique block identifier, system logger uses: v The block identifier of the last log block written.

v The length of the current log block (specified by the caller).

v The length of control information (determined by system logger).

The formula is as follows:

Length of current log block

+ length of control information

+ last log block identifier.

How do I know what the length of the control information is?

Applications can ascertain the length of the control information generated by system logger using the IXGQUERY service, which returns the information in a buffer mapped by the IXGQBUF macro (QBUF_CONTROL_INFO_SIZE field).

Example: How log block identifiers are generated

The following is an example of how log block identifiers are generated: v The log block identifier generated for the first log block is one.

v The first log block is one hundred bytes. The length of the control information system logger adds to a log block for this log stream is 25 bytes: this information was found using the IXGQUERY service.

v

The block identifier for the second log block is generated by adding the first log block identifier to the length of the first log block and the length of the control information: 1+100+25 or 126.

v The 2ND log block is 50 bytes in length, and system logger again added 25 bytes of control information. The block identifier for the third block is 50+25+126 or 201.

Making sure log data is safe to import

If your application is using IXGIMPRT to create a duplicate log, copying information from a source to a target log stream, you must make sure that the data

is safe to import. See “The safe import point: Using IXGQUERY and IXGIMPRT together” on page 504.

502

z/OS MVS Assembler Services Guide

IXGQUERY: Get information about a log stream or system logger

Use the IXGQUERY service to retrieve information about a log stream in the sysplex, or retrieve the system logger ZAI SERVER and PORT values pertaining to the z/OS IBM zAware server location.

When using the IXGQUERY service to retrieve information about a log stream in the sysplex, the information is returned in a buffer mapped by IXGQBUF. The information returned by IXGQUERY for a log stream includes: v

Safe import point. See “The safe import point: Using IXGQUERY and IXGIMPRT together” on page 504.

v Control information size: This value shows the number of bytes that system logger adds to each log block written to the log stream.

v

Structure version number for coupling facility log streams. See “The coupling facility list structure version number” on page 506.

For DASD-only log streams, this value shows the STCK format time stamp that the staging data set for the DASD-only log stream was allocated.

v Group information about the log stream. Every log stream is in either group

TEST or PRODUCTION. See the QBUF_GROUPVALUE field in the IXGQBUF mapping macro. TEST indicates that the log stream is a test log stream.

PRODUCTION indicates that the log stream is a production log stream. Note that you must specify a BUFFLEN value of 200 bytes or more to retrieve the group data for the log stream. See the GROUP keyword in IXGINVNT –

Managing the LOGR inventory couple data set in z/OS MVS Programming:

Assembler Services Reference IAR-XCT.

v

Information related to the size of the current offload data set and staging data set in the IXGQBUF. Note that the maximum value returned in fields

QBUF_LS_DS_SIZE and QBUF_STG_DS_SIZE is 2GB-1 ('7FFFFFFF'x ). For data set sizes greater than 2GB, '7FFFFFFF'X will be returned, but the full value will be available in fields QBUF_FULL_LS_DS_SIZE and

QBUF_FULL_STG_DS_SIZE.

v When QBUF_LS_Offload_Returned is turned on in the IXGQBUF, the fields

QBUF_LS_HighOffload and QBUF_LS_LowOffload are filled in with the log stream definitional HIGHOFFLOAD and LOWOFFLOAD fields.

v Information about the log stream definition values for the elevated and imminent capacity points, which correspond to the IXGWRITE ANSAA flags

ANSAA_WRITEELEVATEDCAPACITY and

ANSAA_WRITEIMMINENTCAPACITY. See “Write triggers” on page 492 for

more information on the how the ANSAA_WRITEELEVATEDCAPACITY and

ANSAA_WRITEIMMINENTCAPACITY fields are set.

When using the IXGQUERY service to retrieve system logger parameter options, the information is returned in a buffer mapped by IXGQZBUF. The information returned by IXGQUERY includes system logger parameter options for: v ZAI SERVER value and significant length of value.

v ZAI PORT value and significant length of value.

Since the system logger parameter options can change as a result of (SET or

SETLOGR) commands, refer to topic “Using ENF event code 48 in system logger applications” on page 480 for details on keeping informed of when changes to

these parameters occur.

Chapter 27. Using system logger services

503

You must be in task mode to issue the IXGQUERY service or else the request is rejected.

For information about the IXGQBUF and IXGQZBUF fields, see z/OS MVS Data

Areas in the z/OS Internet library (www.ibm.com/systems/z/os/zos/library/ bkserv).

The safe import point: Using IXGQUERY and IXGIMPRT together

If you have an application (a resource manager, for example) that uses the

IXGIMPRT service to import log data from a source log stream to a target log stream, creating a duplicate or back-up log stream, you can use IXGQUERY to ascertain the safe import point for a log block before importing it, to make sure the two log streams are synchronized.

See: v

“Coupling facility log streams and the safe import point.”

v

“DASD-only log streams and the safe import point” on page 506.

Coupling facility log streams and the safe import point

Keeping the log streams synchronized can be particularly difficult when the situation involved coupling facility log streams. If the importing application imports data from a source to a target log stream before it is safely hardened on

DASD log data sets or staging data sets, you might get inconsistencies between the source and target log streams. For example, if an importing application involves coupling facility log streams, it is particularly difficult to keep the two log streams

synchronized. For example, Figure 118 on page 505 illustrates the problem. This

figure shows a source log stream, SOURCE1, that is written to by applications on two systems, SYS1 and SYS2. SYS1 also contains the coupling facility containing the structure associated with SOURCE1. That means that SYS1 contains a single point of failure and is therefore backed up by a staging data set. SYS2 is a failure independent connection and is not using a staging data set for SOURCE1.

SYS2 has written log blocks 4, 5, and 6 to the log stream coupling facility structure associated with SOURCE1. SYS1 wrote 1, 2, and 3 to the SOURCE1's coupling facility structure. The importing application on SYS3 browses log stream

SOURCE1, seeing log blocks 1 through 6 and imports them to log stream

TARGET1.

Meanwhile, on SYS1 log blocks 1 and 2 got duplexed to the staging data set, but before 3 could be duplexed, a failure in SYS1 knocked out both the MVS system and the coupling facility. When a rebuild is initiated, only SYS2 can participate to repopulate the log stream. SYS2 repopulates the new structure with the data it wrote (log blocks 4, 5, and 6) and gets blocks 1 and 2 from the staging data set for

SYS1. But log block 3 is not repopulated to the rebuilt structure because the data was not committed to the staging data set. Thus, after the rebuild, log stream

SOURCE1 contains blocks 1, 2, 4, 5, and 6, while TARGET1 contains 1-6. The source and target log streams are now out of sync.

504

z/OS MVS Assembler Services Guide

Before Rebuild After Rebuild

CPC 1

Sys 1

1 2

SYS2/Source1

Staging

Data

Set

1 2 3

CPC 2

Sys 2

4

5

66

Structure A

SOURCE1 Log stream

. . . . . .

Structure A

1 2 4 5

SOURCE1 Log stream

6

CPC 3

Sys 3

1XG1MPRT

CPC 4

Structure B

TARGET1 Log stream

. . .

Structure B

1 2 3 4 5

TARGET1 Log stream

6

Figure 118. How Source and Target Log Streams Can Get Out of Sync

To prevent this problem, system logger provides the safe import point. This helps an application ensure that log data is safe to import. The safe import point is the highest log block identifier that is no longer in the coupling facility structure for a log stream. Any blocks with a block identifier less than or equal to the safe import point can be safely imported to the target log stream. In the preceding example, log streams SOURCE1 and TARGET1 are potentially out of sync unless the importing application on SYS3 determines the safe import point before importing the data to the target log stream. An application can determine the safe import by doing one of the following: v Issue IXGQUERY, which returns the safe import point.

v Listen for ENF event 48 indicating that the safe import point has been updated,

(field IXGENFWrOffLoadSafeImportPoint in the parameter list mapped by macro IXGENF contains the latest safe import point.) The ENF is issued when an offload operation completes. Notification that the offload has completed is presented on all systems in the sysplex that have a connection to the log stream.

For example, using the example in Figure 118 again, log blocks 1-6 have been

written to log stream SOURCE1. Log blocks 1 and 2 have been offloaded to DASD log data sets, so log stream SOURCE1 starts with a safe import point of 2. As before, only blocks 1 and 2 from SYS1 are duplexed to SYS1's staging data set. Log block 3 has not yet been duplexed. The importing application has browsed log stream SOURCE 1 and seen blocks 1-6, but this time, before importing them all, it issues IXGQUERY to find that the safe import point is 2. The resource manager exit imports only log blocks 1 and 2.

When the rebuild occurs, SYS2 repopulates the new structure with log blocks 1, 2,

4, 5, and 6. Again, log block 3 is not repopulated to the rebuilt structure because the data was not committed to the staging data sets. When the browsing

Chapter 27. Using system logger services

505

application is informed of the rebuild via ENF event (bit

IXGENFStrRebuildComplete is on in the parameter list mapped by macro IXGENF) it should then do the following to keep the target log stream synchronized with source log stream SOURCE1: v Issue IXGQUERY for the new safe import point. Let's say the new safe import point is 6.

v Browse log stream SOURCE1 from the last safe import point it knew about (2) to the new safe import point (6). After the rebuild, SOURCE1 contains 4, 5, and 6.

v Import log blocks 4, 5, and 6 to TARGET1.

The end result is that both SOURCE1 and TARGET1 match, containing log blocks

1, 2, 4, 5, and 6.

Note that an application can also try to change the safe import point by initiating an offload using the IXGOFFLD service.

DASD-only log streams and the safe import point

For a DASD-only log stream data is duplexed to DASD staging data sets as it is written to the log stream. This means that the chance of losing data because of a system failure is far less; There is no lag time between a successful write and hardening of the data on DASD. And of course, a coupling facility failure will not affect a DASD-only log stream. However, it can be helpful for an application to use the IXGQUERY service to ensure that log data is safe to import from a DASD-only source log stream. For a DASD-only log stream, the safe import point is the highest log block identifier that has been successfully written to the log stream. The safe import point for a DASD-only is updated with each successful write, because the log data is simultaneously duplexed to DASD staging data sets. Any log blocks in the source log stream with a block identifier less than or equal to the safe import point can be safely imported to the target log stream. An application can determine the safe import point by doing one of the following: v Issue IXGQUERY, which returns the safe import point.

v Listen for ENF event 48 indicating that the safe import point has been updated,

(field IXGENFWrOffLoadSafeImportPoint in the parameter list mapped by macro IXGENF contains the latest safe import point.) The ENF is issued when an offload operation completes. Notification that the offload has completed is presented on all systems in the sysplex that have a connection to the log stream.

The coupling facility list structure version number

The buffer returned by IXGQUERY (IXGQBUF) contains a version number. The meaning varies for DASD-only and coupling facility log streams, but the value is returned in field QBUF_STRUCT_VERSION_NUMBER for both. An alternate name for the field is QBUF_INSTANCE_VERSION_NUMBER.

For a DASD-only log stream

, the version number is the time stamp in STCK format when the staging data set for the DASD-only log stream was created.

For a coupling facility log stream

, the version number is the coupling facility list structure version number. This value shows the list structure version number of the coupling facility structure assigned to the log stream. A version number is assigned when a structure is initially allocated in the coupling facility and increases every time a structure is rebuilt or reallocated.

506

z/OS MVS Assembler Services Guide

Using the coupling facility version number

The coupling facility list structure version number returned for coupling facility log streams is helpful in situations where a rebuild occurs while the resource manager responsible for gathering data for a log stream was inactive at the time of the rebuild. A browsing application can tell if a rebuild has occurred since it was last connected by checking to see if the coupling facility list structure version number has increased since the last browse session. If a browsing application connects to a log stream and issues IXGQUERY to find that the version number has increased, it should then begin browsing from the last valid safe import point it knew about for the most up to date version of the log stream contents.

For example, imagine an application browses log blocks 1 through 6 in a source log stream in anticipation of importing them. Before importing the log blocks to the target log stream, the application checks for the safe import point using

IXGQUERY and imports only blocks 1 and 2. Then, the browsing application is cancelled or fails and disconnects from the log stream, saving the current coupling facility list structure version number and safe import point it knows about (2).

A rebuild then occurs and the new content of the source log stream consists of 1, 2,

4, 5, and 6. The browsing application then reconnects to the log stream and issues

IXGQUERY for the new list structure version number and safe import point. Since a rebuild has occurred, the version number will have increased. The browsing application begins browsing again from the last safe import point (2) to the new safe import point (6), and only imports log blocks 4, 5, and 6.

IXGOFFLD: Initiate offload to DASD log data sets

Use the IXGOFFLD service to initiate an offload of log data to DASD log data sets.

For coupling facility log streams

log data is offloaded from the coupling facility structure associated with a log stream to DASD log data sets. Because offloading hardens log data on DASD log data sets, it updates the safe import point for a log stream. You can use IXGOFFLD to initiate an offload on a source log stream to increase the safe import point. This makes more log data available for safe import from the source to the target log stream.

For DASD-only log streams

log data is offloaded from local storage buffers to

DASD log data sets. Offloading does not update the safe import point, because for

DASD-only log streams, when an IXGWRITE service is issued to write data to local storage buffer, the log data is automatically hardened on DASD staging data sets at the same time. For DASD-only log streams, the safe import point is updated after every successful write request.

The number of off-loads initiated via IXGOFFLD are tracked in a field in SMF record 88.

You must be in task mode to issue the IXGOFFLD service or else the request is rejected.

Managing a target log stream: Using IXGIMPRT, IXGOFFLD, and IXGQUERY together

An application managing a target log stream can monitor the offloads occurring on the source log stream via ENF event 48 writer offload completion events as an indication of when there will be more data to import (IXGIMPRT) to the target log

Chapter 27. Using system logger services

507

stream. But the application must also check the safe import point of the source log stream. The application can do this in one of two ways: v

Listen for ENF event 48, notifying them of a change to the safe import point

(field IXGENFWrOffLoadSafeImportPoint in the parameter list mapped by macro IXGENF contains the latest safe import point).

v

Issuing the IXGQUERY service (see “The safe import point: Using IXGQUERY and IXGIMPRT together” on page 504) to verify that the data is safe to import to

the target log stream.

You must verify the safe import point because it is not always updated for an

IXGOFFLD initiated offload even though the safe import point is tied to offloading. This is true because of the way system logger manages log data set control intervals that are not yet full.

IXGUPDAT: Modify log stream control information

Use the IXGUPDAT service to modify the UTC time stamp control information for a log stream. Once modified, the next log block written to the log stream will be assigned a UTC time stamp equal to or greater than the one specified on the

IXGUPDAT request.

For coupling facility log streams

, the time stamp for a log stream maintained in the coupling facility list controls.

For DASD-only log streams

, the time stamp for a log stream maintained in the local control blocks for the system associated with the log stream and the staging data set control records.

On the IXGUPDAT service, you must supply a time stamp that is equal to or greater than the current time stamp maintained in the Log Stream Control information. You can obtain the current time stamp for the log stream by issuing the IXGQUERY service.

You must be in task mode to issue the IXGUPDAT service or else the request is rejected. The program issuing IXGUPDAT must also have specified AUTH=WRITE on the IXGCONN request to connect to the log stream to issue this request.

Why would I need to change a time stamp on a log stream? The IXGUPDAT service is useful mainly to coupling facility log streams. If an application writes to multiple coupling facility log streams at the time of a failure necessitating recovery processing, database recovery processing truncates the log streams to the latest point consistent across all the log streams. This can mean a loss of data. For example, let's say an application writes to two log streams. In log stream 1, the last log block written was at 9 A.M.. In log stream 2, the last log block was written at

9:15 A.M.. The recovery process logically truncates log stream 2 data to 9 A.M., to be consistent with log stream 1 for recovery. This means that the data written to log stream 2 between 9:00 and 9:15 is lost.

In this situation, you would use IXGUPDAT to update the time stamp for log stream 1 to 9:15 or greater so that all data for both log streams can be recovered.

All data written to the two log streams up until 9:15 A.M can then be recovered.

IXGUPDAT lets you advance the time stamp for a log stream or streams to the latest time among all the log streams. This ensures that log streams have a consistent time stamp and include all the data written to any of the log streams.

508

z/OS MVS Assembler Services Guide

Rebuilds and IXGUPDAT processing

For a coupling facility log stream, when a rebuild occurs after you update a time stamp using IXGUPDAT, the time stamp for the log stream will be set for the time of the last log block written and recovered to the log stream. This will be the last log block written, unless rebuild processing indicates a loss of data condition for the log stream.

If the rebuild occurs after one or more successful write requests have occurred since the IXGUPDAT request, the time stamp is reset for the last post-IXGUPDAT written and recovered log block time stamp. If however, the rebuild occurs before any write requests to the log stream since the IXGUPDAT request, the time stamp for the log stream reverts to the last pre-IXGUPDAT written and recovered write request.

Setting up the system logger configuration

v To set up a system logger configuration for a logging function or application, see see the chapter on planning for system logger functions in z/OS MVS Setting Up

a Sysplex.

v For system logger applications, IBM recommends that you use ENF event code

48 and write an ENF event code 48 listen exit. See the topic on Writing an ENF event 48 listen exit in the z/OS MVS Programming: Authorized Assembler Services

Guide.

Reading data from log streams in data set format

There are two ways that you can read data from log streams: v Write a new application to read data that supports the log stream data format

using the system logger services, particularly IXGBRWSE. See “IXGBRWSE:

Browsing/reading a log stream” on page 495.

v Use the LOGR subsystem to access log stream data in data set format for existing applications that need to read log data but do not support the log stream format.

This information describes how to use the LOGR subsystem to access log stream data in data set format. For example, you might have existing applications that read logrec data in data set format. The LOGR subsystem interface allows you to use your existing applications to read log stream output without having to re-write them.

Is my application eligible for the LOGR subsystem?

You can use the LOGR subsystem to access log stream data for programs that conform to the following: v Use only BSAM or QSAM access methods .

v Use only record lengths allowed by QSAM or BSAM in the log stream .

QSAM and BSAM access methods support up to approximately 32K record sizes while a log stream can use a record size up to 64K-4. Make sure that the log stream uses a record size compatible with the access method if you want to use the LOGR subsystem to read log stream data. See z/OS DFSMS Macro

Instructions for Data Sets for more information about access methods.

v Use only the following macros to access data:

– DCB

– DCBE

Chapter 27. Using system logger services

509

– RDJFCB

– OPEN

– GET (QSAM)

– READ (BSAM)

– CHECK (BSAM)

– TRUNC (BSAM)

– SYNADAF

– SYNADRLS

– CLOSE

Your program is NOT eligible for use with the LOGR subsystem if it uses the

NOTE, POINT, and CNTRL macros.

Preparing to use the LOGR subsystem

If you want to use the LOGR subsystem to read log stream data in data set format, make sure of the following: v The LOGR subsystem must be activated on each system where you expect to use it.

Note that you cannot use either the SETSSI ACTIVATE or SETSSI DEACTIVATE command to activate or deactivate the LOGR subsystem. See the chapter on system logger functions in z/OS MVS Setting Up a Sysplex.

Each system must have LOGR defined as a subsystem on the SUBSYS statement in the job that runs the subsystem.

v The log stream owner must supply an exit that generates a view of its log data.

You can use this to ensure that the new application program is written with the correct data format in mind. See z/OS MVS Programming: Assembler Services

Guide.

v The system where the new log data reading application runs on must be in the same sysplex as the log stream.

v The application must have the appropriate SAF authority (READ/WRITE) to the log stream, SAF CLASS(LOGSTRM) RESOURCE(log_stream_name).

If there is no log stream class defined to a security product such as RACF, no access checking is performed.

v Make sure the LOGR subsystem is activated.

References:

v See the chapter on planning for system logger functions in z/OS MVS Setting Up

a Sysplex.

v See z/OS MVS Initialization and Tuning Reference for information about the

IEFSSNxx parmlib member.

v See z/OS MVS System Commands for information about the SETSSI command.

v See z/OS MVS Installation Exits for information about the LOGR subsystem exit.

Using the LOGR subsystem

Do the following to use the LOGR subsystem:

1.

Obtain the following information from the log stream owner: v Name of the log stream.

v

Name of the exit routine.

510

z/OS MVS Assembler Services Guide

|

|

|

2.

Add the exit routine and log stream data to the JCL used to invoke the

application using the SUBSYS statement. See “JCL for the LOGR Subsystem.”

3.

Make sure the LOGR subsystem has been activated. See “Preparing to use the

LOGR subsystem” on page 510.

JCL for the LOGR Subsystem

Use the SUBSYS parameter to call the log stream subsystem (LOGR) to access log stream data.

//ddname

DD

DSNAME=log.stream.name,

//

SUBSYS=(LOGR[,exit_routine_name][,’SUBSYS-options1’][,’SUBSYS-options2’]) where:SUBSYS-options1:

[FROM={({[yyyy/ddd][,hh:mm[:ss]]})

| OLDEST}]

[TO={({[yyyy/ddd][,hh:mm[:ss]]})

| YOUNGEST}]

[,DURATION=(nnnn,HOURS)]

[,VIEW={ACTIVE|ALL|INACTIVE}]

[,GMT|LOCAL] SUBSYS-options2: defined by the log stream owner

Note:

Quotation marks around keywords are required when parentheses, commas, equal signs, or blank characters are used within the SUBSYS keyword.

Other DD keywords are validated, if specified, but are ignored in the LOGR subsystem processing.

DSNAME=log.stream.name

Specifies the name of the log stream to read. The name can be 1 to 26 characters in a data-set-name format.

SUBSYS=(LOGR[,exit_routine_name][,'SUBSYS-options1'][,'SUBSYS-options2'])

Specifies that processing of this DD is to be handled by the LOGR subsystem.

The exit_routine_name is the second positional parameter and specifies the name of the exit routine to receive control from the LOGR subsystem.

Note:

Contact your installation system programmer to ensure your

exit_routine_name can be used as a log stream subsystem exit routine. See

Authorization for system logger applications in z/OS MVS Setting Up a Sysplex v Specify or use the default value to IXGSEXIT to use the log stream subsystem exit routine.

v Specify IFBSEXIT to access records from the logrec log stream. See

SUBSYS-options2 for logrec-specific parameters.

v Specify IFASEXIT to access records from SMF log streams. See

SUBSYS-options2 for SMF-specific parameters.

SUBSYS-options1

Specifies options that are meaningful to all exit routines. See the documentation for a specific log stream exit for exceptions to these common options. The keywords are:

FROM=starting_time

Indicates the starting time of the first log stream block to be processed based on the log stream view that the VIEW keyword specifies. The first block is the one with a time stamp later than or equal to the specified time.

OLDEST

Indicates the first block read is the oldest block on the log stream.

OLDEST is the default.

Chapter 27. Using system logger services

511

yyyy/ddd

Specifies the start date. If the date is omitted, the current date is assumed. yyyy is a 4-digit year number and ddd is a 3-digit day number from 001 through 366 (366 is valid only on leap years). For example, code February 20, 2000 as 2000/051, and code December 31,

1996 as 1996/366.

hh:mm[:ss]

Specifies the start time. If the time is omitted, the first block written after midnight is used. hh is a 2–digit hour number from 00 to 23, mm is a two digit minute number from 00 to 59, and ss is a 2–digit second number from 00 to 59. The seconds field and associated : delimiter can be omitted if it is not required by the log stream owner.

The FROM keyword is mutually exclusive with the DURATION keyword.

TO=ending_time

Indicates the ending time of the last log stream block to be processed based on the log stream view that the VIEW keyword specifies. The last block is the one with a time stamp earlier than or equal to the specified time.

YOUNGEST

Indicates the last block read will be the youngest block on the log stream at the time the allocation for the DD occurs. YOUNGEST is the default.

yyyy/ddd

Specifies the end date. If the date is omitted, the current date is assumed. yyyy is a 4-digit year number and ddd is a 3-digit day number from 001 through 366 (366 is valid only on leap years). For example, code March 7, 2001 as 2001/066, and code November 12, 2000 as 2000/317.

hh:mm[:ss]

Specifies the end time. If the time is omitted, the last block written before midnight will be used. If the end date is the same as the current day, then the youngest block on the log stream at the time the allocation for the DD occurs will be used. hh is a 2–digit hour number from 00 to 23, mm is a two digit minute number from 00 to 59, and ss is a 2–digit second number from 00 to 59. The seconds field and associated: delimiter can be omitted if it is not required by the log stream owner.

The TO keyword is mutually exclusive with the DURATION keyword.

Note:

If the value specified for the FROM keyword is greater than the value specified for the TO keyword, the system ends the jobstep with a

JCL error.

DURATION=(nnnn,HOURS)

Specifies which blocks are to be processed. Each n is a numeric from 0 to 9.

Specifying (nnnn,HOURS) requests the blocks for the last nnnn hours up to the youngest block that is to be processed based on the log stream view that the VIEW keyword specifies. The last nnnn hours are calculated from the current time of the allocation for the DD.

512

z/OS MVS Assembler Services Guide

The first block is the one with a time stamp greater than or equal to the calculated start time. The last block read is the youngest block on the log stream at the time the allocation for the DD occurs.

The DURATION keyword is mutually exclusive with the TO and the

FROM keywords.

VIEW=ACTIVE|ALL|INACTIVE

Specifies the view or portion of log data to be used to obtain records from the log stream. System logger maintains two kinds of log stream data in a log stream: an active portion and an inactive portion. The active portion of the log stream is the log data that the log stream owner has not logically deleted through an IXGDELET request. The inactive portion of the log stream is the log data that the log stream owner has logically deleted but that has not yet been physically deleted from the log stream because the retention period (RETPD) specified for the log stream has not yet expired.

The VIEW option designates the portion(s) of the log stream to be used to obtain log data from the log stream, in addition to applying the other parameters.

Because the other parameters also apply, the combination of the FROM,

TO, or DURATION parameters and the VIEW parameter might mean that the log stream subsystem exit returns no log data or only a portion of the intended log data. For example, if FROM=starting_time and

VIEW=INACTIVE are both specified, and the starting_time is later

(younger) than the log data in the inactive portion of the log stream, then there is no log data to meet the access criteria. In the same way, if

TO=ending_time and VIEW=ACTIVE are both specified, and the ending_time is earlier (older) than the log data in the active portion of the log stream, then there is no log data to meet the access criteria.

ACTIVE

The view of the log stream is to include only active log data, in addition to applying the other log stream access parameters. ACTIVE is the default.

ALL

The view of the log stream is to include both active and inactive log data, in addition to applying the other log stream access parameters.

INACTIVE

The view of the log stream is to include only the inactive log data, in addition to applying the other log stream access parameters.

GMT|LOCAL

Specifies whether the time is local time (based on the time zone offset at the time the log was written) or GMT time. GMT is the default.

SUBSYS-options2

Specifies unique exit routine options. See the following: v For information about obtaining records from the logrec log stream, see z/OS

MVS Diagnosis: Tools and Service Aids.

v For information about obtaining records from SMF log streams, see Using

SMF log streams in z/OS MVS System Management Facilities (SMF).

LOGR SUBSYS dynamic allocation considerations

Dynamic allocation (SVC99) can also be used to allocate a LOGR SUBSYS DD for accessing log stream data.

Chapter 27. Using system logger services

513

Refer to the information in z/OS MVS Programming: Authorized Assembler Services

Guide dealing with the SVC 99 parameter list for details about using dynamic allocation.

IBM recommends using, at minimum, the following text unit keys:

DALDDNAM

DDNAME

DALDSNAM

DSNAME - log stream name

DALSTATS

Data set status - SHR

DALRECFM

Record format (RECFM)

DALBLKSZ

Block size (BLKSIZE)

DALSSNM

Subsystem name - LOGR

DALSSPRM

Subsystem parameters: exit name, SUBSYS-options 1, SUBSYS-options 2

The following examples show how to code the text units related to the LOGR

SUBSYS options. The text unit key is identified followed by an example of the

EBCDIC characters that would be used for the particular example. The text units would need to be coded as required by the Dynamic Allocation processing. Note that spaces between the characters is for readability purposes.

Subsystem Name Request Specification - Key = '005F'

Example:

To request subsystem LOGR, code:

KEY # LEN PARM

005F 0001 0004 D3 D6 C7 D9

Subsystem Parameter Specification - Key = '0060'

To specify these three parameters for the LOGR subsystem

IFBSEXIT,'FROM=OLDEST,TO=YOUNGEST',DEVICESTATS, code:

Example 1:

KEY # LEN PARM

0060 0003 0008 C9 C6 C2 E2 C5 E7 C9 E3

LEN PARM

0017 C6 D9 D6 D4 7E D6 D3 C4 C5 E2 E3

6B E3 D6 7E E8 D6 E4 D5 C7 C5 E2 E3

LEN PARM

000B C4 C5 E5 C9 C3 C5 E2 E3 C1 E3 E2

Example 2:

Here are a few examples of how to code the SUBSYS parameters when reading CICS

® log streams.

Assume the corresponding JCL DD options are desired (ignoring the JCL column alignment) and the Subsystem name text unit (key = '005F') is also coded as shown earlier.

514

z/OS MVS Assembler Services Guide

a

SUBSYS=(LOGR,DFHLG520,"FROM=(1998/350,12:00:00),GMT",

COMPAT41)

KEY # LEN PARM

0060 0003 0008 C4 C6 C8 D3 C7 F5 F2 F0

LEN PARM

001C C6 D9 D6 D4 7E 4D F1 F9 F9 F8 61 F3 F5 F0

6B F1 F2 7A F0 F0 7A F0 F0 5D 6B C7 D4 E3

LEN PARM

0008 C3 D6 D4 D7 C1 E3 F4 F1 b.

SUBSYS=(LOGR,DFHLGCNV,"FROM=(1998/287,00:00:00),

TO=(1998/287,17:30:00),LOCAL’,DELETE)

KEY # LEN PARM

0060 0003 0008 C4 C6 C8 D3 C7 C3 D5 E5

LEN PARM

0035 C6 D9 D6 D4 7E 4D F1 F9 F9 F8 61 F2 F8 F7

6B F0 F0 7A F0 F0 7A F0 F0 5D 6B E3 D6

7E 4D F1 F9 F9 F8 61 F2 F8 F7 6B F1 F7

7A F3 F0 7A F0 F0 5D 6B D3 D6 C3 C1 D3

LEN PARM

0006 C4 C5 D3 C5 E3 C5 c.

SUBSYS=(LOGR,DFHLG520,,LASTRUN)

KEY # LEN PARM

0060 0003 0008 C4 C6 C8 D3 C7 F5 F2 F0

LEN PARM LEN PARM

0000 0007 D3 C1 E2 E3 D9 E4 D5

When things go wrong — Recovery scenarios for system logger

This information describes some of the failures that can affect system logger applications and the action taken by system logger in response.

System logger performs recovery differently for DASD-only versus coupling facility log streams. Recovery for DASD-only log streams need to be done by the application. Therefore, most of the information applies to coupling facility log

streams only. For DASD-only log streams, see “Recovery performed for DASD-only log streams” on page 516. Other recovery information pertinent to DASD-only log

streams are noted under each of the following topics.

For many of the failures, an application can listen for an ENF 48 event to find out when problems are resolved or resources are available again.

Note:

The following topic has moved to When a resource manager fails in z/OS

MVS Programming: Authorized Assembler Services Guide.

When a system logger application fails

If a system logger application fails while holding active connections to one or more log streams, system logger automatically disconnects the application from the log streams.

Chapter 27. Using system logger services

515

If the connection was the last connection to a log stream from a system, all log data written by that system to the log stream is offloaded to DASD log data sets.

When an MVS system or sysplex fails

This information applies to coupling facility log streams only; for DASD-only log

streams, see “Recovery performed for DASD-only log streams.”

When a system fails, system logger tries to safeguard all the coupling facility log data for the failed system by offloading it to DASD log data sets so that it is on a persistent media.

Recovery processing for the failing system is done by a peer connector, which is another system in the sysplex with a connection to a coupling facility structure that the failing system was also connected to. Note that a peer connector need only be connected to the same coupling facility structure, not the same log stream. See the chapter on planning for system logger functions in z/OS MVS Setting Up a Sysplex for more information.

When all the systems in a sysplex fail, there are no peer connectors to perform the recovery processing for the failing systems, which would consist of offloading the coupling facility data for log streams to DASD log data sets. Coupling facility resident log data continues to exist. Further recovery processing depends on whether or not the coupling facility also failed.

Recovery performed for DASD-only log streams

Like a coupling facility log stream, a DASD-only log stream is subject to system or system logger failure. A DASD-only log stream is not subject, however, to coupling facility or structure failures. When a failure occurs involving a DASD-only log stream, system logger releases the exclusive ENQ on the log stream name serializing the log stream for one system. No system-level or peer recovery is performed for a DASD-only log stream after a failure or as part of system initialization. System logger does not perform system-level recovery for a

DASD-only log stream because data is already safeguarded on DASD staging data sets, a non-volatile medium. For a DASD-only log stream, offload of log data to

DASD log data sets is not done as part of recovery processing for the same reason

- log data is already on DASD staging data sets. Peer recovery is both unnecessary and not possible for a DASD-only log stream, because there are no peer systems connected to the log stream.

Recovery for a DASD-only log stream only takes place when an application reconnects to the log stream. As part of connect processing, system logger reads log data from the staging data set (associated with the last connection to the log stream) into the local storage buffers of the current connecting system. This allows the application to control recovery, by selecting which system they wish to have reconnect to the log stream and when. Note that for another system to connect to the log stream and perform recovery, the staging data sets must reside on devices accessible by both systems.

When the system logger address space fails

This information applies to both coupling facility and DASD-only log streams.

516

z/OS MVS Assembler Services Guide

If the system logger address space fails, any system logger requests from the system where the system logger component failed are rejected. See z/OS MVS

Programming: Assembler Services Reference IAR-XCT for information on system logger services.

When the coupling facility structure fails

This information applies to coupling facility log streams only.

The following coupling facility problems can occur, resulting in rebuild processing for the structure: v Damage to or failure of the coupling facility structure.

v Loss of connectivity to a coupling facility.

v A coupling facility becomes volatile.

For complete information on rebuild processing, see z/OS MVS Programming:

Sysplex Services Guide.

Damage to or failure of the coupling facility structure

If a coupling facility fails or is damaged, all systems connected to the coupling facility structure detect the failure. The first system whose system logger component detects the failure initiates the structure rebuild process. The structure rebuild process results in the recovery of one or more of the affected coupling facility structure's log streams. All the systems in the sysplex that are connected to the list structure participate in the process of rebuilding the log streams in a new coupling facility list structure.

When the rebuild starts, system logger issues an event 48 signal to inform applications that the rebuild is starting and that the log streams associated to the coupling facility structure that is being rebuilt are not available. Bits

IXGENFStrRebuildStart and IXGENFLogStreamsNotAvailable are on in the event

48 parameter list mapped by macro IXGENF.

While the rebuild is in progress, system logger rejects any system logger service requests against the log stream. Applications must listen for another ENF event 48 to learn the status of the log stream after rebuild processing is complete. The status will be one of the following: v The structure rebuild has completed successfully, the coupling facility structure and associated log streams are available, and system logger requests will be accepted. Bits IXGENFLogStreamsAvailable and IXGENFStrRebuildComplete are on in the event 48 parameter list mapped by macro IXGENF.

v The structure rebuild was unsuccessful and connection to the structure is not possible because the structure is in a failed state. Log data still resides in staging data sets if they are used to duplex the log data for the log stream. If staging data sets were not used, the data persists in the local storage buffers on each system. All system logger service requests against the log streams will be rejected. Bits IXGENFLogStreamsNotAvailable, IXGENFStrRebuildFailed, and

IXGENFRebuildFailStrFail are on in the event 48 parameter list mapped by macro IXGENF.

In this case, applications connected to the affected log streams must wait for the structure to be rebuilt successfully and the system to issue an ENF 48 event to indicate that the log streams are available.

Chapter 27. Using system logger services

517

Loss of connectivity to the coupling facility structure

If a system loses connectivity to the coupling facility structure due to a hardware link failure, all the systems connected to the log streams associated with the coupling facility detect the failure.

Then, based on the rebuild threshold specified, if any, in the structure definition in the CFRM policy, the system that lost connectivity may initiate a rebuild for the structure.

If a rebuild is initiated, the event 48 parameter list mapped by macro IXGENF has bits IXGENFLogStreamsNotAvailable, and IXGENFStrRebuildStart, on, and field

IXGENFStrName contains the name of the coupling facility structure affected.

System logger rejects logger service requests issued during the rebuild process.

If XES cannot allocate a new coupling facility that all the systems affected can connect to, system logger does one of the following, depending on whether the system or systems that cannot connect to the new coupling facility structure were using staging data sets: v If the system was using staging data sets, the rebuild process continues and the coupling facility log data for the system is recovered from the staging data sets.

v If the system was not using staging data sets, the rebuild process is stopped. The systems go back to using the source structure.

The systems that do not have connectivity to the old coupling facility structure issue an ENF 48 event indicating that they do not have connectivity to the log stream.

The systems that can connect to the source structure issue an ENF 48 event indicating that the log stream is available to that system and can resume use of the log stream.

The installation should either update the CFRM to make the new coupling facility structure available to all the systems or else fix the hardware link problem and then have the operator initiate a rebuild for the structure so that all the original systems will have connectivity.

Applications must listen for another ENF event 48 to learn the status of the log stream after rebuild processing is complete. The status will be one of the following: v The structure rebuild has completed successfully, the coupling facility structure and associated log streams are available, and system logger requests will be accepted. Bits IXGENFLogStreamsAvailable and IXGENFStrRebuildComplete are on in the event 48 parameter list mapped by macro IXGENF.

v The structure rebuild was unsuccessful. Connections to the structure are not available because the system receiving the ENF event code has lost connectivity to the structure.

All system logger service requests against the log streams will be rejected. Bits

IXGENFLogStreamsNotAvailable, IXGENFStrRebuildFailed, and

IXGENFRebuildFailLossConn are on in the event 48 parameter list mapped by macro IXGENF.

A coupling facility becomes volatile

If a coupling facility changes to the volatile state, the system logger on each system using the coupling facility structure is notified. A dynamic rebuild of the structure is initiated so that the log data can be moved to a non-volatile coupling facility.

During rebuild processing, system logger rejects any logger service requests.

518

z/OS MVS Assembler Services Guide

If there is not a structure available in a non-volatile coupling facility, system logger will still rebuild the data on a new volatile coupling facility. System logger may then change the way it duplexes coupling facility data since the volatile coupling facility constitutes a single point of failure: v For log streams defined with STG_DUPLEX=YES, system logger will begin duplexing data to staging data sets, if they were not already in use.

v For log streams defined with STG_DUPLEX=NO, system logger will keep on duplexing data to local storage buffers on each system.

When the coupling facility space for a log stream becomes full

This information applies to coupling facility log streams only.

Ordinarily, system logger offloads coupling facility resident log stream data to

DASD log data sets before the coupling facility storage allocated to the log stream is fully utilized. Occasionally however, the coupling facility storage allocated to a log stream reaches 100% utilization, for reasons such as a sudden burst of logging activity or because your coupling facility is sized too small for the volume of log data.

Applications are notified of a filled log stream by system logger service return code of X'08' and a reason code of IXGRsnCodeCFLogStreamStorFull (X'0860').

System logger will not accept write requests until offload processing can be completed and applications receive an ENF signal with bit

IXGENFStructureNotFull on.

When a staging data set becomes full

This information applies to both coupling facility and DASD-only log streams.

The staging data sets for each system should not fill up. If they do, you probably have them sized too small for your volume of log data and should enlarge them.

When a DASD staging data set becomes full, IXGWRITE requests from the system with a staging data set full condition will be rejected with a return code of

X'08'and a reason code of IXGRsnCodeStagingDsFull (X'0865').

System logger will immediately begin offloading log data to DASD log data sets. If your staging data set is too small, you may find that offloading occurs very frequently.

System logger will not accept write requests from the system associated with the staging data set until offload processing can be completed and applications receive an ENF signal indicating that the staging data set full condition has ended.

When a log stream is damaged

This information applies to both coupling facility and DASD-only log streams.

damaged when it cannot recover log data from either DASD staging data sets or the local storage buffers after a system, sysplex, or coupling facility failure.

Applications are notified of the damage by the following means: v

When they issue IXGCONN, they receive return code, X'04', reason code,

IXGRsnCodePossibleLossOfData v When they issue IXGBRWSE, they receive return code, X'04', reason code,

IXGRsnCodeWarningGap

Chapter 27. Using system logger services

519

v Their listen exit detects ENF event 48.

Applications should do the following to respond to a damaged log stream condition, depending on how critical a data loss is to the application: v Applications that absolutely cannot tolerate any data loss whatsoever, some short term transaction logs for example, should stop issuing system logger services to the affected log stream, disconnect from the log stream, perform recovery for the application, and then reconnect to a new log stream.

v Applications that can tolerate some data loss, such as archive logs that do not read a great deal of data from the log stream, may be able to continue using the

log stream. See “How system logger handles gaps in the log stream” on page

475 for a summary of the results of reading a damaged log stream.

When DASD log data set space fills

This step applies to both coupling facility and DASD-only log streams.

The number of DASD log data sets available for log streams in a sysplex depends on whether you use the default (168 per log stream) or have provided additional directory extents in the LOGR couple data set.

System logger monitors usage of the available log stream directory space, notifying you as follows if you start to run out of space: v If you are using the DSEXTENT parameter in the LOGR couple data set system logger issues messages IXG261E and IXG262A indicating that usage of directory extents is over 85% and 95% respectively.

v If you are using the default number of log data sets allowed for a log stream

(168), system logger issues message IXG257I indicating that the data set directory for the log stream is over 90% full.

If you have run out of log stream directory space, offloads may fail. When this occurs, system logger issues message IXG301I. Offload processing for the log stream cannot complete until more log stream directory space or directory extents are made available. If the last disconnect to a log stream occurs and the offload cannot complete successfully, the log stream is in a failed state. In this case, the log stream is considered 'in use' and there may be a failed-persistent connection to a structure associated with the log stream.

You can make more directory space available for a log stream in one of the following ways. Use the IXCMIAPU utility to run a report of the log stream definitions in the LOGR couple data set to help you with this step. The LIST

LOGSTREAM NAME(*) DETAIL(YES) statement outputs information showing which log streams might be using large numbers of data sets and directory extents.

See LOGR keywords and parameters for the administrative data utility in z/OS

MVS Setting Up a Sysplex for more information about IXCMIAPU.

v Format another set of LOGR couple data sets with a higher DSEXTENT value and bringing them into the sysplex as the active primary and alternate LOGR couple data sets. You must have a LOGR couple data set to use the DSEXTENT parameter. See Administrative data utility in z/OS MVS Setting Up a Sysplex for the IXCL1DSU utility and the DSEXTENT parameter.

v Free directory extents currently in use in one of the following ways:

– Use a program that issues the IXGDELET service to delete enough data from the log stream to free up space in the log stream data set directory.

520

z/OS MVS Assembler Services Guide

Some products provide a program to delete log stream data. See Deleting log data and log data sets in z/OS MVS Setting Up a Sysplex for information on deletion programs provided for IBM products. See the documentation for the product to see if it provides a deletion program.

– Delete log stream definitions from the LOGR couple data set.

Identify and delete the definitions for unused or unnecessary log streams.

This will free the directory space associated with the log streams, which may free up directory extents for use by other log streams.

Note:

Deleting DASD log data sets using a non-system logger method will not work because system logger will still count the data sets toward the data set directory entry limit. You cannot, for example:

– Use a TSO/E DELETE command to delete a log data set.

– Use DFHSM to migrate log stream data sets to tape.

When unrecoverable DASD I/O errors occur

This information applies to both coupling facility and DASD-only log streams, with differences noted.

DASD I/O errors may occur against either log data sets or staging data sets.

System logger tries to recover from the error, but if it cannot, the error is characterized as an unrecoverable I/O error. See the following: v

“When unrecoverable DASD I/O errors occur during offload”

v

“When staging data set unrecoverable DASD I/O errors occur”

When unrecoverable DASD I/O errors occur during offload

DASD I/O errors may occur during offload processing, while log data is being written to DASD log data sets. When this happens, system logger tries to recover by closing the current log data set and allocating a new one. If this process fails, the I/O error is characterized as an unrecoverable I/O error.

In the case of unrecoverable I/O errors, system logger will accept subsequent

IXGWRITE requests as follows: v For a coupling facility log stream, system logger will accept IXGWRITE requests if the log stream is connected to a coupling facility where there is still room for log data. If the coupling facility is full or no coupling facility exists, system logger rejects IXGWRITE requests.

v For a DASD-only log stream, system logger will accept IXGWRITE requests until the staging data set for the system writing to the log stream is filled.

IXGBRWSE and IXGDELET requests may continue to work. I/O errors encountered in the process of completing these requests are reported to the application in return and reason codes.

To correct an unrecoverable I/O problem, delete the log stream definition in the

LOGR policy and redefine it with different log data set attributes, such as

LS_DATACLAS, in order to get the log stream data set allocated in a usable location.

When staging data set unrecoverable DASD I/O errors occur

DASD I/O errors may occur when log data is being duplexed to DASD staging data sets. When this occurs, system logger tries to recover by doing the following:

1.

Offload current log data to DASD log data sets.

Chapter 27. Using system logger services

521

2.

Delete and unallocate the staging data set.

3.

Re-allocate a new instance of the staging data set.

In the meantime, system logger continues to accept write and other requests against the log stream.

If system logger cannot re-allocate a new staging data set, the I/O error is characterized as unrecoverable. In the case of an unrecoverable staging data set

I/O error, system logger does the following: v For a coupling facility based log stream , system logger switches the duplexing mode to duplex log data to local storage buffers. The system issues message

IXG255I indicating that the duplexing mode has changed. Normal system logger processing continues. The log stream may be more vulnerable to data loss due to system, sysplex, or coupling facility failure.

v For a DASD-only log stream , system logger disconnects connectors from the log stream. The system issues message IXG216I to indicate that connectors are being disconnected because a staging data set could not be allocated.

522

z/OS MVS Assembler Services Guide