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.
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.
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:
All storage areas specified must be in the same storage
key as the caller with the following exception:
|
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.
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.
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.
None.
The IXGBRWSE macro with the REQUEST=START parameter starts a browse session and sets the starting position of the browse cursor.
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) | |
The parameters are explained as follows:
To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
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.
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.
When VIEW=ALL is specified, you must specify a starting block that is active.
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.
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 for the VIEW parameter to be recognized.
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.
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.
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.
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.
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.
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) | |
The parameters are explained as follows:
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.
To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
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.
The default is 0, which means that the buffer is in the calling program's primary address space.
If you omit the RETBLOCKINFO parameter, RETBLOCKINFO=NO is the default.
If you omit the MAXNUMLOGBLOCKS, the default is 0.
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.
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.
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.
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.
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) | |
The parameters are explained as follows:
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.
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.
To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
To ascertain the optimal answer area size, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
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.
The default is 0, which means that the buffer is in the calling program's primary address space.
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.
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.
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.
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.
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) | |
The parameters are explained as follows:
To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
To ascertain the optimal answer area size, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
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.
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.
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.
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.
The IXGBRWSE macro with the REQUEST=END parameter ends the browse session begun with the REQUEST=START parameter.
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) | |
The parameters are explained as follows:
To ascertain the optimal answer area length, look at the ANSAA_PREFERRED_SIZE field of the IXGANSAA macro.
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.
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.
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.
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.
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.
When IXGBRWSE macro returns control to your program, GPR 15 contains a return code and GPR 0 contains a reason code.
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.
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:
|
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.
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:
|
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:
|
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:
Action: Do one of the following:
|
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:
|
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.
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:
|
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:
|
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:
|
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:
|
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:
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:
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:
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:
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. |
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
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
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
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
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
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
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