Programmer Guide/Macro Library/BUTIL



BUTIL

This macro implements a package of general purpose functions.



COPYFILE

Copy the source file to the target.

Usage:

BUTIL COPYFILE source ; target

Parameters:

source

The file name (and path) of the file being copied.

target

The name of the target file or directory to copy to.

Result:

0 for success or non-zero errorcode.



DELETEFILE

Delete the file filename.

Usage:

BUTIL DELETEFILE filename

Parameters:

filename

The name of the file to be deleted (no wildcards are allowed).

Result:

0 for success or non-zero errorcode



DIRECTORY

Selects a new working working directory (if dir is supplied) and returns the full path of the working directory.

Usage:

BUTIL DIRECTORY [ dir ]

Parameters:

dir

The new working directory.

Result:

The full path of the current or selected working directory.



DIRECTORYDIALOG

Display a directory selection dialog and return the selected directory path. If subdirs is set to Yes (1) a check-box for sub-directory processing is displayed.

Usage:

BUTIL DIRECTORYDIALOG caption [; path ; restore ; subdirs ; subflag ]

Parameters:

caption

The dialog window caption.

path

The default directory or * for the current working directory.

restore

Restore the current working directory (No|Yes). If No, the current working directory is set to the selected directory. The default is No.

subdirs

Show the sub-directory checkbox (No|Yes). The default is No.

subflag

The state to initialize the sub-directory checkbox to (Off|On). The default is Off.

Result:

An empty string (if the dialog was cancelled), the selected directory (if subdirs=No) or the selected directory and the subflag ('directory;subflag'), if subdirs=Yes. The value of subflag equals 0 or 1.



FILEDIALOG

A dialog to open (mode = OPEN|LOAD) or create (mode = NEW|SAVE) a file is displayed. All 'type=text' assignments are added to the filetype combo-box. The type "*=all files" is always appended to the type list. If the function returns a file path, all checks for opening and/or creating the file are performed, but the file is not opened or created! If a file is opened or loaded (type = OPEN | LOAD) only existing files can be used. It must be possible to open the selected file for read access. If a file is created (type = NEW|SAVE) it is tested to see if it exists already (an overwrite dialog is displayed) and if it is possible to open the file for write access.

Usage:

BUTIL FILEDIALOG mode [; caption ; defFile ; type=typetext ; type=...]

Parameters:

mode

The file dialog mode OPEN (=LOAD) or NEW (=SAVE).

caption

The file dialog window caption.

defFile

The default file name. The default file is selected when the dialog is displayed (if it exists). If no default file is specified, the dialog is initialised with the present working directory (PWD).

type

The file extension.

typetext

The description of files with extension type.

Result:

The full path of file or empty string for cancel.

Examples:

butil filedialog open ; Select a settings file ; J:\data\settings.xml ; xml=xml settings file 



GETDIRECTORY

Call this macro to verify if a directory exists and to get a valid path (always).

Usage:

BUTIL GETDIRECTORY path

Parameters:

path

The directory to be checked.

Result:

The full path of the directory (if path exists and is a directory) or the S_TOOLS-STx installation directory.



GETKEYINDEX

If value is a valid keyword index (0 .. number of keywords – 1) or a keyword abbreviation, the corresponding keyword index is returned, otherwise the default value is returned.

Usage:

BUTIL GETKEYINDEX value ; default ; keywords

Parameters:

value

The argument value (an index or a keyword).

default

The default value.

keywords

A blank separated list of keywords.

Result:

The index of the keyword (if value is included in the keyword list) or the default value.



GETKEYWORD

If value is a valid keyword index (0 .. number of keywords – 1) or a keyword abbreviation the corresponding keyword is returned, otherwise the default value is returned.

Usage:

BUTIL GETKEYWORD value ; default ; keywords

Parameters:

value

The argument value (an index or a keyword).

default

The default value.

keywords

A blank separated list of keywords.

Result:

The keyword (if the value is included in the keyword list) or the default value.



GETSWITCH

Get a logical switch value. If value is a valid switch-value the value index (0|1) is returned, otherwise the index of the default value is returned. If both values are invalid, the function returns 0.

Usage:

BUTIL GETSWITCH value ; default

Parameters:

value

The switch argument value (0|NO|OFF|FALSE or 1|YES|ON|TRUE).

default

The default value, used if value is not a valid switch.

Result:

0 for false and 1 for true



LOGMSG

Write a message line into the log-window. The message line consists of the name of the calling macro (script) and the specified text.

Usage:

BUTIL LOGMSG text

Parameters:

text

The text to write to the log window.

Result:

None.



MSGBOX

Display a message box with specified title and text-line. The buttons can be selected from a couple of pre-defined sets, or define by the user.

