SafeFire PPP REXX API Extension

v.0.9 beta

Contents

Introduction

To achieve maximum flexibility SafeFire PPP provides ways to execute external REXX scripts to perform particular tasks.

Such ways are called REXX exits or REXX hooks. SafeFire supports REXX exits for following tasks:

During processing of the REXX exit a set of Common REXX API extensions provided by SafeFire PPP are available. Particular REXX exit may provide an additional REXX API extensions specific for this exit.

Connection REXX exit

This REXX exit is called by SafeFire PPP during processing of the normal connection sequence or during processing of the call back connection sequence.

When REXX exit is called it receives the following parameters (parameter passing is compatible with standard PPP.EXE):

  1. Interface index

    This index should be later passed without modifications as a parameter to PPP_COM_* and PPP_Modem functions (see below).

  2. COM port name

    This parameter may be useful for logging or other purposes.

  3. Other parameters provided by user in script command line

    They are passed as-is and SafeFire PPP has no control over it.

During processing of this exit following additional API's are available (those marked as new are introduced in SafeFire PPP and not supported by standard PPP.EXE):

Message processing REXX exit

This feature is enabled by setting variable message.hook in plugman section to the name of the file with message processing script. During processing of this script Common REXX API is available.

This exit is called every time when message in passed into Message queue. Each time it receives following parameters:

  1. Message name

    Messages and its names are described in Message Reference book.

  2. Additional information size

    This parameter is set to size of the third parameter len if it is not empty, or 0.

  3. Additional information

    Additional information provided with the message.

  4. Message source

    Name of the sender of the message.

NOTE: Before message will be passed to REXX exit it will be stored in message queue. If REXX exit is unable to process messages fast enough, then some messages may be lost and appropriate log entries will be generated.

Message log REXX exit

To enable this feature set variable log.hook in plugman section to name of the file with message log processing script.

REXX exit script receives the same parameters as Message processing REXX exit, except message names. This method of parameter passing was chosen to enable use of the same script for both tasks: Message processing and Message log processing.

This REXX exit can receive one of the following message names (each message name corresponds to message importance level):

MSG_00000200Emergency"system is unusable"
MSG_00000201Alert"action must be taken immediately"
MSG_00000202Critical"critical conditions"
MSG_00000203Error"error conditions"
MSG_00000204Warning"warning conditions"
MSG_00000205Notice"normal but significant condition"
MSG_00000206Info"informational"
MSG_00000207Debug"debug-level messages"

Message itself is passed as Additional information parameter (see Message processing section).

Common REXX API

This section describes part of REXX API available for all scripts executed by SafeFire PPP.

Common REXX API extension can be divided into several parts: