Angel Check API

Use the Angel Check API to check whether a specific named angel or the default angel is running.

The BBGZACHK, BGVT, and ECVT control blocks contain the pointer locations that are needed to determine whether a given angel is running. The following table lists the pointer location for the Angel Check API or a control block.

Table 1. Pointer location for the Angel Check API or a control block
API or control block	Pointer location
The Angel Check API	Offset 0x14 of the BBGZACHK control block
The BBGZACHK control block	Offset 0x2AC of the BGVT control block If the pointer is NULL, no angel has been started.
The BGVT control block	Offset 0x234 of the ECVT control block. If the pointer is NULL, no angel has been started. For more information about the ECVT control block, see MVS Data Areas, Volume 1 (ABE- IAX).

Environment

The following table gives the requirements for the caller.

Table 2. Environmental factors and their requirements
Environmental factor	Requirement
AMODE	64-bit
ASC mode	Primary
Minimum authorization	Problem state or Supervisor state The BBGZACHK control block is available from any storage key of program status word (PSW) 0-15.

Input register information

The following table gives the input registers for the Angel Check API.

Table 3. Input registers and their contents
Register	Contents
1	The address of the null-terminated angel name string, or NULL. To check whether a specific named angel is running, ensure register 1 contains a pointer to the name of the angel as a null-terminated string when calling the Angel Check API. To check whether the default angel is running, ensure that register 1 is cleared when calling the Angel Check API.
13	144-byte save area in F4SA format.
14	The address to return to.

Output register information

The following table gives the output register for the Angel Check API.

Table 4. Output register and its contents
Register	Contents
15	Return code of 0 if the specified angel is running, non-zero otherwise

BBGZAACK macro for calling the Angel Check API

To simplify calling the Angel Check API, you can use the BBGZAACK macro that is located at ${wlp.install.dir}/dev/api/ibm/zos/BBGZAACK.

The following table gives the syntax for the BBGZAACK macro.

Table 5. BBGZAACK macro syntax
Syntax	Description
`name`	`name`: Symbol. Begin `name` in column 1.
ƀ	One or more blanks must precede BBGZAACK.
BBGZAACK
ƀ	One or more blanks must follow BBGZAACK.
ANAME=`angelname`	A-type address or register (2) - (12).

Parameters

The parameter is explained as follows:

ANAME: Specifies the address of the name of the angel to check. Including the terminating null, the length of this parameter must be between 1 and 55 characters, inclusive. Use a single null character to specify the default angel.

Return and reason codes

When control returns from the BBGZAACK macro, general purpose register (GPR) 15 contains the return code. Return code 0 indicates that the specified angel was found and is active. A non-zero return code indicates that the specified angel was not found or is not active.

Examples

The following examples assume that you copied the ${wlp.install.dir}/dev/api/ibm/zos/BBGZAACK file to your MACLIB.

Example 1

Check whether the default angel is active.


   USING PARMS,5         
   XC ANGLPARM,ANGLPARM Clear storage / null term
   BBGZAACK ANAME=ANGLPARM
   ST 15,ANGLRC Store return code
*
PARMS DSECT
ANGLPARM DS CL1
ANGLRC DS F

Example 2

Check whether an angel named ANGEL01 is active.

         
   USING PARMS,5 XC   
   ANGLPARM,ANGLPARM Clear storage / null term
   MVC ANGLPARM(7),ANGLNAME Copy angel name
   BBGZAACK ANAME=ANGLPARM
   ST 15,ANGLRC Store return code
*
   LTORG
   ANGLNAME DC CL7'ANGEL01'
*
PARMS DSECT
ANGLPARM DS CL8
ANGLRC DS F