REQUEST=GETSTOR allows you to create a memory object. To avoid an abend for exceeding a MEMLIMIT, specify the COND=YES parameter.
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Problem state and PSW key 8-15. |
Dispatchable unit mode: | Task or SRB |
Cross memory mode: | Any PASN, any HASN, any SASN A 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: | Enabled for I/O and external interrupts |
Locks: | No locks may be held. |
Control parameters: | Control parameters must be in the primary address space. |
None.
No data space ALETs can be specified.
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 | |
,SEGMENTS=segments | segments: RS-type address or address in register (2) - (12). |
,FPROT=YES | Default: FPROT=YES |
,FPROT=NO | |
,SVCDUMPRGN=YES | Default: SVCDUMPRGN=YES |
,SVCDUMPRGN=NO | |
,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 |
,ORIGIN=origin | origin: RS-type address or address in register (2) - (12). |
,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 | |
,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:
To code: Specify the RS-type address, or address in register (2)-(12), of a doubleword field.
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 non-zero 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 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.
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.