Userini.vdm

Subroutine macro for reading from and writing data to the user.ini file
Written by Scott Lambert     May, 2010

For Vedit 6.01 and above.

Installation Notes:

Put the userini.vdm file in your vedit\user-mac folder. The User.ini file will be created
in the vedit\user-mac folder during execution, if it does not exist.

Files included: userini.vdm, userini.txt

General Description:

Until now, there has been no way for a macro to easily preserve data safely &
reliably between executions of the macro. Information in registers can get altered by other
macros or by the enduser, or lost completely if the enduser exits Vedit.

Userini.vdm is a subroutine macro designed to be called from other macros. It is not a stand
alone macro. Userini.vdm is used to read or write data to or from the user.ini file (from
either a text register or a numeric register). 

Each macro gets its own private section in the user.ini file. The is also a global section for
sharing data between macros. Macro data is safely preserved in the user.ini file, until the
calling macro needs it again.

Type of data that might be saved in the user.ini file: last filename opened, last filespec
specified, last file position, block_begin & block_end file postions, various macro
internal flags, etc.

Details of input & output registers for userini.vdm:

n-reg 10 : 

Used to indicate whether the calling macro is going to read the user.ini file for
data or write data to the user.ini file.

0=read from user.ini	1=write to user.ini

n-reg 12 :

Used to indicate whether to use the calling macro's private section or the shared global
section.

0=use calling macro's private section    
1=use the shared global section (called [allmacros] in the user.ini file)

t-reg 10 :

This is used to specify the variable name to read from or write to. Variable names can be
quite long. Variable names must NOT contain an = sign, and should not contain spaces.

Important: To specify a variable that will hold numeric data from a nureric register, you must
start the variable name with a #

If a variable name does not exist, it is created during a write operation. During a read
operation it returns with return_value set to 1

Examples of some possible variable names:

LastFilenameUsed
LastFileSpecSelected
treg50
#nreg35
#lastfileposition
#blockbeginpos
#blockendpos

t-reg 12:

Used to specify the calling macro's filename without the .vdm extension. By using the calling
macros filename, it is easier to keep track of which section is being used by which macro, if
one is viewing the user.ini file in Vedit.

Important: The name allmacros is reserved for the global section, if you have a macro
called this, rename it to something else before using with userini.vdm.

T-reg 12 is ignored if n-reg 12 is set to 1 (use the global section)

If a macro's section does not exist, it is created during a write operation. During a read
operation it returns with return_value set to 2

t-reg 11   and   n-reg 11:

T-reg 11 and n-reg 11 are the two registers that hold the data to be transferred to or from
the user.ini file.

Important: text data in t-reg 11 must be on one line only. However line can be as long as
needed (within reason). To save multi-line data, use the Vedit macro command reg_save()
and then store the filename specified in the reg_save() command in the user.ini file.

Note: when reading a numeric variable, it is returned in both registers, hence the calling
macro can get it from either register depending on how it wants the data (in numeric format 
or text format)

Summary of return_value codes:
 
0=ok - no errors
1=variable name not specified or not found for read in user.ini
2=calling macro not specified or not found for read in user.ini

Programming Examples:

Reading text data from user.ini (macro's local section):

#10=0  // specify a read request
#12=0  // read from calling macro's private section
reg_set(12,"gadget") // specify calling macro's name
reg_set(10,"LastFileName") // specify the variable name 
call_file(101,"userini.vdm") // execute userini.vdm (use whatever t-reg you want)
if(return_value==0) {
// if no errors do:
reg_set(25,@11) // copy retrieved data to another t-reg in case of another call to userini.vdm
} else {
// error handling code goes here
}


Reading numeric data from user.ini (macro's local section):

#10=0  // specify a read request
#12=0  // read from calling macro's private section
reg_set(12,"mymacro") // specify calling macro's name
reg_set(10,"#LastFilepos") // specify the variable name - note the # 
call_file(101,"userini.vdm") // execute userini.vdm (use whatever t-reg you want)
if(return_value==0) {
// if no errors do:
#25=#11 // copy retrieved data to another n-reg in case of another call to userini.vdm
// or the following instead if calling macro wants it as text:
// reg_set(25,@11) // copy retrieved data to another t-reg 
} else {
// error handling code goes here
}

Reading text data from user.ini (shared global section):

#10=0  // specify a read request
#12=1  // read from from shared global section
// note t-reg 12 is ignored in this case
reg_set(10,"mydocslocation") // specify the variable name 
call_file(101,"userini.vdm") // execute userini.vdm (use whatever t-reg you want)
if(return_value==0) {
// if no errors do:
reg_set(25,@11) // copy retrieved data to another t-reg in case of another call to userini.vdm
} else {
// error handling code goes here
}

Reading numeric data from user.ini (shared global section):

#10=0  // specify a read request
#12=1  // read from shared global section
// note t-reg 12 is ignored in this case
reg_set(10,"#fileopencount") // specify the variable name - note the # 
call_file(101,"userini.vdm") // execute userini.vdm (use whatever t-reg you want)
if(return_value==0) {
// if no errors do:
#25=#11 // copy retrieved data to another n-reg in case of another call to userini.vdm
// or the following instead if calling macro wants it as text:
// reg_set(25,@11) // copy retrieved data to another t-reg 
} else {
// error handling code goes here
}

Writing text data to user.ini (macro's local section):

#10=1  // specify a write request
#12=0  // write to calling macro's private section
reg_set(12,"gadget") // specify calling macro's name
reg_set(10,"LastFileName") // specify the variable name 
reg_set(11,"index.htm") // specify the one line variable data to store   
call_file(101,"userini.vdm") // execute userini.vdm (use whatever t-reg you want)
if(return_value>0) {
// error handling code goes here
}

Writing numeric data to user.ini (macro's local section):

#10=1  // specify a write request
#12=0  // write to calling macro's private section
reg_set(12,"mymacro") // specify calling macro's name
reg_set(10,"#LastFilePos") // specify the variable name - note the # 
#11=144 // specify the numeric data   
call_file(101,"userini.vdm") // execute userini.vdm (use whatever t-reg you want)
if(return_value>0) {
// error handling code goes here
}

Writing text data to user.ini (shared global section):

#10=1  // specify a write request
#12=1  // write to shared global section
// t-reg 12 is ignored in this case
reg_set(10,"mydocslocation") // specify the variable name 
reg_set(11,"c:\documents and settings\john smith\my documents") // specify the one line variable data to store   
call_file(101,"userini.vdm") // execute userini.vdm (use whatever t-reg you want)
if(return_value>0) {
// error handling code goes here
}

Writing numeric data to user.ini (shared global section):

#10=1  // specify a write request
#12=1  // write to shared global section
// t-reg 12 is ignored in this case
reg_set(10,"#filecount") // specify the variable name - note the # 
#11=23 // specify the numeric data to store   
call_file(101,"userini.vdm") // execute userini.vdm (use whatever t-reg you want)
if(return_value>0) {
// error handling code goes here
}

End of programming examples.