IXGBRWSE — Browse/read a log stream

Description

Use the IXGBRWSE macro to read and browse a log stream for log block information. Using IXGBRWSE, a program can read consecutive log blocks in a log stream or search for and read a specific log block in a log stream. IXGBRWSE returns the specified log block in the calling program's output buffer.

The requests for IXGBRWSE are:

REQUEST=START, which starts a browse session. A browse session is identified by a browse token which is created by the browse start request. The browse session remains active until it is ended as a result of a REQUEST=END request or the log stream has been disconnected. See REQUEST=START option of IXGBRWSE for the syntax of this request.
REQUEST=READCURSOR, which reads the next consecutive log block (or blocks) in the log stream. Use this request multiple times or use the MULTIBLOCK keyword to read consecutive blocks in a log stream. See REQUEST=READCURSOR option of IXGBRWSE for the syntax of this request.
REQUEST=READBLOCK, which reads a selected log block in a log stream. See REQUEST=READBLOCK option of IXGBRWSE for the syntax of this request.
REQUEST=RESET, which resets the browse cursor to either the beginning or the end of the log stream. See REQUEST=RESET option of IXGBRWSE for the syntax of this request.
REQUEST=END, which ends a browse session. See REQUEST=END option of IXGBRWSE for the syntax of this request.

For information about using the system logger services and the IXGBRWSE request, see z/OS MVS Programming: Assembler Services Guide, which also includes information about related macros IXGCONN, IXGINVNT, IXGWRITE, IXGDELET, and IXGQUERY.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem or Supervisor state with any PSW key. The caller must be in supervisor state with any system (0-7) PSW key to either invoke this service in SRB mode or to use the MODE=SYNCEXIT keyword.
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, HASN or SASN
AMODE:	31-bit or 64-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled for I/O and external interrupts.
Locks:	No locks held.
Control parameters:	All control parameters must be in the primary address space with the following exceptions: The ECB should be addressable from the home address space. Any parameter area that is explicitly ALET-qualified as allowed by the input parameter (for example, the area referenced by the BUFFER parameter when the BUFFALET parameter is specified) must be in an address or data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL). All storage areas specified must be in the same storage key as the caller with the following exception: Any parameter area is explicitly storage key qualified as allowed by the input parameters (example: the area referenced by the BUFFER parameter when the BUFFKEY parameter is also specified).

Programming requirements

The current primary address space must be the same primary address space used at the time your program issued the IXGCONN request.
The calling program must be connected to the log stream through the IXGCONN service with either read or write authority.
The parameter list for this service must be addressable in the caller's primary address space.
Include the IXGCON mapping macro in your program. This macro provides a list of equate symbols for the system logger services.
Include macro IXGANSAA in your program. This macro maps the format of the answer area output returned for each system logger service in the ANSAREA parameter.
For a READCURSOR browse request with the MULTIBLOCK=YES option, include the IXGBRMLT mapping macro in your program. This macro provides a mapping of the area returned by the system logger for each block that is returned in the caller's buffer. Additionally, the area pointed to by the BUFFER or BUFFER64 parameter must be on a word boundary for multiple log block READCURSOR requests.
Although the data pointed to by the BUFFER64 keyword may be above the bar (2-gigabyte), the length of the name or address of the input field specified in the BUFFLEN keyword is still limited to 4 bytes.
When coding the MODE=SYNCECB and ECB parameters, you must ensure that:
- The virtual storage area specified for the ECB resides on a fullword boundary.
- You initialize the ECB field to zero.
- The ECB resides in either common or home address space storage at the time the IXGBRWSE request is issued.
- The storage used for output parameters, such as ANSAREA, BROWSETOKEN, BUFFER, BUFFER64, ANSAREA, BLKSIZE, TIMESTAMP, and RETBLOCKID, are accessible by both the IXGBRWSE invoker and the ECB waiter.
When coding the MODE=SYNCEXIT parameter, you must ensure that the storage used for output parameters, such as ANSAREA, BROWSETOKEN, BUFFER, BUFFER64, ANSAREA, BLKSIZE, TIMESTAMP, and RETBLOCKID, are accessible by both the IXGBRWSE invoker and the completion exit routine.

Restrictions

There is more than one version of this macro available. The parameters you can use depend on the version you specify on the PLISTVER parameter. See the description of the PLISTVER parameter for more information.

You can call any of the system logger services in either AMODE 31 or 64, but the parameter list and all other data addresses, with the excption of BUFFER64 must reside in 31-bit storage.

Input register information

Before issuing the IXGBRWSE macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0: Reason code, if register 15 contains a non-zero return code
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as a work register by the system
2-13: Unchanged
14-15: Used as a work register by the system

When control returns to a caller running in AMODE 64, the 64–bit registers contain:

Register: Contents
0-1: Used as a work register by the system, if the caller specified BUFFER64. Otherwise, unchanged.
2-13: Unchanged
14: Unchanged
15: Used as a work register by the system.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

REQUEST=START option of IXGBRWSE

The IXGBRWSE macro with the REQUEST=START parameter starts a browse session and sets the starting position of the browse cursor.

Syntax for REQUEST=START

The IXGBRWSE REQUEST=START macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede IXGBRWSE.

IXGBRWSE

␢	One or more blanks must follow IXGBRWSE.

REQUEST=START

,STREAMTOKEN=`streamtoken`	`streamtoken`: RS-type address or register (2) - (12).

,BROWSETOKEN=`browsetoken`	`browsetoken`: RS-type address or register (2) - (12).

,ANSAREA=`ansarea`	`ansarea`: RS-type address or register (2) - (12).

,ANSLEN=`anslen`	`anslen`: RS-type address or register (2) - (12).

,OLDEST	Default: OLDEST
,YOUNGEST
,STARTBLOCKID=`startblockid`	`startblockid`: RS-type address or register (2) - (12).
,SEARCH=`search`	`search`: RS-type address or register (2) - (12).

GMT=YES
GMT=NO

VIEW=ACTIVE	Default: VIEW=ACTIVE
VIEW=ALL
VIEW=NO_VIEW

MODE=SYNC	Default: MODE=SYNC
MODE=SYNCECB
MODE=SYNCEXIT

,REQDATA=`reqdata`	`reqdata`: RS-type address or register (2) - (12).

,ECB=`ecb`	`ecb`: RS-type address or register (2) - (12).

,DIAG=NO_DIAG	Default: DIAG=NO_DIAG
,DIAG=NO
,DIAG=YES

,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX	Default: IMPLIED_VERSION
,PLISTVER=`plistver`

,RETCODE=`retcode`	`retcode`: RS-type address or register (2) - (12).

,RSNCODE=`rsncode`	`rsncode`: RS-type address or register (2) - (12).

,MF=S	Default: MF=S
,MF=(L,`list addr`)
,MF=(L,`list addr,attr`)
,MF=(L,`list addr`,0D)
,MF=(E,`list addr`)
,MF=(E,`list addr`,COMPLETE)
,MF=(E,`list addr`,NOCHECK)
,MF=(M,`list addr`)
,MF=(M,`list addr`,COMPLETE)
,MF=(M,`list addr`,NOCHECK)

Parameters for REQUEST=START

The parameters are explained as follows:

REQUEST=START

Requests that a browse session be started.

,STREAMTOKEN=streamtoken

Specifies the name or address (using a register) of a required 16-byte input field containing the token for the log stream that you want to browse and read. The stream token is returned by the IXGCONN service at connection to the log stream.

,BROWSETOKEN=browsetoken

Specifies the name or address (using a register) of a required 4-byte output area where a token uniquely identifying the browse session is returned by the IXGBRWSE REQUEST=START request. This browse token is then used as an input to subsequent IXGBRWSE requests to identify the browse session.

,ANSAREA=ansarea

Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.

,ANSLEN=anslen

