NUCLKUP — Nucleus map lookup service

Description

The NUCLKUP macro provides lookup functions by name and by address. Use the macro to get:
  • The name and address of a nucleus CSECT if you have an address within the CSECT
  • The address and AMODE of a nucleus CSECT or ENTRY if you have its name
You would use the NUCLKUP macro to:
  • Check an installation program once your installation has put it into the nucleus
  • Diagnose a problem of a program residing in the nucleus

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state or supervisor state, and any PSW key
Dispatchable unit mode: Task or SRB
Cross memory mode: Any PASN, any HASN, any SASN
AMODE: 24- or 31-bit
ASC mode: Primary
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: No requirement
Control parameters: Must be in the primary address space

Programming requirements

The caller must include the CVT mapping macro in the program that issues the NUCLKUP macro.

Restrictions

None.

Input register information

Before issuing the NUCLKUP macro, the caller must ensure that the following general purpose register (GPR) contains the specified information:
Register
Contents
13
The address of a standard 18-word save area

Output register information

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the caller issued the macro. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0
  • For a BYNAME request, the address and AMODE of the CSECT or ENTRY
  • For a BYADDR request, the 31-bit address of the CSECT
The AMODE is returned as part of the 31-bit address for a BYNAME request:
  • AMODE 24: high-order and low-order bits are both 0
  • AMODE 31: high-order bit is 1, low-order bit is 0
  • AMODE 64: high-order bit is 0, low-order bit is 1
  • If the AMODE of the module is ANY, it indicates AMODE 24 if the caller is AMODE 24 (the high order bit is 0), or AMODE 31, if the caller is AMODE 31 or AMODE 64 (the high order bit is 1).
1
For a BYNAME request, the high-order byte is zero and the low-order three bytes contain the length from the entry point to the end of the CSECT; for a BYADDR request, register 1 contains the address of the 8-byte area in which the CSECT name is returned.
2-13
Unchanged.
14
Used as a work register by the system.
15
Return code.

Performance implications

None.

Syntax

The standard form of the NUCLKUP macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede NUCLKUP.
   
NUCLKUP  
   
␢ One or more blanks must follow NUCLKUP.
   
BYNAME,NAME=name id name id: 8-byte literal (enclosed in apostrophes), or the address of the 8-byte literal which can be either an RX-type address, or register (1) - (12).
BYADDR,NAME=name loc  
  name loc: RX-type address or register (1) - (12).
   
,ADDR=addr addr: RX-type address, or register (0) or (2) - (12).
   

Parameters

The parameters are explained as follows:

BYNAME
BYADDR
Specifies the function to be performed. If BYNAME is specified, the user supplies on NAME=name id the name of a CSECT or ENTRY and receives on ADDR the address and AMODE of that CSECT or ENTRY. If BYADDR is specified, the user supplies on ADDR an address within a CSECT and receives on NAME=name id the name and address of the CSECT.
,NAME=name id
,NAME=name loc
Specifies the name or the location of the name of the CSECT depending on the option requested. If the user specifies BYNAME, name id contains the 8-character name to be searched for or the address of that name. If the user specifies BYADDR, name loc will contain the address of the 8-byte area in which the CSECT name is to be returned.
,ADDR=addr
Contains the address to be searched for if BYADDR is specified; contains the address of the CSECT or ENTRY that is returned if BYNAME is specified.
The AMODE is returned as part of the 31-bit address for a BYNAME request:
  • AMODE 24: high-order and low-order bits are both 0
  • AMODE 31: high-order bit is 1, low-order bit is 0
  • AMODE 64: high-order bit is 0, low-order bit is 1
  • If the AMODE of the module is ANY, it indicates AMODE 24 if the caller is AMODE 24 (the high order bit is 0), or AMODE 31, if the caller is AMODE 31 or AMODE 64 (the high order bit is 1).

ABEND codes

None.

Return codes

When NUCLKUP macro returns control to your program, GPR 15 contains a hexadecimal return code.

Table 1. Return Codes for the NUCLKUP Macro
Return Code Meaning and Action
00 Meaning: The request was satisfied.

Action: None.
04 Meaning: The request was not satisfied.

For a BYNAME request, the name was not found, and the location containing the address was set to zero.

For a BYADDR request, the address was not found in the nucleus, and the location containing the name was set to zero.

Action: None required. However, you might take some action based upon your application.
08 Meaning: Program error. The request was not satisfied because the type of request was not specified correctly. The locations containing the name and address were set to zero.

Action: Ensure that the name id value is supplied for BYNAME requests, and the addr value is provided on BYADDR requests.

Example 1

Place the address and AMODE of entry point IEAVESTU in register 0. 
NUCLKUP BYNAME,NAME='IEAVESTU',ADDR=(0)

Example 2

Look up the address and amode of the entry point name in location STRING and return it at location RETLOC. 
        NOCLKUP BYNAME,NAME=STRING,ADDR=RETLOC
        .
        .
STRING  DS      CL8
RETLOC  DS      F

Example 3

Return the CSECT name and address of the nucleus routine in which the address at location INADDR falls. Return the name at location EPLOC1 and the address at INADDR. 
        NUCLKUP BYADDR,NAME=EPLOC,ADDR=INADDR
        .
        .
EPLOC   DS      CL8
INADDR  DS      F