ScreenPM - Screen Private Messages Home
Contact Us

Service Request
Catalogs / Manuals
Support Forum

Copyright (c) 2005 by J. Bart Henthorn

All Rights Reserved - May not be used without explicit permission from J. Bart Henthorn. Contact the author at:

for information and to obtain permission to use ScreenPM.

Table of Contents

1. The Purpose of ScreenPM
2. How ScreenPM Works
3. Installing ScreenPM
3.1 Loading ScreenPM into mIRC
3.2 Customzing ScreenPM
4. The ScreenPM Commands
4.1 ScreenPM Help
4.2 ScreenPM ON and ScreenPM OFF
4.3 ScreenPM DNDON and ScreenPM DNDOFF
4.4 ScreenPM LIST
4.5 ScreenPM CLEAR
4.6 ScreenPM REMOVE
4.7 ScreenPM ALLOW
4.8 ScreenPM ONCE
4.8.1 Automatic ONCE
4.9 ScreenPM BLOCK
5. The ScreenPM Window
5.1 The Pending Tab
5.2 The Allowed Tab
5.3 The Blocked Tab
Appendix A - Revision History

ScreenPM is a script designed for use with the mIRC program written by Khaled Mardam-Bey. It has been tested with v6.16 but may work on other versions. However there is no guarantee of that. If you try it on your version and it works, please let the author know.

1. The Purpose of ScreenPM

One of the most annoying things about IRC chat programs is their ability to receive "Private Messages" or "PMs". Yes, a PM can be very handy and useful, but when they arrive without warning they can also be annoying. In many "busy" IRC forums, PMs arrive so rapidly that just closing all the windows can consume all of your time.

Since there is no way to control who can send a PM, the bother becomes too much, and often results in frustration or anger. Some have even left IRC chat in general because of the frustration.

ScreenPM is a script designed to work with the mIRC client program that is very common among IRC chatters. Instead of blocking PMs, ScreenPM provides an easy way to manage and control them.

There are many such scripts on the scene these days, but most do a lot of other things too. Not wishing to install those "end all, do all" scripts, I set about writing one that does one thing and hopefully does it well.

2. How ScreenPM Works

ScreenPM maintains three "lists". One contains the nicknames of those that have sent PMs and are previously unknown to you, one contains the nicknames of those allowed to send you PMs, and the last contains the nicknames of those that are not allowed to send PMs. These two lists, the Allowed and Blocked lists, are collectively referred to as the "Known List".

When you receive a PM from someone previously unknown to you, their message is saved and a response is sent indicating you are not accepting PMs at the moment. Their nickname is then added to the Pending list and you see a message in the active window that indicates a new message has been received. Any further messages from the same person are discarded and no further notices are displayed to you.

You can respond to their PM in one of several ways. You can allow the person to PM with you using the ALLOW command, you can block them from sending PMs using the BLOCK command, or you can simply ignore them and leave them on the Pending list. Leaving them on the Pending list has essentially the same effect as blocking them, except that when you CLEAR the Pending list, their next PM will notify you and add them back to the list. Blocking them prevents them from ever sending you another PM and will not bother you with notices when they try.

ScreenPM provides two methods for managing the lists. You may either use commands to ScreenPM, or you may use the control window. Both methods are provided by ScreenPM and both may be used interchangeably without special consideration. Changes made using commands are instantly shown in the control window when it is displayed.

3. Installing ScreenPM

ScreenPM is provided as a text script file called "ScreenPM.mrc". It must be copied to the mIRC program folder and then loaded into mIRC by use of a special command. When ScreenPM is loaded, several commands are executed. These commands, referred to as "Initialization" commands, must be allowed to run in order for ScreenPM to work properly.

Unzip the ScreenPM.mrc file and copy it to the same folder where mIRC is installed. If you are not sure what folder that is, enter the following command into the mIRC Status Window:

//echo $mircdir

The response will be the full drive and path of the folder that contains the mIRC program file and configuration files. For example:

C:\Program Files\mIRC

If you are upgrading to a newer version of ScreenPM then you must overwrite the previous file with the new version. You can then use the regular Load command to install the new version.

3.1 Loading ScreenPM into mIRC

You must enter a special mIRC command to cause it to read the script file and add it to those scripts mIRC understands. After copying the script file to the mIRC program folder, enter the following command into the mIRC Status Window:

/load -rs screenpm.mrc

Immediately after loading, you may see a window warning you that the script contains commands that will run during the load process. This is normal and is part of the process by which ScreenPM installs itself. These commands initialize variables used by ScreenPM for proper operation.

You MUST click "Yes" to allow the Initialization to run and for ScreenPM to work properly. If you accidentally answer "No", you can load it again using the same command, but choose "Yes" instead. This will not cause the loss of any information from previous versions or previous runs.

When the load process is complete, you will see messages that are similar to the following:

* Loaded script 'C:\Program Files\mIRC\screenpm.mrc'
* ScreenPM ver 2.3 is now Loaded!
* All functions are active. Type /ScreenPM Help for instructions.

You are now protected against all new PMs. To learn how to use ScreenPM, type:

/screenpm help

The full command list will be displayed along with brief instructions on the function of each command.

If you prefer, you may use the "Window Interface" of ScreenPM. To open and access the ScreenPM window, type the following command:


3.2 Customzing ScreenPM

ScreenPM allows a small amount of customization too. The text sent to someone when they PM you for the first time, the text sent when they are added to your Allowed list, and the way those responses are sent may all be modified by changing the values of variables. The variables are set when ScreenPM is loaded, but may also be modified directly in mIRC by using the Alt+R command and selecting the "Variables" tab.

screenpmPMsOffMsg - This variable contains the text sent when someone sends you a PM for the first time. It should tell them that your PMs are shut off at the moment, but that their nickname and PM message have been saved.

screenpmAllowMsg - This variable contains the text sent when you "Allow" PMs from someone that has already sent you a PM. It should tell them that they may now send more PMs if they wish.

screenpmSendNotices - This variable determines how the above responses are sent. The default value is '0' to indicate that responses are sent as PMs. This is usually the best setting since people that send PMs often have their PM window still open. Change it to '1' to send the responses as Notices instead.

4. The ScreenPM Commands

ScreenPM may be controlled by using several different commands. Just like the commands you enter to mIRC, commands to ScreenPM must all begin with a forward slash "/" and must start with the word ScreenPM. To save typing time, you may also use the shorthand form "spm". Thus the following two commands are identical:

/screenpm help
/spm help

4.1 ScreenPM Help

The first place to start is with the ScreenPM Help. The Help text gives very brief information on how to use ScreenPM properly. The actual text may vary but will appear similar to this:

* ScreenPM will block incoming PMs from unwanted people.
* Commands are:
* HELP - Display this text.
* ON - Turn On screening of PMs
* OFF - Turn Off screening of PMs
* DNDON - Turn Off ALL PMs of any kind from anyone (Do Not Disturb)
* DNDOFF - Turn On normal PM processing (Cancel Do Not Disturb)
* ALLOW <nickname> [replytext] - Allow <nickname> to send you a PM
* [replytext] is optional and if included will be sent as a reply
* BLOCK <nickname> - Prevent <nickname> from sending a PM
* LIST - List the names in the Known and Pending lists
* CLEAR - Clear all the names in the Pending list
* REMOVE <nickname> - Remove <nickname> from Known and Pending lists
* (blank) - Displays the ScreenPM Control Window
* ScreenPM is currently On
* All PMs are being blocked (DND Mode)

The last two lines of the Help text show you the current state of ScreenPM's protection; either "On" or "Off" and the DND state if enabled.

4.2 ScreenPM ON and ScreenPM OFF

These two commands allow you to turn ScreenPM's protection on and off. Turn ScreenPM's protection on by using the command:

/ScreenPM ON

Turn if off by using the command:

/ScreenPM OFF

4.3 ScreenPM DNDON and ScreenPM DNDOFF

There are times when you do not wish to receive any PMs at all. This is also known as "DND" or "Do Not Disturb". ScreenPM allows you to temporarily block all PMs with the DNDON command. You can allow PMs to be handled normally with the DNDOFF command.

Enable DND Mode (turn off all incoming PMs) with the command:


Cancel DND Mode and allow normal PM processing with the command:


4.4 ScreenPM LIST

This command lists the nicknames in the Pending, Allowed and Blocked lists. This is a handy way to see how many names are on the Pending list (if any) and to quickly review who has been Allowed and who has been Blocked from sending PMs.

