ASHARE - Load user's shared code into common memory pools

General

Application area:	Linking and loading; see "Linking and loading"
Macro type:	S-Typ, MF-Format 2: Type S, MF format 2: standard/C/D/L/E/M form; see "S-type macros"

See also the “BLSSERV” manual [4 (Related publications)] for information on the dynamic binder loader DBL.

Macro description

The ASHARE macro links and loads the user's shared code into a common memory pool. This shared code may consist of a set of modules (see section “Common memory areasshared by several users (Memory pools)”). Any user connected to the common memory pool can access this type of shared program via its program name or via all other nonmasked CSECTS or ENTRYs, using the LOAD-EXECUTABLE-PROGRAM and START-EXECUTABLE-PROGRAM commands (or LOAD-PROGRAM and START-PROGRAM) or the BIND and VSVI1 macros.

In indirect linking, ASHARE can be used for loading server modules into a common memory pool.

Macro format and description of operands

ASHARE

[, {CONTEXT=name / CONTXT@={addr / (r)}}]

[,LIBNAM={file / *} / LIBNAM@={addr / (r)} / LIBLINK=name / LIBLNK@={addr / (r)}]

,ALTLIB=*DBLOPT / NO / YES

,INTVERS=BLSP2 / SRV001

,MAP=*DBLOPT / NO / BOTH / (BOTH,nn) / nn / SYSOUT

[,MPID=addr / (r)]

[,MSGCTRL=*DBLOPT / INFORMATION / WARNING / ERROR / NONE]

, {PGMVERS={*STD / version} / PGMVER@={addr / (r)}}

[, {PROGRAM=name / PROG@={addr / (r)}}]

[, {REPFILE=file / REPFIL@={addr / (r)}}]

,RESMP=NO / YES

,RESSYS=NO / YES

[,START@=addr / (r)]

, {SYMBOL=name / SYMBOL@={addr / (r)}}

,SYMTYP=ANY / CSECT / CSEN / MODULE / ENTRY

[, {VERSION=version / VERS@={addr / (r)}}]

,MF=S / C / D / E / L / M

[,PARAM=addr / (r)]

,PREFIX=P / p

,MACID=BAS / macid

The operands are described in alphabetical order below.

ALTLIB=
Specifies whether alternate libraries are to be searched for the object defined by SYMBOL or SYMBOL@. Alternate libraries are assigned using the file link name BLSLIBnn (00<=nn<=99) or $BLSLBnn (for alternate system libraries) and are also used for the autolink function of DBL.

*DBLOPT
The parameter value is taken from the last call of the MODIFY-DBL-DEFAULTS command. If a value for the parameter has not yet been set using the MODIFY-DBL-DEFAULTS command, ALTLIB=NO applies.

NO
Alternate libraries will not be searched.

YES
Alternate libraries will be searched.

The operands ALTLIB=YES and LIBNAM/LIBNAM@/LIBLINK/LIBLNK@ may be specified together in the same macro. If, however, the main library specified by LIBNAM/LIBNAM@/LIBLINK/LIBLNK@ is not present, DBL will abort the processing. ALTLIB=YES cannot serve as a substitute for a missing or invalid main library.

CONTEXT=
Specifies the name of the context in which the program is to be loaded. If this context already exists in a memory pool that is accessible by the user task, this name must refer to the memory pool specified in the MPID operand. Up to 15 contexts may be defined in one memory pool.

name
Context name. The first character of the context name must be “#”. The name may be up to 32 characters long. The default name is “#” followed by the first 31 characters of the memory pool specified in the MPID operand.

CONTXT@=
Specifies the address of a field containing the context name. Can be specified only if MF=M.

addr
Address of an auxiliary field which contains the field address searched for.

(r)
r = register containing the field address searched for.

INTVERS=
This operand defines the version of the macro interface ASHARE.

BLSP2
Default. Corresponds to macro version 2.

SRV001
Corresponds to macro version 3. This version is supported as of BLSSERV V2.4A.

LIBLINK=name
Explicit specification of the file link name of the main library. This name may be up to 8 characters long.

LIBLNK@=
Specifies the address of a field containing the file link name of the main library. May be specified only if MF=M.

addr
Address of an auxiliary field which contains the field address searched for.

(r)
r = register containing the field address searched for.