If the timeout mode is used (maxtime > 0), a progress bar for the elapsed time is included in the message box. For the timeout-mode the default timer step is 50ms. The timer step can be specified with the argument maxtime in the format 'maxtime , step'.

To specify the x/y window position in pixels, a positive or negative number can be used. If x/y is greater/equal zero it is the offset from the left/top side of the desktop, otherwise (<0) it is the offset from the right/bottom side.

Usage:

BUTIL MSGBOX [ type [ buttons ]]; text [; caption ; maxtime ; xpos ; ypos ; monitor ]

Parameters:

type

The type of message box to display. The following values are supported:

MSG - An 'OK' button.

YESNO - A 'Yes' and a 'No' button.

YESNOCANCEL - A 'Yes', 'No' and 'Cancel' button.

OKAYCANCEL - An 'OK' and a 'Cancel' button.

OKAYRETRYCANCEL - An 'OK', a 'Retry' and a 'Cancel' button.

USERDEFINED - The argument buttons contains a blank separated list of buttons. See example below.

If type is not specified (the default), then no buttons are displayed. The message box can be closed withe the Escape key.

buttons

A list of user-defined buttons (blank separated).

text

The message text.

caption

The message box caption.

maxtime

The maximum time for which the message box should be displayed; set to 0 or less (default) to disable timeout handling.

xpos, ypos

The x-position in pixels or keyword LEFT, RIGHT or CENTER and the y-position in pixels or keyword TOP, BOTTOM, CENTER. If the xpos and ypos are not specified, the window is centered.

monitor

The monitor the dialog should appear on (from left to right - 1..x) or blank, if all monitors should be treated as one monitor.

Result:

Name of button or one of the keywords CANCEL (if the window was closed) or TIMEOUT (if the maximum timeout value was reached). Note that user-defined buttons using the ampersand '&' to underline a letter (e.g. &Segment) return the keyword including the ampersand.

Examples:

<code>BUTIL 'MSGBOX USERDEFINED Open Run Cancel ; User-defined Message Box Example'</code>



OPENFILE

Opens a file with the specified application (app is an application name or an exe-file path) or with the default windows application for the type of the specified file (app = *).

Usage:

BUTIL OPENFILE app ; file

Parameters:

app

The name of the application or * for the default application.

file

The name of the file to be opened.

Result:

none (void)



RENAMEFILE

Rename or move the source file to the target. If the target is a directory or a file in an other directory or on an other disk, the source file is moved, otherwise it is renamed.

Usage:

BUTIL RENAMEFILE source ; target

Parameters:

source

The name of the source file.

target

The name of the target file or directory.

Result:

0 for success or non-zero errorcode



SELECTTABLE

Usage:

BUTIL SELECTTABLE table selection

Parameters:

table

The name of a table item.

selection

A selection keyword: ALL|TOGGLE|NONE

Result:

The number of selected entries

Description:

Select all entries (ALL), clear selection (NONE) or invert selection (TOGGLE) of a table.



TRACE

Set trace mode or turn trace mode off.

Usage:

BUTIL TRACE mode [ logfile ]

Parameters:

mode

The following modes are supported:

OFF - turn trace mode off

ON - standard trace mode (write to log window) DEBUG - debug mode (show debug window on error)

logfile

The logfile path for standard trace mode; def.: workdir\TRACE.LST

Result:

none

see also:

COBJ::TRACE, global variables @TRACEON and @TRACEOFF



ONERROR

Write a message line into the log-window. The message line consists of the name of the calling macro (script) and the specified text.

Usage:

BUTIL ONERROR text

Parameters:

text

The text to log.

Result:

none



TREE2TREE

Copies the whole source directory tree to the target directory. Information, progress and errors are written to the script console.

Usage:

BUTIL TREE2TREE source ; target

Parameters:

sourceThe source directory to copy files and directories from.targetThe target directory to copy the source directory to.=====Result:=====

Returns the number of failed directories and/or files.



TREE2DATASET

Import all soundfiles from the source directory tree into a linked DataSet. If the dataset file already exists it is overwritten.

Usage:

BUTIL TREE2DATASET source ; datasetfilename ; createsets

Parameters:

sourceThe source directory to import soundfiles from.datasetfilenameThe name of the dataset file to import soundfiles into.createsetsSet to 1 if a set should be created in the DataSet for each subdirectory (0|1).=====Result:=====

There are no messages or return values.



EDITBOX

Display an edit box to retrieve basic user input

Usage:

BUTIL EDITBOX [ [ caption ] ; [ edit ] ; [ title ] ; [ width ]]

Parameters:

caption

The caption to display above the edit box. If left blank, no caption is used.

edit

The value to initialize the edit box with. If left blank, the edit box is left blank.

title

The title to use for the dialog box. If left blank, the default 'Edit Box' is used.

width

The edit box width in characters. The default is 17.

Result:

The content of the edit box on OK, and an empty string on Cancel.

Array