Specifies the name (or address in a register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 40 bytes and must be the same length as the field specified in ANSAREA.

To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.

,OLDEST

,YOUNGEST

,STARTBLOCKID=startblockid

,SEARCH=search

Specifies where the cursor should be set for the start of the browse session.

OLDEST: Specifies that the block cursor be positioned at the oldest log block in the log stream.
When VIEW=ACTIVE is specified for this browse session, the cursor is positioned at the oldest active log block in the log stream. If there is no active data in the log stream, the request will fail.

When VIEW=ALL is specified, the cursor is positioned at the oldest log block in the log stream of the active and inactive data. If there is neither active nor inactive data in the log stream, the request will fail.
YOUNGEST: Specifies that the block cursor be positioned at the youngest log block in the log stream.
When VIEW=ACTIVE is specified for this browse session, the cursor is positioned at the youngest active log block in the log stream.

When VIEW=ALL is specified, the cursor is positioned at the youngest log block in the log stream, even if the youngest block is eligible for deletion.
STARTBLOCKID=startblockid: Specifies the name (or register) of a 8-byte input field containing the block identifier for the log block you want to use as the starting cursor position.
When VIEW=ALL is specified, you must specify a starting block that is active.
SEARCH=search: Specifies the name (or register) of a 64-bit input field containing the time stamp you want to use in searching for a particular log block as the starting cursor position for this browse session. For information on how the SEARCH keyword works, see z/OS MVS Programming: Assembler Services Guide.
The time stamp must be Coordinated universal time (UTC) or local time, in time of day (TOD) clock format. The GMT parameter is required with the SEARCH parameter.

,GMT=YES

,GMT=NO

Specifies whether the time stamp specified on the SEARCH parameter is UTC or local time.

GMT=YES: The time stamp specified on the SEARCH parameter is in UTC format.
GMT=NO: The time stamp specified on the SEARCH parameter is local time.

VIEW=ACTIVE

VIEW=ALL

VIEW=NO_VIEW

Specifies whether requests issued during this browse session return active data only, or both active and inactive data. Active data is data that has not been marked for deletion via the IXGDELET service. Inactive data is data that has been deleted via IXGDELET but has not been physically deleted from the log stream because of the retention period specified in the log stream definition in the LOGR couple data set.

VIEW=ACTIVE, which is the default, specifies that in this browse session, system logger will only return active data from the log stream.
VIEW=ALL specifies that in this browse session, system logger will return both active and inactive data.
When VIEW=ALL is specified and a log block is returned, system logger sets a flag in the answer area, AnsaaBlkFromInactive, indicating whether the block was active or eligible for deletion.
VIEW=NO_VIEW specifies that the default VIEW value will be used for the browse session.

The system where IXGBRWSE is issued must be IPLed for the VIEW parameter to be recognized.

,MODE=SYNC

,MODE=SYNCECB

,MODE=SYNCEXIT

Specifies that the request should be processed in one of the following ways:

MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB parameter is posted when the request completes. The ECB parameter is required with MODE=SYNCECB.
MODE=SYNCEXIT: Specifies that the request process synchronously, if possible. If the request cannot be processed synchronously, your complete exit (specified on the COMPLETEEXIT parameter on the IXGCONN request) gets control when this request completes. Control returns to the caller with a return and reason code indicating that the request is not complete. The system passes the data specified on the REQDATA parameter, if specified, to the complete exit.
When a MODE=SYNCEXIT request processes asynchronously, system logger maintains latent binds to the storage location specified by the answer area (ANSAREA) fields, and, if specified, to RETBLOCKID and TIMESTAMP.

To use this parameter, the system where the application is running must be IPLed. The application must run in supervisor state, key 0-7 to use this parameter.

,ECB=ecb

Specifies the name or address (using a register) of a 4-byte input field containing an event control block (ECB) to be posted when the request completes.

Before coding ECB, you must ensure that:

You initialize the ECB to zero.
The ECB must reside in either common storage or the home address space at the time the IXGBRWSE request is issued.
The virtual storage area specified for the ECB must reside on a fullword boundary.

,DIAG=NO_DIAG

,DIAG=NO

,DIAG=YES

Specifies whether or not the DIAG option on the IXGCONN for this logstream will be in effect for this browse session. Refer to the DIAG keyword on the IXGINVNT, IXGCONN, and IXGDELET macro services.

If you specify DIAG=NO_DIAG, which is the default, then the DIAG option on the IXGCONN for this logstream will be in effect for this browse session.

If you specify DIAG=NO, thenLogger will not take additional diagnostic action as defined in the logstream definition DIAG parameter.

If you specify DIAG=YES, then Logger will take additional diagnostic action as defined on the logstream definition DIAG parameter providing the IXGCONN connect DIAG specification allows it.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.

The values are:

IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
0, supports all parameters except those specifically referenced in higher versions.
1, supports both the following parameters and parameters from version 0:
- DIAG
- REQDATA
2, supports both the following parameters and parameters from version 0 and 1:
- MAXNUMLOGBLOCKS
- MULTIBLOCK
- RETBLOCKINFO

To code: Specify in this input parameter one of the following:

IMPLIED_VERSION
MAX
A decimal value of 0, 1 or 2

,RETCODE=retcode

Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.

,RSNCODE=rsncode

Specifies a name or address (using a register) of a 4-byte output field where the system will place the reason code. The reason code is also in general purpose register (GPR) 0, if you received a non-zero return code.

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

,MF=(E,list addr,NOCHECK)

,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be specified on the list form of the macro. IBM recommends that you always specify PLISTVER=MAX on the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.

You should use the modify and execute forms in the following order:

Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
Use MF=(E,list_addr,NOCHECK), to execute the macro.

,list addr: The name of a storage area to contain the parameters.
,attr: An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE: Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK: Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.

REQUEST=READCURSOR option of IXGBRWSE

The IXGBRWSE macro with the REQUEST=READCURSOR option allows a program to read the next consecutive log block in a log stream. Subsequent READCURSOR requests will start reading at the next consecutive block. Use this request multiple times or use the MULTIBLOCK keyword to read a series of consecutive log blocks. The direction of the browse is controlled by the program and can be changed dynamically.

READCURSOR requests are limited to reading log blocks within the range of data defined by the browse session's view. The view is controlled by the VIEW keyword on either the browse START request or the browse RESET request.

Note: REQUEST=READCURSOR reads the next consecutive log block in the log stream, but the blocks may not be in exact local time sequence. This can happen, for example, because of daylight savings time, one or more records with the same local time stamp, or multiple applications writing to the same log stream.

Syntax for REQUEST=READCURSOR

The IXGBRWSE REQUEST=READCURSOR macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede IXGBRWSE.

IXGBRWSE

␢	One or more blanks must follow IXGBRWSE.

REQUEST=READCURSOR

,STREAMTOKEN=`streamtoken`	`streamtoken`: RS-type address or register (2) - (12).

,BROWSETOKEN=`browsetoken`	`browsetoken`: RS-type address or register (2) - (12).

,BUFFER=`buffer`	`buffer`: RS-type address or register (2) - (12).
,BUFFER64=`buffer64`	`buffer64`: RS-type address or register (2) - (12).

,BUFFLEN=`bufflen`	`bufflen`: RS-type address or register (2) - (12).

,DIRECTION=OLDTOYOUNG
,DIRECTION=YOUNGTOOLD

,ANSAREA=`ansarea`	`ansarea`: RS-type address or register (2) - (12).

,ANSLEN=`anslen`	`anslen`: RS-type address or register (2) - (12).

,BUFFKEY=`buffkey`	`buffkey`: RS-type address or register (2) - (12).
	Default: PSW key of the caller

,BUFFALET=`buffalet`	`buffalet`: RS-type address or register (2) - (12).
	Default: BUFFALET=0

,BLKSIZE=`blksize`	`blksize`: RS-type address or register (2) - (12). Default: BLKSIZE=0

,MULTIBLOCK=YES
,MULTIBLOCK=NO	Default: MULTIBLOCK=NO

,RETBLOCKID=`retblockid`	`retblockid`: RS-type address or register (2) - (12). Default: NO_BLKID Note: RETBLOCKID is valid with MULTIBLOCK=NO only.

,TIMESTAMP=`timestamp`	`timestamp`: RS-type address or register (2) - (12). Default: NO_TIMESTAMP Note: TIMESTAMP is valid with MULTIBLOCK=NO only.

,RETBLOCKINFO=YES
,RETBLOCKINFO=NO	Default: NO Note: RETBLOCKINFO is valid with MULTIBLOCK=YES only.

,MAXNUMLOGBLOCKS=`maxnumlogblocks`
	`maxnumlogblocks`: RS-type address or register (2) - (12).
	Default: MAXNUMLOGBLOCKS=0 Note: MAXNUMLOGBLOCKS is valid with MULTIBLOCK=YES only.

MODE=SYNC	Default: MODE=SYNC
MODE=SYNCECB
MODE=SYNCEXIT

,ECB=`ecb`	`ecb`: RS-type address or register (2) - (12).

,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX	Default: IMPLIED_VERSION
,PLISTVER=`plistver`

,RETCODE=`retcode`	`retcode`: RS-type address or register (2) - (12).

,RSNCODE=`rsncode`	`rsncode`: RS-type address or register (2) - (12).

,MF=S	Default: MF=S
,MF=(L,`list addr`)
,MF=(L,`list addr,attr`)
,MF=(L,`list addr`,0D)
,MF=(E,`list addr`)
,MF=(E,`list addr`,COMPLETE)
,MF=(E,`list addr`,NOCHECK)
,MF=(M,`list addr`)
,MF=(M,`list addr`,COMPLETE)
,MF=(M,`list addr`,NOCHECK)

Parameters for REQUEST=READCURSOR

The parameters are explained as follows:

REQUEST=READCURSOR

Requests that a program read the next consecutive log block in the log stream, in the direction specified on the DIRECTION parameter.

,STREAMTOKEN=streamtoken

,BROWSETOKEN=browsetoken

Specifies the name or address (using a register) of a required 4-byte input field containing the identifier for the browse session which was returned on the IXGBRWSE REQUEST=START request.

,BUFFER=buffer

,BUFFER64=buffer64

Specifies the name or address (using a register) of a required output field that contains the buffer into which the log block is read.

BUFFER=buffer specifies that the location of the buffer is in 31-bit storage.
BUFFER64=buffer64 specifies that the location of the buffer is in 64-bit storage.

the BUFFER and BUFFER64 parameters are mutually exclusive.

,BUFFLEN=bufflen

Specifies the name or address (using a register) of a required 4-byte input field that contains the length of the buffer specified on the BUFFER or BUFFER64 parameter.

IXGBRWSE will return the length of the block in the BLKSIZE parameter, if specified. If you specify MULTIBLOCK=NO, you can issue IXGBRWSE with BLKSIZE specified to obtain the length of the block and then re-issue IXGBRWSE using the returned BLKSIZE value in the BUFFLEN parameter.

,DIRECTION=OLDTOYOUNG

,DIRECTION=YOUNGTOOLD

Specifies the direction that you want the cursor to move to read the next consecutive log block. Specify OLDTOYOUNG to get the next youngest block or YOUNGTOOLD to get the next oldest block.

,ANSAREA=ansarea

Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.

,ANSLEN=anslen

To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.

,BUFFKEY=buffkey

Specifies the name (or address in a register) of a 4-byte input field specifying the storage key for the buffer specified on the BUFFER or BUFFER64 parameter.

If the caller is running in problem state, the caller's PSW key and the key specified in the BUFFKEY parameter must match.

If the caller is running in supervisor state, specify any syntactically valid (0 through 15) key on the BUFFKEY parameter.

If you omit the BUFFKEY parameter, the default used is the PSW key of the caller.

,BUFFALET=buffalet

Specifies the name (or address in a register) of a 4-byte input field specifying the access list entry table (ALET) to be used to access the buffer specified on the BUFFER or BUFFER64 keyword. If the buffer is ALET-qualified, the ALET must index a valid entry on the task's dispatchable unit access list (DUAL) or specify a SCOPE=COMMON data space. An ALET that indexes the system logger PASN-AL list will not work.

The default is 0, which means that the buffer is in the calling program's primary address space.

,BLKSIZE=blksize

Specifies the name or address (using a register) of a 4-byte output field where the space used or needed in the BUFFER or BUFFER64 area is returned. When MULTIBLOCK=NO is specified and there is enough space in the buffer to return the requested log block data, the actual size of the log block is returned. When MULTIBLOCK=YES is specified and there is enough space in the buffer to return the requested log blocks, the amount of space used in the BUFFER or BUFFER64 area is returned. If the BUFFLEN value is not large enough to allow any log block data to be returned, then the BLKSIZE value will indicate the minimum amount of space necessary to return the next log block.

,MULTIBLOCK=YES

,MULTIBLOCK=NO

Specifies whether one or more than one log stream log block will be returned by the read cursor request.

MULTIBLOCK=NO indicates that only one log stream log block is to be returned.
MULTIBLOCK=YES indicates that the system logger will retrieve as many log blocks as meet the browse parameter criteria and fit into the caller's buffer.

,RETBLOCKID=retblockid

Specifies the name or address (using a register) of an 8-byte output field where the identifier or the requested log block is returned

,TIMESTAMP=timestamp

Specifies the name or address (using a register) of a 16-byte output field where the Coordinated universal time stamp and the local time stamp associated with the requested log block are returned. The UTC time stamp is first, then the local time stamp. Both time stamps are in TOD-clock format.

,RETBLOCKINFO=YES

,RETBLOCKINFO=NO

Specifies whether or not system logger should return the log blocksize, blockid, timestamps and other identification information in the caller's buffer as part of the output. Specify RETBLOCKINFO=YES to receive each log block's identification information. Specify RETBLOCKINFO=NO to only receive the information necessary to navigate the caller's buffer.

If you omit the RETBLOCKINFO parameter, RETBLOCKINFO=NO is the default.

,MAXNUMLOGBLOCKS=xmaxnumlogblocks

Specifies the name (or address in a register) of an optional fullword input that indicates the maximum number of log blocks to be returned in the buffer. When a non-zero value is specified, system logger will not return more than this requested number of log blocks, even if there are more log blocks that meet the other browse parameter criteria.

If enough room is provided in the BUFFLEN value and there are sufficient log blocks that meet the browse criteria, system logger will return the requested maximum number of log blocks.
If enough room is not provided in the BUFFLEN value, system logger will return as many log blocks as fit into the caller's buffer.
If 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.

If you omit the MAXNUMLOGBLOCKS, the default is 0.

,MODE=SYNC

,MODE=SYNCECB

,MODE=SYNCEXIT

Specifies that the request should be processed in one of the following ways:

MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB parameter is posted when the request completes. The ECB parameter is required with MODE=SYNCECB.
MODE=SYNCEXIT: Specifies that the request process synchronously, if possible. if the request cannot be processed synchronously, your complete exit (specified on the COMPLETEEXIT parameter on the IXGCONN request) gets control when this request completes. Control returns to the caller with a return and reason code indicating that the request is not complete. The system passes the data specified on the REQDATA parameter, if specified, to the complete exit.
When a MODE=SYNCEXIT request processes asynchronously, system logger maintains latent binds to the storage location specified by the answer area (ANSAREA) fields, and, if specified, to RETBLOCKID and TIMESTAMP.

To use this parameter, the system where the application is running must be IPLed. The application must run in supervisor state, key 0-7 to use this parameter.

ECB=ecb

Specifies the name or address (using a register) of a 4-byte input field that contains an event control block (ECB) to be posted when the request completes.

Before coding ECB, you must ensure that:

You initialize the ECB to zero.
The ECB must reside in either common storage or the home address space at the time the IXGBRWSE request is issued.
The virtual storage area specified for the ECB must reside on a fullword boundary.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.

The values are:

IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
0, supports all parameters except those specifically referenced in higher versions.
1, supports both the following parameters and parameters from version 0:
- DIAG
- REQDATA
2, supports both the following parameters and parameters from version 0 and 1:
- MAXNUMLOGBLOCKS
- MULTIBLOCK
- RETBLOCKINFO

To code: Specify in this input parameter one of the following:

IMPLIED_VERSION
MAX
A decimal value of 0, 1 or 2

,RETCODE=retcode

Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

,MF=(E,list addr,NOCHECK)

,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

IBM recommends that you use the modify and execute forms in the following order:

Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
Use MF=(E,list_addr,NOCHECK), to execute the macro.

,list addr: The name of a storage area to contain the parameters.
,attr: An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE: Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK: Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.

REQUEST=READBLOCK option of IXGBRWSE

The IXGBRWSE macro with the REQUEST=READBLOCK parameter allows a program to search for and read a specific log block from the log stream. The target can be defined either by the log block identifier or by a time stamp.

Syntax for REQUEST=READBLOCK

The IXGBRWSE REQUEST=READBLOCK macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede IXGBRWSE.

IXGBRWSE

␢	One or more blanks must follow IXGBRWSE.

REQUEST=READBLOCK

,STREAMTOKEN=`streamtoken`	`streamtoken`: RS-type address or register (2) - (12).

,BROWSETOKEN=`browsetoken`	`browsetoken`: RS-type address or register (2) - (12).

,BLOCKID=`blockid`	`blockid`: RS-type address or register (2) - (12).
,SEARCH=`search`	`search`: RS-type address or register (2) - (12).

,BUFFER=`buffer`	`buffer`: RS-type address or register (2) - (12).
,BUFFER64=`buffer64`	`buffer64`: RS-type address or register (2) - (12).

,BUFFLEN=`bufflen`	`bufflen`: RS-type address or register (2) - (12).

,ANSAREA=`ansarea`	`ansarea`: RS-type address or register (2) - (12).

,ANSLEN=`anslen`	`anslen`: RS-type address or register (2) - (12).

GMT=YES
GMT=NO

,BUFFKEY=`buffkey`	`buffkey`: RS-type address or register (2) - (12).
	Default: PSW key of the caller

,BUFFALET=`buffalet`	`buffalet`: RS-type address or register (2) - (12).
	Default: BUFFALET=0

,BLKSIZE=`blksize`	`blksize`: RS-type address or register (2) - (12).
	Default: BLKSIZE=0

,RETBLOCKID=`retblockid`	`retblockid`: RS-type address or register (2) - (12).
	Default: NO_BLKID

,TIMESTAMP=`timestamp`	`timestamp`: RS-type address or register (2) - (12).
	Default: NO_TIMESTAMP

MODE=SYNC	Default: MODE=SYNC
MODE=SYNCECB
MODE=SYNCEXIT

,ECB=`ecb`	`ecb`: RS-type address or register (2) - (12).

,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX	Default: IMPLIED_VERSION
,PLISTVER=`plistver`

,RETCODE=`retcode`	`retcode`: RS-type address or register (2) - (12).

,RSNCODE=`rsncode`	`rsncode`: RS-type address or register (2) - (12).

,MF=S	Default: MF=S
,MF=(L,`list addr`)
,MF=(L,`list addr,attr`)
,MF=(L,`list addr`,0D)
,MF=(E,`list addr`)
,MF=(E,`list addr`,COMPLETE)
,MF=(E,`list addr`,NOCHECK)
,MF=(M,`list addr`)
,MF=(M,`list addr`,COMPLETE)
,MF=(M,`list addr`,NOCHECK)

Parameters for REQUEST=READBLOCK

The parameters are explained as follows:

REQUEST=READBLOCK

Requests that a program read a specific block from the log stream. The target can be defined either by the log block identifier or by a time stamp.

,STREAMTOKEN=streamtoken

Specifies the name or address (using a register) of a required 16-byte input field containing the token for the log stream that you want to search. The stream token is returned by the IXGCONN service at connection to the log stream.

,BROWSETOKEN=browsetoken

Specifies the name or address (using a register) of a required 4-byte input field containing the identifier for the browse session which was returned from the IXGBRWSE REQUEST=START request.

,BLOCKID=blockid

Specifies the name or address (using a register) of an 8-byte input field that contains the block identifier of the log block you wish to read. The block identifier was returned from the IXGWRITE request.

,SEARCH=search

Specifies the name or address (using a register) of a 64-bit input field containing the time stamp for the log block you wish to search for and read. The time stamp must be Greenwich mean time or local time,

When you use a time stamp as a search criteria, IXGBRWSE searches in the oldest-to-youngest direction, searching for a log block with an exactly matching time stamp. If no exact match is found, IXGBRWSE reads the next latest (youngest) time stamp. For information on how the SEARCH keyword works, see z/OS MVS Programming: Assembler Services Guide.

The GMT parameter is required with the SEARCH parameter.

,BUFFER=buffer

,BUFFER64=buffer64

Specifies the name or address (using a register) of a required output field that contains the buffer into which the log block is read.

BUFFER=buffer specifies that the location of the buffer is in 31-bit storage.
BUFFER64=buffer64 specifies that the location of the buffer is in 64-bit storage.

the BUFFER and BUFFER64 parameters are mutually exclusive.

,BUFFLEN=bufflen

Specifies the name or address (using a register) of a required 4-byte input field that contains the length of the buffer specified on the BUFFER or BUFFER64 parameter.

IXGBRWSE will return the length of the block in the BLKSIZE parameter, if specified. You can issue IXGBRWSE with BLKSIZE specified to obtain the length of the block and then re-issue IXGBRWSE using the returned BLKSIZE value in the BUFFLEN parameter.

,ANSAREA=ansarea

Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.

,ANSLEN=anslen

To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.

,ANSLEN=anslen

Specifies the name (or register) of the 4-byte field containing the answer area length. The length of the answer area must be at least 32 bytes and must be the same length as the field specified in ANSAREA.

To ascertain the optimal answer area size, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.

,GMT=YES

,GMT=NO

Specifies whether the time stamp specified on the SEARCH parameter is in Coordinated universal time (UTC) or local time.

GMT=YES: The time stamp specified on the SEARCH parameter is in Greenwich mean time.
GMT=NO: The time stamp specified on the SEARCH parameter is local time.

,BUFFKEY=buffkey

Specifies the name (or address in a register) of a 4-byte input field specifying the storage key for the buffer specified on the BUFFERor BUFFER64 parameter.

If the caller is running in problem state, the caller's PSW key and the key specified in the BUFFKEY parameter must match.

If the caller is running in supervisor state, specify any syntactically valid (0 through 15) key on the BUFFKEY parameter.

If you omit the BUFFKEY parameter, the default used is the PSW key of the caller.

,BUFFALET=buffalet

The default is 0, which means that the buffer is in the calling program's primary address space.

,BLKSIZE=blksize

Specifies the name or address (using a register) of a 4-byte output field where the actual size of the requested log block is returned.

,RETBLOCKID=retblockid

Specifies the name or address (using a register) of a 8-byte output field where the identifier of the requested log block is returned.

,TIMESTAMP=timestamp

Specifies the name or address (using a register) of a 16-byte output field where the Coordinated universal time and local time stamps associated with the requested log block is returned. The UTC time stamp is first, then the local time stamp. Both time stamps will be in TOD-clock format.

,MODE=SYNC

,MODE=SYNCECB

,MODE=SYNCEXIT

Specifies that the request should be processed in one of the following ways:

MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB parameter is posted when the request completes. The ECB parameter is required with MODE=SYNCECB.
MODE=SYNCEXIT: Specifies that the request process synchronously, if possible. if the request cannot be processed synchronously, your complete exit (specified on the COMPLETEEXIT parameter on the IXGCONN request) gets control when this request completes. Control returns to the caller with a return and reason code indicating that the request is not complete. The system passes the data specified on the REQDATA parameter, if specified, to the complete exit.
When a MODE=SYNCEXIT request processes asynchronously, system logger maintains latent binds to the storage location specified by the answer area (ANSAREA) fields, and, if specified, to RETBLOCKID and TIMESTAMP.

To use this parameter, the system where the application is running must be IPLed. The application must run in supervisor state, key 0-7 to use this parameter.

ECB=ecb

Specifies the name or address (using a register) of a 4-byte input field that contains an event control block (ECB) to be posted when the request completes.

Before coding ECB, you must ensure that:

You initialize the ECB to zero.
The ECB must reside in either common storage or the home address space at the time the IXGBRWSE request is issued.
The virtual storage area specified for the ECB must reside on a fullword boundary.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.

The values are:

IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
0, supports all parameters except those specifically referenced in higher versions.
1, supports both the following parameters and parameters from version 0:
- DIAG
- REQDATA
2, supports both the following parameters and parameters from version 0 and 1:
- MAXNUMLOGBLOCKS
- MULTIBLOCK
- RETBLOCKINFO

To code: Specify in this input parameter one of the following:

IMPLIED_VERSION
MAX
A decimal value of 0, 1 or 2

,RETCODE=retcode

Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

,MF=(E,list addr,NOCHECK)

,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

IBM recommends that you use the modify and execute forms in the following order:

Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
Use MF=(E,list_addr,NOCHECK), to execute the macro.

,list addr: The name of a storage area to contain the parameters.
,attr: An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE: Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK: Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.

REQUEST=RESET option of IXGBRWSE

The IXGBRWSE macro with the REQUEST=RESET parameter allows a program to re-position the browse cursor to either the youngest or oldest block in the log stream.

Syntax for REQUEST=RESET

The IXGBRWSE REQUEST=RESET macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede IXGBRWSE.

IXGBRWSE

␢	One or more blanks must follow IXGBRWSE.

REQUEST=RESET

,STREAMTOKEN=`streamtoken`	`streamtoken`: RS-type address or register (2) - (12).

,BROWSETOKEN=`browsetoken`	`browsetoken`: RS-type address or register (2) - (12).

,POSITION=YOUNGEST
,POSITION=OLDEST

,ANSAREA=`ansarea`	`ansarea`: RS-type address or register (2) - (12).

,ANSLEN=`anslen`	`anslen`: RS-type address or register (2) - (12).

VIEW=ACTIVE
VIEW=ALL

MODE=SYNC	Default: MODE=SYNC
MODE=SYNCECB
MODE=SYNCEXIT

,ECB=`ecb`	`ecb`: RS-type address or register (2) - (12).

,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX	Default: IMPLIED_VERSION
,PLISTVER=`plistver`

,RETCODE=`retcode`	`retcode`: RS-type address or register (2) - (12).

,RSNCODE=`rsncode`	`rsncode`: RS-type address or register (2) - (12).

,MF=S	Default: MF=S
,MF=(L,`list addr`)
,MF=(L,`list addr,attr`)
,MF=(L,`list addr`,0D)
,MF=(E,`list addr`)
,MF=(E,`list addr`,COMPLETE)
,MF=(E,`list addr`,NOCHECK)
,MF=(M,`list addr`)
,MF=(M,`list addr`,COMPLETE)
,MF=(M,`list addr`,NOCHECK)

Parameters for REQUEST=RESET

The parameters are explained as follows:

REQUEST=RESET

Requests that the browse cursor be repositioned at either the oldest or youngest block in the log stream.

,STREAMTOKEN=streamtoken

,BROWSETOKEN=browsetoken

Specifies the name or address (using a register) of a required 4-byte input field containing the identifier for the browse session which was returned from the IXGBRWSE REQUEST=START request.

,POSITION=YOUNGEST

,POSITION=OLDEST

Specifies the cursor position desired, at either the youngest or the oldest log block in the log stream.

,ANSAREA=ansarea

Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.

,ANSLEN=anslen

To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.

,ANSLEN=anslen

To ascertain the optimal answer area size, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.

VIEW=ACTIVE

VIEW=ALL

VIEW=ACTIVE, which is the default, specifies that in this browse session, system logger will only return active data from the log stream.
VIEW=ALL specifies that in this browse session, system logger will return both active and inactive data.
When VIEW=ALL is specified and a log block is returned, system logger sets a flag in the answer area, AnsaaBlkFromInactive, indicating whether the block was active or eligible for deletion.

The system where IXGBRWSE is issued must be IPLed.

,MODE=SYNC

,MODE=SYNCECB

,MODE=SYNCEXIT

Specifies that the request should be processed in one of the following ways:

MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB parameter is posted when the request completes. The ECB parameter is required with MODE=SYNCECB.
MODE=SYNCEXIT: Specifies that the request process synchronously, if possible. if the request cannot be processed synchronously, your complete exit (specified on the COMPLETEEXIT parameter on the IXGCONN request) gets control when this request completes. Control returns to the caller with a return and reason code indicating that the request is not complete. The system passes the data specified on the REQDATA parameter, if specified, to the complete exit.
When a MODE=SYNCEXIT request processes asynchronously, system logger maintains latent binds to the storage location specified by the answer area (ANSAREA) fields, and, if specified, to RETBLOCKID and TIMESTAMP.

To use this parameter, the system where the application is running must be IPLed. The application must run in supervisor state, key 0-7 to use this parameter.

ECB=ecb

Specifies the name or address (using a register) of a 4-byte input field that contains an event control block (ECB) to be posted when the request completes.

Before coding ECB, you must ensure that:

You initialize the ECB to zero.
The ECB must reside in either common storage or the home address space at the time the IXGBRWSE request is issued.
The virtual storage area specified for the ECB must reside on a fullword boundary.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.

The values are:

IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
0, supports all parameters except those specifically referenced in higher versions.
1, supports both the following parameters and parameters from version 0:
- DIAG
- REQDATA
2, supports both the following parameters and parameters from version 0 and 1:
- MAXNUMLOGBLOCKS
- MULTIBLOCK
- RETBLOCKINFO

To code: Specify in this input parameter one of the following:

IMPLIED_VERSION
MAX
A decimal value of 0, 1 or 2

,RETCODE=retcode

Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

,MF=(E,list addr,NOCHECK)

,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

IBM recommends that you use the modify and execute forms in the following order:

Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
Use MF=(E,list_addr,NOCHECK), to execute the macro.

,list addr: The name of a storage area to contain the parameters.
,attr: An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE: Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK: Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.

REQUEST=END option of IXGBRWSE

The IXGBRWSE macro with the REQUEST=END parameter ends the browse session begun with the REQUEST=START parameter.

Syntax for REQUEST=END

The IXGBRWSE REQUEST=END macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede IXGBRWSE.

IXGBRWSE

␢	One or more blanks must follow IXGBRWSE.

REQUEST=END

,STREAMTOKEN=`streamtoken`	`streamtoken`: RS-type address or register (2) - (12).

,BROWSETOKEN=`browsetoken`	`browsetoken`: RS-type address or register (2) - (12).

,ANSAREA=`ansarea`	`ansarea`: RS-type address or register (2) - (12).

,ANSLEN=`anslen`	`anslen`: RS-type address or register (2) - (12).

MODE=SYNC	Default: MODE=SYNC
MODE=SYNCECB
MODE=SYNCEXIT

,ECB=`ecb`	`ecb`: RS-type address or register (2) - (12).

,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX	Default: IMPLIED_VERSION
,PLISTVER=`plistver`

,RETCODE=`retcode`	`retcode`: RS-type address or register (2) - (12).

,RSNCODE=`rsncode`	`rsncode`: RS-type address or register (2) - (12).

,MF=S	Default: MF=S
,MF=(L,`list addr`)
,MF=(L,`list addr,attr`)
,MF=(L,`list addr`,0D)
,MF=(E,`list addr`)
,MF=(E,`list addr`,COMPLETE)
,MF=(E,`list addr`,NOCHECK)
,MF=(M,`list addr`)
,MF=(M,`list addr`,COMPLETE)
,MF=(M,`list addr`,NOCHECK)

Parameters for REQUEST=END

The parameters are explained as follows:

REQUEST=END

Requests that the browse session be ended.

,STREAMTOKEN=streamtoken

,BROWSETOKEN=browsetoken

Specifies the name or address (using a register) of a required 4-byte input field containing the identifier for the browse session which was returned from the IXGBRWSE REQUEST=START request.

,ANSAREA=ansarea

Specifies the name (or address in a register) of an answer area containing information about this request. The answer area must be at least 40 bytes. To map this information, use the IXGANSAA macro.

,ANSLEN=anslen

To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.

,MODE=SYNC

,MODE=SYNCECB

,MODE=SYNCEXIT

Specifies that the request should be processed in one of the following ways:

MODE=SYNC: Specifies that the request process synchronously. Control is not returned to the caller until request processing is complete. If necessary, the calling program will be suspended until the request completes.
MODE=SYNCECB: Specifies that the request process synchronously if possible. If the request processes asynchronously, control returns to the caller before the request completes and the event control block (ECB) specified on the ECB parameter is posted when the request completes. The ECB parameter is required with MODE=SYNCECB.
When a MODE=SYNCECB request processes asynchronously, system logger maintains latent binds to the storage location specified by the answer area (ANSAREA) fields, and, if specified, to BUFFER, BUFFER64, RETBLOCKID, TIMESTAMP, and BLKSIZE.
MODE=SYNCEXIT: Specifies that the request process synchronously, if possible. if the request cannot be processed synchronously, your complete exit (specified on the COMPLETEEXIT parameter on the IXGCONN request) gets control when this request completes. Control returns to the caller with a return and reason code indicating that the request is not complete. The system passes the data specified on the REQDATA parameter, if specified, to the complete exit.
When a MODE=SYNCEXIT request processes asynchronously, system logger maintains latent binds to the storage location specified by the answer area (ANSAREA) fields, and, if specified, to BUFFER, BUFFER64, RETBLOCKID, TIMESTAMP, and BLKSIZE.

To use this parameter, the system where the application is running must be IPLed. The application must run in supervisor state, key 0-7 to use this parameter.

ECB=ecb

Specifies the name or address (using a register) of a 4-byte input field that contains an event control block (ECB) to be posted when the request completes.

Before coding ECB, you must ensure that:

You initialize the ECB to zero.
The ECB must reside in either common storage or the home address space at the time the IXGBRWSE request is issued.
The virtual storage area specified for the ECB must reside on a fullword boundary.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates.

The values are:

IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default. Note that on the list form, the default will cause the smallest parameter list to be created.
MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form when both forms are assembled using the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
0, supports all parameters except those specifically referenced in higher versions.
1, supports both the following parameters and parameters from version 0:
- DIAG
- REQDATA
2, supports both the following parameters and parameters from version 0 and 1:
- MAXNUMLOGBLOCKS
- MULTIBLOCK
- RETBLOCKINFO

To code: Specify in this input parameter one of the following:

IMPLIED_VERSION
MAX
A decimal value of 0, 1 or 2

,RETCODE=retcode

Specifies a name or address (using a register) of a 4-byte output field where the system will place the return code. The return code is also in general purpose register (GPR) 15.

,RSNCODE=rsncode

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

,MF=(E,list addr,NOCHECK)

,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

IBM recommends that you use the modify and execute forms in the following order:

Use MF=(M,list_addr,COMPLETE), specifying appropriate parameters, including all required ones.
Use MF=(M,list_addr,NOCHECK), specifying the parameters you want to change.
Use MF=(E,list_addr,NOCHECK), to execute the macro.

,list addr: The name of a storage area to contain the parameters.
,attr: An optional 1- to 60-character input string, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE: Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK: Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.

ABEND codes

The IXGBRWSE service may issue abend X'1C5' with reason codes X'804', X'85F' or X'30006'. See z/OS MVS System Codes for more information on this abend.

Return and reason codes

When IXGBRWSE macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.

Note: A program invoking the IXGBRWSE service may indicate via the MODE parameter that requests which can not be completed synchronously should have control returned to the caller prior to completion of the request. When the request does complete, the invoker will be notified and the return and reason codes are in the answer area mapped by IXGANSAA.

The IXGCON mapping macro provides equate symbols for the return and reason codes. The equate symbols associated with each hexadecimal return code are as follows:

00: IXGRSNCODEOK - Service completes successfully.
04: IXGRSNCODEWARNING - Service completes with a warning.
08: IXGRETCODEERROR - Service does not complete.
0C: IXGRETCODECOMPERROR - Service does not complete.

The following table contains hexadecimal return and reason codes, the equate symbols associated with each reason code, and the meaning and suggested action for each return and reason code.

Table 1. Return and Reason Codes for the IXGBRWSE Macro
Return Code	Reason Code	Meaning and Action
00	xxxx0000	Equate Symbol: IxgRsnCodeOk Explanation: Request processed successfully.
04	xxxx0401	Equate Symbol: IxgRsnCodeProcessedAsynch Explanation: Program error. The program specified MODE=SYNCECB and the request must be processed asynchronously. Action: Wait for the ECB specified on the ECB parameter to be posted, indicating that the request is complete. Check the ANSAA_ASYNCH_RETCODE and ANSAA_ASYNCH_RSNCODE fields, mapped by IXGANSAA, to determine whether the request completed successfully.
04	xxxx0402	Equate Symbol: IxgRsnCodeWarningDel Explanation: Environment error. The request completed successfully, but the data requested was deleted from the log stream. The next available data in the log stream in the direction specified is returned. Action: Determine whether this is an acceptable condition for your application. If so, ignore this condition. If not, provide serialization or some other installation protocol to prevent deletes from being performed by other applications on the log stream during a browse session.
04	xxxx0403	Equate Symbol: IxgRsnCodeWarningGap Explanation: Environment error. The request completed successfully, but the data requested was unreadable. The next readable data in the log stream in the specified direction is returned. This condition could be caused by either an I/O error while attempting to read a log data set or a log data set deleted without using the logger interfaces. Action: The action necessary is completely up to the application, depending on how critical your data is. You can do one of the following: Accept this condition and continue reading. Stop processing the log all together. Attempt to get the problem rectified, if possible, and then attempt to re-read the log data.
04	xxxx0405	Equate Symbol: IxgRsnCodeWarningLossOfData Explanation: Environment error. Returned for READCURSOR, START OLDEST and RESET OLDEST requests. This condition occurs when a system and coupling facility fail and not all of the log data in the log stream could be recovered. For READCURSOR: A log block has been returned, but there may be log blocks permanently missing between this log block and the one previously returned. For START OLDEST and RESET OLDEST: The oldest log blocks in the log stream may be permanently missing, the browse cursor is set at the oldest available log block. Action: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
04	xxxx0416	Equate Symbol: IxgRsnCodeWarningMultiblock Explanation: Environment error. Returned for READCURSOR requests with MULTIBLOCK=YES specified only. The request completed successfully, which means that some log block data was returned, but at least one of the log blocks returned in the buffer area encountered a warning return code condition. To determine which log block or blocks encountered the warning condition, check the fields, Ixgbrmlt_RetCode and Ixgbrmlt_RsnCode, as the log blocks are processed by your program. Action: The action necessary is completely up to the application, depending on how critical your data is. You can do one of the following: Accept this condition and continue reading. Stop processing the log all together. Attempt to get the problem rectified, if possible, and then attempt to re-read the log data.
04	xxxx0417	Equate Symbol: IxgRsnCodeMultiblockErrorWarning Explanation: Environment error. Returned for READCURSOR requests with MULTIBLOCK=YES specified only. A log block has been returned, but an error condition was encountered while attempting to read more data. This may be issued when some log block data is returned and an end of the log stream (eof) is reached. Action: The action necessary is completely up to the application, depending on how critical your data is. You can do one of the following: Accept this condition and continue reading. Stop processing the log all together. Attempt to get the problem rectified, if possible, and then attempt to re-read the log data.
08	xxxx0801	Equate Symbol: IxgRsnCodeBadParmlist Explanation: Program error. The parameter list could not be accessed. Action: Ensure that the storage area for the parameter list is accessible to the system logger for the duration of the request. The parameter list storage must be addressable in the caller's primary address space and in the same key as the caller.
08	xxxx0802	Equate Symbol: IxgRsnCodeXESError Explanation: System error. A severe cross-system extended services (XES) error has occurred. Action: See ANSAA_DIAG1 for the XES return code and ANSAA_DIAG2 for the XES reason code.
08	xxxx0803	Equate Symbol: IxgRsnCodeBadBuffer Explanation: Program error. The virtual storage area specified on the BUFFER or BUFFER64 parameter is not addressable. On IXGBRWSE READCURSOR MULTIBLOCK requests, the buffer address must be on a word boundary. Action: Ensure that the storage area specified on the BUFFER or BUFFER64 parameter is accessible to system logger for the duration of the request. If the BUFFKEY parameter is specified, make sure it contains a valid key associated with the storage area. If BUFFKEY is not used, ensure that the storage is in the same key as the program at the time the logger service was requested. The storage must be addressable in the caller's primary address space. For IXGBRWSE READCURSOR MULTIBLOCK requests, put the buffer address on a word boundary.
08	xxxx0804	Equate Symbol: IxgRsnCodeNoBlock Explanation: Program error. The block identifier or time stamp does not exist in the requested view of the log stream. If the SEARCH parameter was specified on a START request, the time stamp is greater than any block in the log stream. Either the value provided was never a valid location within the log stream, or a prior IXGDELET request deleted the portion of the log stream it referred to. Action: Ensure that the value provided references an existing portion of the log stream.
08	xxxx0806	Equate Symbol: IxgRsnCodeBadStmToken Explanation: Program error. One of the following occurred: The stream token was not valid. The specified request was issued from an address space other than the connector's address space. Action: Do one of the following: Make sure that the stream token specified is valid. Ensure that the request was issued from the connector's address space.
08	xxxx0807	Equate Symbol: IxgRsnCodeBadBrwToken Explanation: Program error. The browse token specified is not valid. Action: Ensure that the browse token being passed to the IXGBRWSE service is the same one returned from the IXGBRWSE REQUEST=START function.
08	xxxx080A	Equate Symbol: IxgRsnCodeRequestLocked Explanation: Program error. The program issuing the request is holding a lock. Action: Ensure that the program issuing the request is not holding a lock.
08	xxxx080F	Equate Symbol: IxgRsnCodeBadBufsize Explanation: Program error. The buffer specified on the BUFFER or BUFFER64 parameter is not large enough to contain the next log block. No data is returned. Action: Obtain a buffer of at least the length returned in the BLKSIZE parameter and then re-issue the request.
08	xxxx0814	Equate Symbol: IxgRsnCodeNotAvailForIPL Explanation: Environment error. The system logger address space is not available for the remainder of this IPL. The system issues messages about this error during system logger initialization. Action: See the explanation for system messages issued during system logger initialization.
08	xxxx0815	Equate Symbol: IxgRsnCodeNotEnabled Explanation: Program error. The program issuing the request is not enabled for I/O and external interrupts, so the request fails. Action: Make sure the program issuing the request is enabled for I/O and external interrupts.
08	xxxx0816	Equate Symbol: IxgRsnCodeBadAnslen Explanation: Program error. The answer area length (ANSLEN parameter) is not large enough. The system logger returned the required size in the Ansaa_Preferred_Size field of the answer area, mapped by IXGANSAA macro. Action: Re-issue the request, specifying an answer area of the required size.
08	xxxx0817	Equate Symbol: IxgRsnCodeBadAnsarea Explanation: Program error. The storage area specified on the ANSAREA parameter cannot be accessed. This may occur after the system logger address space has terminated. Action: Specify storage that is in the caller's primary address space and in the same key as the calling program at the time the system logger service was issued. This storage must be accessible until the request completes.
08	xxxx0818	Equate Symbol: IxgRsnCodeBadBlockidStor Explanation: Program error. The storage area specified by BLOCKID cannot be accessed. Action: Ensure that the storage area is accessible to system logger for the duration of the request. The storage must be addressable in the caller's primary address space and in the same key as the caller.
08	xxxx082D	Equate Symbol: IxgRsnCodeExpiredStmToken Explanation: Environment error. The stream token is no longer valid because the connector has been disconnected. Action: Connect to the log stream again before issuing any functional requests.
08	xxxx0836	Equate Symbol: IxgRsnCodeBadGap Explanation: Environment error. The request failed because the requested log data was unreadable. This condition could be caused by either an I/O error while attempting to read a log data set or a log data set deleted without using logger interfaces. Action: For an IXGBRWSE request, choose on of the following: Continue processing. Stop processing the log stream all together. Attempt to get the problem rectified if possible, then attempt to re-read the log data. For an IXGDELET request, the block identifier of the first accessible block toward the youngest data in the log stream is returned in the ANSAA_GAPS_NEXT_BLKID field in the answer area mapped by the IXGANSAA macro. If appropriate, re-issue the IXGDELET request using this block identifier.
08	xxxx0837	Equate Symbol: IxgRsnCodeBadTimestamp Explanation: Program error. The storage area specified by TIMESTAMP cannot be accessed. Action: Ensure that the storage area is accessible to the system logger service for the duration of the request. The storage must be addressable in the caller's primary address space and in the same key as the caller.
08	xxxx083B	Equate Symbol: IxgRsncodeBadBTokenStor Explanation: Program error. The storage area specified by BROWSETOKEN cannot be accessed. Action: Ensure that the storage area is accessible to the system logger for the duration of the request. The storage must be addressable in the caller's primary address space and in the same key as the caller.
08	xxxx083D	Equate Symbol: IxgRsnCodeBadECBStor Explanation: Program error. The ECB storage area was not accessible to the system logger. Action: Ensure that the storage area is accessible to the system logger for the duration of the request. The storage must be addressable in the caller's home address space and in the same key as the caller.
08	xxxx083F	Equate Symbol: IxgRsnCodeTestartError Explanation: System error. An unexpected error was encountered while attempting to validate the buffer ALET. Action: See ANSAA_DIAG1 in the answer area mapped by the IXGANSAA macro for the return code from the TESTART system service.
08	xxxx0841	Equate Symbol: IxgRsnCodeBadBufferAlet Explanation: Program error. The buffer ALET specified is not zero and does not represent a valid entry on the caller's dispatchable unit access list (DUAL). See the ANSAA_DIAG1 field of the answer area, mapped by the IXGANSAA macro, for the return code from the TESTART system service. Action: Ensure that the correct ALET was specified. If not, provide the correct ALET. Otherwise, add the correct ALET to dispatchable unit access list (DUAL).
08	xxxx0845	Equate Symbol: IxgRsnCodeInvalidFunc Explanation: System error. One of 2 problems was detected. The parameter list for this service contains an unrecognizable function code. The parameter list storage may have been overlayed. The IXGBRWSE START is rejected because either: A: An unauthorized caller attempted to start a session when 100 or more browse sessions already exist for this connection. Or, B: An unauthorized caller attempted to start a session when 20 or more browse sessions already exist that show no recent activity. (An unauthorized caller is a caller whose PSW Key is >= 8 and that is not in supervisor state). For Case 2: DIAG1 in the Answer Area will contain 1 if 'A' is the case, and 2 if 'B' is the case. DIAG2 will contain the number of browse sessions that was exceeded. Action: Fix the problem and then re-issue the request. It may be necessary to terminate some Browse sessions that are not being used.
08	xxxx0846	Equate Symbol: IxgRsnCodeEmptyStream Explanation: Environment error. The log stream is empty. Action: Wait for data to be written to the log stream before browsing for data.
08	xxxx0847	Equate Symbol: IxgRsnCodeEOFDelete Explanation: Environment error. The request prematurely reached the beginning or the end of the log stream. The portion of the log stream from the requested log data to either the beginning or the end of the log stream (depending on the direction of the read) was deleted from the log stream. Action: Determine whether this is an acceptable condition for your application. If so, ignore this condition. If not, provide serialization on the log stream or some other installation protocol to prevent deletes from being performed by other applications during a browse session.
08	xxxx0848	Equate Symbol: IxgRsnCodeEndReached Explanation: Environment error. The request failed and no log data is returned. For a READCURSOR request, the end of the log stream has been reached in the direction of the read. If the SEARCH parameter was specified on a READBLOCK request, the time stamp is greater than any block in the log stream. Action: For the READCURSOR case, no more data exists in the log stream in the direction of the read. You can choose to stop reading, wait for more data to be written, or change the direction of the read. In the case where the SEARCH parameter was provided, ensure that the time stamp is less than or equal to the highest time stamp of a log block in the log stream.
08	xxxx0849	Equate Symbol: IxgRsnCodeBadBuffkey Explanation: Program error. The buffer key specified on the BUFFKEY parameter specifies an invalid key. Either the key is greater than 15 or the program is running in problem state and the specified key is not the same key as the PSW key at the time the system logger service was issued. Action: For problem state programs, either do not specify the BUFFKEY parameter or else specify the same key as the PSW key at the time the system logger service was issued. For supervisor state programs, specify a valid storage key (0 <= key <= 15).
08	xxxx084A	Equate Symbol: IxgRsnCodeEOFGap Explanation: Environment error. The request prematurely reached the beginning or the end of the log stream. The portion of the log stream from the requested log data to either the beginning or the end of the log stream (depending on the direction of the read) was unreadable. This condition may be caused by either an I/O error while trying to read a log data set, or a log data set deleted without using logger interfaces. Action: The action necessary is completely up to the application depending on how critical your data is. You can do one of the following: Accept this condition and continue reading. Stop processing the log all together. Attempt to get the problem rectified, if possible, and then attempt to re-issue the request.
08	xxxx084B	Equate Symbol: IxgRsncodeLossOfDataGap Explanation: Environment error. The requested log data referenced a section of the log stream where log data is permanently missing. This condition occurs when a system or coupling facility is in recovery due to a failure, but not all of the log data in the log stream could be recovered. Action: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
08	xxxx084D	Equate Symbol: IxgRsnCodeLossOfDataEOF Explanation: Environment error. The request prematurely reached the beginning or the end of the log stream. The portion of the log stream from the requested log data to either the beginning or the end of the log stream (depending on direction of the read) was permanently lost. This condition occurs when a system or coupling facility is in recovery due to a failure, but not all of the log data in the log stream could be recovered. Action: If your application cannot tolerate any data loss, stop issuing system logger services to this log stream, disconnect from the log stream, and reconnect to a new, undamaged log stream. You can continue using the log stream if your applications can tolerate data loss.
08	xxxx0852	Equate Symbol: IxgRsnCodeBadBlkSizeStor Explanation: Program error. The storage area specified on the BLKSIZE parameter cannot be accessed. Action: Ensure that the storage area is accessible to system logger for the duration of the request.
08	xxxx085F	Equate Symbol: IxgRsnPercToRequestor Explanation: Environment error. Percolation to the service requestor's task occurred because of an abend during system logger processing. Retry was not allowed. Action: Issue the request again. If the problem persists, contact the IBM Support Center.
08	xxxx0861	Equate Symbol: IxgRsnCodeRebuildInProgress Explanation: Environment error. No requests can be processed for this log stream because a coupling facility structure re-build is in progress for the structure associated with this log stream. Action: Listen for ENF signal 48 that will indicate one of the following: The log stream is available because the re-build completed successfully. Re-issue the request. The re-build failed and the log stream is not available.
08	xxxx0862	Equate Symbol: IxgRsnCodeXESPurge Explanation: Environment error. An cross-system extended services (XES) request has been purged due to re-build processing. Action: Listen for ENF signal 48 that will indicate one of the following: The log stream is available because the re-build completed successfully. Re-issue the request. The re-build failed and the log stream is not available.
08	xxxx0863	Equate Symbol: IxgRsnCodeStructureFailed Explanation: Environment error. Either the coupling facility structure associated with the log stream has failed or the coupling facility itself has failed. Action: Listen for ENF signal 48 that will indicate one of the following: The log stream is available because the re-build completed successfully. Re-issue the request. The re-build failed and the log stream is not available.
08	xxxx0864	Equate Symbol: IxgRsnCodeNoConnectivity Explanation: Environment error. No connectivity exists to the coupling facility associated with the log stream. The system logger will either attempt to re-build the log stream in another coupling facility or the log stream will be disconnected. Action: Listen for ENF signal 48 that will indicate one of the following: The log stream is available because the re-build completed successfully. Re-issue the request. The re-build failed and the log stream is not available. The log stream has been disconnected from this system. If a re-build initiated because of a loss of connectivity previously failed, an ENF corresponding to this reason code might not be issued. Further action by the installation might be necessary to cause the change of the log stream status again. Check the log for messages IXG101I, IXG107I and related rebuild messages for information on resolving any outstanding issues.
08	xxxx0890	Equate Symbol: IxgRsnCodeAddrSpaceNotAvail Explanation: System error. The system logger address space failed and is not available. Action: Do not issue system logger requests.
08	xxxx0891	Equate Symbol: IxgRsnCodeAddrSpaceInitializing Explanation: System error. The system logger address space is not available because it is IPLing. Action: Listen for ENF signal 48, which will indicate when the system logger address space is available. Re-connect to the log stream, then re-issue this request. You can also listen for ENF signal 48, which will indicate if the system logger address space will not be available for the life of the IPL. In that case, do not issue system logger services.
08	xxxx08D0	Equate Symbol: IxgRsnCodeProblemState Explanation: Environment error. The request was rejected because of one of the following: The request was issued in SRB mode while the requestor was in problem program state. The SYNCEXIT parameter was specified while the requestor's PSW key was in problem program key. Action: Change the invoking environment to supervisor state.
08	xxxx08D1	Equate Symbol: IxgRsnCodeProgramKey Explanation: Environment error. The request was rejected because of one of the following: The request was issued in SRB mode while the requestor was in problem program key (key 8-F). The SYNCEXIT parameter was specified while the requestor's PSW key was in problem program key. Action: Change the invoking environment to a system key (key 0-7).
08	xxxx08D2	Equate Symbol: IxgRsnCodeNoCompleteExit Explanation: Program error. MODE=SYNCEXIT was specified, but the connection request did not identify a complete exit. Action: Either change this request to a different MODE option, or reconnect to the log stream with a complete exit on the COMPLETEXIT parameter.
08	xxxx08D3	Equate Symbol: IxgRsnCodeFuncNotSupported Explanation: Environment error. The options specified on the IXGBRWSE request are not supported on this system/maintenance level of system logger. Action: Either install the level of system logger that provides the support for the requested function, or do not specify options that are not supported at this level.
0C	xxxx0000	Equate Symbol: IxgRetCodeCompError Explanation: User or System error. One of the following occurred: You issued the FORCE IXGLOGR,ARM command to terminate the system logger address space. System logger component error occurred. Action: If this reason code is not the result of forcing the system logger address space, search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center. Provide the diagnostic data in the answer area (IXGANSAA) and any dumps or LOGREC entries from system logger.

Example 1

Issue IXGBRWSE REQUEST=START to start a browse session, starting the browse cursor at the log block with the specified local time.

          IXGBRWSE REQUEST=START,                                      X
               STREAMTOKEN=TOKEN,                                      X
               SEARCH=SRCHTIME,                                        X
               GMT=NO,                                                 X
               BROWSETOKEN=BRSTOKEN,                                   X
               MODE=SYNC,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
ANSLEN   DC    A(L'ANSAREA)           length of logger's answer area
TOKEN    DS    CL16                   stream token from connect
SRCHTIME DS    2F                     local search time in stck format
BRSTOKEN DS    CL4                    returned browse token
ANSAREA  DS    CL(ANSAA_LEN)          answer area for log requests
RETCODE  DS    F                      return code
RSNCODE  DS    F                      reason code
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area

Example 2

Issue IXGBRWSE REQUEST=READCURSOR to read the next consecutive log block in the specified direction. In this example, the default of MULTIBLOCK=NO has been taken.

          IXGBRWSE REQUEST=READCURSOR,                                 X
               STREAMTOKEN=TOKEN,                                      X
               BUFFER=BUFF,                                            X
               BUFFLEN=BUFFLEN,                                        X
               BUFFALET=ALET,                                          X
               BLKSIZE=BLKSIZE,                                        X
               DIRECTION=OLDTOYOUNG,                                   X
               RETBLOCKID=RETBLK,                                      X
               TIMESTAMP=TIMESTMP,                                     X
               BROWSETOKEN=BRSTOKEN,                                   X
               MODE=SYNC,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
ANSLEN   DC    A(L'ANSAREA)           length of logger's answer area
BUFFLEN  DC    F'200'                 buffer length
TOKEN    DS    CL16                   stream token from connect
BRSTOKEN DS    CL4                    returned browse token
BUFF     DS    CL200                  buffer where data will be put
ALET     DC    F'1'                   buffer alet in secondary
BLKSIZE  DS    F                      block size of buffer
RETBLK   DS    CL8                    return block id
TIMESTMP DS    CL16                   returned time stamp stck format
ANSAREA  DS    CL(ANSAA_LEN)          answer area for log requests
RETCODE  DS    F                      return code
RSNCODE  DS    F                      reason code
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area

Example 3

Issue IXGBRWSE REQUEST=READBLOCK to read a log block selected by block identifier.

          IXGBRWSE REQUEST=READBLOCK,                                  X
               STREAMTOKEN=TOKEN,                                      X
               BLOCKID=BLKID,                                          X
               BUFFER=BUFF,                                            X
               BUFFLEN=BUFFLEN,                                        X
               BUFFALET=ALET,                                          X
               BLKSIZE=BLKSIZE,                                        X
               RETBLOCKID=RETBLK,                                      X
               TIMESTAMP=TIMESTMP,                                     X
               BROWSETOKEN=BRSTOKEN,                                   X
               MODE=SYNC,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
ANSLEN   DC    A(L'ANSAREA)           length of logger's answer area
BUFFLEN  DC    F'200'                 buffer length
TOKEN    DS    CL16                   stream token from connect
BRSTOKEN DS    CL4                    returned browse token
BUFF     DS    CL200                  buffer where data will be put
ALET     DS    F'1'                   buffer alet in secondary
BLKSIZE  DS    F                      block size of buffer
RETBLK   DS    CL8                    return block id
BLKID    DS    CL8                    specific block id to browse
TIMESTMP DS    CL16                   returned time stamp stck format
ANSAREA  DS    CL(ANSAA_LEN)          answer area for log requests
RETCODE  DS    F                      return code
RSNCODE  DS    F                      reason code
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area

Example 4

Issue IXGBRWSE REQUEST=RESET to reset the cursor at the youngest block in the log stream.

          IXGBRWSE REQUEST=RESET,                                      X
               STREAMTOKEN=TOKEN,                                      X
               POSITION=YOUNGEST,                                      X
               BROWSETOKEN=BRSTOKEN,                                   X
               MODE=SYNC,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
ANSLEN   DC    A(L'ANSAREA)           length of logger's answer area
TOKEN    DS    CL16                   stream token from connect
BRSTOKEN DS    CL4                    returned browse token
ANSAREA  DS    CL(ANSAA_LEN)          answer area for log requests
RETCODE  DS    F                      return code
RSNCODE  DS    F                      reason code
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area

Example 5

Issue IXGBRWSE REQUEST=END to end a browse session.

          IXGBRWSE REQUEST=END,                                        X
               STREAMTOKEN=TOKEN,                                      X
               BROWSETOKEN=BRSTOKEN,                                   X
               MODE=SYNC,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
ANSLEN   DC    A(L'ANSAREA)           length of logger's answer area
TOKEN    DS    CL16                   stream token from connect
BRSTOKEN DS    CL4                    browse token from browse start
ANSAREA  DS    CL(ANSAA_LEN)          answer area for log requests
RETCODE  DS    F                      return code
RSNCODE  DS    F                      reason code
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area

Example 6

Issue IXGBRWSE REQUEST=END to end a browse session asynchronously, if synchronous processing is not possible.

          IXGBRWSE REQUEST=END,                                        X
               STREAMTOKEN=TOKEN,                                      X
               BROWSETOKEN=BRSTOKEN,                                   X
               MODE=SYNCECB,                                           X
               ECB=ANECB,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
*++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
*        if rsncode = '00000401'X then wait on
*        the ecb ANECB.
*++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ANSLEN   DC    A(L'ANSAREA)           length of logger's answer area
TOKEN    DS    CL16                   stream token from connect
BRSTOKEN DS    CL4                    browse token from browse start
ANSAREA  DS    CL(ANSAA_LEN)          answer area for log requests
ANECB    DS    F                      ecb on which to wait
RETCODE  DS    F                      return code
RSNCODE  DS    F                      reason code
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area

Example 7

Issue IXGBRWSE REQUEST=END using registers.

          LA   R6,TOKEN               place stream token in reg 6
          IXGBRWSE REQUEST=END,                                        X
               STREAMTOKEN=(6),                                        X
               BROWSETOKEN=BRSTOKEN,                                   X
               MODE=SYNC,                                              X
               ANSAREA=ANSAREA,                                        X
               ANSLEN=ANSLEN,                                          X
               RSNCODE=RSNCODE,                                        X
               MF=S,                                                   X
               RETCODE=RETCODE
ANSLEN   DC    A(L'ANSAREA)           length of logger's answer area
TOKEN    DS    CL16                   stream token from connect
BRSTOKEN DS    CL4                    browse token from browse start
ANSAREA  DS    CL(ANSAA_LEN)          answer area for log requests
RETCODE  DS    F                      return code
RSNCODE  DS    F                      reason code
DATAREA  DSECT
         IXGANSAA LIST=YES            answer area
R6       EQU   6