• Command files can be viewed in any text editor (File > New > Command File)
• Used for editing, saving and running the command file

The Command Processor supports a variety of commands. The processing done for a command line depends on the type of command line.

1. Common SQL commands

If the first token is one of the recognized SQL commands, the command line is passed to the SQL engine, possibly after some modest processing to simplify entry. For example, prefixing the qualifier (schema) of the table name is done automatically in the FROM clause of insert, update, and delete statements.

The recognized SQL commands are:
    INSERT, UPDATE, DELETE, CREATE, DROP, GRANT, REVOKE, and COMMIT

SELECT is not one of the directly supported SQL commands. Instead, you formulate queries and return results through Database Buffer commands (see below).

Also introduced below are some friendlier alternative Database Library commands, which can be used instead of the standard SQL commands. For example, you can use AddRec instead of INSERT, ChgRec instead of UPDATE, and CreatDbRecTyp instead of CREATE.

2. Built-in basic commands

If the first token is one of the recognized basic built-in commands, then the appropriate Command File is executed or Command Processor function is invoked. "Built-in" basic commands are an integral part of the Command Processor and are available exclusively through its command line interface.

The Command Processor's built-in basic commands include:

• Run, GoToCmdFil, DefMacro, UndefMacro
• OpenOutputCmdFil, ClosOutputCmdFil

The Command Processor can create an Output Command File listing all commands that will be executed when the command file is executed. Macros and nested command files are expanded for a total picture of what will happen at run time. All statements are listed, but are not executed, providing a tool for understanding, testing, and maintaining command files.

3. Built-in commands that use the Data Dictionary

If the first token is one of the recognized "built-in" commands that take advantage of the presence of the Data Dictionary that is part of the Rich Client architecture, then the appropriate Command Processor function is invoked in combination with access to the current database's data dictionary.

The Command Processor's built-in commands that use the Data Dictionary include:

• LoadRecs, UnloadRecs, DefMacroFromDb
• CreatDbRecTyp, DropDbRecTyp, CreatDbIdx, DropDbIdx
• CreatDbRefIntegrity, DropDbRefIntegrity
• GrantDbRights, RevokeDbRights

4. DOS and WIN command lines

If the first token is "DOS" or "WIN", then the rest of the command line is passed for DOS or Windows command line execution. (For DOS paths, because backslash, \, is considered the general "escape" character, remember to double any backslashes, \\, and the Command Processor will automatically convert them back into a single backslash, \, before passing the command line on for execution).

5. Error suppression commands

If the first token is SuppressDbErrsBegin or SuppressDbErrsEnd, then this command line marks the start or the end of a sequence of commands in which all but fatal errors are ignored, and only the most severe errors cause processing to stop.

6. Database buffer commands

A database buffer represents an area of main memory used for retrieving data from and transmitting data to a database. For each type of database buffer, there is a separate Create command (e.g. CreatRecBuf, CreatRecSetScrlCacheBuf), CreatProcBuf), which appears first on the command line, and the second token is the name to be given to the new database buffer. Thereafter, if the first token of a command line is a user-created Database Buffer Name, then this must be followed by "dot", i.e. ".", followed by a function name that is valid for the type of Database Buffer. The rest of the command line is treated as parameters to that function. Most operations on a database buffer require using the "BufferName - dot - command" syntax (e.g. "recStudent.GetNextRec").

The Database Buffer commands are described in the Database Library manual. The ones that can be used in a Command processor command line include:

• CreatRecBuf, CreatRecSetBaseBuf, CreatRecSetScrlCacheBuf
• CreatProcBuf, CreatRecSetFilBuf
• InitRec, InitRecSet, InitProc, InitRecSetFil
• AddRec, ChgRec, DelRec, SetData, SetParamData, SetPrepareDbCmdFlag
• ExecProc, BuildRecSetFil, WriteRec
• GetRecSet, GetRec, GetFirstRec, GetLastRec, GetNextRec, GetPrevRec
• SetSelItmLst, SetSelFromLst, SetSelCriteria, SetSelDistinctFlag
• SetSelFromLstAndJoinExpr, SetGrpByColLst, SetGrpHavingCondition
• SetSortOrder, SetSortKey, SetSearchVal, FindRec
• GetData, GetAttObj, SetAttObj, SetDbBufNam

7. Database Manager commands

