|
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. |
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.
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.
|
|