The Graham Utilities for OS/2 - Version 2


[Warpspeed]

[Table of Contents] [Index] [Previous] [Next]


BE - Batch Enhancer

Summary

BE may be used to enhance batch files (.CMD). It has various sub commands available. Use BE to create interactive, more powerful batch files.

Icon

Command Line Format

Usage: BE <File Spec>
           or
       BE command parameters
Where command is one of the following:
ASK
BEEP
BOX
CLS
DAY
DELAY
MONTH
PRINTCHAR
REBOOT
ROWCOL
SA
SEMCLEAR
SEMCLOSE
SEMCREATE
SEMKILL
SEMLIST
SEMSET
SEMWAIT
WEEKDAY
WINDOW
YEAR

Enter BE command ? to get help on a specific command.

Description

BE has two command formats. It can be passed all of its command line arguments at once, for example:

BE SA White on Blue
Or BE can be passed a response file to parse. In this mode BE can be passed multiple commands all at once, and they will be executed in sequence. Be aware however, that some commands (SEMWAIT for example) will return an exit code. The response file will not be processed beyond any command which returns an exit code. Return codes are useful for a batch programmer to enable the control of the execution of a .CMD file.

A response file is a file which contains BE commands and parameters for batch processing. Each line in the file contains one BE command. Response files do not require BE to be on each individual line. For example:

BE TestFile
where TestFile contains:
SA White on Blue
All of the following examples will be of the BE command parameters format.

BE ASK

Summary

BE ASK prompts the user for a response to a question. Use ASK to make conditional branches (jumps) in your .CMD files.

Command Line Format

Usage: BE ASK "prompt" key-list <DEFAULT=key>TIMEOUT=n
                      ADJUST=n Colour Spec

Parameters

