The purpose of this tutorial is to help people understand the purpose, usage, and proper decision-making in using ini files. This tutorial will cover the basics:

*Description of INI files
*When to Use an INI file, and when to use a different method (e.g. Hash).
*Using mIRC's commands associated with INI files.

INI Files: What are they, and what are they good for?

An INI file is just like a regular text document, except that it is written with a structure to support handling of individual items under what are called sections. INI files are commonly used to store settings or multiple parameters for items, where each item would have its own section.

To get an understanding of how this structure is set up, in your mIRC type:

Code

This will make a file pop up, showing you the contents of the INI file that mIRC uses to store most basic settings. As you can see, there is a structure here, arranged in a pattern of:

Code

Thus, when mIRC needs to find a particular value, it will just check the appropriate Section. Say it wants to check on what files it needs to load up on starting, it will check the section [rfiles], and then go through each item number and load the value for that file.

NOTE: DO NOT EDIT MIRC.INI, WE HAVE OPENED IT FOR OBSERVATION PURPOSES ONLY.

mIRC has a method built-in for allowing you to handle your own INI files, also. These can be quite useful if you need multiple things to be "remembered" for, say, one nickname. Thus, using the built-in /writeini command, we can begin setting up a file structure for a new ini.

Let us pretend, for instance, that you have the following code loaded in your mIRC:

Code

And we have an ini file that looks like this:

Code

Every time NICKNAME_001 typed a line in a channel, it would first read Lines, under the section [NICKNAME_001], and set the Value (4543) as %x. It would then increase the number (4544), and write that number back to the ini file. You do not have to specify that you want it to be overwritten, mIRC will automatically overwrite the old "Lines=" if it exists under the Section [NICKNAME_001]

You could use a setup like this just to keep tabs on user statistics, or do any number of other things that need multiple values remembered under one thing.

Another example would be if you were building a MUD script, and needed to add a monster called Giant Ant. You could simply make your mIRC (or type it in yourself) put all the values you need under one neat little section.

Notice, though, that Giant Ant is two words. Section Headers can only contain one word, as if you tried specifying a second word it would believe that to be the item.

Code

This would write your INI file as:

Code

Since we want the item to be Health, and the Section Name to be Giant Ant, we will have to replace the space in there. Therefore, you will want to use Giant_Ant, and then just use $replace(<Section Header>,$chr(32),$chr(95)) to turn the spaces into underscores. You can also reverse the process using $replace(<Section Header>,$chr(95),$chr(32)). It is also important to note that Items act the same way (they cannot have any spaces), so if you need a "multiple word" Item name, you will have to use the same method to bypass the limitations of INI.

Using INI

So, you're ready to build your first ini file. Writing and reading from INI is nearly as simple as doing the same from a regular text document.

For the purposes of this tutorial, please add the following to your Remotes in Script Editor:

Code

This will add three commands. /add_to_ini, remove_from_ini, and /read_from_ini. Note that these are not necessary to create in your own scripts using ini, it is just for the purposes of this tutorial.

First, after adding the snippet above to remotes, type this:

Code

As you can see, you should have an INI file that looks like this:

Code

Congratulations! You have taken your first step toward doing your own ini files. Now, study the single line of code in add_to_ini. The breakdown goes like this:

In this case, $1 $2 $3- replace Section, Item and Value. So when you typed

/add_to_ini Hello Im Learning

Hello was $1, Im was $2, and $3- was Learning, and it was written to the file imlearning.ini.

It is not necessary to have the -n switch there unless you are building a large ini file, I just do it out of habit.

Now let's add a little more to our ini file. Type this:

Code

Now, your INI file should look like this:

Code

Notice that in the second runthrough, we've added the item "Ive" to the section "Hello", however we have also overwritten the item "Im" in there. The value WAS "Learning", and now the value is "About to learn Reading!" Whenever you name an item that already exists, mIRC will automatically overwrite it with your new value.

When we started out with Hooray instead of Hello, it also started a new section, "Hooray," and we added two items to it.

Also of note is the system explained above about one-word section headers and one-word item names.

"HoorayOr at least I'm pretty sure I do"

The italicized Hooray became your section header, and the underlined "Or" became your item. Everything else became your value.

Reading from INI

Now that we have writing to INI files down, let's try retrieving some of that precious data we put there. For this exercise, we will be using the alias /read_from_ini.

Now in mIRC, type this:

Code

This will make mIRC echo in your active window: "Learning"

Now let's review the structure of the /read_from_ini alias:

echo -a $readini(imlearning.ini,$1,$2)

Notice that when reading from an ini, you have to use the identifier $readini().

The structure of $readini() goes:

Code

So when you typed /read_from_ini Hello Still, it filled out $readini like so:

Code

And the echo made the result "Learning" show up on your active mIRC window.

