CSRVIEW — View an object

Description

Call the CSRVIEW window service to:

Map a window to one or more blocks of a data object. If you specified scrolling when you called CSRIDAC to identify the object, CSRVIEW maps the window to the blocks in the scroll area and maps the scroll area to the object.
Specify that the reference pattern you are using is either random or sequential.
End a view that you previously created through CSRVIEW or CSREVW, and unmap 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 service also maps a data object. Use that service if your program references the data in the window in a sequential pattern and can benefit from having more than 16 blocks come into a window at one time, or if it can benefit from having fewer than 16 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 addresses
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 CSRVIEW 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 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.

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 CSRVIEW	,(operation_type ,object_id ,offset ,span ,window_name ,usage ,disposition ,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 the type of operation CSRVIEW is to perform. To begin viewing an object, specify BEGIN. To end a view, whether mapped by CSRVIEW or CSREVW, specify END.

Define operation_type as character data of length 5. If you specify END, pad the string on the right with 1 or 2 blanks.

,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 the expected pattern of references to pages in the object. Specify one of the following values:

SEQ: The reference pattern is expected to be sequential. If you specify SEQ, window services brings up to 16 blocks of data into the window at a time, depending on the size of the window and availability of resources.
RANDOM: The reference pattern is expected to be random. If you specify RANDOM, window services brings data into the window one block at a time.

Define usage as character data of length 6. If you specify SEQ, pad the string on the right with 1 to 3 blanks.

,disposition

Defines how CSRVIEW is to handle data that is in the window when you begin or end a view.

When you specify CSRVIEW BEGIN and a disposition of:
REPLACE

The first time you reference a block to which the window is mapped, CSRVIEW 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.
When you specify CSRVIEW END and a disposition of:
REPLACE

CSRVIEW discards the data that is in the window, making the window contents unpredictable. CSRVIEW does not update mapped blocks of the object or scroll area.

RETAIN

If the object is permanent and has no scroll area, CSRVIEW retains the data that is in the window. CSRVIEW does not update mapped blocks of the object.
If the object is permanent and has a scroll area, or if the object is temporary, CSRVIEW retains the data that's in the window and updates the mapped blocks of the object or scroll area.

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

,return_code

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

,reason_code)

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

ABEND codes

The CSRVIEW service 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 CSRVIEW service returns control to your program, GPR 15 (and return_code) contains a return code and GPR 0 (and reason_code) contains a reason code. The following table identifies return code and reason code combinations and tells what each means.

A return code of X'4' or X'C' means that data-in-virtual encountered a problem or an unexpected condition. Data-in-virtual reason codes, which are two bytes long and right justified, 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	00000125	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 `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 `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.