/ScreenPM LIST

4.5 ScreenPM CLEAR

This command deletes all the nicknames stored in the Pending list. It should be used periodically to empty the list of pending PMs. All nicknames stored in the Pending list will be deleted, so you should make sure to ALLOW or BLOCK anyone you wish to keep (either allowed or blocked from sending PMs).


4.6 ScreenPM REMOVE

The REMOVE command is used to remove (or delete) a specific name from the Pending, Allowed and Blocked lists. Once you Remove a nickname, if that person sends another PM, they will be "unknown" and will receive the same reply as someone who sends you a PM for the very first time.

/ScreenPM REMOVE <nickname>

You must include the nickname you wish removed. For example:

/ScreenPM REMOVE BadBoySendingPMs

Note that the case of a nickname is not important. Thus these two commands are identical:

/ScreenPM REMOVE badboysendingpms

4.7 ScreenPM ALLOW

The ALLOW command has several uses. How it is used and when it is used depends on whether or not you have received a PM from someone already. However, no matter which way you use it, the result is that all future PMs will be allowed as long as they are from the nickname you enter.

/ScreenPM ALLOW <nickname>

If you have already received a PM from this person, their nickname will be removed from the Pending list and placed onto the Allowed list. ScreenPM will then send a PM to them notifying them that PMs are now allowed and a new Query Window will open. The text of their first PM will be displayed for you, and you may immediately begin typing to them via the normal PM process.

You may also include an opening line of text that will be sent to the person when the Query Window is opened. For example:

/ScreenPM ALLOW GoodGuyILike Hello GoodGuy. I like you.

The person using the nickname "GoodGuyILike" will receive the message that PMs are now allowed, immediately followed by the message "Hello GoodGuy. I like you."

If you have not previously received a PM from the person or if they were previously blocked, their nickname will simply be added to the Allowed list. However, no reply PM will be sent. This allows you to add someone to your list ahead of time; for example, if you know they will be sending you a PM soon or if you wish to give them prior approval. Since no Reply PM is sent though, you cannot add the optional reply text after their nickname.

4.8 ScreenPM ONCE

This command works just like the ScreenPM ALLOW command (above) with one exception. When the PM window is closed, the person's nickname will be removed from the Allow List. This enables you to temporarily accept PMs from someone, but not permanently add them to your Allow List. (Very handy for ChanOps and others that have a lot of PMs with new people that they do not necessarily wish to allow again.)

4.8.1 Automatic ONCE

When someone previously unknown to you sends a PM, and then you subsequently open a PM window to them, ScreenPM will perform an automatic ONCE command. This adds them to your Allow List for this one time. As soon as you close the PM window, their name will be removed from the Allow List automatically.

4.9 ScreenPM BLOCK

This command is used to permanently block all PMs from someone. When they attempt to send a PM to you, ScreenPM will simply discard it and will not notify you of the attempt, nor will it notify the person that their PMs are being blocked. As far as they know, their PM simply disappeared or you are totally ignoring them.

Even if the person was previously Allowed to send PMs, or if they have never sent a PM before, no message will be sent to them notifying them that they are now blocked. As the old saying goes, best to let sleeping dogs lay.

/ScreenPM BLOCK <nickname>

Once a nickname is marked as Blocked, no further PMs from them will appear in mIRC. You must either REMOVE them or ALLOW them in order to begin receiving their PMs again.

5. The ScreenPM Window

Sometimes it is much easier to just "point and click" in order to get something done. While the commands for ScreenPM are few and easy to remember, typing the exact nicknames is not. Therefore ScreenPM includes a full windowed interface as well. Using the ScreenPM Window gives you a simple and accurate means of managing the Pending, Allowed and Blocked lists, as well as allowing you to quickly turn ScreenPM's protection on or off.

The ScreenPM Window is displayed simply by entering the ScreenPM command without any additional text:


The top of the window contains a checkbox labeled "ScreenPM Enabled". When the checkbox is ticked, ScreenPM's protection is enabled. When the checkbox is cleared, ScreenPM's protection is disabled. Changing the state of the checkbox immediately turns the protection on or off.

Below the checkbox are three "tabs", one for each of the three lists. The use of the three tabs is described in more detail in the following sections.