LIBNAM=
Specifies the main library in which the search for the object defined with SYMBOL or SYMBOL@ is to take place. The main library can be defined by specifying its file name explicitly or by means of a file link name. The EAM object module file is defined using the file name “*”. It is not possible to specify a file link name for the EAM object module file. If the LIBNAM, LIBNAM@, LIBLINK and LIBLNK@ operands are omitted, the library with the file link name BLSLIB is searched.

The main library is searched before the alternate libraries (see "BIND - Link and load load unit"). It is also used for the autolink function of DBL. If the LIBLINK or LIBLNK@ operand is specified, any LIBNAM or LIBNAM@ entry is ignored.

file
Explicit specification of the file name of the main library. The file name may be up to 54 characters long.

*
Specifies the EAM object module file as the main library.

LIBNAM@=
Specifies the address of a field containing the name of the main library. May be specified only if MF=M.

addr (r)

Address of an auxiliary field which contains the field address searched for. r = register containing the field address searched for.

MAP=

Specified only with INTVERS=SRVxxx and xxx >= 001
Defines whether or not a DBL map is output and specifies the output destination for the DBL map.

*DBLOPT
This operand value is taken over from the last call of the MODIFY-DBL-DEFAULTS command. If no value has yet been defined with MODIFY-DBL-DEFAULTS for the operand involved, MAP=NO applies.

NO
No DBL map is output.

BOTH
The output destination is the SYSOUT system file and the SYSLST00 system file.

(BOTH,nn)
The output destination is the SYSOUT system file and a SYSLSTnn system file (00<=nn<=99).

nn
The output destination is a system file from the range SYSLST00 through SYSLST99 whose number must be specified here.
The number must be specified as a 2-digit number (00 for 0 etc.).

SYSOUT
The output destination is the SYSOUT system file.

MF=
For a general description of the MF operand, its operand values and any of the specified operands PARAM, PREFIX and MACID, see section “S-type macros”. The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.

It is possible to specify a PREFIX (consisting of one alphabetic character) in the C form, D form or M form of the macro, and additionally a MACID (three alphabetic characters) in the C form or M form (see section “S-type macros”).

MPID=addr
Symbolic address of a 4-byte field containing the identifier of a memory pool into which the load unit will be loaded. This identifier is made available to the user by means of the ENAMP macro, which must be executed before the ASHARE macro.

(r)
r = register containing the address value “addr”. May be specified only if MF=M.

MSGCTRL=

Specifies the lowest message class; DBL messages at and above this level will be output. The value set in the load call with LOAD-EXECUTABLE-PROGRAM or START-EXECUTABLE-PROGRAM (or LOAD-PROGRAM or START-PROGRAM) will be used as the default value.

*DBLOPT
The parameter value is taken from the last call of the MODIFY-DBL-DEFAULTS command. If a value for the parameter has not yet been set using the MODIFY-DBL-DEFAULTS command, MSGCTRL=INFORMATION applies.

INFORMATION
All classes of message will be output.

WARNING
Only messages of the WARNING and ERROR classes will be output.

ERROR
Only messages of the ERROR class will be output.

NONE
No DBL messages will be output.

PGMVERS=
Specifies the program version.

*STD
The load unit resulting from the load call receives the version of the loaded library element as the program version. If the symbol specified in the load call is already loaded, a search is carried out for the program version that was set using the SELECT-PROGRAM-VERSION command. If no program version has been set, DBL uses the first symbol found.

version
The version specification may be up to 24 characters long. If this program version already exists in the common memory pool, the load procedure is aborted and the corresponding return code is output.

PGMVER@=
Specifies the address of a field containing the program version. May be specified only if MF=M.

addr
Address of an auxiliary field which contains the field address searched for.

(r)
r = register containing the field address searched for.

PROGRAM=

Identifies the program.

name
The specified name must be unique and must not be more than 32 characters long. The default value is the name specified for SYMBOL or SYMBOL@. If this program already exists in a common memory pool that can be accessed by the user, the load procedure is aborted.

PROG@=
Specifies the address of a field containing the program name. May be specified only if MF=M.

addr
Address of an auxiliary field which contains the field address searched for.

(r)
r = register containing the field address searched for.

REPFILE=
Specifies the name of the REP file which contains REP records in standard BS2000 format (see the “Introduction to System Administration” manual [10 (Related publications)]). If there is an error during the processing of REP records, DBL outputs an error message on SYSOUT and the errored REP record is skipped. REP processing then resumes.

