Running FlashBASIC from Visual Basic

When using a FlashBASIC module with the D3 Visual Basic class, D3clsRuleModule, some differences and constraints are applied due to the differences between the Windows and D3 environments.

The topics listed below outline these differences and provide notes about writing FlashBASIC code to be called from Visual Basic.

Passing Visual Basic Arguments

Passing D3 Visual Basic Objects

Accessing VME Resources from a Rule Module

Passing Visual Basic Arguments

As detailed in the D3 Visual Basic documentation, only VARIANT variables can be passed to the FlashBASIC subroutine, and any number of them may be passed. Arguments are passed by references, which means they can be modified on return. There are some exceptions listed in the table below.

NOTE	Only ANSI strings can be passed to a FlashBASIC routine. Arrays are not supported.

VB Type	FlashBASIC Argument	See Notes
Byte	String with one character
Short	Integer	1, 2
Long	Integer	1, 2
Real	Floating point in double precision
Bool	Integer	2, 3
BSTR	String	4, 5
Empty	String with 0 characters
Null	String with 0 characters
All Others	String with 0 characters	6

Notes

If any arithmetic operation is performed, the number is returned as a floating point number (in double precision) on which the usual D3 arithmetic precision factor has been applied. Note the argument is then coerced into a Real (see Note 2).
To use floating point numbers, which improves performance significantly, use the (f option when compiling a FlashBASIC module.
Any non-null number is treated by FlashBASIC as TRUE. If a TRUE value is returned, the numerical value of the result is 1, not the Visual Basic True value which is -1. Note the argument may be coerced into a Real.
Only ANSI strings can be passed to a Flash subroutine. Since Visual Basic uses OLE characters (UNICODE), there may be data loss if the string cannot be converted to ANSI.
If any arithmetic operation is performed on the string, or if FlashBASIC stores a number in the string, the argument is coerced on return into a Real.
By default, all unsupported VARIANT types are received by the Flash subroutine as a null string. On return, the argument is coerced into a Visual Basic string.

Passing D3 Visual Basic Objects

The following D3 Visual Basic object handles (using the brHandle method available to each D3 Visual Basic object) can be passed to a FlashBASIC subroutine:

D3 Object	FlashBASIC Argument	Notes
Dynamic Array	String	Only ANSI string can be passed.
File	File variable	The file must be opened in Visual Basic. The FlashBASIC subroutine can read and write the file, but must not close the file. File variables are not modified on return. In other words, it is not possible to pass an empty file object and have a FlashBASIC module open a file. NOTE—The module can open/close files within the module. However, the Visual Basic application will not have access to those files unless it also opens the file.
Select List	String	The Flash subroutine should not modify the input string.
All Others	Generate a Run Time Exception.

Accessing VME Resources from a Rule Module

There are several important rules to observe when running a FlashBASIC module, either as a Visual Basic rule module object from a subroutine called by such an object, or from a trigger.

User-ID

If the trigger or rule module is invoked from a VB application, the user is logged on to the VME with a user-ID equal to the Windows user name, appended with an underscore.
If the trigger or rule module is invoked by a process running in a VME, the user-ID is constructed by concatenating the D3 user (not the Windows user) with a $, followed by the PIB associated with the user (not the trigger’s PIB) and another $ (for example, dm$1$). This user-ID cannot be used outside of the module context. The password is generated automatically.
The USERS item-ID can be modified, but must not have any logto command in the user's macro field.

Database

The user is logged on to the default database (normally FSI:DM).

All FlashBASIC statements are supported, with the following notes:

data/ execute	The execute is run on a randomly selected PIB. There is no guarantee that two invocations of the same rule module doing an execute will get the same PIB. Therefore, it is recommended that you not have one rule module doing an execute select and another rule module doing another execute trying to use the select list. Make sure both execute statements are in the same rule module - select from one module and use the list from another module.
oconv()	The MR/ML and MC mask correlatives are supported natively by FlashBASIC and do not require VME access. All other oconv versions do require VME access.
iconv()	All other iconv versions require VME access.
system()	The following system() functions are supported natively by Flash and do not require VME access: 0, 12, 19, 41, 42, 43 All other values are executed by logging on to the VME.
time()	The returned time is the client’s time.
date()	The returned date is the client’s date.
timedate()	The returned time date is the client’s time date. ANSI syntax is used for the abbreviated month.
sleep()	Only the sleep for form is supported. In other words, the argument must be a number of seconds, not a wake-up time. The sleep until form logs on to the VME.
sort()	Only simple (ascending and descending) sorts are allowed. sort() functions of greater complexity require VME access and may result in decreased performance.
@()	The escape sequences are returned for an ANSI emulation. The terminal type cannot be modified by an execute.

Printing from a Rule Module

FlashBASIC runtime supports printing from a rule module called from Visual Basic or the D3 File Manager. The print and printer FlashBASIC statements direct output to one or more Windows printers after issuing the printer on statement.

To enable this feature, the variable below must be set in the MS-DOS environment:

D3FLASHPRT=PrinterName{,{boj}{,eoj}};__,__,__;...

Parameter(s)

PrinterName	Specifies the name and location of a printer (for example, \\Server\Printer).
boj	(Optional) Beginning of job page eject. Specifies whether or not an empty page is ejected before a print job. Possible values are:
	S	Suppresses the initial page eject.
	null	Ejects one page prior to each job.
eoj	(Optional) End of job page eject. Specifies number of empty pages from 0-8 the printer ejects after each job. The default is 0.

Example(s)

name	The boj and eoj are not specified, resulting in a single page eject prior to the job. No page ejects occur after the job.
name,S	The boj specification is S (suppress) and the eoj is not specified. The result is no page ejects prior to or after the job.
name,,5	The boj specification is null and the eoj specification is 5. The result is a single page eject prior to the job and 5 page ejects after.
name,S,7	The boj specification is S (suppress) and the eoj specification is 5. The result is no page eject prior to the job and 7 page ejects after.

The printer device is specified with the print on statement, where the device number, starting at 0, is the device listed in the D3FLASHPRT MS-DOS variable. By default, the first printer(0) is used.