REQUEST=GETSTOR allows you to create a memory object. To avoid an abend for exceeding MEMLIMIT, specify the COND=YES parameter.
The requirements for the caller are:
| Environmental factor | Requirement |
|---|---|
| Minimum authorization: | Supervisor state or with PSW key 0-7. To
use the PAGEFRAMESIZE parameter, a caller can be in problem state
with either one of the following authorizations:
|
| Dispatchable unit mode: | Task or SRB |
| Cross memory mode: | Any PASN, any HASN, any SASN Note: The problem
state caller running in PSW key 8-15 can use GETSTOR/DETACH only when
the primary address space is the home address space.
|
| AMODE: | 31- or 64-bit |
| ASC mode: | Primary or access register (AR) |
| Interrupt status: |
|
| Locks: | A local lock may be held, subject to the following
limitation: When a local lock is held for a request (GETSTOR, SHAREMEMOBJ, DETACH, CHANGEGUARD, or DISCARDDATA) the lock must be for the address space specified or set as the default by the input ALETVALUE. |
| Control parameters: | Control parameters must be in the primary address space and can reside both below and above the bar. |
None
This macro supports multiple versions. Some keywords are unique to certain versions. See PLISTVER parameter description.
Before issuing the IARV64 macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
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.
None
The REQUEST=GETSTOR option of the IARV64 macro is written as follows:
| Syntax | Description |
|---|---|
| name | name: symbol. Begin name in column 1. |
| ␢ | One or more blanks must precede IARV64. |
| IARV64 | |
| ␢ | One or more blanks must follow IARV64. |
| REQUEST=GETSTOR | |
| ,COND=NO | Default: COND=NO |
| ,COND=YES | |
,LOCALSYSAREA=NO |
Default: LOCALSYSAREA=NO |
,LOCALSYSAREA=YES |
|
| ,SEGMENTS='segments' | segments: RS-type address or address in register (2) - (12). |
| ,TYPE=DREF | |
| ,TYPE=PAGEABLE | Default: TYPE=PAGEABLE when one of
the following is specified:
|
| ,PAGEFRAMESIZE=4K | Default: PAGEFRAMESIZE=4K |
| ,PAGEFRAMESIZE=1MEG | |
| ,PAGEFRAMESIZE=MAX | |
| ,PAGEFRAMESIZE=PAGEABLE1MEG | |
| ,PAGEFRAMESIZE=DREF1MEG | |
| ,UNITS=units | units: Size of the memory object, which is the number of units specified by UNITSIZE. |
| ,UNITSIZE=1M | Specifies a 1 MB unit size. |
| ,PAGEFRAMESIZE=4K|1M | If UNITSIZE=1M is specified, a PAGEFRAMESIZE of 4K or 1M must be specified. There is no default value. |
| ,UNITSIZE=2G | Specifies a 2 GB unit size. |
| ,PAGEFRAMESIZE=4K|1M|2G | If UNITSIZE=2G is specified, a PAGEFRAMESIZE of 4K, 1M or 2G must be specified. There is no default value. |
| ,TYPE=FIXED | |
| ,TYPE=DREF | |
| ,TYPE=PAGEABLE | |
| ,KEY=key | key: RS-type address or address in register (2) - (12). |
| ,KEY=CALLERKEY | Default: KEY=CALLERKEY |
| ,FPROT=YES | Default: FPROT=YES |
| ,FPROT=NO | |
| ,MEMLIMIT=NO | Default: MEMLIMIT=YES |
| ,MEMLIMIT=YES | |
| ,SVCDUMPRGN=YES | Default: SVCDUMPRGN=YES |
| ,SVCDUMPRGN=NO | |
| ,DUMP=LIKERGN | Default: DUMP=LIKERGN |
,DUMPPRIORITY=99 |
Default: DUMPPRIORITY=99 |
,DUMPPRIORITY=dumppriority |
|
| ,DUMP=LIKELSQA | |
| ,DUMP=NO | |
| ,DUMP=BYOPTIONVALUE | |
| ,OPTIONVALUE=option | option: RS-type address or address in register (2) - (12). |
| ,CONTROL=UNAUTH | Default: CONTROL=UNAUTH |
| ,CONTROL=AUTH | |
| ,MOTKNSOURCE=USER | Default: MOTKNSOURCE=USER |
,MOTKN=motkn |
Default: MOTKN |
,MOTKNCREATOR=USER |
Default: MOTKNCREATOR=USER |
,MOTKNCREATOR=SYSTEM |
|
,USERTKN=NO_USERTKN |
Default: USERTKN=NO_USERTKN |
,USERTKN=usertkn |
usertkn: RS-type address or address in register (2) - (12). |
| ,MOTKNSOURCE=SYSTEM | |
,OUTMOTKN=outmotkn |
Outmotkn: RS-type address or address in register (2) - (12). |
| ,USERTKN=usertkn | usertkn: RS-type address or address in register (2) - (12). |
| ,USERTKN=NO_USERTKN | Default: USERTKN=NO_USERTKN |
| ,GUARDSIZE=guardsize | guardsize: RS-type address or address in register (2) - (12). |
| ,GUARDSIZE=0 | Default: GUARDSIZE=0 |
| ,GUARDSIZE64=guardsize64 | guardsize64: RS-type address or address in register (2) - (12). |
| ,GUARDSIZE64=0 | Default: GUARDSIZE64=0 |
| ,GUARDLOC=LOW | Default: GUARDLOC=LOW |
| ,GUARDLOC=HIGH | |
| ,TTOKEN=ttoken | ttoken: RS-type address or address in register (2) - (12). |
| ,TTOKEN=NO_TTOKEN | Default: TTOKEN=NO_TTOKEN |
| ,ALETVALUE=aletvalue | aletvalue: RS-type address or address in register (2) - (12). |
| ,ALETVALUE=0 | Default: ALETVALUE=0 |
| ,ORIGIN=origin | origin: RS-type address or address in register (2) - (12). |
| ,DETACHFIXED=NO | Default: DETACHFIXED=NO |
| ,DETACHFIXED=YES | |
| ,RETCODE=retcode | retcode: RS-type address or register (2) - (12). |
| ,RSNCODE=rsncode | rsncode: RS-type address or register (2) - (12). |
| ,PLISTVER=IMPLIED_VERSION | Default: PLISTVER=IMPLIED_VERSION |
| ,PLISTVER=MAX | |
| ,PLISTVER=0, 1, 2, 3, 4,5 | |
| ,MF=S | Default: MF=S |
| ,MF=(L,list addr) | list addr: RS-type address or register (1) - (12). |
| ,MF=(L,list addr,attr) | |
| ,MF=(L,list addr,0D) | |
| ,MF=(E,list addr) | |
| ,MF=(E,list addr,COMPLETE) | |
The parameters are explained as follows:
If the key is not specified, the storage key of the memory object is the same as the caller's PSW key. The default is CALLERKEY.
To code: Specify the RS-type address, or address in register (2)-(12), of a one-byte field.
SEGMENTS and UNITS are mutually exclusive keys. This set is required; only one key can be specified.
A required input parameter that specifies the size of the memory object requested, in megabytes. This must be a nonzero value. The amount of storage requested that is not in the guard state is charged against the MEMLIMIT for the address space where the memory object is to be created.
To code: Specify the RS-type address, or address in register (2)-(12), of a doubleword field.
The default value is TYPE=DREF when PAGEFRAMESIZE=DREF1MEG is specified. If PAGEFRAMESIZE=1MEG or PAGEFRAMESIZE=MAX is specified and the memory object is backed with 1 MB-page frames, the 1 MB-pages backing this memory object are fixed.
UNITS and SEGMENTS are mutually exclusive keys. This set is required; only one key can be specified.
A required input parameter that specifies the size of the memory object as a number of units specified by the UNITSIZE parameter. This must be a nonzero value. The amount of storage requested that is not in the guard state is counted towards the MEMLIMIT for the address space where the memory object will be created. UNITS belongs to a set of mutually exclusive keys. This set is required; only one key can be specified.
To code: Specify the RS-type address, or address in register (2)-(12), of a doubleword field.
SVCDUMPRGN and DUMP are mutually exclusive keys. This set is optional; only one key may be specified.
An optional input parameter that specifies whether the memory object should be included in an SVC dump when region is requested. The default is SVCDUMPRGN=YES.for TYPE=PAGEABLE. If neither the SVCDUMPRGN keyword nor the DUMP keyword is specified the defaults that apply are as described under the defaults for the DUMP keyword.
DUMP and SVCDUMPRGN are mutually exclusive keys. This set is optional; only one key may be specified.
An optional input parameter that specifies whether the 64-bit private memory object will be included in an SVC dump when RGN or LSQA is specified on SDATA. When TYPE=PAGEABLE is specified on IARV64 GETSTOR the default is DUMP=LIKERGN. When TYPE=DREF is specified on IARV64 GETSTOR the default is DUMP=LIKELSQA. For memory objects backed with large pages the default is DUMP=NO.
This is a permanent attribute of the memory object and cannot be altered by other services. The default is CONTROL=UNAUTH.
The user provides the memory object token.
The following is a set of mutually exclusive keys. This set is optional; only one key may be specified.
This parameter belongs to a set of mutually exclusive keys. It is the name of an optional doubleword integer input that identifies the user token to be associated with the memory object. This can be used on a later DETACH request to free all memory objects associated with this value.
IARV64 REQUEST(GETCOMMON) MOTKNSOURCE(SYSTEM) OUTMOTKN(mytoken)IARV64 REQUEST(GETCOMMON) MOTKNSOURCE(USER) MOTKN(mytoken)To avoid inadvertent collisions in the values specified, the left word (bits 0-31) of the user token must be binary zeros for a problem state program. The system enforces this requirement. The right word (bits 32-63) should represent the virtual address of some storage related to the caller, which could be a control block address, an entry point address, and so on, which is used as an application choice.
The convention for supervisor state program is that the left word (bits 0-31) should represent an address of some storage related to the caller. The system enforces the rule that the left word is nonzero for supervisor state callers. The format for the right word (bits 32-63) is a choice left to the caller.
If you specify no user token, the default is that no user token is supplied to associate this memory object with others.
To avoid inadvertent collisions in the values specified, the left word (bits 0-31) of the user token must be binary zeros for a problem state program. The system enforces this requirement. The right word (bits 32-63) should represent the virtual address of some storage related to the caller, which could be a control block address, an entry point address, and so on, which is used as an application choice.
The convention for supervisor state program is that the left word (bits 0-31) should represent an address of some storage related to the caller. The system enforces the rule that the left word is nonzero for supervisor state callers. The format for the right word (bits 32-63) is a choice left to the caller.
If you specify NO_USERTKN, the default is that no user token is supplied to associate this memory object with others. The default is NO_USERTKN.
To code: Specify the RS-type address, or address in register (2)-(12), of a doubleword field.
GUARDSIZE and GUARDSIZE64 are mutually exclusive keys. This set is optional; only one key may be specified. A fullword integer input parameter that indicates the number of megabytes of guard area to be created at the high or low end of the memory object. Guard areas cannot be referenced and when referenced will cause a program check. Guard area does not count against the MEMLIMIT. A guard area can be reduced through CHANGEGUARD CONVERT=FROMGUARD.
GUARDSIZE must not be larger than the size of the memory object. The default is 0.
To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field.
GUARDSIZE64 belongs to a set of mutually exclusive keys. This set is optional; only one key may be specified. A doubleword integer input parameter that indicates the number of megabytes of guard area to be created at the high or low end of the memory object. Guard areas cannot be referenced and when referenced will cause a program check. Guard area does not count against the MEMLIMIT. A guard area can be reduced through CHANGEGUARD CONVERT=FROMGUARD.
GUARDSIZE64 must not be larger than the size of the memory object. The default is 0.
To code: Specify the RS-type address, or address in register (2)-(12), of a doubleword field.
If TTOKEN is specified, the task identified by the TTOKEN becomes the owner of the memory object. If TTOKEN is not specified, the currently dispatched task becomes the owner of the memory object. The task identified by the TTOKEN must be in the address space specified or defaulted by the ALETVALUE keyword.
The TTOKEN parameter must be used by an caller that is an SRB.
When the TTOKEN parameter is used by problem state program with PSW key 8 - 15, the target task must represent the calling task OR the jobstep task for the calling task OR the mother task. A caller cannot assign ownership to a task above the jobstep task.
A memory object will be freed when its owning task terminates.
If the TTOKEN parameter is not specified, and the caller is a task (rather than an SRB), the currently dispatched task will become the owner of the memory object. An SRB will be abnormally ended if the TTOKEN parameter does not specify a valid TTOKEN. The default is NO_TTOKEN.
To code: Specify the RS-type address, or address in register (2)-(12), of a 16 character field.
The only supported values are 0 (primary) and 2 (home). The ALETVALUE parameter can be used only by callers running in supervisor state or with PSW key 0-7. The default is 0.
To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field.
To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.
To code: Specify the RS-type address of a fullword field, or register (2)-(12).
To code: Specify the RS-type address of a fullword field, or register (2)-(12).
If you can tolerate the size change, IBM® recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.
Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.
Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.