Appendix C - User-Defined Action Macros

Appendix C - User-Defined Action Macros

Commands marked with (*) can be executed via DDE Server.

> and >> Redirection is possible only for UDA commands whose standard output is "UDA Output window".

Macro examples:

UDA macro without redirection: .c:\bc5\bin\bcc32.exe xx.c
UDA macro with redirection: .c:\bc5\bin\bcc32.exe xx.c > red.lst
UDA macro with append: .c:\bc5\bin\bcc32.exe xx.c >> app.lst

%Activate* Sets focus to the application.

%AsmFile Loops through the files of the project, returning each full name. The line in which this macro is used will be executed for each file, unless used with %Dir macro. If the original file does not exist, the name of the alternative file (determined by Referential Extensions) will be returned.

%AsmToolsDir Returns active “Assembler tools directory” configured in "Assembler Options" dialog.

%BrowseFolder( Title, StartFrom ) Returns the selected path in the dialog box entitled Title, starting with the folder assigned by the StartFrom parameter. If the second or both parameters are left out, the Project Root directory is started.

%CallGraph( filename, functionname )* This macro is implemented for usage via DDE interface. It shows "filename" file in Editor, then shows Call Graph for "functionname".

%Cancel Terminates the execution of User-Defined Actions.

%CFile Loops through the C files of the project, returning each full name of a file which have extension defined as C module extension. The line in which this macro is used will be executed for each file, unless used with %Dir or %AsmFile macros, which both have higher priority. If the original file does not exist, the name of the alternative file (determined by Referential Extensions) will be returned.

%Close( filename )* Closes all open windows containing the named file.

%Cls Clears content of the "UDA Output" tab in the Command window. It can be used directly from command line in User-Defined Actions Output window.

%CompToolsDir Returns active “Compiler tools directory” configured in "Compiler Options" dialog.

%CurrColumn Returns the column number of the insertion point in the currently edited file. If the active window is not an Editor, an empty string is returned,

%CurrEdit If the active window is an Editor, the name of the edited file is returned. Otherwise, an empty string is returned.

%CurrFile Returns the full name of the active file. If the active window is a Project Explorer with the existing selection, the name of the selected file is returned. The line in which this macro is used will be executed for each selected file, unless used with the %Dir macro. If the active window is an Editor, the name of the edited file is returned. Similarly, the file name can be extracted from Browser or Messages line. Otherwise, an empty string is returned.

%CurrLine Returns the line number of the insertion point in the currently edited file. If the active window is not an Editor, an empty string is returned.

%CurrPath Returns the full path of the active file. If the active window is a Project Explorer with the existing selection, the path of the selected folder is returned. If the active window is an Editor, the path of the edited file is returned. Similarly, the path can be extracted from Browser or Messages line. Otherwise, an empty string is returned.

%Del( filename, norecyclebin ) Moves the file filename to Recycle Bin folder. Using optional Boolean norecyclebin parameter with value "TRUE", deleted file will be permanently erased. If second parameter is omitted, or set to FALSE, deleted file will be moved into Recycle Bin. Wildcards in filename are supported.

%Dialog( title ) Activates the dialog box which allows text entry and returns its result.

%Dir Loops through the names of the project subfolders, returning the name of each project folder. The line in which this macro is used will be executed for each project subfolder. In this case, the %File macro will be executed only for the first file in the subfolder.

%Disk( filename ) Extracts the name of the disk from the full file name. The trailing colon, that is "C:" is included.

%Edit( filename )* Opens an Editor containing the named file.
Named file is searched thru the following folders in the following order:
1. Folder defined by the SetDir macro (by default it is Project Root folder).
2. Project Root folder
3. Referential Root folder

%Env( varname ) Returns the value of an environment variable. Returns an empty string if the variable is not defined.

%EQ( x, y ) Returns "T" if x is equal to y, otherwise returns an empty string.

%ErrClr( tabname ) Clears Message Logs partial contents. If the tabname is an empty string, the User-Defined Actions tab will be cleared, otherwise the tabname will be cleared.

