VSMLOC — Verify virtual storage allocation

Description

The VSMLOC macro verifies that a given storage area has been allocated using the GETMAIN or STORAGE macros.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	For LINKAGE=SYSTEM, problem state and PSW key 8-15. For LINKAGE=BRANCH, supervisor state and PSW key 0.
Dispatchable unit mode:	Task or SRB.
Cross memory mode:	Any PASN, any HASN, any SASN.
AMODE:	24- or 31-bit. All addresses passed to VSMLOC must be 31-bit addresses.
ASC mode:	Primary.
Interrupt status:	For LINKAGE=SYSTEM, enabled or disabled for I/O and external interrupts. For LINKAGE=BRANCH, interrupt status depends on the area of storage for which information is requested. See the LINKAGE=BRANCH parameter for complete information.
Locks:	For LINKAGE=SYSTEM with LSQA, PVT, or CPOOLLCL specified, you may hold only the local lock. For LINKAGE=BRANCH, see the LINKAGE=BRANCH parameter for locking requirements.
Control parameters:	Must be in the primary address space

Programming requirements

All addresses are associated with the current address space.
The VSMLOC service does not provide serialization or recovery for callers specifying LINKAGE=BRANCH. Callers must provide serialization and recovery as described under the LINKAGE parameter description.
The VSMLOC service provides serialization and recovery for callers specifying LINKAGE=SYSTEM.

Restrictions

None.

Input register information for LINKAGE=SYSTEM

The VSMLOC macro is sensitive to the SYSSTATE macro with the OSREL=ZOSV1R6 parameter

If the caller has issued the SYSSTATE macro with the OSREL=ZOSV1R6 parameter (Version 1 Release 6 of z/OS® or later) before issuing the VSMLOC macro, the caller does not have to place any information into any general purpose register (GPR) unless using it in register notation for a particular parameter, or using it as a base register.
Otherwise, the caller must ensure that the following general purpose register contains the specified information:
Register

Contents

13

The address of an 18-word save area

Output register information for LINKAGE=SYSTEM

When control returns to the caller, the GPRs contain:

Register: Contents
0: If GPR15 contains a value of zero, byte 3 contains the number of the subpool from which the specified storage area was obtained. Bytes 0-2 do not contain any relevant information.
If GPR15 contains a nonzero value, contains zero.
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

Input register information for LINKAGE=BRANCH

The caller must ensure that the following general purpose register (GPR) contains the specified information:

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

Output register information for LINKAGE=BRANCH

When control returns to the caller, the GPRs contain:

Register: Contents
0: If GPR15 contains a value of 0, byte 3 contains the number of the subpool from which the specified storage area was obtained. Bytes 0-2 do not contain any relevant information.
If GPR15 contains a nonzero value, contains zero.
1-2: Used as work registers by the system
3-13: Unchanged.
14: Used as a work register by the system.
15: Return code.

When control returns to the caller, the 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

The VSMLOC macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede VSMLOC.

VSMLOC

␢	One or more blanks must follow VSMLOC.

SQA
CSA
LSQA
PVT
CPOOLFIX
CPOOLPAG
CPOOLLCL

,AREA=(`addr`,`length`)	`addr`: RX-type address or register (0) - (12).
	`length`: Symbol, decimal digit or register (0), (2) - (12). Use only with SQA, CSA, LSQA, and PVT.

,AREA=(`addr`)	`addr`: RX-type address or register (0) - (12). Use only with CPOOLFIX, CPOOLPAG, and CPOOLLCL.

,TCB=`addr`
	`addr`: RX-type address or register (0) - (12). Can only be specified with PVT.

,LINKAGE=SYSTEM	Default: LINKAGE=SYSTEM
,LINKAGE=BRANCH

Parameters

The parameters are explained as follows:

SQA

CSA

LSQA

PVT

CPOOLFIX

CPOOLPAG

CPOOLLCL

Used to verify that storage has been allocated.

SQA, CSA, LSQA, and PVT are used to verify that storage for SQA, CSA, LSQA, or PVT (private area storage) has been allocated in the current address space.

CPOOLFIX is used to verify that storage for a global fixed cell pool has been allocated. Users who obtain their storage from subpool 226, 227, 228, 239, or 245 should specify this keyword.

CPOOLPAG is used to verify that storage for a global pageable cell pool has been allocated. Users who obtain storage from subpool 231, 241, 247, or 248 should specify this keyword.

CPOOLLCL is used to verify that storage for a local cell pool has been allocated. Users who obtain storage from subpool 0-127, 129-132, 203-205, 213-215, 223-225, 229, 230, 233-237, 240, 249, or 250-255 should specify this keyword.

,AREA=(addr,length)

Indicates the start of the virtual storage area (addr) and the length of the virtual storage area (length) to be verified.

,AREA=(addr)

Indicates the start of the virtual storage area (addr) to be verified.

,TCB=addr

Indicates that VSMLOC is to place the address of the TCB associated with the verified storage in the register or storage area specified by the TCB parameter. If the return code from VSMLOC is not zero, the register or storage area specified by the TCB parameter is set to zero. The TCB parameter can be specified only with PVT.

,LINKAGE=SYSTEM

,LINKAGE=BRANCH

Indicates the type of linkage that VSMLOC is to use.

If LINKAGE=SYSTEM is specified, the VSMLOC routine uses a basic PC instruction for linkage.

The caller's secondary ASID is preserved when a basic PC is issued.

If LINKAGE=BRANCH is specified, the VSMLOC routine uses branch entry linkage. Before issuing VSMLOC, provide serialization as follows:

For LSQA, CPOOLLCL, and PVT requests, obtain the LOCAL lock.
For CSA, SQA, and CPOOLFIX requests, issue the SETLOCK macro right before and right after the VSMLOC request, as follows:
```
SETLOCK OBTAIN,TYPE=VSMFIX,MODE=UNCOND
VSMLOC request
SETLOCK RELEASE,TYPE=VSMFIX
```
If your program is covered by a functional recovery routine (FRR) and the FRR receives control after SETLOCK OBTAIN has been issued and before SETLOCK RELEASE has been issued, your FRR must either issue SETLOCK RELEASE,TYPE=VSMFIX or must issue the SETLOCK and SETRP macros as follows:
```
       SETLOCK TEST,TYPE=VSMFIX,BRANCH=(NOTHELD,NOVSMFIX)
       SETRP FRELOCK=VSMFIX
NOVSMFIX DS 0H
```
Note:
1. Your program will be disabled for I/O and external interrupts from the time the SETLOCK OBTAIN completes until the SETLOCK RELEASE completes. See the descriptions of the SETLOCK and SETRP macros for additional usage information.
2. Your program and your FRR must not issue any of the following macros before issuing SETLOCK RELEASE,TYPE=VSMFIX:
  - GETMAIN
  - FREEMAIN
  - STORAGE
For CPOOLPAG requests, issue the SETLOCK macro right before and right after the VSMLOC request, as follows:
```
SETLOCK OBTAIN,TYPE=VSMPAG,MODE=UNCOND
VSMLOC request
SETLOCK RELEASE,TYPE=VSMPAG
```
If your program is covered by a functional recovery routine (FRR) and the FRR receives control after SETLOCK OBTAIN has been issued and before SETLOCK RELEASE has been issued, your FRR must either issue SETLOCK RELEASE,TYPE=VSMPAG or must issue SETLOCK and SETRP macros as follows:
```
       SETLOCK TEST,TYPE=VSMPAG,BRANCH=(NOTHELD,NOVSMPAG)
       SETRP FRELOCK=VSMPAG
NOVSMPAG DS 0H
```
Note:
1. Your program will be disabled for I/O and external interrupts from the time the SETLOCK OBTAIN completes until the SETLOCK RELEASE completes. See the descriptions of the SETLOCK and SETRP macros for additional usage information.
2. Your program and your FRR must not issue any of the following macros before issuing SETLOCK RELEASE,TYPE=VSMPAG:
  - GETMAIN
  - FREEMAIN
  - STORAGE

ABEND codes

The VSMLOC macro might issue abend code X'C78'. For detailed abend code information, see z/OS MVS System Codes.

Return and reason codes

When the VSMLOC macro returns control to your program, GPR 15 contains one of the following hexadecimal return codes:

Table 1. Return Codes for the VSMLOC Macro
Return Code	Meaning and Action
0	Meaning: Successful completion. The specified virtual storage area is allocated. Action: None.
4	Meaning: Possible program error. The specified virtual storage area is: Not allocated. Overlaps free space. Overlaps other subpools. Action: This return code is not a program error if you have issued VSMLOC to determine whether the storage at the specified address is currently allocated and the system indicates that it is not. This return code signifies a program error if you expected the specified storage area to be allocated and the system reports one of the conditions listed above. If this is an error, you need to determine why the storage area is in the indicated state. Possible reasons include: The storage area address or length is not valid. The storage has been freed by another program. The storage was in a subpool that is automatically freed by the system and the system has freed the storage.
8	Meaning: System error. The system encountered an error while scanning virtual storage management data areas. This return code is obtained only by users who specify LINKAGE=SYSTEM. Action: Notify system support personnel that there might be an error in virtual storage management's control structure. If there is a problem with VSM's control structure, the entire system will be adversely affected and you might have to wait until the problem is identified and resolved. System support personnel should request a dump of the virtual storage management control structure and contact IBM® support. If the problem appears to involve common storage, the contents of common storage should be dumped to view the VSM control structure. If the problem appears to involve private storage, private storage should be dumped.
C	Meaning: Program error. You have specified a parameter incorrectly. This return code is obtained only by users who specify LINKAGE=BRANCH. Users who specify LINKAGE=SYSTEM receive a X'C78' abend for this error. Action: Ensure that the virtual storage area you have specified does not exceed 2 gigabytes. Verify that you have coded the parameters as required.
10	Meaning: System error. Internal system error. Action: Record the return code and notify IBM support personnel.

Example 1

Verify that the virtual storage, starting at the address given in register 2 and having a length specified in register 3, has been allocated in the SQA.

VSMLOC SQA,AREA=((2),(3))

Example 2

Verify that the 8-bytes of virtual storage starting at X have been allocated in the CSA. Use a PC instruction for linkage and let VSMLOC provide recovery and serialization.

VSMLOC CSA,AREA=(X,8),LINKAGE=SYSTEM

Example 3

Verify that the 8-bytes of virtual storage starting at the address specified in register 2 have been allocated in the LSQA. Use branch entry for linkage.

VSMLOC LSQA,AREA=((2),8),LINKAGE=BRANCH

Example 4

Verify that the virtual storage, starting at X and having a length specified in register 3, has been allocated in private area storage. Use branch entry for linkage.

VSMLOC PVT,AREA=(X,(3)),LINKAGE=BRANCH

Example 5

Verify that the 100 bytes of virtual storage starting at the address specified in register 1 have been allocated in private area storage. The address of the TCB associated with the storage verified is returned in register 4.

VSMLOC PVT,AREA=((1),100),TCB=(4),LINKAGE=BRANCH