Proposed REXX Script Standards for OS/2 IRC CLients
The RxScript Standard
Draft: 11/16/96 - Revision 0.007

Charter:

To develop a set of implementation standards for OS/2 based IRC clients regarding REXX procedure scripts such that a reasonable level of portability of scripts may be achieved between the various clients.

Revision Changes:

Changes to this draft by this revision include amendments to or addition of item numbers 101/003 102/004 110/005 112 115/006 117/007

Foreword:

This is a working document for establishing a standard feature set for REXX procedure scripts in OS/2 based IRC clients. Once all items have reached some resolution, this document (after some reformatting) will be regarded as the official standards. The primary purpose of this document at this time is to maintain some type of order to our proceedings and to keep everyone updated as to where we stand on each item.

Each item for discussion and resolution is described below and contains an identifying item number. Please use the item number when discussing and item. Each item open to general discussion is marked as open. Items marked as closed have been resolved and are considered a future standard.

In addition, each item is marked as "Required" or "Optional". Required items are those features which must be implemented for a client to claim it meets these standards. Optional features do not have to be implemented at all, but if that feature is implemented it must be implemented in the specified manner to claim compliance with the standard.

Discussion is open to anyone who subscribes to the ircrexx (at) invlogic.com mailing list. Addition of new items and resolution of pending items is limited to voting members. The current voting members are:

Stephen Berg sberg (at) southwind.com
Mike McLagan mmclagan (at) invlogic.com
Benny Ormson ormson (at) ionet.net
Scott Palmer scottp (at) intergate.bc.ca
Kim Rasmussen kr (at) belle.dk

Item 001 Required Closed

Parameter information shall be provided to the various scripts in the form of preset variables with standard names. The method of implementation to set these variables is left to the individual client. In order to be in compliance, the client must provide the preset variables shown below. The client may provide other preset variables in addition to these.

IrcWinHandle - The window handle from which the script being executed originated. Note (1) applies.

IrcServHandle - A server identification. Note (1) applies.

IrcTarget - Window identifier. Normally the window title. This is usually the channel name for a channel window, a nickname for a query window, etc. Note (2) applies.

IrcTargetType - Determines the type of target. Defined values include CHANNEL, QUERY, DCC, RAW, TALK, PROCESS, INVALID, and UNKNOWN. Clients are not required to support all of the defined types. The INVALID type shall be set if IrcTarget is not equal to "CMD".

IrcNick - The client's current nickname on this server.

IrcType - The type of script being executed. "CMD" "MSG" "SA" etc.

IrcParm - Parameter specific to the type of script. For instance this would be "/command parms" for a CMD script.

IrcVerMajor - The RxScript Standard major version to which the client complies.

IrcVerMinor - The RxScript Standard minor version to which the client complies.

IrcClient - String identifying the client. The following clients are currently defined with the following assigned strings:

