CSRSAVE — Save changes made to a permanent object

Description

To update specified blocks of a permanent object with changes, call the CSRSAVE window service. The changes can be in blocks that are mapped to the scroll area, in blocks that are mapped to windows, or in a combination of these places.

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

You cannot use CSRSAVE to save changes made to a temporary object. If you call CSRSAVE for a temporary object, CSRSAVE ignores the request and returns control to your program with a return code of 8. To save changes made to a temporary object, call CSRSCOT.

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

Input register information

Before calling the CSRSAVE 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 CSRSAVE	,(object_id ,offset ,span ,new_hi_offset ,return_code ,reason_code)

Parameters

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

The parameters are explained as follows:

,(object_id

Specifies the object identifier. Supply the same 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 into the object in blocks of 4096 bytes. A value of 0 specifies the first block of 4096 bytes or bytes 0 to 4095 of the object; a value of 1 specifies the second block of 4096 bytes, or bytes 4096 to 8191 of the object, and so forth.

Define offset as integer data of length 4.

offset and span, together, determine what part of the object window services saves. To save the entire object, specify 0 for offset and 0 for span.

,span

Specifies how many 4096-byte blocks CSRSAVE is to save.

Define span as integer data of length 4.

,new_hi_offset

When CSRSAVE completes, new_hi_offset contains the new size of the object expressed in units of 4096 bytes.

Define new_hi_offset as integer data of length 4.

,return_code

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

,reason_code)

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

ABEND codes

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

A return code of X'4' with a reason code of X'0807' or a return code of X'C' with any reason code 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	xxxx0807	Meaning: Environmental error. Media damage might be present in allocated DASD space. The damage is beyond the currently saved portion of the object. The SAVE operation completed successfully. The value X'0807' 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 X'0807'.
00000008	00000143	Meaning: Program error. You cannot use the SAVE service for a temporary object. Action: Call CSRSCOT to save changes made to a temporary object.
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.