CSREVW — View an object and sequentially access it

Description

Call the CSREVW window service if your program references data in a sequential manner and you want to:

Map a window to one or more blocks (4096 bytes) of a data object. If you specified scrolling when you called CSRIDAC to identify the object, CSREVW maps the window to the blocks in the scroll area and maps the scroll area to the object.
Specify how many blocks window services is to try to transfer into the window each time CSREVW needs more data from the object.

Mapping a data object enables your program to access the data that is viewed through the window the same way it accesses other data in your storage.

The CSREVW and CSRVIEW services differ on how to specify sequential access:

If you use CSRVIEW and specify sequential, when you reference data that is not in your window, window services reads up to 16 blocks — the one that contains the data your program requests, plus the next 15 consecutive blocks. The number of blocks that actually come into the window depends on the size of the window and the availability of central storage.
If you use CSREVW, you can specify the number of additional consecutive blocks that window services reads into the window at one time. The number ranges from 0 through 255 blocks. The number of blocks that actually come into the window depends on the size of the window and the availability of central storage.

Use CSREVW if your program can benefit from having more than 16 blocks come into a window at one time, or fewer than 16 blocks at one time.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state with PSW key 8-15
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN = SASN
AMODE:	24- or 31-bit, but all addresses must be 31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space

Programming requirements

None.

Restrictions

The caller must follow all the restrictions imposed by the DIV macro.

Input register information

Before calling the CSREVW service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register: Contents
13: The address of a standard 18-word save area

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0: Reason 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 access registers (ARs) contain:

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

Some callers depend on the register contents remaining the same before and after issuing a service. If the system changes the contents of the 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.

Syntax

Write the CALL as shown in the syntax diagram. You must code all parameters on the CALL statement in the order shown.

Syntax	Description
CALL CSREVW	,(operation_type ,object_id ,offset ,span ,window_name ,usage ,disposition ,pfcount ,return_code ,reason_code)

Parameters

All input to callable services is in the form of RX-type addresses.

The parameters are explained as follows:

,(operation_type

Specifies that you are to begin viewing an object.

Define operation_type as character data of length at least 5 bytes, containing the characters "BEGIN".

,object_id

Specifies the object identifier. Supply the object identifier that CSRIDAC returned when you obtained access to the object.

Define object_id as character data of length 8.

,offset

Specifies the offset of the view into the object. Specify the offset in blocks of 4096 bytes.

Define offset as integer data of length 4.

,span

Specifies the window size in blocks of 4096 bytes.

Define span as integer data of length 4.

,window_name

Specifies the symbolic name you assigned to the window in your address space.

,usage

Specifies that the expected pattern of references to data in the object will be sequential.

Define usage as character data of at least 4 bytes, containing the characters "SEQ". Pad the string on the right with 1 or more blanks.

,disposition

Defines how CSREVW is to handle data that is in the window when you begin a view. You can specify CSREVW BEGIN with a disposition of REPLACE or RETAIN. REPLACE and RETAIN cause the data in the window to be handled as follows:

REPLACE: The first time you reference a block to which the window is mapped, CSREVW replaces the data in the window with the data from the referenced block.
RETAIN: When you reference a block to which the window is mapped, the data in the window remains unchanged. When you call CSRSAVE to save the mapped blocks, CSRSAVE saves all of the mapped blocks because CSRSAVE considers them changed.

Define disposition as character data of length 7. If you specify RETAIN, pad the string on the right with 1 blank.

,pfcount

Specifies the number of additional blocks you want window services to bring into the window each time your program references data that is not already in the window. The number you specify is added to the minimum of one block that window services always brings in. That is, if you specify a value of 20, window services brings in up to 21. The number of additional blocks ranges from zero through 255.

Define pfcount as integer data of length 4.

,return_code

When CSREVW completes, return_code contains the return code. Define return_code as integer data of length 4.

,reason_code)

When CSREVW completes, reason_code contains the reason code. Define reason_code as integer data of length 4.

ABEND codes

CSREVW might abnormally terminate with abend code X'019'. See z/OS MVS System Codes for an explanation and programmer responses.

Return and reason codes

When the CSREVW service returns control to your program, GPR 15 (and return_code) contains a return code. GPR 0 (and reason_code) contains a reason code. The following table identifies return code and reason code combinations and explains their meanings. Data-in-virtual reason codes, which are returned with CSREVW return codes X'4' and X'C', are two bytes long and right justified. They are explained in the description of the DIV macro (DIV — Data-in-virtual).

Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00000000	00000000	Meaning: The operation was successful. Action: None.
00000004	00000165	Meaning: System error. The service could not retain all the data that was in the scroll area. Action: Retry the request. If the problem persists, contact the appropriate IBM® support personnel.
00000004	xxxxnnnn	Meaning: The value `nnnn` is a data-in-virtual reason code. The value `xxxx` is not part of the intended programming interface. Action: See the DIV macro description for an explanation of reason code `nnnn`.
0000000C	xxxxnnnn	Meaning: The value `nnnn` is a data-in-virtual reason code. The value `xxxx` is not part of the intended programming interface. Action: See the DIV macro description for an explanation of reason code `nnnn`.
0000002C	00000004	Meaning: Program error. Window services have not been defined to your system, or the link to the service failed. Action: If window services are available on your system, rerun the program one or more times. If the problem persists, contact the appropriate IBM support personnel.