"GtIrc" - GammaTech IRC.
"InetAdv" - Internet Adventurer
"IRC/2" - IRC/2
"PMIRC/2" - PM IRC/2
(email me what you want for your client and I'll add it here)

Notes:

1. These variables shall be considered as atomic values. The script must not attempt to alter these variables or use the value of these variables in any manner other than for documented uses. The implementation of values for these variables is undefined and left to the client authors.
2. This variable is valid only if IrcType is equal to "CMD".

Item 002 Required Closed

Input parameters for standalone REXX scripts shall be as derfined in item number 001.

IrcType - This variable wil be set to "SA".

IrcParm - This variable will contain any parameters specified by the user to be passed to the REXX procedure.

Return values for standalone REXX scripts are ignored.

Item 003 Required Closed

Input parameters for the inbound message script shall be as defined in item number 001.

IrcType - This variable wil be set to "MSG".

IrcParm - This variable will contain the raw message as received from the IRC server.

Return values for the inbound message script shall be as follows:

"" The message is to be ignored by the client.
"OK" The message should be processed by the client.

Item 004 Required Closed

Input parameters for the output command script shall be as defined in item number 001.

IrcType - This variable wil be set to "CMD".

IrcParm - This variable will contain the complete /command string as entered by the user.

Return values for the output command script shall be as follows:

"" The command is to be ignored by the client.
"OK" The command should be procesed by the client.

Item 005 Required Closed

IrcRexxWildCard(<pattern&glt;,<string>>[,<options>>])

This function is used to determine if a string of text matches a wild card mask.

<pattern> The wild card pattern. e.g. *!user@*

<string> The string to be tested.

<options> Use of this parameter is optional. Specifying an option of "CASE" enables case sensitivity.

Returns:

"MATCH" The pattern was matched.
"NOMATCH" The pattern was not matched.

Item 006 Required Closed

A predefined script which recieves various event notifications.

The following preset variables will be available when this script is called:

IrcType The type of the script exit - "EVENT"

IrcEvent The type of event for which this script was called and defined in item 118.

Return values be as follows:

"" The message is to be ignored by the client.
"OK" The message should be processed by the client.

Item 007 Required Closed

Error return values shall be provided from all IrcRexxFuunctions() by setting a predefined REXX variable with the name IrcError prior to returning control to the script. Valid values for the IrcError variable are indicated below:

"OK" No Error
"ERROR" An Error has occured.
"ERROR,errorinfo" An Error has occured and is further described in the "errorinfo" text.

Item 103 Required Open

IrcRexxCommand(<command>,<win>)

This string <command> is executed as if it were user input from <win> window. Normally done by sending the text through the command parser. Command processing may call the REXX command script.

<command> Normally a /command but may be text to a window.

<win> The window handle of the window where the command output will be displayed.

Returns: Not defined.

Item 104 Required Open

IrcRexxDisplay(<text>,<win>)

This string <text> is displayed in the window specified by <win>.

<text> Any text to be displayed.

<win> The window handle of the window where the text is to be displayed.

Returns: Not defined.

Item 105 ??????? Open

IrcRexxFunction(<win>,<name>;&;lt;argsgt;)

I am not clear on what this function does.

<win> The window handle.

<name> The string to be tested.

<args> The string to be tested.

Returns:

Item 106 Required Open

IrcRexxIsOp(<channel>,<nick>,<win>)

This function is used to determine if a nickname is a channel operator on the specified channel. It can also be used to determine if a nickname is joined to the specified channel.

If <channel>, is "*" then the current channel is assumed. <channel>, must be a channel to which this client is joined.

<win> is the window handle for the server window.

Returns:

"YES" <nick> is a channel operator on .
"NO" <nick> is on but is not a channel operator.
"ERROR" <nick> is either not joined to or cannot be found.

Item 107 Required Open

IrcRexxSend(,<win>)

This string is transmitted as is to the server associated with <win>.

The text to be sent to the server.

<win> The server level window for the desired server. Clients which do not support multiple server connections may ignore this parameter but should permit it's presence for compatability.

Returns: Not defined.

Item 108 Required Open

IrcRexxTargetWindow(,)

This function is used to determine the best window handle to use for the specified target.

is the window handle of the server window.

is a nickname, channel name, dcc chat name, etc.

Returns:

The window handle in integer form for the specified target. If no window is found the window handle for the server window of is returned.

Item 109 Required Open

IrcRexxVariable(<win>,<name>[,<value>])

This function is used to set or retrieve a IRC variable.

<win> The window associated with the variable. Normally this is the server window. Variables which are window specific may be accessed by using the appropriate window handle here.

<name> The name of the $variable. Variable names normally begin with $. All uppercase names are by definition, system level variables. Users are encouraged to use variable names which are either all lower case or mixed case for future compatibility.

<value> If specified, the variable <name> is set to this value provided it is a variable which may be altered by the user. If this parameter is not specified the call is considered a query for the variables current value.

Note: If <value> is specified and the variable <name> does not exist it is created.

Returns: The current value of the variable or "" if an error occurs.

The following variable names are standardized:

$NICK The users current nickname.

$VERSION A short version string identifying the client and it's version. The version sting is of the format "client version" where the client section identifies the client and contains no embedded spaces and the version section contains the version of the client with no embedded spaces. The client and version sections are seperated by a single space. e.g. "GtIrc 2.03"

Item 111 Optional Open

Some method of setting a timer in a script to have a script executed after "n" seconds. Perhaps with options to have it executed "n" seconds of inactivity, or not, and whether it is a one time or recurring event. If recurring, we also need a way to kill it.

Item 113 Optional Open

IrcRexxAddMenu(<unknown>)

Permits a script to add menu choices onto some or all menus.

Item 114 Optional Open

IrcRexxAddTool(<unknown>)

Permits a script to add items to toolbars.

Iftem 116 ???????? Open

A method which permits the script to identify what optional features are supported for any given client and version of that client.

A number of ideas and research into this are currently underway.

Item 118 Optional Open

This item defines the values for the IrcEvent type variable as passed to the event script defined in item 006.

IDLE <time> TIMER <whatever> FLOOD <various info> INIT

Item 119 Optional Open

Provide the option to preload REXX scripts in order to improve performance. Also an option should be provided to enable the script to be reloaded or unloaded. The method by which this feature is implemented is left to the individual client.

Item 120 Optional Open

Provide method of redirection of I/O for REXX functions such as PULL, SAY and error message output. The precise method of implementation is left to the client.

Item 121 Optional Open

Provide an exit to supress return values not accounted for by the script so they do not get passed to the environment for processing.

This addresses the overhead and associated problems dealing with needless output passed to the client as a result from the script not specifying a variable to receive returned output.

Report any access issues to our webmaster.