Macro type: type S (E form/L form/D form/C form/M form); see "Macro types"
The SHOPLNK macro provides information on the assignment of ISAM pools to ISAM pool link names. When using the macro, the user can specify either the pool link name or the name of the ISAM pool.
An ISAM pool link name can be assigned to any ISAM pool where there is a link to that ISAM pool, irrespective of the scope of the ISAM pool or of the host computer on which the ISAM pool is located.
Format
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
AREA
Specifies an output area to which the output list is to be transferred. There are no restrictions on the character set and length.Only the operand value addr is allowed for the MF=L form.
Default value: | X'FFFFFFFF' |
= addr
Symbolic address of a field containing the name of the output area.
= (r)
Register containing the address of a field in which the name of the output area is stored.
CATID
Specifies the catalog ID of the PVS under which the ISAM pool (for which the pool link name is to be shown) was created (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 default PVS ID of the job (DEFAULT-PUBSET in the user catalog entry) or the home PVS ID (depending on the setting of the system parameter “ISPLDEFC”). |
= 'name'
Name of a field containing the catalog ID of the pubset; four characters in length.
= addr
Symbolic address of a field with the catalog ID of the pubset.
= (r)
Register containing the address of a field with the catalog ID of the pubset.
LINK = *ALL
Returns the assignments of all pool link names defined by the caller to ISAM pools.
= name
Specifies the ISAM pool link name for which the associated ISAM pool is to be shown.
= addr
Symbolic address of a field containing the link name.
= (r)
Register containing the address of the link name.
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 = ISL |
= 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 ("Macro types").
NAME
Specifies the name under which the ISAM pool (for which the pool link name is to be shown) was created. The desired ISAM pool is uniquely identified by the specified name, the catalog ID (CATID) and the scope (see the SCOPE operand).
Only the operand values 'name'/*ALL can be specified for the MF=L form.
= *ALL
Requests the pool link names for all ISAM pools created by the caller.
= 'name'
Name of the ISAM pool for which pool link names are to be shown.
= addr
Symbolic address of a field containing the name of the ISAM pool or *ALL.
= (r)
Register containing the address of a field in which the name of the ISAM pool or *ALL is held.
SCOPE
Scope of the specified ISAM pool for which information is to be shown. If NAME=*ALL was specified, the SCOPE operand specification is ignored.
Only the operand values *TASK/*USERID/*HOST are allowed for the MF=L form.
= *TASK
Requests pool link names for the task-local 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
Requests pool link names for the cross-task ISAM pool with the specified name.
= addr
4-byte symbolic address of a field containing the scope of the ISAM pool.
= (r)
Register containing the address at which the scope of the ISAM pool is stored.
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
4-byte symbolic address for the length of the output area.
= (r)
Register containing the length of the output area.
= *equ
Equate with 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.
= LINKDESC
Expands the layout of the pool link descriptor.
Return codes
The return codes are placed in the header of the parameter list (standard header):
The main return code, in a half-word with the name DISLMRET.
Subcode1, in a byte with the name DISLSR1.
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 when main codes are expanded for a macro, evaluations which are exclusively in response to error classes are not taken into account.
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 DISL.SYCD 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 SHOPLNK macro in tabular form. The string DISL must be added to the left of the indicated names for EQU instructions. This string can be modified by using the parameter PREFIX=prefix or MACID=macid (see the operand descriptions).
Standard header: ccbbaaaa
The following code relating to execution of the SHOPLNK 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. |
X'01' | X'0002' | Parameter error. |
X'20' | X'0005' | Internal system error on calling a system function. |
X'40' | X'0008' | The specified ISAM pool link name does not exist. |
X'40' | X'0009' | The caller has not defined an ISAM pool link name. |
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 operand list
Macro expansion with MF=D and default values for PREFIX and MACID:
SHOPLNK MF=D 1 STACK PRINT 1 PRINT NOGEN 2 *,##### PREFIX=D, MACID=ISL ##### 1 #INTF INTNAME=SHOPLNK,REFTYPE=REQUEST,INTCOMP=002 1 DISLPLA DS 0F BEGIN of PARAMETERAREA _INOUT 1 FHDR MF=(C,DISL),EQUATES=YES 2 DS 0A 2 DISLFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER 2 * 2 DISLIFID DS 0A 0 INTERFACE IDENTIFIER 2 DISLFCTU 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 DISLFCT DS AL1 2 FUNCTION NUMBER 2 DISLFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER 2 * 2 DISLRET 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 DISLSRET DS 0AL2 4 SUB RETURN CODE 2 DISLSR2 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 DISLR2OK EQU X'00' All correct, no additional info 2 DISLR2NA EQU X'01' Successful, no action was necessary 2 DISLR2WA EQU X'02' Warning, particular situation 2 DISLSR1 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 DISLRFSP EQU X'00' FUNCTION SUCCESSFULLY PROCESSED 2 DISLRPER EQU X'01' PARAMETER SYNTAX ERROR 2 * 3 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'01' - X'1F' 2 DISLRFNS EQU X'01' CALLED FUNCTION NOT SUPPORTED 2 DISLRFNA EQU X'02' CALLED FUNCTION NOT AVAILABLE 2 DISLRVNA EQU X'03' INTERFACE VERSION NOT SUPPORTED 2 * 2 DISLRAER EQU X'04' ALIGNMENT ERROR 2 DISLRIER EQU X'20' INTERNAL ERROR 2 DISLRCAR EQU X'40' CORRECT AND RETRY 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'40' - X'7F' 2 DISLRECR EQU X'41' SUBSYSTEM (SS) MUST BE CREATED 2 * EXPLICITELY BY CREATE-SS 2 DISLRECN EQU X'42' SS MUST BE EXPLICITELY CONNECTED 2 * 2 DISLRWAR EQU X'80' WAIT FOR A SHORT TIME AND RETRY 2 DISLRWLR EQU X'81' " LONG " 2 DISLRWUR 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 DISLRTNA EQU X'81' SS TEMPORARILY NOT AVAILABLE 2 DISLRDH EQU X'82' SS IN DELETE / HOLD 2 * 2 DISLMRET DS 0AL2 6 MAIN RETURN CODE 2 DISLMR2 DS AL1 6 MAIN RETURN CODE 2 2 DISLMR1 DS AL1 7 MAIN RETURN CODE 1 2 * 2 * SPECIAL LAYOUT OF LINKAGE_MAIN_RETURN_CODE (YYYY IN X'00XXYYYY') 2 * 2 DISLRLNK EQU X'FFFF' LINKAGE ERROR / REQ. NOT PROCESSED 2 DISLFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH 2 * 1 DISLOK EQU X'0000' FUNCTION SUCCESSFUL PROCESSED 1 DISLNPAR EQU X'0001' PARAMETERLIST NOT ACCESSIBLE 1 DISLPERR EQU X'0002' PARAMETER ERROR 1 DISLSYSE EQU X'0005' INTERNAL SYSTEM ERROR 1 DISLLLNE EQU X'0008' SPECIFIED POOL LINK NAME NOT FOUND 1 DISLNOLI EQU X'0009' NO ISAM POOL LINK EXISTING 1 DISLNOSP EQU X'000B' NO MEMORY AVAILABLE 1 DISLNUGR EQU X'000C' NO USEGROUP DEFINED 1 DISLINOP EQU X'001F' SSTA INOP 1 DISLSSER EQU X'0020' SSTA INTERNAL ERROR 1 DISLMEMR EQU X'0021' SSTA MEMORY ERROR 1 DISLOPSR EQU X'0022' SSTA OPS ERROR 1 DISLOPME EQU X'0023' SSTA OPS MEMORY ERROR 1 * 1 * 1 DISLPLNK DS CL8 LINK-NAME 1 DISLPNAM DS CL8 POOL-NAME 1 DISLCID DS CL4 CATALOG-IDENTIFIER 1 * 1 DISLSCOP DS XL1 SCOPE 1 DISLTASK EQU X'00' = TASK 1 DISLUSID EQU X'01' = USERID 1 DISLHOST EQU X'02' = HOST-SYSTEM 1 DISLUSGR EQU X'03' = USERGROUP 1 * 1 DISLSYCD DS XL1 SYSTEM-ERROR-CODE 1 * 1 DISLADDR DS A ADDRESS OF OUTPUT-AREA 1 DISLSIZE DS F SIZE OF OUTPUT-AREA 1 * 1 DISL# EQU *-DISLPLA LENGTH of PARAMETERAREA
Format of the output area
The SHOPLNK macro returns the assignments of ISAM pools to ISAM pool names in the output area specified by the caller. This area begins with a management header of 16 bytes containing the following information:
The management header of the output area is generated by specifying the control parameter XPAND=DESCHDR when calling the SHOPLNK macro with the control operand MF=D or MF=C:
1 DISLADMH DS 0F MANAGEMENT HEADER LAYOUT 1 DISLLLG DS F NUMBER OF BYTES TRANSFERRED 1 DISLLCLG DS F LENGTH OF TOTAL INFORMATION 1 DISLL#LN DS H NUMBER OF LINK NAMES INVOLVED 1 DISLLIND DS XL1 TRANSFER INDICATOR 1 DISLLCOM EQU X'00' INFORMATION COMPLETE 1 DISLLPAR EQU X'01' INFORMATION INCOMPLETE 1 DISLLRES DS CL5 NOT USED 1 DISLLLEN EQU *-DISLADMH LENGTH OF MANAGEMENT HEADER
The entry with information can be expanded using the parameter XPAND=LINKDESC when calling the SHOPLNK macro with the control operand MF=C or MF=D:
1 DISLLDDS DS 0F POOL LINK DESCRIPTOR LAYOUT 1 DISLLNAM DS CL8 NAME OF POOL LINK 1 DISLPONA DS CL8 NAME OF ASSOCIATED ISAM POOL 1 DISLLCID DS CL4 NAME OF ASSOCIATED PVS 1 DISLLSCO DS XL1 SCOPE OF ISAM POOL 1 DISLLTSK EQU X'00' SCOPE = TASK 1 DISLLUSR EQU X'01' SCOPE = USERID 1 DISLLHOS EQU X'02' SCOPE = HOST 1 DISLLUGR EQU X'03' SCOPE = USERGROUP 1 DISLLUID DS CL8 USERID FOR SCOPE = *USERID 1 * GROUP NAME WITH SCOPE = *USERGROUP 1 DISLLRSV DS CL3 NOT USED 1 DISLLLNG EQU *-DISLLDDS LENGTH OF ISAM-POOL-DESCR.
Explanation of the individual fields in the output area
Management header
The management header (16 bytes in length) 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). This value is significant for the caller of the macro if the output area is too small. The caller of the macro must then supply an output area of (at least) this length,
the number of ISAM pool link names for which the assignments to ISAM pools was shown in the output area (length: 2 bytes),
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 accommodate the entire information. The length of this larger area can then be obtained from the second word of the management header,
the remaining 5 bytes are not used.
Descriptor area
In order to identify an ISAM pool uniquely, the name of the ISAM pool, the catalog ID of the host computer on which the pool exists, and the scope of the ISAM pool are required. The output area for the SHOPLNK macro contains 32-byte entries comprising an ISAM pool link name at the beginning, followed by an ISAM pool descriptor with the above information. In other words, the following information is included in such entries:
the name of an ISAM pool link name with a length of 8 bytes (printable),
the name of the associated ISAM pool with a length of 8 bytes (printable),
the catalog ID (CATID) of the host computer on which the ISAM pool in question exists; also printable, and 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 user ID – if the associated ISAM pool has been provided with the attribute SCOPE = USERID,
the remaining 3 bytes are not used.
The above-named structures are laid out in the output area filled by the SHOPLNK macro as follows:
HEADER | LINKNAME1 | POOLNAME1 | CATID1 | SCOPE1 | userid | UNUSED LINKNAME2 | POOLNAME2 | CATID2 | SCOPE2 | userid | UNUSED ....... ....... LINKNAMEn | POOLNAMEn | CATIDn | SCOPEn | userid | UNUSED
The “userid” field contains blanks if SCOPE=TASK or SCOPE=HOST applies.
The links between ISAM pools and pool link names are described after the management header. The number of entries created is contained in the management header itself.