General
Application area: | Memory pools; see "Common memory areas shared by several users (Memory pools)" |
Macro type: | Type S, MF format 3: C/D/E/L/M form; see "S-type macros" |
A memory pool (MP) is a memory area (class 6 memory) that may be used by several users together. The user who creates the memory pool defines its size (position), designation (name) and memory attributes.
Information about the size of the memory pool and the number of memory pages allocated can be requested by means of the MINF macro.
Macro description
The SHOWMP macro informs about common memory pools that currently exist in the system. Local memory pools will not be output. The macro outputs the name, scope and number of connected tasks. The user can also request the TSNs of the connected tasks.
In all cases, a nonprivileged user will only see the nonprivileged memory pools that have a connected task for his user ID. The list of sharer tasks will only contain tasks with the user's own user ID.
The information can be narrowed down via the following parameters:
Output for a certain name or range of names
Output for a certain scope
Output for memory pools with certain characteristics
The user can also determine the maximum number of TSNs to be listed with the connected tasks (default setting is 45).
Privileged functions
Privileged users (TSOS or SW-MONITOR-ADMINISTRATION privilege) can access information on all memory pools. Also, all sharer tasks will be output, irrespective of the user ID. Privileged memory pools can be selected with the PRIV_POOL operand.
Macro format and description of operands
SHOWMP |
MF=D / E / L / C / M {,MPNAME={*ALL / '<name 1..54 with_wild>'} / [,MPNAMAD={A(name) / addrd / (r)} ,MPNAMLN={<integer 1..54> / <var: int:4> / (<reg: integer 1..54>)}] } ,SCOPE=*ANY / *GLOBAL / *GROUP / *USER-GROUP {,GROUP_USERID={*ANY / *OWN / '<name 1..8>' / <var: name 8..8> / (<reg: A(name 8..8)>)} / ,USER_GROUPID={*ANY / *OWN / '<name 1..8>' / <var: name 8..8> / (<reg: A(name 8..8)>)} } ,SELECT=*ALL / *PAR ,PRIV_POOL=*ANY / *YES / *NO ,CONNECT=*ANY / *BY-USER / *BY-TASK {,USERID={*OWN / '<name 1..8>' / <var: name 8..8> / (<reg: A(name 8..8)>)} / ,TSN={*OWN / '<name 1..4>' / <var: name 4..4> / (<reg: A(name 4..4)>)} } ,INFO=*STD / *ALL ,NUMSHR=45 / <integer 1..4096> / <var: int:4> / (<reg: integer 1..4096>) ,INFO_AREA=addr / (r) ,INFO_LENGTH=1 / <integer 1..1024> / <var: int:4> / (<reg: integer 1..1024>) [,PARAM=addr / (r)] ,PREFIX=N / p ,MACID=VPI / macid ,XPAND=PARAM / INFA ,EQUATES=YES / NO] |
MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. a prefix), see section “S-type macros”. The valid MF values are given at the beginning of the macro description under “Macro type” and are included in the macro format.
MPNAME=
Specifies the names of the memory pools to be output (note the connection with the SCOPE and SELECT operands).
Depending on the MF variant, the MPNAMAD operand may be used instead, see “Programming notes”.
*ALL
All memory pools are output.
'<name 1..54 with-wild>'
Only the specified memory pool is output. When using a wildcard, all memory pools with a name corresponding to the wildcard string will be output. The wildcard character is *. The first blank space marks the end of the name or wildcard string.
MPNAMAD=
Specifies the address of the field containing the name of the memory pool (note the connection with the SCOPE and SELECT operands). * is a valid wildcard. The first blank space marks the end of the name or wildcard string.
Depending on the MF variant, the operand MPNAME may be used instead, see “Programming notes”.
A(name)
Address of the field containing the name of the memory pool.
addr
Symbolic address (name) of an auxiliary field containing the address of the field containing the name of the memory pool (only for MF=M).
(r)
r = register with the address value of the field (only for MF=M).
MPNAMLN=
Defines the length of the name specified under MPNAMAD. Mandatory when using MPNAMAD. Otherwise, MPNAMLN will be ignored.
<integer 1..54>Length in bytes.
<var: int:4>
Symbolic address (name) of the field containing the length (only for MF=M).
(<reg: integer 1..54>)
reg = register containing the length (only for MF=M).
SCOPE=
Specifies whether only memory pools with a certain scope should be output.
*ANY
The memory pools will be output irrespective of their scope.
*GLOBAL / *GROUP / *USER_GROUP
Only memory pools with the specified scope will be output.
GROUP_USERID=*ANY / *OWN / '<name 1..8>' / <var: name 8..8> /
(<reg: A(name 8..8)>)
Operand will only be evaluated if SCOPE=*GROUP.
Only memory pools created with the indicated user ID will be output. *OWN designates the user ID of the calling task.
With *ANY, the output is pre-defined irrespective of the user ID.
'<name 1..8>'
Specification of the user ID.
<var: name 8..8>
Symbolic address (name) of the field containing the user ID (only for MF=M).
(<reg:A(name 8..8))
reg = register containing the address of the field containing the user ID (only for MF=M).
USER_GROUPID=*ANY / *OWN / '<name 1..8>' / <var: name 8..8> /
(<reg: A(name 8..8)>)
Operand will only be evaluated if SCOPE=*USER_GROUP.
Only memory pools created by the specified user group will be output. *OWN designates the user group to which the calling task belongs. With *ANY, the output is pre-defined irrespective of the user group.
'<name 1..8>'
Indication of the user group.
<var: name 8..8>
Symbolic address (name) of the field containing the name of the user group (only for MF=M).
(<reg:A(name 8..8))
reg = register containing the address of the field containing the name of the user group (only for MF=M).
SELECT=*ALL / *PAR
Specifies whether the number of memory pools defined by name and SCOPE should be further narrowed down through additional criteria (*PAR) or not (*ALL).
PRIV_POOL=*ANY / *YES / *NO
If SELECT=*PAR, this operand defines whether only privileged memory pools (*YES, only valid for privileged users) are to be output. If *NO, no privileged memory pools will be output. *ANY: both privileged and nonprivileged memory pools will be output.
CONNECT=
If SELECT=*PAR, this operand defines whether the memory pools will be filtered depending on their connected tasks. *ANY: memory pools will be output irrespective of their connected tasks.
*BY-USER
Only memory pools will be output that have a connected task with the user ID defined in the following USERID operand.
*BY-TASK
Only memory pools will be output that have the connected task with the TSN defined in the following TSN operand.
USERID=*OWN / '<name 1..8>' / <var: name 8..8> / (<reg: A(name 8..8)>)
Operand will only be evaluated for INFO=*ALL.
If CONNECT=*BY-USER, this operand specifies the user ID for the connected task. *OWN: the user ID of the caller. Only privileged users can view memory pools that have connected tasks with a user ID other than their own.
'<name 1..8>'
Specification of the user ID.
<var: name 8..8>
Symbolic address (name) of the field containing the user ID (only for MF=M).
(<reg:A(name 8..8))
reg = register containing the address of the field containing the user ID (only for MF=M).
TSN=*OWN / '<name 1..4>' / <var: name 4..4> / (<reg: A(name 4..4)>)
If CONNECT=*BY-TASK, this operand specifies the TSN for the connected task. *OWN: the TSN of the caller. Nonprivileged users can only specify tasks with their own user ID here.
'<name 1..4>' Specification of the TSN.
<var: name 4..4>
Symbolic address (name) of the field containing the TSN (only for MF=M).
(<reg:A(name 4..4))
reg = register containing the address of the field containing the TSN (only for MF=M).
INFO=
Defines the amount of information output.
*STD
The properties of the memory pools and the number of connected tasks will be output.
*ALL
In addition to the standard output, all connected tasks will be listed with their TSN. Nonprivileged users will only see the TSNs for their own user ID. Privileged users will see all TSNs.
NUMSHR=45 / <integer 1..4096> / <var: int:4> / (<reg: integer 1..4096>)Operand will only be evaluated for INFO=*ALL.
Defines the maximum number of tasks to be listed.
<integer 1..4096>
Specification of number of tasks.
<var: int:4>
Symbolic address (name) of the field containing the number of tasks (only for MF=M).
(<reg: integer 1..4096>)
reg = register containing the number of tasks (only for MF=M).
INFO_AREA=addr / (r)
Only for MF=M.
Specifies the address of the information output area. The area has to consist of one or more class 6 memory pages.
addr
Symbolic address (name) of an auxiliary field containing the address of the information output area.
(r)
r = register with the address value of the information output area.
INFO_LENGTH=1 / <integer 1..1024> / <var: int:4> / (<reg: integer 1..1024>)
Specification of the number of pages for this output.
<integer 1..1024>
Specification of the number of pages.
<var: int:4>
Symbolic address (name) of the field containing the number of pages (only for MF=M).
(<reg: integer 1..1024>)
reg = register containing the number of pages (only for MF=M).
XPAND=
Control operand only for MF=C and MF=D:
Specifies, which structure is to be expanded (created). For other MF values, this operand will be ignored.
PARAM
The layout of the parameter list will be expanded.
INFA
The layout of the information area will be expanded.
EQUATES=
Control operand only for MF=C and MF=D:
Specifies, whether, when expanding the parameter or information area, equates for the values of the fields of the parameter or information area are to be generated as well.
YES
When expanding the parameter or information area, equates for the values of the fields of the parameter or information area are to be generated.
NO
When expanding the parameter or information area, equates for the values of the fields of the parameter or information area are not to be generated.
Programming notes
There are three pairs of operands that may not be used together and that exclude each other: MPNAME and MPNAMAD, GROUP_USERID and USER_GROUPID, USERID and TSN. For these pairs, the following rule applies: the latest specification (in different MF variants) is valid and has to match the other operands.
In detail:
If MPNAME or MPNAMAD are specified, the latest of these specifications is valid (meaning from the latest MF=L- or MF=M call).
For SCOPE=*GROUP, the latest specification has to be GROUP_USERID (not USER_GROUPID).
For SCOPE=*USER_GROUP, the latest specification hat to be USER_GROUPID (not GROUP_USERID).
For SELECT=*PAR and CONNECT=*BY-USER, the latest specification has to be the USERID operand (not TSN).
For SELECT=*PAR and CONNECT=*BY-TASK, the latest specification has to be the TSN operand (not USERID).
Information about the memory pools is provided in the information area (INFO_AREA and INFO_LENGTH operands). There are also two more fields with output information in the parameter area:
If the function was executed successfully or partially, the number of memory pools for which information is provided in the information area is indicated in the
&P.NPOLfield.If the size of the class 6 memory (INFO_LENGTH operand) is not enough (return information: function partially executed. Information area too small), the required page number is provided in the parameter area (field
&P.INFX). It can be used for additional calls of SHOWMP, e.g. in a loop.The number of memory pools can change between two SHOWMP calls!
Layout of the parameter area
&P._MDL DSECT * subcode2 &P.NONE EQU 0 no further information &P.NOMP EQU 1 no memory pool found &P.NOCO EQU 2 no connection to memory pool &P.MNER EQU 3 error in MPNAME specification &P.MAER EQU 4 invalid MPNAMAD address &P.MLER EQU 5 invalid MPNAMLN value * specified &P.SCER EQU 6 error in SCOPE specification &P.SEER EQU 7 error in SELECT specification &P.PPER EQU 8 error in PRIV_POOL * specification &P.COER EQU 9 error in CONNECT * specification &P.GUER EQU 10 wrong USERID specified for * SCOPE=*GROUP &P.GRER EQU 11 wrong GROUPID specified for * SCOPE=*USER-GROUP &P.CUER EQU 12 wrong USERID specified for * CONNECT=*BY-USER &P.CTER EQU 13 wrong TSN specified for * CONNECT=*BY-TASK &P.IFER EQU 14 error in INFO specification &P.NSER EQU 15 error in NUMSHR specification &P.IAER EQU 16 invalid INFO_AREA address &P.ILER EQU 17 invalid INFO_LENGTH value * specified &P.FHDR FHDR MF=(C,&P.),EQUATES=NO Standardheader * main return codes &P.SUCC EQU 0 function processed * successfully &P.PART EQU 1 function processed only * partially &P.PAER EQU 2 parameter error &P.INER EQU 3 internal error &P.PRER EQU 4 privilege error &P.PSAT EQU 5 paging area saturation &P.MSAT EQU 6 main memory saturation &P.USAT EQU 7 user space saturation &P.SSAT EQU 8 system space saturation * &P.MPSS DS AL1 MPSHOW FLAG &P.MPNS EQU X'80' *ALL OR MP NAME SPECIFIED &P.CUSS EQU X'40' *OWN OR USERID SPECIFIED
&P.TSNS EQU X'20' *OWN OR TSN SPECIFIED &P.GUSS EQU X'10' *OWN/*ANY OR USERID SPECIFIED &P.GRPS EQU X'08' *OWN/*ANY OR GROUPID * SPECIFIED &P.GUOA EQU X'04' *ANY OR *OWN FOR USERID * SPECIFIED &P.GROA EQU X'02' *ANY or *OWN FOR GROUPID * SPECIFIED &P.RES1 EQU X'01' RESERVED * &P.COPE DS FL1 SCOPE OF SHOWMP * scope of memory pools &P.ANYS EQU 0 any memory pool scope &P.GRP EQU 1 memory pools of scope=group &P.UGRP EQU 2 memory pools of * scope=user-group &P.GLB EQU 3 memory pools of * scope=user-global * &P.SELE DS FL1 SELECTION OF SHOWMP * select memory pools &P.ALLS EQU 0 select all memory pool data &P.PAR EQU 1 select specific data * &P.CONM DS FL1 CONNECTION OF SHOWMP * select connected memory pools &P.ANYC EQU 0 select any memory pool &P.USER EQU 1 select memory pools of user * ID &P.TASK EQU 2 select memory pools of task * &P.PRPO DS FL1 PRIV-POOL OF SHOWMP * privilege of memory pools &P.ANYP EQU 0 select memory pools whether * privileged or no &P.YESP EQU 1 select only privileged memory * pools &P.NOP EQU 2 select only non-privileged * &P.INFM DS FL1 INFO OF SHOWMP * type of information &P.STD EQU 0 get data without TSN-list &P.ALLI EQU 1 get data with TSN-list * &P.MPNM DS CL54 MEMORY POOL NAME &P.MPNA DS A ADDRESS OF MEMORY POOL NAME &P.MPLN DS F LENGTH OF MPNAME &P.SCOPE_ID DS 0XL8 USER- OR GROUP_ID
&P.GUSI DS CL8 USER-ID BY SCOPE=GROUP ORG &P.SCOPE_ID &P.GRPI DS CL8 GROUP-ID BY SCOPE=USER-GROUP ORG &P.SCOPE_ID+8 &P.CONNECT_ID DS 0XL8 USER-ID OR TSN &P.USID DS CL8 USER-ID BY CONNECT=*BY-USER ORG &P.CONNECT_ID &P.TSN DS CL4 TSN BY CONNECT=*BY-TSN ORG &P.CONNECT_ID+8 &P.NRSH DS F # OF SHARER &P.INFP DS A ADDRESS OF INFO AREA &P.INFL DS F LENGTH OF INFO AREA IN PAGES &P.NPOL DS F NUMBER OF FOUND MEMORY POOLS &P.INFX DS F NEW LENGTH OF INFO AREA (PAGES) &P.# EQU *-&P.FHDR
Layout of the information area
&P.INFA DSECT * * info area description &P.NXTM DS A NEXT MEMORY POOL &P.MPNA DS CL54 MEMORY POOL NAME &P.MPSC DS FL1 SCOPE OF MEMORY POOL * scope of memory pools &P.GRPO EQU 1 memory pools of scope=group &P.UGRO EQU 2 memory pools of * scope=user-group &P.GLBO EQU 3 memory pools of * scope=global * &P.RES DS XL1 RESERVED BYTE &P.GUID DS CL8 GROUP- OR USER-ID &P.NSHR DS F # OF SHARER TASKS &P.STSN DS CL4 TSN OF SHARER &P.INFA# EQU *-&P.NXTM
Return information and error flags
Standard header:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
A return code relating to the execution of the SHOWMP 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' | Macro executed normally. |
X'01' | X'00' | X'0000' | Normal execution. No matching memory pool in the system |
X'02' | X'00' | X'0000' | Normal execution. Specified memory pool exists, but not connected |
X'00' | X'00' | X'0001' | Function partially executed. Information area too small. The required |
X'03' | X'01' | X'0002' | Error in MPNAME operand (also if MPNAMAD refers to a field with a |
X'04' | X'01' | X'0002' | Invalid address in MPNAMAD operand |
X'05' | X'01' | X'0002' | Invalid value in MPNAMLN operand |
X'06' | X'01' | X'0002' | Error in SCOPE operand |
X'07' | X'01' | X'0002' | Error in SELECT operand |
X'08' | X'01' | X'0002' | Error in PRIV_POOL operand |
X'09' | X'01' | X'0002' | Error in CONNECT operand |
X'0A' | X'01' | X'0002' | Wrong user ID in USERID operand (SCOPE=*GROUP) |
X'0B' | X'01' | X'0002' | Wrong group ID in GROUPID operand (SCOPE=*USER-GROUP) |
X'0C' | X'01' | X'0002' | Wrong user ID in USERID operand (CONNECT=*BY-USER) |
X'0D' | X'01' | X'0002' | Wrong TSN in TSN operand (CONNECT=*BY-TASK) |
X'0E' | X'01' | X'0002' | Error in INFO operand |
X'0F' | X'01' | X'0002' | Error in NUMSHR operand |
X'10' | X'01' | X'0002' | Invalid address in INFO_AREA operand (also for missing indication or |
X'11' | X'01' | X'0002' | Invalid length in INFO_LENGTH operand |
X'00' | X'20' | X'0003' | Internal error |
X'00' | X'40' | X'0004' | Not privileged for call |
X'00' | X'80' | X'0005' | Shortage in paging memory |
X'00' | X'80' | X'0006' | Shortage in main memory |
X'00' | X'80' | X'0007' | Shortage in user address space |
Other return codes which, in accordance with conventions, apply to all macros are given in the table “Standard return codes” (Standard header).
Program example
SHOWMP MF=D,XPAND=PARAM SHOWMP MF=D,XPAND=INFA * SHMEMPO @ENTR TYP=I,LOCAL=SHMEMPL SHMEMPL @PAR D=YES SHMEMPC SHOWMP MF=C,PREFIX=A,XPAND=PARAM * SHMPNAME DS CL8 MPNAME SHUSERID DS CL8 USERID FOR GROUP SHMEMPL @PAR LED=YES ... LA R3,SHMEMPC USING NVPI_MDL,R3 LA R4,1 MVC SHMEMPC(NVPI#),SHMEMPD MVC SHMPNAME,MEMPNAME COPY MPNAME MVC SHUSERID,USERID Assume: MYUID is own USERID LA R9,SHMPNAME A(MPNAME) * SHOWMP MF=M,MPNAMAD=(R9),MPNAMLN=8,GROUP_USERID=SHUSERID * @CYCL , * REQM (R4) REQUEST CLASS 6 PAGES @WHEN NZ LTR R15,R15 @BREAK , * LR R5,R1 SHOWMP MF=M,INFO_AREA=(R5) * SHOWMP MF=E,PARAM=(R3) GET MEMORY POOL DATA XR R15,R15 @WHEN EQ CLC NVPIMRET,=X'0000' @OR GT CLC NVPIMRET,=X'0001' @BREAK , * RELM (R4),(R5) RELEASE CLASS 6 PAGES
* L R4,NVPIINFL GET NEW PAGE NUMBER @BEND , * @IF ZE LTR R15,R15 @AND EQ CLC NVPIMRET,=X'0000' @AND NE CLC NVPINPOL,=F'0' AVOID CYCLE WITH LOOP COUNT 0 @THEN , * * evaluation of returned info data * L R8,NVPINPOL LR R7,R5 ADDRESS OF INFO AREA USING NVPIINFA,R7 * @CYCL (R8) LOOP OVER FOUND MEMPOOLS . . L R7,NVPINXTM NEXT MEMORY POOL @BEND , * @ELSE , * * error handling * @BEND , ... @END , * DATA SHMEMPD SHOWMP MF=L,SCOPE=*GROUP,SELECT=*ALL,INFO=*ALL * MEMPNAME DC CL8'HAUS*' MPNAME WITH WILDCARD USERID DC CL8'MYUID' USERID FOR GROUP