"prompt"
The text string with which the user is presented. If it is more than a single word, it must be surrounded by double quotes (").
key-list
Key-list is the list of valid responses that the user may select. The first character will return an error level of 1, the second an error level of 2 and so on.
DEFAULT=key
If the user presses Enter or uses it with the TIMEOUT option, ASK will behave as if the user had selected this response. This is an optional parameter. If DEFAULT is not specified, BE will return an error level of 255.
TIMEOUT=n
Used to return an answer after n seconds if the user has not pressed a key. This should be used with the DEFAULT option. This is an optional parameter. If it is not specified, ASK will continue to wait until a valid key is pressed.
ADJUST=n
Adjust allows you to specify an offset to the error code returned to the OS/2 command processor. The value of n will be added to all return values. This is an optional parameter.
Colour Spec
Colour Spec is a colour specification. See BE SA for further details. This is an optional parameter.

Description

BE ASK prompts the user for a response to a question. ASK will return an error code to OS/2 so that the IF ERRORLEVEL batch command can be used to make conditional branches (jumps) in your .CMD files.

Note that both the "prompt" and [key-list] options must be supplied.

Examples

Rem this is the first sample batch file
BE ASK "Start the network in Server mode [Y/n]?" YN
Default=Y timeout=10
If errorlevel 2 goto Requester
Rem Start the network in server mode
Net Start Server
Goto Quit
:Requester
BE ASK "Start the network in Requester mode [Y/n]?"
YN Default=Y timeout=10
If errorlevel 2 goto Quit
Net Start Requester
:Quit
This batch file will ask the user if they wish to start IBM LAN Server in Server mode. If the user responds "No" to this, by pressing the "N" key, they will be further prompted to start LAN Server in Requester mode. If the user does not press any key within 10 seconds, the default option of Y is used to start the network in server mode.
REM this is the second sample batch file
BE ASK "Press the Y key only" Y
Echo You pressed the Y key
:Quit
This example is as about as simple as you can get. It prompts the user to only press the 'Y' key.

BE BEEP

Summary

BE BEEP plays a tune file.

Command Line Format

Usage: BE BEEP <file>
Options

The following options are valid in tune files:

/Fn
Specify the frequency of the tone in Hertz.
/Dn
Specify the duration of the tone in n/18 seconds.
/Tn
Specify the duration of the tone in milliseconds.
/Rn
Repeat a tone n times.
/Wn
Wait n/18 seconds between tones.

They can also be specified in raw Frequency Duration pairs. This makes BEEP compatible with Maximus BBS format tune files.

The repeat and wait options only apply to the line on which they appear.

Tune files may also have comments in them. Comments start with a semicolon ";".

Description

BE BEEP allows you to play tunes on your computer. It supports a wide variety of formats.

Two sample tune files have been provided. These are INDIANA and SIMPSONS.

Examples

BE BEEP INDIANA
Will play the "Indiana Jones" theme.
BE BEEP SIMPSONS
Will play the theme from "The Simpsons".

BE BOX

Summary

BOX allows you to display a box on your text screen.

Command Line Format

Usage: BE BOX top left bottom right <colour spec> STYLE=n
Parameters
top
Specifies the row position of the top left hand corner of the box.
left
Specifies the column position of the top left hand corner of the box.
bottom
Specifies the row position of the bottom right hand corner of the box.
right
Specifies the column position of the bottom right hand corner of the box.
colour spec
Specifies a colour specification. See BE SA for further details. This is an optional parameter.
STYLE=n
This allows you to specify the style of the box which is drawn. Valid values for n are:
0 No border is drawn.
1 A single line border is drawn.
2 A double line border is drawn.
The default style is 2.

The row and column coordinates can range from one up to the maximum row and column coordinates as specified by the MODE command. These values have a default value which is dependent on your video adaptor.

Description

BOX allows you to display a box on the screen. Only the boarder of the box is drawn. The body, or centre of the box is left as is. The type of box characters drawn can be specified by the STYLE parameter. A SA colour specification may also be added to set the colours of the drawn box.

Examples

BE BOX 1 1 25 80
In standard VGA screen mode (80 columns by 25 rows), the above command will display a box which will outline the entire screen in the current screen colours.
BE BOX 10 10 15 70 Bright Green on Black
This will display a box using bright green characters on a black background in the middle of the screen.
BE BOX 10 10 15 70 Bright Red on Black Style=1
This will display a box using bright red characters on a black background in the middle of the screen. The box will be drawn using single line box characters.

BE CLS

Summary

Clears the current screen.

Command Line Format

Usage: BE CLS

Description

BE CLS will clear the current screen. This is identical to the OS/2 CLS command and is included so that it may be used in a response file.

Example

BE CLS
This will clear the current screen. The current screen colour remains unchanged.

BE DAY

Summary

The BE DAY returns the current day of the month as an error level.

Command Line Format

Usage: BE DAY

Description

BE DAY will return the current day of the month as an error level so that batch programs can carry out actions on specified days. This BE sub command will return an error level to the OS/2 command interpreter. With the use of this command any processing of a BE response file will cease.

Example

BE DAY
The current day of the month will be returned as an error level. The returned values are in the range of 1 to 31.

BE DELAY

Summary

BE DELAY waits for a specified period.

Command Line Format

Usage: BE DELAY ticks  {-ESC} (1 tick = 1/18 second)
Parameters
ticks
Specifies the time period of the delay. Each tick is 1/18 of a second or approximately 55 mSec.
-ESC
Allows early escape from the delay by pressing the Escape key.

Description

The BE DELAY command is useful to force a batch file to pause for a fixed period of time. You could use the BE DELAY command to allow some of your computers on a network to boot and establish themselves before they start to share each other's resources.

Examples

Net Start Server
REM Wait for 5 minutes
REM Wait for the other machine to boot and wait for us
BE DELAY 5400
Logon Chris
Net Use H: Main-H
This example starts LAN Server in server mode. BE then waits for 5 minutes for another server to boot and then logs on and uses the resources of other machines.

BE MONTH

Summary

BE MONTH returns the current month of the year as an error level.

Command Line Format

Usage: BE MONTH

Description

BE MONTH will return the current month of the year as an error level to enable batch programs to carry out actions in a specified month. This BE sub command will return an error level to the OS/2 command interpreter. Any processing of a BE response file will cease with this command. The month of January will return an error level of 1 and so on.

Example

BE MONTH
The current month of the year will be returned as an error level. The returned values are in the range of 1 to 12.

BE PRINTCHAR

Summary

BE PRINTCHAR prints a specified character at the current cursor position a defined number of times.

Command Line Format

Usage: BE PRINTCHAR character count <colour spec>
Parameters
character
Specifies the character to be printed.
count
Specifies the number of times the character is to be printed.
colour spec
Specifies a colour specification. See BE SA for further details. This is an optional parameter.

Description

BE PRINTCHAR is a convenient way of displaying a single character multiple times. Using BE ROWCOL will establish the cursor position.

Note : If more than one character is given, then only the first one will be printed.

Examples

BE PRINTCHAR A 20 bright green on blue
This will print the letter "A" 20 times at the current cursor position. The "A" will be bright green on a blue background.
BE PRINTCHAR " " 10
This example will print 10 spaces at the current cursor position.

BE REBOOT

Summary

BE REBOOT will shutdown all file systems and then reboot your computer.

Command Line Format

Usage: BE REBOOT {-NOVERIFY}

Switches

-NOVERIFY
Specifies that the user will NOT be prompted to confirm the reboot of the computer.

Description

BE REBOOT allows you to reboot your computer. It will shutdown all file systems, close all open files and then reboot.

Warning : USING THIS METHOD TO REBOOT YOUR COMPUTER IS DANGEROUS. THE CURRENTLY ACTIVE PROGRAMS RECEIVE NO WARNING THAT THE MACHINE IS ABOUT TO BE REBOOTED. DATA LOSS COULD RESULT BECAUSE A PROGRAM MAY HAVE DATA IN MEMORY WHICH HAS NOT BEEN SAVED TO DISK.

This option of BE requires the DOS compatibility box to be installed. If BE is unable to reboot the computer due to the DOS compatibility box not being installed you will be given the following error message:

DOS.SYS not installed (SYS0110).
Microsoft Windows NT does not support this command. Using Windows NT you will see the above error.

Examples

BE REBOOT
With this example you will be asked if you wish to continue and reboot the computer, or cancel the command.
BE REBOOT /NOVERIFY
This example will not prompt the user, it will simply reboot the computer.

It is recommended that this command is only used when a user will not be in attendance. An example could be to force a machine to reboot at midnight.

BE ROWCOL

Summary

BE ROWCOL will position the cursor at the specified location, and if required, print some text in a given colour.

Command Line Format

Usage: BE ROWCOL row col <"text"> colour spec
Parameters
row
Specifies the row position of the cursor.
col
Specifies the column position of the cursor.
"text"
Specifies the text to be displayed. This is an optional parameter.
colour spec
Colour is a colour specification. See BE SA for further details. This is an optional parameter.

Description

BE ROWCOL positions the cursor at the specified row and column position. It may also optionally display some text. The colour of the displayed text may also be specified. This option is most useful in a BE response file.

The row and column coordinates start at 1 and range up to the maximum row and column coordinates as specified by the MODE command. These values have a default value dependent on your video adaptor.

Examples

BE ROWCOL 10 10
Positions the cursor at 10, 10.
BE ROWCOL 15 40 Hello
Prints "Hello" at 15, 40.
BE ROWCOL 16 40 "Hello There"
Prints "Hello There" at 16,40.
BE ROWCOL 17 40 "Hello There Again" Bright Red
Prints "Hello There Again" at 17, 40 in bright red on a black background.

BE SA

Summary

BE SA allows the user to specify the current screen attributes, or colours.

Command Line Format

Usage: BE SA [bright] [blinking] [reverse] [underline]
            <colour> on colour -c
Parameters
bright
Specifies that the foreground colour will be bright. This is an optional parameter.
blinking
Specifies that the displayed characters will blink or flash. This is an optional parameter.
reverse
Specifies that the text to be displayed will be displayed in black on white, unless over ridden by a foreground/background combination. This is an optional parameter.
underline
Specifies that the text to be displayed will be underlined. This will only work on monochrome monitors. Colour monitors will display any underlined text in blue.
colour
Specifies the foreground colour. It can be any one of the valid colours. This is an optional parameter.
on colour
Specifies the background colour. It can be any one of the valid colours. This is an optional parameter.
-c
This switch will clear the screen before the new colour attributes are set.

The valid colours are:

Black
Red
Green
Yellow
Blue
Magenta
Cyan
White

Description

BE SA allows the user to specify the current screen attributes, or colours. It sets the current screen attributes so that any further displayed text will appear in those attributes unless overridden with a colour specification from another BE SA or similar command.

Examples

BE SA RED
This will set the current foreground colour to red. The background colour is set to black.
BE SA ON RED
This will set the current background colour to white on red. If the foreground colour is not specified it will default to white.
BE SA Bright green
This will set the foreground colour to bright green on black.
BE SA REVERSE -c
This will set the current text colours to black text on a white background, after the screen has been cleared.
BE SA blue reverse
This will set the current text colours to blue on a white background.
BE SA blinking red
This will set the current foreground text colour to blinking red on a black background.

BE SEMCLEAR

Summary

BE SEMCLEAR is used to clear a system semaphore.

Command Line Format

Usage: BE SEMCLEAR <semaphore>
Parameter
semaphore
This is the semaphore which SEMMGR will clear. It must be a valid OS/2 file name.

Description

A system semaphore has two states; set or cleared. The BE SEMCLEAR command clears the specified semaphore. Please consult Appendix B - SEMMGR for a description of SEMMGR and semaphores.

Examples

BE SEMCLEAR test
This example clears the semaphore \SEM\SEMMGR\TEST. It must have been previously created using the BE SEMCREATE command.
BE SEMCLEAR test\test
This example clears the semaphore \SEM\SEMMGR\TEST\TEST.

BE SEMCLOSE

Summary

BE SEMCLOSE closes a system semaphore.

Command Line Format

Usage: BE SEMCLOSE <semaphore>
Parameter
semaphore
This is the semaphore which SEMMGR will close. It must be a valid OS/2 file name.

Description

The BE SEMCLOSE command closes a semaphore which is managed by SEMMGR. The semaphore must be cleared before SEMCLOSE can be called. If it is not cleared, an error will occur. When the semaphore is closed, it is no longer maintained by SEMMGR. Thus it no longer exists. For the same semaphore to be reused again, it must be recreated with the BE SEMCREATE command. Please consult Appendix B - SEMMGR for a description of SEMMGR and semaphores.

Examples

BE SEMCLOSE test
This example closes the semaphore \SEM\SEMMGR\test.
BE SEMCLOSE test\test
This example closes the semaphore \SEM\SEMMGR\test\test.

BE SEMCREATE

Summary

BE SEMCREATE is used to create a system semaphore.

Command Line Format

Usage: BE SEMCREATE <semaphore>
Parameters
semaphore
This is the semaphore which SEMMGR will create. It must be a valid OS/2 file name.

Description

A semaphore must be created before it can be used. BE SEMCREATE does this. When a semaphore is created, its initial state is cleared. See Appendix B for a complete discussion on the use of semaphores.

SEMMGR has a maximum limit of 128 semaphores.

Examples

BE SEMCREATE test
This example will create a semaphore. The complete semaphore name is \SEM\SEMMGR\test. However you will only supply the name which follows \SEM\SEMMGR\. SEMMGR builds up the complete semaphore name for you.
BE SEMCREATE test\test
The semaphore \SEM\SEMMGR\TEST\TEST will be created for you. It may then be used in subsequent semaphore operations.

BE SEMKILL

Summary

BE SEMKILL terminates the detached process SEMMGR.

Command Line Format

Usage: BE SEMKILL

Description

SEMMGR is a detached process. It runs in the background. It has no way of accepting commands from the user, except from BE. The BE SEMKILL command sends a command to SEMMGR to force SEMMGR to terminate.

Warning : When SEMMGR is terminated it clears all semaphores and closes them. This may cause unexpected results in your batch programs. Its use is not recommended, although sometimes it is necessary to unilaterally clear and close all SEMMGR managed semaphores. Please consult Appendix B - SEMMGR for a description of SEMMGR and semaphores.

Example

BE SEMKILL
The BE SEMKILL command has no parameters. This is the only way in which it may be called.

BE SEMLIST

Summary

BE SEMLIST lists all of the semaphores currently managed by SEMMGR and their state.

Command Line Format

Usage: BE SEMLIST

Description

The BE SEMLIST command lists the full name of each of the semaphores managed by SEMMGR as well as their state. Please consult Appendix B - SEMMGR for a description of SEMMGR and semaphores.

Example

BE SEMLIST
There are no parameters for the BE SEMLIST command. The output of the command will look similar to:
State  Semaphore Name:
-----  --------------
Set    \SEM\SEMMGR\test
Clear  \SEM\SEMMGR\test\test

BE SEMSET

Summary

BE SEMSET is used to clear a system semaphore.

Command Line Format

Usage: BE SEMSET <semaphore>
Parameter
semaphore
This is the semaphore which SEMMGR will set. It must be a valid OS/2 file name.

Description

A system semaphore has two states; set or cleared. The BE SEMSET command sets the specified semaphore. The BE SEMSET command waits for the semaphore to be cleared before it is again set. This is to stop semaphore contention problems. Please consult Appendix B - SEMMGR for a description of SEMMGR and semaphores.

Examples

BE SEMSET test
This example sets the semaphore \SEM\SEMMGR\TEST. It must have been previously created using the BE SEMCREATE command.
BE SEMSET test\test
This example sets the semaphore \SEM\SEMMGR\TEST\TEST.

BE SEMWAIT

Summary

BE SEMWAIT waits for a specified semaphore to clear.

Command Line Format

Usage: BE SEMWAIT <semaphore> [timeout (in mSec)]
Parameters
semaphore
This is the semaphore which SEMMGR will wait on. It must be a valid OS/2 file name.
timeout
This specifies the timeout value during which BE will wait for the semaphore to clear. If no value is specified, BE will wait indefinitely.

Description

Semaphores have two states - they are either set or cleared. The default state of a semaphore when it is created is cleared. The BE SEMWAIT command waits for a semaphore's state to change from set to clear. A timeout period, (the period that you are prepared to wait for the semaphore to clear), may also be specified. The timeout period is specified in milliseconds. If a period is not given, BE will wait indefinitely. If the timeout period is given, and the semaphore has not cleared within that period, BE will return with an error level of 1. If the semaphore is already clear, or is cleared while BE is waiting for it, BE will return with an error level of 0. See Appendix B for a complete discussion on the use of SEMMGR and semaphores.

Unless it is the last command, this command should not be used in a response file. This BE sub command will return an error level to the OS/2 command interpreter. Any processing of a BE response file will cease with the use of this command.

Examples

BE SEMWAIT test
This example waits for the semaphore \SEM\SEMMGR\TEST to clear. BE will wait indefinitely for the semaphore to clear. It will return immediately if the semaphore is already clear. The error level returned is 0.
BE SEMWAIT test\test 10000
This example waits for the semaphore \SEM\SEMMGR\TEST\TEST to clear. If the semaphore has not cleared within the specified time (10 seconds), an error level of 1 will be returned. Otherwise the semaphore has cleared and an error level of 0 will be returned.

BE WEEKDAY

Summary

BE WEEKDAY returns the current day of the week as an error level.

Command Line Format

Usage: BE WEEKDAY

Description

BE WEEKDAY will return the current day of the week as an error level to enable batch programs to carry out actions on a specified day. This BE sub command will return an error level to the OS/2 command interpreter. Any processing of a BE response file will cease with this command. Sunday will return an error level of 1, Monday an error level of 2 and so on.

Example

BE WEEKDAY
The current day of the week will be returned as an error level. The returned values are in the range of 1 to 7.

BE WINDOW

Summary

BE WINDOW allows you to display a window on the text screen.

Command Line Format

Usage: BE WINDOW top left bottom right <colour spec>
[EXPLODE] [SHADOW] STYLE=n
Parameters
top
Specifies the row position of the top left hand corner of the box.
left
Specifies the column position of the top left hand corner of the box.
bottom
Specifies the row position of the bottom right hand corner of the box.
right
Specifies the column position of the bottom right hand corner of the box.
colour spec
Specifies a colour specification. See BE SA for further details. This is an optional parameter.
[EXPLODE]
Explodes the window. That is, the window is drawn in a number of stages. This is an optional parameter.
This parameter is implemented in syntax only. It does not actually do anything.
[SHADOW]
Places a shadow under the window. This is an optional parameter.
This parameter is implemented in syntax only. It does not actually do anything.
STYLE=n
This allows you to specify the style of the box which is drawn. Valid values for n are:
0 No border is drawn.
1 A single line border is drawn.
2 A double line border is drawn.
The default value is 2.

The row and column coordinates range from one up to the maximum row and column coordinates as specified by the MODE command. These values have a default value dependent on your video adaptor.

Description

BE WINDOW allows you to display a window on the screen. Unlike the BE BOX command, window fills in the body of the window with spaces, BE BOX does not. The type of box characters drawn can be specified by the STYLE parameter. A SA colour specification may also be added to set the colours of the drawn box.

Examples

BE WINDOW 1 1 25 80
In standard VGA screen mode (80 columns by 25 rows), the above command will display a window which will outline the entire screen in the current screen colours.
BE WINDOW 10 10 15 70 Bright Green on Black
This will display a bright green window in the middle of the screen.

BE YEAR

Summary

BE YEAR returns the current year as an error level.

Command Line Format

Usage: BE YEAR

Description

BE YEAR will return the current year as an error level to enable batch programs to carry out actions in a specified year. This BE sub command will return an error level to the OS/2 command interpreter. Any processing of a BE response file will cease with this command. The year 1995 will return an error level of 95 and so on.

Example

BE YEAR
The current year will be returned as an error level. The year 2000 will return a value of 100, the year 1994 an error level of 94 and so on.