## SafeFire PPP REXX API Extension

### v1.0

# Contents

- Introduction
- REXX exits
  - Establishing of the connection
  - Message processing
  - Processing of the SafeFire PPP message log
  - User Authentication
- Common REXX API
  - Data Storage
  - Process Management
  - Message Bus
  - SYSLOG Logging facility
  - Configuration data access

# 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:

- Establishing of the connection

  This is a traditional REXX exit which is very useful when unusual processing is required before connection will be established.

  Additional API's provided for this REXX exit are compatible with standard PPP.EXE but has few additional functions which will simplify writing of connection scripts and allow control over the COM port modem control lines.

- Message processing

  Each event happened during SafeFire PPP work can be used to perform special tasks associated with this event. For example information that PPP connection is established can be used to start process of retrieving mail or to inform user by changing the look of the custom made user interface.

  Accessible from inside the REXX script additional functions allow to pass messages back to SafeFire PPP and to control SafeFire PPP: skip to next phone number, exit from program, reset idle or connection timer etc.

- Processing of the SafeFire PPP message log

  Although SafeFire PPP provides mechanism to filter out message based on the message importance level, it may be useful for particular application to filter out message using other criteria.

  Other similar task is routing messages into custom log facility, for example user interface application with message log window.

  Message log REXX exit provides convenient and flexible way to accomplish this tasks.

- User Authentication

  This REXX exit is not a feature provided by SafeFire PPP but rather by one of the authentication plugins. More details about it can be found here.

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):

- PPP_COM_Input - read string from COM port.

  str = PPP_COM_Input(index[, size[, timeout]])

  index | interface index as it passed to REXX exit
  size | number of bytes to read
  timeout | how long to wait before return (0 - wait forever)

  Returns: string received from COM port.

- PPP_COM_Output - write string to COM port.

  call PPP_COM_Output index, string

  index | interface index as it passed to REXX exit
  string | string to write to COM port

  Returns: none.

- PPP_COM_LineIn new - read string from comport ended by CR character.

  Parameters and return value is the same as for PPP_COM_Input.

- PPP_Getch - get one character from keyboard.

  key = PPP_Getch()

  Returns: character received from keyboard

- PPP_Modem new - get/set modem status lines.

  modem_status = PPP_Modem(index[, command])

  index | interface index as it passed to REXX exit
  command | 'DTR_ON', 'DTR_OFF', 'RTS_ON' or 'RTS_OFF'

  Returns: modem status string.

  Modem status string may contain following substrings: CTS DSR RI DCD.
  If modem line is set, then result string contain appropriate substring. For example: result string 'CTS RI' means that appropriate modem lines are set and rest of lines are reset.

# 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 length 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_00000200 | Emergency | "system is unusable"
MSG_00000201 | Alert | "action must be taken immediately"
MSG_00000202 | Critical | "critical conditions"
MSG_00000203 | Error | "error conditions"
MSG_00000204 | Warning | "warning conditions"
MSG_00000205 | Notice | "normal but significant condition"
MSG_00000206 | Info | "informational"
MSG_00000207 | Debug | "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:

- Data Storage

  Because REXX scripts called every time in the state 'from scratch', it is extremely helpful to have some kind of storage for variables which should live between calls. Data Storage is addressing this issue.

- Process Management

  Process Management API at present time consists from one function which allows to run particular script in separate thread.

- Message Bus

  Message Bus is a message passing mechanism which allows SafeFire PPP to pass miscellaneous information to script and receive control commands. Information through Message Bus includes internal state changing events and information obtained during normal PPP negotiation. In response script may pass control messages which will change state of the SafeFire PPP.

- Log facility

- Data Storage API

  - SF_Set_Var

    SF_Set_Var(VarName[, VarValue])

    Set variable pointed by VarName to value VarValue or delete VarName if VarValue is not specified.

    Example:

        FileName='c:\os2\apps\data\ISP.cfg'

        VarValue = SF_Set_Var('FileName', FileName)

  - SF_Get_Var

    VarValue = SF_Get_Var(VarName[, DefValue])

    Get value of the variable pointed by VarName.

    If variable can not be found DefValue is returned. If DefValue is not specified, TRANSLATE(VarName)is returned.

    Example:

        FileName='c:\os2\apps\data\ISP.cfg'

        VarValue = SF_Set_Var('FileName', FileName)

        VarValue = SF_Get_Var('FileName')
        say VarValue

  - SF_Drop_Var

    SF_Drop_Var(VarNameStart)

    Drops all the variable with names starting with VarNameStart

    Example:

        call SF_Set_Var 'Value.0', 1
        call SF_Set_Var 'Value.1', "First value"
        call SF_Set_Var 'Value.2', "Second value"
            ...
        call SF_Drop_Var 'Value.'

