Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly
Loading...

{{viewport.spaceProperty.prod}}

DSPSRV - Control a data space

&pagelevel(3)&pagelevel

General

Application area:

Extended addressing with data spaces; see "Extended addressing with data spaces"

Macro type:

Type S, MF format 3: C/D/L/M/R/E form; see "S-type macros"


The DSPSRV macro can be used all BS2000 servers
(see section “Extended addressing with data spaces”).

Macro description

The DSPSRV macro enables the user to create a data space by specifying type, name, scope and desired size. A user who creates a data space automatically becomes its owner. The system returns an identification (the SPID) that uniquely identifies the data space throughout the session. A program that is to access a data space must be connected to it via access lists. This connection is established by means of the ALESRV macro.

The data space type determines the kind of memory allocation/deallocation within the data space and the functions that are provided for this.

The functions of the DSPSRV macro make it possible to:

  • create a data space (FCT=CREATE),

  • release an existing data space (FCT=DESTROY),

  • request information on an existing data space (FCT=INFORM),

for a data space with type STACK:

  • extend an existing data space by adding memory pages (FCT=EXTEND) and

  • delete the contents of an existing data space (in some cases also in units of 4K), i.e. overwrite them with binary zeros (FCT=CLEAR)

  • reduce the current size of a data space (FCT=REDUCE)

for a data space with type HEAP:

  • allocate an area (FCT=GETAREA)

  • release an allocated area (FCT=RETAREA)

Macro format and description of operands

DSPSRV

FCT=

{ CREATE, NAME={'name' / name_addr}, INISIZE={number / (r)}

,MAXSIZE={number / (r)}, DIAPROT={NO / YES}

,SCOPE={LOCAL / GROUP / USER_GROUP / GLOBAL}

,TYPE={STACK / HEAP} /

DESTROY,SPID=spid_addr

INFORM,IDENT={NAME / SPID} [,SPID=spid_addr][,NAME={'name' / name_addr}]

,SCOPE={LOCAL / GROUP / USER_GROUP / GLOBAL} /

EXTEND,SPID=spid_addr ,SIZE={number / (r)} /

CLEAR,SPID=spid_addr,AREA={area_addr / (r)} ,SIZE={number / (r)} /

REDUCE,SPID=spid_addr, SIZE={number / (r)} /

GETAREA,SPID=spid_addr, SIZE={number / (r)} /

RETAREA,SPID=spid_addr, AREA={area_addr / (r)} ,SIZE={number / (r)} }

[,MF={C / D / L / M / E / R}[,SPID=spid_addr][,EXTADDR=ext_addr][.AREA=area_addr]]

[,PARAM={addr / (r)}]

,PREFIX={N / p}

,MACID={VDD / macid}

The operands are described in alphabetical order below.

AREA=
Specifies the start address of a data space area. This operand can be both input operand (FCT=RETAREA, CLEAR) and output operand (FCT=GETAREA).
The address must be aligned on a page boundary (4K) and be located within the area of the generated data space.

area_addr
Symbolic address (name) of a 4-byte field containing the start address of the area.

(r)
Register containing the start address value “addr”.

DIAPROT=

Specifies whether the data space is to be protected against access by diagnostic tools (e.g. AID, USERDUMP, CDUMP2).

NO
The data space is not protected, i.e. diagnostic tools may access it.

YES
The data space is to be given special protection. Diagnostic tools may not access it.

EXTADDR=
Specifies the start address of the data space to be extended. This operand is an output operand (only with MF=R).

ext_addr
Address for outputting the start address of the new memory space extension (with FCT=EXTEND).

FCT=
Specifies which of the functions of the DSPSRV macro is to be executed.

CREATE
Creates a new data space. The caller becomes the owner of the data space.
With return code X'aaaa'=X'0000', the system returns the SPID. This can be read from the parameter list with MF=R.

DESTROY
Releases an existing data space, provided that the caller is also the owner of the data space.

EXTEND
Extends an existing data space of type STACK by adding 4K memory pages. For information on the size of the data space, see the notes on address space size.
With return code X'aaaa'=X'0000', the system returns the start address of the memory space extension (EXTADDR). This can be read from the parameter list with MF=R. The allocated area within the data space is cleared to binary zeros.

CLEAR
Deletes the contents of a data space area of type STACK by overwriting memory pages in units of 4K with binary zeros. The deleted memory pages are no longer retained in real memory (paging memory).

INFORM
Provides information on the data space specified by means of its name and scope or SPID. The DSECT generated with MF=D contains all information.

REDUCE
Reduces the current size of a data space of type STACK in 4 K units.

GETAREA

Allocates an area within a data space of type HEAP.
With return code X'aaaa'=X'0000', the system returns the start address of the area (AREA). This can be read from the parameter list with MF=R. The allocated area within the data space is cleared to binary zeros.

RETAREA
Releases an allocated area within a data space of type HEAP.

IDENT=
Specifies which operands (NAME and SCOPE or SPID) are to be used to identify the data space (if FCT=INFORM).