The two switches involved with $readini() are only there for special purposes, the n switch making it read as plain text (as in if you had mIRC identifiers stored in the ini but DIDN'T want them going off on reading), and p, which would make | pipes read as command separators (which is useful for storing bits of mIRC script in an ini file if you need it.)

To integrate the switches, just use $readini(example.ini,np,123,456). Notice there are FOUR areas separated by commas here, but only THREE areas separated by commas in our example above. You only need the fourth area between <file> and <section> if you're using switches.

So, try a couple more. /run imlearning.ini, and pick from the two headers, and try each item, just to see how it works.

Removing from INI

So, we have our small INI, and there are things we just don't want anymore. What do we do? Luckily, mIRC makes the DELETE IT decision easy to go through with.

We have one more command to play with in the arsenal we put into your remotes earlier: remove_from_ini.

To start, type this:

Code

Now /run imlearning.ini. You will see that all we have left is

Code

To understand how this works, let's break down our alias remove_from_ini. The single line of code is:

Code

As you can see, the file is already plugged in in the alias. We just provided the section and item.

However you may be wondering why we didn't have an item on typing /remove_from_ini Hello earlier. If you specify an item, it will just remove that item (we removed Or from Hooray). If you ONLY specify a section though, the entire section gets deleted. This is handy for removing whole sections of items that you do not need anymore (We didn't need the Hello anymore, as we now know about INI!)

Congratulations, you now know the three ini commands! Remember though, you don't need to build shell aliases to use them, this was just for demonstration. In a real script, just put in the $readini() right in where you need it, or use remini in that IF () statement to delete what you need.

When is it okay to use INI?

In a lot of cases where you are storing data in this format, people will suggest Hash Tables since there is more manipulation available to the scripter, and is a LOT quicker for many simultaneous actions involving data manipulation and retrieval. For more information on using Hash tables, there are other tutorials available in this forum.

For some cases though, INI is the more convenient solution. Since INI files only "Write it, Read it, Ditch it," it can be more simplified for newer scripters and only takes a few steps to integrate into most scripts.

However, if you need a script where you can parse through with wildcards and find things, etc, Hashes are your friend. INI files are only really meant to use to store data in a generic, text-based format, and you should only use these if you know the data you will be writing to it can be comfortably retrieved using $readini() commands instead of using a $find() command, and only if you are fine with a little less speed than using an equally sized hash table.

For the purposes of storing things such as statistics as I mentioned in the introduction, this is a great choice to start with until you learn about Hash routines, and also provides you the ability to open the INI file in most text editors for manual editing, and will be your friend for time-insensitive, structured data until you get until you get a grasp on more advanced subjects.

Note however the difference between an INI file and a regular text file is data STRUCTURE. Say if you just needed to keep a list of names, text files may be a little better for you. But if you need to keep a separate list of names for each network you are on, for example, INI will provide that for you. Whereas regular text files are like tossing papers into a filing cabinet at random, INI will offer one level of structure, kind of like placing the files in organized folders in the same cabinet.

However, in order to get even more structured, like putting folders in OTHER folders (going on our metaphor above), INI cannot provide the solution for without having redundant systems such as having INI files that just point to other INI files, and would end up becoming too confusing and convoluted to serve a useful purpose quite quickly. In cases where such multiple-tier structure is necessary it may be better to try another solution.

So, are you ready to take your first step into structured data with mIRC? Give it a shot!

Last edited by IllogicTC on Thu Apr 07, 2011 5:51 am; edited 1 time in total

I applaud your effort in writing this tutorial to benefit neophytes at MSL. This will serve a good helpful read for those who need to further gain INI know-how. ^^

As to the distinction between an INI and Hash table, it all depends on the circumstantial needs when it comes to them to determine which one is more fitting for the operation you're to embark upon. I myself sort of dislike the fact about saving a hash table, since the item and data save in it are temporary compared to INI or regular TXT.

IllogicTC wrote

In a lot of cases where you are storing data in this format, people will suggest Hash Tables [...] is a LOT quicker for many simultaneous actions involving data manipulation and retrieval.

actually, this isn't quite true ;P unlike $read() and /write, when an INI function is used, mIRC will cache the file in its memory (very likely in a collection of hash tables) making subsequent INI operations on that file, within the same call stack, quite fast. in fact, i've found their speed to be on the same order of magnitude as that of comparable hash table functions: only around twice as slow on my machine, for example.

that's why /flushini exists by the way, to update the file on disk during the call stack rather than waiting until it completes.

I've actually been known to use hash and INI in conjunction with each other, treating the INI as a storage for items that aren't being used and hashes for items that are being used. It works easier for me, but others may disagree with this method. Using /hsave -i, you can save your hash table to an INI file; while using /hload -i will load the table. You have to remember to /hmake your table before you /hload it though.