AUTHCALL

Format

Purpose

Use the AUTHCALL macro to call an authorized program from an unauthorized program. An important feature of GCS is that it permits an authorized program to be called by an unauthorized program. The authorized program resides in a shared segment, having been linked to its virtual machine at GCS initialization time. The unauthorized program resides in one of the virtual machines that makes up the group.

Note: In this context, an authorized program is one running in supervisor state, an unauthorized program is one running in problem state.

The AUTHCALL macro allows an unauthorized program to call an authorized program. However, AUTHCALL is not an authorized GCS function.

Parameters

EP

Specifies the name by which the authorized program is known to the unauthorized program. Note that this name is from one to eight alphanumeric characters long.

EPLOC

Specifies the address at which the name of the authorized program can be found. Again, this is the name by which the authorized program is known to the unauthorized program.

You can write this address as an assembler program label, as register (0), or as register (2) through (12). The name of the authorized program, as stored at this address, should be padded on the right with blanks if the name occupies fewer than 8 bytes.

UWORD

Specifies an optional fullword address that may be passed to the authorized program when it is called by the unauthorized program.

You can use this parameter to pass any information you wish to the authorized program.

The UWORD may be written as an assembler program label or as register (1) through (12). If you write it as a label, then the UWORD is passed to the authorized program as the address associated with that label. If you write it as a register, then the UWORD is passed to the authorized program as the contents of that register. If no UWORD is specified, it is passed as the value zero.

Usage

It is impossible for an unauthorized program to call an authorized program through the AUTHCALL macro unless the AUTHNAME macro is issued for that authorized program first. If necessary, review the entry titled AUTHNAME.
Any program started through the AUTHCALL macro runs in key 0.
Any program started through the AUTHCALL macro will run in the AMODE specified for it in the CONTENTS macro. See CONTENTS.

Examples

AUTHCALL EP=PATH

Calls an authorized program named PATH.

AUTHCALL EPLOC=(2),UWORD=(5)

Calls an authorized program whose name can be found at the address in register 2. Register 5 contains information that the program expects to receive from the program that called it.

The authorized program being called receives the following information in its registers.

Register	Contents
0	The user word (UWORD) specified in the associated AUTHNAME macro.
1	The user word (UWORD) specified in the AUTHCALL macro.
13	The address of the register save area.
14	The address to which control is to return after the authorized program completes execution.
15	The address of the entry point in the program being called.

Return Codes and ABEND Codes

Except for the return code noted in the following, the authorized program will pass its return code to the program that called it in register 15. The AUTHCALL macro generates the following return code.

If you receive a return code of -3 in register 15, do not mistake it for a return code generated by the program that you called.

Hex Code	Decimal Code	Meaning
X'FFFFFFFD'	-3	The system could not find the program whose address you specified.
X'30'	48	The CONTENTS entry has AMODE=CONTENTS or AMODE=CALLER, the caller is in AMODE 24 and the exit address is above the 16MB line.

ABEND Code	Reason Code	Meaning
FCB	0100	A call was made to an authorized program that is not available to the unauthorized program.
FCB	0102	The GETMAIN macro, issued by GCS, was unable to obtain enough storage to complete your request.