CSRIDAC — Request or terminate access to a data object

Description

Use the CSRIDAC callable window service to control access to a data object. The CSRIDAC service allows you to:

Request access to a data object
End access to a data object.

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 CSRIDAC 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 CSRIDAC	,(operation_type ,object_type ,object_name ,scroll_area ,object_state ,access_mode ,object_size ,object_id ,high_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:

,(operation_type

Specifies the type of operation the service is to perform:

To request access to an object, specify BEGIN.
To terminate access to an object, specify END. If the object is temporary, CSRIDAC deletes it.

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

,object_type

Specifies the type of object. The types are:

DDNAME: The object is an existing (OLD) VSAM linear data set allocated to the file whose DDNAME is specified by object_name.
DSNAME: The object is the linear VSAM data set whose name is specified by object_name. The data set may already exist or may be a new data set that you want window services to create.
TEMPSPACE: The object is a temporary data object. Window services will delete the object when your program issues CSRIDAC END.

If operation_type is BEGIN, you must supply a value.

Define this parameter as character data of length 9. If you specify either DDNAME or DSNAME, pad the string on the right with blanks.

,object_name

Specifies the data set name of a permanent object or the DDNAME of a data definition (DD) statement that defines a permanent object.

If object_type is DDNAME, object_name must contain the name of a DD statement.
If object_type is DSNAME, object_name must contain the data set name of the permanent object.

If operation_type is BEGIN and object_type is DDNAME or DSNAME, you must supply a value for object_name.

Define object_name as character data of length 1 to 44. If object_name contains fewer than 44 characters, pad the name on the right with blanks.

,scroll_area

Specifies whether window services is to create a scroll area for the data object.

YES: Create a scroll area.
NO: Do not create a scroll area.

If operation_type is BEGIN and object_type is TEMPSPACE, specify YES.

Define scroll_area as character data of length 3. If you specify NO, pad the string on the right with a blank.

,object_state

Specifies the state of the object.

OLD: The object exists.
NEW: The object does not exist and window services must create it.

If operation_type is BEGIN and object_type is DSNAME, you must supply a value for object_state.

Define object_state as character data of length 3.

,access_mode

Specifies the type of access required.

READ: READ access.
UPDATE: UPDATE access.

If operation_type is BEGIN and object_type is DDNAME or DSNAME, you must supply a value for access_mode. For a new or temporary data object, window services assumes UPDATE.

Define access_mode as character data of length 6. If you specify READ, pad the string on the right with 1 or 2 blanks.

,object_size

Specifies the maximum size of the new object in units of 4096 bytes.

This parameter is required if either of the following conditions is true:

Operation_type is BEGIN, object_type is DSNAME, and object_state is NEW
Operation_type is BEGIN and object_type is TEMPSPACE

Define object_size as integer data of length 4.

,object_id

Specifies the object identifier.

When operation_type is BEGIN, the service returns the object identifier in this parameter. Use the identifier to identify the object to other window services.

When operation_type is END, you must supply the object identifier in this parameter.

Define object_id as character data of length 8.

,high_offset

When CSRIDAC completes, high_offset contains the size of the existing object expressed in blocks of 4096 bytes

Define high_offset as integer data of length 4.

,return_code

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

,reason_code)

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

ABEND codes

The CSRIDAC 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 CSRIDAC service returns control to your program, return_code contains a return code 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 CSRIDAC 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	xxxxnnnn	Meaning: Program error or environmental error. The operation was successful; however, data-in-virtual issued a warning. The value `nnnn` is a data-in-virtual reason code. The value `xxxx` is not part of the intended programming interface. Action: See the description of the DIV macro for an explanation of reason code nnnn.
00000008	00000118	Meaning: Environmental error. The system could not obtain enough storage to create a hiperspace for the temporary object or the scroll area. Action: Rerun the program one or more times. If the problem persists, notify your system programmer, who can increase the SMF limit. The SMF limit, which is set by the installation, restricts the amount of virtual storage that programs in each address space can use for data spaces and hiperspaces.
00000008	00000119	Meaning: Environmental error. The system could not delete or unidentify the temporary object or the scroll area. Action: Retry the request. If the problem persists, record the return and reason code, and contact the appropriate IBM® support personnel.
00000008	0000011A	Meaning: Environmental error. The system was unable to create a new VSAM linear data set. Your system must include SMS, and SMS must be active. Action: Contact your system programmer to request that SMS be made active.
0000000C	xxxxnnnn	Meaning: Program error or environmental error. The value `nnnn` is a data-in-virtual reason code. The value `xxxx` is not part of the intended programming interface. Action: See the description of the DIV macro for an explanation of reason code nnnn.
00000010	rrrrnnnn	Meaning: Program or environmental error. The system was unable to allocate or unallocate the data set specified as `object_name`. The value `rrrr` is the return code from dynamic allocation. The value `nnnn` is the two-byte reason code from dynamic allocation. Action: If `object_state` is new, make sure that a data set of the same name does not already exist. If this is the case, either use the existing data set or change the name of your data set. If you are unable to correct the problem, notify your system programmer.
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.