- Process Management API

  - SF_Start

    SF_Start(ScriptName)

    Start script pointed by ScriptName in separate thread in SafeFire PPP REXX context (all SafeFire PPP's REXX API extensions are available, including those provided by plugins).

    Example:

        call SF_Start(ScriptName)

- Message Bus API

  NOTE: Functions described below as well as message bus call back uses the same coding for message names described in Message Reference book.

  - SF_GetMsg

    SF_GetMsg()

    This function returns message from message queue. If no messages are present in the queue then function waits for message.

    Received message is returned in the form MESSAGE:SOURCE:INFO, where MESSAGE is a name of the message as described in Message Reference book, SOURCE is a source of message (see below) and INFO is an additional information passed with message (see Message Reference for details).

    Message source is a name of the plugin or plugin configuration section or one of the predefined names. In most cases this is name of the configuration section. This parameter may or may not be informational, depending on the particular message. Message passed to message bus through SF_PostMsg has SOURCE set to rexx.

    Example:

        Message = SF_GetMsg()

        parse value Message with msg':'source':'info

        if msg='MSG_00000063' | msg='MSG_00000064' then
        do
        	say 'DNS set to 'info
        end

  - SF_PostMsg

    SF_PostMsg(MsgName, MsgInfo)

    This function places message into message queue. MsgName is in format described in Message Reference book and MsgInfo is information associated with message.

    NOTE: Although there are no restrictions to which message will be passed into message bus with this function, most of the messages are informational and will not affect SafeFire PPP. Control messages are not covered by this rule.

- SYSLOG Logging facility

  - SF_SysLog

    SF_SysLog(MessageType, MessageText)

    MessageType is one of the following:

    MessageType | Priority | Priority meaning
    EMERG | 0 | "system is unusable"
    EMERGENCY | 0 | "system is unusable"
    LOG_EMERG | 0 | "system is unusable"
    ALRT | 1 | "action must be taken immediately"
    ALERT | 1 | "action must be taken immediately"
    LOG_ALERT | 1 | "action must be taken immediately"
    CRIT | 2 | "critical conditions"
    CRITICAL | 2 | "critical conditions"
    LOG_CRIT | 2 | "critical conditions"
    ERR | 3 | "error conditions"
    ERROR | 3 | "error conditions"
    LOG_ERR | 3 | "error conditions"
    WARN | 4 | "warning conditions"
    WARNING | 4 | "warning conditions"
    LOG_WARNING | 4 | "warning conditions"
    NOTE | 5 | "normal but significant condition"
    NOTICE | 5 | "normal but significant condition"
    LOG_NOTICE | 5 | "normal but significant condition"
    INFO | 6 | "informational"
    INFORMATION | 6 | "informational"
    INFORMATIONAL | 6 | "informational"
    LOG_INFO | 6 | "informational"
    DBG | 7 | "debug-level messages"
    DEBUG | 7 | "debug-level messages"
    LOG_DEBUG | 7 | "debug-level messages"

    This function passes message to SYSLOG facility. If appropriate daemon (SYSLOGD) is running then message will be logged according to SYSLOGD settings. For more information about SYSLOGD see OS/2 TCP/IP Command Reference.

- Configuration data access

  - SF_Get_Config

    SF_Get_Config(section, variable[, ordinal])

    This function returns value of the variable from specified section of configuration file(s) loaded at startup. For variables that may present in configuration more than once, optional ordinal parameter can be specified. If ordinal is passed as 0 then number of variable instances will be returned. If variable or section does not exists then empty string is returned. If variable present has multiple instances and function is called without ordinal parameter, then last instance is returned. Last instance also used by SafeFire PPP.

Return to documentation index | SafeFire PPP (C) Link Guard Solutions 1999, 2000