file
The file name may be up to 54 characters long.

REPFIL@=
Specifies the address of a field which contains the name of a REP file. May be specified only if MF=M.

addr
Address of an auxiliary field which contains the field address searched for.

(r)
r = register containing the field address searched for.

RESMP=
Specifies the scope for resolving external references in the shared code in the memory pool.

NO
Only the context specified in the CONTEXT operand is used to resolve external references.

YES
All contexts that refer to the memory pool are used to resolve external references.

RESSYS=

Specifies whether the shared code in the system address space (class 3/4/5 memory) is also to be searched in order to resolve external references. This shared code is loaded with DSSM in the form of nonprivileged subsystems.

NO
Shared code in the system address space is not used to resolve external references.

YES
Shared code in the system address space is used to resolve any external references that were not resolved as a result of searching the shared code in the memory pool.

START@=addr
Symbolic address of a 4 byte field to which DBL transfers the start address of the load unit in the memory pool. The field must be aligned on a word boundary. The user must request the start address explicitly with START@; it is not returned by default.

(r)
r = register containing containing the address value “addr”. May be specified only if MF=M.

SYMBOL=name
Explicit specification of an object name. DBL uses this name to determine which module of the load unit is to be loaded into the memory pool first. The name can refer to the following objects:

• control section (CSECT),

• entry point (ENTRY),

• object module (OM) (element name),

• linking loader module (LLM) (element name).

The name may be up to 32 characters long. The type of the object is defined using the SYMTYP operand.

SYMBOL@=
Specifies the address of a field containing the name of the object. May be specified only if MF=M.

addr
Address of an auxiliary field which contains the field address searched for.

(r)
r = register containing the field address searched for.

SYMTYP=

Specifies the type of object defined with the name SYMBOL or SYMBOL@ and defines the search sequence for the object. A symbol (CSECT or ENTRY) or module (OM or LLM) can be defined as the type of object.
If the object is a symbol, the name SYMBOL or SYMBOL@ designates a symbol name and can be

• the name of a nonmasked CSECT or ENTRY entry in a program library (type R or type L),

• the name of a nonmasked CSECT or ENTRY entry in an object module library (OML) or in the EAM object module file.

If the object is a module, the name SYMBOL or SYMBOL@ designates a module name and can be

• the name of a library element (type R or type L) in a program library or

• the name of a library element in an object module library (OML).

  ANY
  The search is performed in the following sequence:

  1. LLMs with the module name SYMBOL or SYMBOL@

  2. OMs with the module name SYMBOL or SYMBOL@

  3. Symbols with the symbol name SYMBOL or SYMBOL@ in an LLM. DBL searches for CSECTS first. If no CSECT is found, it searches for ENTRYs.

  4. Symbols with the symbol name SYMBOL or SYMBOL@ in an OM. DBL searches for CSECTS first. If no CSECT is found, it searches for ENTRYs.

  CSECT
  Only control sections (CSECTs) with the symbol name SYMBOL@ or SYMBOL are searched for.

  ENTRY
  Only entry points (ENTRYs) with the symbol name SYMBOL or SYMBOL@ are searched for.

  CSEN
  CSECTs and ENTRYs with the symbol name SYMBOL or SYMBOL@ are searched for. DBL searches for CSECTs first. If no CSECT is found, it searches for ENTRYs.

  MODULE
  Only modules with the module name SYMBOL or SYMBOL@ are searched for.

VERSION=
Specifies the element version of the library element defined by SYMBOL or SYMBOL@.If SYMTYP=ANY, the VERSION operand is taken into account only if the object name (SYMBOL or SYMBOL@) refers to a module in a program library (type R or type L). If a CSECT or ENTRY name is specified, the VERSION operand is ignored. If the operand is not specified, the default value for the highest element version in program libraries is used (see the “LMS” manual [29 (Related publications)]).

version
Explicit specification of the element version. The version specification may be up to 24 characters long.

VERS@=
Specifies the address of a field containing the element version. May be specified only if MF=M.

addr
Address of an auxiliary field which contains the field address searched for.

(r)
r = register containing the field address searched for.

Notes on the macro call

• Before calling the ASHARE macro, the user must have been connected to the common memory pool by means of the ENAMP macro. The memory pool must have been set up with the ENAMP operand FIXED=YES and the SCOPE may not be LOCAL.

• If the memory pool was created in address space higher than 16 Mbytes, all CSECTS of the loaded modules must have the attribute RMODE=ANY.

• External references that cannot be resolved and name conflicts are not permitted.

• LLMs with user-defined slices cannot be loaded into common memory pools using the ASHARE macro. In the case of LLMs whose slices have been defined with the PUBLIC attribute, only the PUBLIC part is loaded using ASHARE. This also applies to the autolink function of DBL.

• Test and diagnostic information (LSD) is not taken into account.

• The number of memory pools in which the user can store shared code is limited to 16 per scope (ENAMP operand SCOPE) for each user ID:

  1. up to 16 memory pools for SCOPE=GROUP,

  2. up to 16 memory pools assigned to a specific user group for SCOPE=USER-GROUP and

  3. up to 16 memory pools for SCOPE=GLOBAL.

  A task can therefore access a total of 48 memory pools for shared code in the user address space. Shared code that is to be accessible for all users as in
  SCOPE=GLOBAL, can also be loaded into the system address space as a nonprivileged subsystem with DSSM.

• If the specified program version has not yet been loaded but a program with this name already exists in the link context (see CONTEXT parameter), loading is rejected because of the name conflict.
  To avoid such name conflicts, different versions of a program must be loaded into different contexts.

• Only a limited number of memory pages in the system address space are available for storing linking and loading information concerning the modules loaded with ASHARE. The number of pages is defined in the startup parameter service via the system parameter BLSUSLIM.

• A resident memory pool can be used for ASHARE only if it is created in a load module that was loaded with the corresponding value for #RESIDENT-PAGES (see the START-EXECUTABLE-PROGRAM command [19 (Related publications)]).

• When searching for the primary input, symbols of the FILE type are ignored for ASHARE since an FILE symbol may never be used as the entry point of a server module for indirect linking.

Return information and error flags

The start address of the load unit is transferred to the field specified with the START@ operand.

Standard header:

+---------------+
|   |   |   |   |
|c|c|b|b|a|a|a|a|
+---------------+

A return code relating to the execution of the ASHARE 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'	Function executed normally
X'00'	X'01'	X'0001'	Symbol name omitted
X'00'	X'01'	X'0002'	Memory pool identifier (MPID operand) omitted
X'00'	X'01'	X'0003'	Invalid identifier specified in MPID
X'00'	X'01'	X'0004'	Invalid context name
X'00'	X'01'	X'0005'	Invalid symbol type
X'00'	X'01'	X'0006'	Invalid field address specified for START@
X'00'	X'01'	X'0007'	Invalid memory pool name.
X'00'	X'01'	X'0008'	Invalid MAP operand.
X'00'	X'01'	X'0009'	The SYSLST number in the MAP operand is invalid.
X'00'	X'01'	X'0011'	Task not connected to memory pool
X'00'	X'01'	X'0012'	Memory pool created with wrong attributes. FIXED=YES missing from ENAMP macro or CLASS=5 or SCOPE=LOCAL specified in ENAMP
X'00'	X'01'	X'0013'	Program name specified for PROGRAM not unique; already exists in a memory pool
X' 00'	X'01'	X'0014'	Context specified for CONTEXT already exists in another memory pool
X'00'	X'01'	X'0015'	Context cannot be generated since the maximum number of 15 contexts has already been reached in this memory pool
X'00'	X'01'	X'0016'	Maximum number of 16 memory pools with this scope already in use for this user ID. No more memory pools can be used with this scope
X'00'	X'01'	X'0017'	System storage area for linking and loading information is full (number of memory pages defined in system parameter BLSUSLIM already reached)
X'00'	X'01'	X'0018'	Specified symbol already loaded in this context
X'00'	X'01'	X'0019'	Memory pool already specified in a BIND macro and can no longer be used for shared code
X'00'	X'01'	X'0020'	Error during linking/loading. The return code relating to this errored load procedure is transferred in the parameter list. Possible values are described with the BIND macro
X'00'	X'20'	X'0100'	System error
X'00'	X'20'	X'0101'	Internal DBL error
X'00'	X'20'	X'0103'	DBL Lock Manager error during processing of ASHARE macro
X'00'	X'01'	X'FFFF'	The function is no longer or not yet supported
X'00'	X'03'	X'FFFF'	The interface version is not supported

Other return codes which, in accordance with conventions, apply to all macros are given in the table “Standard return codes” (Standard header).