5.1 The Pending Tab

The nicknames of people that have sent you PMs but were not already in either the Allowed or Blocked lists are shown on this tab. Also shown with the nickname is the text of the first PM sent. This allows you to quickly see who sent the PM and what it said.

Below the list are four buttons: Allow, Block, Remove and Clear. The buttons will be enabled when their functions are permitted.

Clear - This button clears the Pending list, deleting all nicknames in the list. You must answer "Yes" to a prompt window to verify that you wish to clear the Pending list. Answering "No" will preserve the names in the list.

Allow - This button will move a nickname from the Pending list into the Allowed list. Just like the ALLOW function (section 4.6 above), a message will be sent to the person notifying them that PMs are now allowed and a new Query Window will open in mIRC that allows you to begin a PM conversation with them.

Block - This button will move a nickname from the Pending list to the Blocked list. No notification will be sent to the person that their PMs are now blocked, however no future PMs will be accepted from them nor will you be notified of any further PMs they send.

Remove - This button removes the nickname from the Pending list. The next time a PM is received from them, they will be notified that their PM was received and you will receive a notice that a new PM has been received.

5.2 The Allowed Tab

The Allowed Tab lists the nicknames of people that are allowed to send you PMs. Below the list are three buttons: Send PM, Remove and Block.

Send PM - This button opens a new Query Window in mIRC and begins a PM conversation. It is a handy way to PM someone that is already in your Allowed list.

Remove - This button removes a nickname from the Allowed list completely. The next time this person sends you a PM, their nickname will be added to the Pending list exactly as if it was the first time they had ever sent you a PM.

Block - This button removes a nickname from the Allowed list and adds it to the Blocked list. No notification is sent to the person that their PMs are now blocked, nor will you be notified should they send more PMs in the future.

5.3 The Blocked Tab

The Blocked Tab lists the nicknames of the people that are prevented from sending you PMs. If anyone from this list sends a PM, they will not be notified that the PM was ignored nor will you be notified that their PM was received and discarded.

There are two buttons on this tab: Remove and Allow.

Remove - This button removes a nickname from the Blocked list completely. The next time this person sends you a PM, their nickname will be added to the Pending list exactly as if it was the first time they had ever sent you a PM.

Allow - This button removes a nickname from the Blocked list and adds it to the Allowed list. All future PMs from this person will be allowed and you will be notified when a new PM is received. No notification is sent to the person that their PMs are now allowed.

Appendix A - Revision History

2.7 - Fixed a problem that causes false logging when switching to the Status Window. Also added a feature that shows the text of the initial PM from an unknown person in the PM Notification message. This greatly helps in deciding whether to allow, once or ignore a PM.

2.6 - Added the ONCE command to allow PMs from someone only once. Their name will be removed from the ALLOW list as soon as the PM window is closed. Also added "Automatic ONCE"; when you receive a PM from an unknown person and then open a PM to them, ScreenPM does a ONCE command automatically.

2.5 - General fixes. Nothing major.

2.4 - Added PM Logging. All PMs, no matter how they are handled, are logged in a file called ScreenPM.csv. The file is formatted with TAB characters and may be rapidly loaded into various programs for analysis and review of PMs received.

2.3 - Added a DND (Do Not Disturb) feature that allows rapidly disabling receipt of all PMs regardless of the sender.

2.2 - Cleaned up the Help text and added some variables to make it easier to customize the responses sent to people sending PMs. Also added the option to send responses via NOTICE instead of by MSG or QUERY.

2.1 - Fixed bugs regarding nicknames with square brackets '[' and ']' in them. Also fixed bug that caused a name to remain on the Pending List display even though it was properly moved to the Allowed List. Also the first version to include a ReadMe file (this file).

2.0 - First release that includes the new ScreenPM Window Interface.

1.2 - Added support for multi-server connections. Prior versions would not return a PM to the proper server if it was received on a different connection than the current one.

1.1 - Minor bug fixes and enhancements. Added the ability to include optional reply text with the ALLOW command.

1.0 - Initial Release.


Home | Products | F.A.Q. | Service Request | Suggestions | Catalogs / Manuals | Support Forum

Questions or problems regarding this web site should be directed to
Copyright 2007-2012 GreyFace Productions. All rights reserved.
Last modified: 08/07/2012.