NAME
The data space is identified by means of its name and scope.

SPID
The data space is identified by means of its SPID.

INISIZE=
Specifies the initial size of the requested data space in units of 4K.
For information on the size of the data space, see the notes on address space size and allocation size on "DSPSRV - Control a data space".

number
Positive integer (X'01' .. X'80000') specifying the initial size of the data space.

(r)
Register containing the “number”.

MAXSIZE=
Specifies the maximum desired size of the requested data space in units of 4K.
For a data space of the type HEAP the specified size is rounded up to the next MB boundary.
A data space does not have to reach the maximum size specified here; this value simply sets an upper limit. The maximum permitted size depends on the maximum address space size (ADDRESS-SPACE-LIMIT) specified in the user catalog (see the notes on address space size).

number
Positive integer (X'01' .. X'80000') specifying the maximum size of the data space.

(r)
Register containing the “number”.

MF=

For a general description of the MF operand, its operand values and any subsequent operands (e.g. PREFIX, MACID and PARAM), see "S-type macros". The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.

A PREFIX can be specified in the C form, D form, R form or M form of the macro and additionally a MACID in the C form, R form or M form (see "S-type macros").

MF=R enables the output parameters of the functions CREATE (SPID=),
INFORM (SPID=), EXTEND (EXTADDR=) and GETAREA (AREA=) to be read from the parameter area.

NAME=
Specifies the name of the data space. Length = 1..54 alphanumeric characters, the first of which must be a letter or one of the characters # or @.
The name of a data space is unique only within its scope (see the SCOPE operand),
i.e. there may be data spaces with the same name but with different scopes.

'name'
Name of the data space.

name_addr
Symbolic address (name) of a field (54 byte) containing the name of the data space in alphanumeric characters.

SCOPE=
Defines the scope of the specified data space. The name of a data space identifies the data space uniquely only within the specified scope.
The scope determines which tasks can participate in the specified data space, i.e. access it.

LOCAL
Use of the data space is limited to the task which created it. Other tasks may not access it.

GROUP
All tasks with the user ID of the task that created the data space can be connected to the data space.

USER_GROUP
All tasks belonging to the same user group as the user ID of the task that created the data space can use the data space, provided that the SRPM has been loaded.

GLOBAL
All the tasks in the system can access the data space.

SIZE=

Specifies the size of the data space area for the functions EXTEND, REDUCE, CLEAR, GETAREA and RETAREA. This operand is specified in units of 4K.
The following points must be taken into account:

  • if FCT=EXTEND: The data space extended by SIZE may not exceed the size specified in MAXSIZE; see the notes on address space size on "DSPSRV - Control a data space".

  • if FCT=CLEAR/RETAREA: The area defined by AREA and SIZE must be located within an existing data space identified by means of its SPID.

  • if FCT=REDUCE: The value of SIZE may not be greater than the current size of the data space.

  • if FCT=GETAREA: The sum of all allocated areas may not be greater than specified in MAXSIZE.

    number
    Positive integer >= 1 that defines the number of 4K units to be added to the data space (FCT=EXTEND) or deleted (FCT=CLEAR).

    (r)
    Register containing the address value of “number”.

SPID=
Identifies a data space uniquely throughout the system.
The system assigns the SPID when a data space is created. This operand may be an input or output operand.

spid_addr
Symbolic address (name) of an 8-byte field containing the SPID of the data space.

TYPE=
Determines the type of memory allocation/deallocation within the data space. This is determined at generation time.

STACK
A data space of the type STACK is an allocated area that is contiguous in virtual terms, starting with address 0 and going up to the current size.
The allocation functions available are EXTEND, REDUCE and CLEAR. The GETAREA and RETAREA functions are rejected.

HEAP
A data space of the type HEAP is a virtual address space in which areas of any required size can be allocated dynamically up to the maximum size of the data space. The allocation functions available are GETAREA and RETAREA. The EXTEND, REDUCE and CLEAR functions and the INISIZE parameter are rejected.

Note

DIV (Data in Virtual) functionality is only supported in data spaces of the type STACK.

Notes on the macro call

  • The SPID may be an input or output operand, i.e. it is placed in the generated parameter list as an output operand with FCT=CREATE or FCT=INFORM and, the next time this parameter list is used, is also valid as an input operand. The same applies for the AREA operand in the functions GETAREA and RETAREA.

  • The sum of the memory pages already occupied by the task and the additional memory pages requested by DSPSRV may not exceed the maximum address space size (ADDRESS-SPACE-LIMIT) entered in the user catalog for the owner. The same applies to the MAXSIZE specification.
    The command SHOW-USER-ATTRIBUTES PUBSET=*HOME can be used to obtain information on the user's own address space size. If the address space is full, a storage space error is reported and the function is aborted.

  • On termination of the program that created the data space, the data space is released automatically, i.e. without FCT=DESTROY. The SPID is no longer valid; any remaining ALETS, however, are not deleted. If another program uses one of these ALETs to attempt to access a data space that no longer exists, the program will be terminated.

  • If a data space to be deleted still contains DIV windows, these windows must be closed before the data space can be released.