The Database Manager provides the Command Processor with most important functions for operating on databases as a whole. Whatever follows the command name in the command line is passed as parameters to the Database Manager function. There are commands for opening and closing additional databases or switching between databases. There are other useful commands, like CopyData, which copies data from one database buffer to another, DelResultSet, which is used for deleting large number of database records from a record type based on a criteria and DelRecSetFil for deleting a record set file.

The Database Manager commands are described in the Database Library manual. The ones that can be used in a Command processor command line include:

• OpenDb, ClosDb, SwitchDb, SetDbTyp, SetLogonUsr
• Commit, SuppressDbErrsBegin, SuppressDbErrsEnd
• CopyData, DelResultSet, DelRecSetFil, InitDbLog, LogStr
• StartDbTrace, StopDbTrace, SetDbTraceLvl, SetDbTraceOutputOpt

8. Custom commands

If the first token in a command line is on the list of "custom" commands in that application's "global definitions", then the associated, application-supplied, Custom Command Function is invoked, with the rest of the command line passed as a parameter. ShowStr and ShowDbBuf are sample, useful, custom display commands, and their C++ source code can be changed to suit the application. Such global definitions are not available through the BFCCOM interface, and Custom Commands are not available through BFCCOM.

Besides adding new commands, the Custom Command facility can also be used by C++ programmers to deny access to any of the known commands that can appear as the first token in a command line. The search to determine if the first token is a Custom Command precedes all other lookups. This permits the programmer to prevent the use of any command simply by making an entry that launches a custom function that returns an access-denied message.

9. Macro assignment command lines

If the first token of a command line is not recognized, and the second token is the equal sign, then the first token is taken as the name of a macro to be set with the return value of the command specified by the rest of the command line (that is, starting with the third token).

10. Any other command line

If the first token is not recognized by the Command Processor and the second token is not the equal sign, =, then the entire command line is passed without change for execution to the SQL processor of the current database.

Users running the programmer's version of the Command Processor dialog have diagnostic options such as stopping on every line of a command file, ignoring errors, or issuing commands by typing them directly without using a command file at all. The operator's version of the Command Processor dialog is the same as the programmer's version except that operators cannot edit command files and the operator's version always stops on errors. It is simple for a programmer to create a custom dialog which operators use to run a particular command file. The programmer merely supplies a dialog box title and a message to display on successful completion.

Command Processor (operator version) - Rebuild BFC Sample Data

The programmer's version is launched by a menu item under the Foundation App's System menu. The operator's version is used extensively for activities found under the Administration/System Utilities, such as "Build Application Database", and "Unload Sample Data" (one of the Test Utilities). The batch version is used in the sample batch function for running a command file as a batch job.

Sample Command File Showing LoadRecs Usage

/**************************************************************************
Date last modified: 2000-05-16
File Name: IWDLSam.cmd
Module Name: InterWatch - LOAD SAMPLE Data - Command File
********************** */

// Delete all sample data if present
DELETE FROM RptSpecItm WHERE UsrCod >= 51 AND UsrCod <= 100;
DELETE FROM RptSpecMast WHERE UsrCod >= 51 AND UsrCod <= 100;
DELETE FROM UsrMast WHERE UsrCod >= 51 AND UsrCod <= 100;
DELETE FROM UsrGrp WHERE UsrGrpCod >= 51 AND UsrGrpCod <= 100;
DELETE FROM SecGrp WHERE SecGrpCod >= 51 AND SecGrpCod <= 100;

// Sample Security Group
LoadRecs SECGRP
SECGRPCOD,SECGRPNAM,
SECGRPREM;
{
51,InterWatch Guest User Privileges,
No Administrative or System Utility functions
}

// Sample User Group
LoadRecs UsrGrp
UsrGrpCod, UsrGrpNam, UsrGrpRem;
{
51,Base One/Allegiance, Programmers and Testers
}
{
52,Young and Rubicam, Sample Client
}
{
53,InterWatch Trainee Access, CMR and IAS trainees
}

// Sample Users
LoadRecs USRMAST
USRCOD,USRID,
USRSORTNAM,NAMPREFIX,
FIRSTNAM,MIDDLENAM,LASTNAM,
NAMSUFFIX,
USRPASSW,
USRGRPCOD,SECGRPCOD,USRTYPCOD,
LOGFILPATH,
(USRNOTE,AttObjTypCod);
{
51,JSMITH,
"smith, john",,
John,,Smith,
,
JSMITH,
52,51,4,
,
}
{
52,MJONES,
"jones, mary",,
Mary,,Jones,
,
MJONES,
51,1,4,
,
}