Skip to content

Storage services

Macro reference

SVC functions

The following is a list of the z390 SVC services that support the macros.

DEC HEX Service
4 04 GETMAIN
4 04 GETVIS (VSE)
5 05 FREEMAIN
5 05 FREEVIS (VSE)

Supporting macros

  • STORAGE - Obtain/release storage
  • CPOOL - Obtain a storage area

STORAGE - Obtain/release storage

name     STORAGE OBTAIN,LENGTH=,LOC=,COND=  Acquire storage
name     STORAGE RELEASE,ADDR=,LENGTH=      Free storage

An alternative to GETMAIN and FREEMAIN.

  • LENGTH= becomes the GETMAIN/FREEMAIN parameter LV=
  • LOC= is the same
  • COND=NO (default) is the GETMAIN type R
  • COND=YES is the GETMAIN type RC
  • ADDR= becomes the GETMAIN/FREEMAIN parameter A

GETMAIN - Acquire storage

name     GETMAIN type,LV=,LOC=,A=

Parameters

type
Value Description
R Obtain storage unconditionally. The default location is below 16M.
RC Obtain storage conditionally. The default location is above 16M. The return code indicates whether the acquisition was successful.
RU Obtain storage unconditionally. The default location is above 16M.
LV
Value Description
LV=n Obtain n bytes (maximum value of n is 2G-1)
LV=nK Obtain nK bytes (maximum value of n is 2097151)
LV=nM Obtain nM bytes (maximum value of n is 2047)
LV=(reg) Length required is in GR reg

Note

All storage requests will be rounded up to the next 8-byte boundary and is not initialized.

LOC (optional)

If omitted:

  • type=R default to LOC=ABOVE
  • type=RC default to LOC=BELOW
  • type=RU default to LOC=BELOW
Value Description
LOC=BELOW
LOC=RES
LOC=24
LOC=(24)
Try to acquire storage below 16M.
LOC=ABOVE
LOC=ANY
LOC=31
LOC=(31)
LOC=(24,31)
Try to acquire storage above 16M.
A (optional)

After successful completion GR1 will contain the address of the acquired storage. This 4-byte address may be placed at label, or at the address in GRreg.

The length will be returned in GR0, rounded as necessary.

Usage

GETMAIN 1024 bytes below 16M, unconditionally.

         GETMAIN R,LV=1024

GETMAIN number of bytes in GR3 below 16M, conditionally,

         GETMAIN RC,LV=(R3),LOC=BELOW

Memory allocation

Storage is limited by the MEM(nnn) parameter on ez390 with nnn in megabytes. The default is MEM(1).

When the value is 16 or less then all GETMAINs will allocate storage LOC=BELOW.

When the value is above 16, then 16M bytes is available LOC=BELOW and the rest LOC=ABOVE.

There is a preset maximum of MEM(50) set by Java. If this is insufficient, then code -Xmx nnnnnnnnn after the -Xrs option on ez390 to extend the MEM limit.

Warning

Over-extending memory this way may degrade the performance of your operating system.

Register Usage

  • R0 = Input flags, output length
  • R1 = Input length, output address
  • R15= Return code

Return

GR15 has a return code:

  • 0 - GETMAIN ok
  • 4 - Conditional request unsuccessful

Abends

  • S804 Invalid request - Can occur if LRECL/BLKSIZE on a DCB are both zero
  • S80A Unconditional out of memory

GETVIS - Acquire storage (VSE)

name     GETVIS LENGTH=,ADDRESS=,LOC=

All forms map to GETMAIN R

LENGTH and ADDRESS are mandatory.

Parameters map to GETMAIN as follows:

  • LENGTH=n Maps to LV=n
  • LENGTH=(reg) Maps to LV=(reg)
  • ADDRESS=label Maps to A=label
  • ADDRESS=(reg) GR reg is not a pointer, the GETMAINd area
  • address is placed in GR reg.
  • LOC= Maps the same.

Register Usage

  • R0 = Input flags, output length
  • R1 = Input length, output address
  • R15= Return code

Return

GR15 has a return code:

  • 0 - GETVIS ok

Abends

  • S804 Invalid request - Can occur if LRECL/BLKSIZE on a DCB are both zero
  • S80A Unconditional out of memory

FREEMAIN - Free storage

name     FREEMAIN LV=,LA=,A=

Specify either LV= or LA=, if both are present LV= will be ignored.

Parameters

LV
Value Description
LV=n Free n bytes (maximum value of n is 2G-1)
LV=nK Free nK bytes (maximum value of n is 2097151)
LV=nM Free nM bytes (maximum value of n is 2047)
LV=label label must be an equated value
LV=(reg) Length to be freed is in GRreg
LA
Value Description
LA=label The location of a 4-byte length
LA=(reg) GR reg must point to a 4-byte length
A (optional)

If A= is omitted then GR1 must contain the address of the storage to be freed.

Value Description
A=label The location of the 4-byte address of the storage to be freed.
A=(reg) The 4-byte address of the storage to be freed is in GR reg.

Note

The storage address specified must be on a doubleword boundary. A section of a previous GETMAIN may be freed. It is the programmer's responsibility to manage the resulting fragmentation.

Register Usage

  • R0 = length
  • R1 = address
  • R15= return code

Return

GR15 has a return code:

  • 0 - FREEMAIN ok

Abends

  • S804 Invalid request
  • S90A Attempt to FREEMAIN an area which is not on a doubleword boundary
  • SA0A Attempt to FREEMAIN an area already free

FREEVIS - Free storage (VSE)

name     FREEVIS LENGTH=,ADDRESS=

All forms map to FREEMAIN R

Defaults are LENGTH=(0) and ADDRESS=(1).

Parameters map to FREEMAIN as follows:

  • LENGTH=n Maps to LV=n
  • LENGTH=(reg) Maps to LV=(reg)
  • ADDRESS=label Maps to A=label
  • ADDRESS=(reg) Maps to A=(reg)

Register Usage

  • R0 = length
  • R1 = address
  • R15= return code

Return

GR15 has a return code:

  • 0 - FREEVIS ok

Abends

  • S804 Invalid request

CPOOL - Obtain a storage area

         CPOOL BUILD,CPID=label,PCELLCT=nnn, SCELLCT=nnn,CSIZE=nnn,HDR='...'

BUILD obtains a storage area divided into cells. Each subsequent GET retrieves the next cell.

Warning

FREE and DELETE are not yet implemented.

  • CPID will contain the address of the GET routine for this cell
  • PCELLCT contains the primary number of cells
  • SCELLCT contains the secondary number of cells
  • CSIZE is the size of each cell
  • HDR is an optional string to identify the pool

The GETMAIN size will be (PCELLCT+SCELLCT)*CSIZE

         CPOOL GET,CPID=label

Get the next cell in this pool, GR1 contains the address or zero if all cells have been read.

Back to top