%ErrGet( listfile ), %ErrGet( listfile, title ) %ErrGet( listfile, efmt, wfmt ), %ErrGet( listfile, efmt, wfmt, title ), %ErrGet( listfile, efmt, wfmt, ffmt, ifmt, title ) Activates a Message Logs and displays all parsed messages from the listfile file, title is the title of the appropriate Message tab. If invoked with one or two parameters the format of recognized messages in listfile depends on the current ANSI-C dialect defined using the Options >Static Code Analysis... / C Source dialog box. The message format can also be specified by the arguments: efmt (errors format), wfmt (warnings format), ffmt (fatal errors format) and ifmt (information format). Format parameters begin with first character after ',' and end with last character before ',' or ')'. This can be used for any file, for example linker map or another log files. Special marks are provided for describing message formats: $F - file name $L - line number (sequence of decimal digits) $I - non-empty sequence of characters which should be ignored. When the marks $F or $L are supplied in a format string, the marks must not follow each other directly (there must be one or more ordinary characters in between). Lines beginning with a sequence that can be fitted in the error or warning format are copied to the Message Logs window - the remaining part of the line is considered message description. If the mark $F is not supplied, then the listfile and the line in which the format string is matched is associated. Otherwise, the file recognized in the error message is associated. $F recognizes only files with extensions defined in “Options > Project > File Types”. If one string on the beginning of line shall be copied in a message then this part shall be marked with $M.

Formats for every supported compiler are hard coded, for example:

"Error $F $L: "
"Warning $F $L: "

Equivalent calls with explicit usage of these formats:

%ErrGet( lstfile,Error $F $L: ,Warning $F $L: )

Invoking of %ErrGet with only one parameter when the current version of the C language is "Kernighan and Ritchie" C or ANSI-C will cause an error to be reported.

With %ErrGet(lstfile,PC-Lint,V8.xx,tabname) you may parse the PC-Lint V8.xx output file. With %ErrGet(lstfile,PC-Lint,V9.xx,tabname) you may parse the PC-Lint V9.xx output file. DA-C supports only the PC-Lint default message format.

Message line in listing file: "Error: E:\Work\...\peripherals_init.c(15): '.' not expected"
Filter definition: "Error:$M $F($L):"
Resulting line in DA-C Message Window: "Error: '.' not expected"

%ErrJump( n, name, flag ) Jumps to the n-th (default 1) message line in a "name" tab (default "User-Defined Actions"). If the "flag" has logical true value or "open" then opens appropriate file on the message line (in Editor).

%Exist( filename ) Returns a "T" string if the filename file exists, otherwise returns an empty string.

%Ext( filename ) Extracts the file extension from the full file name, including "." as the first character, that is ".h".

%False() Returns empty string.

%FDialog( title ) Activates the File > Open dialog box with the given title and returns its result.

%File Loops through the project files, returning each full file name. The line in which this macro is used will be executed for each file, unless used with the %Dir macro. If the original file does not exist, the name of the Referential file will be returned.

%FileOpt( filename, optname )
Returns the optname option associated with the filename file.
This macro replaces the obsolete %FileDescription and %FileMakeOpt macros, which are still supported for reasons of compatibility.
The optname parameter can have one of the following values:

MakeOpt returns Makefile options string for file, entered in the DA-C Properties dialog box. To ensure compatibility with earlier versions of DA-C, the %FileMakeOpt macro is still supported.

Alias returns alias name of file, entered in the DA-C Properties dialog box. To ensure compatibility with earlier versions of DA-C, the %FileDescription and %FileAlias macros are still supported.

%FlowChart( filename, linenumber | funnctionname )* This macro is implemented for usage via DDE interface. It shows "filename" file in Editor, then shows Flowchart on "linenumber" or for "functionname".

%GE( x, y ) Returns "T" if x is greater than or equal to y, otherwise returns an empty string. Comparison is made like strcmp.

%GT( x, y ) Returns "T" if x is greater than y, otherwise returns an empty string. Comparison is made like strcmp.

%HasAsmExt( x, y ) Returns "T" if the file extension corresponds to one of the extensions defined by Assembler module extension, otherwise returns an empty string.

%HasModuleExt( filename ) Returns "T" if the file extension corresponds to one of the extensions defined by the Module Extension, otherwise returns an empty string.

%if( x, y ) Returns y if x is not equal to "", otherwise returns an empty string.

%if( x, y, z ) Returns y if x is not equal to "", otherwise returns z.

%LE( x, y ) Returns "T" if x is less than or equal to y, otherwise returns an empty string. Comparison is made like strcmp.

%LeaveAppOnTop( condition )
Sets or resets the flag which changes the behavior of DA-C during invoking of other applications. Setting this flag can in the appropriate circumstances force DA-C to stay in the background after invoking of the application from User-Defined Actions. The flag is by default set to FALSE on the start of all commands which belong to the one User-Defined Action.

%LT( x, y ) Returns "T" if x is less than y, otherwise returns an empty string. Comparison is made like strcmp.

%MakeToolsDir Returns active "Make tools directory", configured in "Makefile Generator Options" dialog.

%Message( text ) Shows the message box with the given text and returns an empty string.

%Name( filename ) Extracts the file name filename without disk, path and extension parts of the full file name.

%NE( x, y ) Returns "T" if x differs from y, otherwise returns an empty string.