Notes on address space size

  • Any specification for creating or extending data spaces may not exceed the maximum address space size specified in the user catalog. This means that the sum of all memory requests must be less than or equal to the address space size given in the ADDRESS-SPACE-LIMIT field. The sum of all memory requests is calculated from:

  • the class 6 memory pages allocated in the program space,

  • the allocated pages that were requested for existing data spaces,

  • the pages requested in the current DSPSRV macro (with INISIZE and MAXSIZE when creating a data space or with SIZE when extending a data space).

  • The maximum size specified for a data space when it is created (MAXSIZE) must be greater than or equal to the initial data space size specified for INISIZE.
    The size specified in SIZE when extending a data space (together with INISIZE and any memory pages that were added previously with FCT=EXTEND) may not exceed MAXSIZE.

Return information and error flags

Standard header:

+---------------+
|   |   |   |   |
|c|c|b|b|a|a|a|a|

+---------------+

A return code relating to the execution of the DSPSRV macro is transferred in the standard header (cc=Subcode2, bb=Subcode1, aaaa=Maincode):

X'cc'

X'bb'

X'aaaa'

Meaning

X'00'

X'00'

X'0000'

Function executed successfully.
The following values can be read from the parameter list with MF=R:

  • if FCT=CREATE: spid_addr (SPID operand)

  • if FCT=EXTEND: ext_addr (EXTADDR operand)

  • if FCT=INFORM: spid_addr (SPID operand)

  • if FCT=GETAREA: area_addr (AREA operand)

X'02'

X'00'

X'0001'

Warning: the specified data space has been released even though other
programs are connected to it (if FCT=DESTROY).

X'00'

X'01'

X'0003'

Invalid FCT operand.

X'01'

X'01'

X'0003'

Invalid NAME operand.

X'02'

X'01'

X'0003'

Invalid SCOPE operand.

X’04’

X’01’

X’0003’

Invalid TYPE operand

X'05'

X'01'

X'0003'

Invalid IDENT operand.

X'06'

X'01'

X'0003'

Invalid MAXSIZE operand.

X'07'

X'01'

X'0003'

Invalid INISIZE operand.

X'0A'

X'01'

X'0003'

Invalid DIAPROT operand.

X'0C'

X'01'

X'0003'

Invalid AREA operand.

X'0D'

X'01'

X'0003'

Invalid combination of operands.


X'20'

X'0005'

Internal error.

X'00'

X'40'

X'000D'

DIV application running: the data space contains DIV windows (if
FCT=DESTROY).

X'00'

X'40'

X'0102'

Invalid specification of NAME operand. A data space with the specified
name already exists (only if FCT=CREATE).

X'00'

X'40'

X'0104'

Invalid specification of NAME and/or SCOPE (if FCT=INFORM).

X'00'

X'40'

X'0106'

Maximum load reached for paging memory.

X'00'

X'40'

X'0107'

The maximum address space available to the task (ADDRESS-SPACE-
LIMIT in user catalog) has been exceeded. Invalid specification of
INISIZE or MAXSIZE (if FCT=CREATE) or SIZE (if FCT=EXTEND).

X'00'

X'40'

X'0202'

Error in SCOPE=USER_GROUP: the SRPM subsystem is not loaded
(if FCT=CREATE).

X'00'

X'40'

X'0206'

Maximum load reached for main memory.

X'00'

X'40'

X'0302'

The calling task is not the owner of the data space and may not delete it
(if FCT=DESTROY).

X'00'

X'40'

X'0304'

Incorrect specification of SPID operand.
The specified data space does not exist or the caller is not authorized to
access this data space.

X'00'

X'40'

X'0306'

Maximum number of data spaces reached (if FCT=CREATE).

X'00'

X'40'

X'0404'

Error in TYPE. The data space type is invalid for the specified function.

X'00'

X'40'

X'0406'

Address space saturation. There is insufficient free and contiguous
address space available in the data space to satisfy the requirements
(with FCT=GETAREA)

X'00'

X'40'

X'0604'

Invalid MAXSIZE operand:

  • maximum data space size exceeded (if FCT=EXTEND).

  • the specified size is greater than the current size of the data space
    (with FCT=REDUCE).

  • the specified size is greater than the maximum size of the data
    space (with FCT=GETAREA)

X'00'

X'40'

X'0C04'

The specified area is not a part of the data space (if FCT=CLEAR or
RETAREA).

X'00'

X'40'

X'0F04'

Allocation error. The area specified is not allocated within the data space
(with FCT=RETAREA).

X'00'

X'81'

X'0106'

Maximum load reached for paging memory.

X'00'

X'81'

X'0306'

Internal shortage of resources.

Other return codes which, in accordance with conventions, apply to all macros are given in the table “Standard return codes” (Standard header).

For an example see section “Extended addressing with data spaces”.

Powered by Atlassian Confluence and Scroll Viewport.