Macro type: type S (E form/L form/D form/C form/M form); see "Macro types"
The SHOPOOL macro returns information on ISAM pools linked to the current job, taking the links to ISAM pools on remote systems into account (except with the SELECT operand). The user may request information on a specific ISAM pool or on all ISAM pools to which a link exists.
The output comprises detailed information on the pool-specific attributes of each ISAM pool (as defined in the CREPOOL macro).
If desired, the user may also have the task sequence numbers (TSNs) of all connected jobs for each ISAM pool displayed.
While the user can set up a connection to an ISAM pool with the CREPOOL macro, a job can also be implicitly connected to standard pools by NK-ISAM.
Note
Cross-task ISAM pools are created automatically in a data space on a file-specific basis when the file is opened.
DSCOPE=USERID and SCOPE=USERGROUP which were available up to BS2000/OSD V6.0A are still accepted for reasons of compatibility, but internnaly they are mapped to SCOPE=HOST (cross-task ISAM pool). For further information on NK-ISAM pools in data spaces please refer to the “Introductory Guide to DMS” [1].
Format
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
AREA
Specifies an output area to which the output list is to be transferred.
Only the operand value addr is allowed for the MF=L form.
Default value: | X'FFFFFFFF' |
= addr
Symbolic address (name) of the output area. There are no restrictions on the character set and length.
= (r)
Register in which the address of the output area is entered.
CATID
Catalog ID of the pubset to which the ISAM pool (for which information is to be obtained) is assigned (of no consequence if the parameter NAME=*ALL is specified).
Only the operand value 'name' is allowed for the MF=L form.
Default value: | The ISAM pool is assigned to the catalog that was set with the system parameter ISPLDEFC (ISAM-POOL-DEFAULT-CATID): X'00': default catalog ID from the user entry (DEFAULT-PUBSET) X'01': catalog ID of the home pubset |
= 'name'
Catalog ID of the home pubset; 4 characters in length.
= addr
4-byte address of a field containing the catalog ID of the pubset.
= (r)
Register containing the address of a field with the catalog ID of the pubset.
INFO
Defines the scope of the information to be output. The SHOPOOL macro returns the requested information in the output area specified by the caller (see the format of the output area on "SHOPOOL - Return information on ISAM pools").
= *ATTR
Outputs the static attributes for the ISAM pool specified in NAME.
= *ALL
Outputs the job numbers (TSNs) of all jobs connected to the specified ISAM pool/s in addition to the static attributes.
= addr
Address of a field containing the scope of the information to be output.
= (r)
Register containing the address of a field in which the scope of the information to be output is stored.
MACID
Evaluated only in conjunction with MF=C; defines the second through fourth characters of the field names and equates generated in the data area when the macro is expanded.
Default value: | MACID = ISP |
= macid
Three-character string defining the second through fourth characters of each field name and equate generated.
MF
The forms of the MF operand are described in detail in the appendix on "Macro types".
NAME
Name of the ISAM pool for which information is to be returned. The desired ISAM pool is uniquely identified by the specified pool name, the catalog identifier (“catid”) and the scope.Information is output only if the ISAM pool exists and the current job is connected to it.Only the operand values “name” and “*ALL” can be specified with the MF=L form.
= *ALL
Returns information on all ISAM pools to which the current job is connected.
= 'name'
Name of the ISAM pool for which information is to be output. 'name' may have a length of up to 8 characters.
= addr
Address of a field containing the name of the ISAM pool or *ALL.
= (r)
Register containing an address at which the name of the ISAM pool or *ALL is stored.
PARAM
Indicates the address of the operand list. This operand is only evaluated in conjunction with MF=E (see also "Macro types").
= addr
Symbolic address (name) of the operand list.
= (r)
Number of the register containing the address of the operand list. The register must be loaded with this address value before the macro is called.
PREFIX
Evaluated only in conjunction with MF=C or MF=D; defines the first character of each field name and equate generated in the data area when the macro is expanded.
Default value: | PREFIX = D |
= pre
“pre” is a one-character prefix with which the field names and equates generated by the assembler are to begin.
SCOPE
Scope of the specified ISAM pool for which information is to be returned. If NAME=*ALL is specified, entries in the SCOPE operand are ignored.
Only the operand values *TASK/*USER-ID/*HOST are allowed for the MF=L form.
= *TASK
Returns information on the cross-task ISAM pool with the specified name.
= *USERID
= *USERGROUP
SCOPE=USERID and SCOPE=USERGROUP which were available up to BS2000/OSD V6.0A are still accepted for reasons of compatibility, but internnaly they are mapped to SCOPE=HOST (cross-task ISAM pool).
However, in each case only the ISAM pools which were created with the specified scope are displayed.
= *HOST
Returns information on the cross-task ISAM pool with the specified name.
= addr
Symbolic name of a field containing the scope of the specified ISAM pool.
= (r)
Register containing the address of a field in which the scope of the ISAM pool is stored.
SELECT
Specifies the criteria by which the ISAM pools specified via the NAME parameter are selected for the output of information.
= *OWN
Returns information on ISAM pools to which the calling task is connected. ISAM pools on remote systems are also shown in the output.
= *ALL
This operand value can only be specified by a task that has TSOS or SW-MONITOR-ADMINISTRATION privileges.
Information is returned on all existing ISAM pools, even if no connection to the ISAM pool exists. Remote ISAM pools are not shown.
= addr
Symbolic name of a field containing the criteria for selecting the ISAM pools for which information is to be output.
= (r)
Register with the address of a field containing the criteria for selecting the ISAM pools for which information is to be output.
SIZE
Specifies the length of the output area.
Only the operand values nmbr/*equ are allowed for the MF=L form.
Default value: | X'00000000' |
= nmbr
Numeric value that specifies the length of the output area.
100 <= nmbr <= 10000.
= addr
Is the address for the length of the output area.
= *equ
Equate containing the length of the output area.
XPAND
Control operand; for MF=C and MF=D only:
Defines which structure is to be expanded (i.e. generated). This operand is ignored for other MF values.
= PARAM
Expands the layout of the parameter list.
= DESCHDR
Expands the layout of the header of the output area.
= POOLDESC
Expands the layout of a pool descriptor.
Return codes
The return codes are placed in the header of each parameter list:
The main return code, in a half-word with the name DISPMRET.
Subcode1, in a byte with the name DISPSR1.
Subcode1 describes error classes which allow the caller to respond to similar error situations.The caller can refer back to the main code as well as to subcode1; however, the evaluation of subcode1 must be given preference, because evaluations which are exclusively in response to error classes are not taken into account when main codes are expanded for a macro.
Subcode2 always has the value X'00'.
If return codes cannot be placed in the header of a macro (because it is not accessible, for example), the calling program is terminated with an appropriate error message.
If the return code for an “'internal system error on calling a system function” is generated, the field DISPSYCD in the parameter list of the macro in question will contain a more detailed code to enable diagnostics (see the inserts with the corresponding message for values).
A macro called with MF=D or MF=C generates EQU instructions for the return codes in addition to the field names.
The following overview shows the return codes for the SHOPOOL macro in tabular form. The string DISP must be added to the left of the indicated names for EQU instructions. This string can be modified using the parameter PREFIX=prefix or MACID=macid (see the operand descriptions).
Standard header: ccbbaaaa
The following code relating to execution of the SHOPOOL macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'bb' | X'aaaa' | Meaning |
X'00' | X'0000' | The function was executed successfully |
X'01' | X'FFFF' | The header is corrupted, e.g. not correctly initialized. |
X'02' | X'FFFF' | Linkage error (function not available) |
X'03' | X'FFFF' | Linkage error (version not supported) |
X'01' | X'0001' | Parameter list not accessible. No repetition possible |
X'01' | X'0002' | Parameter error. No repetition possible |
X'40' | X'0003' | The specified catalog ID name does not exist |
X'40' | X'0004' | The specified ISAM pool link name does not exist |
X'20' | X'0005' | Internal system error on calling a system function |
X'40' | X'0006' | No ISAM pool exists |
X'40' | X'0007' | Privileges required for function not available |
X'82' | X'000A' | Specified catalog ID does not exist. |
X'82' | X'000B' | No virtual memory available. |
Further return codes, whose meanings are defined by conventions valid for all macros, can be found in the table on "Standard header" (standard header).
The calling program is terminated if one of the following errors occurs with respect to the parameter list:
the list is not assigned to the caller
the list is not aligned on a word boundary
the list is write-protected.
Layout of the parameter list
Macro expansion with MF=D and default values for PREFIX and MACID:
The parameter list of the macro contains a header, whose fields are loaded automatically when the list is created with the L form.
If a parameter list is to be created dynamically with the D or C form, it must be initialized beforehand with a parameter list created with the L form. This is the only way of ensuring that the header of a parameter list contains the correct information.
SHOPOOL MF=D 1 STACK PRINT 1 PRINT NOGEN 2 *,##### PREFIX=D, MACID=ISP ##### 1 #INTF INTNAME=SHOPOOL,REFTYPE=REQUEST,INTCOMP=002 1 DISPPPA DS 0F BEGIN of PARAMETERAREA _INOUT 1 FHDR MF=(C,DISP),EQUATES=YES 2 DS 0A 2 DISPFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER 2 * 2 DISPIFID DS 0A 0 INTERFACE IDENTIFIER 2 DISPFCTU DS AL2 0 FUNCTION UNIT NUMBER 2 * BIT 15 HEADER FLAG BIT, 2 * MUST BE RESET UNTIL FURTHER NOTICE 2 * BIT 14-12 UNUSED, MUST BE RESET 2 * BIT 11-0 REAL FUNCTION UNIT NUMBER 2 DISPFCT DS AL1 2 FUNCTION NUMBER 2 DISPFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER 2 * 2 DISPRET DS 0A 4 GENERAL RETURN CODE 2 * 2 * GENERAL_RETURN_CODE CLEARED (X'00000000') MEANS 2 * REQUEST SUCCESSFUL PROCESSED AND NO ADDITIONAL INFORMATION 2 * 2 DISPSRET DS 0AL2 4 SUB RETURN CODE 2 DISPSR2 DS AL1 4 SUB RETURN CODE 2 2 * ALWAYS CLEARED (X'00') IF MAIN_RETURN_CODE IS X'FFFF' 2 * Standard subcode2 values as defined by convention: 2 DISPR2OK EQU X'00' All correct, no additional info 2 DISPR2NA EQU X'01' Successful, no action was necessary 2 DISPR2WA EQU X'02' Warning, particular situation 2 DISPSR1 DS AL1 5 SUB RETURN CODE 1 2 * 2 * GENERAL INDICATION OF ERROR CLASSES 2 * 2 * CLASS A X'00' FUNCTION WAS SUCCESSFULLY PROCESSED 2 * CLASS B X'01' - X'1F' PARAMETER SYNTAX ERROR 2 * CLASS C X'20' INTERNAL ERROR IN CALLED FUNCTION 2 * CLASS D X'40' - X'7F' NO CLASS SPECIFIC REACTION POSSIBLE 2 * CLASS E X'80' - X'82' WAIT AND RETRY 2 * 2 DISPRFSP EQU X'00' FUNCTION SUCCESSFULLY PROCESSED 2 DISPRPER EQU X'01' PARAMETER SYNTAX ERROR 2 * 3 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'01' - X'1F' 2 DISPRFNS EQU X'01' CALLED FUNCTION NOT SUPPORTED 2 DISPRFNA EQU X'02' CALLED FUNCTION NOT AVAILABLE 2 DISPRVNA EQU X'03' INTERFACE VERSION NOT SUPPORTED 2 * 2 DISPRAER EQU X'04' ALIGNMENT ERROR 2 DISPRIER EQU X'20' INTERNAL ERROR 2 DISPRCAR EQU X'40' CORRECT AND RETRY 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'40' - X'7F' 2 DISPRECR EQU X'41' SUBSYSTEM (SS) MUST BE CREATED 2 * EXPLICITELY BY CREATE-SS 2 DISPRECN EQU X'42' SS MUST BE EXPLICITELY CONNECTED 2 * 2 DISPRWAR EQU X'80' WAIT FOR A SHORT TIME AND RETRY 2 DISPRWLR EQU X'81' " LONG " 2 DISPRWUR EQU X'82' WAIT TIME IS UNCALCULABLY LONG 2 * BUT RETRY IS POSSIBLE 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'80' - X'82' 2 DISPRTNA EQU X'81' SS TEMPORARILY NOT AVAILABLE 2 DISPRDH EQU X'82' SS IN DELETE / HOLD 2 * 2 DISPMRET DS 0AL2 6 MAIN RETURN CODE 2 DISPMR2 DS AL1 6 MAIN RETURN CODE 2 2 DISPMR1 DS AL1 7 MAIN RETURN CODE 1 2 * 2 * SPECIAL LAYOUT OF LINKAGE_MAIN_RETURN_CODE (YYYY IN X'00XXYYYY') 2 * 2 DISPRLNK EQU X'FFFF' LINKAGE ERROR / REQ. NOT PROCESSED 2 DISPFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH 2 * 1 DISPOK EQU X'0000' FUNCTION SUCCESSFUL PROCESSED 1 DISPNPAR EQU X'0001' PARAMETERLIST NOT ACCESSIBLE 1 DISPPERR EQU X'0002' PARAMETER ERROR 1 DISPNCAT EQU X'0003' CATID NOT KNOWN 1 DISPPLNE EQU X'0004' SPECIFIED ISAM POOL NOT FOUND 1 DISPSYSE EQU X'0005' INTERNAL SYSTEM ERROR 1 DISPNOPL EQU X'0006' NO ISAM POOL EXISTING 1 DISPNAUT EQU X'0007' NO AUTHORIZATION FOR FUNCTION 1 DISPNACC EQU X'000A' CATID NOT AVAILABLE 1 DISPNOSP EQU X'000B' NO MEMORY AVAILABLE 1 DISPNUGR EQU X'000C' NO USERGROUP DEFINED 1 DISPINOP EQU X'001F' SSTA INOP 1 DISPSSER EQU X'0020' SSTA INTERNAL ERROR 1 DISPMEMR EQU X'0021' SSTA MEMORY ERROR 1 DISPOPSR EQU X'0022' SSTA OPS ERROR 1 DISPOPME EQU X'0023' SSTA OPS MEMORY ERROR 1 * 1 * 1 DISPPNAM DS CL8 POOL-NAME 1 DISPCID DS CL4 CATALOG-IDENTIFIER 1 * 1 DISPSCOP DS XL1 SCOPE 1 DISPTASK EQU X'00' = TASK 1 DISPUSID EQU X'01' = USERID 1 DISPHOST EQU X'02' = HOST-SYSTEM 1 DISPUSGR EQU X'03' = USERGROUP 1 * 1 DISPSELC DS XL1 SELECT 1 DISPOWN EQU X'00' = OWN 1 DISPALLH EQU X'01' = ALL (HOST) 1 * 1 DISPINFO DS XL1 INFO 1 DISPATTR EQU X'00' = ATTR 1 DISPALLT EQU X'01' = ALL 1 * 1 DISPSYCD DS XL1 SYS-ERROR-CODE 1 * 1 DISPADDR DS A ADDRESS OF OUTPUT-AREA 1 DISPSIZE DS F SIZE OF OUTPUT-AREA 1 * 1 DISP# EQU *-DISPPPA LENGTH of PARAMETERAREA
Format of the output area
The SHOPOOL macro returns the requested information in the output area specified by the caller.
Management header of the output area
This area begins with a management header with a length of 16 bytes. The management header of the output area is generated by specifying the operand XPAND=DESCHDR when calling the SHOPOOL macro with the control operand MF=D or MF=C:
1 DISPADMH DS 0F MANAGEMENT HEADER LAYOUT 1 DISPPLG DS F NUMBER OF BYTES TRANSFERRED 1 DISPPCLG DS F LENGTH OF COMPLETE INFORMATION 1 DISPP#PO DS H NUMBER OF ISAM POOLS INVOLVED 1 DISPPINF DS XL1 INDICATOR FOR SCOPE OF INFO 1 DISPPATT EQU X'00' INFO = *ATTR 1 DISPPALL EQU X'01' INFO = *ALL 1 DISPPIND DS XL1 TRANSFER INDICATOR 1 DISPPCOM EQU X'00' INFORMATION COMPLETE 1 DISPPPAR EQU X'01' INFORMATION INCOMPLETE 1 DISPPRES DS CL4 NOT USED 1 DISPPLEN EQU *-DISPADMH LENGTH OF HEADER
Specified output area
An ISAM pool is described in the output area specified by the caller by means of a so-called ISAM pool descriptor with a length of 32 bytes. ISAM pool descriptors are generated by specifying the control parameter XPAND=DESCHDR when calling the SHOPOOL macro with the control operand MF=C or MF=D:
1 DISPPDDS DS 0F ISAM POOL DESCRIPTOR LAYOUT 1 DISPNAME DS CL8 NAME OF ISAM POOL 1 DISPPCID DS CL4 NAME OF ALLOCATED PVS 1 DISPPSIZ DS F POOL SIZE (IN 2K UNITS) 1 DISPPSCO DS XL1 SCOPE OF ISAM POOL 1 DISPPTSK EQU X'00' SCOPE = TASK 1 DISPPUSR EQU X'01' SCOPE = USERID 1 DISPPHOS EQU X'02' SCOPE = HOST 1 DISPPUGR EQU X'03' SCOPE = USERGROUP 1 DISPPWRO DS XL1 WROUT ATTRIBUTE OF ISAM POOL 1 DISPPDEF EQU X'00' WROUT = DEFERRED 1 DISPPIMM EQU X'01' WROUT = IMMEDIATE 1 DISPPCST DS XL1 CSTAT RESIDENCE OF ISAM POOL 1 DISPPNRE EQU X'00' ISAM POOL NOT CSTAT-RESIDENT 1 DISPPRSD EQU X'01' ISAM POOL CSTAT-RESIDENT 1 DISPPEXT DS XL1 EXISTING ISAM POOL EXTENTS 1 DISPPNEX EQU X'00' NO EXTENT EXISTS 1 DISPPEX2 EQU X'01' 2K EXTENT EXISTS 1 DISPPEX4 EQU X'02' 4K EXTENT EXISTS 1 DISPPEXA EQU X'03' 2K AND 4K EXTENT EXISTS 1 DISPPLCI DS XL1 INDICATOR FOR LOCALITY 1 DISPPLCL EQU X'00' POOL ON LOCAL COMPUTER 1 DISPPREM EQU X'01' POOL ON REMOTE COMPUTER 1 DISPPUID DS CL8 USERID FOR SCOPE = *USERID 1 * GROUP NAME FOR SCOPE = *USERGROUP 1 DISPPRSV DS CL3 NOT USED 1 DISPPLNG EQU *-DISPPDDS LENGTH OF ISAM POOL DESCRIPTOR
Explanation of the individual fields in the output area:
The management header contains the following information:
the number of bytes that were transferred to the output area (length: 4 bytes),
the total number of bytes contained in the complete information (length: 4 bytes) requested. The caller of the macro must supply an output area of (at least) the same length,
the number of ISAM pools for which information is to be placed in the output area (length: 2 bytes),
an indicator, with a length of 1 byte, that represents the scope of information specified in the macro call. The following values apply:
X'00': INFO = *ATTR X'01': INFO = *ALL an indicator, with a length of 1 byte, which specifies whether the information transferred to the output area is complete or whether only a part of the desired information could be returned because the output area was too small. The following values are assigned to this indicator:
X'00': The information is complete. X'01': The information was truncated and is incomplete (In the latter case, the caller must provide a larger output area in order to receive the entire information. The length of this larger area can then be obtained from the second word of the management header),
the remaining 4 bytes are not used.
The specified output area can contain the following information:
An ISAM pool is described in the output area specified by the caller by means of an ISAM pool descriptor, with a length of 32 bytes, which contains the following information:
the name of the ISAM pool involved, with a length of 8 bytes (printable),
the catalog ID (CATID) of the host computer on which the specified ISAM pool exists; also printable, and with a length of 4 bytes,
the size of the ISAM pool involved (in 2K units), with a length of 4 bytes,
the scope of the ISAM pool involved, with a length of 1 byte for which values are assigned as follows:
X'00': SCOPE = *TASK X'01': SCOPE = *USERID X'02': SCOPE = *HOST X'03': SCOPE = *USERGROUP the WROUT attribute of the ISAM involved, with the following possible values (1 byte):
X'00': WROUT = DEFERRED X'01': WROUT = IMMEDIATE the CSTAT-residence attribute of the ISAM pool involved (1 byte), with the following assignment:
X'00': the ISAM pool is not CSTAT-resident X'01': the ISAM pool is CSTAT-resident whether the ISAM pool involved is made up of a 2K extent, a 4K extent, or both extents (for detains concerning 4K-capable NK-ISAM):
X'00': no extent created as yet X'01': existing 2K extent for ISAM pool X'02': existing 4K extent for ISAM pool X'03': ISAM pool has a 2K extent as well as a 4K extent whether the ISAM pool involved belongs to a local or remote host computer, indicated by the following assignment:
X'00': pool on local host X'01': pool on remote host the user ID – if the associated ISAM pool has been provided with the attribute SCOPE = USERID,
the remaining 3 bytes are not used.
The structure of the management header (HDR) and ISAM pool descriptor (DESC) are the main factors that determine the format of the output area. The scope of information that was specified when calling the SHOPOOL macro determines the layout.
INFO = *ATTR
If the caller has specified the parameter INFO = *ATTR in the macro call (or selected this default value by omitting the parameter), the output area of the user will be structured as follows:
If INFO=*ATTR is specified, the indicator provided for it in the management header of the output area is assigned the value X'00'. The management header is followed by the ISAM pool descriptors located below one another in contiguous order (without gaps). The number of descriptors is also indicated in the management header.
HDR DESC1 DESC2 ....... ....... DESCn
INFO = *ALL
By specifying the parameter INFO = *ALL in the SHOPOOL macro, the caller requests information in the output area on not only the static attributes of the specified ISAM pool, but also the TSNs of tasks connected to that pool. The indicator provided for this in the management header of the output area is assigned the value X'01', and each ISAM pool descriptor is followed by a word containing the number of tasks connected to that pool, followed by a list of the TSNs of the corresponding tasks (in 4 bytes each; printable).
If the caller has specified the parameter INFO = *ALL in the macro call, the output area of the user will be structured as follows:
HDR | DESC1 | TASK#1 | TSN11 | TSN12 | ..... | TSN1m | DESC2 | TASK#2 | TSN21 | TSN22 | ..... | ..... | TSN2r | ...... | ........................................... ..... | ........................................... DESCn | TASK#n | TSNn1 | ..... | TSNns |