%Not( x ) Returns "T" if x is equal to "", otherwise returns an empty string.

%Path( filename, options )
Extracts the path from the full file name filename. The leading and trailing backslash are included, that is "\dir\subdir\". Parameter options can be a combination of the characters "s", "-" and "/", where meanings of these characters are:

's' short path to Project Root (if possible), To ensure compatibility with earlier versions of DA-C, the %RelToPrjRoot macro is still supported.

"-*" suppresses leading backslash, "*-" suppresses trailing backslash.

'/' change '\' to '/'

%PrjRoot Returns the Project Root directory.

%Project Returns the full name of the project.

%R1( string ), %R1, %R2( string ), %R2, %R3( string ), %R3, %R4( string ), %R4 The form with the parameter stores the contents of the string, while the other one returns the previously stored value.

%ReferFile( filename ) Returns the full referential name of "filename".

%ReferPath( path ) Returns the full referential path of "path". To ensure compatibility with earlier versions of DA-C, the %ReferRoot macro is still supported.

%RefreshPrjWin* Refresh a Project Explorer in accordance with the current state on the disk.

%Registry( key ) Returns key value for "key". The key may be from HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_USERS and HKEY_CURRENT_CONFIG class.

%Reset( filename )* If a filename exists, the Reset macro resets lines numbers in the Editor. After this macro has been run, jumps from the Browser no longer function properly; to correct this, the Start > BuildProject command should be carried out.

Explanation: Once static code analysis has been performed, browse information contains current line numbers in files. Using an internal filter for translating browse line numbers into current line numbers, Editor also takes into account subsequent file changes, so that navigation on the basis of browse information is still possible to a certain extent. The regular procedure is to save the file before any external commands are carried out (calling the Compiler, Make, and the like). After any external commands have been carried out, you will display parsed messages from listfile in the Message Logs (%ErrGet macro). Should you now want to go to the line which caused the message by double-clicking the message line, Editor will display the wrong line due to internal filter use. To reset the internal filter, run the %Reset macro. Once the internal filter has been reset, jumps from the Browser will no longer be correct, which makes it necessary to carry out the Start > BuildProject command prior to such jumps.

%SaveAll* Realizes the File > Save All function and returns an empty string. This macro can appear as the only content of the external command or as its part, in which case it is realized first.

%Save( filename )* Saves the file from the Editor to the disk, if any change has been made. To ensure compatibility with earlier versions, the alternative command %Update( filename )* may be used.

%SetDir( path ) Sets the disk and the directory from which the external programs will be executed. This path is valid for all external programs and the %ErrGet macro from the line in which it was used till the end of the user action or the next %SetDir. In case the directory has not been assigned, the default directory will be the one defined by Options > Project / Project Root Directory.

%SetWin( winsize ) Determines the state of the external program Main window. The winsize parameter can have the following values: "MIN" (the Main window is minimized), "MAX" (the Main window is maximized) and "NORMAL" (the Main window is of normal size). This macro is valid for all external programs from the line in which it was used till the end of the user action or the next %SetWin. For a DOS program, the program-information file (PIF) for the application (or _DEFAULT.PIF) determines the window state. %SetWin has no effect if the program is executed in full screen mode.

%Show( filename )* Shows filename file in Editor if it is open or opens the filename file in Editor.

%SourceMode Returns the string identifying the current dialect of the C language defined in the Options > Compiler... / C language dialct list.

%Time( filename ) Returns the time of the most recent modification of a file in the form of a string consisting of two-digit numbers representing the year, month, day, hour, minute, second (for example: 940930054535). This macro returns an empty string if the file cannot be found.

%TrimName( filename ) Removes the extension from the full file name filename (C:\A\B.TXT becomes C:\A\B). The effect of the %TrimName macro can be produced by concatenating %TrimPath and %Name macros.

%TrimPath( dirname ) Removes the last "\" character from the name of the folder, unless it represent the root folder. This can be useful in some external commands. The %TrimPath macro can also be used to remove the file name and extension parts from a full file name, similarly to the %Path macro.

%TrimSpec( namepart ) Removes an ending colon ( : ) or a backslash ( \ ) character from the given string. Otherwise returns original string. This can be useful when a folder or a disk name without a terminating backslash or colon is needed.

%True Returns "T".

%Wait( time ) Used after external programs have been started with "+program" in order to wait for call results. If the program is started with ".program", then the use of this macro is nonsensical. Time is defined in seconds.

%YesNo( title ) Activates the dialog box with the given title and Yes / No / Cancel options. If Cancel is selected, it terminates the execution of User-Defined Actions. Selecting Yes returns "T", while selecting No returns an empty string.