Using the Scripting Feature in BarScan
1. Introduction – this is an overview of the scripting feature in Bar|Scan.
2. Feature – One of Bar|Scan’s features is the ability to control startup settings and actions in a BarScan initialization (.bini) file. The .bini file can literally login, change some of the system’s default folder, perform some actions such as print a report or do an import, issue a message to the user then either turn over control to them as normal or automatically logout. It can also force a logout after a fixed time period of inactivity.
3. Overview
a. The Bar|Scan initialization file (.bini) can be used in three major scenarios.
i. All users will execute the instructions of a common .bini file
ii. Individual .bini files can be specified to perform specific actions (such as being associated with a desktop shortcut)
iii. An unattended execution of specific BarScan actions can be setup on a times basis, much like a Windows batch file.
4. How to Execute Bini file
a. Name the bini file BSYSPATH.BINI and put it into the same folder as BARSCANW.EXE. The default filename for the scripting file is BSYSPATH.BINI. BarScan will look for this filename in the same folder as the application file. If present, it will load it and run it.
b. Run BarScanw.exe from a command line and set the bini files as the first parameter. BarScan can take a filename as a line item parameter. Line item parameters can be specified in the COMMAND box (CMD for Windows) or in shortcuts. These can be any legal filename and reside anywhere on your computer or network as long as it is accessible.
c. Use the Windows Task Scheduler. See “How to use the Task Scheduler” below. In Task Scheduler there is a line to enter your program, so you would enter
1. c:BarscanwBarscanw.exe
ii. For your argument you would enter the fully qualified path+filename of the .bini file, such as
1. c:BarScanwSampleBiniFile.bini
d. Don’t use the path mentioned here, but use the actual path to your actual .bini file. For more information see “How to Use Task Scheduler” below.
5. Bini File Contents
a. The bini file is structured similar to many initialization files. It is broken up into major sections, with line item parameters or instructions within each section. There are three major sections. Section titles are specified by a section name enclosed in square brackets. No spaces are allowed and they must be uppercase.
i. [LOGIN] This section is where you specify the user initials and password.
ii. [PATHS] This section is where you override system paths.
iii. [ACTIONS] This section is where you specify any startup processes that you want performed before the user gets control.
b. When consulting the instructions for the contents of the file below, remember the following:
i. Items enclosed in angle brackets (<>) are a required entry. The angle brackets themselves are not to be entered. For example, “>LABEL <cLabel>” means that you must enter a label name after the >LABEL command, e.g. “>LABEL THEEND”.
ii. Items enclosed in square brackets are optional.
iii. Items separated by a vertical bar are alternatives. For example: >ENABLED [TRUE|FALSE]
iv. Most commands have parameters with a parameter name followed by an equal sign (=) followed by the parameter value. For example: “>PACK ONERROR=ENDLABEL”. All entries that can have embedded spaces (such as a filename) need to be enclosed in the double quote mark, e.g. “This is a test.bini”.
v. All command line parameters must be separated by at least one space. Individual parameters with their names and values can be on their own line in the script.
vi. IMPORTANT! All filenames contained within the bini file must be fully qualified, i.e., they must be the full path starting with the drive (or share) ending with the file extension.
vii. IMPORTANT! We recommend adding a Password to the User Table specifically for your scripting and used only for scripting. All passwords contained in the bini file are in clear text and are specified in the User table within BarScan. If a user login changes its password then it must also be changed in the bini file if that login is being used in the bini file. Because the password is in clear text it is important that the bini file login have its privileges restricted within BarScan as well as made secure (such as by privileges or location) within Windows.
6. [LOGIN]
a. The [LOGIN] section specifies the information needed to login to BarScan. There are two parameters available. The parameter name is specified then followed by an equal to (=) sign, then the value. Do not include the angle brackets (<>).
i. ID=<User Initials>
ii. PASSWORD=<Password>
b. For example:
i. [LOGIN]
ii. ID=MAS
iii. PASSWORD=MASTER
7. [PATHS]
a. The [PATHS] section is used to override the default paths used by BarScan upon startup and operation. For example, the SYSHOME path name redirects ALL paths so that BarScan will look for all of its system folders below the specified folder. This is normally used to place the BarScan executable program on a remote workstation but have it look at a server for its system files. This increases remote startup speed. There are several path names available. First specify the path name, then an equal sign, then the new path.
i. SYSHOME=<newpath>
ii. SYSUSER=<newpath>
iii. SYSDBF=<newpath>
iv. READER=<newpath>
v. TEMPLATE=<newpath>
vi. TEMP=<newpath>
vii. REPORTS=<newpath>
viii. USER=<newpath>
b. With the exception of SYSHOME, the path name is the same as the BarScan system folder name that is being redirected. Note that SYSHOME needs to go first if it is specified or else previously specified paths will be reset.
8. [ACTIONS]
a. The [ACTIONS] section specifies a set of operations, a script, to be performed upon startup. There are a number of commands that can be used, so startup operations can be quite extensive. This is especially useful if you want to have all users start up with a common set of operations. For example, you can specify a startup message that all users will see every time they login. Commands also have parameters to control their operation. See the explanation of each command for how to use it and its parameters.
b. The following commands are available. Please note that all commands start with the left angle bracket (greater than sign), this is part of the text of the command and serves to differentiate it from the parameter lines. In alphabetical order they are:
i. >CHECKPATHS
ii. >ENABLED
iii. >EXPORT
iv. >GOTO
v. >IMPORT
vi. >INACTIVITYSHUTDOWN
vii. >LABEL
viii. >MOVE
ix. >MSG
x. >OPENCOMPANY
xi. >PACK
xii. >REINDEX
xiii. >REPORT
xiv. >RESTRUCTURE
xv. >SHUTDOWN
xvi. >TESTTHROUGHPUT
xvii. >VALIDATE
9. >CHECKPATHS
a. Parameters: None.
b. Description: This is a global setting. Its existence anywhere within the [ACTIONS] section enables it. Upon startup, BarScan enters the contents of the environmental PATH into the startup log. This command parses the PATH contents into its individual folders, sorts them, checks for duplicates and whether or not the paths are visible from the application.
c. Example:
>CHECKPATHS
Here are some sample results in log file.
2020-11-20T09:15:15[+8=UTC] (MAS){5WX0JT2U0} C:WINDOWS
2020-11-20T09:15:15[+8=UTC] (MAS){5WX0JT2U0} Dup C:WINDOWS
2020-11-20T09:15:15[+8=UTC] (MAS){5WX0JT2U0} C:WINDOWSSYSTEM32
2020-11-20T09:15:15[+8=UTC] (MAS){5WX0JT2U0} Dup C:WINDOWSSYSTEM32
2020-11-20T09:15:15[+8=UTC] (MAS){5WX0JT2U0} Dup C:WINDOWSSYSTEM32
2020-11-20T09:15:16[+8=UTC] (MAS){5WX0JT2U0} Not Found C:WINDOWSSYSTEM32OPENSSH
2020-11-20T09:15:16[+8=UTC] (MAS){5WX0JT2U0} Dup, Not Found C:WINDOWSSYSTEM32OPENSSH
10. >ENABLED [TRUE|FALSE|YES|NO]
a. Parameters:
i. [YES|TRUE|NO|FALSE] – Text. Include one of these instructions to determine whether the script can be run. If not specified, the default is YES. Optional.
b. Description: This command, anywhere in the list of commands, will specify whether or not the entire [ACTION] section is ignored. If no parameter is specified, the default is ENABLED TRUE. If enabled is true, commands in the [ACTIONS] section are executed as specified. If enabled is false, no commands are executed, the entire section is ignored. Commands are executed starting at the first command. This is a single line command.
c. Example:
i. >ENABLED TRUE
ii. >ENABLED FALSE
11. >GOTO <LabelName >
a. Parameters:
i. <LabelName> The name of label that will be the next line executed in the bini script. This line must be identified by a LABEL command with the corresponding <LabelName>. Embedded spaces are not allowed. Do not enclose in quotes. Required.
b. Description: This command is paired with the LABEL command. A label name is specified and control moves to the command immediately following the label. This is a single line command.
c. Example:
i. >GOTO ALLDONE
1. …<MISCELLANEOUS OPERATIONS-These are skipped because of the GOTO>
ii. >LABEL ALLDONE
iii. >MSG “All Operations have been completed.”
12. >EXPORT – See >IMPORT.
13. >IMPORT <Name=<cFormattedIxName>> [ONERROR=<LabelName>]
a. Parameters:
i. Name=<cFormattedIxName>. The name of the formatted import/export item. Required.
ii. ONERROR=<LabelName>. If an error occurs during operation, the error will be logged to the log file and then control will move to the Label statement with this LabelName. Optional.
b. Description: This command will perform the formatted import or export specified.
c. Example: Assume you have a formatted import entitled “MY SPECIAL IMPORT FROM MY HR SYSTEM”
i. >IMPORT NAME=”MY SPECIAL IMPORT FROM MY HR SYSTEM” ONERROR=BADIMPORT
ii. >MSG “The import was successful.”
iii. >GOTO Alldoneiv. >LABEL BADIMPORT
v. >MSG “The import didn’t work”
vi. >LABEL ALLDONE
14. > INACTIVITYSHUTDOWN Minutes=<NumberOfMinutes>
a. Parameters
i. Minutes = <NumberOfMinutes>. The number of minutes that BarScan waits before shutting itself down due to inactivity. Inactivity is defined as no mouse movement over the defined number of minutes. Required.
b. Description: This command sets the inactivity timeout. In other words, if BarScan has no user activity for the specified number of minutes, BarScan will attempt to logoff and shutdown. There are some situations where this may not be possible. Inactivity is defined as no mouse movement.
c. Example:
i. >MSG “BarScan will close after 30 minutes of inactivity.”
ii. >INACTIVITYTIMEOUT MINUTES=30
iii. >LABEL ALLDONE
15. >LABEL <LabelName>
a. Parameters:
i. <LabelName>. The name associated with this location in the script.
b. Description: This command gives a name to a location in your command list so that other commands can jump to this location immediately, such as by using the GOTO command or an ONERROR parameter.
c. Example: In the following script the MSG command will be skipped.
i. >GOTO ALLDONE
ii. >MSG THIS LINE IS SKIPPED
iii. >LABEL ALLDONE
16. >MOVE [PARTIAL=[YES|TRUE|FALSE|NO] [ONERROR=<LabelName>]
a. Parameters:
i. PARTIAL=[YES|TRUE|FALSE|NO]. Forces movement of assets from the Transaction table to the Asset table to occur on an individual basis. Generally, this is not recommended since it is substantially slower moving assets. All completely valid assets will be moved even if others in the same move fail. The default is that if any Transactions fail to move, then all Transactions in the same batch will fail to move.
ii. ONERROR=<LabelName>. If an error occurs during operation, the error will be logged to the log file and then control will move to the Label statement with this LabelName. Optional.
b. Description: This command MOVES assets from the Transaction table to the Asset table. The default behavior of the MOVE command is that ALL eligible assets are moved. If there are any errors then none of them are moved (i.e., this is the same as progressive commit being turned off). If you use the PARTIAL command, you can activate partial moves (i.e., this is the same as progressive commit being turned on). In this case, each transaction is moved independent of any errors in other transactions.
c. Example: Assume you have a company called “COMPANY.DBC”. Note: if the company or path has spaces then you should enclose the path within quotes, e.g. “D:Sample CompanySample Company Name.dbc”).
i. >OPENCOMPANY DBC=C:BARSCANWCOMPANYCOMPANY.DBC ONERROR=BADOPEN
ii. >MSG “The company opened successfully.”
iii. >MOVE ONERROR=BADMOVE PARTIAL=TRUE
iv. >GOTO Alldone
v. >LABEL BADOPEN
vi. >MSG “The company open didn’t work”
vii. >GOTO ALLDONE
viii. >LABEL BADMOVE
ix. >MSG “The MOVE didn’t work”
x. >LABEL ALLDONE
17. >MSG Msg=<MsgText> [Destination=ALL|LOG|SCREEN]
a. Parameters:
i. Msg=<MsgText>. The text of the message to issue. Required. See note below.
ii. Destination=ALL|LOG|SCREEN. The destination of the message.
1. Messages sent to the SCREEN produce a modal dialog for the user. The message is displayed in the dialog and the user must press the OK button before the script can continue. The content of the message can be anything that will fit on a single line of text. It is displayed ‘as is’. Optional. If not specified the default is DESTINATION=ALL.
iii. Note: If no parameters names are listed the entire line following the >MSG command is taken as the text of the message.
b. Description: Issue a message to the User, the log file, or both.
c. Example:
i. >MSG This displays a dialog box AND sends this text to the log file.
ii. >MSG Msg=”This displays a dialog box only.” Destination=SCREEN
iii. >MSG MSG=”Just a LOG message” Destination=LOG
18. >OPENCOMPANY Dbc=<DbcFilename> [ALONE] [SCANUP] [ONERROR=<LabelName>]
a. Parameters:
i. DBC=<DbcFilename>. This is the fully qualified DBC filename of the company. e.g. C:BARSCANWDEMOCODEMOCO.DBC.
ii. ALONE – All previously opened companies are closed. As the script executes, multiple >OPENCOMPANY commands may be encountered. Unless the ALONE option is specified, all previously opened companies remain open.
iii. SCANUP – Starting with the folder of the company to be opened, look upwards in the folder tree looking for standard BarScan folders and use them rather than the default folders. The first one encountered will be the one used. These are: “SYSDBF”, “SYSUSER”, “READER”, “USER”, “TEMPLATE”, “REPORTS”, “COMPANY”, “DEMOCO”, “IMAGES”, “SYNC”.
iv. ONERROR=<LabelName>. If an error occurs during operation, the error will be logged to the log file and then control will move to the Label statement with this LabelName. Optional.
b. Description: This command opens and sets the current company. Any command that logically follow this one will be working on this company.
c. Example: Assume you have a company called “COMPANY.DBC”.
i. >OPENCOMPANY DBC=C:BARSCANWCOMPANYCOMPANY.DBC ONERROR=BADOPEN
ii. >MSG “The company opened successfully.”
iii. >GOTO Alldoneiv. >LABEL BADOPEN
v. >MSG “The company open didn’t work”
vi. >LABEL ALLDONE
19. >PACK [DBC=<cDbcFilename>] [ONERROR=<LabelName>] – See RESTRUCTURE.
20. >REINDEX [DBC=<cDbcFilename>] [ONERROR=<LabelName>] – See RESTRUCTURE.
21. >REPORT Name=<ReportName> [MARKASPRINTED] [ONERROR=cLabelName]
a. Parameters:
i. Name=<ReportName >. The name of the report. Required.
ii. ONERROR=<LabelName>. If an error occurs during operation, the error will be logged to the log file and then control will move to the Label statement with this LabelName. Optional.
iii. MARKASPRINTED. Mark any transactions in the report as printed.
b. Description: This command runs the specified report. Please note that the report must be setup ahead of time to behave as desired. For example, if this startup is part of an automated process, be sure that the report will not require any human interaction such as a print preview or prompted filter.
c. Example: Assume you have a report called “MY REPORT”. If you are running interactively the following would be ok.
i. >REPORT NAME=”MY REPORT” ONERROR=BADOPEN
ii. >MSG “The report printed successfully.”
iii. >GOTO Alldoneiv. >LABEL BADOPENv. >MSG “The report had a problem”
vi. >LABEL ALLDONE
22. >RESTRUCTURE [DBC=<cDbcFilename>] [ONERROR=<LabelName>]
a. Parameters:
i. ONERROR=<LabelName>. If an error occurs during operation, the error will be logged to the log file and then control will move to the Label statement with this LabelName. Optional.
ii. DBC=<DbcFilename>. Specifies the DBC to open and switch to. This makes the selected DBC the current company for any following commands unless there is an error. If an error occurs the current company will be unknown. It is recommended that the separate OPENCOMPANY command be used to select the desired company.
b. Description: This command PACKS/REINDEXES/RESTRUCTURES all of the company tables. IMPORTANT: The Restructure is performed as it is when doing a Restructure from the Table Integrity screen when Verification of Tables is NOT checked. When Restructuring, it is always possible that something will come up that requires human intervention. There are several operations that require human intervention, such as when a table needs to be created. If this happens, the restructure operation will pause waiting for human interaction.
c. Example:
i. >REINDEX DBC=C:BARSCANWCOMPANYCOMPANY.DBC ONERROR=BADOP
ii. >MSG “The company was reindexed successfully”
iii. >RESTRUCTURE DBC=C:BARSCANWCOMPANYCOMPANY.DBC ONERROR=BADOP
iv. >MSG “The company was restructured successfully.”
v. >PACK DBC=C:BARSCANWCOMPANYCOMPANY.DBC ONERROR=BADOP
vi. >MSG “The company was packed successfully.”
vii. >GOTO Alldoneviii. >LABEL BADOP
ix. >MSG “The PACK/REINDEX/RESTRUCTURE didn’t work”
x. >LABEL ALLDONE
23. >SHUTDOWN
a. Parameters: None.
b. Description: This command attempts to perform an immediate logoff and shutdown. It must be understood that there are some circumstances where it will not be able to do so, for example, during a currently running operation.
c. Example, assume that an automated process is desired to be run every night. Windows can start BarScan at the desired time. It might run the following startup script. This script will open the target company, perform an import, print a report on what was imported, then exit.
i. >OPEN COMPANY DBC=”C:BARSCANWCOMPANYCOMPANY.DBC” ONERROR=HADAPROBLEM
ii. >IMPORT NAME=”MAINFRAME IMPORT” ONERROR=HADAPROBLEM
iii. >REPORT NAME=”LIST OF ITEMS IMPORTED OVERNIGHT” ONERROR=HADAPROBLEM
iv. >GOTO ALLDONE
v. >LABEL HADAPROBLEM
vi. >MSG Msg=”WARNING. OVERNIGHT PROCESS HAD A PROBLEM.”
vii. >LABEL ALLDONE
24. >TESTTHROUGHPUT [REPS=nReps] [USERCOMMENT=cComment] [INTERVAL=nInterval] [STARTTIME=tStart] [VERIFYSTART=Y|N]
a. Parameters:
i. REPS. Numeric. The number of consecutive times to run the test.
ii. USERCOMMENT. Text. Include this comment in test log.
iii. INTERVAL. Numeric. Minutes. Amount of time to wait between consecutive tests when REPS>1.
iv. STARTTIME-Time. Time format conforms to local time as specified by Windows, e.g., 11/20/20 11:52:12 AM for USA.
v. VERIFYSTART. Logical. NOT RECOMMENDED. Forces an interactive dialog with the user to verify running the throughput test.
b. Description: Perform a throughput test and put the results into the system Log folder. Optionally, specify some of the parameters of the test. Note that this test can run several minutes at the least.
25. >VALIDATE [ONERROR=<LabelName>]
a. Parameters:
i. ONERROR=<LabelName>. If an error occurs during operation, the error will be logged to the log file and then control will move to the Label statement with this LabelName. Optional.
b. Description: This command validates assets in the Transaction table to prepare them for movement to the Asset table.
c. Example: Assume you have a company called “COMPANY.DBC”
i. >OPENCOMPANY DBC=”C:BARSCANWCOMPANYCOMPANY.DBC” ONERROR=BADOPEN
ii. >MSG “The company opened successfully.”
iii. >VALIDATE ONERROR=BADVALIDATE
iv. >MOVE ONERROR=BADMOVE
v. >GOTO Alldone
vi. >LABEL BADOPEN
vii. >MSG “The company open didn’t work”
viii. >GOTO ALLDONE
ix. >LABEL BADMOVE
x. >MSG “The MOVE didn’t work”
xi. >LABEL BADVALIDATE
xii. >MSG “The VALIDATE didn’t work”
xiii. >LABEL ALLDONE
26. Samples
a. The following are some sample scripts. Please note that some of the parameter values may continue on to the next line, but in reality, they must all be on a single line.
b. Sample #1. This script will issue a message to all users logging in.
i. >MSG MESSAGE TO ALL USERS. DON’T FORGET TO LOGOUT BEFORE GOING HOME.
c. Sample #2. This script will issue a message to the user starting BarScan, force them to use a specific company, then set an inactivity timeout just in case they don’t logout at night.
i. >OPEN COMPANY DBC=C:BARSCANWCOMPANYCOMPANY.DBC ONERROR=HADAPROBLEM
ii. >INACTIVITYTIMEOUT MINUTES=30
iii. >MSG Until further notice, all users must use the COMPANY company.
iv. >LABEL ALLDONE
d. Sample #3. This script will LOGIN, open the target company, perform an import, print a report on what was imported, then exit. If there was a problem it will display a dialog box and sit there until someone notices it.
i. [LOGIN]
ii. ID=MAS
iii. PASSWORD=MASTER
iv. [ACTIONS]
v. >OPEN COMPANY DBC=C:BARSCANWCOMPANYCOMPANY.DBC ONERROR=HADAPROBLEM
vi. >IMPORT NAME=MAINFRAME IMPORT ONERROR=HADAPROBLEM
vii. >REPORT NAME=LIST OF ITEMS IMPORTED OVERNIGHT ONERROR=HADAPROBLEM
viii. >GOTO ALLDONE
ix. >LABEL HADAPROBLEM
x. >MSG WARNING. OVERNIGHT PROCESS HAD A PROBLEM.
xi. >LABEL ALLDONE
e. Sample #4. This script will LOGIN, open a company, then restructure it, pack and reindex, then logout.
i. [LOGIN]
ii. ID=MAS
iii. PASSWORD=MASTER
iv. [ACTIONS]v. >OPEN COMPANY DBC=C:BARSCANWCOMPANYCOMPANY.DBC ONERROR=HADAPROBLEM
vi. >RESTRUCTURE
vii. >PACK
viii. >REINDEX
ix. >GOTO ALLDONE
x. >LABEL HADAPROBLEM
xi. >MSG WARNING. UNABLE TO OPEN COMPANY FOR PACK, ETC.
xii. >LABEL ALLDONE
xiii. >SHUTDOWN
27. How to Use the Task Scheduler. Bar|Scan Scripting is designed to work with the Windows Task scheduler to handle the timing of the startup. Note that there are two ways to use the task scheduler.
1. Specify the Bar|Scan program without putting in any arguments. i.e., “C:BarScanBarScanw.exe” in the “Program/script” field, and nothing in the “Add arguments(optional)” field. In this case the barscanw.exe program automatically looks for the file “bsyspath.bini” in its same folder. If found, it will execute its contents. However, this is probably not the best way to go if you want to do a nightly operation, as it is activated for ALL logins.
2. Specify the BarScan program with an argument. i.e., “C:BarScanBarScanw.exe” in the “Program/script” field, and the full path to the .bini file in the “Add arguments(optional)” field. For example, the Vista Task schedule panel specifying the program and arguments might look like this:
In this case the full path to the .bini file is specified, “c:barscanbsyspath.bini”, in the BarScan folder. Other supported versions of Windows can do the same thing, but their entry fields vary a bit. Note that it is important that the path for ‘Start in’ be specified and be the same path specified (without the filename) under ‘Program/script’. You can also have multiple .bini files, all with different names. For example:
a. MidnightOrgImport.bini
b. Bsyspath.bini
c. NightlyReport.bini
3. Each of these would have to have its own startup scheduled in windows, and each of these files would perform their own expected actions. For example, here is a script that runs a report. If the Windows Task scheduler ‘argument’ points to this file, then the report will be run whenever the scheduler says it should.
a. [LOGIN]
b. ID=MAS
c. PASSWORD=MASTER
d. [ACTIONS]
e. >Enabled=TRUE
f. >OPENCOMPANY DBC=C:BARSCANWDEMOCODEMOCO.DBC
g. >REPORT NAME=SAMPLE ASSET DEPRECIATION SPLIT BETWEEN ORGANIZATIONS
h. >GOTO ALLDONE
i. >LABEL ALLDONE
j. >SHUTDOWN