RISGNL — Issue remote immediate signal

Description

The RISGNL macro uses the emergency signal (EMS) order code of the signal processor (SIGP) instruction to invoke the execution of a specified software program on a specific processor in a multiprocessing configuration. The program may be requested to execute in parallel or serially with the function requesting the program. The specified software program (receiving routine) gets control disabled, in key 0, and supervisor state. The receiving routine cannot enable for I/O or external interrupts, request locks, or issue SVCs. In addition, the receiving routine must return via the address in register 14.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state and PSW key 0
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN=SASN or PASN¬=HASN¬=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary or secondary
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	No locks required
Control parameters:	None

Programming requirements

The receiving routine must be loaded into page-fixed, common storage.
The caller must include the CVT mapping macro.

Restrictions

If the receiving routine establishes an FRR, the FRR should not depend on the storage areas passed to it by the signalling routine. When alternate CPU recovery (ACR) is active, the signalling routine might receive control from RISGNL before the receiving routine's FRR gets control. IBM® recommends that the receiving routine's FRR access only storage areas owned independently of the signalling routine. If the receiving routine's FRR attempts to access storage and the signalling routine has already freed the storage, the FRR might abnormally end.

Input register information

Before issuing the RISGNL macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

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 macro was issued. 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 GPRs contain:

Register: Contents
0-1: Used as work registers by the system
2-10: Unchanged
11-12: Used as work registers by the system
13: Unchanged
14: Address of calling program
15: Return code

Performance implications

None.

Syntax

The RISGNL macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede RISGNL.

RISGNL

␢	One or more blanks must follow RISGNL.

PARALLEL
SERIAL

,CPU=`PCCA addr`	`PCCA addr`: RX-type address, or register (1).

,EP=`entry name addr`	`entry name addr`: RX-type address, or register (12).

,PARM=`parm addr`	`parm addr`: RX-type address, or register (11).

Parameters

The parameters are explained as follows:

PARALLEL
SERIAL: Specifies that control is to be returned to the caller when the specified receiving routine has been given control (PARALLEL) or has completed execution (SERIAL) on the designated processor.
,CPU=PCCA addr: Specifies the address of the physical configuration communication area (PCCA) of the processor on which the function is to be performed.
Note: The PCCA must reside in 24-bit addressable storage.
,EP=entry name addr: Specifies the address of the receiving routine to be executed on the specified processor. The receiving routine will get control in the same addressing mode as the macro issuer.
,PARM=parm addr: Specifies the address of a user-defined fullword parameter to be passed to the receiving routine. When the receiving routine receives control, general purpose register one points to a fullword parameter.

ABEND codes

07B

See z/OS MVS System Codes for an explanation and programmer responses for this code.

Return codes

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

Table 1. Return Codes for the RISGNL Macro
Return Code	Meaning and Action
00	Meaning: Specified receiving routine has been given control or has completed execution, as requested. Action: None.
04	Meaning: Environmental error. Function not initiated because addressed processor not online. If it appeared to be online, it is no longer in the configuration. Action: None required. However, you might take some action based upon your application.
14	Meaning: Environmental error. Function not initiated because addressed processor was taken offline during RISGNL processing. Action: None required. However, you might take some action based upon your application.

Example 1

The routine whose address is in register 12 is to be given control on the processor whose PCCA address is in register 1. Return control to the caller when the specified receiving routine has been given control.

RISGNL PARALLEL,CPU=(1),EP=(12)

Example 2

The routine whose address is in register 12 is to be given control on the processor whose PCCA address is in register 1. The routine will complete before the caller of RISGNL receives control again. Register 11 contains the address of a parameter to be passed to the receiving routine.

RISGNL SERIAL,CPU=(1),EP=(12),PARM=(11)