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:
This is a traditional REXX exit which is very useful when not usual 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.
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.
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.
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.
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):
This index should be later passed without modifications as a parameter to PPP_COM_* and PPP_Modem functions (see below).
This parameter may be useful for logging or other purposes.
They are passed as-is and SafeFire PPP has no control over it.
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.
call PPP_COM_Output index, string
index | interface index as it passed to REXX exit |
string | string to write to COM port |
Returns: none.
Parameters and return value is the same as for PPP_COM_Input.
key = PPP_Getch()
Returns: character received from keyboard
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.
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:
Messages and its names are described in Message Reference book.
This parameter is set to size of the third parameter len if it is not empty, or 0.
Additional information provided with the message.
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:
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 API at present time consists from one function which allows to run particular script in separate thread.
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.
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)
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(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.'
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)
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()
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(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.
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.
Return to documentation index | SafeFire PPP (C) Link Guard Solutions 1999 |